1 /* GDB parameters implemented in Python
3 Copyright (C) 2008-2019 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"
31 /* Parameter constants and their values. */
38 struct parm_constant parm_constants[] =
40 { "PARAM_BOOLEAN", var_boolean }, /* ARI: var_boolean */
41 { "PARAM_AUTO_BOOLEAN", var_auto_boolean },
42 { "PARAM_UINTEGER", var_uinteger },
43 { "PARAM_INTEGER", var_integer },
44 { "PARAM_STRING", var_string },
45 { "PARAM_STRING_NOESCAPE", var_string_noescape },
46 { "PARAM_OPTIONAL_FILENAME", var_optional_filename },
47 { "PARAM_FILENAME", var_filename },
48 { "PARAM_ZINTEGER", var_zinteger },
49 { "PARAM_ZUINTEGER", var_zuinteger },
50 { "PARAM_ZUINTEGER_UNLIMITED", var_zuinteger_unlimited },
51 { "PARAM_ENUM", var_enum },
55 /* A union that can hold anything described by enum var_types. */
58 /* Hold an integer value, for boolean and integer types. */
61 /* Hold an auto_boolean. */
62 enum auto_boolean autoboolval;
64 /* Hold an unsigned integer value, for uinteger. */
67 /* Hold a string, for the various string types. */
70 /* Hold a string, for enums. */
71 const char *cstringval;
74 /* A GDB parameter. */
79 /* The type of the parameter. */
82 /* The value of the parameter. */
83 union parmpy_variable value;
85 /* For an enum command, the possible values. The vector is
86 allocated with xmalloc, as is each element. It is
88 const char **enumeration;
91 typedef struct parmpy_object parmpy_object;
93 extern PyTypeObject parmpy_object_type
94 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("parmpy_object");
96 /* Some handy string constants. */
97 static PyObject *set_doc_cst;
98 static PyObject *show_doc_cst;
102 /* Get an attribute. */
104 get_attr (PyObject *obj, PyObject *attr_name)
106 if (PyString_Check (attr_name)
108 && ! PyUnicode_CompareWithASCIIString (attr_name, "value"))
110 && ! strcmp (PyString_AsString (attr_name), "value"))
113 parmpy_object *self = (parmpy_object *) obj;
115 return gdbpy_parameter_value (self->type, &self->value);
118 return PyObject_GenericGetAttr (obj, attr_name);
121 /* Set a parameter value from a Python value. Return 0 on success. Returns
122 -1 on error, with a python exception set. */
124 set_parameter_value (parmpy_object *self, PyObject *value)
131 case var_string_noescape:
132 case var_optional_filename:
134 if (! gdbpy_is_string (value)
135 && (self->type == var_filename
136 || value != Py_None))
138 PyErr_SetString (PyExc_RuntimeError,
139 _("String required for filename."));
143 if (value == Py_None)
145 xfree (self->value.stringval);
146 if (self->type == var_optional_filename)
147 self->value.stringval = xstrdup ("");
149 self->value.stringval = NULL;
153 gdb::unique_xmalloc_ptr<char>
154 string (python_string_to_host_string (value));
158 xfree (self->value.stringval);
159 self->value.stringval = string.release ();
167 if (! gdbpy_is_string (value))
169 PyErr_SetString (PyExc_RuntimeError,
170 _("ENUM arguments must be a string."));
174 gdb::unique_xmalloc_ptr<char>
175 str (python_string_to_host_string (value));
178 for (i = 0; self->enumeration[i]; ++i)
179 if (! strcmp (self->enumeration[i], str.get ()))
181 if (! self->enumeration[i])
183 PyErr_SetString (PyExc_RuntimeError,
184 _("The value must be member of an enumeration."));
187 self->value.cstringval = self->enumeration[i];
192 if (! PyBool_Check (value))
194 PyErr_SetString (PyExc_RuntimeError,
195 _("A boolean argument is required."));
198 cmp = PyObject_IsTrue (value);
201 self->value.intval = cmp;
204 case var_auto_boolean:
205 if (! PyBool_Check (value) && value != Py_None)
207 PyErr_SetString (PyExc_RuntimeError,
208 _("A boolean or None is required"));
212 if (value == Py_None)
213 self->value.autoboolval = AUTO_BOOLEAN_AUTO;
216 cmp = PyObject_IsTrue (value);
220 self->value.autoboolval = AUTO_BOOLEAN_TRUE;
222 self->value.autoboolval = AUTO_BOOLEAN_FALSE;
230 case var_zuinteger_unlimited:
235 if (! PyInt_Check (value))
237 PyErr_SetString (PyExc_RuntimeError,
238 _("The value must be integer."));
242 if (! gdb_py_int_as_long (value, &l))
252 ok = (l >= 0 && l <= UINT_MAX);
255 case var_zuinteger_unlimited:
256 ok = (l >= -1 && l <= INT_MAX);
260 ok = (l >= INT_MIN && l <= INT_MAX);
266 ok = (l >= INT_MIN && l <= INT_MAX);
270 gdb_assert_not_reached ("unknown var_ constant");
275 PyErr_SetString (PyExc_RuntimeError,
276 _("Range exceeded."));
280 if (self->type == var_uinteger || self->type == var_zuinteger)
281 self->value.uintval = (unsigned) l;
283 self->value.intval = (int) l;
288 PyErr_SetString (PyExc_RuntimeError,
289 _("Unhandled type in parameter value."));
296 /* Set an attribute. Returns -1 on error, with a python exception set. */
298 set_attr (PyObject *obj, PyObject *attr_name, PyObject *val)
300 if (PyString_Check (attr_name)
302 && ! PyUnicode_CompareWithASCIIString (attr_name, "value"))
304 && ! strcmp (PyString_AsString (attr_name), "value"))
309 PyErr_SetString (PyExc_RuntimeError,
310 _("Cannot delete a parameter's value."));
313 return set_parameter_value ((parmpy_object *) obj, val);
316 return PyObject_GenericSetAttr (obj, attr_name, val);
319 /* A helper function which returns a documentation string for an
322 static gdb::unique_xmalloc_ptr<char>
323 get_doc_string (PyObject *object, PyObject *attr)
325 gdb::unique_xmalloc_ptr<char> result;
327 if (PyObject_HasAttr (object, attr))
329 gdbpy_ref<> ds_obj (PyObject_GetAttr (object, attr));
331 if (ds_obj != NULL && gdbpy_is_string (ds_obj.get ()))
333 result = python_string_to_host_string (ds_obj.get ());
335 gdbpy_print_stack ();
339 result.reset (xstrdup (_("This command is not documented.")));
343 /* Helper function which will execute a METHOD in OBJ passing the
344 argument ARG. ARG can be NULL. METHOD should return a Python
345 string. If this function returns NULL, there has been an error and
346 the appropriate exception set. */
347 static gdb::unique_xmalloc_ptr<char>
348 call_doc_function (PyObject *obj, PyObject *method, PyObject *arg)
350 gdb::unique_xmalloc_ptr<char> data;
351 gdbpy_ref<> result (PyObject_CallMethodObjArgs (obj, method, arg, NULL));
356 if (gdbpy_is_string (result.get ()))
358 data = python_string_to_host_string (result.get ());
364 PyErr_SetString (PyExc_RuntimeError,
365 _("Parameter must return a string value."));
372 /* A callback function that is registered against the respective
373 add_setshow_* set_doc prototype. This function will either call
374 the Python function "get_set_string" or extract the Python
375 attribute "set_doc" and return the contents as a string. If
376 neither exist, insert a string indicating the Parameter is not
379 get_set_value (const char *args, int from_tty,
380 struct cmd_list_element *c)
382 PyObject *obj = (PyObject *) get_cmd_context (c);
383 gdb::unique_xmalloc_ptr<char> set_doc_string;
385 gdbpy_enter enter_py (get_current_arch (), current_language);
386 gdbpy_ref<> set_doc_func (PyString_FromString ("get_set_string"));
388 if (set_doc_func == NULL)
390 gdbpy_print_stack ();
394 if (PyObject_HasAttr (obj, set_doc_func.get ()))
396 set_doc_string = call_doc_function (obj, set_doc_func.get (), NULL);
397 if (! set_doc_string)
398 gdbpy_handle_exception ();
401 const char *str = set_doc_string.get ();
402 if (str != nullptr && str[0] != '\0')
403 fprintf_filtered (gdb_stdout, "%s\n", str);
406 /* A callback function that is registered against the respective
407 add_setshow_* show_doc prototype. This function will either call
408 the Python function "get_show_string" or extract the Python
409 attribute "show_doc" and return the contents as a string. If
410 neither exist, insert a string indicating the Parameter is not
413 get_show_value (struct ui_file *file, int from_tty,
414 struct cmd_list_element *c,
417 PyObject *obj = (PyObject *) get_cmd_context (c);
418 gdb::unique_xmalloc_ptr<char> show_doc_string;
420 gdbpy_enter enter_py (get_current_arch (), current_language);
421 gdbpy_ref<> show_doc_func (PyString_FromString ("get_show_string"));
423 if (show_doc_func == NULL)
425 gdbpy_print_stack ();
429 if (PyObject_HasAttr (obj, show_doc_func.get ()))
431 gdbpy_ref<> val_obj (PyString_FromString (value));
435 gdbpy_print_stack ();
439 show_doc_string = call_doc_function (obj, show_doc_func.get (),
441 if (! show_doc_string)
443 gdbpy_print_stack ();
447 fprintf_filtered (file, "%s\n", show_doc_string.get ());
451 /* We have to preserve the existing < GDB 7.3 API. If a
452 callback function does not exist, then attempt to read the
453 show_doc attribute. */
454 show_doc_string = get_doc_string (obj, show_doc_cst);
455 fprintf_filtered (file, "%s %s\n", show_doc_string.get (), value);
460 /* A helper function that dispatches to the appropriate add_setshow
463 add_setshow_generic (int parmclass, enum command_class cmdclass,
464 const char *cmd_name, parmpy_object *self,
465 const char *set_doc, const char *show_doc,
466 const char *help_doc,
467 struct cmd_list_element **set_list,
468 struct cmd_list_element **show_list)
470 struct cmd_list_element *param = NULL;
471 const char *tmp_name = NULL;
477 add_setshow_boolean_cmd (cmd_name, cmdclass,
478 &self->value.intval, set_doc, show_doc,
479 help_doc, get_set_value, get_show_value,
480 set_list, show_list);
484 case var_auto_boolean:
485 add_setshow_auto_boolean_cmd (cmd_name, cmdclass,
486 &self->value.autoboolval,
487 set_doc, show_doc, help_doc,
488 get_set_value, get_show_value,
489 set_list, show_list);
493 add_setshow_uinteger_cmd (cmd_name, cmdclass,
494 &self->value.uintval, set_doc, show_doc,
495 help_doc, get_set_value, get_show_value,
496 set_list, show_list);
500 add_setshow_integer_cmd (cmd_name, cmdclass,
501 &self->value.intval, set_doc, show_doc,
502 help_doc, get_set_value, get_show_value,
503 set_list, show_list); break;
506 add_setshow_string_cmd (cmd_name, cmdclass,
507 &self->value.stringval, set_doc, show_doc,
508 help_doc, get_set_value, get_show_value,
509 set_list, show_list); break;
511 case var_string_noescape:
512 add_setshow_string_noescape_cmd (cmd_name, cmdclass,
513 &self->value.stringval,
514 set_doc, show_doc, help_doc,
515 get_set_value, get_show_value,
516 set_list, show_list);
520 case var_optional_filename:
521 add_setshow_optional_filename_cmd (cmd_name, cmdclass,
522 &self->value.stringval, set_doc,
523 show_doc, help_doc, get_set_value,
524 get_show_value, set_list,
529 add_setshow_filename_cmd (cmd_name, cmdclass,
530 &self->value.stringval, set_doc, show_doc,
531 help_doc, get_set_value, get_show_value,
532 set_list, show_list); break;
535 add_setshow_zinteger_cmd (cmd_name, cmdclass,
536 &self->value.intval, set_doc, show_doc,
537 help_doc, get_set_value, get_show_value,
538 set_list, show_list);
542 add_setshow_zuinteger_cmd (cmd_name, cmdclass,
543 &self->value.uintval, set_doc, show_doc,
544 help_doc, get_set_value, get_show_value,
545 set_list, show_list);
548 case var_zuinteger_unlimited:
549 add_setshow_zuinteger_unlimited_cmd (cmd_name, cmdclass,
550 &self->value.intval, set_doc,
551 show_doc, help_doc, get_set_value,
553 set_list, show_list);
557 add_setshow_enum_cmd (cmd_name, cmdclass, self->enumeration,
558 &self->value.cstringval, set_doc, show_doc,
559 help_doc, get_set_value, get_show_value,
560 set_list, show_list);
561 /* Initialize the value, just in case. */
562 self->value.cstringval = self->enumeration[0];
566 /* Lookup created parameter, and register Python object against the
567 parameter context. Perform this task against both lists. */
569 param = lookup_cmd (&tmp_name, *show_list, "", 0, 1);
571 set_cmd_context (param, self);
574 param = lookup_cmd (&tmp_name, *set_list, "", 0, 1);
576 set_cmd_context (param, self);
579 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
580 error, with a python exception set. */
582 compute_enum_values (parmpy_object *self, PyObject *enum_values)
588 PyErr_SetString (PyExc_RuntimeError,
589 _("An enumeration is required for PARAM_ENUM."));
593 if (! PySequence_Check (enum_values))
595 PyErr_SetString (PyExc_RuntimeError,
596 _("The enumeration is not a sequence."));
600 size = PySequence_Size (enum_values);
605 PyErr_SetString (PyExc_RuntimeError,
606 _("The enumeration is empty."));
610 gdb_argv holder (XCNEWVEC (char *, size + 1));
611 char **enumeration = holder.get ();
613 for (i = 0; i < size; ++i)
615 gdbpy_ref<> item (PySequence_GetItem (enum_values, i));
619 if (! gdbpy_is_string (item.get ()))
621 PyErr_SetString (PyExc_RuntimeError,
622 _("The enumeration item not a string."));
625 enumeration[i] = python_string_to_host_string (item.get ()).release ();
626 if (enumeration[i] == NULL)
630 self->enumeration = const_cast<const char**> (holder.release ());
634 /* Object initializer; sets up gdb-side structures for command.
636 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
638 NAME is the name of the parameter. It may consist of multiple
639 words, in which case the final word is the name of the new command,
640 and earlier words must be prefix commands.
642 CMDCLASS is the kind of command. It should be one of the COMMAND_*
643 constants defined in the gdb module.
645 PARMCLASS is the type of the parameter. It should be one of the
646 PARAM_* constants defined in the gdb module.
648 If PARMCLASS is PARAM_ENUM, then the final argument should be a
649 collection of strings. These strings are the valid values for this
652 The documentation for the parameter is taken from the doc string
653 for the python class.
655 Returns -1 on error, with a python exception set. */
658 parmpy_init (PyObject *self, PyObject *args, PyObject *kwds)
660 parmpy_object *obj = (parmpy_object *) self;
662 gdb::unique_xmalloc_ptr<char> set_doc, show_doc, doc;
664 int parmclass, cmdtype;
665 PyObject *enum_values = NULL;
666 struct cmd_list_element **set_list, **show_list;
668 if (! PyArg_ParseTuple (args, "sii|O", &name, &cmdtype, &parmclass,
672 if (cmdtype != no_class && cmdtype != class_run
673 && cmdtype != class_vars && cmdtype != class_stack
674 && cmdtype != class_files && cmdtype != class_support
675 && cmdtype != class_info && cmdtype != class_breakpoint
676 && cmdtype != class_trace && cmdtype != class_obscure
677 && cmdtype != class_maintenance)
679 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
683 if (parmclass != var_boolean /* ARI: var_boolean */
684 && parmclass != var_auto_boolean
685 && parmclass != var_uinteger && parmclass != var_integer
686 && parmclass != var_string && parmclass != var_string_noescape
687 && parmclass != var_optional_filename && parmclass != var_filename
688 && parmclass != var_zinteger && parmclass != var_zuinteger
689 && parmclass != var_zuinteger_unlimited && parmclass != var_enum)
691 PyErr_SetString (PyExc_RuntimeError,
692 _("Invalid parameter class argument."));
696 if (enum_values && parmclass != var_enum)
698 PyErr_SetString (PyExc_RuntimeError,
699 _("Only PARAM_ENUM accepts a fourth argument."));
702 if (parmclass == var_enum)
704 if (! compute_enum_values (obj, enum_values))
708 obj->enumeration = NULL;
709 obj->type = (enum var_types) parmclass;
710 memset (&obj->value, 0, sizeof (obj->value));
712 cmd_name = gdbpy_parse_command_name (name, &set_list,
718 cmd_name = gdbpy_parse_command_name (name, &show_list,
723 set_doc = get_doc_string (self, set_doc_cst);
724 show_doc = get_doc_string (self, show_doc_cst);
725 doc = get_doc_string (self, gdbpy_doc_cst);
731 add_setshow_generic (parmclass, (enum command_class) cmdtype,
733 set_doc.get (), show_doc.get (),
734 doc.get (), set_list, show_list);
736 CATCH (except, RETURN_MASK_ALL)
740 gdbpy_convert_exception (except);
750 /* Initialize the 'parameters' module. */
752 gdbpy_initialize_parameters (void)
756 parmpy_object_type.tp_new = PyType_GenericNew;
757 if (PyType_Ready (&parmpy_object_type) < 0)
760 set_doc_cst = PyString_FromString ("set_doc");
763 show_doc_cst = PyString_FromString ("show_doc");
767 for (i = 0; parm_constants[i].name; ++i)
769 if (PyModule_AddIntConstant (gdb_module,
770 parm_constants[i].name,
771 parm_constants[i].value) < 0)
775 return gdb_pymodule_addobject (gdb_module, "Parameter",
776 (PyObject *) &parmpy_object_type);
781 PyTypeObject parmpy_object_type =
783 PyVarObject_HEAD_INIT (NULL, 0)
784 "gdb.Parameter", /*tp_name*/
785 sizeof (parmpy_object), /*tp_basicsize*/
794 0, /*tp_as_sequence*/
799 get_attr, /*tp_getattro*/
800 set_attr, /*tp_setattro*/
802 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
803 "GDB parameter object", /* tp_doc */
806 0, /* tp_richcompare */
807 0, /* tp_weaklistoffset */
815 0, /* tp_descr_get */
816 0, /* tp_descr_set */
817 0, /* tp_dictoffset */
818 parmpy_init, /* tp_init */