1 /* Header file for command creation. 2 3 Copyright (C) 1986-2021 Free Software Foundation, Inc. 4 5 This program is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 3 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 17 18 #if !defined (COMMAND_H) 19 #define COMMAND_H 1 20 21 #include "gdbsupport/gdb_vecs.h" 22 #include "gdbsupport/scoped_restore.h" 23 24 struct completion_tracker; 25 26 /* This file defines the public interface for any code wanting to 27 create commands. */ 28 29 /* Command classes are top-level categories into which commands are 30 broken down for "help" purposes. 31 32 The class_alias is used for the user-defined aliases, defined 33 using the "alias" command. 34 35 Aliases pre-defined by GDB (e.g. the alias "bt" of the "backtrace" command) 36 are not using the class_alias. 37 Different pre-defined aliases of the same command do not necessarily 38 have the same classes. For example, class_stack is used for the 39 "backtrace" and its "bt" alias", while "info stack" (also an alias 40 of "backtrace" uses class_info. */ 41 42 enum command_class 43 { 44 /* Classes of commands followed by a comment giving the name 45 to use in "help <classname>". 46 Note that help accepts unambiguous abbreviated class names. */ 47 48 /* Special classes to help_list */ 49 class_deprecated = -3, 50 all_classes = -2, /* help without <classname> */ 51 all_commands = -1, /* all */ 52 53 /* Classes of commands */ 54 no_class = -1, 55 class_run = 0, /* running */ 56 class_vars, /* data */ 57 class_stack, /* stack */ 58 class_files, /* files */ 59 class_support, /* support */ 60 class_info, /* status */ 61 class_breakpoint, /* breakpoints */ 62 class_trace, /* tracepoints */ 63 class_alias, /* aliases */ 64 class_bookmark, 65 class_obscure, /* obscure */ 66 class_maintenance, /* internals */ 67 class_tui, /* text-user-interface */ 68 class_user, /* user-defined */ 69 70 /* Used for "show" commands that have no corresponding "set" command. */ 71 no_set_class 72 }; 73 74 /* Types of "set" or "show" command. */ 75 typedef enum var_types 76 { 77 /* "on" or "off". *VAR is a bool which is true for on, 78 false for off. */ 79 var_boolean, 80 81 /* "on" / "true" / "enable" or "off" / "false" / "disable" or 82 "auto. *VAR is an ``enum auto_boolean''. NOTE: In general a 83 custom show command will need to be implemented - one that for 84 "auto" prints both the "auto" and the current auto-selected 85 value. */ 86 var_auto_boolean, 87 88 /* Unsigned Integer. *VAR is an unsigned int. The user can type 89 0 to mean "unlimited", which is stored in *VAR as UINT_MAX. */ 90 var_uinteger, 91 92 /* Like var_uinteger but signed. *VAR is an int. The user can 93 type 0 to mean "unlimited", which is stored in *VAR as 94 INT_MAX. The only remaining use of it is the Python API. 95 Don't use it elsewhere. */ 96 var_integer, 97 98 /* String which the user enters with escapes (e.g. the user types 99 \n and it is a real newline in the stored string). 100 *VAR is a malloc'd string, or NULL if the string is empty. */ 101 var_string, 102 /* String which stores what the user types verbatim. 103 *VAR is a malloc'd string, or NULL if the string is empty. */ 104 var_string_noescape, 105 /* String which stores a filename. (*VAR) is a malloc'd string, 106 or "" if the string was empty. */ 107 var_optional_filename, 108 /* String which stores a filename. (*VAR) is a malloc'd 109 string. */ 110 var_filename, 111 /* ZeroableInteger. *VAR is an int. Like var_integer except 112 that zero really means zero. */ 113 var_zinteger, 114 /* ZeroableUnsignedInteger. *VAR is an unsigned int. Zero really 115 means zero. */ 116 var_zuinteger, 117 /* ZeroableUnsignedInteger with unlimited value. *VAR is an int, 118 but its range is [0, INT_MAX]. -1 stands for unlimited and 119 other negative numbers are not allowed. */ 120 var_zuinteger_unlimited, 121 /* Enumerated type. Can only have one of the specified values. 122 *VAR is a char pointer to the name of the element that we 123 find. */ 124 var_enum 125 } 126 var_types; 127 128 /* This structure records one command'd definition. */ 129 struct cmd_list_element; 130 131 typedef void cmd_const_cfunc_ftype (const char *args, int from_tty); 132 133 /* This structure specifies notifications to be suppressed by a cli 134 command interpreter. */ 135 136 struct cli_suppress_notification 137 { 138 /* Inferior, thread, frame selected notification suppressed? */ 139 int user_selected_context; 140 }; 141 142 extern struct cli_suppress_notification cli_suppress_notification; 143 144 /* Forward-declarations of the entry-points of cli/cli-decode.c. */ 145 146 /* API to the manipulation of command lists. */ 147 148 /* Return TRUE if NAME is a valid user-defined command name. 149 This is a stricter subset of all gdb commands, 150 see find_command_name_length. */ 151 152 extern bool valid_user_defined_cmd_name_p (const char *name); 153 154 /* Return TRUE if C is a valid command character. */ 155 156 extern bool valid_cmd_char_p (int c); 157 158 /* Const-correct variant of the above. */ 159 160 extern struct cmd_list_element *add_cmd (const char *, enum command_class, 161 cmd_const_cfunc_ftype *fun, 162 const char *, 163 struct cmd_list_element **); 164 165 /* Like add_cmd, but no command function is specified. */ 166 167 extern struct cmd_list_element *add_cmd (const char *, enum command_class, 168 const char *, 169 struct cmd_list_element **); 170 171 extern struct cmd_list_element *add_cmd_suppress_notification 172 (const char *name, enum command_class theclass, 173 cmd_const_cfunc_ftype *fun, const char *doc, 174 struct cmd_list_element **list, 175 int *suppress_notification); 176 177 extern struct cmd_list_element *add_alias_cmd (const char *, 178 cmd_list_element *, 179 enum command_class, int, 180 struct cmd_list_element **); 181 182 183 extern struct cmd_list_element *add_prefix_cmd (const char *, enum command_class, 184 cmd_const_cfunc_ftype *fun, 185 const char *, 186 struct cmd_list_element **, 187 int, 188 struct cmd_list_element **); 189 190 /* Like add_prefix_cmd, but sets the callback to a function that 191 simply calls help_list. */ 192 193 extern struct cmd_list_element *add_basic_prefix_cmd 194 (const char *, enum command_class, const char *, struct cmd_list_element **, 195 int, struct cmd_list_element **); 196 197 /* Like add_prefix_cmd, but useful for "show" prefixes. This sets the 198 callback to a function that simply calls cmd_show_list. */ 199 200 extern struct cmd_list_element *add_show_prefix_cmd 201 (const char *, enum command_class, const char *, struct cmd_list_element **, 202 int, struct cmd_list_element **); 203 204 extern struct cmd_list_element *add_prefix_cmd_suppress_notification 205 (const char *name, enum command_class theclass, 206 cmd_const_cfunc_ftype *fun, 207 const char *doc, struct cmd_list_element **subcommands, 208 int allow_unknown, 209 struct cmd_list_element **list, 210 int *suppress_notification); 211 212 extern struct cmd_list_element *add_abbrev_prefix_cmd (const char *, 213 enum command_class, 214 cmd_const_cfunc_ftype *fun, 215 const char *, 216 struct cmd_list_element 217 **, int, 218 struct cmd_list_element 219 **); 220 221 typedef void cmd_const_sfunc_ftype (const char *args, int from_tty, 222 struct cmd_list_element *c); 223 extern void set_cmd_sfunc (struct cmd_list_element *cmd, 224 cmd_const_sfunc_ftype *sfunc); 225 226 /* A completion routine. Add possible completions to tracker. 227 228 TEXT is the text beyond what was matched for the command itself 229 (leading whitespace is skipped). It stops where we are supposed to 230 stop completing (rl_point) and is '\0' terminated. WORD points in 231 the same buffer as TEXT, and completions should be returned 232 relative to this position. For example, suppose TEXT is "foo" and 233 we want to complete to "foobar". If WORD is "oo", return "oobar"; 234 if WORD is "baz/foo", return "baz/foobar". */ 235 typedef void completer_ftype (struct cmd_list_element *, 236 completion_tracker &tracker, 237 const char *text, const char *word); 238 239 /* Same, but for set_cmd_completer_handle_brkchars. */ 240 typedef void completer_handle_brkchars_ftype (struct cmd_list_element *, 241 completion_tracker &tracker, 242 const char *text, const char *word); 243 244 extern void set_cmd_completer (struct cmd_list_element *, completer_ftype *); 245 246 /* Set the completer_handle_brkchars callback. */ 247 248 extern void set_cmd_completer_handle_brkchars (struct cmd_list_element *, 249 completer_handle_brkchars_ftype *); 250 251 /* HACK: cagney/2002-02-23: Code, mostly in tracepoints.c, grubs 252 around in cmd objects to test the value of the commands sfunc(). */ 253 extern int cmd_cfunc_eq (struct cmd_list_element *cmd, 254 cmd_const_cfunc_ftype *cfun); 255 256 /* Execute CMD's pre/post hook. Throw an error if the command fails. 257 If already executing this pre/post hook, or there is no pre/post 258 hook, the call is silently ignored. */ 259 extern void execute_cmd_pre_hook (struct cmd_list_element *cmd); 260 extern void execute_cmd_post_hook (struct cmd_list_element *cmd); 261 262 /* Flag for an ambiguous cmd_list result. */ 263 #define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1) 264 265 extern struct cmd_list_element *lookup_cmd (const char **, 266 struct cmd_list_element *, 267 const char *, 268 std::string *, 269 int, int); 270 271 /* This routine takes a line of TEXT and a CLIST in which to start the 272 lookup. When it returns it will have incremented the text pointer past 273 the section of text it matched, set *RESULT_LIST to point to the list in 274 which the last word was matched, and will return a pointer to the cmd 275 list element which the text matches. It will return NULL if no match at 276 all was possible. It will return -1 (cast appropriately, ick) if ambigous 277 matches are possible; in this case *RESULT_LIST will be set to point to 278 the list in which there are ambiguous choices (and *TEXT will be set to 279 the ambiguous text string). 280 281 if DEFAULT_ARGS is not null, *DEFAULT_ARGS is set to the found command 282 default args (possibly empty). 283 284 If the located command was an abbreviation, this routine returns the base 285 command of the abbreviation. Note that *DEFAULT_ARGS will contain the 286 default args defined for the alias. 287 288 It does no error reporting whatsoever; control will always return 289 to the superior routine. 290 291 In the case of an ambiguous return (-1), *RESULT_LIST will be set to point 292 at the prefix_command (ie. the best match) *or* (special case) will be NULL 293 if no prefix command was ever found. For example, in the case of "info a", 294 "info" matches without ambiguity, but "a" could be "args" or "address", so 295 *RESULT_LIST is set to the cmd_list_element for "info". So in this case 296 RESULT_LIST should not be interpreted as a pointer to the beginning of a 297 list; it simply points to a specific command. In the case of an ambiguous 298 return *TEXT is advanced past the last non-ambiguous prefix (e.g. 299 "info t" can be "info types" or "info target"; upon return *TEXT has been 300 advanced past "info "). 301 302 If RESULT_LIST is NULL, don't set *RESULT_LIST (but don't otherwise 303 affect the operation). 304 305 This routine does *not* modify the text pointed to by TEXT. 306 307 If IGNORE_HELP_CLASSES is nonzero, ignore any command list elements which 308 are actually help classes rather than commands (i.e. the function field of 309 the struct cmd_list_element is NULL). 310 311 When LOOKUP_FOR_COMPLETION_P is true the completion is being requested 312 for the completion engine, no warnings should be printed. */ 313 314 extern struct cmd_list_element *lookup_cmd_1 315 (const char **text, struct cmd_list_element *clist, 316 struct cmd_list_element **result_list, std::string *default_args, 317 int ignore_help_classes, bool lookup_for_completion_p = false); 318 319 /* Look up the command called NAME in the command list LIST. 320 321 Unlike LOOKUP_CMD, partial matches are ignored and only exact matches 322 on NAME are considered. 323 324 LIST is a chain of struct cmd_list_element's. 325 326 If IGNORE_HELP_CLASSES is true (the default), ignore any command list 327 elements which are actually help classes rather than commands (i.e. 328 the function field of the struct cmd_list_element is null). 329 330 If found, return the struct cmd_list_element for that command, 331 otherwise return NULLPTR. */ 332 333 extern struct cmd_list_element *lookup_cmd_exact 334 (const char *name, 335 struct cmd_list_element *list, 336 bool ignore_help_classes = true); 337 338 extern struct cmd_list_element *deprecate_cmd (struct cmd_list_element *, 339 const char * ); 340 341 extern void deprecated_cmd_warning (const char *, struct cmd_list_element *); 342 343 extern int lookup_cmd_composition (const char *text, 344 struct cmd_list_element **alias, 345 struct cmd_list_element **prefix_cmd, 346 struct cmd_list_element **cmd); 347 348 extern struct cmd_list_element *add_com (const char *, enum command_class, 349 cmd_const_cfunc_ftype *fun, 350 const char *); 351 352 extern cmd_list_element *add_com_alias (const char *name, 353 cmd_list_element *target, 354 command_class theclass, 355 int abbrev_flag); 356 357 extern struct cmd_list_element *add_com_suppress_notification 358 (const char *name, enum command_class theclass, 359 cmd_const_cfunc_ftype *fun, const char *doc, 360 int *supress_notification); 361 362 extern struct cmd_list_element *add_info (const char *, 363 cmd_const_cfunc_ftype *fun, 364 const char *); 365 366 extern cmd_list_element *add_info_alias (const char *name, 367 cmd_list_element *target, 368 int abbrev_flag); 369 370 extern void complete_on_cmdlist (struct cmd_list_element *, 371 completion_tracker &tracker, 372 const char *, const char *, int); 373 374 extern void complete_on_enum (completion_tracker &tracker, 375 const char *const *enumlist, 376 const char *, const char *); 377 378 /* Functions that implement commands about CLI commands. */ 379 380 extern void help_list (struct cmd_list_element *, const char *, 381 enum command_class, struct ui_file *); 382 383 /* Method for show a set/show variable's VALUE on FILE. If this 384 method isn't supplied deprecated_show_value_hack() is called (which 385 is not good). */ 386 typedef void (show_value_ftype) (struct ui_file *file, 387 int from_tty, 388 struct cmd_list_element *cmd, 389 const char *value); 390 /* NOTE: i18n: This function is not i18n friendly. Callers should 391 instead print the value out directly. */ 392 extern show_value_ftype deprecated_show_value_hack; 393 394 /* Return value type for the add_setshow_* functions. */ 395 396 struct set_show_commands 397 { 398 cmd_list_element *set, *show; 399 }; 400 401 extern set_show_commands add_setshow_enum_cmd 402 (const char *name, command_class theclass, const char *const *enumlist, 403 const char **var, const char *set_doc, const char *show_doc, 404 const char *help_doc, cmd_const_sfunc_ftype *set_func, 405 show_value_ftype *show_func, cmd_list_element **set_list, 406 cmd_list_element **show_list); 407 408 extern set_show_commands add_setshow_auto_boolean_cmd 409 (const char *name, command_class theclass, auto_boolean *var, 410 const char *set_doc, const char *show_doc, const char *help_doc, 411 cmd_const_sfunc_ftype *set_func, show_value_ftype *show_func, 412 cmd_list_element **set_list, cmd_list_element **show_list); 413 414 extern set_show_commands add_setshow_boolean_cmd 415 (const char *name, command_class theclass, bool *var, const char *set_doc, 416 const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, 417 show_value_ftype *show_func, cmd_list_element **set_list, 418 cmd_list_element **show_list); 419 420 extern set_show_commands add_setshow_filename_cmd 421 (const char *name, command_class theclass, char **var, const char *set_doc, 422 const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, 423 show_value_ftype *show_func, cmd_list_element **set_list, 424 cmd_list_element **show_list); 425 426 extern set_show_commands add_setshow_string_cmd 427 (const char *name, command_class theclass, char **var, const char *set_doc, 428 const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, 429 show_value_ftype *show_func, cmd_list_element **set_list, 430 cmd_list_element **show_list); 431 432 extern set_show_commands add_setshow_string_noescape_cmd 433 (const char *name, command_class theclass, char **var, const char *set_doc, 434 const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, 435 show_value_ftype *show_func, cmd_list_element **set_list, 436 cmd_list_element **show_list); 437 438 extern set_show_commands add_setshow_optional_filename_cmd 439 (const char *name, command_class theclass, char **var, const char *set_doc, 440 const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, 441 show_value_ftype *show_func, cmd_list_element **set_list, 442 cmd_list_element **show_list); 443 444 extern set_show_commands add_setshow_integer_cmd 445 (const char *name, command_class theclass, int *var, const char *set_doc, 446 const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, 447 show_value_ftype *show_func, cmd_list_element **set_list, 448 cmd_list_element **show_list); 449 450 extern set_show_commands add_setshow_uinteger_cmd 451 (const char *name, command_class theclass, unsigned int *var, 452 const char *set_doc, const char *show_doc, const char *help_doc, 453 cmd_const_sfunc_ftype *set_func, show_value_ftype *show_func, 454 cmd_list_element **set_list, cmd_list_element **show_list); 455 456 extern set_show_commands add_setshow_zinteger_cmd 457 (const char *name, command_class theclass, int *var, const char *set_doc, 458 const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, 459 show_value_ftype *show_func, cmd_list_element **set_list, 460 cmd_list_element **show_list); 461 462 extern set_show_commands add_setshow_zuinteger_cmd 463 (const char *name, command_class theclass, unsigned int *var, 464 const char *set_doc, const char *show_doc, const char *help_doc, 465 cmd_const_sfunc_ftype *set_func, show_value_ftype *show_func, 466 cmd_list_element **set_list, cmd_list_element **show_list); 467 468 extern set_show_commands add_setshow_zuinteger_unlimited_cmd 469 (const char *name, command_class theclass, int *var, const char *set_doc, 470 const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func, 471 show_value_ftype *show_func, cmd_list_element **set_list, 472 cmd_list_element **show_list); 473 474 /* Do a "show" command for each thing on a command list. */ 475 476 extern void cmd_show_list (struct cmd_list_element *, int); 477 478 /* Used everywhere whenever at least one parameter is required and 479 none is specified. */ 480 481 extern void error_no_arg (const char *) ATTRIBUTE_NORETURN; 482 483 484 /* Command line saving and repetition. 485 Each input line executed is saved to possibly be repeated either 486 when the user types an empty line, or be repeated by a command 487 that wants to repeat the previously executed command. The below 488 functions control command repetition. */ 489 490 /* Commands call dont_repeat if they do not want to be repeated by null 491 lines or by repeat_previous (). */ 492 493 extern void dont_repeat (); 494 495 /* Commands call repeat_previous if they want to repeat the previous 496 command. Such commands that repeat the previous command must 497 indicate to not repeat themselves, to avoid recursive repeat. 498 repeat_previous marks the current command as not repeating, and 499 ensures get_saved_command_line returns the previous command, so 500 that the currently executing command can repeat it. If there's no 501 previous command, throws an error. Otherwise, returns the result 502 of get_saved_command_line, which now points at the command to 503 repeat. */ 504 505 extern const char *repeat_previous (); 506 507 /* Prevent dont_repeat from working, and return a cleanup that 508 restores the previous state. */ 509 510 extern scoped_restore_tmpl<int> prevent_dont_repeat (void); 511 512 /* Set the arguments that will be passed if the current command is 513 repeated. Note that the passed-in string must be a constant. */ 514 515 extern void set_repeat_arguments (const char *args); 516 517 /* Returns the saved command line to repeat. 518 When a command is being executed, this is the currently executing 519 command line, unless the currently executing command has called 520 repeat_previous (): in this case, get_saved_command_line returns 521 the previously saved command line. */ 522 523 extern char *get_saved_command_line (); 524 525 /* Takes a copy of CMD, for possible repetition. */ 526 527 extern void save_command_line (const char *cmd); 528 529 /* Used to mark commands that don't do anything. If we just leave the 530 function field NULL, the command is interpreted as a help topic, or 531 as a class of commands. */ 532 533 extern void not_just_help_class_command (const char *, int); 534 535 /* Call the command function. */ 536 extern void cmd_func (struct cmd_list_element *cmd, 537 const char *args, int from_tty); 538 539 #endif /* !defined (COMMAND_H) */ 540