1 /* gdb commands implemented in Python 2 3 Copyright (C) 2008, 2009, 2010, 2011 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 char **(*completer) (struct cmd_list_element *, char *, char *); 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 74 /* Constants used by this module. */ 75 static PyObject *invoke_cst; 76 static PyObject *complete_cst; 77 78 79 80 /* Python function which wraps dont_repeat. */ 81 static PyObject * 82 cmdpy_dont_repeat (PyObject *self, PyObject *args) 83 { 84 dont_repeat (); 85 Py_RETURN_NONE; 86 } 87 88 89 90 /* Called if the gdb cmd_list_element is destroyed. */ 91 92 static void 93 cmdpy_destroyer (struct cmd_list_element *self, void *context) 94 { 95 cmdpy_object *cmd; 96 struct cleanup *cleanup; 97 98 cleanup = ensure_python_env (get_current_arch (), current_language); 99 100 /* Release our hold on the command object. */ 101 cmd = (cmdpy_object *) context; 102 cmd->command = NULL; 103 Py_DECREF (cmd); 104 105 /* We allocated the name, doc string, and perhaps the prefix 106 name. */ 107 xfree (self->name); 108 xfree (self->doc); 109 xfree (self->prefixname); 110 111 do_cleanups (cleanup); 112 } 113 114 /* Called by gdb to invoke the command. */ 115 116 static void 117 cmdpy_function (struct cmd_list_element *command, char *args, int from_tty) 118 { 119 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command); 120 PyObject *argobj, *ttyobj, *result; 121 struct cleanup *cleanup; 122 123 cleanup = ensure_python_env (get_current_arch (), current_language); 124 125 if (! obj) 126 error (_("Invalid invocation of Python command object.")); 127 if (! PyObject_HasAttr ((PyObject *) obj, invoke_cst)) 128 { 129 if (obj->command->prefixname) 130 { 131 /* A prefix command does not need an invoke method. */ 132 do_cleanups (cleanup); 133 return; 134 } 135 error (_("Python command object missing 'invoke' method.")); 136 } 137 138 if (! args) 139 args = ""; 140 argobj = PyUnicode_Decode (args, strlen (args), host_charset (), NULL); 141 if (! argobj) 142 { 143 gdbpy_print_stack (); 144 error (_("Could not convert arguments to Python string.")); 145 } 146 147 ttyobj = from_tty ? Py_True : Py_False; 148 Py_INCREF (ttyobj); 149 result = PyObject_CallMethodObjArgs ((PyObject *) obj, invoke_cst, argobj, 150 ttyobj, NULL); 151 Py_DECREF (argobj); 152 Py_DECREF (ttyobj); 153 154 if (! result) 155 { 156 PyObject *ptype, *pvalue, *ptraceback; 157 char *msg; 158 159 PyErr_Fetch (&ptype, &pvalue, &ptraceback); 160 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. */ 164 165 msg = gdbpy_exception_to_string (ptype, pvalue); 166 make_cleanup (xfree, msg); 167 168 if (msg == NULL) 169 { 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 (); 176 } 177 178 /* Don't print the stack for gdb.GdbError exceptions. 179 It is generally used to flag user errors. 180 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. */ 184 185 if (! PyErr_GivenExceptionMatches (ptype, gdbpy_gdberror_exc) 186 || msg == NULL || *msg == '\0') 187 { 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); 192 else 193 error (_("Error occurred in Python command.")); 194 } 195 else 196 { 197 Py_XDECREF (ptype); 198 Py_XDECREF (pvalue); 199 Py_XDECREF (ptraceback); 200 error ("%s", msg); 201 } 202 } 203 204 Py_DECREF (result); 205 do_cleanups (cleanup); 206 } 207 208 /* Called by gdb for command completion. */ 209 static char ** 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 char **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 result = (char **) xmalloc ((len + 1) * sizeof (char *)); 257 for (i = out = 0; i < len; ++i) 258 { 259 PyObject *elt = PySequence_GetItem (resultobj, i); 260 261 if (elt == NULL || ! gdbpy_is_string (elt)) 262 { 263 /* Skip problem elements. */ 264 PyErr_Clear (); 265 continue; 266 } 267 result[out] = python_string_to_host_string (elt); 268 if (result[out] == NULL) 269 { 270 /* Skip problem elements. */ 271 PyErr_Clear (); 272 continue; 273 } 274 ++out; 275 } 276 result[out] = NULL; 277 } 278 else if (PyInt_Check (resultobj)) 279 { 280 /* User code may also return one of the completion constants, 281 thus requesting that sort of completion. */ 282 long value; 283 284 if (! gdb_py_int_as_long (resultobj, &value)) 285 { 286 /* Ignore. */ 287 PyErr_Clear (); 288 } 289 else if (value >= 0 && value < (long) N_COMPLETERS) 290 result = completers[value].completer (command, text, word); 291 } 292 293 done: 294 295 do_cleanups (cleanup); 296 297 return result; 298 } 299 300 /* Helper for cmdpy_init which locates the command list to use and 301 pulls out the command name. 302 303 TEXT is the command name list. The final word in the list is the 304 name of the new command. All earlier words must be existing prefix 305 commands. 306 307 *BASE_LIST is set to the final prefix command's list of 308 *sub-commands. 309 310 START_LIST is the list in which the search starts. 311 312 This function returns the xmalloc()d name of the new command. On 313 error sets the Python error and returns NULL. */ 314 char * 315 gdbpy_parse_command_name (char *text, 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 (text); 321 int i, lastchar; 322 char *prefix_text; 323 char *result; 324 325 /* Skip trailing whitespace. */ 326 for (i = len - 1; i >= 0 && (text[i] == ' ' || text[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 (text[i - 1]) 337 || text[i - 1] == '-' 338 || text[i - 1] == '_'); 339 --i) 340 ; 341 result = xmalloc (lastchar - i + 2); 342 memcpy (result, &text[i], lastchar - i + 1); 343 result[lastchar - i + 1] = '\0'; 344 345 /* Skip whitespace again. */ 346 for (--i; i >= 0 && (text[i] == ' ' || text[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, text, i + 1); 356 prefix_text[i + 1] = '\0'; 357 358 text = prefix_text; 359 elt = lookup_cmd_1 (&text, *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 */ 404 static int 405 cmdpy_init (PyObject *self, PyObject *args, PyObject *kw) 406 { 407 cmdpy_object *obj = (cmdpy_object *) self; 408 char *name; 409 int cmdtype; 410 int completetype = -1; 411 char *docstring = NULL; 412 volatile struct gdb_exception except; 413 struct cmd_list_element **cmd_list; 414 char *cmd_name, *pfx_name; 415 static char *keywords[] = { "name", "command_class", "completer_class", 416 "prefix", NULL }; 417 PyObject *is_prefix = NULL; 418 int cmp; 419 420 if (obj->command) 421 { 422 /* Note: this is apparently not documented in Python. We return 423 0 for success, -1 for failure. */ 424 PyErr_Format (PyExc_RuntimeError, 425 _("Command object already initialized.")); 426 return -1; 427 } 428 429 if (! PyArg_ParseTupleAndKeywords (args, kw, "si|iO", 430 keywords, &name, &cmdtype, 431 &completetype, &is_prefix)) 432 return -1; 433 434 if (cmdtype != no_class && cmdtype != class_run 435 && cmdtype != class_vars && cmdtype != class_stack 436 && cmdtype != class_files && cmdtype != class_support 437 && cmdtype != class_info && cmdtype != class_breakpoint 438 && cmdtype != class_trace && cmdtype != class_obscure 439 && cmdtype != class_maintenance) 440 { 441 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument.")); 442 return -1; 443 } 444 445 if (completetype < -1 || completetype >= (int) N_COMPLETERS) 446 { 447 PyErr_Format (PyExc_RuntimeError, 448 _("Invalid completion type argument.")); 449 return -1; 450 } 451 452 cmd_name = gdbpy_parse_command_name (name, &cmd_list, &cmdlist); 453 if (! cmd_name) 454 return -1; 455 456 pfx_name = NULL; 457 if (is_prefix != NULL) 458 { 459 cmp = PyObject_IsTrue (is_prefix); 460 if (cmp == 1) 461 { 462 int i, out; 463 464 /* Make a normalized form of the command name. */ 465 pfx_name = xmalloc (strlen (name) + 2); 466 467 i = 0; 468 out = 0; 469 while (name[i]) 470 { 471 /* Skip whitespace. */ 472 while (name[i] == ' ' || name[i] == '\t') 473 ++i; 474 /* Copy non-whitespace characters. */ 475 while (name[i] && name[i] != ' ' && name[i] != '\t') 476 pfx_name[out++] = name[i++]; 477 /* Add a single space after each word -- including the final 478 word. */ 479 pfx_name[out++] = ' '; 480 } 481 pfx_name[out] = '\0'; 482 } 483 else if (cmp < 0) 484 { 485 xfree (cmd_name); 486 return -1; 487 } 488 } 489 if (PyObject_HasAttr (self, gdbpy_doc_cst)) 490 { 491 PyObject *ds_obj = PyObject_GetAttr (self, gdbpy_doc_cst); 492 493 if (ds_obj && gdbpy_is_string (ds_obj)) 494 { 495 docstring = python_string_to_host_string (ds_obj); 496 if (docstring == NULL) 497 { 498 xfree (cmd_name); 499 xfree (pfx_name); 500 return -1; 501 } 502 } 503 } 504 if (! docstring) 505 docstring = xstrdup (_("This command is not documented.")); 506 507 Py_INCREF (self); 508 509 TRY_CATCH (except, RETURN_MASK_ALL) 510 { 511 struct cmd_list_element *cmd; 512 513 if (pfx_name) 514 { 515 int allow_unknown; 516 517 /* If we have our own "invoke" method, then allow unknown 518 sub-commands. */ 519 allow_unknown = PyObject_HasAttr (self, invoke_cst); 520 cmd = add_prefix_cmd (cmd_name, (enum command_class) cmdtype, 521 NULL, docstring, &obj->sub_list, 522 pfx_name, allow_unknown, cmd_list); 523 } 524 else 525 cmd = add_cmd (cmd_name, (enum command_class) cmdtype, NULL, 526 docstring, cmd_list); 527 528 /* There appears to be no API to set this. */ 529 cmd->func = cmdpy_function; 530 cmd->destroyer = cmdpy_destroyer; 531 532 obj->command = cmd; 533 set_cmd_context (cmd, self); 534 set_cmd_completer (cmd, ((completetype == -1) ? cmdpy_completer 535 : completers[completetype].completer)); 536 } 537 if (except.reason < 0) 538 { 539 xfree (cmd_name); 540 xfree (docstring); 541 xfree (pfx_name); 542 Py_DECREF (self); 543 PyErr_Format (except.reason == RETURN_QUIT 544 ? PyExc_KeyboardInterrupt : PyExc_RuntimeError, 545 "%s", except.message); 546 return -1; 547 } 548 return 0; 549 } 550 551 552 553 /* Initialize the 'commands' code. */ 554 void 555 gdbpy_initialize_commands (void) 556 { 557 int i; 558 559 if (PyType_Ready (&cmdpy_object_type) < 0) 560 return; 561 562 /* Note: alias and user are special; pseudo appears to be unused, 563 and there is no reason to expose tui or xdb, I think. */ 564 if (PyModule_AddIntConstant (gdb_module, "COMMAND_NONE", no_class) < 0 565 || PyModule_AddIntConstant (gdb_module, "COMMAND_RUNNING", class_run) < 0 566 || PyModule_AddIntConstant (gdb_module, "COMMAND_DATA", class_vars) < 0 567 || PyModule_AddIntConstant (gdb_module, "COMMAND_STACK", class_stack) < 0 568 || PyModule_AddIntConstant (gdb_module, "COMMAND_FILES", class_files) < 0 569 || PyModule_AddIntConstant (gdb_module, "COMMAND_SUPPORT", 570 class_support) < 0 571 || PyModule_AddIntConstant (gdb_module, "COMMAND_STATUS", class_info) < 0 572 || PyModule_AddIntConstant (gdb_module, "COMMAND_BREAKPOINTS", 573 class_breakpoint) < 0 574 || PyModule_AddIntConstant (gdb_module, "COMMAND_TRACEPOINTS", 575 class_trace) < 0 576 || PyModule_AddIntConstant (gdb_module, "COMMAND_OBSCURE", 577 class_obscure) < 0 578 || PyModule_AddIntConstant (gdb_module, "COMMAND_MAINTENANCE", 579 class_maintenance) < 0) 580 return; 581 582 for (i = 0; i < N_COMPLETERS; ++i) 583 { 584 if (PyModule_AddIntConstant (gdb_module, completers[i].name, i) < 0) 585 return; 586 } 587 588 Py_INCREF (&cmdpy_object_type); 589 PyModule_AddObject (gdb_module, "Command", 590 (PyObject *) &cmdpy_object_type); 591 592 invoke_cst = PyString_FromString ("invoke"); 593 complete_cst = PyString_FromString ("complete"); 594 } 595 596 597 598 static PyMethodDef cmdpy_object_methods[] = 599 { 600 { "dont_repeat", cmdpy_dont_repeat, METH_NOARGS, 601 "Prevent command repetition when user enters empty line." }, 602 603 { 0 } 604 }; 605 606 static PyTypeObject cmdpy_object_type = 607 { 608 PyObject_HEAD_INIT (NULL) 609 0, /*ob_size*/ 610 "gdb.Command", /*tp_name*/ 611 sizeof (cmdpy_object), /*tp_basicsize*/ 612 0, /*tp_itemsize*/ 613 0, /*tp_dealloc*/ 614 0, /*tp_print*/ 615 0, /*tp_getattr*/ 616 0, /*tp_setattr*/ 617 0, /*tp_compare*/ 618 0, /*tp_repr*/ 619 0, /*tp_as_number*/ 620 0, /*tp_as_sequence*/ 621 0, /*tp_as_mapping*/ 622 0, /*tp_hash */ 623 0, /*tp_call*/ 624 0, /*tp_str*/ 625 0, /*tp_getattro*/ 626 0, /*tp_setattro*/ 627 0, /*tp_as_buffer*/ 628 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/ 629 "GDB command object", /* tp_doc */ 630 0, /* tp_traverse */ 631 0, /* tp_clear */ 632 0, /* tp_richcompare */ 633 0, /* tp_weaklistoffset */ 634 0, /* tp_iter */ 635 0, /* tp_iternext */ 636 cmdpy_object_methods, /* tp_methods */ 637 0, /* tp_members */ 638 0, /* tp_getset */ 639 0, /* tp_base */ 640 0, /* tp_dict */ 641 0, /* tp_descr_get */ 642 0, /* tp_descr_set */ 643 0, /* tp_dictoffset */ 644 cmdpy_init, /* tp_init */ 645 0, /* tp_alloc */ 646 PyType_GenericNew /* tp_new */ 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 * 659 gdbpy_string_to_argv (PyObject *self, PyObject *args) 660 { 661 PyObject *py_argv; 662 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 if (argp != NULL) 686 { 687 Py_DECREF (argp); 688 } 689 Py_DECREF (py_argv); 690 freeargv (c_argv); 691 return NULL; 692 } 693 } 694 695 freeargv (c_argv); 696 } 697 698 return py_argv; 699 } 700