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