1 /* gdb commands implemented in Python
3 Copyright (C) 2008-2014 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 "exceptions.h"
25 #include "python-internal.h"
28 #include "cli/cli-decode.h"
29 #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 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", make_symbol_completion_list_fn
},
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 static 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
)
97 struct cleanup
*cleanup
;
99 cleanup
= ensure_python_env (get_current_arch (), current_language
);
101 /* Release our hold on the command object. */
102 cmd
= (cmdpy_object
*) context
;
106 /* We allocated the name, doc string, and perhaps the prefix
108 xfree ((char *) self
->name
);
110 xfree (self
->prefixname
);
112 do_cleanups (cleanup
);
115 /* Called by gdb to invoke the command. */
118 cmdpy_function (struct cmd_list_element
*command
, char *args
, int from_tty
)
120 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
121 PyObject
*argobj
, *ttyobj
, *result
;
122 struct cleanup
*cleanup
;
124 cleanup
= ensure_python_env (get_current_arch (), current_language
);
127 error (_("Invalid invocation of Python command object."));
128 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
130 if (obj
->command
->prefixname
)
132 /* A prefix command does not need an invoke method. */
133 do_cleanups (cleanup
);
136 error (_("Python command object missing 'invoke' method."));
141 argobj
= PyUnicode_Decode (args
, strlen (args
), host_charset (), NULL
);
144 gdbpy_print_stack ();
145 error (_("Could not convert arguments to Python string."));
148 ttyobj
= from_tty
? Py_True
: Py_False
;
150 result
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
, argobj
,
157 PyObject
*ptype
, *pvalue
, *ptraceback
;
160 PyErr_Fetch (&ptype
, &pvalue
, &ptraceback
);
162 /* Try to fetch an error message contained within ptype, pvalue.
163 When fetching the error message we need to make our own copy,
164 we no longer own ptype, pvalue after the call to PyErr_Restore. */
166 msg
= gdbpy_exception_to_string (ptype
, pvalue
);
167 make_cleanup (xfree
, msg
);
171 /* An error occurred computing the string representation of the
172 error message. This is rare, but we should inform the user. */
173 printf_filtered (_("An error occurred in a Python command\n"
174 "and then another occurred computing the "
175 "error message.\n"));
176 gdbpy_print_stack ();
179 /* Don't print the stack for gdb.GdbError exceptions.
180 It is generally used to flag user errors.
182 We also don't want to print "Error occurred in Python command"
183 for user errors. However, a missing message for gdb.GdbError
184 exceptions is arguably a bug, so we flag it as such. */
186 if (! PyErr_GivenExceptionMatches (ptype
, gdbpy_gdberror_exc
)
187 || msg
== NULL
|| *msg
== '\0')
189 PyErr_Restore (ptype
, pvalue
, ptraceback
);
190 gdbpy_print_stack ();
191 if (msg
!= NULL
&& *msg
!= '\0')
192 error (_("Error occurred in Python command: %s"), msg
);
194 error (_("Error occurred in Python command."));
200 Py_XDECREF (ptraceback
);
206 do_cleanups (cleanup
);
209 /* Called by gdb for command completion. */
211 static VEC (char_ptr
) *
212 cmdpy_completer (struct cmd_list_element
*command
,
213 const char *text
, const char *word
)
215 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
216 PyObject
*textobj
, *wordobj
, *resultobj
= NULL
;
217 VEC (char_ptr
) *result
= NULL
;
218 struct cleanup
*cleanup
;
220 cleanup
= ensure_python_env (get_current_arch (), current_language
);
223 error (_("Invalid invocation of Python command object."));
224 if (! PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
226 /* If there is no complete method, don't error -- instead, just
227 say that there are no completions. */
231 textobj
= PyUnicode_Decode (text
, strlen (text
), host_charset (), NULL
);
233 error (_("Could not convert argument to Python string."));
234 wordobj
= PyUnicode_Decode (word
, strlen (word
), host_charset (), NULL
);
236 error (_("Could not convert argument to Python string."));
238 resultobj
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, complete_cst
,
239 textobj
, wordobj
, NULL
);
244 /* Just swallow errors here. */
250 if (PyInt_Check (resultobj
))
252 /* User code may also return one of the completion constants,
253 thus requesting that sort of completion. */
256 if (! gdb_py_int_as_long (resultobj
, &value
))
261 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
262 result
= completers
[value
].completer (command
, text
, word
);
266 PyObject
*iter
= PyObject_GetIter (resultobj
);
272 while ((elt
= PyIter_Next (iter
)) != NULL
)
276 if (! gdbpy_is_string (elt
))
278 /* Skip problem elements. */
282 item
= python_string_to_host_string (elt
);
286 /* Skip problem elements. */
290 VEC_safe_push (char_ptr
, result
, item
);
295 /* If we got some results, ignore problems. Otherwise, report
297 if (result
!= NULL
&& PyErr_Occurred ())
303 Py_XDECREF (resultobj
);
304 do_cleanups (cleanup
);
309 /* Helper for cmdpy_init which locates the command list to use and
310 pulls out the command name.
312 NAME is the command name list. The final word in the list is the
313 name of the new command. All earlier words must be existing prefix
316 *BASE_LIST is set to the final prefix command's list of
319 START_LIST is the list in which the search starts.
321 This function returns the xmalloc()d name of the new command. On
322 error sets the Python error and returns NULL. */
325 gdbpy_parse_command_name (const char *name
,
326 struct cmd_list_element
***base_list
,
327 struct cmd_list_element
**start_list
)
329 struct cmd_list_element
*elt
;
330 int len
= strlen (name
);
333 const char *prefix_text2
;
336 /* Skip trailing whitespace. */
337 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
341 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
346 /* Find first character of the final word. */
347 for (; i
> 0 && (isalnum (name
[i
- 1])
348 || name
[i
- 1] == '-'
349 || name
[i
- 1] == '_');
352 result
= xmalloc (lastchar
- i
+ 2);
353 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
354 result
[lastchar
- i
+ 1] = '\0';
356 /* Skip whitespace again. */
357 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
361 *base_list
= start_list
;
365 prefix_text
= xmalloc (i
+ 2);
366 memcpy (prefix_text
, name
, i
+ 1);
367 prefix_text
[i
+ 1] = '\0';
369 prefix_text2
= prefix_text
;
370 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
371 if (!elt
|| elt
== (struct cmd_list_element
*) -1)
373 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
383 *base_list
= elt
->prefixlist
;
387 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
394 /* Object initializer; sets up gdb-side structures for command.
396 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
398 NAME is the name of the command. It may consist of multiple words,
399 in which case the final word is the name of the new command, and
400 earlier words must be prefix commands.
402 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
403 constants defined in the gdb module.
405 COMPLETER_CLASS is the kind of completer. If not given, the
406 "complete" method will be used. Otherwise, it should be one of the
407 COMPLETE_* constants defined in the gdb module.
409 If PREFIX is True, then this command is a prefix command.
411 The documentation for the command is taken from the doc string for
415 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
417 cmdpy_object
*obj
= (cmdpy_object
*) self
;
420 int completetype
= -1;
421 char *docstring
= NULL
;
422 volatile struct gdb_exception except
;
423 struct cmd_list_element
**cmd_list
;
424 char *cmd_name
, *pfx_name
;
425 static char *keywords
[] = { "name", "command_class", "completer_class",
427 PyObject
*is_prefix
= NULL
;
432 /* Note: this is apparently not documented in Python. We return
433 0 for success, -1 for failure. */
434 PyErr_Format (PyExc_RuntimeError
,
435 _("Command object already initialized."));
439 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
440 keywords
, &name
, &cmdtype
,
441 &completetype
, &is_prefix
))
444 if (cmdtype
!= no_class
&& cmdtype
!= class_run
445 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
446 && cmdtype
!= class_files
&& cmdtype
!= class_support
447 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
448 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
449 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
451 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
455 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
457 PyErr_Format (PyExc_RuntimeError
,
458 _("Invalid completion type argument."));
462 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
467 if (is_prefix
!= NULL
)
469 cmp
= PyObject_IsTrue (is_prefix
);
474 /* Make a normalized form of the command name. */
475 pfx_name
= xmalloc (strlen (name
) + 2);
481 /* Skip whitespace. */
482 while (name
[i
] == ' ' || name
[i
] == '\t')
484 /* Copy non-whitespace characters. */
485 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
486 pfx_name
[out
++] = name
[i
++];
487 /* Add a single space after each word -- including the final
489 pfx_name
[out
++] = ' ';
491 pfx_name
[out
] = '\0';
499 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
501 PyObject
*ds_obj
= PyObject_GetAttr (self
, gdbpy_doc_cst
);
503 if (ds_obj
&& gdbpy_is_string (ds_obj
))
505 docstring
= python_string_to_host_string (ds_obj
);
506 if (docstring
== NULL
)
518 docstring
= xstrdup (_("This command is not documented."));
522 TRY_CATCH (except
, RETURN_MASK_ALL
)
524 struct cmd_list_element
*cmd
;
530 /* If we have our own "invoke" method, then allow unknown
532 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
533 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
534 NULL
, docstring
, &obj
->sub_list
,
535 pfx_name
, allow_unknown
, cmd_list
);
538 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
, NULL
,
539 docstring
, cmd_list
);
541 /* There appears to be no API to set this. */
542 cmd
->func
= cmdpy_function
;
543 cmd
->destroyer
= cmdpy_destroyer
;
546 set_cmd_context (cmd
, self
);
547 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
548 : completers
[completetype
].completer
));
550 if (except
.reason
< 0)
556 PyErr_Format (except
.reason
== RETURN_QUIT
557 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
558 "%s", except
.message
);
566 /* Initialize the 'commands' code. */
569 gdbpy_initialize_commands (void)
573 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
574 if (PyType_Ready (&cmdpy_object_type
) < 0)
577 /* Note: alias and user are special; pseudo appears to be unused,
578 and there is no reason to expose tui or xdb, I think. */
579 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
580 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
581 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
582 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
583 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
584 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
586 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
587 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
588 class_breakpoint
) < 0
589 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
591 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
593 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
594 class_maintenance
) < 0
595 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
598 for (i
= 0; i
< N_COMPLETERS
; ++i
)
600 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
604 if (gdb_pymodule_addobject (gdb_module
, "Command",
605 (PyObject
*) &cmdpy_object_type
) < 0)
608 invoke_cst
= PyString_FromString ("invoke");
609 if (invoke_cst
== NULL
)
611 complete_cst
= PyString_FromString ("complete");
612 if (complete_cst
== NULL
)
620 static PyMethodDef cmdpy_object_methods
[] =
622 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
623 "Prevent command repetition when user enters empty line." },
628 static PyTypeObject cmdpy_object_type
=
630 PyVarObject_HEAD_INIT (NULL
, 0)
631 "gdb.Command", /*tp_name*/
632 sizeof (cmdpy_object
), /*tp_basicsize*/
641 0, /*tp_as_sequence*/
649 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
650 "GDB command object", /* tp_doc */
653 0, /* tp_richcompare */
654 0, /* tp_weaklistoffset */
657 cmdpy_object_methods
, /* tp_methods */
662 0, /* tp_descr_get */
663 0, /* tp_descr_set */
664 0, /* tp_dictoffset */
665 cmdpy_init
, /* tp_init */
671 /* Utility to build a buildargv-like result from ARGS.
672 This intentionally parses arguments the way libiberty/argv.c:buildargv
673 does. It splits up arguments in a reasonable way, and we want a standard
674 way of parsing arguments. Several gdb commands use buildargv to parse their
675 arguments. Plus we want to be able to write compatible python
676 implementations of gdb commands. */
679 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
684 if (!PyArg_ParseTuple (args
, "s", &input
))
687 py_argv
= PyList_New (0);
691 /* buildargv uses NULL to represent an empty argument list, but we can't use
692 that in Python. Instead, if ARGS is "" then return an empty list.
693 This undoes the NULL -> "" conversion that cmdpy_function does. */
697 char **c_argv
= gdb_buildargv (input
);
700 for (i
= 0; c_argv
[i
] != NULL
; ++i
)
702 PyObject
*argp
= PyString_FromString (c_argv
[i
]);
705 || PyList_Append (py_argv
, argp
) < 0)