1 /* Header file for command creation. 2 3 Copyright (C) 1986-2020 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 *, const char *, 178 enum command_class, int, 179 struct cmd_list_element **); 180 181 extern struct cmd_list_element *add_alias_cmd (const char *, 182 cmd_list_element *, 183 enum command_class, int, 184 struct cmd_list_element **); 185 186 187 extern struct cmd_list_element *add_prefix_cmd (const char *, enum command_class, 188 cmd_const_cfunc_ftype *fun, 189 const char *, 190 struct cmd_list_element **, 191 const char *, int, 192 struct cmd_list_element **); 193 194 /* Like add_prefix_cmd, but sets the callback to a function that 195 simply calls help_list. */ 196 197 extern struct cmd_list_element *add_basic_prefix_cmd 198 (const char *, enum command_class, const char *, struct cmd_list_element **, 199 const char *, int, struct cmd_list_element **); 200 201 /* Like add_prefix_cmd, but useful for "show" prefixes. This sets the 202 callback to a function that simply calls cmd_show_list. */ 203 204 extern struct cmd_list_element *add_show_prefix_cmd 205 (const char *, enum command_class, const char *, struct cmd_list_element **, 206 const char *, int, struct cmd_list_element **); 207 208 extern struct cmd_list_element *add_prefix_cmd_suppress_notification 209 (const char *name, enum command_class theclass, 210 cmd_const_cfunc_ftype *fun, 211 const char *doc, struct cmd_list_element **prefixlist, 212 const char *prefixname, int allow_unknown, 213 struct cmd_list_element **list, 214 int *suppress_notification); 215 216 extern struct cmd_list_element *add_abbrev_prefix_cmd (const char *, 217 enum command_class, 218 cmd_const_cfunc_ftype *fun, 219 const char *, 220 struct cmd_list_element 221 **, const char *, int, 222 struct cmd_list_element 223 **); 224 225 typedef void cmd_const_sfunc_ftype (const char *args, int from_tty, 226 struct cmd_list_element *c); 227 extern void set_cmd_sfunc (struct cmd_list_element *cmd, 228 cmd_const_sfunc_ftype *sfunc); 229 230 /* A completion routine. Add possible completions to tracker. 231 232 TEXT is the text beyond what was matched for the command itself 233 (leading whitespace is skipped). It stops where we are supposed to 234 stop completing (rl_point) and is '\0' terminated. WORD points in 235 the same buffer as TEXT, and completions should be returned 236 relative to this position. For example, suppose TEXT is "foo" and 237 we want to complete to "foobar". If WORD is "oo", return "oobar"; 238 if WORD is "baz/foo", return "baz/foobar". */ 239 typedef void completer_ftype (struct cmd_list_element *, 240 completion_tracker &tracker, 241 const char *text, const char *word); 242 243 /* Same, but for set_cmd_completer_handle_brkchars. */ 244 typedef void completer_handle_brkchars_ftype (struct cmd_list_element *, 245 completion_tracker &tracker, 246 const char *text, const char *word); 247 248 extern void set_cmd_completer (struct cmd_list_element *, completer_ftype *); 249 250 /* Set the completer_handle_brkchars callback. */ 251 252 extern void set_cmd_completer_handle_brkchars (struct cmd_list_element *, 253 completer_handle_brkchars_ftype *); 254 255 /* HACK: cagney/2002-02-23: Code, mostly in tracepoints.c, grubs 256 around in cmd objects to test the value of the commands sfunc(). */ 257 extern int cmd_cfunc_eq (struct cmd_list_element *cmd, 258 cmd_const_cfunc_ftype *cfun); 259 260 /* Each command object has a local context attached to it. */ 261 extern void set_cmd_context (struct cmd_list_element *cmd, 262 void *context); 263 extern void *get_cmd_context (struct cmd_list_element *cmd); 264 265 266 /* Execute CMD's pre/post hook. Throw an error if the command fails. 267 If already executing this pre/post hook, or there is no pre/post 268 hook, the call is silently ignored. */ 269 extern void execute_cmd_pre_hook (struct cmd_list_element *cmd); 270 extern void execute_cmd_post_hook (struct cmd_list_element *cmd); 271 272 /* Flag for an ambiguous cmd_list result. */ 273 #define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1) 274 275 extern struct cmd_list_element *lookup_cmd (const char **, 276 struct cmd_list_element *, 277 const char *, 278 std::string *, 279 int, int); 280 281 extern struct cmd_list_element *lookup_cmd_1 (const char **, 282 struct cmd_list_element *, 283 struct cmd_list_element **, 284 std::string *, 285 int); 286 287 extern struct cmd_list_element *deprecate_cmd (struct cmd_list_element *, 288 const char * ); 289 290 extern void deprecated_cmd_warning (const char *); 291 292 extern int lookup_cmd_composition (const char *text, 293 struct cmd_list_element **alias, 294 struct cmd_list_element **prefix_cmd, 295 struct cmd_list_element **cmd); 296 297 extern struct cmd_list_element *add_com (const char *, enum command_class, 298 cmd_const_cfunc_ftype *fun, 299 const char *); 300 301 extern struct cmd_list_element *add_com_alias (const char *, const char *, 302 enum command_class, int); 303 304 extern struct cmd_list_element *add_com_suppress_notification 305 (const char *name, enum command_class theclass, 306 cmd_const_cfunc_ftype *fun, const char *doc, 307 int *supress_notification); 308 309 extern struct cmd_list_element *add_info (const char *, 310 cmd_const_cfunc_ftype *fun, 311 const char *); 312 313 extern struct cmd_list_element *add_info_alias (const char *, const char *, 314 int); 315 316 extern void complete_on_cmdlist (struct cmd_list_element *, 317 completion_tracker &tracker, 318 const char *, const char *, int); 319 320 extern void complete_on_enum (completion_tracker &tracker, 321 const char *const *enumlist, 322 const char *, const char *); 323 324 /* Functions that implement commands about CLI commands. */ 325 326 extern void help_list (struct cmd_list_element *, const char *, 327 enum command_class, struct ui_file *); 328 329 /* Method for show a set/show variable's VALUE on FILE. If this 330 method isn't supplied deprecated_show_value_hack() is called (which 331 is not good). */ 332 typedef void (show_value_ftype) (struct ui_file *file, 333 int from_tty, 334 struct cmd_list_element *cmd, 335 const char *value); 336 /* NOTE: i18n: This function is not i18n friendly. Callers should 337 instead print the value out directly. */ 338 extern show_value_ftype deprecated_show_value_hack; 339 340 extern void add_setshow_enum_cmd (const char *name, 341 enum command_class theclass, 342 const char *const *enumlist, 343 const char **var, 344 const char *set_doc, 345 const char *show_doc, 346 const char *help_doc, 347 cmd_const_sfunc_ftype *set_func, 348 show_value_ftype *show_func, 349 struct cmd_list_element **set_list, 350 struct cmd_list_element **show_list, 351 void *context = nullptr); 352 353 extern void add_setshow_auto_boolean_cmd (const char *name, 354 enum command_class theclass, 355 enum auto_boolean *var, 356 const char *set_doc, 357 const char *show_doc, 358 const char *help_doc, 359 cmd_const_sfunc_ftype *set_func, 360 show_value_ftype *show_func, 361 struct cmd_list_element **set_list, 362 struct cmd_list_element **show_list); 363 364 extern cmd_list_element * 365 add_setshow_boolean_cmd (const char *name, 366 enum command_class theclass, 367 bool *var, 368 const char *set_doc, const char *show_doc, 369 const char *help_doc, 370 cmd_const_sfunc_ftype *set_func, 371 show_value_ftype *show_func, 372 struct cmd_list_element **set_list, 373 struct cmd_list_element **show_list); 374 375 extern void add_setshow_filename_cmd (const char *name, 376 enum command_class theclass, 377 char **var, 378 const char *set_doc, 379 const char *show_doc, 380 const char *help_doc, 381 cmd_const_sfunc_ftype *set_func, 382 show_value_ftype *show_func, 383 struct cmd_list_element **set_list, 384 struct cmd_list_element **show_list); 385 386 extern void add_setshow_string_cmd (const char *name, 387 enum command_class theclass, 388 char **var, 389 const char *set_doc, 390 const char *show_doc, 391 const char *help_doc, 392 cmd_const_sfunc_ftype *set_func, 393 show_value_ftype *show_func, 394 struct cmd_list_element **set_list, 395 struct cmd_list_element **show_list); 396 397 extern struct cmd_list_element *add_setshow_string_noescape_cmd 398 (const char *name, 399 enum command_class theclass, 400 char **var, 401 const char *set_doc, 402 const char *show_doc, 403 const char *help_doc, 404 cmd_const_sfunc_ftype *set_func, 405 show_value_ftype *show_func, 406 struct cmd_list_element **set_list, 407 struct cmd_list_element **show_list); 408 409 extern void add_setshow_optional_filename_cmd (const char *name, 410 enum command_class theclass, 411 char **var, 412 const char *set_doc, 413 const char *show_doc, 414 const char *help_doc, 415 cmd_const_sfunc_ftype *set_func, 416 show_value_ftype *show_func, 417 struct cmd_list_element **set_list, 418 struct cmd_list_element **show_list); 419 420 extern void add_setshow_integer_cmd (const char *name, 421 enum command_class theclass, 422 int *var, 423 const char *set_doc, 424 const char *show_doc, 425 const char *help_doc, 426 cmd_const_sfunc_ftype *set_func, 427 show_value_ftype *show_func, 428 struct cmd_list_element **set_list, 429 struct cmd_list_element **show_list); 430 431 extern void add_setshow_uinteger_cmd (const char *name, 432 enum command_class theclass, 433 unsigned int *var, 434 const char *set_doc, 435 const char *show_doc, 436 const char *help_doc, 437 cmd_const_sfunc_ftype *set_func, 438 show_value_ftype *show_func, 439 struct cmd_list_element **set_list, 440 struct cmd_list_element **show_list); 441 442 extern void add_setshow_zinteger_cmd (const char *name, 443 enum command_class theclass, 444 int *var, 445 const char *set_doc, 446 const char *show_doc, 447 const char *help_doc, 448 cmd_const_sfunc_ftype *set_func, 449 show_value_ftype *show_func, 450 struct cmd_list_element **set_list, 451 struct cmd_list_element **show_list); 452 453 extern void add_setshow_zuinteger_cmd (const char *name, 454 enum command_class theclass, 455 unsigned int *var, 456 const char *set_doc, 457 const char *show_doc, 458 const char *help_doc, 459 cmd_const_sfunc_ftype *set_func, 460 show_value_ftype *show_func, 461 struct cmd_list_element **set_list, 462 struct cmd_list_element **show_list); 463 464 extern void 465 add_setshow_zuinteger_unlimited_cmd (const char *name, 466 enum command_class theclass, 467 int *var, 468 const char *set_doc, 469 const char *show_doc, 470 const char *help_doc, 471 cmd_const_sfunc_ftype *set_func, 472 show_value_ftype *show_func, 473 struct cmd_list_element **set_list, 474 struct cmd_list_element **show_list); 475 476 /* Do a "show" command for each thing on a command list. */ 477 478 extern void cmd_show_list (struct cmd_list_element *, int); 479 480 /* Used everywhere whenever at least one parameter is required and 481 none is specified. */ 482 483 extern void error_no_arg (const char *) ATTRIBUTE_NORETURN; 484 485 486 /* Command line saving and repetition. 487 Each input line executed is saved to possibly be repeated either 488 when the user types an empty line, or be repeated by a command 489 that wants to repeat the previously executed command. The below 490 functions control command repetition. */ 491 492 /* Commands call dont_repeat if they do not want to be repeated by null 493 lines or by repeat_previous (). */ 494 495 extern void dont_repeat (); 496 497 /* Commands call repeat_previous if they want to repeat the previous 498 command. Such commands that repeat the previous command must 499 indicate to not repeat themselves, to avoid recursive repeat. 500 repeat_previous marks the current command as not repeating, and 501 ensures get_saved_command_line returns the previous command, so 502 that the currently executing command can repeat it. If there's no 503 previous command, throws an error. Otherwise, returns the result 504 of get_saved_command_line, which now points at the command to 505 repeat. */ 506 507 extern const char *repeat_previous (); 508 509 /* Prevent dont_repeat from working, and return a cleanup that 510 restores the previous state. */ 511 512 extern scoped_restore_tmpl<int> prevent_dont_repeat (void); 513 514 /* Set the arguments that will be passed if the current command is 515 repeated. Note that the passed-in string must be a constant. */ 516 517 extern void set_repeat_arguments (const char *args); 518 519 /* Returns the saved command line to repeat. 520 When a command is being executed, this is the currently executing 521 command line, unless the currently executing command has called 522 repeat_previous (): in this case, get_saved_command_line returns 523 the previously saved command line. */ 524 525 extern char *get_saved_command_line (); 526 527 /* Takes a copy of CMD, for possible repetition. */ 528 529 extern void save_command_line (const char *cmd); 530 531 /* Used to mark commands that don't do anything. If we just leave the 532 function field NULL, the command is interpreted as a help topic, or 533 as a class of commands. */ 534 535 extern void not_just_help_class_command (const char *, int); 536 537 /* Check function pointer. */ 538 extern int cmd_func_p (struct cmd_list_element *cmd); 539 540 /* Call the command function. */ 541 extern void cmd_func (struct cmd_list_element *cmd, 542 const char *args, int from_tty); 543 544 #endif /* !defined (COMMAND_H) */ 545