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 /* Each command object has a local context attached to it.  */
 257 extern void set_cmd_context (struct cmd_list_element *cmd,
 258                              void *context);
 259 extern void *get_cmd_context (struct cmd_list_element *cmd);
 260
 261
 262 /* Execute CMD's pre/post hook.  Throw an error if the command fails.
 263    If already executing this pre/post hook, or there is no pre/post
 264    hook, the call is silently ignored.  */
 265 extern void execute_cmd_pre_hook (struct cmd_list_element *cmd);
 266 extern void execute_cmd_post_hook (struct cmd_list_element *cmd);
 267
 268 /* Flag for an ambiguous cmd_list result.  */
 269 #define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1)
 270
 271 extern struct cmd_list_element *lookup_cmd (const char **,
 272                                             struct cmd_list_element *,
 273                                             const char *,
 274                                             std::string *,
 275                                             int, int);
 276
 277 /* This routine takes a line of TEXT and a CLIST in which to start the
 278    lookup.  When it returns it will have incremented the text pointer past
 279    the section of text it matched, set *RESULT_LIST to point to the list in
 280    which the last word was matched, and will return a pointer to the cmd
 281    list element which the text matches.  It will return NULL if no match at
 282    all was possible.  It will return -1 (cast appropriately, ick) if ambigous
 283    matches are possible; in this case *RESULT_LIST will be set to point to
 284    the list in which there are ambiguous choices (and *TEXT will be set to
 285    the ambiguous text string).
 286
 287    if DEFAULT_ARGS is not null, *DEFAULT_ARGS is set to the found command
 288    default args (possibly empty).
 289
 290    If the located command was an abbreviation, this routine returns the base
 291    command of the abbreviation.  Note that *DEFAULT_ARGS will contain the
 292    default args defined for the alias.
 293
 294    It does no error reporting whatsoever; control will always return
 295    to the superior routine.
 296
 297    In the case of an ambiguous return (-1), *RESULT_LIST will be set to point
 298    at the prefix_command (ie. the best match) *or* (special case) will be NULL
 299    if no prefix command was ever found.  For example, in the case of "info a",
 300    "info" matches without ambiguity, but "a" could be "args" or "address", so
 301    *RESULT_LIST is set to the cmd_list_element for "info".  So in this case
 302    RESULT_LIST should not be interpreted as a pointer to the beginning of a
 303    list; it simply points to a specific command.  In the case of an ambiguous
 304    return *TEXT is advanced past the last non-ambiguous prefix (e.g.
 305    "info t" can be "info types" or "info target"; upon return *TEXT has been
 306    advanced past "info ").
 307
 308    If RESULT_LIST is NULL, don't set *RESULT_LIST (but don't otherwise
 309    affect the operation).
 310
 311    This routine does *not* modify the text pointed to by TEXT.
 312
 313    If IGNORE_HELP_CLASSES is nonzero, ignore any command list elements which
 314    are actually help classes rather than commands (i.e. the function field of
 315    the struct cmd_list_element is NULL).
 316
 317    When LOOKUP_FOR_COMPLETION_P is true the completion is being requested
 318    for the completion engine, no warnings should be printed.  */
 319
 320 extern struct cmd_list_element *lookup_cmd_1
 321         (const char **text, struct cmd_list_element *clist,
 322          struct cmd_list_element **result_list, std::string *default_args,
 323          int ignore_help_classes, bool lookup_for_completion_p = false);
 324
 325 /* Look up the command called NAME in the command list LIST.
 326
 327    Unlike LOOKUP_CMD, partial matches are ignored and only exact matches
 328    on NAME are considered.
 329
 330    LIST is a chain of struct cmd_list_element's.
 331
 332    If IGNORE_HELP_CLASSES is true (the default), ignore any command list
 333    elements which are actually help classes rather than commands (i.e.
 334    the function field of the struct cmd_list_element is null).
 335
 336    If found, return the struct cmd_list_element for that command,
 337    otherwise return NULLPTR.  */
 338
 339 extern struct cmd_list_element *lookup_cmd_exact
 340                         (const char *name,
 341                          struct cmd_list_element *list,
 342                          bool ignore_help_classes = true);
 343
 344 extern struct cmd_list_element *deprecate_cmd (struct cmd_list_element *,
 345                                                const char * );
 346
 347 extern void deprecated_cmd_warning (const char *, struct cmd_list_element *);
 348
 349 extern int lookup_cmd_composition (const char *text,
 350                                    struct cmd_list_element **alias,
 351                                    struct cmd_list_element **prefix_cmd,
 352                                    struct cmd_list_element **cmd);
 353
 354 extern struct cmd_list_element *add_com (const char *, enum command_class,
 355                                          cmd_const_cfunc_ftype *fun,
 356                                          const char *);
 357
 358 extern cmd_list_element *add_com_alias (const char *name,
 359                                         cmd_list_element *target,
 360                                         command_class theclass,
 361                                         int abbrev_flag);
 362
 363 extern struct cmd_list_element *add_com_suppress_notification
 364                        (const char *name, enum command_class theclass,
 365                         cmd_const_cfunc_ftype *fun, const char *doc,
 366                         int *supress_notification);
 367
 368 extern struct cmd_list_element *add_info (const char *,
 369                                           cmd_const_cfunc_ftype *fun,
 370                                           const char *);
 371
 372 extern cmd_list_element *add_info_alias (const char *name,
 373                                          cmd_list_element *target,
 374                                          int abbrev_flag);
 375
 376 extern void complete_on_cmdlist (struct cmd_list_element *,
 377                                  completion_tracker &tracker,
 378                                  const char *, const char *, int);
 379
 380 extern void complete_on_enum (completion_tracker &tracker,
 381                               const char *const *enumlist,
 382                               const char *, const char *);
 383
 384 /* Functions that implement commands about CLI commands.  */
 385
 386 extern void help_list (struct cmd_list_element *, const char *,
 387                        enum command_class, struct ui_file *);
 388
 389 /* Method for show a set/show variable's VALUE on FILE.  If this
 390    method isn't supplied deprecated_show_value_hack() is called (which
 391    is not good).  */
 392 typedef void (show_value_ftype) (struct ui_file *file,
 393                                  int from_tty,
 394                                  struct cmd_list_element *cmd,
 395                                  const char *value);
 396 /* NOTE: i18n: This function is not i18n friendly.  Callers should
 397    instead print the value out directly.  */
 398 extern show_value_ftype deprecated_show_value_hack;
 399
 400 /* Return value type for the add_setshow_* functions.  */
 401
 402 struct set_show_commands
 403 {
 404   cmd_list_element *set, *show;
 405 };
 406
 407 extern set_show_commands add_setshow_enum_cmd
 408   (const char *name, command_class theclass, const char *const *enumlist,
 409    const char **var, const char *set_doc, const char *show_doc,
 410    const char *help_doc, cmd_const_sfunc_ftype *set_func,
 411    show_value_ftype *show_func, cmd_list_element **set_list,
 412    cmd_list_element **show_list, void *context = nullptr);
 413
 414 extern set_show_commands add_setshow_auto_boolean_cmd
 415   (const char *name, command_class theclass, auto_boolean *var,
 416    const char *set_doc, const char *show_doc, const char *help_doc,
 417    cmd_const_sfunc_ftype *set_func, show_value_ftype *show_func,
 418    cmd_list_element **set_list, cmd_list_element **show_list);
 419
 420 extern set_show_commands add_setshow_boolean_cmd
 421   (const char *name, command_class theclass, bool *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_filename_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_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_string_noescape_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_optional_filename_cmd
 445   (const char *name, command_class theclass, char **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_integer_cmd
 451   (const char *name, command_class theclass, int *var, const char *set_doc,
 452    const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func,
 453    show_value_ftype *show_func, cmd_list_element **set_list,
 454    cmd_list_element **show_list);
 455
 456 extern set_show_commands add_setshow_uinteger_cmd
 457   (const char *name, command_class theclass, unsigned int *var,
 458    const char *set_doc, const char *show_doc, const char *help_doc,
 459    cmd_const_sfunc_ftype *set_func, show_value_ftype *show_func,
 460    cmd_list_element **set_list, cmd_list_element **show_list);
 461
 462 extern set_show_commands add_setshow_zinteger_cmd
 463   (const char *name, command_class theclass, int *var, const char *set_doc,
 464    const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func,
 465    show_value_ftype *show_func, cmd_list_element **set_list,
 466    cmd_list_element **show_list);
 467
 468 extern set_show_commands add_setshow_zuinteger_cmd
 469   (const char *name, command_class theclass, unsigned int *var,
 470    const char *set_doc, const char *show_doc, const char *help_doc,
 471    cmd_const_sfunc_ftype *set_func, show_value_ftype *show_func,
 472    cmd_list_element **set_list, cmd_list_element **show_list);
 473
 474 extern set_show_commands add_setshow_zuinteger_unlimited_cmd
 475   (const char *name, command_class theclass, int *var, const char *set_doc,
 476    const char *show_doc, const char *help_doc, cmd_const_sfunc_ftype *set_func,
 477    show_value_ftype *show_func, cmd_list_element **set_list,
 478    cmd_list_element **show_list);
 479
 480 /* Do a "show" command for each thing on a command list.  */
 481
 482 extern void cmd_show_list (struct cmd_list_element *, int);
 483
 484 /* Used everywhere whenever at least one parameter is required and
 485    none is specified.  */
 486
 487 extern void error_no_arg (const char *) ATTRIBUTE_NORETURN;
 488
 489
 490 /* Command line saving and repetition.
 491    Each input line executed is saved to possibly be repeated either
 492    when the user types an empty line, or be repeated by a command
 493    that wants to repeat the previously executed command.  The below
 494    functions control command repetition.  */
 495
 496 /* Commands call dont_repeat if they do not want to be repeated by null
 497    lines or by repeat_previous ().  */
 498
 499 extern void dont_repeat ();
 500
 501 /* Commands call repeat_previous if they want to repeat the previous
 502    command.  Such commands that repeat the previous command must
 503    indicate to not repeat themselves, to avoid recursive repeat.
 504    repeat_previous marks the current command as not repeating, and
 505    ensures get_saved_command_line returns the previous command, so
 506    that the currently executing command can repeat it.  If there's no
 507    previous command, throws an error.  Otherwise, returns the result
 508    of get_saved_command_line, which now points at the command to
 509    repeat.  */
 510
 511 extern const char *repeat_previous ();
 512
 513 /* Prevent dont_repeat from working, and return a cleanup that
 514    restores the previous state.  */
 515
 516 extern scoped_restore_tmpl<int> prevent_dont_repeat (void);
 517
 518 /* Set the arguments that will be passed if the current command is
 519    repeated.  Note that the passed-in string must be a constant.  */
 520
 521 extern void set_repeat_arguments (const char *args);
 522
 523 /* Returns the saved command line to repeat.
 524    When a command is being executed, this is the currently executing
 525    command line, unless the currently executing command has called
 526    repeat_previous (): in this case, get_saved_command_line returns
 527    the previously saved command line.  */
 528
 529 extern char *get_saved_command_line ();
 530
 531 /* Takes a copy of CMD, for possible repetition.  */
 532
 533 extern void save_command_line (const char *cmd);
 534
 535 /* Used to mark commands that don't do anything.  If we just leave the
 536    function field NULL, the command is interpreted as a help topic, or
 537    as a class of commands.  */
 538
 539 extern void not_just_help_class_command (const char *, int);
 540
 541 /* Call the command function.  */
 542 extern void cmd_func (struct cmd_list_element *cmd,
 543                       const char *args, int from_tty);
 544
 545 #endif /* !defined (COMMAND_H) */