1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2018 Free Software Foundation, Inc.
5 This file is part of GDB.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 3 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>. */
23 #include "python-internal.h"
26 #include "cli/cli-decode.h"
27 #include "completer.h"
29 #include "arch-utils.h"
32 /* Parameter constants and their values. */
39 struct parm_constant parm_constants
[] =
41 { "PARAM_BOOLEAN", var_boolean
}, /* ARI: var_boolean */
42 { "PARAM_AUTO_BOOLEAN", var_auto_boolean
},
43 { "PARAM_UINTEGER", var_uinteger
},
44 { "PARAM_INTEGER", var_integer
},
45 { "PARAM_STRING", var_string
},
46 { "PARAM_STRING_NOESCAPE", var_string_noescape
},
47 { "PARAM_OPTIONAL_FILENAME", var_optional_filename
},
48 { "PARAM_FILENAME", var_filename
},
49 { "PARAM_ZINTEGER", var_zinteger
},
50 { "PARAM_ZUINTEGER", var_zuinteger
},
51 { "PARAM_ZUINTEGER_UNLIMITED", var_zuinteger_unlimited
},
52 { "PARAM_ENUM", var_enum
},
56 /* A union that can hold anything described by enum var_types. */
59 /* Hold an integer value, for boolean and integer types. */
62 /* Hold an auto_boolean. */
63 enum auto_boolean autoboolval
;
65 /* Hold an unsigned integer value, for uinteger. */
68 /* Hold a string, for the various string types. */
71 /* Hold a string, for enums. */
72 const char *cstringval
;
75 /* A GDB parameter. */
80 /* The type of the parameter. */
83 /* The value of the parameter. */
84 union parmpy_variable value
;
86 /* For an enum command, the possible values. The vector is
87 allocated with xmalloc, as is each element. It is
89 const char **enumeration
;
92 typedef struct parmpy_object parmpy_object
;
94 extern PyTypeObject parmpy_object_type
95 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("parmpy_object");
97 /* Some handy string constants. */
98 static PyObject
*set_doc_cst
;
99 static PyObject
*show_doc_cst
;
103 /* Get an attribute. */
105 get_attr (PyObject
*obj
, PyObject
*attr_name
)
107 if (PyString_Check (attr_name
)
109 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
111 && ! strcmp (PyString_AsString (attr_name
), "value"))
114 parmpy_object
*self
= (parmpy_object
*) obj
;
116 return gdbpy_parameter_value (self
->type
, &self
->value
);
119 return PyObject_GenericGetAttr (obj
, attr_name
);
122 /* Set a parameter value from a Python value. Return 0 on success. Returns
123 -1 on error, with a python exception set. */
125 set_parameter_value (parmpy_object
*self
, PyObject
*value
)
132 case var_string_noescape
:
133 case var_optional_filename
:
135 if (! gdbpy_is_string (value
)
136 && (self
->type
== var_filename
137 || value
!= Py_None
))
139 PyErr_SetString (PyExc_RuntimeError
,
140 _("String required for filename."));
144 if (value
== Py_None
)
146 xfree (self
->value
.stringval
);
147 if (self
->type
== var_optional_filename
)
148 self
->value
.stringval
= xstrdup ("");
150 self
->value
.stringval
= NULL
;
154 gdb::unique_xmalloc_ptr
<char>
155 string (python_string_to_host_string (value
));
159 xfree (self
->value
.stringval
);
160 self
->value
.stringval
= string
.release ();
168 if (! gdbpy_is_string (value
))
170 PyErr_SetString (PyExc_RuntimeError
,
171 _("ENUM arguments must be a string."));
175 gdb::unique_xmalloc_ptr
<char>
176 str (python_string_to_host_string (value
));
179 for (i
= 0; self
->enumeration
[i
]; ++i
)
180 if (! strcmp (self
->enumeration
[i
], str
.get ()))
182 if (! self
->enumeration
[i
])
184 PyErr_SetString (PyExc_RuntimeError
,
185 _("The value must be member of an enumeration."));
188 self
->value
.cstringval
= self
->enumeration
[i
];
193 if (! PyBool_Check (value
))
195 PyErr_SetString (PyExc_RuntimeError
,
196 _("A boolean argument is required."));
199 cmp
= PyObject_IsTrue (value
);
202 self
->value
.intval
= cmp
;
205 case var_auto_boolean
:
206 if (! PyBool_Check (value
) && value
!= Py_None
)
208 PyErr_SetString (PyExc_RuntimeError
,
209 _("A boolean or None is required"));
213 if (value
== Py_None
)
214 self
->value
.autoboolval
= AUTO_BOOLEAN_AUTO
;
217 cmp
= PyObject_IsTrue (value
);
221 self
->value
.autoboolval
= AUTO_BOOLEAN_TRUE
;
223 self
->value
.autoboolval
= AUTO_BOOLEAN_FALSE
;
231 case var_zuinteger_unlimited
:
236 if (! PyInt_Check (value
))
238 PyErr_SetString (PyExc_RuntimeError
,
239 _("The value must be integer."));
243 if (! gdb_py_int_as_long (value
, &l
))
253 ok
= (l
>= 0 && l
<= UINT_MAX
);
256 case var_zuinteger_unlimited
:
257 ok
= (l
>= -1 && l
<= INT_MAX
);
261 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
267 ok
= (l
>= INT_MIN
&& l
<= INT_MAX
);
271 gdb_assert_not_reached ("unknown var_ constant");
276 PyErr_SetString (PyExc_RuntimeError
,
277 _("Range exceeded."));
281 if (self
->type
== var_uinteger
|| self
->type
== var_zuinteger
)
282 self
->value
.uintval
= (unsigned) l
;
284 self
->value
.intval
= (int) l
;
289 PyErr_SetString (PyExc_RuntimeError
,
290 _("Unhandled type in parameter value."));
297 /* Set an attribute. Returns -1 on error, with a python exception set. */
299 set_attr (PyObject
*obj
, PyObject
*attr_name
, PyObject
*val
)
301 if (PyString_Check (attr_name
)
303 && ! PyUnicode_CompareWithASCIIString (attr_name
, "value"))
305 && ! strcmp (PyString_AsString (attr_name
), "value"))
310 PyErr_SetString (PyExc_RuntimeError
,
311 _("Cannot delete a parameter's value."));
314 return set_parameter_value ((parmpy_object
*) obj
, val
);
317 return PyObject_GenericSetAttr (obj
, attr_name
, val
);
320 /* A helper function which returns a documentation string for an
323 static gdb::unique_xmalloc_ptr
<char>
324 get_doc_string (PyObject
*object
, PyObject
*attr
)
326 gdb::unique_xmalloc_ptr
<char> result
;
328 if (PyObject_HasAttr (object
, attr
))
330 gdbpy_ref
<> ds_obj (PyObject_GetAttr (object
, attr
));
332 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
334 result
= python_string_to_host_string (ds_obj
.get ());
336 gdbpy_print_stack ();
340 result
.reset (xstrdup (_("This command is not documented.")));
344 /* Helper function which will execute a METHOD in OBJ passing the
345 argument ARG. ARG can be NULL. METHOD should return a Python
346 string. If this function returns NULL, there has been an error and
347 the appropriate exception set. */
348 static gdb::unique_xmalloc_ptr
<char>
349 call_doc_function (PyObject
*obj
, PyObject
*method
, PyObject
*arg
)
351 gdb::unique_xmalloc_ptr
<char> data
;
352 gdbpy_ref
<> result (PyObject_CallMethodObjArgs (obj
, method
, arg
, NULL
));
357 if (gdbpy_is_string (result
.get ()))
359 data
= python_string_to_host_string (result
.get ());
365 PyErr_SetString (PyExc_RuntimeError
,
366 _("Parameter must return a string value."));
373 /* A callback function that is registered against the respective
374 add_setshow_* set_doc prototype. This function will either call
375 the Python function "get_set_string" or extract the Python
376 attribute "set_doc" and return the contents as a string. If
377 neither exist, insert a string indicating the Parameter is not
380 get_set_value (const char *args
, int from_tty
,
381 struct cmd_list_element
*c
)
383 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
384 gdb::unique_xmalloc_ptr
<char> set_doc_string
;
386 gdbpy_enter
enter_py (get_current_arch (), current_language
);
387 gdbpy_ref
<> set_doc_func (PyString_FromString ("get_set_string"));
389 if (set_doc_func
== NULL
)
391 gdbpy_print_stack ();
395 if (PyObject_HasAttr (obj
, set_doc_func
.get ()))
397 set_doc_string
= call_doc_function (obj
, set_doc_func
.get (), NULL
);
398 if (! set_doc_string
)
400 gdbpy_print_stack ();
405 const char *str
= set_doc_string
.get ();
406 if (str
!= nullptr && str
[0] != '\0')
407 fprintf_filtered (gdb_stdout
, "%s\n", str
);
410 /* A callback function that is registered against the respective
411 add_setshow_* show_doc prototype. This function will either call
412 the Python function "get_show_string" or extract the Python
413 attribute "show_doc" and return the contents as a string. If
414 neither exist, insert a string indicating the Parameter is not
417 get_show_value (struct ui_file
*file
, int from_tty
,
418 struct cmd_list_element
*c
,
421 PyObject
*obj
= (PyObject
*) get_cmd_context (c
);
422 gdb::unique_xmalloc_ptr
<char> show_doc_string
;
424 gdbpy_enter
enter_py (get_current_arch (), current_language
);
425 gdbpy_ref
<> show_doc_func (PyString_FromString ("get_show_string"));
427 if (show_doc_func
== NULL
)
429 gdbpy_print_stack ();
433 if (PyObject_HasAttr (obj
, show_doc_func
.get ()))
435 gdbpy_ref
<> val_obj (PyString_FromString (value
));
439 gdbpy_print_stack ();
443 show_doc_string
= call_doc_function (obj
, show_doc_func
.get (),
445 if (! show_doc_string
)
447 gdbpy_print_stack ();
451 fprintf_filtered (file
, "%s\n", show_doc_string
.get ());
455 /* We have to preserve the existing < GDB 7.3 API. If a
456 callback function does not exist, then attempt to read the
457 show_doc attribute. */
458 show_doc_string
= get_doc_string (obj
, show_doc_cst
);
459 fprintf_filtered (file
, "%s %s\n", show_doc_string
.get (), value
);
464 /* A helper function that dispatches to the appropriate add_setshow
467 add_setshow_generic (int parmclass
, enum command_class cmdclass
,
468 char *cmd_name
, parmpy_object
*self
,
469 char *set_doc
, char *show_doc
, char *help_doc
,
470 struct cmd_list_element
**set_list
,
471 struct cmd_list_element
**show_list
)
473 struct cmd_list_element
*param
= NULL
;
474 const char *tmp_name
= NULL
;
480 add_setshow_boolean_cmd (cmd_name
, cmdclass
,
481 &self
->value
.intval
, set_doc
, show_doc
,
482 help_doc
, get_set_value
, get_show_value
,
483 set_list
, show_list
);
487 case var_auto_boolean
:
488 add_setshow_auto_boolean_cmd (cmd_name
, cmdclass
,
489 &self
->value
.autoboolval
,
490 set_doc
, show_doc
, help_doc
,
491 get_set_value
, get_show_value
,
492 set_list
, show_list
);
496 add_setshow_uinteger_cmd (cmd_name
, cmdclass
,
497 &self
->value
.uintval
, set_doc
, show_doc
,
498 help_doc
, get_set_value
, get_show_value
,
499 set_list
, show_list
);
503 add_setshow_integer_cmd (cmd_name
, cmdclass
,
504 &self
->value
.intval
, set_doc
, show_doc
,
505 help_doc
, get_set_value
, get_show_value
,
506 set_list
, show_list
); break;
509 add_setshow_string_cmd (cmd_name
, cmdclass
,
510 &self
->value
.stringval
, set_doc
, show_doc
,
511 help_doc
, get_set_value
, get_show_value
,
512 set_list
, show_list
); break;
514 case var_string_noescape
:
515 add_setshow_string_noescape_cmd (cmd_name
, cmdclass
,
516 &self
->value
.stringval
,
517 set_doc
, show_doc
, help_doc
,
518 get_set_value
, get_show_value
,
519 set_list
, show_list
);
523 case var_optional_filename
:
524 add_setshow_optional_filename_cmd (cmd_name
, cmdclass
,
525 &self
->value
.stringval
, set_doc
,
526 show_doc
, help_doc
, get_set_value
,
527 get_show_value
, set_list
,
532 add_setshow_filename_cmd (cmd_name
, cmdclass
,
533 &self
->value
.stringval
, set_doc
, show_doc
,
534 help_doc
, get_set_value
, get_show_value
,
535 set_list
, show_list
); break;
538 add_setshow_zinteger_cmd (cmd_name
, cmdclass
,
539 &self
->value
.intval
, set_doc
, show_doc
,
540 help_doc
, get_set_value
, get_show_value
,
541 set_list
, show_list
);
545 add_setshow_zuinteger_cmd (cmd_name
, cmdclass
,
546 &self
->value
.uintval
, set_doc
, show_doc
,
547 help_doc
, get_set_value
, get_show_value
,
548 set_list
, show_list
);
551 case var_zuinteger_unlimited
:
552 add_setshow_zuinteger_unlimited_cmd (cmd_name
, cmdclass
,
553 &self
->value
.intval
, set_doc
,
554 show_doc
, help_doc
, get_set_value
,
556 set_list
, show_list
);
560 add_setshow_enum_cmd (cmd_name
, cmdclass
, self
->enumeration
,
561 &self
->value
.cstringval
, set_doc
, show_doc
,
562 help_doc
, get_set_value
, get_show_value
,
563 set_list
, show_list
);
564 /* Initialize the value, just in case. */
565 self
->value
.cstringval
= self
->enumeration
[0];
569 /* Lookup created parameter, and register Python object against the
570 parameter context. Perform this task against both lists. */
572 param
= lookup_cmd (&tmp_name
, *show_list
, "", 0, 1);
574 set_cmd_context (param
, self
);
577 param
= lookup_cmd (&tmp_name
, *set_list
, "", 0, 1);
579 set_cmd_context (param
, self
);
582 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
583 error, with a python exception set. */
585 compute_enum_values (parmpy_object
*self
, PyObject
*enum_values
)
591 PyErr_SetString (PyExc_RuntimeError
,
592 _("An enumeration is required for PARAM_ENUM."));
596 if (! PySequence_Check (enum_values
))
598 PyErr_SetString (PyExc_RuntimeError
,
599 _("The enumeration is not a sequence."));
603 size
= PySequence_Size (enum_values
);
608 PyErr_SetString (PyExc_RuntimeError
,
609 _("The enumeration is empty."));
613 gdb_argv
holder (XCNEWVEC (char *, size
+ 1));
614 char **enumeration
= holder
.get ();
616 for (i
= 0; i
< size
; ++i
)
618 gdbpy_ref
<> item (PySequence_GetItem (enum_values
, i
));
622 if (! gdbpy_is_string (item
.get ()))
624 PyErr_SetString (PyExc_RuntimeError
,
625 _("The enumeration item not a string."));
628 enumeration
[i
] = python_string_to_host_string (item
.get ()).release ();
629 if (enumeration
[i
] == NULL
)
633 self
->enumeration
= const_cast<const char**> (holder
.release ());
637 /* Object initializer; sets up gdb-side structures for command.
639 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
641 NAME is the name of the parameter. It may consist of multiple
642 words, in which case the final word is the name of the new command,
643 and earlier words must be prefix commands.
645 CMDCLASS is the kind of command. It should be one of the COMMAND_*
646 constants defined in the gdb module.
648 PARMCLASS is the type of the parameter. It should be one of the
649 PARAM_* constants defined in the gdb module.
651 If PARMCLASS is PARAM_ENUM, then the final argument should be a
652 collection of strings. These strings are the valid values for this
655 The documentation for the parameter is taken from the doc string
656 for the python class.
658 Returns -1 on error, with a python exception set. */
661 parmpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kwds
)
663 parmpy_object
*obj
= (parmpy_object
*) self
;
665 char *set_doc
, *show_doc
, *doc
;
667 int parmclass
, cmdtype
;
668 PyObject
*enum_values
= NULL
;
669 struct cmd_list_element
**set_list
, **show_list
;
671 if (! PyArg_ParseTuple (args
, "sii|O", &name
, &cmdtype
, &parmclass
,
675 if (cmdtype
!= no_class
&& cmdtype
!= class_run
676 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
677 && cmdtype
!= class_files
&& cmdtype
!= class_support
678 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
679 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
680 && cmdtype
!= class_maintenance
)
682 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
686 if (parmclass
!= var_boolean
/* ARI: var_boolean */
687 && parmclass
!= var_auto_boolean
688 && parmclass
!= var_uinteger
&& parmclass
!= var_integer
689 && parmclass
!= var_string
&& parmclass
!= var_string_noescape
690 && parmclass
!= var_optional_filename
&& parmclass
!= var_filename
691 && parmclass
!= var_zinteger
&& parmclass
!= var_zuinteger
692 && parmclass
!= var_zuinteger_unlimited
&& parmclass
!= var_enum
)
694 PyErr_SetString (PyExc_RuntimeError
,
695 _("Invalid parameter class argument."));
699 if (enum_values
&& parmclass
!= var_enum
)
701 PyErr_SetString (PyExc_RuntimeError
,
702 _("Only PARAM_ENUM accepts a fourth argument."));
705 if (parmclass
== var_enum
)
707 if (! compute_enum_values (obj
, enum_values
))
711 obj
->enumeration
= NULL
;
712 obj
->type
= (enum var_types
) parmclass
;
713 memset (&obj
->value
, 0, sizeof (obj
->value
));
715 cmd_name
= gdbpy_parse_command_name (name
, &set_list
,
721 cmd_name
= gdbpy_parse_command_name (name
, &show_list
,
726 set_doc
= get_doc_string (self
, set_doc_cst
).release ();
727 show_doc
= get_doc_string (self
, show_doc_cst
).release ();
728 doc
= get_doc_string (self
, gdbpy_doc_cst
).release ();
734 add_setshow_generic (parmclass
, (enum command_class
) cmdtype
,
737 doc
, set_list
, show_list
);
739 CATCH (except
, RETURN_MASK_ALL
)
746 PyErr_Format (except
.reason
== RETURN_QUIT
747 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
748 "%s", except
.message
);
758 /* Initialize the 'parameters' module. */
760 gdbpy_initialize_parameters (void)
764 parmpy_object_type
.tp_new
= PyType_GenericNew
;
765 if (PyType_Ready (&parmpy_object_type
) < 0)
768 set_doc_cst
= PyString_FromString ("set_doc");
771 show_doc_cst
= PyString_FromString ("show_doc");
775 for (i
= 0; parm_constants
[i
].name
; ++i
)
777 if (PyModule_AddIntConstant (gdb_module
,
778 parm_constants
[i
].name
,
779 parm_constants
[i
].value
) < 0)
783 return gdb_pymodule_addobject (gdb_module
, "Parameter",
784 (PyObject
*) &parmpy_object_type
);
789 PyTypeObject parmpy_object_type
=
791 PyVarObject_HEAD_INIT (NULL
, 0)
792 "gdb.Parameter", /*tp_name*/
793 sizeof (parmpy_object
), /*tp_basicsize*/
802 0, /*tp_as_sequence*/
807 get_attr
, /*tp_getattro*/
808 set_attr
, /*tp_setattro*/
810 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
811 "GDB parameter object", /* tp_doc */
814 0, /* tp_richcompare */
815 0, /* tp_weaklistoffset */
823 0, /* tp_descr_get */
824 0, /* tp_descr_set */
825 0, /* tp_dictoffset */
826 parmpy_init
, /* tp_init */