1 /* gdb commands implemented in Python 2 3 Copyright (C) 2008-2019 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 "python-internal.h" 25 #include "charset.h" 26 #include "gdbcmd.h" 27 #include "cli/cli-decode.h" 28 #include "completer.h" 29 #include "language.h" 30 31 /* Struct representing built-in completion types. */ 32 struct cmdpy_completer 33 { 34 /* Python symbol name. */ 35 const char *name; 36 /* Completion function. */ 37 completer_ftype *completer; 38 }; 39 40 static const struct cmdpy_completer completers[] = 41 { 42 { "COMPLETE_NONE", noop_completer }, 43 { "COMPLETE_FILENAME", filename_completer }, 44 { "COMPLETE_LOCATION", location_completer }, 45 { "COMPLETE_COMMAND", command_completer }, 46 { "COMPLETE_SYMBOL", symbol_completer }, 47 { "COMPLETE_EXPRESSION", expression_completer }, 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 extern PyTypeObject cmdpy_object_type 72 CPYCHECKER_TYPE_OBJECT_FOR_TYPEDEF ("cmdpy_object"); 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 gdbpy_enter enter_py (get_current_arch (), current_language); 96 97 /* Release our hold on the command object. */ 98 gdbpy_ref<cmdpy_object> cmd ((cmdpy_object *) context); 99 cmd->command = NULL; 100 101 /* We allocated the name, doc string, and perhaps the prefix 102 name. */ 103 xfree ((char *) self->name); 104 xfree ((char *) self->doc); 105 xfree ((char *) self->prefixname); 106 } 107 108 /* Called by gdb to invoke the command. */ 109 110 static void 111 cmdpy_function (struct cmd_list_element *command, 112 const char *args, int from_tty) 113 { 114 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command); 115 116 gdbpy_enter enter_py (get_current_arch (), current_language); 117 118 if (! obj) 119 error (_("Invalid invocation of Python command object.")); 120 if (! PyObject_HasAttr ((PyObject *) obj, invoke_cst)) 121 { 122 if (obj->command->prefixname) 123 { 124 /* A prefix command does not need an invoke method. */ 125 return; 126 } 127 error (_("Python command object missing 'invoke' method.")); 128 } 129 130 if (! args) 131 args = ""; 132 gdbpy_ref<> argobj (PyUnicode_Decode (args, strlen (args), host_charset (), 133 NULL)); 134 if (argobj == NULL) 135 { 136 gdbpy_print_stack (); 137 error (_("Could not convert arguments to Python string.")); 138 } 139 140 gdbpy_ref<> ttyobj 141 = gdbpy_ref<>::new_reference (from_tty ? Py_True : Py_False); 142 gdbpy_ref<> result (PyObject_CallMethodObjArgs ((PyObject *) obj, invoke_cst, 143 argobj.get (), ttyobj.get (), 144 NULL)); 145 146 if (result == NULL) 147 gdbpy_handle_exception (); 148 } 149 150 /* Helper function for the Python command completers (both "pure" 151 completer and brkchar handler). This function takes COMMAND, TEXT 152 and WORD and tries to call the Python method for completion with 153 these arguments. 154 155 This function is usually called twice: once when we are figuring out 156 the break characters to be used, and another to perform the real 157 completion itself. The reason for this two step dance is that we 158 need to know the set of "brkchars" to use early on, before we 159 actually try to perform the completion. But if a Python command 160 supplies a "complete" method then we have to call that method 161 first: it may return as its result the kind of completion to 162 perform and that will in turn specify which brkchars to use. IOW, 163 we need the result of the "complete" method before we actually 164 perform the completion. The only situation when this function is 165 not called twice is when the user uses the "complete" command: in 166 this scenario, there is no call to determine the "brkchars". 167 168 Ideally, it would be nice to cache the result of the first call (to 169 determine the "brkchars") and return this value directly in the 170 second call (to perform the actual completion). However, due to 171 the peculiarity of the "complete" command mentioned above, it is 172 possible to put GDB in a bad state if you perform a TAB-completion 173 and then a "complete"-completion sequentially. Therefore, we just 174 recalculate everything twice for TAB-completions. 175 176 This function returns a reference to the PyObject representing the 177 Python method call. */ 178 179 static gdbpy_ref<> 180 cmdpy_completer_helper (struct cmd_list_element *command, 181 const char *text, const char *word) 182 { 183 cmdpy_object *obj = (cmdpy_object *) get_cmd_context (command); 184 185 if (obj == NULL) 186 error (_("Invalid invocation of Python command object.")); 187 if (!PyObject_HasAttr ((PyObject *) obj, complete_cst)) 188 { 189 /* If there is no complete method, don't error. */ 190 return NULL; 191 } 192 193 gdbpy_ref<> textobj (PyUnicode_Decode (text, strlen (text), host_charset (), 194 NULL)); 195 if (textobj == NULL) 196 error (_("Could not convert argument to Python string.")); 197 198 gdbpy_ref<> wordobj; 199 if (word == NULL) 200 { 201 /* "brkchars" phase. */ 202 wordobj = gdbpy_ref<>::new_reference (Py_None); 203 } 204 else 205 { 206 wordobj.reset (PyUnicode_Decode (word, strlen (word), host_charset (), 207 NULL)); 208 if (wordobj == NULL) 209 error (_("Could not convert argument to Python string.")); 210 } 211 212 gdbpy_ref<> resultobj (PyObject_CallMethodObjArgs ((PyObject *) obj, 213 complete_cst, 214 textobj.get (), 215 wordobj.get (), NULL)); 216 if (resultobj == NULL) 217 { 218 /* Just swallow errors here. */ 219 PyErr_Clear (); 220 } 221 222 return resultobj; 223 } 224 225 /* Python function called to determine the break characters of a 226 certain completer. We are only interested in knowing if the 227 completer registered by the user will return one of the integer 228 codes (see COMPLETER_* symbols). */ 229 230 static void 231 cmdpy_completer_handle_brkchars (struct cmd_list_element *command, 232 completion_tracker &tracker, 233 const char *text, const char *word) 234 { 235 gdbpy_enter enter_py (get_current_arch (), current_language); 236 237 /* Calling our helper to obtain a reference to the PyObject of the Python 238 function. */ 239 gdbpy_ref<> resultobj = cmdpy_completer_helper (command, text, word); 240 241 /* Check if there was an error. */ 242 if (resultobj == NULL) 243 return; 244 245 if (PyInt_Check (resultobj.get ())) 246 { 247 /* User code may also return one of the completion constants, 248 thus requesting that sort of completion. We are only 249 interested in this kind of return. */ 250 long value; 251 252 if (!gdb_py_int_as_long (resultobj.get (), &value)) 253 { 254 /* Ignore. */ 255 PyErr_Clear (); 256 } 257 else if (value >= 0 && value < (long) N_COMPLETERS) 258 { 259 completer_handle_brkchars_ftype *brkchars_fn; 260 261 /* This is the core of this function. Depending on which 262 completer type the Python function returns, we have to 263 adjust the break characters accordingly. */ 264 brkchars_fn = (completer_handle_brkchars_func_for_completer 265 (completers[value].completer)); 266 brkchars_fn (command, tracker, text, word); 267 } 268 } 269 } 270 271 /* Called by gdb for command completion. */ 272 273 static void 274 cmdpy_completer (struct cmd_list_element *command, 275 completion_tracker &tracker, 276 const char *text, const char *word) 277 { 278 gdbpy_enter enter_py (get_current_arch (), current_language); 279 280 /* Calling our helper to obtain a reference to the PyObject of the Python 281 function. */ 282 gdbpy_ref<> resultobj = cmdpy_completer_helper (command, text, word); 283 284 /* If the result object of calling the Python function is NULL, it 285 means that there was an error. In this case, just give up. */ 286 if (resultobj == NULL) 287 return; 288 289 if (PyInt_Check (resultobj.get ())) 290 { 291 /* User code may also return one of the completion constants, 292 thus requesting that sort of completion. */ 293 long value; 294 295 if (! gdb_py_int_as_long (resultobj.get (), &value)) 296 { 297 /* Ignore. */ 298 PyErr_Clear (); 299 } 300 else if (value >= 0 && value < (long) N_COMPLETERS) 301 completers[value].completer (command, tracker, text, word); 302 } 303 else 304 { 305 gdbpy_ref<> iter (PyObject_GetIter (resultobj.get ())); 306 307 if (iter == NULL) 308 return; 309 310 bool got_matches = false; 311 while (true) 312 { 313 gdbpy_ref<> elt (PyIter_Next (iter.get ())); 314 if (elt == NULL) 315 break; 316 317 if (! gdbpy_is_string (elt.get ())) 318 { 319 /* Skip problem elements. */ 320 continue; 321 } 322 gdb::unique_xmalloc_ptr<char> 323 item (python_string_to_host_string (elt.get ())); 324 if (item == NULL) 325 { 326 /* Skip problem elements. */ 327 PyErr_Clear (); 328 continue; 329 } 330 tracker.add_completion (std::move (item)); 331 got_matches = true; 332 } 333 334 /* If we got some results, ignore problems. Otherwise, report 335 the problem. */ 336 if (got_matches && PyErr_Occurred ()) 337 PyErr_Clear (); 338 } 339 } 340 341 /* Helper for cmdpy_init which locates the command list to use and 342 pulls out the command name. 343 344 NAME is the command name list. The final word in the list is the 345 name of the new command. All earlier words must be existing prefix 346 commands. 347 348 *BASE_LIST is set to the final prefix command's list of 349 *sub-commands. 350 351 START_LIST is the list in which the search starts. 352 353 This function returns the xmalloc()d name of the new command. On 354 error sets the Python error and returns NULL. */ 355 356 char * 357 gdbpy_parse_command_name (const char *name, 358 struct cmd_list_element ***base_list, 359 struct cmd_list_element **start_list) 360 { 361 struct cmd_list_element *elt; 362 int len = strlen (name); 363 int i, lastchar; 364 const char *prefix_text2; 365 char *result; 366 367 /* Skip trailing whitespace. */ 368 for (i = len - 1; i >= 0 && (name[i] == ' ' || name[i] == '\t'); --i) 369 ; 370 if (i < 0) 371 { 372 PyErr_SetString (PyExc_RuntimeError, _("No command name found.")); 373 return NULL; 374 } 375 lastchar = i; 376 377 /* Find first character of the final word. */ 378 for (; i > 0 && (isalnum (name[i - 1]) 379 || name[i - 1] == '-' 380 || name[i - 1] == '_'); 381 --i) 382 ; 383 result = (char *) xmalloc (lastchar - i + 2); 384 memcpy (result, &name[i], lastchar - i + 1); 385 result[lastchar - i + 1] = '\0'; 386 387 /* Skip whitespace again. */ 388 for (--i; i >= 0 && (name[i] == ' ' || name[i] == '\t'); --i) 389 ; 390 if (i < 0) 391 { 392 *base_list = start_list; 393 return result; 394 } 395 396 std::string prefix_text (name, i + 1); 397 398 prefix_text2 = prefix_text.c_str (); 399 elt = lookup_cmd_1 (&prefix_text2, *start_list, NULL, 1); 400 if (elt == NULL || elt == CMD_LIST_AMBIGUOUS) 401 { 402 PyErr_Format (PyExc_RuntimeError, _("Could not find command prefix %s."), 403 prefix_text.c_str ()); 404 xfree (result); 405 return NULL; 406 } 407 408 if (elt->prefixlist) 409 { 410 *base_list = elt->prefixlist; 411 return result; 412 } 413 414 PyErr_Format (PyExc_RuntimeError, _("'%s' is not a prefix command."), 415 prefix_text.c_str ()); 416 xfree (result); 417 return NULL; 418 } 419 420 /* Object initializer; sets up gdb-side structures for command. 421 422 Use: __init__(NAME, COMMAND_CLASS [, COMPLETER_CLASS][, PREFIX]]). 423 424 NAME is the name of the command. It may consist of multiple words, 425 in which case the final word is the name of the new command, and 426 earlier words must be prefix commands. 427 428 COMMAND_CLASS is the kind of command. It should be one of the COMMAND_* 429 constants defined in the gdb module. 430 431 COMPLETER_CLASS is the kind of completer. If not given, the 432 "complete" method will be used. Otherwise, it should be one of the 433 COMPLETE_* constants defined in the gdb module. 434 435 If PREFIX is True, then this command is a prefix command. 436 437 The documentation for the command is taken from the doc string for 438 the python class. */ 439 440 static int 441 cmdpy_init (PyObject *self, PyObject *args, PyObject *kw) 442 { 443 cmdpy_object *obj = (cmdpy_object *) self; 444 const char *name; 445 int cmdtype; 446 int completetype = -1; 447 char *docstring = NULL; 448 struct cmd_list_element **cmd_list; 449 char *cmd_name, *pfx_name; 450 static const char *keywords[] = { "name", "command_class", "completer_class", 451 "prefix", NULL }; 452 PyObject *is_prefix = NULL; 453 int cmp; 454 455 if (obj->command) 456 { 457 /* Note: this is apparently not documented in Python. We return 458 0 for success, -1 for failure. */ 459 PyErr_Format (PyExc_RuntimeError, 460 _("Command object already initialized.")); 461 return -1; 462 } 463 464 if (!gdb_PyArg_ParseTupleAndKeywords (args, kw, "si|iO", 465 keywords, &name, &cmdtype, 466 &completetype, &is_prefix)) 467 return -1; 468 469 if (cmdtype != no_class && cmdtype != class_run 470 && cmdtype != class_vars && cmdtype != class_stack 471 && cmdtype != class_files && cmdtype != class_support 472 && cmdtype != class_info && cmdtype != class_breakpoint 473 && cmdtype != class_trace && cmdtype != class_obscure 474 && cmdtype != class_maintenance && cmdtype != class_user) 475 { 476 PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument.")); 477 return -1; 478 } 479 480 if (completetype < -1 || completetype >= (int) N_COMPLETERS) 481 { 482 PyErr_Format (PyExc_RuntimeError, 483 _("Invalid completion type argument.")); 484 return -1; 485 } 486 487 cmd_name = gdbpy_parse_command_name (name, &cmd_list, &cmdlist); 488 if (! cmd_name) 489 return -1; 490 491 pfx_name = NULL; 492 if (is_prefix != NULL) 493 { 494 cmp = PyObject_IsTrue (is_prefix); 495 if (cmp == 1) 496 { 497 int i, out; 498 499 /* Make a normalized form of the command name. */ 500 pfx_name = (char *) xmalloc (strlen (name) + 2); 501 502 i = 0; 503 out = 0; 504 while (name[i]) 505 { 506 /* Skip whitespace. */ 507 while (name[i] == ' ' || name[i] == '\t') 508 ++i; 509 /* Copy non-whitespace characters. */ 510 while (name[i] && name[i] != ' ' && name[i] != '\t') 511 pfx_name[out++] = name[i++]; 512 /* Add a single space after each word -- including the final 513 word. */ 514 pfx_name[out++] = ' '; 515 } 516 pfx_name[out] = '\0'; 517 } 518 else if (cmp < 0) 519 { 520 xfree (cmd_name); 521 return -1; 522 } 523 } 524 if (PyObject_HasAttr (self, gdbpy_doc_cst)) 525 { 526 gdbpy_ref<> ds_obj (PyObject_GetAttr (self, gdbpy_doc_cst)); 527 528 if (ds_obj != NULL && gdbpy_is_string (ds_obj.get ())) 529 { 530 docstring = python_string_to_host_string (ds_obj.get ()).release (); 531 if (docstring == NULL) 532 { 533 xfree (cmd_name); 534 xfree (pfx_name); 535 return -1; 536 } 537 } 538 } 539 if (! docstring) 540 docstring = xstrdup (_("This command is not documented.")); 541 542 gdbpy_ref<> self_ref = gdbpy_ref<>::new_reference (self); 543 544 TRY 545 { 546 struct cmd_list_element *cmd; 547 548 if (pfx_name) 549 { 550 int allow_unknown; 551 552 /* If we have our own "invoke" method, then allow unknown 553 sub-commands. */ 554 allow_unknown = PyObject_HasAttr (self, invoke_cst); 555 cmd = add_prefix_cmd (cmd_name, (enum command_class) cmdtype, 556 NULL, docstring, &obj->sub_list, 557 pfx_name, allow_unknown, cmd_list); 558 } 559 else 560 cmd = add_cmd (cmd_name, (enum command_class) cmdtype, 561 docstring, cmd_list); 562 563 /* There appears to be no API to set this. */ 564 cmd->func = cmdpy_function; 565 cmd->destroyer = cmdpy_destroyer; 566 567 obj->command = cmd; 568 set_cmd_context (cmd, self_ref.release ()); 569 set_cmd_completer (cmd, ((completetype == -1) ? cmdpy_completer 570 : completers[completetype].completer)); 571 if (completetype == -1) 572 set_cmd_completer_handle_brkchars (cmd, 573 cmdpy_completer_handle_brkchars); 574 } 575 CATCH (except, RETURN_MASK_ALL) 576 { 577 xfree (cmd_name); 578 xfree (docstring); 579 xfree (pfx_name); 580 gdbpy_convert_exception (except); 581 return -1; 582 } 583 END_CATCH 584 585 return 0; 586 } 587 588 589 590 /* Initialize the 'commands' code. */ 591 592 int 593 gdbpy_initialize_commands (void) 594 { 595 int i; 596 597 cmdpy_object_type.tp_new = PyType_GenericNew; 598 if (PyType_Ready (&cmdpy_object_type) < 0) 599 return -1; 600 601 /* Note: alias and user are special; pseudo appears to be unused, 602 and there is no reason to expose tui, I think. */ 603 if (PyModule_AddIntConstant (gdb_module, "COMMAND_NONE", no_class) < 0 604 || PyModule_AddIntConstant (gdb_module, "COMMAND_RUNNING", class_run) < 0 605 || PyModule_AddIntConstant (gdb_module, "COMMAND_DATA", class_vars) < 0 606 || PyModule_AddIntConstant (gdb_module, "COMMAND_STACK", class_stack) < 0 607 || PyModule_AddIntConstant (gdb_module, "COMMAND_FILES", class_files) < 0 608 || PyModule_AddIntConstant (gdb_module, "COMMAND_SUPPORT", 609 class_support) < 0 610 || PyModule_AddIntConstant (gdb_module, "COMMAND_STATUS", class_info) < 0 611 || PyModule_AddIntConstant (gdb_module, "COMMAND_BREAKPOINTS", 612 class_breakpoint) < 0 613 || PyModule_AddIntConstant (gdb_module, "COMMAND_TRACEPOINTS", 614 class_trace) < 0 615 || PyModule_AddIntConstant (gdb_module, "COMMAND_OBSCURE", 616 class_obscure) < 0 617 || PyModule_AddIntConstant (gdb_module, "COMMAND_MAINTENANCE", 618 class_maintenance) < 0 619 || PyModule_AddIntConstant (gdb_module, "COMMAND_USER", class_user) < 0) 620 return -1; 621 622 for (i = 0; i < N_COMPLETERS; ++i) 623 { 624 if (PyModule_AddIntConstant (gdb_module, completers[i].name, i) < 0) 625 return -1; 626 } 627 628 if (gdb_pymodule_addobject (gdb_module, "Command", 629 (PyObject *) &cmdpy_object_type) < 0) 630 return -1; 631 632 invoke_cst = PyString_FromString ("invoke"); 633 if (invoke_cst == NULL) 634 return -1; 635 complete_cst = PyString_FromString ("complete"); 636 if (complete_cst == NULL) 637 return -1; 638 639 return 0; 640 } 641 642 643 644 static PyMethodDef cmdpy_object_methods[] = 645 { 646 { "dont_repeat", cmdpy_dont_repeat, METH_NOARGS, 647 "Prevent command repetition when user enters empty line." }, 648 649 { 0 } 650 }; 651 652 PyTypeObject cmdpy_object_type = 653 { 654 PyVarObject_HEAD_INIT (NULL, 0) 655 "gdb.Command", /*tp_name*/ 656 sizeof (cmdpy_object), /*tp_basicsize*/ 657 0, /*tp_itemsize*/ 658 0, /*tp_dealloc*/ 659 0, /*tp_print*/ 660 0, /*tp_getattr*/ 661 0, /*tp_setattr*/ 662 0, /*tp_compare*/ 663 0, /*tp_repr*/ 664 0, /*tp_as_number*/ 665 0, /*tp_as_sequence*/ 666 0, /*tp_as_mapping*/ 667 0, /*tp_hash */ 668 0, /*tp_call*/ 669 0, /*tp_str*/ 670 0, /*tp_getattro*/ 671 0, /*tp_setattro*/ 672 0, /*tp_as_buffer*/ 673 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/ 674 "GDB command object", /* tp_doc */ 675 0, /* tp_traverse */ 676 0, /* tp_clear */ 677 0, /* tp_richcompare */ 678 0, /* tp_weaklistoffset */ 679 0, /* tp_iter */ 680 0, /* tp_iternext */ 681 cmdpy_object_methods, /* tp_methods */ 682 0, /* tp_members */ 683 0, /* tp_getset */ 684 0, /* tp_base */ 685 0, /* tp_dict */ 686 0, /* tp_descr_get */ 687 0, /* tp_descr_set */ 688 0, /* tp_dictoffset */ 689 cmdpy_init, /* tp_init */ 690 0, /* tp_alloc */ 691 }; 692 693 694 695 /* Utility to build a buildargv-like result from ARGS. 696 This intentionally parses arguments the way libiberty/argv.c:buildargv 697 does. It splits up arguments in a reasonable way, and we want a standard 698 way of parsing arguments. Several gdb commands use buildargv to parse their 699 arguments. Plus we want to be able to write compatible python 700 implementations of gdb commands. */ 701 702 PyObject * 703 gdbpy_string_to_argv (PyObject *self, PyObject *args) 704 { 705 const char *input; 706 707 if (!PyArg_ParseTuple (args, "s", &input)) 708 return NULL; 709 710 gdbpy_ref<> py_argv (PyList_New (0)); 711 if (py_argv == NULL) 712 return NULL; 713 714 /* buildargv uses NULL to represent an empty argument list, but we can't use 715 that in Python. Instead, if ARGS is "" then return an empty list. 716 This undoes the NULL -> "" conversion that cmdpy_function does. */ 717 718 if (*input != '\0') 719 { 720 gdb_argv c_argv (input); 721 722 for (char *arg : c_argv) 723 { 724 gdbpy_ref<> argp (PyString_FromString (arg)); 725 726 if (argp == NULL 727 || PyList_Append (py_argv.get (), argp.get ()) < 0) 728 return NULL; 729 } 730 } 731 732 return py_argv.release (); 733 } 734