gdb/command.h

   1 /* Header file for command creation.
   2
   3    Copyright (C) 1986-2017 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 "gdb_vecs.h"
  22 #include "common/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    Notes on classes: class_alias is for alias commands which are not
  33    abbreviations of the original command.  class-pseudo is for
  34    commands which are not really commands nor help topics ("stop").  */
  35
  36 enum command_class
  37 {
  38   /* Special args to help_list */
  39   class_deprecated = -3, all_classes = -2, all_commands = -1,
  40   /* Classes of commands */
  41   no_class = -1, class_run = 0, class_vars, class_stack, class_files,
  42   class_support, class_info, class_breakpoint, class_trace,
  43   class_alias, class_bookmark, class_obscure, class_maintenance,
  44   class_pseudo, class_tui, class_user, class_xdb,
  45   no_set_class  /* Used for "show" commands that have no corresponding
  46                    "set" command.  */
  47 };
  48
  49 /* FIXME: cagney/2002-03-17: Once cmd_type() has been removed, ``enum
  50    cmd_types'' can be moved from "command.h" to "cli-decode.h".  */
  51 /* Not a set/show command.  Note that some commands which begin with
  52    "set" or "show" might be in this category, if their syntax does
  53    not fall into one of the following categories.  */
  54 typedef enum cmd_types
  55   {
  56     not_set_cmd,
  57     set_cmd,
  58     show_cmd
  59   }
  60 cmd_types;
  61
  62 /* Types of "set" or "show" command.  */
  63 typedef enum var_types
  64   {
  65     /* "on" or "off".  *VAR is an integer which is nonzero for on,
  66        zero for off.  */
  67     var_boolean,
  68
  69     /* "on" / "true" / "enable" or "off" / "false" / "disable" or
  70        "auto.  *VAR is an ``enum auto_boolean''.  NOTE: In general a
  71        custom show command will need to be implemented - one that for
  72        "auto" prints both the "auto" and the current auto-selected
  73        value.  */
  74     var_auto_boolean,
  75
  76     /* Unsigned Integer.  *VAR is an unsigned int.  The user can type
  77        0 to mean "unlimited", which is stored in *VAR as UINT_MAX.  */
  78     var_uinteger,
  79
  80     /* Like var_uinteger but signed.  *VAR is an int.  The user can
  81        type 0 to mean "unlimited", which is stored in *VAR as
  82        INT_MAX.  The only remaining use of it is the Python API.
  83        Don't use it elsewhere.  */
  84     var_integer,
  85
  86     /* String which the user enters with escapes (e.g. the user types
  87        \n and it is a real newline in the stored string).
  88        *VAR is a malloc'd string, or NULL if the string is empty.  */
  89     var_string,
  90     /* String which stores what the user types verbatim.
  91        *VAR is a malloc'd string, or NULL if the string is empty.  */
  92     var_string_noescape,
  93     /* String which stores a filename.  (*VAR) is a malloc'd string,
  94        or "" if the string was empty.  */
  95     var_optional_filename,
  96     /* String which stores a filename.  (*VAR) is a malloc'd
  97        string.  */
  98     var_filename,
  99     /* ZeroableInteger.  *VAR is an int.  Like var_integer except
 100        that zero really means zero.  */
 101     var_zinteger,
 102     /* ZeroableUnsignedInteger.  *VAR is an unsigned int.  Zero really
 103        means zero.  */
 104     var_zuinteger,
 105     /* ZeroableUnsignedInteger with unlimited value.  *VAR is an int,
 106        but its range is [0, INT_MAX].  -1 stands for unlimited and
 107        other negative numbers are not allowed.  */
 108     var_zuinteger_unlimited,
 109     /* Enumerated type.  Can only have one of the specified values.
 110        *VAR is a char pointer to the name of the element that we
 111        find.  */
 112     var_enum
 113   }
 114 var_types;
 115
 116 /* This structure records one command'd definition.  */
 117 struct cmd_list_element;
 118
 119 typedef void cmd_const_cfunc_ftype (const char *args, int from_tty);
 120
 121 /* This structure specifies notifications to be suppressed by a cli
 122    command interpreter.  */
 123
 124 struct cli_suppress_notification
 125 {
 126   /* Inferior, thread, frame selected notification suppressed?  */
 127   int user_selected_context;
 128 };
 129
 130 extern struct cli_suppress_notification cli_suppress_notification;
 131
 132 /* Forward-declarations of the entry-points of cli/cli-decode.c.  */
 133
 134 /* API to the manipulation of command lists.  */
 135
 136 extern int valid_user_defined_cmd_name_p (const char *name);
 137
 138 /* Const-correct variant of the above.  */
 139
 140 extern struct cmd_list_element *add_cmd (const char *, enum command_class,
 141                                          cmd_const_cfunc_ftype *fun,
 142                                          const char *,
 143                                          struct cmd_list_element **);
 144
 145 /* Like add_cmd, but no command function is specified.  */
 146
 147 extern struct cmd_list_element *add_cmd (const char *, enum command_class,
 148                                          const char *,
 149                                          struct cmd_list_element **);
 150
 151 extern struct cmd_list_element *add_alias_cmd (const char *, const char *,
 152                                                enum command_class, int,
 153                                                struct cmd_list_element **);
 154
 155 extern struct cmd_list_element *add_alias_cmd (const char *,
 156                                                cmd_list_element *,
 157                                                enum command_class, int,
 158                                                struct cmd_list_element **);
 159
 160
 161 extern struct cmd_list_element *add_prefix_cmd (const char *, enum command_class,
 162                                                 cmd_const_cfunc_ftype *fun,
 163                                                 const char *,
 164                                                 struct cmd_list_element **,
 165                                                 const char *, int,
 166                                                 struct cmd_list_element **);
 167
 168 extern struct cmd_list_element *add_abbrev_prefix_cmd (const char *,
 169                                                        enum command_class,
 170                                                        cmd_const_cfunc_ftype *fun,
 171                                                        const char *,
 172                                                        struct cmd_list_element
 173                                                        **, const char *, int,
 174                                                        struct cmd_list_element
 175                                                        **);
 176
 177 typedef void cmd_const_sfunc_ftype (const char *args, int from_tty,
 178                                     struct cmd_list_element *c);
 179 extern void set_cmd_sfunc (struct cmd_list_element *cmd,
 180                            cmd_const_sfunc_ftype *sfunc);
 181
 182 /* A completion routine.  Add possible completions to tracker.
 183
 184    TEXT is the text beyond what was matched for the command itself
 185    (leading whitespace is skipped).  It stops where we are supposed to
 186    stop completing (rl_point) and is '\0' terminated.  WORD points in
 187    the same buffer as TEXT, and completions should be returned
 188    relative to this position.  For example, suppose TEXT is "foo" and
 189    we want to complete to "foobar".  If WORD is "oo", return "oobar";
 190    if WORD is "baz/foo", return "baz/foobar".  */
 191 typedef void completer_ftype (struct cmd_list_element *,
 192                               completion_tracker &tracker,
 193                               const char *text, const char *word);
 194
 195 /* Same, but for set_cmd_completer_handle_brkchars.  */
 196 typedef void completer_handle_brkchars_ftype (struct cmd_list_element *,
 197                                               completion_tracker &tracker,
 198                                               const char *text, const char *word);
 199
 200 extern void set_cmd_completer (struct cmd_list_element *, completer_ftype *);
 201
 202 /* Set the completer_handle_brkchars callback.  */
 203
 204 extern void set_cmd_completer_handle_brkchars (struct cmd_list_element *,
 205                                                completer_handle_brkchars_ftype *);
 206
 207 /* HACK: cagney/2002-02-23: Code, mostly in tracepoints.c, grubs
 208    around in cmd objects to test the value of the commands sfunc().  */
 209 extern int cmd_cfunc_eq (struct cmd_list_element *cmd,
 210                          cmd_const_cfunc_ftype *cfun);
 211
 212 /* Each command object has a local context attached to it.  */
 213 extern void set_cmd_context (struct cmd_list_element *cmd,
 214                              void *context);
 215 extern void *get_cmd_context (struct cmd_list_element *cmd);
 216
 217
 218 /* Execute CMD's pre/post hook.  Throw an error if the command fails.
 219    If already executing this pre/post hook, or there is no pre/post
 220    hook, the call is silently ignored.  */
 221 extern void execute_cmd_pre_hook (struct cmd_list_element *cmd);
 222 extern void execute_cmd_post_hook (struct cmd_list_element *cmd);
 223
 224 /* Return the type of the command.  */
 225 extern enum cmd_types cmd_type (struct cmd_list_element *cmd);
 226
 227 /* Flag for an ambiguous cmd_list result.  */
 228 #define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1)
 229
 230 extern struct cmd_list_element *lookup_cmd (const char **,
 231                                             struct cmd_list_element *,
 232                                             const char *,
 233                                             int, int);
 234
 235 extern struct cmd_list_element *lookup_cmd_1 (const char **,
 236                                               struct cmd_list_element *,
 237                                               struct cmd_list_element **,
 238                                               int);
 239
 240 extern struct cmd_list_element *deprecate_cmd (struct cmd_list_element *,
 241                                                const char * );
 242
 243 extern void deprecated_cmd_warning (const char *);
 244
 245 extern int lookup_cmd_composition (const char *text,
 246                                    struct cmd_list_element **alias,
 247                                    struct cmd_list_element **prefix_cmd,
 248                                    struct cmd_list_element **cmd);
 249
 250 extern struct cmd_list_element *add_com (const char *, enum command_class,
 251                                          cmd_const_cfunc_ftype *fun,
 252                                          const char *);
 253
 254 extern struct cmd_list_element *add_com_alias (const char *, const char *,
 255                                                enum command_class, int);
 256
 257 extern struct cmd_list_element *add_com_suppress_notification
 258                        (const char *name, enum command_class theclass,
 259                         cmd_const_cfunc_ftype *fun, const char *doc,
 260                         int *supress_notification);
 261
 262 extern struct cmd_list_element *add_info (const char *,
 263                                           cmd_const_cfunc_ftype *fun,
 264                                           const char *);
 265
 266 extern struct cmd_list_element *add_info_alias (const char *, const char *,
 267                                                 int);
 268
 269 extern void complete_on_cmdlist (struct cmd_list_element *,
 270                                  completion_tracker &tracker,
 271                                  const char *, const char *, int);
 272
 273 extern void complete_on_enum (completion_tracker &tracker,
 274                               const char *const *enumlist,
 275                               const char *, const char *);
 276
 277 /* Functions that implement commands about CLI commands.  */
 278
 279 extern void help_list (struct cmd_list_element *, const char *,
 280                        enum command_class, struct ui_file *);
 281
 282 /* Method for show a set/show variable's VALUE on FILE.  If this
 283    method isn't supplied deprecated_show_value_hack() is called (which
 284    is not good).  */
 285 typedef void (show_value_ftype) (struct ui_file *file,
 286                                  int from_tty,
 287                                  struct cmd_list_element *cmd,
 288                                  const char *value);
 289 /* NOTE: i18n: This function is not i18n friendly.  Callers should
 290    instead print the value out directly.  */
 291 extern show_value_ftype deprecated_show_value_hack;
 292
 293 extern void add_setshow_enum_cmd (const char *name,
 294                                   enum command_class theclass,
 295                                   const char *const *enumlist,
 296                                   const char **var,
 297                                   const char *set_doc,
 298                                   const char *show_doc,
 299                                   const char *help_doc,
 300                                   cmd_const_sfunc_ftype *set_func,
 301                                   show_value_ftype *show_func,
 302                                   struct cmd_list_element **set_list,
 303                                   struct cmd_list_element **show_list);
 304
 305 extern void add_setshow_auto_boolean_cmd (const char *name,
 306                                           enum command_class theclass,
 307                                           enum auto_boolean *var,
 308                                           const char *set_doc,
 309                                           const char *show_doc,
 310                                           const char *help_doc,
 311                                           cmd_const_sfunc_ftype *set_func,
 312                                           show_value_ftype *show_func,
 313                                           struct cmd_list_element **set_list,
 314                                           struct cmd_list_element **show_list);
 315
 316 extern void add_setshow_boolean_cmd (const char *name,
 317                                      enum command_class theclass,
 318                                      int *var,
 319                                      const char *set_doc, const char *show_doc,
 320                                      const char *help_doc,
 321                                      cmd_const_sfunc_ftype *set_func,
 322                                      show_value_ftype *show_func,
 323                                      struct cmd_list_element **set_list,
 324                                      struct cmd_list_element **show_list);
 325
 326 extern void add_setshow_filename_cmd (const char *name,
 327                                       enum command_class theclass,
 328                                       char **var,
 329                                       const char *set_doc,
 330                                       const char *show_doc,
 331                                       const char *help_doc,
 332                                       cmd_const_sfunc_ftype *set_func,
 333                                       show_value_ftype *show_func,
 334                                       struct cmd_list_element **set_list,
 335                                       struct cmd_list_element **show_list);
 336
 337 extern void add_setshow_string_cmd (const char *name,
 338                                     enum command_class theclass,
 339                                     char **var,
 340                                     const char *set_doc,
 341                                     const char *show_doc,
 342                                     const char *help_doc,
 343                                     cmd_const_sfunc_ftype *set_func,
 344                                     show_value_ftype *show_func,
 345                                     struct cmd_list_element **set_list,
 346                                     struct cmd_list_element **show_list);
 347
 348 extern struct cmd_list_element *add_setshow_string_noescape_cmd
 349                       (const char *name,
 350                        enum command_class theclass,
 351                        char **var,
 352                        const char *set_doc,
 353                        const char *show_doc,
 354                        const char *help_doc,
 355                        cmd_const_sfunc_ftype *set_func,
 356                        show_value_ftype *show_func,
 357                        struct cmd_list_element **set_list,
 358                        struct cmd_list_element **show_list);
 359
 360 extern void add_setshow_optional_filename_cmd (const char *name,
 361                                                enum command_class theclass,
 362                                                char **var,
 363                                                const char *set_doc,
 364                                                const char *show_doc,
 365                                                const char *help_doc,
 366                                                cmd_const_sfunc_ftype *set_func,
 367                                                show_value_ftype *show_func,
 368                                                struct cmd_list_element **set_list,
 369                                                struct cmd_list_element **show_list);
 370
 371 extern void add_setshow_integer_cmd (const char *name,
 372                                      enum command_class theclass,
 373                                      int *var,
 374                                      const char *set_doc,
 375                                      const char *show_doc,
 376                                      const char *help_doc,
 377                                      cmd_const_sfunc_ftype *set_func,
 378                                      show_value_ftype *show_func,
 379                                      struct cmd_list_element **set_list,
 380                                      struct cmd_list_element **show_list);
 381
 382 extern void add_setshow_uinteger_cmd (const char *name,
 383                                       enum command_class theclass,
 384                                       unsigned int *var,
 385                                       const char *set_doc,
 386                                       const char *show_doc,
 387                                       const char *help_doc,
 388                                       cmd_const_sfunc_ftype *set_func,
 389                                       show_value_ftype *show_func,
 390                                       struct cmd_list_element **set_list,
 391                                       struct cmd_list_element **show_list);
 392
 393 extern void add_setshow_zinteger_cmd (const char *name,
 394                                       enum command_class theclass,
 395                                       int *var,
 396                                       const char *set_doc,
 397                                       const char *show_doc,
 398                                       const char *help_doc,
 399                                       cmd_const_sfunc_ftype *set_func,
 400                                       show_value_ftype *show_func,
 401                                       struct cmd_list_element **set_list,
 402                                       struct cmd_list_element **show_list);
 403
 404 extern void add_setshow_zuinteger_cmd (const char *name,
 405                                        enum command_class theclass,
 406                                        unsigned int *var,
 407                                        const char *set_doc,
 408                                        const char *show_doc,
 409                                        const char *help_doc,
 410                                        cmd_const_sfunc_ftype *set_func,
 411                                        show_value_ftype *show_func,
 412                                        struct cmd_list_element **set_list,
 413                                        struct cmd_list_element **show_list);
 414
 415 extern void
 416   add_setshow_zuinteger_unlimited_cmd (const char *name,
 417                                        enum command_class theclass,
 418                                        int *var,
 419                                        const char *set_doc,
 420                                        const char *show_doc,
 421                                        const char *help_doc,
 422                                        cmd_const_sfunc_ftype *set_func,
 423                                        show_value_ftype *show_func,
 424                                        struct cmd_list_element **set_list,
 425                                        struct cmd_list_element **show_list);
 426
 427 /* Do a "show" command for each thing on a command list.  */
 428
 429 extern void cmd_show_list (struct cmd_list_element *, int, const char *);
 430
 431 /* Used everywhere whenever at least one parameter is required and
 432    none is specified.  */
 433
 434 extern void error_no_arg (const char *) ATTRIBUTE_NORETURN;
 435
 436 extern void dont_repeat (void);
 437
 438 extern scoped_restore_tmpl<int> prevent_dont_repeat (void);
 439
 440 /* Set the arguments that will be passed if the current command is
 441    repeated.  Note that the passed-in string must be a constant.  */
 442
 443 extern void set_repeat_arguments (const char *args);
 444
 445 /* Used to mark commands that don't do anything.  If we just leave the
 446    function field NULL, the command is interpreted as a help topic, or
 447    as a class of commands.  */
 448
 449 extern void not_just_help_class_command (const char *, int);
 450
 451 /* Check function pointer.  */
 452 extern int cmd_func_p (struct cmd_list_element *cmd);
 453
 454 /* Call the command function.  */
 455 extern void cmd_func (struct cmd_list_element *cmd,
 456                       char *args, int from_tty);
 457
 458 #endif /* !defined (COMMAND_H) */