1 /* gdb commands 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/>. */
22 #include "arch-utils.h"
24 #include "python-internal.h"
27 #include "cli/cli-decode.h"
28 #include "completer.h"
32 /* Struct representing built-in completion types. */
33 struct cmdpy_completer
35 /* Python symbol name. */
37 /* Completion function. */
38 completer_ftype *completer;
41 static const struct cmdpy_completer completers[] =
43 { "COMPLETE_NONE", noop_completer },
44 { "COMPLETE_FILENAME", filename_completer },
45 { "COMPLETE_LOCATION", location_completer },
46 { "COMPLETE_COMMAND", command_completer },
47 { "COMPLETE_SYMBOL", symbol_completer },
48 { "COMPLETE_EXPRESSION", expression_completer },
51 #define N_COMPLETERS (sizeof (completers) / sizeof (completers[0]))
53 /* A gdb command. For the time being only ordinary commands (not
54 set/show commands) are allowed. */
59 /* The corresponding gdb command object, or NULL if the command is
60 no longer installed. */
61 struct cmd_list_element *command;
63 /* A prefix command requires storage for a list of its sub-commands.
64 A pointer to this is passed to add_prefix_command, and to add_cmd
65 for sub-commands of that prefix. If this Command is not a prefix
66 command, then this field is unused. */
67 struct cmd_list_element *sub_list;
70 typedef struct cmdpy_object cmdpy_object;
72 extern PyTypeObject cmdpy_object_type
73 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("cmdpy_object");
75 /* Constants used by this module. */
76 static PyObject *invoke_cst;
77 static PyObject *complete_cst;
81 /* Python function which wraps dont_repeat. */
83 cmdpy_dont_repeat (PyObject *self, PyObject *args)
91 /* Called if the gdb cmd_list_element is destroyed. */
94 cmdpy_destroyer (struct cmd_list_element *self, void *context)
96 gdbpy_enter enter_py (get_current_arch (), current_language);
98 /* Release our hold on the command object. */
99 gdbpy_ref<cmdpy_object> cmd ((cmdpy_object *) context);
102 /* We allocated the name, doc string, and perhaps the prefix
104 xfree ((char *) self->name);
105 xfree ((char *) self->doc);
106 xfree ((char *) self->prefixname);
109 /* Called by gdb to invoke the command. */
112 cmdpy_function (struct cmd_list_element *command,
113 const char *args, int from_tty)
115 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command);
117 gdbpy_enter enter_py (get_current_arch (), current_language);
120 error (_("Invalid invocation of Python command object."));
121 if (! PyObject_HasAttr ((PyObject *) obj, invoke_cst))
123 if (obj->command->prefixname)
125 /* A prefix command does not need an invoke method. */
128 error (_("Python command object missing 'invoke' method."));
133 gdbpy_ref<> argobj (PyUnicode_Decode (args, strlen (args), host_charset (),
137 gdbpy_print_stack ();
138 error (_("Could not convert arguments to Python string."));
142 = gdbpy_ref<>::new_reference (from_tty ? Py_True : Py_False);
143 gdbpy_ref<> result (PyObject_CallMethodObjArgs ((PyObject *) obj, invoke_cst,
144 argobj.get (), ttyobj.get (),
149 PyObject *ptype, *pvalue, *ptraceback;
151 PyErr_Fetch (&ptype, &pvalue, &ptraceback);
153 /* Try to fetch an error message contained within ptype, pvalue.
154 When fetching the error message we need to make our own copy,
155 we no longer own ptype, pvalue after the call to PyErr_Restore. */
157 gdb::unique_xmalloc_ptr<char>
158 msg (gdbpy_exception_to_string (ptype, pvalue));
162 /* An error occurred computing the string representation of the
163 error message. This is rare, but we should inform the user. */
164 printf_filtered (_("An error occurred in a Python command\n"
165 "and then another occurred computing the "
166 "error message.\n"));
167 gdbpy_print_stack ();
170 /* Don't print the stack for gdb.GdbError exceptions.
171 It is generally used to flag user errors.
173 We also don't want to print "Error occurred in Python command"
174 for user errors. However, a missing message for gdb.GdbError
175 exceptions is arguably a bug, so we flag it as such. */
177 if (! PyErr_GivenExceptionMatches (ptype, gdbpy_gdberror_exc)
178 || msg == NULL || *msg == '\0')
180 PyErr_Restore (ptype, pvalue, ptraceback);
181 gdbpy_print_stack ();
182 if (msg != NULL && *msg != '\0')
183 error (_("Error occurred in Python command: %s"), msg.get ());
185 error (_("Error occurred in Python command."));
191 Py_XDECREF (ptraceback);
192 error ("%s", msg.get ());
197 /* Helper function for the Python command completers (both "pure"
198 completer and brkchar handler). This function takes COMMAND, TEXT
199 and WORD and tries to call the Python method for completion with
202 This function is usually called twice: once when we are figuring out
203 the break characters to be used, and another to perform the real
204 completion itself. The reason for this two step dance is that we
205 need to know the set of "brkchars" to use early on, before we
206 actually try to perform the completion. But if a Python command
207 supplies a "complete" method then we have to call that method
208 first: it may return as its result the kind of completion to
209 perform and that will in turn specify which brkchars to use. IOW,
210 we need the result of the "complete" method before we actually
211 perform the completion. The only situation when this function is
212 not called twice is when the user uses the "complete" command: in
213 this scenario, there is no call to determine the "brkchars".
215 Ideally, it would be nice to cache the result of the first call (to
216 determine the "brkchars") and return this value directly in the
217 second call (to perform the actual completion). However, due to
218 the peculiarity of the "complete" command mentioned above, it is
219 possible to put GDB in a bad state if you perform a TAB-completion
220 and then a "complete"-completion sequentially. Therefore, we just
221 recalculate everything twice for TAB-completions.
223 This function returns the PyObject representing the Python method
227 cmdpy_completer_helper (struct cmd_list_element *command,
228 const char *text, const char *word)
230 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command);
233 error (_("Invalid invocation of Python command object."));
234 if (!PyObject_HasAttr ((PyObject *) obj, complete_cst))
236 /* If there is no complete method, don't error. */
240 gdbpy_ref<> textobj (PyUnicode_Decode (text, strlen (text), host_charset (),
243 error (_("Could not convert argument to Python string."));
248 /* "brkchars" phase. */
249 wordobj = gdbpy_ref<>::new_reference (Py_None);
253 wordobj.reset (PyUnicode_Decode (word, strlen (word), host_charset (),
256 error (_("Could not convert argument to Python string."));
259 gdbpy_ref<> resultobj (PyObject_CallMethodObjArgs ((PyObject *) obj,
262 wordobj.get (), NULL));
263 if (resultobj == NULL)
265 /* Just swallow errors here. */
269 return resultobj.release ();
272 /* Python function called to determine the break characters of a
273 certain completer. We are only interested in knowing if the
274 completer registered by the user will return one of the integer
275 codes (see COMPLETER_* symbols). */
278 cmdpy_completer_handle_brkchars (struct cmd_list_element *command,
279 completion_tracker &tracker,
280 const char *text, const char *word)
282 gdbpy_enter enter_py (get_current_arch (), current_language);
284 /* Calling our helper to obtain the PyObject of the Python
286 gdbpy_ref<> resultobj (cmdpy_completer_helper (command, text, word));
288 /* Check if there was an error. */
289 if (resultobj == NULL)
292 if (PyInt_Check (resultobj.get ()))
294 /* User code may also return one of the completion constants,
295 thus requesting that sort of completion. We are only
296 interested in this kind of return. */
299 if (!gdb_py_int_as_long (resultobj.get (), &value))
304 else if (value >= 0 && value < (long) N_COMPLETERS)
306 completer_handle_brkchars_ftype *brkchars_fn;
308 /* This is the core of this function. Depending on which
309 completer type the Python function returns, we have to
310 adjust the break characters accordingly. */
311 brkchars_fn = (completer_handle_brkchars_func_for_completer
312 (completers[value].completer));
313 brkchars_fn (command, tracker, text, word);
318 /* Called by gdb for command completion. */
321 cmdpy_completer (struct cmd_list_element *command,
322 completion_tracker &tracker,
323 const char *text, const char *word)
325 gdbpy_enter enter_py (get_current_arch (), current_language);
327 /* Calling our helper to obtain the PyObject of the Python
329 gdbpy_ref<> resultobj (cmdpy_completer_helper (command, text, word));
331 /* If the result object of calling the Python function is NULL, it
332 means that there was an error. In this case, just give up. */
333 if (resultobj == NULL)
336 if (PyInt_Check (resultobj.get ()))
338 /* User code may also return one of the completion constants,
339 thus requesting that sort of completion. */
342 if (! gdb_py_int_as_long (resultobj.get (), &value))
347 else if (value >= 0 && value < (long) N_COMPLETERS)
348 completers[value].completer (command, tracker, text, word);
352 gdbpy_ref<> iter (PyObject_GetIter (resultobj.get ()));
357 bool got_matches = false;
360 gdbpy_ref<> elt (PyIter_Next (iter.get ()));
364 if (! gdbpy_is_string (elt.get ()))
366 /* Skip problem elements. */
369 gdb::unique_xmalloc_ptr<char>
370 item (python_string_to_host_string (elt.get ()));
373 /* Skip problem elements. */
377 tracker.add_completion (std::move (item));
381 /* If we got some results, ignore problems. Otherwise, report
383 if (got_matches && PyErr_Occurred ())
388 /* Helper for cmdpy_init which locates the command list to use and
389 pulls out the command name.
391 NAME is the command name list. The final word in the list is the
392 name of the new command. All earlier words must be existing prefix
395 *BASE_LIST is set to the final prefix command's list of
398 START_LIST is the list in which the search starts.
400 This function returns the xmalloc()d name of the new command. On
401 error sets the Python error and returns NULL. */
404 gdbpy_parse_command_name (const char *name,
405 struct cmd_list_element ***base_list,
406 struct cmd_list_element **start_list)
408 struct cmd_list_element *elt;
409 int len = strlen (name);
412 const char *prefix_text2;
415 /* Skip trailing whitespace. */
416 for (i = len - 1; i >= 0 && (name[i] == ' ' || name[i] == '\t'); --i)
420 PyErr_SetString (PyExc_RuntimeError, _("No command name found."));
425 /* Find first character of the final word. */
426 for (; i > 0 && (isalnum (name[i - 1])
427 || name[i - 1] == '-'
428 || name[i - 1] == '_');
431 result = (char *) xmalloc (lastchar - i + 2);
432 memcpy (result, &name[i], lastchar - i + 1);
433 result[lastchar - i + 1] = '\0';
435 /* Skip whitespace again. */
436 for (--i; i >= 0 && (name[i] == ' ' || name[i] == '\t'); --i)
440 *base_list = start_list;
444 prefix_text = (char *) xmalloc (i + 2);
445 memcpy (prefix_text, name, i + 1);
446 prefix_text[i + 1] = '\0';
448 prefix_text2 = prefix_text;
449 elt = lookup_cmd_1 (&prefix_text2, *start_list, NULL, 1);
450 if (elt == NULL || elt == CMD_LIST_AMBIGUOUS)
452 PyErr_Format (PyExc_RuntimeError, _("Could not find command prefix %s."),
462 *base_list = elt->prefixlist;
466 PyErr_Format (PyExc_RuntimeError, _("'%s' is not a prefix command."),
473 /* Object initializer; sets up gdb-side structures for command.
475 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
477 NAME is the name of the command. It may consist of multiple words,
478 in which case the final word is the name of the new command, and
479 earlier words must be prefix commands.
481 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
482 constants defined in the gdb module.
484 COMPLETER_CLASS is the kind of completer. If not given, the
485 "complete" method will be used. Otherwise, it should be one of the
486 COMPLETE_* constants defined in the gdb module.
488 If PREFIX is True, then this command is a prefix command.
490 The documentation for the command is taken from the doc string for
494 cmdpy_init (PyObject *self, PyObject *args, PyObject *kw)
496 cmdpy_object *obj = (cmdpy_object *) self;
499 int completetype = -1;
500 char *docstring = NULL;
501 struct cmd_list_element **cmd_list;
502 char *cmd_name, *pfx_name;
503 static const char *keywords[] = { "name", "command_class", "completer_class",
505 PyObject *is_prefix = NULL;
510 /* Note: this is apparently not documented in Python. We return
511 0 for success, -1 for failure. */
512 PyErr_Format (PyExc_RuntimeError,
513 _("Command object already initialized."));
517 if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "si|iO",
518 keywords, &name, &cmdtype,
519 &completetype, &is_prefix))
522 if (cmdtype != no_class && cmdtype != class_run
523 && cmdtype != class_vars && cmdtype != class_stack
524 && cmdtype != class_files && cmdtype != class_support
525 && cmdtype != class_info && cmdtype != class_breakpoint
526 && cmdtype != class_trace && cmdtype != class_obscure
527 && cmdtype != class_maintenance && cmdtype != class_user)
529 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
533 if (completetype < -1 || completetype >= (int) N_COMPLETERS)
535 PyErr_Format (PyExc_RuntimeError,
536 _("Invalid completion type argument."));
540 cmd_name = gdbpy_parse_command_name (name, &cmd_list, &cmdlist);
545 if (is_prefix != NULL)
547 cmp = PyObject_IsTrue (is_prefix);
552 /* Make a normalized form of the command name. */
553 pfx_name = (char *) xmalloc (strlen (name) + 2);
559 /* Skip whitespace. */
560 while (name[i] == ' ' || name[i] == '\t')
562 /* Copy non-whitespace characters. */
563 while (name[i] && name[i] != ' ' && name[i] != '\t')
564 pfx_name[out++] = name[i++];
565 /* Add a single space after each word -- including the final
567 pfx_name[out++] = ' ';
569 pfx_name[out] = '\0';
577 if (PyObject_HasAttr (self, gdbpy_doc_cst))
579 gdbpy_ref<> ds_obj (PyObject_GetAttr (self, gdbpy_doc_cst));
581 if (ds_obj != NULL && gdbpy_is_string (ds_obj.get ()))
583 docstring = python_string_to_host_string (ds_obj.get ()).release ();
584 if (docstring == NULL)
593 docstring = xstrdup (_("This command is not documented."));
599 struct cmd_list_element *cmd;
605 /* If we have our own "invoke" method, then allow unknown
607 allow_unknown = PyObject_HasAttr (self, invoke_cst);
608 cmd = add_prefix_cmd (cmd_name, (enum command_class) cmdtype,
609 NULL, docstring, &obj->sub_list,
610 pfx_name, allow_unknown, cmd_list);
613 cmd = add_cmd (cmd_name, (enum command_class) cmdtype,
614 docstring, cmd_list);
616 /* There appears to be no API to set this. */
617 cmd->func = cmdpy_function;
618 cmd->destroyer = cmdpy_destroyer;
621 set_cmd_context (cmd, self);
622 set_cmd_completer (cmd, ((completetype == -1) ? cmdpy_completer
623 : completers[completetype].completer));
624 if (completetype == -1)
625 set_cmd_completer_handle_brkchars (cmd,
626 cmdpy_completer_handle_brkchars);
628 CATCH (except, RETURN_MASK_ALL)
634 PyErr_Format (except.reason == RETURN_QUIT
635 ? PyExc_KeyboardInterrupt : PyExc_RuntimeError,
636 "%s", except.message);
646 /* Initialize the 'commands' code. */
649 gdbpy_initialize_commands (void)
653 cmdpy_object_type.tp_new = PyType_GenericNew;
654 if (PyType_Ready (&cmdpy_object_type) < 0)
657 /* Note: alias and user are special; pseudo appears to be unused,
658 and there is no reason to expose tui, I think. */
659 if (PyModule_AddIntConstant (gdb_module, "COMMAND_NONE", no_class) < 0
660 || PyModule_AddIntConstant (gdb_module, "COMMAND_RUNNING", class_run) < 0
661 || PyModule_AddIntConstant (gdb_module, "COMMAND_DATA", class_vars) < 0
662 || PyModule_AddIntConstant (gdb_module, "COMMAND_STACK", class_stack) < 0
663 || PyModule_AddIntConstant (gdb_module, "COMMAND_FILES", class_files) < 0
664 || PyModule_AddIntConstant (gdb_module, "COMMAND_SUPPORT",
666 || PyModule_AddIntConstant (gdb_module, "COMMAND_STATUS", class_info) < 0
667 || PyModule_AddIntConstant (gdb_module, "COMMAND_BREAKPOINTS",
668 class_breakpoint) < 0
669 || PyModule_AddIntConstant (gdb_module, "COMMAND_TRACEPOINTS",
671 || PyModule_AddIntConstant (gdb_module, "COMMAND_OBSCURE",
673 || PyModule_AddIntConstant (gdb_module, "COMMAND_MAINTENANCE",
674 class_maintenance) < 0
675 || PyModule_AddIntConstant (gdb_module, "COMMAND_USER", class_user) < 0)
678 for (i = 0; i < N_COMPLETERS; ++i)
680 if (PyModule_AddIntConstant (gdb_module, completers[i].name, i) < 0)
684 if (gdb_pymodule_addobject (gdb_module, "Command",
685 (PyObject *) &cmdpy_object_type) < 0)
688 invoke_cst = PyString_FromString ("invoke");
689 if (invoke_cst == NULL)
691 complete_cst = PyString_FromString ("complete");
692 if (complete_cst == NULL)
700 static PyMethodDef cmdpy_object_methods[] =
702 { "dont_repeat", cmdpy_dont_repeat, METH_NOARGS,
703 "Prevent command repetition when user enters empty line." },
708 PyTypeObject cmdpy_object_type =
710 PyVarObject_HEAD_INIT (NULL, 0)
711 "gdb.Command", /*tp_name*/
712 sizeof (cmdpy_object), /*tp_basicsize*/
721 0, /*tp_as_sequence*/
729 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
730 "GDB command object", /* tp_doc */
733 0, /* tp_richcompare */
734 0, /* tp_weaklistoffset */
737 cmdpy_object_methods, /* tp_methods */
742 0, /* tp_descr_get */
743 0, /* tp_descr_set */
744 0, /* tp_dictoffset */
745 cmdpy_init, /* tp_init */
751 /* Utility to build a buildargv-like result from ARGS.
752 This intentionally parses arguments the way libiberty/argv.c:buildargv
753 does. It splits up arguments in a reasonable way, and we want a standard
754 way of parsing arguments. Several gdb commands use buildargv to parse their
755 arguments. Plus we want to be able to write compatible python
756 implementations of gdb commands. */
759 gdbpy_string_to_argv (PyObject *self, PyObject *args)
763 if (!PyArg_ParseTuple (args, "s", &input))
766 gdbpy_ref<> py_argv (PyList_New (0));
770 /* buildargv uses NULL to represent an empty argument list, but we can't use
771 that in Python. Instead, if ARGS is "" then return an empty list.
772 This undoes the NULL -> "" conversion that cmdpy_function does. */
776 gdb_argv c_argv (input);
778 for (char *arg : c_argv)
780 gdbpy_ref<> argp (PyString_FromString (arg));
783 || PyList_Append (py_argv.get (), argp.get ()) < 0)
788 return py_argv.release ();