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 const char *args
, int from_tty
)
115 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
117 gdbpy_enter
enter_py (get_current_arch (), current_language
);
120 error (_("Invalid invocation of Python command object."));
121 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
123 if (obj
->command
->prefixname
)
125 /* A prefix command does not need an invoke method. */
128 error (_("Python command object missing 'invoke' method."));
133 gdbpy_ref
<> argobj (PyUnicode_Decode (args
, strlen (args
), host_charset (),
137 gdbpy_print_stack ();
138 error (_("Could not convert arguments to Python string."));
141 gdbpy_ref
<> ttyobj (from_tty
? Py_True
: Py_False
);
142 Py_INCREF (ttyobj
.get ());
143 gdbpy_ref
<> result (PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
,
144 argobj
.get (), ttyobj
.get (),
149 PyObject
*ptype
, *pvalue
, *ptraceback
;
151 PyErr_Fetch (&ptype
, &pvalue
, &ptraceback
);
153 /* Try to fetch an error message contained within ptype, pvalue.
154 When fetching the error message we need to make our own copy,
155 we no longer own ptype, pvalue after the call to PyErr_Restore. */
157 gdb::unique_xmalloc_ptr
<char>
158 msg (gdbpy_exception_to_string (ptype
, pvalue
));
162 /* An error occurred computing the string representation of the
163 error message. This is rare, but we should inform the user. */
164 printf_filtered (_("An error occurred in a Python command\n"
165 "and then another occurred computing the "
166 "error message.\n"));
167 gdbpy_print_stack ();
170 /* Don't print the stack for gdb.GdbError exceptions.
171 It is generally used to flag user errors.
173 We also don't want to print "Error occurred in Python command"
174 for user errors. However, a missing message for gdb.GdbError
175 exceptions is arguably a bug, so we flag it as such. */
177 if (! PyErr_GivenExceptionMatches (ptype
, gdbpy_gdberror_exc
)
178 || msg
== NULL
|| *msg
== '\0')
180 PyErr_Restore (ptype
, pvalue
, ptraceback
);
181 gdbpy_print_stack ();
182 if (msg
!= NULL
&& *msg
!= '\0')
183 error (_("Error occurred in Python command: %s"), msg
.get ());
185 error (_("Error occurred in Python command."));
191 Py_XDECREF (ptraceback
);
192 error ("%s", msg
.get ());
197 /* Helper function for the Python command completers (both "pure"
198 completer and brkchar handler). This function takes COMMAND, TEXT
199 and WORD and tries to call the Python method for completion with
202 This function is usually called twice: once when we are figuring out
203 the break characters to be used, and another to perform the real
204 completion itself. The reason for this two step dance is that we
205 need to know the set of "brkchars" to use early on, before we
206 actually try to perform the completion. But if a Python command
207 supplies a "complete" method then we have to call that method
208 first: it may return as its result the kind of completion to
209 perform and that will in turn specify which brkchars to use. IOW,
210 we need the result of the "complete" method before we actually
211 perform the completion. The only situation when this function is
212 not called twice is when the user uses the "complete" command: in
213 this scenario, there is no call to determine the "brkchars".
215 Ideally, it would be nice to cache the result of the first call (to
216 determine the "brkchars") and return this value directly in the
217 second call (to perform the actual completion). However, due to
218 the peculiarity of the "complete" command mentioned above, it is
219 possible to put GDB in a bad state if you perform a TAB-completion
220 and then a "complete"-completion sequentially. Therefore, we just
221 recalculate everything twice for TAB-completions.
223 This function returns the PyObject representing the Python method
227 cmdpy_completer_helper (struct cmd_list_element
*command
,
228 const char *text
, const char *word
)
230 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
233 error (_("Invalid invocation of Python command object."));
234 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
236 /* If there is no complete method, don't error. */
240 gdbpy_ref
<> textobj (PyUnicode_Decode (text
, strlen (text
), host_charset (),
243 error (_("Could not convert argument to Python string."));
248 /* "brkchars" phase. */
249 wordobj
.reset (Py_None
);
254 wordobj
.reset (PyUnicode_Decode (word
, strlen (word
), host_charset (),
257 error (_("Could not convert argument to Python string."));
260 gdbpy_ref
<> resultobj (PyObject_CallMethodObjArgs ((PyObject
*) obj
,
263 wordobj
.get (), NULL
));
264 if (resultobj
== NULL
)
266 /* Just swallow errors here. */
270 return resultobj
.release ();
273 /* Python function called to determine the break characters of a
274 certain completer. We are only interested in knowing if the
275 completer registered by the user will return one of the integer
276 codes (see COMPLETER_* symbols). */
279 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
280 completion_tracker
&tracker
,
281 const char *text
, const char *word
)
283 gdbpy_enter
enter_py (get_current_arch (), current_language
);
285 /* Calling our helper to obtain the PyObject of the Python
287 gdbpy_ref
<> resultobj (cmdpy_completer_helper (command
, text
, word
));
289 /* Check if there was an error. */
290 if (resultobj
== NULL
)
293 if (PyInt_Check (resultobj
.get ()))
295 /* User code may also return one of the completion constants,
296 thus requesting that sort of completion. We are only
297 interested in this kind of return. */
300 if (!gdb_py_int_as_long (resultobj
.get (), &value
))
305 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
307 completer_handle_brkchars_ftype
*brkchars_fn
;
309 /* This is the core of this function. Depending on which
310 completer type the Python function returns, we have to
311 adjust the break characters accordingly. */
312 brkchars_fn
= (completer_handle_brkchars_func_for_completer
313 (completers
[value
].completer
));
314 brkchars_fn (command
, tracker
, text
, word
);
319 /* Called by gdb for command completion. */
322 cmdpy_completer (struct cmd_list_element
*command
,
323 completion_tracker
&tracker
,
324 const char *text
, const char *word
)
326 gdbpy_enter
enter_py (get_current_arch (), current_language
);
328 /* Calling our helper to obtain the PyObject of the Python
330 gdbpy_ref
<> resultobj (cmdpy_completer_helper (command
, text
, word
));
332 /* If the result object of calling the Python function is NULL, it
333 means that there was an error. In this case, just give up. */
334 if (resultobj
== NULL
)
337 if (PyInt_Check (resultobj
.get ()))
339 /* User code may also return one of the completion constants,
340 thus requesting that sort of completion. */
343 if (! gdb_py_int_as_long (resultobj
.get (), &value
))
348 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
349 completers
[value
].completer (command
, tracker
, text
, word
);
353 gdbpy_ref
<> iter (PyObject_GetIter (resultobj
.get ()));
358 bool got_matches
= false;
361 gdbpy_ref
<> elt (PyIter_Next (iter
.get ()));
365 if (! gdbpy_is_string (elt
.get ()))
367 /* Skip problem elements. */
370 gdb::unique_xmalloc_ptr
<char>
371 item (python_string_to_host_string (elt
.get ()));
374 /* Skip problem elements. */
378 tracker
.add_completion (std::move (item
));
382 /* If we got some results, ignore problems. Otherwise, report
384 if (got_matches
&& PyErr_Occurred ())
389 /* Helper for cmdpy_init which locates the command list to use and
390 pulls out the command name.
392 NAME is the command name list. The final word in the list is the
393 name of the new command. All earlier words must be existing prefix
396 *BASE_LIST is set to the final prefix command's list of
399 START_LIST is the list in which the search starts.
401 This function returns the xmalloc()d name of the new command. On
402 error sets the Python error and returns NULL. */
405 gdbpy_parse_command_name (const char *name
,
406 struct cmd_list_element
***base_list
,
407 struct cmd_list_element
**start_list
)
409 struct cmd_list_element
*elt
;
410 int len
= strlen (name
);
413 const char *prefix_text2
;
416 /* Skip trailing whitespace. */
417 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
421 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
426 /* Find first character of the final word. */
427 for (; i
> 0 && (isalnum (name
[i
- 1])
428 || name
[i
- 1] == '-'
429 || name
[i
- 1] == '_');
432 result
= (char *) xmalloc (lastchar
- i
+ 2);
433 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
434 result
[lastchar
- i
+ 1] = '\0';
436 /* Skip whitespace again. */
437 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
441 *base_list
= start_list
;
445 prefix_text
= (char *) xmalloc (i
+ 2);
446 memcpy (prefix_text
, name
, i
+ 1);
447 prefix_text
[i
+ 1] = '\0';
449 prefix_text2
= prefix_text
;
450 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
451 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
453 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
463 *base_list
= elt
->prefixlist
;
467 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
474 /* Object initializer; sets up gdb-side structures for command.
476 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
478 NAME is the name of the command. It may consist of multiple words,
479 in which case the final word is the name of the new command, and
480 earlier words must be prefix commands.
482 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
483 constants defined in the gdb module.
485 COMPLETER_CLASS is the kind of completer. If not given, the
486 "complete" method will be used. Otherwise, it should be one of the
487 COMPLETE_* constants defined in the gdb module.
489 If PREFIX is True, then this command is a prefix command.
491 The documentation for the command is taken from the doc string for
495 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
497 cmdpy_object
*obj
= (cmdpy_object
*) self
;
500 int completetype
= -1;
501 char *docstring
= NULL
;
502 struct cmd_list_element
**cmd_list
;
503 char *cmd_name
, *pfx_name
;
504 static const char *keywords
[] = { "name", "command_class", "completer_class",
506 PyObject
*is_prefix
= NULL
;
511 /* Note: this is apparently not documented in Python. We return
512 0 for success, -1 for failure. */
513 PyErr_Format (PyExc_RuntimeError
,
514 _("Command object already initialized."));
518 if (!gdb_PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
519 keywords
, &name
, &cmdtype
,
520 &completetype
, &is_prefix
))
523 if (cmdtype
!= no_class
&& cmdtype
!= class_run
524 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
525 && cmdtype
!= class_files
&& cmdtype
!= class_support
526 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
527 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
528 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
530 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
534 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
536 PyErr_Format (PyExc_RuntimeError
,
537 _("Invalid completion type argument."));
541 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
546 if (is_prefix
!= NULL
)
548 cmp
= PyObject_IsTrue (is_prefix
);
553 /* Make a normalized form of the command name. */
554 pfx_name
= (char *) xmalloc (strlen (name
) + 2);
560 /* Skip whitespace. */
561 while (name
[i
] == ' ' || name
[i
] == '\t')
563 /* Copy non-whitespace characters. */
564 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
565 pfx_name
[out
++] = name
[i
++];
566 /* Add a single space after each word -- including the final
568 pfx_name
[out
++] = ' ';
570 pfx_name
[out
] = '\0';
578 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
580 gdbpy_ref
<> ds_obj (PyObject_GetAttr (self
, gdbpy_doc_cst
));
582 if (ds_obj
!= NULL
&& gdbpy_is_string (ds_obj
.get ()))
584 docstring
= python_string_to_host_string (ds_obj
.get ()).release ();
585 if (docstring
== NULL
)
594 docstring
= xstrdup (_("This command is not documented."));
600 struct cmd_list_element
*cmd
;
606 /* If we have our own "invoke" method, then allow unknown
608 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
609 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
610 NULL
, docstring
, &obj
->sub_list
,
611 pfx_name
, allow_unknown
, cmd_list
);
614 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
,
615 docstring
, cmd_list
);
617 /* There appears to be no API to set this. */
618 cmd
->func
= cmdpy_function
;
619 cmd
->destroyer
= cmdpy_destroyer
;
622 set_cmd_context (cmd
, self
);
623 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
624 : completers
[completetype
].completer
));
625 if (completetype
== -1)
626 set_cmd_completer_handle_brkchars (cmd
,
627 cmdpy_completer_handle_brkchars
);
629 CATCH (except
, RETURN_MASK_ALL
)
635 PyErr_Format (except
.reason
== RETURN_QUIT
636 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
637 "%s", except
.message
);
647 /* Initialize the 'commands' code. */
650 gdbpy_initialize_commands (void)
654 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
655 if (PyType_Ready (&cmdpy_object_type
) < 0)
658 /* Note: alias and user are special; pseudo appears to be unused,
659 and there is no reason to expose tui, I think. */
660 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
661 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
662 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
663 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
664 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
665 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
667 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
668 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
669 class_breakpoint
) < 0
670 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
672 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
674 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
675 class_maintenance
) < 0
676 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
679 for (i
= 0; i
< N_COMPLETERS
; ++i
)
681 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
685 if (gdb_pymodule_addobject (gdb_module
, "Command",
686 (PyObject
*) &cmdpy_object_type
) < 0)
689 invoke_cst
= PyString_FromString ("invoke");
690 if (invoke_cst
== NULL
)
692 complete_cst
= PyString_FromString ("complete");
693 if (complete_cst
== NULL
)
701 static PyMethodDef cmdpy_object_methods
[] =
703 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
704 "Prevent command repetition when user enters empty line." },
709 PyTypeObject cmdpy_object_type
=
711 PyVarObject_HEAD_INIT (NULL
, 0)
712 "gdb.Command", /*tp_name*/
713 sizeof (cmdpy_object
), /*tp_basicsize*/
722 0, /*tp_as_sequence*/
730 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
731 "GDB command object", /* tp_doc */
734 0, /* tp_richcompare */
735 0, /* tp_weaklistoffset */
738 cmdpy_object_methods
, /* tp_methods */
743 0, /* tp_descr_get */
744 0, /* tp_descr_set */
745 0, /* tp_dictoffset */
746 cmdpy_init
, /* tp_init */
752 /* Utility to build a buildargv-like result from ARGS.
753 This intentionally parses arguments the way libiberty/argv.c:buildargv
754 does. It splits up arguments in a reasonable way, and we want a standard
755 way of parsing arguments. Several gdb commands use buildargv to parse their
756 arguments. Plus we want to be able to write compatible python
757 implementations of gdb commands. */
760 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
764 if (!PyArg_ParseTuple (args
, "s", &input
))
767 gdbpy_ref
<> py_argv (PyList_New (0));
771 /* buildargv uses NULL to represent an empty argument list, but we can't use
772 that in Python. Instead, if ARGS is "" then return an empty list.
773 This undoes the NULL -> "" conversion that cmdpy_function does. */
777 gdb_argv
c_argv (input
);
779 for (char *arg
: c_argv
)
781 gdbpy_ref
<> argp (PyString_FromString (arg
));
784 || PyList_Append (py_argv
.get (), argp
.get ()) < 0)
789 return py_argv
.release ();