1 /* Header file for command creation.
3 Copyright (C) 1986-2021 Free Software Foundation, Inc.
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.
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.
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/>. */
18 #if !defined (COMMAND_H)
21 #include "gdbsupport/gdb_vecs.h"
22 #include "gdbsupport/scoped_restore.h"
24 struct completion_tracker
;
26 /* This file defines the public interface for any code wanting to
29 /* Command classes are top-level categories into which commands are
30 broken down for "help" purposes.
32 The class_alias is used for the user-defined aliases, defined
33 using the "alias" command.
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. */
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. */
48 /* Special classes to help_list */
49 class_deprecated
= -3,
50 all_classes
= -2, /* help without <classname> */
51 all_commands
= -1, /* all */
53 /* Classes of commands */
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 */
65 class_obscure
, /* obscure */
66 class_maintenance
, /* internals */
67 class_tui
, /* text-user-interface */
68 class_user
, /* user-defined */
70 /* Used for "show" commands that have no corresponding "set" command. */
74 /* Types of "set" or "show" command. */
75 typedef enum var_types
77 /* "on" or "off". *VAR is a bool which is true for on,
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
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. */
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. */
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. */
102 /* String which stores what the user types verbatim.
103 *VAR is a malloc'd string, or NULL if the string is empty. */
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
111 /* ZeroableInteger. *VAR is an int. Like var_integer except
112 that zero really means zero. */
114 /* ZeroableUnsignedInteger. *VAR is an unsigned int. Zero really
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
128 /* Return true if a setting of type VAR_TYPE is backed with type T.
130 This function is left without definition intentionally. This template is
131 specialized for all valid types that are used to back var_types. Therefore
132 if one tries to instantiate this un-specialized template it means the T
133 parameter is not a type used to back a var_type and it is most likely a
134 programming error. */
136 bool var_type_uses (var_types var_type
) = delete;
138 /* Return true if a setting of type T is backed by a bool variable. */
140 inline bool var_type_uses
<bool> (var_types t
)
142 return t
== var_boolean
;
145 /* Return true if a setting of type T is backed by a auto_boolean variable.
148 inline bool var_type_uses
<enum auto_boolean
> (var_types t
)
150 return t
== var_auto_boolean
;
153 /* Return true if a setting of type T is backed by an unsigned int variable.
156 inline bool var_type_uses
<unsigned int> (var_types t
)
158 return (t
== var_uinteger
|| t
== var_zinteger
|| t
== var_zuinteger
);
161 /* Return true if a setting of type T is backed by an int variable. */
163 inline bool var_type_uses
<int> (var_types t
)
165 return (t
== var_integer
|| t
== var_zinteger
166 || t
== var_zuinteger_unlimited
);
169 /* Return true if a setting of type T is backed by a char * variable. */
171 inline bool var_type_uses
<char *> (var_types t
)
173 return (t
== var_string
|| t
== var_string_noescape
174 || t
== var_optional_filename
|| t
== var_filename
);
177 /* Return true if a setting of type T is backed by a const char * variable.
180 inline bool var_type_uses
<const char *> (var_types t
)
182 return t
== var_enum
;
185 /* Interface for getting and setting a setting's value.
187 The underlying data can be of any VAR_TYPES type. */
190 /* Create a setting backed by a variable of type T.
192 Type T must match the var type VAR_TYPE (see VAR_TYPE_USES). */
194 setting (var_types var_type
, T
*var
)
195 : m_var_type (var_type
), m_var (var
)
197 gdb_assert (var
!= nullptr);
198 gdb_assert (var_type_uses
<T
> (var_type
));
201 /* A setting can also be constructed with a pre-validated
202 type-erased variable. Use the following function to
203 validate & type-erase said variable/function pointers. */
211 static erased_args
erase_args (var_types var_type
, T
*var
)
213 gdb_assert (var_type_uses
<T
> (var_type
));
218 /* Create a setting backed by pre-validated type-erased args.
219 ERASED_VAR's fields' real types must match the var type VAR_TYPE
220 (see VAR_TYPE_USES). */
221 setting (var_types var_type
, const erased_args
&args
)
222 : m_var_type (var_type
),
227 /* Access the type of the current setting. */
228 var_types
type () const
233 /* Return the current value.
235 The template parameter T is the type of the variable used to store the
238 const T
&get () const
240 gdb_assert (var_type_uses
<T
> (m_var_type
));
241 gdb_assert (m_var
!= nullptr);
243 return *static_cast<const T
*> (m_var
);
246 /* Sets the value of the setting to V.
248 The template parameter T indicates the type of the variable used to
251 The var_type of the setting must match T. */
253 void set (const T
&v
)
255 /* Check that the current instance is of one of the supported types for
256 this instantiation. */
257 gdb_assert (var_type_uses
<T
> (m_var_type
));
259 *static_cast<T
*> (m_var
) = v
;
263 /* The type of the variable M_VAR is pointing to. */
264 var_types m_var_type
;
266 /* Pointer to the enclosed variable. The type of the variable is encoded
271 /* This structure records one command'd definition. */
272 struct cmd_list_element
;
274 /* The "simple" signature of command callbacks, which doesn't include a
275 cmd_list_element parameter. */
277 typedef void cmd_simple_func_ftype (const char *args
, int from_tty
);
279 /* This structure specifies notifications to be suppressed by a cli
280 command interpreter. */
282 struct cli_suppress_notification
284 /* Inferior, thread, frame selected notification suppressed? */
285 int user_selected_context
;
288 extern struct cli_suppress_notification cli_suppress_notification
;
290 /* Forward-declarations of the entry-points of cli/cli-decode.c. */
292 /* API to the manipulation of command lists. */
294 /* Return TRUE if NAME is a valid user-defined command name.
295 This is a stricter subset of all gdb commands,
296 see find_command_name_length. */
298 extern bool valid_user_defined_cmd_name_p (const char *name
);
300 /* Return TRUE if C is a valid command character. */
302 extern bool valid_cmd_char_p (int c
);
304 /* Const-correct variant of the above. */
306 extern struct cmd_list_element
*add_cmd (const char *, enum command_class
,
307 cmd_simple_func_ftype
*fun
,
309 struct cmd_list_element
**);
311 /* Like add_cmd, but no command function is specified. */
313 extern struct cmd_list_element
*add_cmd (const char *, enum command_class
,
315 struct cmd_list_element
**);
317 extern struct cmd_list_element
*add_cmd_suppress_notification
318 (const char *name
, enum command_class theclass
,
319 cmd_simple_func_ftype
*fun
, const char *doc
,
320 struct cmd_list_element
**list
,
321 int *suppress_notification
);
323 extern struct cmd_list_element
*add_alias_cmd (const char *,
325 enum command_class
, int,
326 struct cmd_list_element
**);
329 extern struct cmd_list_element
*add_prefix_cmd (const char *, enum command_class
,
330 cmd_simple_func_ftype
*fun
,
332 struct cmd_list_element
**,
334 struct cmd_list_element
**);
336 /* Like add_prefix_cmd, but sets the callback to a function that
337 simply calls help_list. */
339 extern struct cmd_list_element
*add_basic_prefix_cmd
340 (const char *, enum command_class
, const char *, struct cmd_list_element
**,
341 int, struct cmd_list_element
**);
343 /* Like add_prefix_cmd, but useful for "show" prefixes. This sets the
344 callback to a function that simply calls cmd_show_list. */
346 extern struct cmd_list_element
*add_show_prefix_cmd
347 (const char *, enum command_class
, const char *, struct cmd_list_element
**,
348 int, struct cmd_list_element
**);
350 extern struct cmd_list_element
*add_prefix_cmd_suppress_notification
351 (const char *name
, enum command_class theclass
,
352 cmd_simple_func_ftype
*fun
,
353 const char *doc
, struct cmd_list_element
**subcommands
,
355 struct cmd_list_element
**list
,
356 int *suppress_notification
);
358 extern struct cmd_list_element
*add_abbrev_prefix_cmd (const char *,
360 cmd_simple_func_ftype
*fun
,
362 struct cmd_list_element
364 struct cmd_list_element
367 typedef void cmd_func_ftype (const char *args
, int from_tty
,
368 cmd_list_element
*c
);
370 /* A completion routine. Add possible completions to tracker.
372 TEXT is the text beyond what was matched for the command itself
373 (leading whitespace is skipped). It stops where we are supposed to
374 stop completing (rl_point) and is '\0' terminated. WORD points in
375 the same buffer as TEXT, and completions should be returned
376 relative to this position. For example, suppose TEXT is "foo" and
377 we want to complete to "foobar". If WORD is "oo", return "oobar";
378 if WORD is "baz/foo", return "baz/foobar". */
379 typedef void completer_ftype (struct cmd_list_element
*,
380 completion_tracker
&tracker
,
381 const char *text
, const char *word
);
383 /* Same, but for set_cmd_completer_handle_brkchars. */
384 typedef void completer_handle_brkchars_ftype (struct cmd_list_element
*,
385 completion_tracker
&tracker
,
386 const char *text
, const char *word
);
388 extern void set_cmd_completer (struct cmd_list_element
*, completer_ftype
*);
390 /* Set the completer_handle_brkchars callback. */
392 extern void set_cmd_completer_handle_brkchars (struct cmd_list_element
*,
393 completer_handle_brkchars_ftype
*);
395 /* HACK: cagney/2002-02-23: Code, mostly in tracepoints.c, grubs
396 around in cmd objects to test the value of the commands sfunc(). */
397 extern int cmd_simple_func_eq (struct cmd_list_element
*cmd
,
398 cmd_simple_func_ftype
*cfun
);
400 /* Execute CMD's pre/post hook. Throw an error if the command fails.
401 If already executing this pre/post hook, or there is no pre/post
402 hook, the call is silently ignored. */
403 extern void execute_cmd_pre_hook (struct cmd_list_element
*cmd
);
404 extern void execute_cmd_post_hook (struct cmd_list_element
*cmd
);
406 /* Flag for an ambiguous cmd_list result. */
407 #define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1)
409 extern struct cmd_list_element
*lookup_cmd (const char **,
410 struct cmd_list_element
*,
415 /* This routine takes a line of TEXT and a CLIST in which to start the
416 lookup. When it returns it will have incremented the text pointer past
417 the section of text it matched, set *RESULT_LIST to point to the list in
418 which the last word was matched, and will return a pointer to the cmd
419 list element which the text matches. It will return NULL if no match at
420 all was possible. It will return -1 (cast appropriately, ick) if ambigous
421 matches are possible; in this case *RESULT_LIST will be set to point to
422 the list in which there are ambiguous choices (and *TEXT will be set to
423 the ambiguous text string).
425 if DEFAULT_ARGS is not null, *DEFAULT_ARGS is set to the found command
426 default args (possibly empty).
428 If the located command was an abbreviation, this routine returns the base
429 command of the abbreviation. Note that *DEFAULT_ARGS will contain the
430 default args defined for the alias.
432 It does no error reporting whatsoever; control will always return
433 to the superior routine.
435 In the case of an ambiguous return (-1), *RESULT_LIST will be set to point
436 at the prefix_command (ie. the best match) *or* (special case) will be NULL
437 if no prefix command was ever found. For example, in the case of "info a",
438 "info" matches without ambiguity, but "a" could be "args" or "address", so
439 *RESULT_LIST is set to the cmd_list_element for "info". So in this case
440 RESULT_LIST should not be interpreted as a pointer to the beginning of a
441 list; it simply points to a specific command. In the case of an ambiguous
442 return *TEXT is advanced past the last non-ambiguous prefix (e.g.
443 "info t" can be "info types" or "info target"; upon return *TEXT has been
444 advanced past "info ").
446 If RESULT_LIST is NULL, don't set *RESULT_LIST (but don't otherwise
447 affect the operation).
449 This routine does *not* modify the text pointed to by TEXT.
451 If IGNORE_HELP_CLASSES is nonzero, ignore any command list elements which
452 are actually help classes rather than commands (i.e. the function field of
453 the struct cmd_list_element is NULL).
455 When LOOKUP_FOR_COMPLETION_P is true the completion is being requested
456 for the completion engine, no warnings should be printed. */
458 extern struct cmd_list_element
*lookup_cmd_1
459 (const char **text
, struct cmd_list_element
*clist
,
460 struct cmd_list_element
**result_list
, std::string
*default_args
,
461 int ignore_help_classes
, bool lookup_for_completion_p
= false);
463 /* Look up the command called NAME in the command list LIST.
465 Unlike LOOKUP_CMD, partial matches are ignored and only exact matches
466 on NAME are considered.
468 LIST is a chain of struct cmd_list_element's.
470 If IGNORE_HELP_CLASSES is true (the default), ignore any command list
471 elements which are actually help classes rather than commands (i.e.
472 the function field of the struct cmd_list_element is null).
474 If found, return the struct cmd_list_element for that command,
475 otherwise return NULLPTR. */
477 extern struct cmd_list_element
*lookup_cmd_exact
479 struct cmd_list_element
*list
,
480 bool ignore_help_classes
= true);
482 extern struct cmd_list_element
*deprecate_cmd (struct cmd_list_element
*,
485 extern void deprecated_cmd_warning (const char *, struct cmd_list_element
*);
487 extern int lookup_cmd_composition (const char *text
,
488 struct cmd_list_element
**alias
,
489 struct cmd_list_element
**prefix_cmd
,
490 struct cmd_list_element
**cmd
);
492 extern struct cmd_list_element
*add_com (const char *, enum command_class
,
493 cmd_simple_func_ftype
*fun
,
496 extern cmd_list_element
*add_com_alias (const char *name
,
497 cmd_list_element
*target
,
498 command_class theclass
,
501 extern struct cmd_list_element
*add_com_suppress_notification
502 (const char *name
, enum command_class theclass
,
503 cmd_simple_func_ftype
*fun
, const char *doc
,
504 int *supress_notification
);
506 extern struct cmd_list_element
*add_info (const char *,
507 cmd_simple_func_ftype
*fun
,
510 extern cmd_list_element
*add_info_alias (const char *name
,
511 cmd_list_element
*target
,
514 extern void complete_on_cmdlist (struct cmd_list_element
*,
515 completion_tracker
&tracker
,
516 const char *, const char *, int);
518 extern void complete_on_enum (completion_tracker
&tracker
,
519 const char *const *enumlist
,
520 const char *, const char *);
522 /* Functions that implement commands about CLI commands. */
524 extern void help_list (struct cmd_list_element
*, const char *,
525 enum command_class
, struct ui_file
*);
527 /* Method for show a set/show variable's VALUE on FILE. If this
528 method isn't supplied deprecated_show_value_hack() is called (which
530 typedef void (show_value_ftype
) (struct ui_file
*file
,
532 struct cmd_list_element
*cmd
,
534 /* NOTE: i18n: This function is not i18n friendly. Callers should
535 instead print the value out directly. */
536 extern show_value_ftype deprecated_show_value_hack
;
538 /* Return value type for the add_setshow_* functions. */
540 struct set_show_commands
542 cmd_list_element
*set
, *show
;
545 extern set_show_commands add_setshow_enum_cmd
546 (const char *name
, command_class theclass
, const char *const *enumlist
,
547 const char **var
, const char *set_doc
, const char *show_doc
,
548 const char *help_doc
, cmd_func_ftype
*set_func
,
549 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
550 cmd_list_element
**show_list
);
552 extern set_show_commands add_setshow_auto_boolean_cmd
553 (const char *name
, command_class theclass
, auto_boolean
*var
,
554 const char *set_doc
, const char *show_doc
, const char *help_doc
,
555 cmd_func_ftype
*set_func
, show_value_ftype
*show_func
,
556 cmd_list_element
**set_list
, cmd_list_element
**show_list
);
558 extern set_show_commands add_setshow_boolean_cmd
559 (const char *name
, command_class theclass
, bool *var
, const char *set_doc
,
560 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
561 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
562 cmd_list_element
**show_list
);
564 extern set_show_commands add_setshow_filename_cmd
565 (const char *name
, command_class theclass
, char **var
, const char *set_doc
,
566 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
567 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
568 cmd_list_element
**show_list
);
570 extern set_show_commands add_setshow_string_cmd
571 (const char *name
, command_class theclass
, char **var
, const char *set_doc
,
572 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
573 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
574 cmd_list_element
**show_list
);
576 extern set_show_commands add_setshow_string_noescape_cmd
577 (const char *name
, command_class theclass
, char **var
, const char *set_doc
,
578 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
579 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
580 cmd_list_element
**show_list
);
582 extern set_show_commands add_setshow_optional_filename_cmd
583 (const char *name
, command_class theclass
, char **var
, const char *set_doc
,
584 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
585 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
586 cmd_list_element
**show_list
);
588 extern set_show_commands add_setshow_integer_cmd
589 (const char *name
, command_class theclass
, int *var
, const char *set_doc
,
590 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
591 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
592 cmd_list_element
**show_list
);
594 extern set_show_commands add_setshow_uinteger_cmd
595 (const char *name
, command_class theclass
, unsigned int *var
,
596 const char *set_doc
, const char *show_doc
, const char *help_doc
,
597 cmd_func_ftype
*set_func
, show_value_ftype
*show_func
,
598 cmd_list_element
**set_list
, cmd_list_element
**show_list
);
600 extern set_show_commands add_setshow_zinteger_cmd
601 (const char *name
, command_class theclass
, int *var
, const char *set_doc
,
602 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
603 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
604 cmd_list_element
**show_list
);
606 extern set_show_commands add_setshow_zuinteger_cmd
607 (const char *name
, command_class theclass
, unsigned int *var
,
608 const char *set_doc
, const char *show_doc
, const char *help_doc
,
609 cmd_func_ftype
*set_func
, show_value_ftype
*show_func
,
610 cmd_list_element
**set_list
, cmd_list_element
**show_list
);
612 extern set_show_commands add_setshow_zuinteger_unlimited_cmd
613 (const char *name
, command_class theclass
, int *var
, const char *set_doc
,
614 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
615 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
616 cmd_list_element
**show_list
);
618 /* Do a "show" command for each thing on a command list. */
620 extern void cmd_show_list (struct cmd_list_element
*, int);
622 /* Used everywhere whenever at least one parameter is required and
623 none is specified. */
625 extern void error_no_arg (const char *) ATTRIBUTE_NORETURN
;
628 /* Command line saving and repetition.
629 Each input line executed is saved to possibly be repeated either
630 when the user types an empty line, or be repeated by a command
631 that wants to repeat the previously executed command. The below
632 functions control command repetition. */
634 /* Commands call dont_repeat if they do not want to be repeated by null
635 lines or by repeat_previous (). */
637 extern void dont_repeat ();
639 /* Commands call repeat_previous if they want to repeat the previous
640 command. Such commands that repeat the previous command must
641 indicate to not repeat themselves, to avoid recursive repeat.
642 repeat_previous marks the current command as not repeating, and
643 ensures get_saved_command_line returns the previous command, so
644 that the currently executing command can repeat it. If there's no
645 previous command, throws an error. Otherwise, returns the result
646 of get_saved_command_line, which now points at the command to
649 extern const char *repeat_previous ();
651 /* Prevent dont_repeat from working, and return a cleanup that
652 restores the previous state. */
654 extern scoped_restore_tmpl
<int> prevent_dont_repeat (void);
656 /* Set the arguments that will be passed if the current command is
657 repeated. Note that the passed-in string must be a constant. */
659 extern void set_repeat_arguments (const char *args
);
661 /* Returns the saved command line to repeat.
662 When a command is being executed, this is the currently executing
663 command line, unless the currently executing command has called
664 repeat_previous (): in this case, get_saved_command_line returns
665 the previously saved command line. */
667 extern char *get_saved_command_line ();
669 /* Takes a copy of CMD, for possible repetition. */
671 extern void save_command_line (const char *cmd
);
673 /* Used to mark commands that don't do anything. If we just leave the
674 function field NULL, the command is interpreted as a help topic, or
675 as a class of commands. */
677 extern void not_just_help_class_command (const char *, int);
679 /* Call the command function. */
680 extern void cmd_func (struct cmd_list_element
*cmd
,
681 const char *args
, int from_tty
);
683 #endif /* !defined (COMMAND_H) */