1 /* gdb commands implemented in Python
3 Copyright (C) 2008-2013 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
},
50 #define N_COMPLETERS (sizeof (completers) / sizeof (completers[0]))
52 /* A gdb command. For the time being only ordinary commands (not
53 set/show commands) are allowed. */
58 /* The corresponding gdb command object, or NULL if the command is
59 no longer installed. */
60 struct cmd_list_element
*command
;
62 /* A prefix command requires storage for a list of its sub-commands.
63 A pointer to this is passed to add_prefix_command, and to add_cmd
64 for sub-commands of that prefix. If this Command is not a prefix
65 command, then this field is unused. */
66 struct cmd_list_element
*sub_list
;
69 typedef struct cmdpy_object cmdpy_object
;
71 static PyTypeObject cmdpy_object_type
72 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("cmdpy_object");
74 /* Constants used by this module. */
75 static PyObject
*invoke_cst
;
76 static PyObject
*complete_cst
;
80 /* Python function which wraps dont_repeat. */
82 cmdpy_dont_repeat (PyObject
*self
, PyObject
*args
)
90 /* Called if the gdb cmd_list_element is destroyed. */
93 cmdpy_destroyer (struct cmd_list_element
*self
, void *context
)
96 struct cleanup
*cleanup
;
98 cleanup
= ensure_python_env (get_current_arch (), current_language
);
100 /* Release our hold on the command object. */
101 cmd
= (cmdpy_object
*) context
;
105 /* We allocated the name, doc string, and perhaps the prefix
107 xfree ((char *) self
->name
);
109 xfree (self
->prefixname
);
111 do_cleanups (cleanup
);
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
);
120 PyObject
*argobj
, *ttyobj
, *result
;
121 struct cleanup
*cleanup
;
123 cleanup
= ensure_python_env (get_current_arch (), current_language
);
126 error (_("Invalid invocation of Python command object."));
127 if (! PyObject_HasAttr ((PyObject
*) obj
, invoke_cst
))
129 if (obj
->command
->prefixname
)
131 /* A prefix command does not need an invoke method. */
132 do_cleanups (cleanup
);
135 error (_("Python command object missing 'invoke' method."));
140 argobj
= PyUnicode_Decode (args
, strlen (args
), host_charset (), NULL
);
143 gdbpy_print_stack ();
144 error (_("Could not convert arguments to Python string."));
147 ttyobj
= from_tty
? Py_True
: Py_False
;
149 result
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, invoke_cst
, argobj
,
156 PyObject
*ptype
, *pvalue
, *ptraceback
;
159 PyErr_Fetch (&ptype
, &pvalue
, &ptraceback
);
161 /* Try to fetch an error message contained within ptype, pvalue.
162 When fetching the error message we need to make our own copy,
163 we no longer own ptype, pvalue after the call to PyErr_Restore. */
165 msg
= gdbpy_exception_to_string (ptype
, pvalue
);
166 make_cleanup (xfree
, msg
);
170 /* An error occurred computing the string representation of the
171 error message. This is rare, but we should inform the user. */
172 printf_filtered (_("An error occurred in a Python command\n"
173 "and then another occurred computing the "
174 "error message.\n"));
175 gdbpy_print_stack ();
178 /* Don't print the stack for gdb.GdbError exceptions.
179 It is generally used to flag user errors.
181 We also don't want to print "Error occurred in Python command"
182 for user errors. However, a missing message for gdb.GdbError
183 exceptions is arguably a bug, so we flag it as such. */
185 if (! PyErr_GivenExceptionMatches (ptype
, gdbpy_gdberror_exc
)
186 || msg
== NULL
|| *msg
== '\0')
188 PyErr_Restore (ptype
, pvalue
, ptraceback
);
189 gdbpy_print_stack ();
190 if (msg
!= NULL
&& *msg
!= '\0')
191 error (_("Error occurred in Python command: %s"), msg
);
193 error (_("Error occurred in Python command."));
199 Py_XDECREF (ptraceback
);
205 do_cleanups (cleanup
);
208 /* Called by gdb for command completion. */
210 static VEC (char_ptr
) *
211 cmdpy_completer (struct cmd_list_element
*command
,
212 const char *text
, const char *word
)
214 cmdpy_object
*obj
= (cmdpy_object
*) get_cmd_context (command
);
215 PyObject
*textobj
, *wordobj
, *resultobj
= NULL
;
216 VEC (char_ptr
) *result
= NULL
;
217 struct cleanup
*cleanup
;
219 cleanup
= ensure_python_env (get_current_arch (), current_language
);
222 error (_("Invalid invocation of Python command object."));
223 if (! PyObject_HasAttr ((PyObject
*) obj
, complete_cst
))
225 /* If there is no complete method, don't error -- instead, just
226 say that there are no completions. */
230 textobj
= PyUnicode_Decode (text
, strlen (text
), host_charset (), NULL
);
232 error (_("Could not convert argument to Python string."));
233 wordobj
= PyUnicode_Decode (word
, strlen (word
), host_charset (), NULL
);
235 error (_("Could not convert argument to Python string."));
237 resultobj
= PyObject_CallMethodObjArgs ((PyObject
*) obj
, complete_cst
,
238 textobj
, wordobj
, NULL
);
243 /* Just swallow errors here. */
249 if (PyInt_Check (resultobj
))
251 /* User code may also return one of the completion constants,
252 thus requesting that sort of completion. */
255 if (! gdb_py_int_as_long (resultobj
, &value
))
260 else if (value
>= 0 && value
< (long) N_COMPLETERS
)
261 result
= completers
[value
].completer (command
, text
, word
);
265 PyObject
*iter
= PyObject_GetIter (resultobj
);
271 while ((elt
= PyIter_Next (iter
)) != NULL
)
275 if (! gdbpy_is_string (elt
))
277 /* Skip problem elements. */
281 item
= python_string_to_host_string (elt
);
285 /* Skip problem elements. */
289 VEC_safe_push (char_ptr
, result
, item
);
294 /* If we got some results, ignore problems. Otherwise, report
296 if (result
!= NULL
&& PyErr_Occurred ())
302 Py_XDECREF (resultobj
);
303 do_cleanups (cleanup
);
308 /* Helper for cmdpy_init which locates the command list to use and
309 pulls out the command name.
311 NAME is the command name list. The final word in the list is the
312 name of the new command. All earlier words must be existing prefix
315 *BASE_LIST is set to the final prefix command's list of
318 START_LIST is the list in which the search starts.
320 This function returns the xmalloc()d name of the new command. On
321 error sets the Python error and returns NULL. */
324 gdbpy_parse_command_name (const char *name
,
325 struct cmd_list_element
***base_list
,
326 struct cmd_list_element
**start_list
)
328 struct cmd_list_element
*elt
;
329 int len
= strlen (name
);
332 const char *prefix_text2
;
335 /* Skip trailing whitespace. */
336 for (i
= len
- 1; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
340 PyErr_SetString (PyExc_RuntimeError
, _("No command name found."));
345 /* Find first character of the final word. */
346 for (; i
> 0 && (isalnum (name
[i
- 1])
347 || name
[i
- 1] == '-'
348 || name
[i
- 1] == '_');
351 result
= xmalloc (lastchar
- i
+ 2);
352 memcpy (result
, &name
[i
], lastchar
- i
+ 1);
353 result
[lastchar
- i
+ 1] = '\0';
355 /* Skip whitespace again. */
356 for (--i
; i
>= 0 && (name
[i
] == ' ' || name
[i
] == '\t'); --i
)
360 *base_list
= start_list
;
364 prefix_text
= xmalloc (i
+ 2);
365 memcpy (prefix_text
, name
, i
+ 1);
366 prefix_text
[i
+ 1] = '\0';
368 prefix_text2
= prefix_text
;
369 elt
= lookup_cmd_1 (&prefix_text2
, *start_list
, NULL
, 1);
370 if (!elt
|| elt
== (struct cmd_list_element
*) -1)
372 PyErr_Format (PyExc_RuntimeError
, _("Could not find command prefix %s."),
382 *base_list
= elt
->prefixlist
;
386 PyErr_Format (PyExc_RuntimeError
, _("'%s' is not a prefix command."),
393 /* Object initializer; sets up gdb-side structures for command.
395 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
397 NAME is the name of the command. It may consist of multiple words,
398 in which case the final word is the name of the new command, and
399 earlier words must be prefix commands.
401 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
402 constants defined in the gdb module.
404 COMPLETER_CLASS is the kind of completer. If not given, the
405 "complete" method will be used. Otherwise, it should be one of the
406 COMPLETE_* constants defined in the gdb module.
408 If PREFIX is True, then this command is a prefix command.
410 The documentation for the command is taken from the doc string for
414 cmdpy_init (PyObject
*self
, PyObject
*args
, PyObject
*kw
)
416 cmdpy_object
*obj
= (cmdpy_object
*) self
;
419 int completetype
= -1;
420 char *docstring
= NULL
;
421 volatile struct gdb_exception except
;
422 struct cmd_list_element
**cmd_list
;
423 char *cmd_name
, *pfx_name
;
424 static char *keywords
[] = { "name", "command_class", "completer_class",
426 PyObject
*is_prefix
= NULL
;
431 /* Note: this is apparently not documented in Python. We return
432 0 for success, -1 for failure. */
433 PyErr_Format (PyExc_RuntimeError
,
434 _("Command object already initialized."));
438 if (! PyArg_ParseTupleAndKeywords (args
, kw
, "si|iO",
439 keywords
, &name
, &cmdtype
,
440 &completetype
, &is_prefix
))
443 if (cmdtype
!= no_class
&& cmdtype
!= class_run
444 && cmdtype
!= class_vars
&& cmdtype
!= class_stack
445 && cmdtype
!= class_files
&& cmdtype
!= class_support
446 && cmdtype
!= class_info
&& cmdtype
!= class_breakpoint
447 && cmdtype
!= class_trace
&& cmdtype
!= class_obscure
448 && cmdtype
!= class_maintenance
&& cmdtype
!= class_user
)
450 PyErr_Format (PyExc_RuntimeError
, _("Invalid command class argument."));
454 if (completetype
< -1 || completetype
>= (int) N_COMPLETERS
)
456 PyErr_Format (PyExc_RuntimeError
,
457 _("Invalid completion type argument."));
461 cmd_name
= gdbpy_parse_command_name (name
, &cmd_list
, &cmdlist
);
466 if (is_prefix
!= NULL
)
468 cmp
= PyObject_IsTrue (is_prefix
);
473 /* Make a normalized form of the command name. */
474 pfx_name
= xmalloc (strlen (name
) + 2);
480 /* Skip whitespace. */
481 while (name
[i
] == ' ' || name
[i
] == '\t')
483 /* Copy non-whitespace characters. */
484 while (name
[i
] && name
[i
] != ' ' && name
[i
] != '\t')
485 pfx_name
[out
++] = name
[i
++];
486 /* Add a single space after each word -- including the final
488 pfx_name
[out
++] = ' ';
490 pfx_name
[out
] = '\0';
498 if (PyObject_HasAttr (self
, gdbpy_doc_cst
))
500 PyObject
*ds_obj
= PyObject_GetAttr (self
, gdbpy_doc_cst
);
502 if (ds_obj
&& gdbpy_is_string (ds_obj
))
504 docstring
= python_string_to_host_string (ds_obj
);
505 if (docstring
== NULL
)
517 docstring
= xstrdup (_("This command is not documented."));
521 TRY_CATCH (except
, RETURN_MASK_ALL
)
523 struct cmd_list_element
*cmd
;
529 /* If we have our own "invoke" method, then allow unknown
531 allow_unknown
= PyObject_HasAttr (self
, invoke_cst
);
532 cmd
= add_prefix_cmd (cmd_name
, (enum command_class
) cmdtype
,
533 NULL
, docstring
, &obj
->sub_list
,
534 pfx_name
, allow_unknown
, cmd_list
);
537 cmd
= add_cmd (cmd_name
, (enum command_class
) cmdtype
, NULL
,
538 docstring
, cmd_list
);
540 /* There appears to be no API to set this. */
541 cmd
->func
= cmdpy_function
;
542 cmd
->destroyer
= cmdpy_destroyer
;
545 set_cmd_context (cmd
, self
);
546 set_cmd_completer (cmd
, ((completetype
== -1) ? cmdpy_completer
547 : completers
[completetype
].completer
));
549 if (except
.reason
< 0)
555 PyErr_Format (except
.reason
== RETURN_QUIT
556 ? PyExc_KeyboardInterrupt
: PyExc_RuntimeError
,
557 "%s", except
.message
);
565 /* Initialize the 'commands' code. */
568 gdbpy_initialize_commands (void)
572 cmdpy_object_type
.tp_new
= PyType_GenericNew
;
573 if (PyType_Ready (&cmdpy_object_type
) < 0)
576 /* Note: alias and user are special; pseudo appears to be unused,
577 and there is no reason to expose tui or xdb, I think. */
578 if (PyModule_AddIntConstant (gdb_module
, "COMMAND_NONE", no_class
) < 0
579 || PyModule_AddIntConstant (gdb_module
, "COMMAND_RUNNING", class_run
) < 0
580 || PyModule_AddIntConstant (gdb_module
, "COMMAND_DATA", class_vars
) < 0
581 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STACK", class_stack
) < 0
582 || PyModule_AddIntConstant (gdb_module
, "COMMAND_FILES", class_files
) < 0
583 || PyModule_AddIntConstant (gdb_module
, "COMMAND_SUPPORT",
585 || PyModule_AddIntConstant (gdb_module
, "COMMAND_STATUS", class_info
) < 0
586 || PyModule_AddIntConstant (gdb_module
, "COMMAND_BREAKPOINTS",
587 class_breakpoint
) < 0
588 || PyModule_AddIntConstant (gdb_module
, "COMMAND_TRACEPOINTS",
590 || PyModule_AddIntConstant (gdb_module
, "COMMAND_OBSCURE",
592 || PyModule_AddIntConstant (gdb_module
, "COMMAND_MAINTENANCE",
593 class_maintenance
) < 0
594 || PyModule_AddIntConstant (gdb_module
, "COMMAND_USER", class_user
) < 0)
597 for (i
= 0; i
< N_COMPLETERS
; ++i
)
599 if (PyModule_AddIntConstant (gdb_module
, completers
[i
].name
, i
) < 0)
603 if (gdb_pymodule_addobject (gdb_module
, "Command",
604 (PyObject
*) &cmdpy_object_type
) < 0)
607 invoke_cst
= PyString_FromString ("invoke");
608 if (invoke_cst
== NULL
)
610 complete_cst
= PyString_FromString ("complete");
611 if (complete_cst
== NULL
)
619 static PyMethodDef cmdpy_object_methods
[] =
621 { "dont_repeat", cmdpy_dont_repeat
, METH_NOARGS
,
622 "Prevent command repetition when user enters empty line." },
627 static PyTypeObject cmdpy_object_type
=
629 PyVarObject_HEAD_INIT (NULL
, 0)
630 "gdb.Command", /*tp_name*/
631 sizeof (cmdpy_object
), /*tp_basicsize*/
640 0, /*tp_as_sequence*/
648 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
649 "GDB command object", /* tp_doc */
652 0, /* tp_richcompare */
653 0, /* tp_weaklistoffset */
656 cmdpy_object_methods
, /* tp_methods */
661 0, /* tp_descr_get */
662 0, /* tp_descr_set */
663 0, /* tp_dictoffset */
664 cmdpy_init
, /* tp_init */
670 /* Utility to build a buildargv-like result from ARGS.
671 This intentionally parses arguments the way libiberty/argv.c:buildargv
672 does. It splits up arguments in a reasonable way, and we want a standard
673 way of parsing arguments. Several gdb commands use buildargv to parse their
674 arguments. Plus we want to be able to write compatible python
675 implementations of gdb commands. */
678 gdbpy_string_to_argv (PyObject
*self
, PyObject
*args
)
683 if (!PyArg_ParseTuple (args
, "s", &input
))
686 py_argv
= PyList_New (0);
690 /* buildargv uses NULL to represent an empty argument list, but we can't use
691 that in Python. Instead, if ARGS is "" then return an empty list.
692 This undoes the NULL -> "" conversion that cmdpy_function does. */
696 char **c_argv
= gdb_buildargv (input
);
699 for (i
= 0; c_argv
[i
] != NULL
; ++i
)
701 PyObject
*argp
= PyString_FromString (c_argv
[i
]);
704 || PyList_Append (py_argv
, argp
) < 0)