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
);
121 gdbpy_enter
enter_py (get_current_arch (), current_language
);
124 error (_("Invalid invocation of Python command object."));
125 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
127 if (obj
->command
->prefixname
)
129 /* A prefix command does not need an invoke method. */
132 error (_("Python command object missing 'invoke' method."));
137 gdbpy_ref
argobj (PyUnicode_Decode (args
, strlen (args
), host_charset (),
141 gdbpy_print_stack ();
142 error (_("Could not convert arguments to Python string."));
145 gdbpy_ref
ttyobj (from_tty
? Py_True
: Py_False
);
146 Py_INCREF (ttyobj
.get ());
147 gdbpy_ref
result (PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
,
148 argobj
.get (), ttyobj
.get (),
153 PyObject
*ptype
, *pvalue
, *ptraceback
;
155 PyErr_Fetch (&ptype
, &pvalue
, &ptraceback
);
157 /* Try to fetch an error message contained within ptype, pvalue.
158 When fetching the error message we need to make our own copy,
159 we no longer own ptype, pvalue after the call to PyErr_Restore. */
161 gdb::unique_xmalloc_ptr
<char>
162 msg (gdbpy_exception_to_string (ptype
, pvalue
));
166 /* An error occurred computing the string representation of the
167 error message. This is rare, but we should inform the user. */
168 printf_filtered (_("An error occurred in a Python command\n"
169 "and then another occurred computing the "
170 "error message.\n"));
171 gdbpy_print_stack ();
174 /* Don't print the stack for gdb.GdbError exceptions.
175 It is generally used to flag user errors.
177 We also don't want to print "Error occurred in Python command"
178 for user errors. However, a missing message for gdb.GdbError
179 exceptions is arguably a bug, so we flag it as such. */
181 if (! PyErr_GivenExceptionMatches (ptype
, gdbpy_gdberror_exc
)
182 || msg
== NULL
|| *msg
== '\0')
184 PyErr_Restore (ptype
, pvalue
, ptraceback
);
185 gdbpy_print_stack ();
186 if (msg
!= NULL
&& *msg
!= '\0')
187 error (_("Error occurred in Python command: %s"), msg
.get ());
189 error (_("Error occurred in Python command."));
195 Py_XDECREF (ptraceback
);
196 error ("%s", msg
.get ());
201 /* Helper function for the Python command completers (both "pure"
202 completer and brkchar handler). This function takes COMMAND, TEXT
203 and WORD and tries to call the Python method for completion with
206 This function is usually called twice: once when we are figuring out
207 the break characters to be used, and another to perform the real
208 completion itself. The reason for this two step dance is that we
209 need to know the set of "brkchars" to use early on, before we
210 actually try to perform the completion. But if a Python command
211 supplies a "complete" method then we have to call that method
212 first: it may return as its result the kind of completion to
213 perform and that will in turn specify which brkchars to use. IOW,
214 we need the result of the "complete" method before we actually
215 perform the completion. The only situation when this function is
216 not called twice is when the user uses the "complete" command: in
217 this scenario, there is no call to determine the "brkchars".
219 Ideally, it would be nice to cache the result of the first call (to
220 determine the "brkchars") and return this value directly in the
221 second call (to perform the actual completion). However, due to
222 the peculiarity of the "complete" command mentioned above, it is
223 possible to put GDB in a bad state if you perform a TAB-completion
224 and then a "complete"-completion sequentially. Therefore, we just
225 recalculate everything twice for TAB-completions.
227 This function returns the PyObject representing the Python method
231 cmdpy_completer_helper (struct cmd_list_element
*command
,
232 const char *text
, const char *word
)
234 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
235 PyObject
*textobj
, *wordobj
;
239 error (_("Invalid invocation of Python command object."));
240 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
242 /* If there is no complete method, don't error. */
246 textobj
= PyUnicode_Decode (text
, strlen (text
), host_charset (), NULL
);
248 error (_("Could not convert argument to Python string."));
249 wordobj
= PyUnicode_Decode (word
, strlen (word
), host_charset (), NULL
);
253 error (_("Could not convert argument to Python string."));
256 resultobj
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, complete_cst
,
257 textobj
, wordobj
, NULL
);
262 /* Just swallow errors here. */
266 Py_XINCREF (resultobj
);
271 /* Python function called to determine the break characters of a
272 certain completer. We are only interested in knowing if the
273 completer registered by the user will return one of the integer
274 codes (see COMPLETER_* symbols). */
277 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
278 const char *text
, const char *word
)
280 PyObject
*resultobj
= NULL
;
282 gdbpy_enter
enter_py (get_current_arch (), current_language
);
284 /* Calling our helper to obtain the PyObject of the Python
286 resultobj
= cmdpy_completer_helper (command
, text
, word
);
288 /* Check if there was an error. */
289 if (resultobj
== NULL
)
292 if (PyInt_Check (resultobj
))
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
, &value
))
304 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
306 /* This is the core of this function. Depending on which
307 completer type the Python function returns, we have to
308 adjust the break characters accordingly. */
309 set_gdb_completion_word_break_characters
310 (completers
[value
].completer
);
316 Py_XDECREF (resultobj
);
319 /* Called by gdb for command completion. */
321 static VEC (char_ptr
) *
322 cmdpy_completer (struct cmd_list_element
*command
,
323 const char *text
, const char *word
)
325 PyObject
*resultobj
= NULL
;
326 VEC (char_ptr
) *result
= NULL
;
328 gdbpy_enter
enter_py (get_current_arch (), current_language
);
330 /* Calling our helper to obtain the PyObject of the Python
332 resultobj
= cmdpy_completer_helper (command
, text
, word
);
334 /* If the result object of calling the Python function is NULL, it
335 means that there was an error. In this case, just give up and
337 if (resultobj
== NULL
)
341 if (PyInt_Check (resultobj
))
343 /* User code may also return one of the completion constants,
344 thus requesting that sort of completion. */
347 if (! gdb_py_int_as_long (resultobj
, &value
))
352 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
353 result
= completers
[value
].completer (command
, text
, word
);
357 PyObject
*iter
= PyObject_GetIter (resultobj
);
363 while ((elt
= PyIter_Next (iter
)) != NULL
)
366 if (! gdbpy_is_string (elt
))
368 /* Skip problem elements. */
372 gdb::unique_xmalloc_ptr
<char>
373 item (python_string_to_host_string (elt
));
377 /* Skip problem elements. */
381 VEC_safe_push (char_ptr
, result
, item
.release ());
386 /* If we got some results, ignore problems. Otherwise, report
388 if (result
!= NULL
&& PyErr_Occurred ())
394 Py_XDECREF (resultobj
);
399 /* Helper for cmdpy_init which locates the command list to use and
400 pulls out the command name.
402 NAME is the command name list. The final word in the list is the
403 name of the new command. All earlier words must be existing prefix
406 *BASE_LIST is set to the final prefix command's list of
409 START_LIST is the list in which the search starts.
411 This function returns the xmalloc()d name of the new command. On
412 error sets the Python error and returns NULL. */
415 gdbpy_parse_command_name (const char *name
,
416 struct cmd_list_element
***base_list
,
417 struct cmd_list_element
**start_list
)
419 struct cmd_list_element
*elt
;
420 int len
= strlen (name
);
423 const char *prefix_text2
;
426 /* Skip trailing whitespace. */
427 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
431 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
436 /* Find first character of the final word. */
437 for (; i
> 0 && (isalnum (name
[i
- 1])
438 || name
[i
- 1] == '-'
439 || name
[i
- 1] == '_');
442 result
= (char *) xmalloc (lastchar
- i
+ 2);
443 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
444 result
[lastchar
- i
+ 1] = '\0';
446 /* Skip whitespace again. */
447 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
451 *base_list
= start_list
;
455 prefix_text
= (char *) xmalloc (i
+ 2);
456 memcpy (prefix_text
, name
, i
+ 1);
457 prefix_text
[i
+ 1] = '\0';
459 prefix_text2
= prefix_text
;
460 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
461 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
463 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
473 *base_list
= elt
->prefixlist
;
477 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
484 /* Object initializer; sets up gdb-side structures for command.
486 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
488 NAME is the name of the command. It may consist of multiple words,
489 in which case the final word is the name of the new command, and
490 earlier words must be prefix commands.
492 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
493 constants defined in the gdb module.
495 COMPLETER_CLASS is the kind of completer. If not given, the
496 "complete" method will be used. Otherwise, it should be one of the
497 COMPLETE_* constants defined in the gdb module.
499 If PREFIX is True, then this command is a prefix command.
501 The documentation for the command is taken from the doc string for
505 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
507 cmdpy_object
*obj
= (cmdpy_object
*) self
;
510 int completetype
= -1;
511 char *docstring
= NULL
;
512 struct cmd_list_element
**cmd_list
;
513 char *cmd_name
, *pfx_name
;
514 static char *keywords
[] = { "name", "command_class", "completer_class",
516 PyObject
*is_prefix
= NULL
;
521 /* Note: this is apparently not documented in Python. We return
522 0 for success, -1 for failure. */
523 PyErr_Format (PyExc_RuntimeError
,
524 _("Command object already initialized."));
528 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
529 keywords
, &name
, &cmdtype
,
530 &completetype
, &is_prefix
))
533 if (cmdtype
!= no_class
&& cmdtype
!= class_run
534 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
535 && cmdtype
!= class_files
&& cmdtype
!= class_support
536 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
537 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
538 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
540 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
544 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
546 PyErr_Format (PyExc_RuntimeError
,
547 _("Invalid completion type argument."));
551 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
556 if (is_prefix
!= NULL
)
558 cmp
= PyObject_IsTrue (is_prefix
);
563 /* Make a normalized form of the command name. */
564 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
570 /* Skip whitespace. */
571 while (name
[i
] == ' ' || name
[i
] == '\t')
573 /* Copy non-whitespace characters. */
574 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
575 pfx_name
[out
++] = name
[i
++];
576 /* Add a single space after each word -- including the final
578 pfx_name
[out
++] = ' ';
580 pfx_name
[out
] = '\0';
588 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
590 PyObject
*ds_obj
= PyObject_GetAttr (self
, gdbpy_doc_cst
);
592 if (ds_obj
&& gdbpy_is_string (ds_obj
))
594 docstring
= python_string_to_host_string (ds_obj
).release ();
595 if (docstring
== NULL
)
607 docstring
= xstrdup (_("This command is not documented."));
613 struct cmd_list_element
*cmd
;
619 /* If we have our own "invoke" method, then allow unknown
621 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
622 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
623 NULL
, docstring
, &obj
->sub_list
,
624 pfx_name
, allow_unknown
, cmd_list
);
627 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
, NULL
,
628 docstring
, cmd_list
);
630 /* There appears to be no API to set this. */
631 cmd
->func
= cmdpy_function
;
632 cmd
->destroyer
= cmdpy_destroyer
;
635 set_cmd_context (cmd
, self
);
636 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
637 : completers
[completetype
].completer
));
638 if (completetype
== -1)
639 set_cmd_completer_handle_brkchars (cmd
,
640 cmdpy_completer_handle_brkchars
);
642 CATCH (except
, RETURN_MASK_ALL
)
648 PyErr_Format (except
.reason
== RETURN_QUIT
649 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
650 "%s", except
.message
);
660 /* Initialize the 'commands' code. */
663 gdbpy_initialize_commands (void)
667 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
668 if (PyType_Ready (&cmdpy_object_type
) < 0)
671 /* Note: alias and user are special; pseudo appears to be unused,
672 and there is no reason to expose tui, I think. */
673 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
674 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
675 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
676 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
677 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
678 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
680 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
681 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
682 class_breakpoint
) < 0
683 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
685 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
687 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
688 class_maintenance
) < 0
689 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
692 for (i
= 0; i
< N_COMPLETERS
; ++i
)
694 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
698 if (gdb_pymodule_addobject (gdb_module
, "Command",
699 (PyObject
*) &cmdpy_object_type
) < 0)
702 invoke_cst
= PyString_FromString ("invoke");
703 if (invoke_cst
== NULL
)
705 complete_cst
= PyString_FromString ("complete");
706 if (complete_cst
== NULL
)
714 static PyMethodDef cmdpy_object_methods
[] =
716 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
717 "Prevent command repetition when user enters empty line." },
722 PyTypeObject cmdpy_object_type
=
724 PyVarObject_HEAD_INIT (NULL
, 0)
725 "gdb.Command", /*tp_name*/
726 sizeof (cmdpy_object
), /*tp_basicsize*/
735 0, /*tp_as_sequence*/
743 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
744 "GDB command object", /* tp_doc */
747 0, /* tp_richcompare */
748 0, /* tp_weaklistoffset */
751 cmdpy_object_methods
, /* tp_methods */
756 0, /* tp_descr_get */
757 0, /* tp_descr_set */
758 0, /* tp_dictoffset */
759 cmdpy_init
, /* tp_init */
765 /* Utility to build a buildargv-like result from ARGS.
766 This intentionally parses arguments the way libiberty/argv.c:buildargv
767 does. It splits up arguments in a reasonable way, and we want a standard
768 way of parsing arguments. Several gdb commands use buildargv to parse their
769 arguments. Plus we want to be able to write compatible python
770 implementations of gdb commands. */
773 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
777 if (!PyArg_ParseTuple (args
, "s", &input
))
780 gdbpy_ref
py_argv (PyList_New (0));
784 /* buildargv uses NULL to represent an empty argument list, but we can't use
785 that in Python. Instead, if ARGS is "" then return an empty list.
786 This undoes the NULL -> "" conversion that cmdpy_function does. */
790 char **c_argv
= gdb_buildargv (input
);
793 for (i
= 0; c_argv
[i
] != NULL
; ++i
)
795 gdbpy_ref
argp (PyString_FromString (c_argv
[i
]));
798 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
808 return py_argv
.release ();