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
*,
297 extern struct cmd_list_element
*lookup_cmd_1 (const char **,
298 struct cmd_list_element
*,
299 struct cmd_list_element
**,
303 extern struct cmd_list_element
*deprecate_cmd (struct cmd_list_element
*,
306 extern void deprecated_cmd_warning (const char *);
308 extern int lookup_cmd_composition (const char *text
,
309 struct cmd_list_element
**alias
,
310 struct cmd_list_element
**prefix_cmd
,
311 struct cmd_list_element
**cmd
);
313 extern struct cmd_list_element
*add_com (const char *, enum command_class
,
314 cmd_const_cfunc_ftype
*fun
,
317 extern struct cmd_list_element
*add_com_alias (const char *, const char *,
318 enum command_class
, int);
320 extern struct cmd_list_element
*add_com_suppress_notification
321 (const char *name
, enum command_class theclass
,
322 cmd_const_cfunc_ftype
*fun
, const char *doc
,
323 int *supress_notification
);
325 extern struct cmd_list_element
*add_info (const char *,
326 cmd_const_cfunc_ftype
*fun
,
329 extern struct cmd_list_element
*add_info_alias (const char *, const char *,
332 extern void complete_on_cmdlist (struct cmd_list_element
*,
333 completion_tracker
&tracker
,
334 const char *, const char *, int);
336 extern void complete_on_enum (completion_tracker
&tracker
,
337 const char *const *enumlist
,
338 const char *, const char *);
340 /* Functions that implement commands about CLI commands. */
342 extern void help_list (struct cmd_list_element
*, const char *,
343 enum command_class
, struct ui_file
*);
345 /* Method for show a set/show variable's VALUE on FILE. If this
346 method isn't supplied deprecated_show_value_hack() is called (which
348 typedef void (show_value_ftype
) (struct ui_file
*file
,
350 struct cmd_list_element
*cmd
,
352 /* NOTE: i18n: This function is not i18n friendly. Callers should
353 instead print the value out directly. */
354 extern show_value_ftype deprecated_show_value_hack
;
356 extern void add_setshow_enum_cmd (const char *name
,
357 enum command_class theclass
,
358 const char *const *enumlist
,
361 const char *show_doc
,
362 const char *help_doc
,
363 cmd_const_sfunc_ftype
*set_func
,
364 show_value_ftype
*show_func
,
365 struct cmd_list_element
**set_list
,
366 struct cmd_list_element
**show_list
,
367 void *context
= nullptr);
369 extern void add_setshow_auto_boolean_cmd (const char *name
,
370 enum command_class theclass
,
371 enum auto_boolean
*var
,
373 const char *show_doc
,
374 const char *help_doc
,
375 cmd_const_sfunc_ftype
*set_func
,
376 show_value_ftype
*show_func
,
377 struct cmd_list_element
**set_list
,
378 struct cmd_list_element
**show_list
);
380 extern cmd_list_element
*
381 add_setshow_boolean_cmd (const char *name
,
382 enum command_class theclass
,
384 const char *set_doc
, const char *show_doc
,
385 const char *help_doc
,
386 cmd_const_sfunc_ftype
*set_func
,
387 show_value_ftype
*show_func
,
388 struct cmd_list_element
**set_list
,
389 struct cmd_list_element
**show_list
);
391 extern void add_setshow_filename_cmd (const char *name
,
392 enum command_class theclass
,
395 const char *show_doc
,
396 const char *help_doc
,
397 cmd_const_sfunc_ftype
*set_func
,
398 show_value_ftype
*show_func
,
399 struct cmd_list_element
**set_list
,
400 struct cmd_list_element
**show_list
);
402 extern void add_setshow_string_cmd (const char *name
,
403 enum command_class theclass
,
406 const char *show_doc
,
407 const char *help_doc
,
408 cmd_const_sfunc_ftype
*set_func
,
409 show_value_ftype
*show_func
,
410 struct cmd_list_element
**set_list
,
411 struct cmd_list_element
**show_list
);
413 extern struct cmd_list_element
*add_setshow_string_noescape_cmd
415 enum command_class theclass
,
418 const char *show_doc
,
419 const char *help_doc
,
420 cmd_const_sfunc_ftype
*set_func
,
421 show_value_ftype
*show_func
,
422 struct cmd_list_element
**set_list
,
423 struct cmd_list_element
**show_list
);
425 extern void add_setshow_optional_filename_cmd (const char *name
,
426 enum command_class theclass
,
429 const char *show_doc
,
430 const char *help_doc
,
431 cmd_const_sfunc_ftype
*set_func
,
432 show_value_ftype
*show_func
,
433 struct cmd_list_element
**set_list
,
434 struct cmd_list_element
**show_list
);
436 extern void add_setshow_integer_cmd (const char *name
,
437 enum command_class theclass
,
440 const char *show_doc
,
441 const char *help_doc
,
442 cmd_const_sfunc_ftype
*set_func
,
443 show_value_ftype
*show_func
,
444 struct cmd_list_element
**set_list
,
445 struct cmd_list_element
**show_list
);
447 extern void add_setshow_uinteger_cmd (const char *name
,
448 enum command_class theclass
,
451 const char *show_doc
,
452 const char *help_doc
,
453 cmd_const_sfunc_ftype
*set_func
,
454 show_value_ftype
*show_func
,
455 struct cmd_list_element
**set_list
,
456 struct cmd_list_element
**show_list
);
458 extern void add_setshow_zinteger_cmd (const char *name
,
459 enum command_class theclass
,
462 const char *show_doc
,
463 const char *help_doc
,
464 cmd_const_sfunc_ftype
*set_func
,
465 show_value_ftype
*show_func
,
466 struct cmd_list_element
**set_list
,
467 struct cmd_list_element
**show_list
);
469 extern void add_setshow_zuinteger_cmd (const char *name
,
470 enum command_class theclass
,
473 const char *show_doc
,
474 const char *help_doc
,
475 cmd_const_sfunc_ftype
*set_func
,
476 show_value_ftype
*show_func
,
477 struct cmd_list_element
**set_list
,
478 struct cmd_list_element
**show_list
);
481 add_setshow_zuinteger_unlimited_cmd (const char *name
,
482 enum command_class theclass
,
485 const char *show_doc
,
486 const char *help_doc
,
487 cmd_const_sfunc_ftype
*set_func
,
488 show_value_ftype
*show_func
,
489 struct cmd_list_element
**set_list
,
490 struct cmd_list_element
**show_list
);
492 /* Do a "show" command for each thing on a command list. */
494 extern void cmd_show_list (struct cmd_list_element
*, int);
496 /* Used everywhere whenever at least one parameter is required and
497 none is specified. */
499 extern void error_no_arg (const char *) ATTRIBUTE_NORETURN
;
502 /* Command line saving and repetition.
503 Each input line executed is saved to possibly be repeated either
504 when the user types an empty line, or be repeated by a command
505 that wants to repeat the previously executed command. The below
506 functions control command repetition. */
508 /* Commands call dont_repeat if they do not want to be repeated by null
509 lines or by repeat_previous (). */
511 extern void dont_repeat ();
513 /* Commands call repeat_previous if they want to repeat the previous
514 command. Such commands that repeat the previous command must
515 indicate to not repeat themselves, to avoid recursive repeat.
516 repeat_previous marks the current command as not repeating, and
517 ensures get_saved_command_line returns the previous command, so
518 that the currently executing command can repeat it. If there's no
519 previous command, throws an error. Otherwise, returns the result
520 of get_saved_command_line, which now points at the command to
523 extern const char *repeat_previous ();
525 /* Prevent dont_repeat from working, and return a cleanup that
526 restores the previous state. */
528 extern scoped_restore_tmpl
<int> prevent_dont_repeat (void);
530 /* Set the arguments that will be passed if the current command is
531 repeated. Note that the passed-in string must be a constant. */
533 extern void set_repeat_arguments (const char *args
);
535 /* Returns the saved command line to repeat.
536 When a command is being executed, this is the currently executing
537 command line, unless the currently executing command has called
538 repeat_previous (): in this case, get_saved_command_line returns
539 the previously saved command line. */
541 extern char *get_saved_command_line ();
543 /* Takes a copy of CMD, for possible repetition. */
545 extern void save_command_line (const char *cmd
);
547 /* Used to mark commands that don't do anything. If we just leave the
548 function field NULL, the command is interpreted as a help topic, or
549 as a class of commands. */
551 extern void not_just_help_class_command (const char *, int);
553 /* Check function pointer. */
554 extern int cmd_func_p (struct cmd_list_element
*cmd
);
556 /* Call the command function. */
557 extern void cmd_func (struct cmd_list_element
*cmd
,
558 const char *args
, int from_tty
);
560 #endif /* !defined (COMMAND_H) */