1 /* Header file for command creation.
3 Copyright (C) 1986-2020 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 /* FIXME: cagney/2002-03-17: Once cmd_type() has been removed, ``enum
75 cmd_types'' can be moved from "command.h" to "cli-decode.h". */
76 /* Not a set/show command. Note that some commands which begin with
77 "set" or "show" might be in this category, if their syntax does
78 not fall into one of the following categories. */
79 typedef enum cmd_types
87 /* Types of "set" or "show" command. */
88 typedef enum var_types
90 /* "on" or "off". *VAR is a bool which is true for on,
94 /* "on" / "true" / "enable" or "off" / "false" / "disable" or
95 "auto. *VAR is an ``enum auto_boolean''. NOTE: In general a
96 custom show command will need to be implemented - one that for
97 "auto" prints both the "auto" and the current auto-selected
101 /* Unsigned Integer. *VAR is an unsigned int. The user can type
102 0 to mean "unlimited", which is stored in *VAR as UINT_MAX. */
105 /* Like var_uinteger but signed. *VAR is an int. The user can
106 type 0 to mean "unlimited", which is stored in *VAR as
107 INT_MAX. The only remaining use of it is the Python API.
108 Don't use it elsewhere. */
111 /* String which the user enters with escapes (e.g. the user types
112 \n and it is a real newline in the stored string).
113 *VAR is a malloc'd string, or NULL if the string is empty. */
115 /* String which stores what the user types verbatim.
116 *VAR is a malloc'd string, or NULL if the string is empty. */
118 /* String which stores a filename. (*VAR) is a malloc'd string,
119 or "" if the string was empty. */
120 var_optional_filename
,
121 /* String which stores a filename. (*VAR) is a malloc'd
124 /* ZeroableInteger. *VAR is an int. Like var_integer except
125 that zero really means zero. */
127 /* ZeroableUnsignedInteger. *VAR is an unsigned int. Zero really
130 /* ZeroableUnsignedInteger with unlimited value. *VAR is an int,
131 but its range is [0, INT_MAX]. -1 stands for unlimited and
132 other negative numbers are not allowed. */
133 var_zuinteger_unlimited
,
134 /* Enumerated type. Can only have one of the specified values.
135 *VAR is a char pointer to the name of the element that we
141 /* This structure records one command'd definition. */
142 struct cmd_list_element
;
144 typedef void cmd_const_cfunc_ftype (const char *args
, int from_tty
);
146 /* This structure specifies notifications to be suppressed by a cli
147 command interpreter. */
149 struct cli_suppress_notification
151 /* Inferior, thread, frame selected notification suppressed? */
152 int user_selected_context
;
155 extern struct cli_suppress_notification cli_suppress_notification
;
157 /* Forward-declarations of the entry-points of cli/cli-decode.c. */
159 /* API to the manipulation of command lists. */
161 /* Return TRUE if NAME is a valid user-defined command name.
162 This is a stricter subset of all gdb commands,
163 see find_command_name_length. */
165 extern bool valid_user_defined_cmd_name_p (const char *name
);
167 /* Return TRUE if C is a valid command character. */
169 extern bool valid_cmd_char_p (int c
);
171 /* Const-correct variant of the above. */
173 extern struct cmd_list_element
*add_cmd (const char *, enum command_class
,
174 cmd_const_cfunc_ftype
*fun
,
176 struct cmd_list_element
**);
178 /* Like add_cmd, but no command function is specified. */
180 extern struct cmd_list_element
*add_cmd (const char *, enum command_class
,
182 struct cmd_list_element
**);
184 extern struct cmd_list_element
*add_cmd_suppress_notification
185 (const char *name
, enum command_class theclass
,
186 cmd_const_cfunc_ftype
*fun
, const char *doc
,
187 struct cmd_list_element
**list
,
188 int *suppress_notification
);
190 extern struct cmd_list_element
*add_alias_cmd (const char *, const char *,
191 enum command_class
, int,
192 struct cmd_list_element
**);
194 extern struct cmd_list_element
*add_alias_cmd (const char *,
196 enum command_class
, int,
197 struct cmd_list_element
**);
200 extern struct cmd_list_element
*add_prefix_cmd (const char *, enum command_class
,
201 cmd_const_cfunc_ftype
*fun
,
203 struct cmd_list_element
**,
205 struct cmd_list_element
**);
207 /* Like add_prefix_cmd, but sets the callback to a function that
208 simply calls help_list. */
210 extern struct cmd_list_element
*add_basic_prefix_cmd
211 (const char *, enum command_class
, const char *, struct cmd_list_element
**,
212 const char *, int, struct cmd_list_element
**);
214 /* Like add_prefix_cmd, but useful for "show" prefixes. This sets the
215 callback to a function that simply calls cmd_show_list. */
217 extern struct cmd_list_element
*add_show_prefix_cmd
218 (const char *, enum command_class
, const char *, struct cmd_list_element
**,
219 const char *, int, struct cmd_list_element
**);
221 extern struct cmd_list_element
*add_prefix_cmd_suppress_notification
222 (const char *name
, enum command_class theclass
,
223 cmd_const_cfunc_ftype
*fun
,
224 const char *doc
, struct cmd_list_element
**prefixlist
,
225 const char *prefixname
, int allow_unknown
,
226 struct cmd_list_element
**list
,
227 int *suppress_notification
);
229 extern struct cmd_list_element
*add_abbrev_prefix_cmd (const char *,
231 cmd_const_cfunc_ftype
*fun
,
233 struct cmd_list_element
234 **, const char *, int,
235 struct cmd_list_element
238 typedef void cmd_const_sfunc_ftype (const char *args
, int from_tty
,
239 struct cmd_list_element
*c
);
240 extern void set_cmd_sfunc (struct cmd_list_element
*cmd
,
241 cmd_const_sfunc_ftype
*sfunc
);
243 /* A completion routine. Add possible completions to tracker.
245 TEXT is the text beyond what was matched for the command itself
246 (leading whitespace is skipped). It stops where we are supposed to
247 stop completing (rl_point) and is '\0' terminated. WORD points in
248 the same buffer as TEXT, and completions should be returned
249 relative to this position. For example, suppose TEXT is "foo" and
250 we want to complete to "foobar". If WORD is "oo", return "oobar";
251 if WORD is "baz/foo", return "baz/foobar". */
252 typedef void completer_ftype (struct cmd_list_element
*,
253 completion_tracker
&tracker
,
254 const char *text
, const char *word
);
256 /* Same, but for set_cmd_completer_handle_brkchars. */
257 typedef void completer_handle_brkchars_ftype (struct cmd_list_element
*,
258 completion_tracker
&tracker
,
259 const char *text
, const char *word
);
261 extern void set_cmd_completer (struct cmd_list_element
*, completer_ftype
*);
263 /* Set the completer_handle_brkchars callback. */
265 extern void set_cmd_completer_handle_brkchars (struct cmd_list_element
*,
266 completer_handle_brkchars_ftype
*);
268 /* HACK: cagney/2002-02-23: Code, mostly in tracepoints.c, grubs
269 around in cmd objects to test the value of the commands sfunc(). */
270 extern int cmd_cfunc_eq (struct cmd_list_element
*cmd
,
271 cmd_const_cfunc_ftype
*cfun
);
273 /* Each command object has a local context attached to it. */
274 extern void set_cmd_context (struct cmd_list_element
*cmd
,
276 extern void *get_cmd_context (struct cmd_list_element
*cmd
);
279 /* Execute CMD's pre/post hook. Throw an error if the command fails.
280 If already executing this pre/post hook, or there is no pre/post
281 hook, the call is silently ignored. */
282 extern void execute_cmd_pre_hook (struct cmd_list_element
*cmd
);
283 extern void execute_cmd_post_hook (struct cmd_list_element
*cmd
);
285 /* Return the type of the command. */
286 extern enum cmd_types
cmd_type (struct cmd_list_element
*cmd
);
288 /* Flag for an ambiguous cmd_list result. */
289 #define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1)
291 extern struct cmd_list_element
*lookup_cmd (const char **,
292 struct cmd_list_element
*,
296 extern struct cmd_list_element
*lookup_cmd_1 (const char **,
297 struct cmd_list_element
*,
298 struct cmd_list_element
**,
301 extern struct cmd_list_element
*deprecate_cmd (struct cmd_list_element
*,
304 extern void deprecated_cmd_warning (const char *);
306 extern int lookup_cmd_composition (const char *text
,
307 struct cmd_list_element
**alias
,
308 struct cmd_list_element
**prefix_cmd
,
309 struct cmd_list_element
**cmd
);
311 extern struct cmd_list_element
*add_com (const char *, enum command_class
,
312 cmd_const_cfunc_ftype
*fun
,
315 extern struct cmd_list_element
*add_com_alias (const char *, const char *,
316 enum command_class
, int);
318 extern struct cmd_list_element
*add_com_suppress_notification
319 (const char *name
, enum command_class theclass
,
320 cmd_const_cfunc_ftype
*fun
, const char *doc
,
321 int *supress_notification
);
323 extern struct cmd_list_element
*add_info (const char *,
324 cmd_const_cfunc_ftype
*fun
,
327 extern struct cmd_list_element
*add_info_alias (const char *, const char *,
330 extern void complete_on_cmdlist (struct cmd_list_element
*,
331 completion_tracker
&tracker
,
332 const char *, const char *, int);
334 extern void complete_on_enum (completion_tracker
&tracker
,
335 const char *const *enumlist
,
336 const char *, const char *);
338 /* Functions that implement commands about CLI commands. */
340 extern void help_list (struct cmd_list_element
*, const char *,
341 enum command_class
, struct ui_file
*);
343 /* Method for show a set/show variable's VALUE on FILE. If this
344 method isn't supplied deprecated_show_value_hack() is called (which
346 typedef void (show_value_ftype
) (struct ui_file
*file
,
348 struct cmd_list_element
*cmd
,
350 /* NOTE: i18n: This function is not i18n friendly. Callers should
351 instead print the value out directly. */
352 extern show_value_ftype deprecated_show_value_hack
;
354 extern void add_setshow_enum_cmd (const char *name
,
355 enum command_class theclass
,
356 const char *const *enumlist
,
359 const char *show_doc
,
360 const char *help_doc
,
361 cmd_const_sfunc_ftype
*set_func
,
362 show_value_ftype
*show_func
,
363 struct cmd_list_element
**set_list
,
364 struct cmd_list_element
**show_list
,
365 void *context
= nullptr);
367 extern void add_setshow_auto_boolean_cmd (const char *name
,
368 enum command_class theclass
,
369 enum auto_boolean
*var
,
371 const char *show_doc
,
372 const char *help_doc
,
373 cmd_const_sfunc_ftype
*set_func
,
374 show_value_ftype
*show_func
,
375 struct cmd_list_element
**set_list
,
376 struct cmd_list_element
**show_list
);
378 extern cmd_list_element
*
379 add_setshow_boolean_cmd (const char *name
,
380 enum command_class theclass
,
382 const char *set_doc
, const char *show_doc
,
383 const char *help_doc
,
384 cmd_const_sfunc_ftype
*set_func
,
385 show_value_ftype
*show_func
,
386 struct cmd_list_element
**set_list
,
387 struct cmd_list_element
**show_list
);
389 extern void add_setshow_filename_cmd (const char *name
,
390 enum command_class theclass
,
393 const char *show_doc
,
394 const char *help_doc
,
395 cmd_const_sfunc_ftype
*set_func
,
396 show_value_ftype
*show_func
,
397 struct cmd_list_element
**set_list
,
398 struct cmd_list_element
**show_list
);
400 extern void add_setshow_string_cmd (const char *name
,
401 enum command_class theclass
,
404 const char *show_doc
,
405 const char *help_doc
,
406 cmd_const_sfunc_ftype
*set_func
,
407 show_value_ftype
*show_func
,
408 struct cmd_list_element
**set_list
,
409 struct cmd_list_element
**show_list
);
411 extern struct cmd_list_element
*add_setshow_string_noescape_cmd
413 enum command_class theclass
,
416 const char *show_doc
,
417 const char *help_doc
,
418 cmd_const_sfunc_ftype
*set_func
,
419 show_value_ftype
*show_func
,
420 struct cmd_list_element
**set_list
,
421 struct cmd_list_element
**show_list
);
423 extern void add_setshow_optional_filename_cmd (const char *name
,
424 enum command_class theclass
,
427 const char *show_doc
,
428 const char *help_doc
,
429 cmd_const_sfunc_ftype
*set_func
,
430 show_value_ftype
*show_func
,
431 struct cmd_list_element
**set_list
,
432 struct cmd_list_element
**show_list
);
434 extern void add_setshow_integer_cmd (const char *name
,
435 enum command_class theclass
,
438 const char *show_doc
,
439 const char *help_doc
,
440 cmd_const_sfunc_ftype
*set_func
,
441 show_value_ftype
*show_func
,
442 struct cmd_list_element
**set_list
,
443 struct cmd_list_element
**show_list
);
445 extern void add_setshow_uinteger_cmd (const char *name
,
446 enum command_class theclass
,
449 const char *show_doc
,
450 const char *help_doc
,
451 cmd_const_sfunc_ftype
*set_func
,
452 show_value_ftype
*show_func
,
453 struct cmd_list_element
**set_list
,
454 struct cmd_list_element
**show_list
);
456 extern void add_setshow_zinteger_cmd (const char *name
,
457 enum command_class theclass
,
460 const char *show_doc
,
461 const char *help_doc
,
462 cmd_const_sfunc_ftype
*set_func
,
463 show_value_ftype
*show_func
,
464 struct cmd_list_element
**set_list
,
465 struct cmd_list_element
**show_list
);
467 extern void add_setshow_zuinteger_cmd (const char *name
,
468 enum command_class theclass
,
471 const char *show_doc
,
472 const char *help_doc
,
473 cmd_const_sfunc_ftype
*set_func
,
474 show_value_ftype
*show_func
,
475 struct cmd_list_element
**set_list
,
476 struct cmd_list_element
**show_list
);
479 add_setshow_zuinteger_unlimited_cmd (const char *name
,
480 enum command_class theclass
,
483 const char *show_doc
,
484 const char *help_doc
,
485 cmd_const_sfunc_ftype
*set_func
,
486 show_value_ftype
*show_func
,
487 struct cmd_list_element
**set_list
,
488 struct cmd_list_element
**show_list
);
490 /* Do a "show" command for each thing on a command list. */
492 extern void cmd_show_list (struct cmd_list_element
*, int);
494 /* Used everywhere whenever at least one parameter is required and
495 none is specified. */
497 extern void error_no_arg (const char *) ATTRIBUTE_NORETURN
;
500 /* Command line saving and repetition.
501 Each input line executed is saved to possibly be repeated either
502 when the user types an empty line, or be repeated by a command
503 that wants to repeat the previously executed command. The below
504 functions control command repetition. */
506 /* Commands call dont_repeat if they do not want to be repeated by null
507 lines or by repeat_previous (). */
509 extern void dont_repeat ();
511 /* Commands call repeat_previous if they want to repeat the previous
512 command. Such commands that repeat the previous command must
513 indicate to not repeat themselves, to avoid recursive repeat.
514 repeat_previous marks the current command as not repeating, and
515 ensures get_saved_command_line returns the previous command, so
516 that the currently executing command can repeat it. If there's no
517 previous command, throws an error. Otherwise, returns the result
518 of get_saved_command_line, which now points at the command to
521 extern const char *repeat_previous ();
523 /* Prevent dont_repeat from working, and return a cleanup that
524 restores the previous state. */
526 extern scoped_restore_tmpl
<int> prevent_dont_repeat (void);
528 /* Set the arguments that will be passed if the current command is
529 repeated. Note that the passed-in string must be a constant. */
531 extern void set_repeat_arguments (const char *args
);
533 /* Returns the saved command line to repeat.
534 When a command is being executed, this is the currently executing
535 command line, unless the currently executing command has called
536 repeat_previous (): in this case, get_saved_command_line returns
537 the previously saved command line. */
539 extern char *get_saved_command_line ();
541 /* Takes a copy of CMD, for possible repetition. */
543 extern void save_command_line (const char *cmd
);
545 /* Used to mark commands that don't do anything. If we just leave the
546 function field NULL, the command is interpreted as a help topic, or
547 as a class of commands. */
549 extern void not_just_help_class_command (const char *, int);
551 /* Check function pointer. */
552 extern int cmd_func_p (struct cmd_list_element
*cmd
);
554 /* Call the command function. */
555 extern void cmd_func (struct cmd_list_element
*cmd
,
556 const char *args
, int from_tty
);
558 #endif /* !defined (COMMAND_H) */