gdb/command.h

   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) */