1 /* gdb commands implemented in Python
3 Copyright (C) 2008-2015 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"
31 /* Struct representing built-in completion types. */
32 struct cmdpy_completer
34 /* Python symbol name.
35 This isn't a const char * for Python 2.4's sake.
36 PyModule_AddIntConstant only takes a char *, sigh. */
38 /* Completion function. */
39 completer_ftype
*completer
;
42 static const struct cmdpy_completer completers
[] =
44 { "COMPLETE_NONE", noop_completer
},
45 { "COMPLETE_FILENAME", filename_completer
},
46 { "COMPLETE_LOCATION", location_completer
},
47 { "COMPLETE_COMMAND", command_completer
},
48 { "COMPLETE_SYMBOL", make_symbol_completion_list_fn
},
49 { "COMPLETE_EXPRESSION", expression_completer
},
52 #define N_COMPLETERS (sizeof (completers) / sizeof (completers[0]))
54 /* A gdb command. For the time being only ordinary commands (not
55 set/show commands) are allowed. */
60 /* The corresponding gdb command object, or NULL if the command is
61 no longer installed. */
62 struct cmd_list_element
*command
;
64 /* A prefix command requires storage for a list of its sub-commands.
65 A pointer to this is passed to add_prefix_command, and to add_cmd
66 for sub-commands of that prefix. If this Command is not a prefix
67 command, then this field is unused. */
68 struct cmd_list_element
*sub_list
;
71 typedef struct cmdpy_object cmdpy_object
;
73 extern PyTypeObject cmdpy_object_type
74 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("cmdpy_object");
76 /* Constants used by this module. */
77 static PyObject
*invoke_cst
;
78 static PyObject
*complete_cst
;
82 /* Python function which wraps dont_repeat. */
84 cmdpy_dont_repeat (PyObject
*self
, PyObject
*args
)
92 /* Called if the gdb cmd_list_element is destroyed. */
95 cmdpy_destroyer (struct cmd_list_element
*self
, void *context
)
98 struct cleanup
*cleanup
;
100 cleanup
= ensure_python_env (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
);
113 do_cleanups (cleanup
);
116 /* Called by gdb to invoke the command. */
119 cmdpy_function (struct cmd_list_element
*command
, char *args
, int from_tty
)
121 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
122 PyObject
*argobj
, *ttyobj
, *result
;
123 struct cleanup
*cleanup
;
125 cleanup
= ensure_python_env (get_current_arch (), current_language
);
128 error (_("Invalid invocation of Python command object."));
129 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
131 if (obj
->command
->prefixname
)
133 /* A prefix command does not need an invoke method. */
134 do_cleanups (cleanup
);
137 error (_("Python command object missing 'invoke' method."));
142 argobj
= PyUnicode_Decode (args
, strlen (args
), host_charset (), NULL
);
145 gdbpy_print_stack ();
146 error (_("Could not convert arguments to Python string."));
149 ttyobj
= from_tty
? Py_True
: Py_False
;
151 result
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
, argobj
,
158 PyObject
*ptype
, *pvalue
, *ptraceback
;
161 PyErr_Fetch (&ptype
, &pvalue
, &ptraceback
);
163 /* Try to fetch an error message contained within ptype, pvalue.
164 When fetching the error message we need to make our own copy,
165 we no longer own ptype, pvalue after the call to PyErr_Restore. */
167 msg
= gdbpy_exception_to_string (ptype
, pvalue
);
168 make_cleanup (xfree
, msg
);
172 /* An error occurred computing the string representation of the
173 error message. This is rare, but we should inform the user. */
174 printf_filtered (_("An error occurred in a Python command\n"
175 "and then another occurred computing the "
176 "error message.\n"));
177 gdbpy_print_stack ();
180 /* Don't print the stack for gdb.GdbError exceptions.
181 It is generally used to flag user errors.
183 We also don't want to print "Error occurred in Python command"
184 for user errors. However, a missing message for gdb.GdbError
185 exceptions is arguably a bug, so we flag it as such. */
187 if (! PyErr_GivenExceptionMatches (ptype
, gdbpy_gdberror_exc
)
188 || msg
== NULL
|| *msg
== '\0')
190 PyErr_Restore (ptype
, pvalue
, ptraceback
);
191 gdbpy_print_stack ();
192 if (msg
!= NULL
&& *msg
!= '\0')
193 error (_("Error occurred in Python command: %s"), msg
);
195 error (_("Error occurred in Python command."));
201 Py_XDECREF (ptraceback
);
207 do_cleanups (cleanup
);
210 /* Helper function for the Python command completers (both "pure"
211 completer and brkchar handler). This function takes COMMAND, TEXT
212 and WORD and tries to call the Python method for completion with
213 these arguments. It also takes HANDLE_BRKCHARS_P, an argument to
214 identify whether it is being called from the brkchar handler or
215 from the "pure" completer. In the first case, it effectively calls
216 the Python method for completion, and records the PyObject in a
217 static variable (used as a "cache"). In the second case, it just
218 returns that variable, without actually calling the Python method
219 again. This saves us one Python method call.
221 The reason for this two step dance is that we need to know the set
222 of "brkchars" to use early on, before we actually try to perform
223 the completion. But if a Python command supplies a "complete"
224 method then we have to call that method first: it may return as its
225 result the kind of completion to perform and that will in turn
226 specify which brkchars to use. IOW, we need the result of the
227 "complete" method before we actually perform the completion.
229 It is important to mention that this function is built on the
230 assumption that the calls to cmdpy_completer_handle_brkchars and
231 cmdpy_completer will be subsequent with nothing intervening. This
232 is true for our completer mechanism.
234 This function returns the PyObject representing the Python method
238 cmdpy_completer_helper (struct cmd_list_element
*command
,
239 const char *text
, const char *word
,
240 int handle_brkchars_p
)
242 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
243 PyObject
*textobj
, *wordobj
;
244 /* This static variable will server as a "cache" for us, in order to
245 store the PyObject that results from calling the Python
247 static PyObject
*resultobj
= NULL
;
249 if (handle_brkchars_p
)
251 /* If we were called to handle brkchars, it means this is the
252 first function call of two that will happen in a row.
253 Therefore, we need to call the completer ourselves, and cache
254 the return value in the static variable RESULTOBJ. Then, in
255 the second call, we can just use the value of RESULTOBJ to do
257 if (resultobj
!= NULL
)
258 Py_DECREF (resultobj
);
262 error (_("Invalid invocation of Python command object."));
263 if (!PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
265 /* If there is no complete method, don't error. */
269 textobj
= PyUnicode_Decode (text
, strlen (text
), host_charset (), NULL
);
271 error (_("Could not convert argument to Python string."));
272 wordobj
= PyUnicode_Decode (word
, sizeof (word
), host_charset (), NULL
);
276 error (_("Could not convert argument to Python string."));
279 resultobj
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, complete_cst
,
280 textobj
, wordobj
, NULL
);
285 /* Just swallow errors here. */
289 Py_XINCREF (resultobj
);
295 /* Python function called to determine the break characters of a
296 certain completer. We are only interested in knowing if the
297 completer registered by the user will return one of the integer
298 codes (see COMPLETER_* symbols). */
301 cmdpy_completer_handle_brkchars (struct cmd_list_element
*command
,
302 const char *text
, const char *word
)
304 PyObject
*resultobj
= NULL
;
305 struct cleanup
*cleanup
;
307 cleanup
= ensure_python_env (get_current_arch (), current_language
);
309 /* Calling our helper to obtain the PyObject of the Python
311 resultobj
= cmdpy_completer_helper (command
, text
, word
, 1);
313 /* Check if there was an error. */
314 if (resultobj
== NULL
)
317 if (PyInt_Check (resultobj
))
319 /* User code may also return one of the completion constants,
320 thus requesting that sort of completion. We are only
321 interested in this kind of return. */
324 if (!gdb_py_int_as_long (resultobj
, &value
))
329 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
331 /* This is the core of this function. Depending on which
332 completer type the Python function returns, we have to
333 adjust the break characters accordingly. */
334 set_gdb_completion_word_break_characters
335 (completers
[value
].completer
);
341 /* We do not call Py_XDECREF here because RESULTOBJ will be used in
342 the subsequent call to cmdpy_completer function. */
343 do_cleanups (cleanup
);
346 /* Called by gdb for command completion. */
348 static VEC (char_ptr
) *
349 cmdpy_completer (struct cmd_list_element
*command
,
350 const char *text
, const char *word
)
352 PyObject
*resultobj
= NULL
;
353 VEC (char_ptr
) *result
= NULL
;
354 struct cleanup
*cleanup
;
356 cleanup
= ensure_python_env (get_current_arch (), current_language
);
358 /* Calling our helper to obtain the PyObject of the Python
360 resultobj
= cmdpy_completer_helper (command
, text
, word
, 0);
362 /* If the result object of calling the Python function is NULL, it
363 means that there was an error. In this case, just give up and
365 if (resultobj
== NULL
)
369 if (PyInt_Check (resultobj
))
371 /* User code may also return one of the completion constants,
372 thus requesting that sort of completion. */
375 if (! gdb_py_int_as_long (resultobj
, &value
))
380 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
381 result
= completers
[value
].completer (command
, text
, word
);
385 PyObject
*iter
= PyObject_GetIter (resultobj
);
391 while ((elt
= PyIter_Next (iter
)) != NULL
)
395 if (! gdbpy_is_string (elt
))
397 /* Skip problem elements. */
401 item
= python_string_to_host_string (elt
);
405 /* Skip problem elements. */
409 VEC_safe_push (char_ptr
, result
, item
);
414 /* If we got some results, ignore problems. Otherwise, report
416 if (result
!= NULL
&& PyErr_Occurred ())
422 do_cleanups (cleanup
);
427 /* Helper for cmdpy_init which locates the command list to use and
428 pulls out the command name.
430 NAME is the command name list. The final word in the list is the
431 name of the new command. All earlier words must be existing prefix
434 *BASE_LIST is set to the final prefix command's list of
437 START_LIST is the list in which the search starts.
439 This function returns the xmalloc()d name of the new command. On
440 error sets the Python error and returns NULL. */
443 gdbpy_parse_command_name (const char *name
,
444 struct cmd_list_element
***base_list
,
445 struct cmd_list_element
**start_list
)
447 struct cmd_list_element
*elt
;
448 int len
= strlen (name
);
451 const char *prefix_text2
;
454 /* Skip trailing whitespace. */
455 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
459 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
464 /* Find first character of the final word. */
465 for (; i
> 0 && (isalnum (name
[i
- 1])
466 || name
[i
- 1] == '-'
467 || name
[i
- 1] == '_');
470 result
= xmalloc (lastchar
- i
+ 2);
471 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
472 result
[lastchar
- i
+ 1] = '\0';
474 /* Skip whitespace again. */
475 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
479 *base_list
= start_list
;
483 prefix_text
= xmalloc (i
+ 2);
484 memcpy (prefix_text
, name
, i
+ 1);
485 prefix_text
[i
+ 1] = '\0';
487 prefix_text2
= prefix_text
;
488 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
489 if (elt
== NULL
|| elt
== CMD_LIST_AMBIGUOUS
)
491 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
501 *base_list
= elt
->prefixlist
;
505 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
512 /* Object initializer; sets up gdb-side structures for command.
514 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
516 NAME is the name of the command. It may consist of multiple words,
517 in which case the final word is the name of the new command, and
518 earlier words must be prefix commands.
520 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
521 constants defined in the gdb module.
523 COMPLETER_CLASS is the kind of completer. If not given, the
524 "complete" method will be used. Otherwise, it should be one of the
525 COMPLETE_* constants defined in the gdb module.
527 If PREFIX is True, then this command is a prefix command.
529 The documentation for the command is taken from the doc string for
533 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
535 cmdpy_object
*obj
= (cmdpy_object
*) self
;
538 int completetype
= -1;
539 char *docstring
= NULL
;
540 volatile struct gdb_exception except
;
541 struct cmd_list_element
**cmd_list
;
542 char *cmd_name
, *pfx_name
;
543 static char *keywords
[] = { "name", "command_class", "completer_class",
545 PyObject
*is_prefix
= NULL
;
550 /* Note: this is apparently not documented in Python. We return
551 0 for success, -1 for failure. */
552 PyErr_Format (PyExc_RuntimeError
,
553 _("Command object already initialized."));
557 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
558 keywords
, &name
, &cmdtype
,
559 &completetype
, &is_prefix
))
562 if (cmdtype
!= no_class
&& cmdtype
!= class_run
563 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
564 && cmdtype
!= class_files
&& cmdtype
!= class_support
565 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
566 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
567 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
569 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
573 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
575 PyErr_Format (PyExc_RuntimeError
,
576 _("Invalid completion type argument."));
580 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
585 if (is_prefix
!= NULL
)
587 cmp
= PyObject_IsTrue (is_prefix
);
592 /* Make a normalized form of the command name. */
593 pfx_name
= xmalloc (strlen (name
) + 2);
599 /* Skip whitespace. */
600 while (name
[i
] == ' ' || name
[i
] == '\t')
602 /* Copy non-whitespace characters. */
603 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
604 pfx_name
[out
++] = name
[i
++];
605 /* Add a single space after each word -- including the final
607 pfx_name
[out
++] = ' ';
609 pfx_name
[out
] = '\0';
617 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
619 PyObject
*ds_obj
= PyObject_GetAttr (self
, gdbpy_doc_cst
);
621 if (ds_obj
&& gdbpy_is_string (ds_obj
))
623 docstring
= python_string_to_host_string (ds_obj
);
624 if (docstring
== NULL
)
636 docstring
= xstrdup (_("This command is not documented."));
640 TRY_CATCH (except
, RETURN_MASK_ALL
)
642 struct cmd_list_element
*cmd
;
648 /* If we have our own "invoke" method, then allow unknown
650 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
651 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
652 NULL
, docstring
, &obj
->sub_list
,
653 pfx_name
, allow_unknown
, cmd_list
);
656 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
, NULL
,
657 docstring
, cmd_list
);
659 /* There appears to be no API to set this. */
660 cmd
->func
= cmdpy_function
;
661 cmd
->destroyer
= cmdpy_destroyer
;
664 set_cmd_context (cmd
, self
);
665 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
666 : completers
[completetype
].completer
));
667 if (completetype
== -1)
668 set_cmd_completer_handle_brkchars (cmd
,
669 cmdpy_completer_handle_brkchars
);
671 if (except
.reason
< 0)
677 PyErr_Format (except
.reason
== RETURN_QUIT
678 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
679 "%s", except
.message
);
687 /* Initialize the 'commands' code. */
690 gdbpy_initialize_commands (void)
694 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
695 if (PyType_Ready (&cmdpy_object_type
) < 0)
698 /* Note: alias and user are special; pseudo appears to be unused,
699 and there is no reason to expose tui or xdb, I think. */
700 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
701 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
702 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
703 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
704 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
705 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
707 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
708 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
709 class_breakpoint
) < 0
710 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
712 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
714 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
715 class_maintenance
) < 0
716 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
719 for (i
= 0; i
< N_COMPLETERS
; ++i
)
721 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
725 if (gdb_pymodule_addobject (gdb_module
, "Command",
726 (PyObject
*) &cmdpy_object_type
) < 0)
729 invoke_cst
= PyString_FromString ("invoke");
730 if (invoke_cst
== NULL
)
732 complete_cst
= PyString_FromString ("complete");
733 if (complete_cst
== NULL
)
741 static PyMethodDef cmdpy_object_methods
[] =
743 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
744 "Prevent command repetition when user enters empty line." },
749 PyTypeObject cmdpy_object_type
=
751 PyVarObject_HEAD_INIT (NULL
, 0)
752 "gdb.Command", /*tp_name*/
753 sizeof (cmdpy_object
), /*tp_basicsize*/
762 0, /*tp_as_sequence*/
770 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
771 "GDB command object", /* tp_doc */
774 0, /* tp_richcompare */
775 0, /* tp_weaklistoffset */
778 cmdpy_object_methods
, /* tp_methods */
783 0, /* tp_descr_get */
784 0, /* tp_descr_set */
785 0, /* tp_dictoffset */
786 cmdpy_init
, /* tp_init */
792 /* Utility to build a buildargv-like result from ARGS.
793 This intentionally parses arguments the way libiberty/argv.c:buildargv
794 does. It splits up arguments in a reasonable way, and we want a standard
795 way of parsing arguments. Several gdb commands use buildargv to parse their
796 arguments. Plus we want to be able to write compatible python
797 implementations of gdb commands. */
800 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
805 if (!PyArg_ParseTuple (args
, "s", &input
))
808 py_argv
= PyList_New (0);
812 /* buildargv uses NULL to represent an empty argument list, but we can't use
813 that in Python. Instead, if ARGS is "" then return an empty list.
814 This undoes the NULL -> "" conversion that cmdpy_function does. */
818 char **c_argv
= gdb_buildargv (input
);
821 for (i
= 0; c_argv
[i
] != NULL
; ++i
)
823 PyObject
*argp
= PyString_FromString (c_argv
[i
]);
826 || PyList_Append (py_argv
, argp
) < 0)