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