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 /* This structure records one command'd definition. */
129 struct cmd_list_element
;
131 /* The "simple" signature of command callbacks, which doesn't include a
132 cmd_list_element parameter. */
134 typedef void cmd_simple_func_ftype (const char *args
, int from_tty
);
136 /* This structure specifies notifications to be suppressed by a cli
137 command interpreter. */
139 struct cli_suppress_notification
141 /* Inferior, thread, frame selected notification suppressed? */
142 int user_selected_context
;
145 extern struct cli_suppress_notification cli_suppress_notification
;
147 /* Forward-declarations of the entry-points of cli/cli-decode.c. */
149 /* API to the manipulation of command lists. */
151 /* Return TRUE if NAME is a valid user-defined command name.
152 This is a stricter subset of all gdb commands,
153 see find_command_name_length. */
155 extern bool valid_user_defined_cmd_name_p (const char *name
);
157 /* Return TRUE if C is a valid command character. */
159 extern bool valid_cmd_char_p (int c
);
161 /* Const-correct variant of the above. */
163 extern struct cmd_list_element
*add_cmd (const char *, enum command_class
,
164 cmd_simple_func_ftype
*fun
,
166 struct cmd_list_element
**);
168 /* Like add_cmd, but no command function is specified. */
170 extern struct cmd_list_element
*add_cmd (const char *, enum command_class
,
172 struct cmd_list_element
**);
174 extern struct cmd_list_element
*add_cmd_suppress_notification
175 (const char *name
, enum command_class theclass
,
176 cmd_simple_func_ftype
*fun
, const char *doc
,
177 struct cmd_list_element
**list
,
178 int *suppress_notification
);
180 extern struct cmd_list_element
*add_alias_cmd (const char *,
182 enum command_class
, int,
183 struct cmd_list_element
**);
186 extern struct cmd_list_element
*add_prefix_cmd (const char *, enum command_class
,
187 cmd_simple_func_ftype
*fun
,
189 struct cmd_list_element
**,
191 struct cmd_list_element
**);
193 /* Like add_prefix_cmd, but sets the callback to a function that
194 simply calls help_list. */
196 extern struct cmd_list_element
*add_basic_prefix_cmd
197 (const char *, enum command_class
, const char *, struct cmd_list_element
**,
198 int, struct cmd_list_element
**);
200 /* Like add_prefix_cmd, but useful for "show" prefixes. This sets the
201 callback to a function that simply calls cmd_show_list. */
203 extern struct cmd_list_element
*add_show_prefix_cmd
204 (const char *, enum command_class
, const char *, struct cmd_list_element
**,
205 int, struct cmd_list_element
**);
207 extern struct cmd_list_element
*add_prefix_cmd_suppress_notification
208 (const char *name
, enum command_class theclass
,
209 cmd_simple_func_ftype
*fun
,
210 const char *doc
, struct cmd_list_element
**subcommands
,
212 struct cmd_list_element
**list
,
213 int *suppress_notification
);
215 extern struct cmd_list_element
*add_abbrev_prefix_cmd (const char *,
217 cmd_simple_func_ftype
*fun
,
219 struct cmd_list_element
221 struct cmd_list_element
224 typedef void cmd_func_ftype (const char *args
, int from_tty
,
225 cmd_list_element
*c
);
227 /* A completion routine. Add possible completions to tracker.
229 TEXT is the text beyond what was matched for the command itself
230 (leading whitespace is skipped). It stops where we are supposed to
231 stop completing (rl_point) and is '\0' terminated. WORD points in
232 the same buffer as TEXT, and completions should be returned
233 relative to this position. For example, suppose TEXT is "foo" and
234 we want to complete to "foobar". If WORD is "oo", return "oobar";
235 if WORD is "baz/foo", return "baz/foobar". */
236 typedef void completer_ftype (struct cmd_list_element
*,
237 completion_tracker
&tracker
,
238 const char *text
, const char *word
);
240 /* Same, but for set_cmd_completer_handle_brkchars. */
241 typedef void completer_handle_brkchars_ftype (struct cmd_list_element
*,
242 completion_tracker
&tracker
,
243 const char *text
, const char *word
);
245 extern void set_cmd_completer (struct cmd_list_element
*, completer_ftype
*);
247 /* Set the completer_handle_brkchars callback. */
249 extern void set_cmd_completer_handle_brkchars (struct cmd_list_element
*,
250 completer_handle_brkchars_ftype
*);
252 /* HACK: cagney/2002-02-23: Code, mostly in tracepoints.c, grubs
253 around in cmd objects to test the value of the commands sfunc(). */
254 extern int cmd_simple_func_eq (struct cmd_list_element
*cmd
,
255 cmd_simple_func_ftype
*cfun
);
257 /* Execute CMD's pre/post hook. Throw an error if the command fails.
258 If already executing this pre/post hook, or there is no pre/post
259 hook, the call is silently ignored. */
260 extern void execute_cmd_pre_hook (struct cmd_list_element
*cmd
);
261 extern void execute_cmd_post_hook (struct cmd_list_element
*cmd
);
263 /* Flag for an ambiguous cmd_list result. */
264 #define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1)
266 extern struct cmd_list_element
*lookup_cmd (const char **,
267 struct cmd_list_element
*,
272 /* This routine takes a line of TEXT and a CLIST in which to start the
273 lookup. When it returns it will have incremented the text pointer past
274 the section of text it matched, set *RESULT_LIST to point to the list in
275 which the last word was matched, and will return a pointer to the cmd
276 list element which the text matches. It will return NULL if no match at
277 all was possible. It will return -1 (cast appropriately, ick) if ambigous
278 matches are possible; in this case *RESULT_LIST will be set to point to
279 the list in which there are ambiguous choices (and *TEXT will be set to
280 the ambiguous text string).
282 if DEFAULT_ARGS is not null, *DEFAULT_ARGS is set to the found command
283 default args (possibly empty).
285 If the located command was an abbreviation, this routine returns the base
286 command of the abbreviation. Note that *DEFAULT_ARGS will contain the
287 default args defined for the alias.
289 It does no error reporting whatsoever; control will always return
290 to the superior routine.
292 In the case of an ambiguous return (-1), *RESULT_LIST will be set to point
293 at the prefix_command (ie. the best match) *or* (special case) will be NULL
294 if no prefix command was ever found. For example, in the case of "info a",
295 "info" matches without ambiguity, but "a" could be "args" or "address", so
296 *RESULT_LIST is set to the cmd_list_element for "info". So in this case
297 RESULT_LIST should not be interpreted as a pointer to the beginning of a
298 list; it simply points to a specific command. In the case of an ambiguous
299 return *TEXT is advanced past the last non-ambiguous prefix (e.g.
300 "info t" can be "info types" or "info target"; upon return *TEXT has been
301 advanced past "info ").
303 If RESULT_LIST is NULL, don't set *RESULT_LIST (but don't otherwise
304 affect the operation).
306 This routine does *not* modify the text pointed to by TEXT.
308 If IGNORE_HELP_CLASSES is nonzero, ignore any command list elements which
309 are actually help classes rather than commands (i.e. the function field of
310 the struct cmd_list_element is NULL).
312 When LOOKUP_FOR_COMPLETION_P is true the completion is being requested
313 for the completion engine, no warnings should be printed. */
315 extern struct cmd_list_element
*lookup_cmd_1
316 (const char **text
, struct cmd_list_element
*clist
,
317 struct cmd_list_element
**result_list
, std::string
*default_args
,
318 int ignore_help_classes
, bool lookup_for_completion_p
= false);
320 /* Look up the command called NAME in the command list LIST.
322 Unlike LOOKUP_CMD, partial matches are ignored and only exact matches
323 on NAME are considered.
325 LIST is a chain of struct cmd_list_element's.
327 If IGNORE_HELP_CLASSES is true (the default), ignore any command list
328 elements which are actually help classes rather than commands (i.e.
329 the function field of the struct cmd_list_element is null).
331 If found, return the struct cmd_list_element for that command,
332 otherwise return NULLPTR. */
334 extern struct cmd_list_element
*lookup_cmd_exact
336 struct cmd_list_element
*list
,
337 bool ignore_help_classes
= true);
339 extern struct cmd_list_element
*deprecate_cmd (struct cmd_list_element
*,
342 extern void deprecated_cmd_warning (const char *, struct cmd_list_element
*);
344 extern int lookup_cmd_composition (const char *text
,
345 struct cmd_list_element
**alias
,
346 struct cmd_list_element
**prefix_cmd
,
347 struct cmd_list_element
**cmd
);
349 extern struct cmd_list_element
*add_com (const char *, enum command_class
,
350 cmd_simple_func_ftype
*fun
,
353 extern cmd_list_element
*add_com_alias (const char *name
,
354 cmd_list_element
*target
,
355 command_class theclass
,
358 extern struct cmd_list_element
*add_com_suppress_notification
359 (const char *name
, enum command_class theclass
,
360 cmd_simple_func_ftype
*fun
, const char *doc
,
361 int *supress_notification
);
363 extern struct cmd_list_element
*add_info (const char *,
364 cmd_simple_func_ftype
*fun
,
367 extern cmd_list_element
*add_info_alias (const char *name
,
368 cmd_list_element
*target
,
371 extern void complete_on_cmdlist (struct cmd_list_element
*,
372 completion_tracker
&tracker
,
373 const char *, const char *, int);
375 extern void complete_on_enum (completion_tracker
&tracker
,
376 const char *const *enumlist
,
377 const char *, const char *);
379 /* Functions that implement commands about CLI commands. */
381 extern void help_list (struct cmd_list_element
*, const char *,
382 enum command_class
, struct ui_file
*);
384 /* Method for show a set/show variable's VALUE on FILE. If this
385 method isn't supplied deprecated_show_value_hack() is called (which
387 typedef void (show_value_ftype
) (struct ui_file
*file
,
389 struct cmd_list_element
*cmd
,
391 /* NOTE: i18n: This function is not i18n friendly. Callers should
392 instead print the value out directly. */
393 extern show_value_ftype deprecated_show_value_hack
;
395 /* Return value type for the add_setshow_* functions. */
397 struct set_show_commands
399 cmd_list_element
*set
, *show
;
402 extern set_show_commands add_setshow_enum_cmd
403 (const char *name
, command_class theclass
, const char *const *enumlist
,
404 const char **var
, const char *set_doc
, const char *show_doc
,
405 const char *help_doc
, cmd_func_ftype
*set_func
,
406 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
407 cmd_list_element
**show_list
);
409 extern set_show_commands add_setshow_auto_boolean_cmd
410 (const char *name
, command_class theclass
, auto_boolean
*var
,
411 const char *set_doc
, const char *show_doc
, const char *help_doc
,
412 cmd_func_ftype
*set_func
, show_value_ftype
*show_func
,
413 cmd_list_element
**set_list
, cmd_list_element
**show_list
);
415 extern set_show_commands add_setshow_boolean_cmd
416 (const char *name
, command_class theclass
, bool *var
, const char *set_doc
,
417 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
418 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
419 cmd_list_element
**show_list
);
421 extern set_show_commands add_setshow_filename_cmd
422 (const char *name
, command_class theclass
, char **var
, const char *set_doc
,
423 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
424 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
425 cmd_list_element
**show_list
);
427 extern set_show_commands add_setshow_string_cmd
428 (const char *name
, command_class theclass
, char **var
, const char *set_doc
,
429 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
430 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
431 cmd_list_element
**show_list
);
433 extern set_show_commands add_setshow_string_noescape_cmd
434 (const char *name
, command_class theclass
, char **var
, const char *set_doc
,
435 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
436 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
437 cmd_list_element
**show_list
);
439 extern set_show_commands add_setshow_optional_filename_cmd
440 (const char *name
, command_class theclass
, char **var
, const char *set_doc
,
441 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
442 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
443 cmd_list_element
**show_list
);
445 extern set_show_commands add_setshow_integer_cmd
446 (const char *name
, command_class theclass
, int *var
, const char *set_doc
,
447 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
448 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
449 cmd_list_element
**show_list
);
451 extern set_show_commands add_setshow_uinteger_cmd
452 (const char *name
, command_class theclass
, unsigned int *var
,
453 const char *set_doc
, const char *show_doc
, const char *help_doc
,
454 cmd_func_ftype
*set_func
, show_value_ftype
*show_func
,
455 cmd_list_element
**set_list
, cmd_list_element
**show_list
);
457 extern set_show_commands add_setshow_zinteger_cmd
458 (const char *name
, command_class theclass
, int *var
, const char *set_doc
,
459 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
460 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
461 cmd_list_element
**show_list
);
463 extern set_show_commands add_setshow_zuinteger_cmd
464 (const char *name
, command_class theclass
, unsigned int *var
,
465 const char *set_doc
, const char *show_doc
, const char *help_doc
,
466 cmd_func_ftype
*set_func
, show_value_ftype
*show_func
,
467 cmd_list_element
**set_list
, cmd_list_element
**show_list
);
469 extern set_show_commands add_setshow_zuinteger_unlimited_cmd
470 (const char *name
, command_class theclass
, int *var
, const char *set_doc
,
471 const char *show_doc
, const char *help_doc
, cmd_func_ftype
*set_func
,
472 show_value_ftype
*show_func
, cmd_list_element
**set_list
,
473 cmd_list_element
**show_list
);
475 /* Do a "show" command for each thing on a command list. */
477 extern void cmd_show_list (struct cmd_list_element
*, int);
479 /* Used everywhere whenever at least one parameter is required and
480 none is specified. */
482 extern void error_no_arg (const char *) ATTRIBUTE_NORETURN
;
485 /* Command line saving and repetition.
486 Each input line executed is saved to possibly be repeated either
487 when the user types an empty line, or be repeated by a command
488 that wants to repeat the previously executed command. The below
489 functions control command repetition. */
491 /* Commands call dont_repeat if they do not want to be repeated by null
492 lines or by repeat_previous (). */
494 extern void dont_repeat ();
496 /* Commands call repeat_previous if they want to repeat the previous
497 command. Such commands that repeat the previous command must
498 indicate to not repeat themselves, to avoid recursive repeat.
499 repeat_previous marks the current command as not repeating, and
500 ensures get_saved_command_line returns the previous command, so
501 that the currently executing command can repeat it. If there's no
502 previous command, throws an error. Otherwise, returns the result
503 of get_saved_command_line, which now points at the command to
506 extern const char *repeat_previous ();
508 /* Prevent dont_repeat from working, and return a cleanup that
509 restores the previous state. */
511 extern scoped_restore_tmpl
<int> prevent_dont_repeat (void);
513 /* Set the arguments that will be passed if the current command is
514 repeated. Note that the passed-in string must be a constant. */
516 extern void set_repeat_arguments (const char *args
);
518 /* Returns the saved command line to repeat.
519 When a command is being executed, this is the currently executing
520 command line, unless the currently executing command has called
521 repeat_previous (): in this case, get_saved_command_line returns
522 the previously saved command line. */
524 extern char *get_saved_command_line ();
526 /* Takes a copy of CMD, for possible repetition. */
528 extern void save_command_line (const char *cmd
);
530 /* Used to mark commands that don't do anything. If we just leave the
531 function field NULL, the command is interpreted as a help topic, or
532 as a class of commands. */
534 extern void not_just_help_class_command (const char *, int);
536 /* Call the command function. */
537 extern void cmd_func (struct cmd_list_element
*cmd
,
538 const char *args
, int from_tty
);
540 #endif /* !defined (COMMAND_H) */