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
)
100 gdbpy_enter
enter_py (get_current_arch (), current_language
);
102 /* Release our hold on the command object. */
103 cmd
= (cmdpy_object
*) context
;
107 /* We allocated the name, doc string, and perhaps the prefix
109 xfree ((char *) self
->name
);
110 xfree ((char *) self
->doc
);
111 xfree ((char *) self
->prefixname
);
114 /* Called by gdb to invoke the command. */
117 cmdpy_function (struct cmd_list_element
*command
, char *args
, int from_tty
)
119 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
120 PyObject
*argobj
, *ttyobj
, *result
;
121 struct cleanup
*cleanup
;
123 cleanup
= ensure_python_env (get_current_arch (), current_language
);
126 error (_("Invalid invocation of Python command object."));
127 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
129 if (obj
->command
->prefixname
)
131 /* A prefix command does not need an invoke method. */
132 do_cleanups (cleanup
);
135 error (_("Python command object missing 'invoke' method."));
140 argobj
= PyUnicode_Decode (args
, strlen (args
), host_charset (), NULL
);
143 gdbpy_print_stack ();
144 error (_("Could not convert arguments to Python string."));
147 ttyobj
= from_tty
? Py_True
: Py_False
;
149 result
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
, argobj
,
156 PyObject
*ptype
, *pvalue
, *ptraceback
;
158 PyErr_Fetch (&ptype
, &pvalue
, &ptraceback
);
160 /* Try to fetch an error message contained within ptype, pvalue.
161 When fetching the error message we need to make our own copy,
162 we no longer own ptype, pvalue after the call to PyErr_Restore. */
164 gdb::unique_xmalloc_ptr
<char>
165 msg (gdbpy_exception_to_string (ptype
, pvalue
));
169 /* An error occurred computing the string representation of the
170 error message. This is rare, but we should inform the user. */
171 printf_filtered (_("An error occurred in a Python command\n"
172 "and then another occurred computing the "
173 "error message.\n"));
174 gdbpy_print_stack ();
177 /* Don't print the stack for gdb.GdbError exceptions.
178 It is generally used to flag user errors.
180 We also don't want to print "Error occurred in Python command"
181 for user errors. However, a missing message for gdb.GdbError
182 exceptions is arguably a bug, so we flag it as such. */
184 if (! PyErr_GivenExceptionMatches (ptype
, gdbpy_gdberror_exc
)
185 || msg
== NULL
|| *msg
== '\0')
187 PyErr_Restore (ptype
, pvalue
, ptraceback
);
188 gdbpy_print_stack ();
189 if (msg
!= NULL
&& *msg
!= '\0')
190 error (_("Error occurred in Python command: %s"), msg
.get ());
192 error (_("Error occurred in Python command."));
198 Py_XDECREF (ptraceback
);
199 error ("%s", msg
.get ());
204 do_cleanups (cleanup
);
207 /* Helper function for the Python command completers (both "pure"
208 completer and brkchar handler). This function takes COMMAND, TEXT
209 and WORD and tries to call the Python method for completion with
212 This function is usually called twice: once when we are figuring out
213 the break characters to be used, and another to perform the real
214 completion itself. The reason for this two step dance is that we
215 need to know the set of "brkchars" to use early on, before we
216 actually try to perform the completion. But if a Python command
217 supplies a "complete" method then we have to call that method
218 first: it may return as its result the kind of completion to
219 perform and that will in turn specify which brkchars to use. IOW,
220 we need the result of the "complete" method before we actually
221 perform the completion. The only situation when this function is
222 not called twice is when the user uses the "complete" command: in
223 this scenario, there is no call to determine the "brkchars".
225 Ideally, it would be nice to cache the result of the first call (to
226 determine the "brkchars") and return this value directly in the
227 second call (to perform the actual completion). However, due to
228 the peculiarity of the "complete" command mentioned above, it is
229 possible to put GDB in a bad state if you perform a TAB-completion
230 and then a "complete"-completion sequentially. Therefore, we just
231 recalculate everything twice for TAB-completions.
233 This function returns the PyObject representing the Python method
237 cmdpy_completer_helper (struct cmd_list_element
*command
,
238 const char *text
, const char *word
)
240 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
241 PyObject
*textobj
, *wordobj
;
245 error (_("Invalid invocation of Python command object."));
246 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
248 /* If there is no complete method, don't error. */
252 textobj
= PyUnicode_Decode (text
, strlen (text
), host_charset (), NULL
);
254 error (_("Could not convert argument to Python string."));
255 wordobj
= PyUnicode_Decode (word
, strlen (word
), host_charset (), NULL
);
259 error (_("Could not convert argument to Python string."));
262 resultobj
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, complete_cst
,
263 textobj
, wordobj
, NULL
);
268 /* Just swallow errors here. */
272 Py_XINCREF (resultobj
);
277 /* Python function called to determine the break characters of a
278 certain completer. We are only interested in knowing if the
279 completer registered by the user will return one of the integer
280 codes (see COMPLETER_* symbols). */
283 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
284 const char *text
, const char *word
)
286 PyObject
*resultobj
= NULL
;
288 gdbpy_enter
enter_py (get_current_arch (), current_language
);
290 /* Calling our helper to obtain the PyObject of the Python
292 resultobj
= cmdpy_completer_helper (command
, text
, word
);
294 /* Check if there was an error. */
295 if (resultobj
== NULL
)
298 if (PyInt_Check (resultobj
))
300 /* User code may also return one of the completion constants,
301 thus requesting that sort of completion. We are only
302 interested in this kind of return. */
305 if (!gdb_py_int_as_long (resultobj
, &value
))
310 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
312 /* This is the core of this function. Depending on which
313 completer type the Python function returns, we have to
314 adjust the break characters accordingly. */
315 set_gdb_completion_word_break_characters
316 (completers
[value
].completer
);
322 Py_XDECREF (resultobj
);
325 /* Called by gdb for command completion. */
327 static VEC (char_ptr
) *
328 cmdpy_completer (struct cmd_list_element
*command
,
329 const char *text
, const char *word
)
331 PyObject
*resultobj
= NULL
;
332 VEC (char_ptr
) *result
= NULL
;
334 gdbpy_enter
enter_py (get_current_arch (), current_language
);
336 /* Calling our helper to obtain the PyObject of the Python
338 resultobj
= cmdpy_completer_helper (command
, text
, word
);
340 /* If the result object of calling the Python function is NULL, it
341 means that there was an error. In this case, just give up and
343 if (resultobj
== NULL
)
347 if (PyInt_Check (resultobj
))
349 /* User code may also return one of the completion constants,
350 thus requesting that sort of completion. */
353 if (! gdb_py_int_as_long (resultobj
, &value
))
358 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
359 result
= completers
[value
].completer (command
, text
, word
);
363 PyObject
*iter
= PyObject_GetIter (resultobj
);
369 while ((elt
= PyIter_Next (iter
)) != NULL
)
372 if (! gdbpy_is_string (elt
))
374 /* Skip problem elements. */
378 gdb::unique_xmalloc_ptr
<char>
379 item (python_string_to_host_string (elt
));
383 /* Skip problem elements. */
387 VEC_safe_push (char_ptr
, result
, item
.release ());
392 /* If we got some results, ignore problems. Otherwise, report
394 if (result
!= NULL
&& PyErr_Occurred ())
400 Py_XDECREF (resultobj
);
405 /* Helper for cmdpy_init which locates the command list to use and
406 pulls out the command name.
408 NAME is the command name list. The final word in the list is the
409 name of the new command. All earlier words must be existing prefix
412 *BASE_LIST is set to the final prefix command's list of
415 START_LIST is the list in which the search starts.
417 This function returns the xmalloc()d name of the new command. On
418 error sets the Python error and returns NULL. */
421 gdbpy_parse_command_name (const char *name
,
422 struct cmd_list_element
***base_list
,
423 struct cmd_list_element
**start_list
)
425 struct cmd_list_element
*elt
;
426 int len
= strlen (name
);
429 const char *prefix_text2
;
432 /* Skip trailing whitespace. */
433 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
437 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
442 /* Find first character of the final word. */
443 for (; i
> 0 && (isalnum (name
[i
- 1])
444 || name
[i
- 1] == '-'
445 || name
[i
- 1] == '_');
448 result
= (char *) xmalloc (lastchar
- i
+ 2);
449 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
450 result
[lastchar
- i
+ 1] = '\0';
452 /* Skip whitespace again. */
453 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
457 *base_list
= start_list
;
461 prefix_text
= (char *) xmalloc (i
+ 2);
462 memcpy (prefix_text
, name
, i
+ 1);
463 prefix_text
[i
+ 1] = '\0';
465 prefix_text2
= prefix_text
;
466 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
467 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
469 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
479 *base_list
= elt
->prefixlist
;
483 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
490 /* Object initializer; sets up gdb-side structures for command.
492 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
494 NAME is the name of the command. It may consist of multiple words,
495 in which case the final word is the name of the new command, and
496 earlier words must be prefix commands.
498 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
499 constants defined in the gdb module.
501 COMPLETER_CLASS is the kind of completer. If not given, the
502 "complete" method will be used. Otherwise, it should be one of the
503 COMPLETE_* constants defined in the gdb module.
505 If PREFIX is True, then this command is a prefix command.
507 The documentation for the command is taken from the doc string for
511 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
513 cmdpy_object
*obj
= (cmdpy_object
*) self
;
516 int completetype
= -1;
517 char *docstring
= NULL
;
518 struct cmd_list_element
**cmd_list
;
519 char *cmd_name
, *pfx_name
;
520 static char *keywords
[] = { "name", "command_class", "completer_class",
522 PyObject
*is_prefix
= NULL
;
527 /* Note: this is apparently not documented in Python. We return
528 0 for success, -1 for failure. */
529 PyErr_Format (PyExc_RuntimeError
,
530 _("Command object already initialized."));
534 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
535 keywords
, &name
, &cmdtype
,
536 &completetype
, &is_prefix
))
539 if (cmdtype
!= no_class
&& cmdtype
!= class_run
540 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
541 && cmdtype
!= class_files
&& cmdtype
!= class_support
542 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
543 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
544 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
546 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
550 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
552 PyErr_Format (PyExc_RuntimeError
,
553 _("Invalid completion type argument."));
557 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
562 if (is_prefix
!= NULL
)
564 cmp
= PyObject_IsTrue (is_prefix
);
569 /* Make a normalized form of the command name. */
570 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
576 /* Skip whitespace. */
577 while (name
[i
] == ' ' || name
[i
] == '\t')
579 /* Copy non-whitespace characters. */
580 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
581 pfx_name
[out
++] = name
[i
++];
582 /* Add a single space after each word -- including the final
584 pfx_name
[out
++] = ' ';
586 pfx_name
[out
] = '\0';
594 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
596 PyObject
*ds_obj
= PyObject_GetAttr (self
, gdbpy_doc_cst
);
598 if (ds_obj
&& gdbpy_is_string (ds_obj
))
600 docstring
= python_string_to_host_string (ds_obj
).release ();
601 if (docstring
== NULL
)
613 docstring
= xstrdup (_("This command is not documented."));
619 struct cmd_list_element
*cmd
;
625 /* If we have our own "invoke" method, then allow unknown
627 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
628 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
629 NULL
, docstring
, &obj
->sub_list
,
630 pfx_name
, allow_unknown
, cmd_list
);
633 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
, NULL
,
634 docstring
, cmd_list
);
636 /* There appears to be no API to set this. */
637 cmd
->func
= cmdpy_function
;
638 cmd
->destroyer
= cmdpy_destroyer
;
641 set_cmd_context (cmd
, self
);
642 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
643 : completers
[completetype
].completer
));
644 if (completetype
== -1)
645 set_cmd_completer_handle_brkchars (cmd
,
646 cmdpy_completer_handle_brkchars
);
648 CATCH (except
, RETURN_MASK_ALL
)
654 PyErr_Format (except
.reason
== RETURN_QUIT
655 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
656 "%s", except
.message
);
666 /* Initialize the 'commands' code. */
669 gdbpy_initialize_commands (void)
673 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
674 if (PyType_Ready (&cmdpy_object_type
) < 0)
677 /* Note: alias and user are special; pseudo appears to be unused,
678 and there is no reason to expose tui, I think. */
679 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
680 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
681 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
682 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
683 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
684 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
686 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
687 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
688 class_breakpoint
) < 0
689 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
691 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
693 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
694 class_maintenance
) < 0
695 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
698 for (i
= 0; i
< N_COMPLETERS
; ++i
)
700 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
704 if (gdb_pymodule_addobject (gdb_module
, "Command",
705 (PyObject
*) &cmdpy_object_type
) < 0)
708 invoke_cst
= PyString_FromString ("invoke");
709 if (invoke_cst
== NULL
)
711 complete_cst
= PyString_FromString ("complete");
712 if (complete_cst
== NULL
)
720 static PyMethodDef cmdpy_object_methods
[] =
722 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
723 "Prevent command repetition when user enters empty line." },
728 PyTypeObject cmdpy_object_type
=
730 PyVarObject_HEAD_INIT (NULL
, 0)
731 "gdb.Command", /*tp_name*/
732 sizeof (cmdpy_object
), /*tp_basicsize*/
741 0, /*tp_as_sequence*/
749 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
750 "GDB command object", /* tp_doc */
753 0, /* tp_richcompare */
754 0, /* tp_weaklistoffset */
757 cmdpy_object_methods
, /* tp_methods */
762 0, /* tp_descr_get */
763 0, /* tp_descr_set */
764 0, /* tp_dictoffset */
765 cmdpy_init
, /* tp_init */
771 /* Utility to build a buildargv-like result from ARGS.
772 This intentionally parses arguments the way libiberty/argv.c:buildargv
773 does. It splits up arguments in a reasonable way, and we want a standard
774 way of parsing arguments. Several gdb commands use buildargv to parse their
775 arguments. Plus we want to be able to write compatible python
776 implementations of gdb commands. */
779 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
783 if (!PyArg_ParseTuple (args
, "s", &input
))
786 gdbpy_ref
py_argv (PyList_New (0));
790 /* buildargv uses NULL to represent an empty argument list, but we can't use
791 that in Python. Instead, if ARGS is "" then return an empty list.
792 This undoes the NULL -> "" conversion that cmdpy_function does. */
796 char **c_argv
= gdb_buildargv (input
);
799 for (i
= 0; c_argv
[i
] != NULL
; ++i
)
801 gdbpy_ref
argp (PyString_FromString (c_argv
[i
]));
804 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
814 return py_argv
.release ();