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 const char *cmd_name, parmpy_object *self,
469 const char *set_doc, const char *show_doc,
470 const char *help_doc,
471 struct cmd_list_element **set_list,
472 struct cmd_list_element **show_list)
474 struct cmd_list_element *param = NULL;
475 const char *tmp_name = NULL;
481 add_setshow_boolean_cmd (cmd_name, cmdclass,
482 &self->value.intval, set_doc, show_doc,
483 help_doc, get_set_value, get_show_value,
484 set_list, show_list);
488 case var_auto_boolean:
489 add_setshow_auto_boolean_cmd (cmd_name, cmdclass,
490 &self->value.autoboolval,
491 set_doc, show_doc, help_doc,
492 get_set_value, get_show_value,
493 set_list, show_list);
497 add_setshow_uinteger_cmd (cmd_name, cmdclass,
498 &self->value.uintval, set_doc, show_doc,
499 help_doc, get_set_value, get_show_value,
500 set_list, show_list);
504 add_setshow_integer_cmd (cmd_name, cmdclass,
505 &self->value.intval, set_doc, show_doc,
506 help_doc, get_set_value, get_show_value,
507 set_list, show_list); break;
510 add_setshow_string_cmd (cmd_name, cmdclass,
511 &self->value.stringval, set_doc, show_doc,
512 help_doc, get_set_value, get_show_value,
513 set_list, show_list); break;
515 case var_string_noescape:
516 add_setshow_string_noescape_cmd (cmd_name, cmdclass,
517 &self->value.stringval,
518 set_doc, show_doc, help_doc,
519 get_set_value, get_show_value,
520 set_list, show_list);
524 case var_optional_filename:
525 add_setshow_optional_filename_cmd (cmd_name, cmdclass,
526 &self->value.stringval, set_doc,
527 show_doc, help_doc, get_set_value,
528 get_show_value, set_list,
533 add_setshow_filename_cmd (cmd_name, cmdclass,
534 &self->value.stringval, set_doc, show_doc,
535 help_doc, get_set_value, get_show_value,
536 set_list, show_list); break;
539 add_setshow_zinteger_cmd (cmd_name, cmdclass,
540 &self->value.intval, set_doc, show_doc,
541 help_doc, get_set_value, get_show_value,
542 set_list, show_list);
546 add_setshow_zuinteger_cmd (cmd_name, cmdclass,
547 &self->value.uintval, set_doc, show_doc,
548 help_doc, get_set_value, get_show_value,
549 set_list, show_list);
552 case var_zuinteger_unlimited:
553 add_setshow_zuinteger_unlimited_cmd (cmd_name, cmdclass,
554 &self->value.intval, set_doc,
555 show_doc, help_doc, get_set_value,
557 set_list, show_list);
561 add_setshow_enum_cmd (cmd_name, cmdclass, self->enumeration,
562 &self->value.cstringval, set_doc, show_doc,
563 help_doc, get_set_value, get_show_value,
564 set_list, show_list);
565 /* Initialize the value, just in case. */
566 self->value.cstringval = self->enumeration[0];
570 /* Lookup created parameter, and register Python object against the
571 parameter context. Perform this task against both lists. */
573 param = lookup_cmd (&tmp_name, *show_list, "", 0, 1);
575 set_cmd_context (param, self);
578 param = lookup_cmd (&tmp_name, *set_list, "", 0, 1);
580 set_cmd_context (param, self);
583 /* A helper which computes enum values. Returns 1 on success. Returns 0 on
584 error, with a python exception set. */
586 compute_enum_values (parmpy_object *self, PyObject *enum_values)
592 PyErr_SetString (PyExc_RuntimeError,
593 _("An enumeration is required for PARAM_ENUM."));
597 if (! PySequence_Check (enum_values))
599 PyErr_SetString (PyExc_RuntimeError,
600 _("The enumeration is not a sequence."));
604 size = PySequence_Size (enum_values);
609 PyErr_SetString (PyExc_RuntimeError,
610 _("The enumeration is empty."));
614 gdb_argv holder (XCNEWVEC (char *, size + 1));
615 char **enumeration = holder.get ();
617 for (i = 0; i < size; ++i)
619 gdbpy_ref<> item (PySequence_GetItem (enum_values, i));
623 if (! gdbpy_is_string (item.get ()))
625 PyErr_SetString (PyExc_RuntimeError,
626 _("The enumeration item not a string."));
629 enumeration[i] = python_string_to_host_string (item.get ()).release ();
630 if (enumeration[i] == NULL)
634 self->enumeration = const_cast<const char**> (holder.release ());
638 /* Object initializer; sets up gdb-side structures for command.
640 Use: __init__(NAME, CMDCLASS, PARMCLASS, [ENUM])
642 NAME is the name of the parameter. It may consist of multiple
643 words, in which case the final word is the name of the new command,
644 and earlier words must be prefix commands.
646 CMDCLASS is the kind of command. It should be one of the COMMAND_*
647 constants defined in the gdb module.
649 PARMCLASS is the type of the parameter. It should be one of the
650 PARAM_* constants defined in the gdb module.
652 If PARMCLASS is PARAM_ENUM, then the final argument should be a
653 collection of strings. These strings are the valid values for this
656 The documentation for the parameter is taken from the doc string
657 for the python class.
659 Returns -1 on error, with a python exception set. */
662 parmpy_init (PyObject *self, PyObject *args, PyObject *kwds)
664 parmpy_object *obj = (parmpy_object *) self;
666 gdb::unique_xmalloc_ptr<char> set_doc, show_doc, doc;
668 int parmclass, cmdtype;
669 PyObject *enum_values = NULL;
670 struct cmd_list_element **set_list, **show_list;
672 if (! PyArg_ParseTuple (args, "sii|O", &name, &cmdtype, &parmclass,
676 if (cmdtype != no_class && cmdtype != class_run
677 && cmdtype != class_vars && cmdtype != class_stack
678 && cmdtype != class_files && cmdtype != class_support
679 && cmdtype != class_info && cmdtype != class_breakpoint
680 && cmdtype != class_trace && cmdtype != class_obscure
681 && cmdtype != class_maintenance)
683 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
687 if (parmclass != var_boolean /* ARI: var_boolean */
688 && parmclass != var_auto_boolean
689 && parmclass != var_uinteger && parmclass != var_integer
690 && parmclass != var_string && parmclass != var_string_noescape
691 && parmclass != var_optional_filename && parmclass != var_filename
692 && parmclass != var_zinteger && parmclass != var_zuinteger
693 && parmclass != var_zuinteger_unlimited && parmclass != var_enum)
695 PyErr_SetString (PyExc_RuntimeError,
696 _("Invalid parameter class argument."));
700 if (enum_values && parmclass != var_enum)
702 PyErr_SetString (PyExc_RuntimeError,
703 _("Only PARAM_ENUM accepts a fourth argument."));
706 if (parmclass == var_enum)
708 if (! compute_enum_values (obj, enum_values))
712 obj->enumeration = NULL;
713 obj->type = (enum var_types) parmclass;
714 memset (&obj->value, 0, sizeof (obj->value));
716 cmd_name = gdbpy_parse_command_name (name, &set_list,
722 cmd_name = gdbpy_parse_command_name (name, &show_list,
727 set_doc = get_doc_string (self, set_doc_cst);
728 show_doc = get_doc_string (self, show_doc_cst);
729 doc = get_doc_string (self, gdbpy_doc_cst);
735 add_setshow_generic (parmclass, (enum command_class) cmdtype,
737 set_doc.get (), show_doc.get (),
738 doc.get (), set_list, show_list);
740 CATCH (except, RETURN_MASK_ALL)
744 PyErr_Format (except.reason == RETURN_QUIT
745 ? PyExc_KeyboardInterrupt : PyExc_RuntimeError,
746 "%s", except.message);
756 /* Initialize the 'parameters' module. */
758 gdbpy_initialize_parameters (void)
762 parmpy_object_type.tp_new = PyType_GenericNew;
763 if (PyType_Ready (&parmpy_object_type) < 0)
766 set_doc_cst = PyString_FromString ("set_doc");
769 show_doc_cst = PyString_FromString ("show_doc");
773 for (i = 0; parm_constants[i].name; ++i)
775 if (PyModule_AddIntConstant (gdb_module,
776 parm_constants[i].name,
777 parm_constants[i].value) < 0)
781 return gdb_pymodule_addobject (gdb_module, "Parameter",
782 (PyObject *) &parmpy_object_type);
787 PyTypeObject parmpy_object_type =
789 PyVarObject_HEAD_INIT (NULL, 0)
790 "gdb.Parameter", /*tp_name*/
791 sizeof (parmpy_object), /*tp_basicsize*/
800 0, /*tp_as_sequence*/
805 get_attr, /*tp_getattro*/
806 set_attr, /*tp_setattro*/
808 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
809 "GDB parameter object", /* tp_doc */
812 0, /* tp_richcompare */
813 0, /* tp_weaklistoffset */
821 0, /* tp_descr_get */
822 0, /* tp_descr_set */
823 0, /* tp_dictoffset */
824 parmpy_init, /* tp_init */