1 /* gdb commands implemented in Python
2
3 Copyright (C) 2008-2013 Free Software Foundation, Inc.
4
5 This file is part of GDB.
6
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.
11
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.
16
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/>. */
19
20
21 #include "defs.h"
22 #include "arch-utils.h"
23 #include "value.h"
24 #include "exceptions.h"
25 #include "python-internal.h"
26 #include "charset.h"
27 #include "gdbcmd.h"
28 #include "cli/cli-decode.h"
29 #include "completer.h"
30 #include "language.h"
31
32 /* Struct representing built-in completion types. */
33 struct cmdpy_completer
34 {
35 /* Python symbol name. */
36 char *name;
37 /* Completion function. */
38 completer_ftype *completer;
39 };
40
41 static struct cmdpy_completer completers[] =
42 {
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 };
49
50 #define N_COMPLETERS (sizeof (completers) / sizeof (completers[0]))
51
52 /* A gdb command. For the time being only ordinary commands (not
53 set/show commands) are allowed. */
54 struct cmdpy_object
55 {
56 PyObject_HEAD
57
58 /* The corresponding gdb command object, or NULL if the command is
59 no longer installed. */
60 struct cmd_list_element *command;
61
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;
67 };
68
69 typedef struct cmdpy_object cmdpy_object;
70
71 static PyTypeObject cmdpy_object_type;
72
73 /* Constants used by this module. */
74 static PyObject *invoke_cst;
75 static PyObject *complete_cst;
76
77
78
79 /* Python function which wraps dont_repeat. */
80 static PyObject *
cmdpy_dont_repeat(PyObject * self,PyObject * args)81 cmdpy_dont_repeat (PyObject *self, PyObject *args)
82 {
83 dont_repeat ();
84 Py_RETURN_NONE;
85 }
86
87
88
89 /* Called if the gdb cmd_list_element is destroyed. */
90
91 static void
cmdpy_destroyer(struct cmd_list_element * self,void * context)92 cmdpy_destroyer (struct cmd_list_element *self, void *context)
93 {
94 cmdpy_object *cmd;
95 struct cleanup *cleanup;
96
97 cleanup = ensure_python_env (get_current_arch (), current_language);
98
99 /* Release our hold on the command object. */
100 cmd = (cmdpy_object *) context;
101 cmd->command = NULL;
102 Py_DECREF (cmd);
103
104 /* We allocated the name, doc string, and perhaps the prefix
105 name. */
106 xfree (self->name);
107 xfree (self->doc);
108 xfree (self->prefixname);
109
110 do_cleanups (cleanup);
111 }
112
113 /* Called by gdb to invoke the command. */
114
115 static void
cmdpy_function(struct cmd_list_element * command,char * args,int from_tty)116 cmdpy_function (struct cmd_list_element *command, char *args, int from_tty)
117 {
118 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command);
119 PyObject *argobj, *ttyobj, *result;
120 struct cleanup *cleanup;
121
122 cleanup = ensure_python_env (get_current_arch (), current_language);
123
124 if (! obj)
125 error (_("Invalid invocation of Python command object."));
126 if (! PyObject_HasAttr ((PyObject *) obj, invoke_cst))
127 {
128 if (obj->command->prefixname)
129 {
130 /* A prefix command does not need an invoke method. */
131 do_cleanups (cleanup);
132 return;
133 }
134 error (_("Python command object missing 'invoke' method."));
135 }
136
137 if (! args)
138 args = "";
139 argobj = PyUnicode_Decode (args, strlen (args), host_charset (), NULL);
140 if (! argobj)
141 {
142 gdbpy_print_stack ();
143 error (_("Could not convert arguments to Python string."));
144 }
145
146 ttyobj = from_tty ? Py_True : Py_False;
147 Py_INCREF (ttyobj);
148 result = PyObject_CallMethodObjArgs ((PyObject *) obj, invoke_cst, argobj,
149 ttyobj, NULL);
150 Py_DECREF (argobj);
151 Py_DECREF (ttyobj);
152
153 if (! result)
154 {
155 PyObject *ptype, *pvalue, *ptraceback;
156 char *msg;
157
158 PyErr_Fetch (&ptype, &pvalue, &ptraceback);
159
160 /* Try to fetch an error message contained within ptype, pvalue.
161 When fetching the error message we need to make our own copy,
162 we no longer own ptype, pvalue after the call to PyErr_Restore. */
163
164 msg = gdbpy_exception_to_string (ptype, pvalue);
165 make_cleanup (xfree, msg);
166
167 if (msg == NULL)
168 {
169 /* An error occurred computing the string representation of the
170 error message. This is rare, but we should inform the user. */
171 printf_filtered (_("An error occurred in a Python command\n"
172 "and then another occurred computing the "
173 "error message.\n"));
174 gdbpy_print_stack ();
175 }
176
177 /* Don't print the stack for gdb.GdbError exceptions.
178 It is generally used to flag user errors.
179
180 We also don't want to print "Error occurred in Python command"
181 for user errors. However, a missing message for gdb.GdbError
182 exceptions is arguably a bug, so we flag it as such. */
183
184 if (! PyErr_GivenExceptionMatches (ptype, gdbpy_gdberror_exc)
185 || msg == NULL || *msg == '\0')
186 {
187 PyErr_Restore (ptype, pvalue, ptraceback);
188 gdbpy_print_stack ();
189 if (msg != NULL && *msg != '\0')
190 error (_("Error occurred in Python command: %s"), msg);
191 else
192 error (_("Error occurred in Python command."));
193 }
194 else
195 {
196 Py_XDECREF (ptype);
197 Py_XDECREF (pvalue);
198 Py_XDECREF (ptraceback);
199 error ("%s", msg);
200 }
201 }
202
203 Py_DECREF (result);
204 do_cleanups (cleanup);
205 }
206
207 /* Called by gdb for command completion. */
208
VEC(char_ptr)209 static VEC (char_ptr) *
210 cmdpy_completer (struct cmd_list_element *command, char *text, char *word)
211 {
212 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command);
213 PyObject *textobj, *wordobj, *resultobj = NULL;
214 VEC (char_ptr) *result = NULL;
215 struct cleanup *cleanup;
216
217 cleanup = ensure_python_env (get_current_arch (), current_language);
218
219 if (! obj)
220 error (_("Invalid invocation of Python command object."));
221 if (! PyObject_HasAttr ((PyObject *) obj, complete_cst))
222 {
223 /* If there is no complete method, don't error -- instead, just
224 say that there are no completions. */
225 goto done;
226 }
227
228 textobj = PyUnicode_Decode (text, strlen (text), host_charset (), NULL);
229 if (! textobj)
230 error (_("Could not convert argument to Python string."));
231 wordobj = PyUnicode_Decode (word, strlen (word), host_charset (), NULL);
232 if (! wordobj)
233 error (_("Could not convert argument to Python string."));
234
235 resultobj = PyObject_CallMethodObjArgs ((PyObject *) obj, complete_cst,
236 textobj, wordobj, NULL);
237 Py_DECREF (textobj);
238 Py_DECREF (wordobj);
239 if (! resultobj)
240 {
241 /* Just swallow errors here. */
242 PyErr_Clear ();
243 goto done;
244 }
245 make_cleanup_py_decref (resultobj);
246
247 result = NULL;
248 if (PySequence_Check (resultobj))
249 {
250 Py_ssize_t i, len = PySequence_Size (resultobj);
251 Py_ssize_t out;
252
253 if (len < 0)
254 goto done;
255
256 for (i = out = 0; i < len; ++i)
257 {
258 PyObject *elt = PySequence_GetItem (resultobj, i);
259 char *item;
260
261 if (elt == NULL || ! gdbpy_is_string (elt))
262 {
263 /* Skip problem elements. */
264 PyErr_Clear ();
265 continue;
266 }
267 item = python_string_to_host_string (elt);
268 if (item == NULL)
269 {
270 /* Skip problem elements. */
271 PyErr_Clear ();
272 continue;
273 }
274 VEC_safe_push (char_ptr, result, item);
275 }
276 }
277 else if (PyInt_Check (resultobj))
278 {
279 /* User code may also return one of the completion constants,
280 thus requesting that sort of completion. */
281 long value;
282
283 if (! gdb_py_int_as_long (resultobj, &value))
284 {
285 /* Ignore. */
286 PyErr_Clear ();
287 }
288 else if (value >= 0 && value < (long) N_COMPLETERS)
289 result = completers[value].completer (command, text, word);
290 }
291
292 done:
293
294 do_cleanups (cleanup);
295
296 return result;
297 }
298
299 /* Helper for cmdpy_init which locates the command list to use and
300 pulls out the command name.
301
302 NAME is the command name list. The final word in the list is the
303 name of the new command. All earlier words must be existing prefix
304 commands.
305
306 *BASE_LIST is set to the final prefix command's list of
307 *sub-commands.
308
309 START_LIST is the list in which the search starts.
310
311 This function returns the xmalloc()d name of the new command. On
312 error sets the Python error and returns NULL. */
313
314 char *
gdbpy_parse_command_name(const char * name,struct cmd_list_element *** base_list,struct cmd_list_element ** start_list)315 gdbpy_parse_command_name (const char *name,
316 struct cmd_list_element ***base_list,
317 struct cmd_list_element **start_list)
318 {
319 struct cmd_list_element *elt;
320 int len = strlen (name);
321 int i, lastchar;
322 char *prefix_text, *prefix_text2;
323 char *result;
324
325 /* Skip trailing whitespace. */
326 for (i = len - 1; i >= 0 && (name[i] == ' ' || name[i] == '\t'); --i)
327 ;
328 if (i < 0)
329 {
330 PyErr_SetString (PyExc_RuntimeError, _("No command name found."));
331 return NULL;
332 }
333 lastchar = i;
334
335 /* Find first character of the final word. */
336 for (; i > 0 && (isalnum (name[i - 1])
337 || name[i - 1] == '-'
338 || name[i - 1] == '_');
339 --i)
340 ;
341 result = xmalloc (lastchar - i + 2);
342 memcpy (result, &name[i], lastchar - i + 1);
343 result[lastchar - i + 1] = '\0';
344
345 /* Skip whitespace again. */
346 for (--i; i >= 0 && (name[i] == ' ' || name[i] == '\t'); --i)
347 ;
348 if (i < 0)
349 {
350 *base_list = start_list;
351 return result;
352 }
353
354 prefix_text = xmalloc (i + 2);
355 memcpy (prefix_text, name, i + 1);
356 prefix_text[i + 1] = '\0';
357
358 prefix_text2 = prefix_text;
359 elt = lookup_cmd_1 (&prefix_text2, *start_list, NULL, 1);
360 if (!elt || elt == (struct cmd_list_element *) -1)
361 {
362 PyErr_Format (PyExc_RuntimeError, _("Could not find command prefix %s."),
363 prefix_text);
364 xfree (prefix_text);
365 xfree (result);
366 return NULL;
367 }
368
369 if (elt->prefixlist)
370 {
371 xfree (prefix_text);
372 *base_list = elt->prefixlist;
373 return result;
374 }
375
376 PyErr_Format (PyExc_RuntimeError, _("'%s' is not a prefix command."),
377 prefix_text);
378 xfree (prefix_text);
379 xfree (result);
380 return NULL;
381 }
382
383 /* Object initializer; sets up gdb-side structures for command.
384
385 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]).
386
387 NAME is the name of the command. It may consist of multiple words,
388 in which case the final word is the name of the new command, and
389 earlier words must be prefix commands.
390
391 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_*
392 constants defined in the gdb module.
393
394 COMPLETER_CLASS is the kind of completer. If not given, the
395 "complete" method will be used. Otherwise, it should be one of the
396 COMPLETE_* constants defined in the gdb module.
397
398 If PREFIX is True, then this command is a prefix command.
399
400 The documentation for the command is taken from the doc string for
401 the python class. */
402
403 static int
cmdpy_init(PyObject * self,PyObject * args,PyObject * kw)404 cmdpy_init (PyObject *self, PyObject *args, PyObject *kw)
405 {
406 cmdpy_object *obj = (cmdpy_object *) self;
407 const char *name;
408 int cmdtype;
409 int completetype = -1;
410 char *docstring = NULL;
411 volatile struct gdb_exception except;
412 struct cmd_list_element **cmd_list;
413 char *cmd_name, *pfx_name;
414 static char *keywords[] = { "name", "command_class", "completer_class",
415 "prefix", NULL };
416 PyObject *is_prefix = NULL;
417 int cmp;
418
419 if (obj->command)
420 {
421 /* Note: this is apparently not documented in Python. We return
422 0 for success, -1 for failure. */
423 PyErr_Format (PyExc_RuntimeError,
424 _("Command object already initialized."));
425 return -1;
426 }
427
428 if (! PyArg_ParseTupleAndKeywords (args, kw, "si|iO",
429 keywords, &name, &cmdtype,
430 &completetype, &is_prefix))
431 return -1;
432
433 if (cmdtype != no_class && cmdtype != class_run
434 && cmdtype != class_vars && cmdtype != class_stack
435 && cmdtype != class_files && cmdtype != class_support
436 && cmdtype != class_info && cmdtype != class_breakpoint
437 && cmdtype != class_trace && cmdtype != class_obscure
438 && cmdtype != class_maintenance && cmdtype != class_user)
439 {
440 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
441 return -1;
442 }
443
444 if (completetype < -1 || completetype >= (int) N_COMPLETERS)
445 {
446 PyErr_Format (PyExc_RuntimeError,
447 _("Invalid completion type argument."));
448 return -1;
449 }
450
451 cmd_name = gdbpy_parse_command_name (name, &cmd_list, &cmdlist);
452 if (! cmd_name)
453 return -1;
454
455 pfx_name = NULL;
456 if (is_prefix != NULL)
457 {
458 cmp = PyObject_IsTrue (is_prefix);
459 if (cmp == 1)
460 {
461 int i, out;
462
463 /* Make a normalized form of the command name. */
464 pfx_name = xmalloc (strlen (name) + 2);
465
466 i = 0;
467 out = 0;
468 while (name[i])
469 {
470 /* Skip whitespace. */
471 while (name[i] == ' ' || name[i] == '\t')
472 ++i;
473 /* Copy non-whitespace characters. */
474 while (name[i] && name[i] != ' ' && name[i] != '\t')
475 pfx_name[out++] = name[i++];
476 /* Add a single space after each word -- including the final
477 word. */
478 pfx_name[out++] = ' ';
479 }
480 pfx_name[out] = '\0';
481 }
482 else if (cmp < 0)
483 {
484 xfree (cmd_name);
485 return -1;
486 }
487 }
488 if (PyObject_HasAttr (self, gdbpy_doc_cst))
489 {
490 PyObject *ds_obj = PyObject_GetAttr (self, gdbpy_doc_cst);
491
492 if (ds_obj && gdbpy_is_string (ds_obj))
493 {
494 docstring = python_string_to_host_string (ds_obj);
495 if (docstring == NULL)
496 {
497 xfree (cmd_name);
498 xfree (pfx_name);
499 return -1;
500 }
501 }
502 }
503 if (! docstring)
504 docstring = xstrdup (_("This command is not documented."));
505
506 Py_INCREF (self);
507
508 TRY_CATCH (except, RETURN_MASK_ALL)
509 {
510 struct cmd_list_element *cmd;
511
512 if (pfx_name)
513 {
514 int allow_unknown;
515
516 /* If we have our own "invoke" method, then allow unknown
517 sub-commands. */
518 allow_unknown = PyObject_HasAttr (self, invoke_cst);
519 cmd = add_prefix_cmd (cmd_name, (enum command_class) cmdtype,
520 NULL, docstring, &obj->sub_list,
521 pfx_name, allow_unknown, cmd_list);
522 }
523 else
524 cmd = add_cmd (cmd_name, (enum command_class) cmdtype, NULL,
525 docstring, cmd_list);
526
527 /* There appears to be no API to set this. */
528 cmd->func = cmdpy_function;
529 cmd->destroyer = cmdpy_destroyer;
530
531 obj->command = cmd;
532 set_cmd_context (cmd, self);
533 set_cmd_completer (cmd, ((completetype == -1) ? cmdpy_completer
534 : completers[completetype].completer));
535 }
536 if (except.reason < 0)
537 {
538 xfree (cmd_name);
539 xfree (docstring);
540 xfree (pfx_name);
541 Py_DECREF (self);
542 PyErr_Format (except.reason == RETURN_QUIT
543 ? PyExc_KeyboardInterrupt : PyExc_RuntimeError,
544 "%s", except.message);
545 return -1;
546 }
547 return 0;
548 }
549
550
551
552 /* Initialize the 'commands' code. */
553
554 void
gdbpy_initialize_commands(void)555 gdbpy_initialize_commands (void)
556 {
557 int i;
558
559 cmdpy_object_type.tp_new = PyType_GenericNew;
560 if (PyType_Ready (&cmdpy_object_type) < 0)
561 return;
562
563 /* Note: alias and user are special; pseudo appears to be unused,
564 and there is no reason to expose tui or xdb, I think. */
565 if (PyModule_AddIntConstant (gdb_module, "COMMAND_NONE", no_class) < 0
566 || PyModule_AddIntConstant (gdb_module, "COMMAND_RUNNING", class_run) < 0
567 || PyModule_AddIntConstant (gdb_module, "COMMAND_DATA", class_vars) < 0
568 || PyModule_AddIntConstant (gdb_module, "COMMAND_STACK", class_stack) < 0
569 || PyModule_AddIntConstant (gdb_module, "COMMAND_FILES", class_files) < 0
570 || PyModule_AddIntConstant (gdb_module, "COMMAND_SUPPORT",
571 class_support) < 0
572 || PyModule_AddIntConstant (gdb_module, "COMMAND_STATUS", class_info) < 0
573 || PyModule_AddIntConstant (gdb_module, "COMMAND_BREAKPOINTS",
574 class_breakpoint) < 0
575 || PyModule_AddIntConstant (gdb_module, "COMMAND_TRACEPOINTS",
576 class_trace) < 0
577 || PyModule_AddIntConstant (gdb_module, "COMMAND_OBSCURE",
578 class_obscure) < 0
579 || PyModule_AddIntConstant (gdb_module, "COMMAND_MAINTENANCE",
580 class_maintenance) < 0
581 || PyModule_AddIntConstant (gdb_module, "COMMAND_USER", class_user) < 0)
582 return;
583
584 for (i = 0; i < N_COMPLETERS; ++i)
585 {
586 if (PyModule_AddIntConstant (gdb_module, completers[i].name, i) < 0)
587 return;
588 }
589
590 Py_INCREF (&cmdpy_object_type);
591 PyModule_AddObject (gdb_module, "Command",
592 (PyObject *) &cmdpy_object_type);
593
594 invoke_cst = PyString_FromString ("invoke");
595 complete_cst = PyString_FromString ("complete");
596 }
597
598
599
600 static PyMethodDef cmdpy_object_methods[] =
601 {
602 { "dont_repeat", cmdpy_dont_repeat, METH_NOARGS,
603 "Prevent command repetition when user enters empty line." },
604
605 { 0 }
606 };
607
608 static PyTypeObject cmdpy_object_type =
609 {
610 PyVarObject_HEAD_INIT (NULL, 0)
611 "gdb.Command", /*tp_name*/
612 sizeof (cmdpy_object), /*tp_basicsize*/
613 0, /*tp_itemsize*/
614 0, /*tp_dealloc*/
615 0, /*tp_print*/
616 0, /*tp_getattr*/
617 0, /*tp_setattr*/
618 0, /*tp_compare*/
619 0, /*tp_repr*/
620 0, /*tp_as_number*/
621 0, /*tp_as_sequence*/
622 0, /*tp_as_mapping*/
623 0, /*tp_hash */
624 0, /*tp_call*/
625 0, /*tp_str*/
626 0, /*tp_getattro*/
627 0, /*tp_setattro*/
628 0, /*tp_as_buffer*/
629 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
630 "GDB command object", /* tp_doc */
631 0, /* tp_traverse */
632 0, /* tp_clear */
633 0, /* tp_richcompare */
634 0, /* tp_weaklistoffset */
635 0, /* tp_iter */
636 0, /* tp_iternext */
637 cmdpy_object_methods, /* tp_methods */
638 0, /* tp_members */
639 0, /* tp_getset */
640 0, /* tp_base */
641 0, /* tp_dict */
642 0, /* tp_descr_get */
643 0, /* tp_descr_set */
644 0, /* tp_dictoffset */
645 cmdpy_init, /* tp_init */
646 0, /* tp_alloc */
647 };
648
649
650
651 /* Utility to build a buildargv-like result from ARGS.
652 This intentionally parses arguments the way libiberty/argv.c:buildargv
653 does. It splits up arguments in a reasonable way, and we want a standard
654 way of parsing arguments. Several gdb commands use buildargv to parse their
655 arguments. Plus we want to be able to write compatible python
656 implementations of gdb commands. */
657
658 PyObject *
gdbpy_string_to_argv(PyObject * self,PyObject * args)659 gdbpy_string_to_argv (PyObject *self, PyObject *args)
660 {
661 PyObject *py_argv;
662 const char *input;
663
664 if (!PyArg_ParseTuple (args, "s", &input))
665 return NULL;
666
667 py_argv = PyList_New (0);
668
669 /* buildargv uses NULL to represent an empty argument list, but we can't use
670 that in Python. Instead, if ARGS is "" then return an empty list.
671 This undoes the NULL -> "" conversion that cmdpy_function does. */
672
673 if (*input != '\0')
674 {
675 char **c_argv = gdb_buildargv (input);
676 int i;
677
678 for (i = 0; c_argv[i] != NULL; ++i)
679 {
680 PyObject *argp = PyString_FromString (c_argv[i]);
681
682 if (argp == NULL
683 || PyList_Append (py_argv, argp) < 0)
684 {
685 Py_XDECREF (argp);
686 Py_DECREF (py_argv);
687 freeargv (c_argv);
688 return NULL;
689 }
690 Py_DECREF (argp);
691 }
692
693 freeargv (c_argv);
694 }
695
696 return py_argv;
697 }
698