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.
36 This isn't a const char * for Python 2.4's sake.
37 PyModule_AddIntConstant only takes a char *, sigh. */
39 /* Completion function. */
40 completer_ftype
*completer
;
43 static const struct cmdpy_completer completers
[] =
45 { "COMPLETE_NONE", noop_completer
},
46 { "COMPLETE_FILENAME", filename_completer
},
47 { "COMPLETE_LOCATION", location_completer
},
48 { "COMPLETE_COMMAND", command_completer
},
49 { "COMPLETE_SYMBOL", make_symbol_completion_list_fn
},
50 { "COMPLETE_EXPRESSION", expression_completer
},
53 #define N_COMPLETERS (sizeof (completers) / sizeof (completers[0]))
55 /* A gdb command. For the time being only ordinary commands (not
56 set/show commands) are allowed. */
61 /* The corresponding gdb command object, or NULL if the command is
62 no longer installed. */
63 struct cmd_list_element
*command
;
65 /* A prefix command requires storage for a list of its sub-commands.
66 A pointer to this is passed to add_prefix_command, and to add_cmd
67 for sub-commands of that prefix. If this Command is not a prefix
68 command, then this field is unused. */
69 struct cmd_list_element
*sub_list
;
72 typedef struct cmdpy_object cmdpy_object
;
74 extern PyTypeObject cmdpy_object_type
75 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("cmdpy_object");
77 /* Constants used by this module. */
78 static PyObject
*invoke_cst
;
79 static PyObject
*complete_cst
;
83 /* Python function which wraps dont_repeat. */
85 cmdpy_dont_repeat (PyObject
*self
, PyObject
*args
)
93 /* Called if the gdb cmd_list_element is destroyed. */
96 cmdpy_destroyer (struct cmd_list_element
*self
, void *context
)
98 gdbpy_enter
enter_py (get_current_arch (), current_language
);
100 /* Release our hold on the command object. */
101 gdbpy_ref
<cmdpy_object
> cmd ((cmdpy_object
*) context
);
104 /* We allocated the name, doc string, and perhaps the prefix
106 xfree ((char *) self
->name
);
107 xfree ((char *) self
->doc
);
108 xfree ((char *) self
->prefixname
);
111 /* Called by gdb to invoke the command. */
114 cmdpy_function (struct cmd_list_element
*command
, char *args
, int from_tty
)
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."));
245 gdbpy_ref
<> wordobj (PyUnicode_Decode (word
, strlen (word
), host_charset (),
248 error (_("Could not convert argument to Python string."));
250 gdbpy_ref
<> resultobj (PyObject_CallMethodObjArgs ((PyObject
*) obj
,
253 wordobj
.get (), NULL
));
254 if (resultobj
== NULL
)
256 /* Just swallow errors here. */
260 return resultobj
.release ();
263 /* Python function called to determine the break characters of a
264 certain completer. We are only interested in knowing if the
265 completer registered by the user will return one of the integer
266 codes (see COMPLETER_* symbols). */
269 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
270 const char *text
, const char *word
)
272 gdbpy_enter
enter_py (get_current_arch (), current_language
);
274 /* Calling our helper to obtain the PyObject of the Python
276 gdbpy_ref
<> resultobj (cmdpy_completer_helper (command
, text
, word
));
278 /* Check if there was an error. */
279 if (resultobj
== NULL
)
282 if (PyInt_Check (resultobj
.get ()))
284 /* User code may also return one of the completion constants,
285 thus requesting that sort of completion. We are only
286 interested in this kind of return. */
289 if (!gdb_py_int_as_long (resultobj
.get (), &value
))
294 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
296 /* This is the core of this function. Depending on which
297 completer type the Python function returns, we have to
298 adjust the break characters accordingly. */
299 set_gdb_completion_word_break_characters
300 (completers
[value
].completer
);
305 /* Called by gdb for command completion. */
307 static VEC (char_ptr
) *
308 cmdpy_completer (struct cmd_list_element
*command
,
309 const char *text
, const char *word
)
311 VEC (char_ptr
) *result
= NULL
;
313 gdbpy_enter
enter_py (get_current_arch (), current_language
);
315 /* Calling our helper to obtain the PyObject of the Python
317 gdbpy_ref
<> resultobj (cmdpy_completer_helper (command
, text
, word
));
319 /* If the result object of calling the Python function is NULL, it
320 means that there was an error. In this case, just give up and
322 if (resultobj
== NULL
)
326 if (PyInt_Check (resultobj
.get ()))
328 /* User code may also return one of the completion constants,
329 thus requesting that sort of completion. */
332 if (! gdb_py_int_as_long (resultobj
.get (), &value
))
337 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
338 result
= completers
[value
].completer (command
, text
, word
);
342 gdbpy_ref
<> iter (PyObject_GetIter (resultobj
.get ()));
349 gdbpy_ref
<> elt (PyIter_Next (iter
.get ()));
353 if (! gdbpy_is_string (elt
.get ()))
355 /* Skip problem elements. */
358 gdb::unique_xmalloc_ptr
<char>
359 item (python_string_to_host_string (elt
.get ()));
362 /* Skip problem elements. */
366 VEC_safe_push (char_ptr
, result
, item
.release ());
369 /* If we got some results, ignore problems. Otherwise, report
371 if (result
!= NULL
&& PyErr_Occurred ())
378 /* Helper for cmdpy_init which locates the command list to use and
379 pulls out the command name.
381 NAME is the command name list. The final word in the list is the
382 name of the new command. All earlier words must be existing prefix
385 *BASE_LIST is set to the final prefix command's list of
388 START_LIST is the list in which the search starts.
390 This function returns the xmalloc()d name of the new command. On
391 error sets the Python error and returns NULL. */
394 gdbpy_parse_command_name (const char *name
,
395 struct cmd_list_element
***base_list
,
396 struct cmd_list_element
**start_list
)
398 struct cmd_list_element
*elt
;
399 int len
= strlen (name
);
402 const char *prefix_text2
;
405 /* Skip trailing whitespace. */
406 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
410 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
415 /* Find first character of the final word. */
416 for (; i
> 0 && (isalnum (name
[i
- 1])
417 || name
[i
- 1] == '-'
418 || name
[i
- 1] == '_');
421 result
= (char *) xmalloc (lastchar
- i
+ 2);
422 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
423 result
[lastchar
- i
+ 1] = '\0';
425 /* Skip whitespace again. */
426 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
430 *base_list
= start_list
;
434 prefix_text
= (char *) xmalloc (i
+ 2);
435 memcpy (prefix_text
, name
, i
+ 1);
436 prefix_text
[i
+ 1] = '\0';
438 prefix_text2
= prefix_text
;
439 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
440 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
442 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
452 *base_list
= elt
->prefixlist
;
456 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
463 /* Object initializer; sets up gdb-side structures for command.
465 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
467 NAME is the name of the command. It may consist of multiple words,
468 in which case the final word is the name of the new command, and
469 earlier words must be prefix commands.
471 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
472 constants defined in the gdb module.
474 COMPLETER_CLASS is the kind of completer. If not given, the
475 "complete" method will be used. Otherwise, it should be one of the
476 COMPLETE_* constants defined in the gdb module.
478 If PREFIX is True, then this command is a prefix command.
480 The documentation for the command is taken from the doc string for
484 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
486 cmdpy_object
*obj
= (cmdpy_object
*) self
;
489 int completetype
= -1;
490 char *docstring
= NULL
;
491 struct cmd_list_element
**cmd_list
;
492 char *cmd_name
, *pfx_name
;
493 static char *keywords
[] = { "name", "command_class", "completer_class",
495 PyObject
*is_prefix
= NULL
;
500 /* Note: this is apparently not documented in Python. We return
501 0 for success, -1 for failure. */
502 PyErr_Format (PyExc_RuntimeError
,
503 _("Command object already initialized."));
507 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
508 keywords
, &name
, &cmdtype
,
509 &completetype
, &is_prefix
))
512 if (cmdtype
!= no_class
&& cmdtype
!= class_run
513 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
514 && cmdtype
!= class_files
&& cmdtype
!= class_support
515 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
516 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
517 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
519 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
523 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
525 PyErr_Format (PyExc_RuntimeError
,
526 _("Invalid completion type argument."));
530 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
535 if (is_prefix
!= NULL
)
537 cmp
= PyObject_IsTrue (is_prefix
);
542 /* Make a normalized form of the command name. */
543 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
549 /* Skip whitespace. */
550 while (name
[i
] == ' ' || name
[i
] == '\t')
552 /* Copy non-whitespace characters. */
553 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
554 pfx_name
[out
++] = name
[i
++];
555 /* Add a single space after each word -- including the final
557 pfx_name
[out
++] = ' ';
559 pfx_name
[out
] = '\0';
567 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
569 gdbpy_ref
<> ds_obj (PyObject_GetAttr (self
, gdbpy_doc_cst
));
571 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
573 docstring
= python_string_to_host_string (ds_obj
.get ()).release ();
574 if (docstring
== NULL
)
583 docstring
= xstrdup (_("This command is not documented."));
589 struct cmd_list_element
*cmd
;
595 /* If we have our own "invoke" method, then allow unknown
597 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
598 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
599 NULL
, docstring
, &obj
->sub_list
,
600 pfx_name
, allow_unknown
, cmd_list
);
603 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
, NULL
,
604 docstring
, cmd_list
);
606 /* There appears to be no API to set this. */
607 cmd
->func
= cmdpy_function
;
608 cmd
->destroyer
= cmdpy_destroyer
;
611 set_cmd_context (cmd
, self
);
612 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
613 : completers
[completetype
].completer
));
614 if (completetype
== -1)
615 set_cmd_completer_handle_brkchars (cmd
,
616 cmdpy_completer_handle_brkchars
);
618 CATCH (except
, RETURN_MASK_ALL
)
624 PyErr_Format (except
.reason
== RETURN_QUIT
625 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
626 "%s", except
.message
);
636 /* Initialize the 'commands' code. */
639 gdbpy_initialize_commands (void)
643 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
644 if (PyType_Ready (&cmdpy_object_type
) < 0)
647 /* Note: alias and user are special; pseudo appears to be unused,
648 and there is no reason to expose tui, I think. */
649 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
650 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
651 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
652 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
653 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
654 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
656 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
657 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
658 class_breakpoint
) < 0
659 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
661 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
663 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
664 class_maintenance
) < 0
665 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
668 for (i
= 0; i
< N_COMPLETERS
; ++i
)
670 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
674 if (gdb_pymodule_addobject (gdb_module
, "Command",
675 (PyObject
*) &cmdpy_object_type
) < 0)
678 invoke_cst
= PyString_FromString ("invoke");
679 if (invoke_cst
== NULL
)
681 complete_cst
= PyString_FromString ("complete");
682 if (complete_cst
== NULL
)
690 static PyMethodDef cmdpy_object_methods
[] =
692 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
693 "Prevent command repetition when user enters empty line." },
698 PyTypeObject cmdpy_object_type
=
700 PyVarObject_HEAD_INIT (NULL
, 0)
701 "gdb.Command", /*tp_name*/
702 sizeof (cmdpy_object
), /*tp_basicsize*/
711 0, /*tp_as_sequence*/
719 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
720 "GDB command object", /* tp_doc */
723 0, /* tp_richcompare */
724 0, /* tp_weaklistoffset */
727 cmdpy_object_methods
, /* tp_methods */
732 0, /* tp_descr_get */
733 0, /* tp_descr_set */
734 0, /* tp_dictoffset */
735 cmdpy_init
, /* tp_init */
741 /* Utility to build a buildargv-like result from ARGS.
742 This intentionally parses arguments the way libiberty/argv.c:buildargv
743 does. It splits up arguments in a reasonable way, and we want a standard
744 way of parsing arguments. Several gdb commands use buildargv to parse their
745 arguments. Plus we want to be able to write compatible python
746 implementations of gdb commands. */
749 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
753 if (!PyArg_ParseTuple (args
, "s", &input
))
756 gdbpy_ref
<> py_argv (PyList_New (0));
760 /* buildargv uses NULL to represent an empty argument list, but we can't use
761 that in Python. Instead, if ARGS is "" then return an empty list.
762 This undoes the NULL -> "" conversion that cmdpy_function does. */
766 char **c_argv
= gdb_buildargv (input
);
769 for (i
= 0; c_argv
[i
] != NULL
; ++i
)
771 gdbpy_ref
<> argp (PyString_FromString (c_argv
[i
]));
774 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
784 return py_argv
.release ();