1 /* gdb commands implemented in Python
3 Copyright (C) 2008-2017 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 char *args_entry, int from_tty)
115 const char *args = args_entry;
116 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command);
118 gdbpy_enter enter_py (get_current_arch (), current_language);
121 error (_("Invalid invocation of Python command object."));
122 if (! PyObject_HasAttr ((PyObject *) obj, invoke_cst))
124 if (obj->command->prefixname)
126 /* A prefix command does not need an invoke method. */
129 error (_("Python command object missing 'invoke' method."));
134 gdbpy_ref<> argobj (PyUnicode_Decode (args, strlen (args), host_charset (),
138 gdbpy_print_stack ();
139 error (_("Could not convert arguments to Python string."));
142 gdbpy_ref<> ttyobj (from_tty ? Py_True : Py_False);
143 Py_INCREF (ttyobj.get ());
144 gdbpy_ref<> result (PyObject_CallMethodObjArgs ((PyObject *) obj, invoke_cst,
145 argobj.get (), ttyobj.get (),
150 PyObject *ptype, *pvalue, *ptraceback;
152 PyErr_Fetch (&ptype, &pvalue, &ptraceback);
154 /* Try to fetch an error message contained within ptype, pvalue.
155 When fetching the error message we need to make our own copy,
156 we no longer own ptype, pvalue after the call to PyErr_Restore. */
158 gdb::unique_xmalloc_ptr<char>
159 msg (gdbpy_exception_to_string (ptype, pvalue));
163 /* An error occurred computing the string representation of the
164 error message. This is rare, but we should inform the user. */
165 printf_filtered (_("An error occurred in a Python command\n"
166 "and then another occurred computing the "
167 "error message.\n"));
168 gdbpy_print_stack ();
171 /* Don't print the stack for gdb.GdbError exceptions.
172 It is generally used to flag user errors.
174 We also don't want to print "Error occurred in Python command"
175 for user errors. However, a missing message for gdb.GdbError
176 exceptions is arguably a bug, so we flag it as such. */
178 if (! PyErr_GivenExceptionMatches (ptype, gdbpy_gdberror_exc)
179 || msg == NULL || *msg == '\0')
181 PyErr_Restore (ptype, pvalue, ptraceback);
182 gdbpy_print_stack ();
183 if (msg != NULL && *msg != '\0')
184 error (_("Error occurred in Python command: %s"), msg.get ());
186 error (_("Error occurred in Python command."));
192 Py_XDECREF (ptraceback);
193 error ("%s", msg.get ());
198 /* Helper function for the Python command completers (both "pure"
199 completer and brkchar handler). This function takes COMMAND, TEXT
200 and WORD and tries to call the Python method for completion with
203 This function is usually called twice: once when we are figuring out
204 the break characters to be used, and another to perform the real
205 completion itself. The reason for this two step dance is that we
206 need to know the set of "brkchars" to use early on, before we
207 actually try to perform the completion. But if a Python command
208 supplies a "complete" method then we have to call that method
209 first: it may return as its result the kind of completion to
210 perform and that will in turn specify which brkchars to use. IOW,
211 we need the result of the "complete" method before we actually
212 perform the completion. The only situation when this function is
213 not called twice is when the user uses the "complete" command: in
214 this scenario, there is no call to determine the "brkchars".
216 Ideally, it would be nice to cache the result of the first call (to
217 determine the "brkchars") and return this value directly in the
218 second call (to perform the actual completion). However, due to
219 the peculiarity of the "complete" command mentioned above, it is
220 possible to put GDB in a bad state if you perform a TAB-completion
221 and then a "complete"-completion sequentially. Therefore, we just
222 recalculate everything twice for TAB-completions.
224 This function returns the PyObject representing the Python method
228 cmdpy_completer_helper (struct cmd_list_element *command,
229 const char *text, const char *word)
231 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command);
234 error (_("Invalid invocation of Python command object."));
235 if (!PyObject_HasAttr ((PyObject *) obj, complete_cst))
237 /* If there is no complete method, don't error. */
241 gdbpy_ref<> textobj (PyUnicode_Decode (text, strlen (text), host_charset (),
244 error (_("Could not convert argument to Python string."));
249 /* "brkchars" phase. */
250 wordobj.reset (Py_None);
255 wordobj.reset (PyUnicode_Decode (word, strlen (word), host_charset (),
258 error (_("Could not convert argument to Python string."));
261 gdbpy_ref<> resultobj (PyObject_CallMethodObjArgs ((PyObject *) obj,
264 wordobj.get (), NULL));
265 if (resultobj == NULL)
267 /* Just swallow errors here. */
271 return resultobj.release ();
274 /* Python function called to determine the break characters of a
275 certain completer. We are only interested in knowing if the
276 completer registered by the user will return one of the integer
277 codes (see COMPLETER_* symbols). */
280 cmdpy_completer_handle_brkchars (struct cmd_list_element *command,
281 completion_tracker &tracker,
282 const char *text, const char *word)
284 gdbpy_enter enter_py (get_current_arch (), current_language);
286 /* Calling our helper to obtain the PyObject of the Python
288 gdbpy_ref<> resultobj (cmdpy_completer_helper (command, text, word));
290 /* Check if there was an error. */
291 if (resultobj == NULL)
294 if (PyInt_Check (resultobj.get ()))
296 /* User code may also return one of the completion constants,
297 thus requesting that sort of completion. We are only
298 interested in this kind of return. */
301 if (!gdb_py_int_as_long (resultobj.get (), &value))
306 else if (value >= 0 && value < (long) N_COMPLETERS)
308 completer_handle_brkchars_ftype *brkchars_fn;
310 /* This is the core of this function. Depending on which
311 completer type the Python function returns, we have to
312 adjust the break characters accordingly. */
313 brkchars_fn = (completer_handle_brkchars_func_for_completer
314 (completers[value].completer));
315 brkchars_fn (command, tracker, text, word);
320 /* Called by gdb for command completion. */
323 cmdpy_completer (struct cmd_list_element *command,
324 completion_tracker &tracker,
325 const char *text, const char *word)
327 gdbpy_enter enter_py (get_current_arch (), current_language);
329 /* Calling our helper to obtain the PyObject of the Python
331 gdbpy_ref<> resultobj (cmdpy_completer_helper (command, text, word));
333 /* If the result object of calling the Python function is NULL, it
334 means that there was an error. In this case, just give up. */
335 if (resultobj == NULL)
338 if (PyInt_Check (resultobj.get ()))
340 /* User code may also return one of the completion constants,
341 thus requesting that sort of completion. */
344 if (! gdb_py_int_as_long (resultobj.get (), &value))
349 else if (value >= 0 && value < (long) N_COMPLETERS)
350 completers[value].completer (command, tracker, text, word);
354 gdbpy_ref<> iter (PyObject_GetIter (resultobj.get ()));
359 bool got_matches = false;
362 gdbpy_ref<> elt (PyIter_Next (iter.get ()));
366 if (! gdbpy_is_string (elt.get ()))
368 /* Skip problem elements. */
371 gdb::unique_xmalloc_ptr<char>
372 item (python_string_to_host_string (elt.get ()));
375 /* Skip problem elements. */
379 tracker.add_completion (std::move (item));
383 /* If we got some results, ignore problems. Otherwise, report
385 if (got_matches && PyErr_Occurred ())
390 /* Helper for cmdpy_init which locates the command list to use and
391 pulls out the command name.
393 NAME is the command name list. The final word in the list is the
394 name of the new command. All earlier words must be existing prefix
397 *BASE_LIST is set to the final prefix command's list of
400 START_LIST is the list in which the search starts.
402 This function returns the xmalloc()d name of the new command. On
403 error sets the Python error and returns NULL. */
406 gdbpy_parse_command_name (const char *name,
407 struct cmd_list_element ***base_list,
408 struct cmd_list_element **start_list)
410 struct cmd_list_element *elt;
411 int len = strlen (name);
414 const char *prefix_text2;
417 /* Skip trailing whitespace. */
418 for (i = len - 1; i >= 0 && (name[i] == ' ' || name[i] == '\t'); --i)
422 PyErr_SetString (PyExc_RuntimeError, _("No command name found."));
427 /* Find first character of the final word. */
428 for (; i > 0 && (isalnum (name[i - 1])
429 || name[i - 1] == '-'
430 || name[i - 1] == '_');
433 result = (char *) xmalloc (lastchar - i + 2);
434 memcpy (result, &name[i], lastchar - i + 1);
435 result[lastchar - i + 1] = '\0';
437 /* Skip whitespace again. */
438 for (--i; i >= 0 && (name[i] == ' ' || name[i] == '\t'); --i)
442 *base_list = start_list;
446 prefix_text = (char *) xmalloc (i + 2);
447 memcpy (prefix_text, name, i + 1);
448 prefix_text[i + 1] = '\0';
450 prefix_text2 = prefix_text;
451 elt = lookup_cmd_1 (&prefix_text2, *start_list, NULL, 1);
452 if (elt == NULL || elt == CMD_LIST_AMBIGUOUS)
454 PyErr_Format (PyExc_RuntimeError, _("Could not find command prefix %s."),
464 *base_list = elt->prefixlist;
468 PyErr_Format (PyExc_RuntimeError, _("'%s' is not a prefix command."),
475 /* Object initializer; sets up gdb-side structures for command.
477 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
479 NAME is the name of the command. It may consist of multiple words,
480 in which case the final word is the name of the new command, and
481 earlier words must be prefix commands.
483 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
484 constants defined in the gdb module.
486 COMPLETER_CLASS is the kind of completer. If not given, the
487 "complete" method will be used. Otherwise, it should be one of the
488 COMPLETE_* constants defined in the gdb module.
490 If PREFIX is True, then this command is a prefix command.
492 The documentation for the command is taken from the doc string for
496 cmdpy_init (PyObject *self, PyObject *args, PyObject *kw)
498 cmdpy_object *obj = (cmdpy_object *) self;
501 int completetype = -1;
502 char *docstring = NULL;
503 struct cmd_list_element **cmd_list;
504 char *cmd_name, *pfx_name;
505 static const char *keywords[] = { "name", "command_class", "completer_class",
507 PyObject *is_prefix = NULL;
512 /* Note: this is apparently not documented in Python. We return
513 0 for success, -1 for failure. */
514 PyErr_Format (PyExc_RuntimeError,
515 _("Command object already initialized."));
519 if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "si|iO",
520 keywords, &name, &cmdtype,
521 &completetype, &is_prefix))
524 if (cmdtype != no_class && cmdtype != class_run
525 && cmdtype != class_vars && cmdtype != class_stack
526 && cmdtype != class_files && cmdtype != class_support
527 && cmdtype != class_info && cmdtype != class_breakpoint
528 && cmdtype != class_trace && cmdtype != class_obscure
529 && cmdtype != class_maintenance && cmdtype != class_user)
531 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
535 if (completetype < -1 || completetype >= (int) N_COMPLETERS)
537 PyErr_Format (PyExc_RuntimeError,
538 _("Invalid completion type argument."));
542 cmd_name = gdbpy_parse_command_name (name, &cmd_list, &cmdlist);
547 if (is_prefix != NULL)
549 cmp = PyObject_IsTrue (is_prefix);
554 /* Make a normalized form of the command name. */
555 pfx_name = (char *) xmalloc (strlen (name) + 2);
561 /* Skip whitespace. */
562 while (name[i] == ' ' || name[i] == '\t')
564 /* Copy non-whitespace characters. */
565 while (name[i] && name[i] != ' ' && name[i] != '\t')
566 pfx_name[out++] = name[i++];
567 /* Add a single space after each word -- including the final
569 pfx_name[out++] = ' ';
571 pfx_name[out] = '\0';
579 if (PyObject_HasAttr (self, gdbpy_doc_cst))
581 gdbpy_ref<> ds_obj (PyObject_GetAttr (self, gdbpy_doc_cst));
583 if (ds_obj != NULL && gdbpy_is_string (ds_obj.get ()))
585 docstring = python_string_to_host_string (ds_obj.get ()).release ();
586 if (docstring == NULL)
595 docstring = xstrdup (_("This command is not documented."));
601 struct cmd_list_element *cmd;
607 /* If we have our own "invoke" method, then allow unknown
609 allow_unknown = PyObject_HasAttr (self, invoke_cst);
610 cmd = add_prefix_cmd (cmd_name, (enum command_class) cmdtype,
611 NULL, docstring, &obj->sub_list,
612 pfx_name, allow_unknown, cmd_list);
615 cmd = add_cmd (cmd_name, (enum command_class) cmdtype, NULL,
616 docstring, cmd_list);
618 /* There appears to be no API to set this. */
619 cmd->func = cmdpy_function;
620 cmd->destroyer = cmdpy_destroyer;
623 set_cmd_context (cmd, self);
624 set_cmd_completer (cmd, ((completetype == -1) ? cmdpy_completer
625 : completers[completetype].completer));
626 if (completetype == -1)
627 set_cmd_completer_handle_brkchars (cmd,
628 cmdpy_completer_handle_brkchars);
630 CATCH (except, RETURN_MASK_ALL)
636 PyErr_Format (except.reason == RETURN_QUIT
637 ? PyExc_KeyboardInterrupt : PyExc_RuntimeError,
638 "%s", except.message);
648 /* Initialize the 'commands' code. */
651 gdbpy_initialize_commands (void)
655 cmdpy_object_type.tp_new = PyType_GenericNew;
656 if (PyType_Ready (&cmdpy_object_type) < 0)
659 /* Note: alias and user are special; pseudo appears to be unused,
660 and there is no reason to expose tui, I think. */
661 if (PyModule_AddIntConstant (gdb_module, "COMMAND_NONE", no_class) < 0
662 || PyModule_AddIntConstant (gdb_module, "COMMAND_RUNNING", class_run) < 0
663 || PyModule_AddIntConstant (gdb_module, "COMMAND_DATA", class_vars) < 0
664 || PyModule_AddIntConstant (gdb_module, "COMMAND_STACK", class_stack) < 0
665 || PyModule_AddIntConstant (gdb_module, "COMMAND_FILES", class_files) < 0
666 || PyModule_AddIntConstant (gdb_module, "COMMAND_SUPPORT",
668 || PyModule_AddIntConstant (gdb_module, "COMMAND_STATUS", class_info) < 0
669 || PyModule_AddIntConstant (gdb_module, "COMMAND_BREAKPOINTS",
670 class_breakpoint) < 0
671 || PyModule_AddIntConstant (gdb_module, "COMMAND_TRACEPOINTS",
673 || PyModule_AddIntConstant (gdb_module, "COMMAND_OBSCURE",
675 || PyModule_AddIntConstant (gdb_module, "COMMAND_MAINTENANCE",
676 class_maintenance) < 0
677 || PyModule_AddIntConstant (gdb_module, "COMMAND_USER", class_user) < 0)
680 for (i = 0; i < N_COMPLETERS; ++i)
682 if (PyModule_AddIntConstant (gdb_module, completers[i].name, i) < 0)
686 if (gdb_pymodule_addobject (gdb_module, "Command",
687 (PyObject *) &cmdpy_object_type) < 0)
690 invoke_cst = PyString_FromString ("invoke");
691 if (invoke_cst == NULL)
693 complete_cst = PyString_FromString ("complete");
694 if (complete_cst == NULL)
702 static PyMethodDef cmdpy_object_methods[] =
704 { "dont_repeat", cmdpy_dont_repeat, METH_NOARGS,
705 "Prevent command repetition when user enters empty line." },
710 PyTypeObject cmdpy_object_type =
712 PyVarObject_HEAD_INIT (NULL, 0)
713 "gdb.Command", /*tp_name*/
714 sizeof (cmdpy_object), /*tp_basicsize*/
723 0, /*tp_as_sequence*/
731 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
732 "GDB command object", /* tp_doc */
735 0, /* tp_richcompare */
736 0, /* tp_weaklistoffset */
739 cmdpy_object_methods, /* tp_methods */
744 0, /* tp_descr_get */
745 0, /* tp_descr_set */
746 0, /* tp_dictoffset */
747 cmdpy_init, /* tp_init */
753 /* Utility to build a buildargv-like result from ARGS.
754 This intentionally parses arguments the way libiberty/argv.c:buildargv
755 does. It splits up arguments in a reasonable way, and we want a standard
756 way of parsing arguments. Several gdb commands use buildargv to parse their
757 arguments. Plus we want to be able to write compatible python
758 implementations of gdb commands. */
761 gdbpy_string_to_argv (PyObject *self, PyObject *args)
765 if (!PyArg_ParseTuple (args, "s", &input))
768 gdbpy_ref<> py_argv (PyList_New (0));
772 /* buildargv uses NULL to represent an empty argument list, but we can't use
773 that in Python. Instead, if ARGS is "" then return an empty list.
774 This undoes the NULL -> "" conversion that cmdpy_function does. */
778 char **c_argv = gdb_buildargv (input);
781 for (i = 0; c_argv[i] != NULL; ++i)
783 gdbpy_ref<> argp (PyString_FromString (c_argv[i]));
786 || PyList_Append (py_argv.get (), argp.get ()) < 0)
796 return py_argv.release ();