gdb/command.h

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