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
);
237 error (_("Invalid invocation of Python command object."));
238 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
240 /* If there is no complete method, don't error. */
244 gdbpy_ref
textobj (PyUnicode_Decode (text
, strlen (text
), host_charset (),
247 error (_("Could not convert argument to Python string."));
248 gdbpy_ref
wordobj (PyUnicode_Decode (word
, strlen (word
), host_charset (),
251 error (_("Could not convert argument to Python string."));
253 gdbpy_ref
resultobj (PyObject_CallMethodObjArgs ((PyObject
*) obj
,
256 wordobj
.get (), NULL
));
257 if (resultobj
== NULL
)
259 /* Just swallow errors here. */
263 return resultobj
.release ();
266 /* Python function called to determine the break characters of a
267 certain completer. We are only interested in knowing if the
268 completer registered by the user will return one of the integer
269 codes (see COMPLETER_* symbols). */
272 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
273 const char *text
, const char *word
)
275 gdbpy_enter
enter_py (get_current_arch (), current_language
);
277 /* Calling our helper to obtain the PyObject of the Python
279 gdbpy_ref
resultobj (cmdpy_completer_helper (command
, text
, word
));
281 /* Check if there was an error. */
282 if (resultobj
== NULL
)
285 if (PyInt_Check (resultobj
.get ()))
287 /* User code may also return one of the completion constants,
288 thus requesting that sort of completion. We are only
289 interested in this kind of return. */
292 if (!gdb_py_int_as_long (resultobj
.get (), &value
))
297 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
299 /* This is the core of this function. Depending on which
300 completer type the Python function returns, we have to
301 adjust the break characters accordingly. */
302 set_gdb_completion_word_break_characters
303 (completers
[value
].completer
);
308 /* Called by gdb for command completion. */
310 static VEC (char_ptr
) *
311 cmdpy_completer (struct cmd_list_element
*command
,
312 const char *text
, const char *word
)
314 VEC (char_ptr
) *result
= NULL
;
316 gdbpy_enter
enter_py (get_current_arch (), current_language
);
318 /* Calling our helper to obtain the PyObject of the Python
320 gdbpy_ref
resultobj (cmdpy_completer_helper (command
, text
, word
));
322 /* If the result object of calling the Python function is NULL, it
323 means that there was an error. In this case, just give up and
325 if (resultobj
== NULL
)
329 if (PyInt_Check (resultobj
.get ()))
331 /* User code may also return one of the completion constants,
332 thus requesting that sort of completion. */
335 if (! gdb_py_int_as_long (resultobj
.get (), &value
))
340 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
341 result
= completers
[value
].completer (command
, text
, word
);
345 gdbpy_ref
iter (PyObject_GetIter (resultobj
.get ()));
352 gdbpy_ref
elt (PyIter_Next (iter
.get ()));
356 if (! gdbpy_is_string (elt
.get ()))
358 /* Skip problem elements. */
361 gdb::unique_xmalloc_ptr
<char>
362 item (python_string_to_host_string (elt
.get ()));
365 /* Skip problem elements. */
369 VEC_safe_push (char_ptr
, result
, item
.release ());
372 /* If we got some results, ignore problems. Otherwise, report
374 if (result
!= NULL
&& PyErr_Occurred ())
381 /* Helper for cmdpy_init which locates the command list to use and
382 pulls out the command name.
384 NAME is the command name list. The final word in the list is the
385 name of the new command. All earlier words must be existing prefix
388 *BASE_LIST is set to the final prefix command's list of
391 START_LIST is the list in which the search starts.
393 This function returns the xmalloc()d name of the new command. On
394 error sets the Python error and returns NULL. */
397 gdbpy_parse_command_name (const char *name
,
398 struct cmd_list_element
***base_list
,
399 struct cmd_list_element
**start_list
)
401 struct cmd_list_element
*elt
;
402 int len
= strlen (name
);
405 const char *prefix_text2
;
408 /* Skip trailing whitespace. */
409 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
413 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
418 /* Find first character of the final word. */
419 for (; i
> 0 && (isalnum (name
[i
- 1])
420 || name
[i
- 1] == '-'
421 || name
[i
- 1] == '_');
424 result
= (char *) xmalloc (lastchar
- i
+ 2);
425 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
426 result
[lastchar
- i
+ 1] = '\0';
428 /* Skip whitespace again. */
429 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
433 *base_list
= start_list
;
437 prefix_text
= (char *) xmalloc (i
+ 2);
438 memcpy (prefix_text
, name
, i
+ 1);
439 prefix_text
[i
+ 1] = '\0';
441 prefix_text2
= prefix_text
;
442 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
443 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
445 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
455 *base_list
= elt
->prefixlist
;
459 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
466 /* Object initializer; sets up gdb-side structures for command.
468 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
470 NAME is the name of the command. It may consist of multiple words,
471 in which case the final word is the name of the new command, and
472 earlier words must be prefix commands.
474 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
475 constants defined in the gdb module.
477 COMPLETER_CLASS is the kind of completer. If not given, the
478 "complete" method will be used. Otherwise, it should be one of the
479 COMPLETE_* constants defined in the gdb module.
481 If PREFIX is True, then this command is a prefix command.
483 The documentation for the command is taken from the doc string for
487 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
489 cmdpy_object
*obj
= (cmdpy_object
*) self
;
492 int completetype
= -1;
493 char *docstring
= NULL
;
494 struct cmd_list_element
**cmd_list
;
495 char *cmd_name
, *pfx_name
;
496 static char *keywords
[] = { "name", "command_class", "completer_class",
498 PyObject
*is_prefix
= NULL
;
503 /* Note: this is apparently not documented in Python. We return
504 0 for success, -1 for failure. */
505 PyErr_Format (PyExc_RuntimeError
,
506 _("Command object already initialized."));
510 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
511 keywords
, &name
, &cmdtype
,
512 &completetype
, &is_prefix
))
515 if (cmdtype
!= no_class
&& cmdtype
!= class_run
516 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
517 && cmdtype
!= class_files
&& cmdtype
!= class_support
518 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
519 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
520 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
522 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
526 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
528 PyErr_Format (PyExc_RuntimeError
,
529 _("Invalid completion type argument."));
533 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
538 if (is_prefix
!= NULL
)
540 cmp
= PyObject_IsTrue (is_prefix
);
545 /* Make a normalized form of the command name. */
546 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
552 /* Skip whitespace. */
553 while (name
[i
] == ' ' || name
[i
] == '\t')
555 /* Copy non-whitespace characters. */
556 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
557 pfx_name
[out
++] = name
[i
++];
558 /* Add a single space after each word -- including the final
560 pfx_name
[out
++] = ' ';
562 pfx_name
[out
] = '\0';
570 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
572 gdbpy_ref
ds_obj (PyObject_GetAttr (self
, gdbpy_doc_cst
));
574 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
576 docstring
= python_string_to_host_string (ds_obj
.get ()).release ();
577 if (docstring
== NULL
)
586 docstring
= xstrdup (_("This command is not documented."));
592 struct cmd_list_element
*cmd
;
598 /* If we have our own "invoke" method, then allow unknown
600 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
601 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
602 NULL
, docstring
, &obj
->sub_list
,
603 pfx_name
, allow_unknown
, cmd_list
);
606 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
, NULL
,
607 docstring
, cmd_list
);
609 /* There appears to be no API to set this. */
610 cmd
->func
= cmdpy_function
;
611 cmd
->destroyer
= cmdpy_destroyer
;
614 set_cmd_context (cmd
, self
);
615 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
616 : completers
[completetype
].completer
));
617 if (completetype
== -1)
618 set_cmd_completer_handle_brkchars (cmd
,
619 cmdpy_completer_handle_brkchars
);
621 CATCH (except
, RETURN_MASK_ALL
)
627 PyErr_Format (except
.reason
== RETURN_QUIT
628 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
629 "%s", except
.message
);
639 /* Initialize the 'commands' code. */
642 gdbpy_initialize_commands (void)
646 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
647 if (PyType_Ready (&cmdpy_object_type
) < 0)
650 /* Note: alias and user are special; pseudo appears to be unused,
651 and there is no reason to expose tui, I think. */
652 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
653 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
654 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
655 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
656 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
657 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
659 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
660 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
661 class_breakpoint
) < 0
662 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
664 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
666 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
667 class_maintenance
) < 0
668 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
671 for (i
= 0; i
< N_COMPLETERS
; ++i
)
673 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
677 if (gdb_pymodule_addobject (gdb_module
, "Command",
678 (PyObject
*) &cmdpy_object_type
) < 0)
681 invoke_cst
= PyString_FromString ("invoke");
682 if (invoke_cst
== NULL
)
684 complete_cst
= PyString_FromString ("complete");
685 if (complete_cst
== NULL
)
693 static PyMethodDef cmdpy_object_methods
[] =
695 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
696 "Prevent command repetition when user enters empty line." },
701 PyTypeObject cmdpy_object_type
=
703 PyVarObject_HEAD_INIT (NULL
, 0)
704 "gdb.Command", /*tp_name*/
705 sizeof (cmdpy_object
), /*tp_basicsize*/
714 0, /*tp_as_sequence*/
722 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
723 "GDB command object", /* tp_doc */
726 0, /* tp_richcompare */
727 0, /* tp_weaklistoffset */
730 cmdpy_object_methods
, /* tp_methods */
735 0, /* tp_descr_get */
736 0, /* tp_descr_set */
737 0, /* tp_dictoffset */
738 cmdpy_init
, /* tp_init */
744 /* Utility to build a buildargv-like result from ARGS.
745 This intentionally parses arguments the way libiberty/argv.c:buildargv
746 does. It splits up arguments in a reasonable way, and we want a standard
747 way of parsing arguments. Several gdb commands use buildargv to parse their
748 arguments. Plus we want to be able to write compatible python
749 implementations of gdb commands. */
752 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
756 if (!PyArg_ParseTuple (args
, "s", &input
))
759 gdbpy_ref
py_argv (PyList_New (0));
763 /* buildargv uses NULL to represent an empty argument list, but we can't use
764 that in Python. Instead, if ARGS is "" then return an empty list.
765 This undoes the NULL -> "" conversion that cmdpy_function does. */
769 char **c_argv
= gdb_buildargv (input
);
772 for (i
= 0; c_argv
[i
] != NULL
; ++i
)
774 gdbpy_ref
argp (PyString_FromString (c_argv
[i
]));
777 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
787 return py_argv
.release ();