1 /* Handle lists of commands, their decoding and documentation, for GDB.
3 Copyright (C) 1986-2022 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/>. */
21 #include "gdbsupport/gdb_regex.h"
22 #include "completer.h"
24 #include "cli/cli-cmds.h"
25 #include "cli/cli-decode.h"
26 #include "cli/cli-style.h"
27 #include "gdbsupport/gdb_optional.h"
29 /* Prototypes for local functions. */
31 static void undef_cmd_error (const char *, const char *);
33 static cmd_list_element::aliases_list_type delete_cmd
34 (const char *name, cmd_list_element **list, cmd_list_element **prehook,
35 cmd_list_element **prehookee, cmd_list_element **posthook,
36 cmd_list_element **posthookee);
38 static struct cmd_list_element *find_cmd (const char *command,
40 struct cmd_list_element *clist,
41 int ignore_help_classes,
44 static void help_cmd_list (struct cmd_list_element *list,
45 enum command_class theclass,
47 struct ui_file *stream);
49 static void help_all (struct ui_file *stream);
51 static int lookup_cmd_composition_1 (const char *text,
52 struct cmd_list_element **alias,
53 struct cmd_list_element **prefix_cmd,
54 struct cmd_list_element **cmd,
55 struct cmd_list_element *cur_list);
57 /* Look up a command whose 'subcommands' field is SUBCOMMANDS. Return the
58 command if found, otherwise return NULL. */
60 static struct cmd_list_element *
61 lookup_cmd_with_subcommands (cmd_list_element **subcommands,
62 cmd_list_element *list)
64 struct cmd_list_element *p = NULL;
66 for (p = list; p != NULL; p = p->next)
68 struct cmd_list_element *q;
73 else if (p->subcommands == subcommands)
75 /* If we found an alias, we must return the aliased
77 return p->is_alias () ? p->alias_target : p;
80 q = lookup_cmd_with_subcommands (subcommands, *(p->subcommands));
89 print_help_for_command (const cmd_list_element &c,
90 bool recurse, struct ui_file *stream);
93 do_simple_func (const char *args, int from_tty, cmd_list_element *c)
95 c->function.simple_func (args, from_tty);
99 set_cmd_simple_func (struct cmd_list_element *cmd, cmd_simple_func_ftype *simple_func)
101 if (simple_func == NULL)
104 cmd->func = do_simple_func;
106 cmd->function.simple_func = simple_func;
110 cmd_simple_func_eq (struct cmd_list_element *cmd, cmd_simple_func_ftype *simple_func)
112 return (cmd->func == do_simple_func
113 && cmd->function.simple_func == simple_func);
117 set_cmd_completer (struct cmd_list_element *cmd, completer_ftype *completer)
119 cmd->completer = completer; /* Ok. */
122 /* See definition in commands.h. */
125 set_cmd_completer_handle_brkchars (struct cmd_list_element *cmd,
126 completer_handle_brkchars_ftype *func)
128 cmd->completer_handle_brkchars = func;
132 cmd_list_element::prefixname () const
134 if (!this->is_prefix ())
135 /* Not a prefix command. */
138 std::string prefixname;
139 if (this->prefix != nullptr)
140 prefixname = this->prefix->prefixname ();
142 prefixname += this->name;
148 /* See cli/cli-decode.h. */
150 std::vector<std::string>
151 cmd_list_element::command_components () const
153 std::vector<std::string> result;
155 if (this->prefix != nullptr)
156 result = this->prefix->command_components ();
158 result.emplace_back (std::string (this->name));
162 /* Add element named NAME.
163 Space for NAME and DOC must be allocated by the caller.
164 CLASS is the top level category into which commands are broken down
166 FUN should be the function to execute the command;
167 it will get a character string as argument, with leading
168 and trailing blanks already eliminated.
170 DOC is a documentation string for the command.
171 Its first line should be a complete sentence.
172 It should start with ? for a command that is an abbreviation
173 or with * for a command that most users don't need to know about.
175 Add this command to command list *LIST.
177 Returns a pointer to the added command (not necessarily the head
180 static struct cmd_list_element *
181 do_add_cmd (const char *name, enum command_class theclass,
182 const char *doc, struct cmd_list_element **list)
184 struct cmd_list_element *c = new struct cmd_list_element (name, theclass,
187 /* Turn each alias of the old command into an alias of the new
189 c->aliases = delete_cmd (name, list, &c->hook_pre, &c->hookee_pre,
190 &c->hook_post, &c->hookee_post);
192 for (cmd_list_element &alias : c->aliases)
193 alias.alias_target = c;
196 c->hook_pre->hookee_pre = c;
199 c->hookee_pre->hook_pre = c;
202 c->hook_post->hookee_post = c;
205 c->hookee_post->hook_post = c;
207 if (*list == NULL || strcmp ((*list)->name, name) >= 0)
214 cmd_list_element *p = *list;
215 while (p->next && strcmp (p->next->name, name) <= 0)
223 /* Search the prefix cmd of C, and assigns it to C->prefix.
224 See also add_prefix_cmd and update_prefix_field_of_prefixed_commands. */
225 cmd_list_element *prefixcmd = lookup_cmd_with_subcommands (list, cmdlist);
226 c->prefix = prefixcmd;
232 struct cmd_list_element *
233 add_cmd (const char *name, enum command_class theclass,
234 const char *doc, struct cmd_list_element **list)
236 cmd_list_element *result = do_add_cmd (name, theclass, doc, list);
238 result->function.simple_func = NULL;
242 struct cmd_list_element *
243 add_cmd (const char *name, enum command_class theclass,
244 cmd_simple_func_ftype *fun,
245 const char *doc, struct cmd_list_element **list)
247 cmd_list_element *result = do_add_cmd (name, theclass, doc, list);
248 set_cmd_simple_func (result, fun);
252 /* Add an element with a suppress notification to the LIST of commands. */
254 struct cmd_list_element *
255 add_cmd_suppress_notification (const char *name, enum command_class theclass,
256 cmd_simple_func_ftype *fun, const char *doc,
257 struct cmd_list_element **list,
258 bool *suppress_notification)
260 struct cmd_list_element *element;
262 element = add_cmd (name, theclass, fun, doc, list);
263 element->suppress_notification = suppress_notification;
269 /* Deprecates a command CMD.
270 REPLACEMENT is the name of the command which should be used in
271 place of this command, or NULL if no such command exists.
273 This function does not check to see if command REPLACEMENT exists
274 since gdb may not have gotten around to adding REPLACEMENT when
275 this function is called.
277 Returns a pointer to the deprecated command. */
279 struct cmd_list_element *
280 deprecate_cmd (struct cmd_list_element *cmd, const char *replacement)
282 cmd->cmd_deprecated = 1;
283 cmd->deprecated_warn_user = 1;
285 if (replacement != NULL)
286 cmd->replacement = replacement;
288 cmd->replacement = NULL;
293 struct cmd_list_element *
294 add_alias_cmd (const char *name, cmd_list_element *target,
295 enum command_class theclass, int abbrev_flag,
296 struct cmd_list_element **list)
298 gdb_assert (target != nullptr);
300 struct cmd_list_element *c = add_cmd (name, theclass, target->doc, list);
302 /* If TARGET->DOC can be freed, we should make another copy. */
303 if (target->doc_allocated)
305 c->doc = xstrdup (target->doc);
306 c->doc_allocated = 1;
308 /* NOTE: Both FUNC and all the FUNCTIONs need to be copied. */
309 c->func = target->func;
310 c->function = target->function;
311 c->subcommands = target->subcommands;
312 c->allow_unknown = target->allow_unknown;
313 c->abbrev_flag = abbrev_flag;
314 c->alias_target = target;
315 target->aliases.push_front (*c);
320 /* Update the prefix field of all sub-commands of the prefix command C.
321 We must do this when a prefix command is defined as the GDB init sequence
322 does not guarantee that a prefix command is created before its sub-commands.
323 For example, break-catch-sig.c initialization runs before breakpoint.c
324 initialization, but it is breakpoint.c that creates the "catch" command used
325 by the "catch signal" command created by break-catch-sig.c. */
328 update_prefix_field_of_prefixed_commands (struct cmd_list_element *c)
330 for (cmd_list_element *p = *c->subcommands; p != NULL; p = p->next)
334 /* We must recursively update the prefix field to cover
335 e.g. 'info auto-load libthread-db' where the creation
340 In such a case, when 'auto-load' was created by do_add_cmd,
341 the 'libthread-db' prefix field could not be updated, as the
342 'auto-load' command was not yet reachable by
343 lookup_cmd_for_subcommands (list, cmdlist)
344 that searches from the top level 'cmdlist'. */
346 update_prefix_field_of_prefixed_commands (p);
351 /* Like add_cmd but adds an element for a command prefix: a name that
352 should be followed by a subcommand to be looked up in another
353 command list. SUBCOMMANDS should be the address of the variable
354 containing that list. */
356 struct cmd_list_element *
357 add_prefix_cmd (const char *name, enum command_class theclass,
358 cmd_simple_func_ftype *fun,
359 const char *doc, struct cmd_list_element **subcommands,
360 int allow_unknown, struct cmd_list_element **list)
362 struct cmd_list_element *c = add_cmd (name, theclass, fun, doc, list);
364 c->subcommands = subcommands;
365 c->allow_unknown = allow_unknown;
367 /* Now that prefix command C is defined, we need to set the prefix field
368 of all prefixed commands that were defined before C itself was defined. */
369 update_prefix_field_of_prefixed_commands (c);
374 /* A helper function for add_basic_prefix_cmd. This is a command
375 function that just forwards to help_list. */
378 do_prefix_cmd (const char *args, int from_tty, struct cmd_list_element *c)
380 /* Look past all aliases. */
381 while (c->is_alias ())
384 help_list (*c->subcommands, c->prefixname ().c_str (),
385 all_commands, gdb_stdout);
390 struct cmd_list_element *
391 add_basic_prefix_cmd (const char *name, enum command_class theclass,
392 const char *doc, struct cmd_list_element **subcommands,
393 int allow_unknown, struct cmd_list_element **list)
395 struct cmd_list_element *cmd = add_prefix_cmd (name, theclass, nullptr,
397 allow_unknown, list);
398 cmd->func = do_prefix_cmd;
402 /* A helper function for add_show_prefix_cmd. This is a command
403 function that just forwards to cmd_show_list. */
406 do_show_prefix_cmd (const char *args, int from_tty, struct cmd_list_element *c)
408 cmd_show_list (*c->subcommands, from_tty);
413 struct cmd_list_element *
414 add_show_prefix_cmd (const char *name, enum command_class theclass,
415 const char *doc, struct cmd_list_element **subcommands,
416 int allow_unknown, struct cmd_list_element **list)
418 struct cmd_list_element *cmd = add_prefix_cmd (name, theclass, nullptr,
420 allow_unknown, list);
421 cmd->func = do_show_prefix_cmd;
428 add_setshow_prefix_cmd (const char *name, command_class theclass,
429 const char *set_doc, const char *show_doc,
430 cmd_list_element **set_subcommands_list,
431 cmd_list_element **show_subcommands_list,
432 cmd_list_element **set_list,
433 cmd_list_element **show_list)
435 set_show_commands cmds;
437 cmds.set = add_basic_prefix_cmd (name, theclass, set_doc,
438 set_subcommands_list, 0,
440 cmds.show = add_show_prefix_cmd (name, theclass, show_doc,
441 show_subcommands_list, 0,
447 /* Like ADD_PREFIX_CMD but sets the suppress_notification pointer on the
448 new command list element. */
450 struct cmd_list_element *
451 add_prefix_cmd_suppress_notification
452 (const char *name, enum command_class theclass,
453 cmd_simple_func_ftype *fun,
454 const char *doc, struct cmd_list_element **subcommands,
455 int allow_unknown, struct cmd_list_element **list,
456 bool *suppress_notification)
458 struct cmd_list_element *element
459 = add_prefix_cmd (name, theclass, fun, doc, subcommands,
460 allow_unknown, list);
461 element->suppress_notification = suppress_notification;
465 /* Like add_prefix_cmd but sets the abbrev_flag on the new command. */
467 struct cmd_list_element *
468 add_abbrev_prefix_cmd (const char *name, enum command_class theclass,
469 cmd_simple_func_ftype *fun, const char *doc,
470 struct cmd_list_element **subcommands,
471 int allow_unknown, struct cmd_list_element **list)
473 struct cmd_list_element *c = add_cmd (name, theclass, fun, doc, list);
475 c->subcommands = subcommands;
476 c->allow_unknown = allow_unknown;
481 /* This is an empty "simple func". */
483 not_just_help_class_command (const char *args, int from_tty)
487 /* This is an empty cmd func. */
490 empty_func (const char *args, int from_tty, cmd_list_element *c)
494 /* Add element named NAME to command list LIST (the list for set/show
495 or some sublist thereof).
496 TYPE is set_cmd or show_cmd.
497 CLASS is as in add_cmd.
498 VAR_TYPE is the kind of thing we are setting.
499 VAR is address of the variable being controlled by this command.
500 SET_SETTING_FUNC is a pointer to an optional function callback used to set
502 GET_SETTING_FUNC is a pointer to an optional function callback used to get
504 DOC is the documentation string. */
506 static struct cmd_list_element *
507 add_set_or_show_cmd (const char *name,
509 enum command_class theclass,
511 const setting::erased_args &arg,
513 struct cmd_list_element **list)
515 struct cmd_list_element *c = add_cmd (name, theclass, doc, list);
517 gdb_assert (type == set_cmd || type == show_cmd);
519 c->var.emplace (var_type, arg);
521 /* This needs to be something besides NULL so that this isn't
522 treated as a help class. */
523 c->func = empty_func;
527 /* Add element named NAME to both the command SET_LIST and SHOW_LIST.
528 CLASS is as in add_cmd. VAR_TYPE is the kind of thing we are
529 setting. VAR is address of the variable being controlled by this
530 command. If nullptr is given as VAR, then both SET_SETTING_FUNC and
531 GET_SETTING_FUNC must be provided. SET_SETTING_FUNC and GET_SETTING_FUNC are
532 callbacks used to access and modify the underlying property, whatever its
533 storage is. SET_FUNC and SHOW_FUNC are the callback functions (if non-NULL).
534 SET_DOC, SHOW_DOC and HELP_DOC are the documentation strings.
536 Return the newly created set and show commands. */
538 static set_show_commands
539 add_setshow_cmd_full_erased (const char *name,
540 enum command_class theclass,
542 const setting::erased_args &args,
543 const char *set_doc, const char *show_doc,
544 const char *help_doc,
545 cmd_func_ftype *set_func,
546 show_value_ftype *show_func,
547 struct cmd_list_element **set_list,
548 struct cmd_list_element **show_list)
550 struct cmd_list_element *set;
551 struct cmd_list_element *show;
552 gdb::unique_xmalloc_ptr<char> full_set_doc;
553 gdb::unique_xmalloc_ptr<char> full_show_doc;
555 if (help_doc != NULL)
557 full_set_doc = xstrprintf ("%s\n%s", set_doc, help_doc);
558 full_show_doc = xstrprintf ("%s\n%s", show_doc, help_doc);
562 full_set_doc = make_unique_xstrdup (set_doc);
563 full_show_doc = make_unique_xstrdup (show_doc);
565 set = add_set_or_show_cmd (name, set_cmd, theclass, var_type, args,
566 full_set_doc.release (), set_list);
567 set->doc_allocated = 1;
569 if (set_func != NULL)
570 set->func = set_func;
572 show = add_set_or_show_cmd (name, show_cmd, theclass, var_type, args,
573 full_show_doc.release (), show_list);
574 show->doc_allocated = 1;
575 show->show_value_func = show_func;
576 /* Disable the default symbol completer. Doesn't make much sense
577 for the "show" command to complete on anything. */
578 set_cmd_completer (show, nullptr);
584 static set_show_commands
585 add_setshow_cmd_full (const char *name,
586 enum command_class theclass,
587 var_types var_type, T *var,
588 const char *set_doc, const char *show_doc,
589 const char *help_doc,
590 typename setting_func_types<T>::set set_setting_func,
591 typename setting_func_types<T>::get get_setting_func,
592 cmd_func_ftype *set_func,
593 show_value_ftype *show_func,
594 struct cmd_list_element **set_list,
595 struct cmd_list_element **show_list)
598 = setting::erase_args (var_type, var,
599 set_setting_func, get_setting_func);
601 return add_setshow_cmd_full_erased (name,
603 var_type, erased_args,
612 /* Add element named NAME to command list LIST (the list for set or
613 some sublist thereof). CLASS is as in add_cmd. ENUMLIST is a list
614 of strings which may follow NAME. VAR is address of the variable
615 which will contain the matching string (from ENUMLIST). */
618 add_setshow_enum_cmd (const char *name,
619 enum command_class theclass,
620 const char *const *enumlist,
623 const char *show_doc,
624 const char *help_doc,
625 cmd_func_ftype *set_func,
626 show_value_ftype *show_func,
627 struct cmd_list_element **set_list,
628 struct cmd_list_element **show_list)
630 /* We require *VAR to be initialized before this call, and
631 furthermore it must be == to one of the values in ENUMLIST. */
632 gdb_assert (var != nullptr && *var != nullptr);
633 for (int i = 0; ; ++i)
635 gdb_assert (enumlist[i] != nullptr);
636 if (*var == enumlist[i])
640 set_show_commands commands
641 = add_setshow_cmd_full<const char *> (name, theclass, var_enum, var,
642 set_doc, show_doc, help_doc,
643 nullptr, nullptr, set_func,
644 show_func, set_list, show_list);
645 commands.set->enums = enumlist;
649 /* Same as above but using a getter and a setter function instead of a pointer
650 to a global storage buffer. */
653 add_setshow_enum_cmd (const char *name, command_class theclass,
654 const char *const *enumlist, const char *set_doc,
655 const char *show_doc, const char *help_doc,
656 setting_func_types<const char *>::set set_func,
657 setting_func_types<const char *>::get get_func,
658 show_value_ftype *show_func,
659 cmd_list_element **set_list,
660 cmd_list_element **show_list)
662 auto cmds = add_setshow_cmd_full<const char *> (name, theclass, var_enum,
663 nullptr, set_doc, show_doc,
664 help_doc, set_func, get_func,
665 nullptr, show_func, set_list,
668 cmds.set->enums = enumlist;
673 /* See cli-decode.h. */
674 const char * const auto_boolean_enums[] = { "on", "off", "auto", NULL };
676 /* Add an auto-boolean command named NAME to both the set and show
677 command list lists. CLASS is as in add_cmd. VAR is address of the
678 variable which will contain the value. DOC is the documentation
679 string. FUNC is the corresponding callback. */
682 add_setshow_auto_boolean_cmd (const char *name,
683 enum command_class theclass,
684 enum auto_boolean *var,
685 const char *set_doc, const char *show_doc,
686 const char *help_doc,
687 cmd_func_ftype *set_func,
688 show_value_ftype *show_func,
689 struct cmd_list_element **set_list,
690 struct cmd_list_element **show_list)
692 set_show_commands commands
693 = add_setshow_cmd_full<enum auto_boolean> (name, theclass, var_auto_boolean,
694 var, set_doc, show_doc, help_doc,
695 nullptr, nullptr, set_func,
696 show_func, set_list, show_list);
698 commands.set->enums = auto_boolean_enums;
703 /* Same as above but using a getter and a setter function instead of a pointer
704 to a global storage buffer. */
707 add_setshow_auto_boolean_cmd (const char *name, command_class theclass,
708 const char *set_doc, const char *show_doc,
709 const char *help_doc,
710 setting_func_types<enum auto_boolean>::set set_func,
711 setting_func_types<enum auto_boolean>::get get_func,
712 show_value_ftype *show_func,
713 cmd_list_element **set_list,
714 cmd_list_element **show_list)
716 auto cmds = add_setshow_cmd_full<enum auto_boolean> (name, theclass,
722 set_list, show_list);
724 cmds.set->enums = auto_boolean_enums;
729 /* See cli-decode.h. */
730 const char * const boolean_enums[] = { "on", "off", NULL };
732 /* Add element named NAME to both the set and show command LISTs (the
733 list for set/show or some sublist thereof). CLASS is as in
734 add_cmd. VAR is address of the variable which will contain the
735 value. SET_DOC and SHOW_DOC are the documentation strings.
736 Returns the new command element. */
739 add_setshow_boolean_cmd (const char *name, enum command_class theclass, bool *var,
740 const char *set_doc, const char *show_doc,
741 const char *help_doc,
742 cmd_func_ftype *set_func,
743 show_value_ftype *show_func,
744 struct cmd_list_element **set_list,
745 struct cmd_list_element **show_list)
747 set_show_commands commands
748 = add_setshow_cmd_full<bool> (name, theclass, var_boolean, var,
749 set_doc, show_doc, help_doc,
750 nullptr, nullptr, set_func, show_func,
751 set_list, show_list);
753 commands.set->enums = boolean_enums;
758 /* Same as above but using a getter and a setter function instead of a pointer
759 to a global storage buffer. */
762 add_setshow_boolean_cmd (const char *name, command_class theclass,
763 const char *set_doc, const char *show_doc,
764 const char *help_doc,
765 setting_func_types<bool>::set set_func,
766 setting_func_types<bool>::get get_func,
767 show_value_ftype *show_func,
768 cmd_list_element **set_list,
769 cmd_list_element **show_list)
771 auto cmds = add_setshow_cmd_full<bool> (name, theclass, var_boolean, nullptr,
772 set_doc, show_doc, help_doc,
773 set_func, get_func, nullptr,
774 show_func, set_list, show_list);
776 cmds.set->enums = boolean_enums;
781 /* Add element named NAME to both the set and show command LISTs (the
782 list for set/show or some sublist thereof). */
785 add_setshow_filename_cmd (const char *name, enum command_class theclass,
787 const char *set_doc, const char *show_doc,
788 const char *help_doc,
789 cmd_func_ftype *set_func,
790 show_value_ftype *show_func,
791 struct cmd_list_element **set_list,
792 struct cmd_list_element **show_list)
794 set_show_commands commands
795 = add_setshow_cmd_full<std::string> (name, theclass, var_filename, var,
796 set_doc, show_doc, help_doc,
797 nullptr, nullptr, set_func,
798 show_func, set_list, show_list);
800 set_cmd_completer (commands.set, filename_completer);
805 /* Same as above but using a getter and a setter function instead of a pointer
806 to a global storage buffer. */
809 add_setshow_filename_cmd (const char *name, command_class theclass,
810 const char *set_doc, const char *show_doc,
811 const char *help_doc,
812 setting_func_types<std::string>::set set_func,
813 setting_func_types<std::string>::get get_func,
814 show_value_ftype *show_func,
815 cmd_list_element **set_list,
816 cmd_list_element **show_list)
818 auto cmds = add_setshow_cmd_full<std::string> (name, theclass, var_filename,
819 nullptr, set_doc, show_doc,
820 help_doc, set_func, get_func,
821 nullptr, show_func, set_list,
824 set_cmd_completer (cmds.set, filename_completer);
829 /* Add element named NAME to both the set and show command LISTs (the
830 list for set/show or some sublist thereof). */
833 add_setshow_string_cmd (const char *name, enum command_class theclass,
835 const char *set_doc, const char *show_doc,
836 const char *help_doc,
837 cmd_func_ftype *set_func,
838 show_value_ftype *show_func,
839 struct cmd_list_element **set_list,
840 struct cmd_list_element **show_list)
842 set_show_commands commands
843 = add_setshow_cmd_full<std::string> (name, theclass, var_string, var,
844 set_doc, show_doc, help_doc,
845 nullptr, nullptr, set_func,
846 show_func, set_list, show_list);
848 /* Disable the default symbol completer. */
849 set_cmd_completer (commands.set, nullptr);
854 /* Same as above but using a getter and a setter function instead of a pointer
855 to a global storage buffer. */
858 add_setshow_string_cmd (const char *name, command_class theclass,
859 const char *set_doc, const char *show_doc,
860 const char *help_doc,
861 setting_func_types<std::string>::set set_func,
862 setting_func_types<std::string>::get get_func,
863 show_value_ftype *show_func,
864 cmd_list_element **set_list,
865 cmd_list_element **show_list)
867 auto cmds = add_setshow_cmd_full<std::string> (name, theclass, var_string,
868 nullptr, set_doc, show_doc,
869 help_doc, set_func, get_func,
870 nullptr, show_func, set_list,
873 /* Disable the default symbol completer. */
874 set_cmd_completer (cmds.set, nullptr);
879 /* Add element named NAME to both the set and show command LISTs (the
880 list for set/show or some sublist thereof). */
883 add_setshow_string_noescape_cmd (const char *name, enum command_class theclass,
885 const char *set_doc, const char *show_doc,
886 const char *help_doc,
887 cmd_func_ftype *set_func,
888 show_value_ftype *show_func,
889 struct cmd_list_element **set_list,
890 struct cmd_list_element **show_list)
892 set_show_commands commands
893 = add_setshow_cmd_full<std::string> (name, theclass, var_string_noescape,
894 var, set_doc, show_doc, help_doc,
895 nullptr, nullptr, set_func, show_func,
896 set_list, show_list);
898 /* Disable the default symbol completer. */
899 set_cmd_completer (commands.set, nullptr);
904 /* Same as above but using a getter and a setter function instead of a pointer
905 to a global storage buffer. */
908 add_setshow_string_noescape_cmd (const char *name, command_class theclass,
909 const char *set_doc, const char *show_doc,
910 const char *help_doc,
911 setting_func_types<std::string>::set set_func,
912 setting_func_types<std::string>::get get_func,
913 show_value_ftype *show_func,
914 cmd_list_element **set_list,
915 cmd_list_element **show_list)
917 auto cmds = add_setshow_cmd_full<std::string> (name, theclass,
918 var_string_noescape, nullptr,
919 set_doc, show_doc, help_doc,
921 nullptr, show_func, set_list,
924 /* Disable the default symbol completer. */
925 set_cmd_completer (cmds.set, nullptr);
930 /* Add element named NAME to both the set and show command LISTs (the
931 list for set/show or some sublist thereof). */
934 add_setshow_optional_filename_cmd (const char *name, enum command_class theclass,
936 const char *set_doc, const char *show_doc,
937 const char *help_doc,
938 cmd_func_ftype *set_func,
939 show_value_ftype *show_func,
940 struct cmd_list_element **set_list,
941 struct cmd_list_element **show_list)
943 set_show_commands commands
944 = add_setshow_cmd_full<std::string> (name, theclass, var_optional_filename,
945 var, set_doc, show_doc, help_doc,
946 nullptr, nullptr, set_func, show_func,
947 set_list, show_list);
949 set_cmd_completer (commands.set, filename_completer);
954 /* Same as above but using a getter and a setter function instead of a pointer
955 to a global storage buffer. */
958 add_setshow_optional_filename_cmd (const char *name, command_class theclass,
959 const char *set_doc, const char *show_doc,
960 const char *help_doc,
961 setting_func_types<std::string>::set set_func,
962 setting_func_types<std::string>::get get_func,
963 show_value_ftype *show_func,
964 cmd_list_element **set_list,
965 cmd_list_element **show_list)
968 add_setshow_cmd_full<std::string> (name, theclass, var_optional_filename,
969 nullptr, set_doc, show_doc, help_doc,
970 set_func, get_func, nullptr, show_func,
973 set_cmd_completer (cmds.set, filename_completer);
978 /* Completes on literal "unlimited". Used by integer commands that
979 support a special "unlimited" value. */
982 integer_unlimited_completer (struct cmd_list_element *ignore,
983 completion_tracker &tracker,
984 const char *text, const char *word)
986 static const char * const keywords[] =
993 tracker.add_completion (make_unique_xstrdup ("NUMBER"));
994 complete_on_enum (tracker, keywords, text, word);
997 /* Add element named NAME to both the set and show command LISTs (the
998 list for set/show or some sublist thereof). CLASS is as in
999 add_cmd. VAR is address of the variable which will contain the
1000 value. SET_DOC and SHOW_DOC are the documentation strings. This
1001 function is only used in Python API. Please don't use it elsewhere. */
1004 add_setshow_integer_cmd (const char *name, enum command_class theclass,
1006 const char *set_doc, const char *show_doc,
1007 const char *help_doc,
1008 cmd_func_ftype *set_func,
1009 show_value_ftype *show_func,
1010 struct cmd_list_element **set_list,
1011 struct cmd_list_element **show_list)
1013 set_show_commands commands
1014 = add_setshow_cmd_full<int> (name, theclass, var_integer, var,
1015 set_doc, show_doc, help_doc,
1016 nullptr, nullptr, set_func,
1017 show_func, set_list, show_list);
1019 set_cmd_completer (commands.set, integer_unlimited_completer);
1024 /* Same as above but using a getter and a setter function instead of a pointer
1025 to a global storage buffer. */
1028 add_setshow_integer_cmd (const char *name, command_class theclass,
1029 const char *set_doc, const char *show_doc,
1030 const char *help_doc,
1031 setting_func_types<int>::set set_func,
1032 setting_func_types<int>::get get_func,
1033 show_value_ftype *show_func,
1034 cmd_list_element **set_list,
1035 cmd_list_element **show_list)
1037 auto cmds = add_setshow_cmd_full<int> (name, theclass, var_integer, nullptr,
1038 set_doc, show_doc, help_doc, set_func,
1039 get_func, nullptr, show_func, set_list,
1042 set_cmd_completer (cmds.set, integer_unlimited_completer);
1047 /* Add element named NAME to both the set and show command LISTs (the
1048 list for set/show or some sublist thereof). CLASS is as in
1049 add_cmd. VAR is address of the variable which will contain the
1050 value. SET_DOC and SHOW_DOC are the documentation strings. */
1053 add_setshow_uinteger_cmd (const char *name, enum command_class theclass,
1055 const char *set_doc, const char *show_doc,
1056 const char *help_doc,
1057 cmd_func_ftype *set_func,
1058 show_value_ftype *show_func,
1059 struct cmd_list_element **set_list,
1060 struct cmd_list_element **show_list)
1062 set_show_commands commands
1063 = add_setshow_cmd_full<unsigned int> (name, theclass, var_uinteger, var,
1064 set_doc, show_doc, help_doc,
1065 nullptr, nullptr, set_func,
1066 show_func, set_list, show_list);
1068 set_cmd_completer (commands.set, integer_unlimited_completer);
1073 /* Same as above but using a getter and a setter function instead of a pointer
1074 to a global storage buffer. */
1077 add_setshow_uinteger_cmd (const char *name, command_class theclass,
1078 const char *set_doc, const char *show_doc,
1079 const char *help_doc,
1080 setting_func_types<unsigned int>::set set_func,
1081 setting_func_types<unsigned int>::get get_func,
1082 show_value_ftype *show_func,
1083 cmd_list_element **set_list,
1084 cmd_list_element **show_list)
1086 auto cmds = add_setshow_cmd_full<unsigned int> (name, theclass, var_uinteger,
1087 nullptr, set_doc, show_doc,
1088 help_doc, set_func, get_func,
1089 nullptr, show_func, set_list,
1092 set_cmd_completer (cmds.set, integer_unlimited_completer);
1097 /* Add element named NAME to both the set and show command LISTs (the
1098 list for set/show or some sublist thereof). CLASS is as in
1099 add_cmd. VAR is address of the variable which will contain the
1100 value. SET_DOC and SHOW_DOC are the documentation strings. */
1103 add_setshow_zinteger_cmd (const char *name, enum command_class theclass,
1105 const char *set_doc, const char *show_doc,
1106 const char *help_doc,
1107 cmd_func_ftype *set_func,
1108 show_value_ftype *show_func,
1109 struct cmd_list_element **set_list,
1110 struct cmd_list_element **show_list)
1112 return add_setshow_cmd_full<int> (name, theclass, var_zinteger, var,
1113 set_doc, show_doc, help_doc,
1114 nullptr, nullptr, set_func,
1115 show_func, set_list, show_list);
1118 /* Same as above but using a getter and a setter function instead of a pointer
1119 to a global storage buffer. */
1122 add_setshow_zinteger_cmd (const char *name, command_class theclass,
1123 const char *set_doc, const char *show_doc,
1124 const char *help_doc,
1125 setting_func_types<int>::set set_func,
1126 setting_func_types<int>::get get_func,
1127 show_value_ftype *show_func,
1128 cmd_list_element **set_list,
1129 cmd_list_element **show_list)
1131 return add_setshow_cmd_full<int> (name, theclass, var_zinteger, nullptr,
1132 set_doc, show_doc, help_doc, set_func,
1133 get_func, nullptr, show_func, set_list,
1138 add_setshow_zuinteger_unlimited_cmd (const char *name,
1139 enum command_class theclass,
1141 const char *set_doc,
1142 const char *show_doc,
1143 const char *help_doc,
1144 cmd_func_ftype *set_func,
1145 show_value_ftype *show_func,
1146 struct cmd_list_element **set_list,
1147 struct cmd_list_element **show_list)
1149 set_show_commands commands
1150 = add_setshow_cmd_full<int> (name, theclass, var_zuinteger_unlimited, var,
1151 set_doc, show_doc, help_doc, nullptr,
1152 nullptr, set_func, show_func, set_list,
1155 set_cmd_completer (commands.set, integer_unlimited_completer);
1160 /* Same as above but using a getter and a setter function instead of a pointer
1161 to a global storage buffer. */
1164 add_setshow_zuinteger_unlimited_cmd (const char *name, command_class theclass,
1165 const char *set_doc, const char *show_doc,
1166 const char *help_doc,
1167 setting_func_types<int>::set set_func,
1168 setting_func_types<int>::get get_func,
1169 show_value_ftype *show_func,
1170 cmd_list_element **set_list,
1171 cmd_list_element **show_list)
1174 = add_setshow_cmd_full<int> (name, theclass, var_zuinteger_unlimited,
1175 nullptr, set_doc, show_doc, help_doc, set_func,
1176 get_func, nullptr, show_func, set_list,
1179 set_cmd_completer (cmds.set, integer_unlimited_completer);
1184 /* Add element named NAME to both the set and show command LISTs (the
1185 list for set/show or some sublist thereof). CLASS is as in
1186 add_cmd. VAR is address of the variable which will contain the
1187 value. SET_DOC and SHOW_DOC are the documentation strings. */
1190 add_setshow_zuinteger_cmd (const char *name, enum command_class theclass,
1192 const char *set_doc, const char *show_doc,
1193 const char *help_doc,
1194 cmd_func_ftype *set_func,
1195 show_value_ftype *show_func,
1196 struct cmd_list_element **set_list,
1197 struct cmd_list_element **show_list)
1199 return add_setshow_cmd_full<unsigned int> (name, theclass, var_zuinteger,
1200 var, set_doc, show_doc, help_doc,
1201 nullptr, nullptr, set_func,
1202 show_func, set_list, show_list);
1205 /* Same as above but using a getter and a setter function instead of a pointer
1206 to a global storage buffer. */
1209 add_setshow_zuinteger_cmd (const char *name, command_class theclass,
1210 const char *set_doc, const char *show_doc,
1211 const char *help_doc,
1212 setting_func_types<unsigned int>::set set_func,
1213 setting_func_types<unsigned int>::get get_func,
1214 show_value_ftype *show_func,
1215 cmd_list_element **set_list,
1216 cmd_list_element **show_list)
1218 return add_setshow_cmd_full<unsigned int> (name, theclass, var_zuinteger,
1219 nullptr, set_doc, show_doc,
1220 help_doc, set_func, get_func,
1221 nullptr, show_func, set_list,
1225 /* Remove the command named NAME from the command list. Return the list
1226 commands which were aliased to the deleted command. The various *HOOKs are
1227 set to the pre- and post-hook commands for the deleted command. If the
1228 command does not have a hook, the corresponding out parameter is set to
1231 static cmd_list_element::aliases_list_type
1232 delete_cmd (const char *name, struct cmd_list_element **list,
1233 struct cmd_list_element **prehook,
1234 struct cmd_list_element **prehookee,
1235 struct cmd_list_element **posthook,
1236 struct cmd_list_element **posthookee)
1238 struct cmd_list_element *iter;
1239 struct cmd_list_element **previous_chain_ptr;
1240 cmd_list_element::aliases_list_type aliases;
1246 previous_chain_ptr = list;
1248 for (iter = *previous_chain_ptr; iter; iter = *previous_chain_ptr)
1250 if (strcmp (iter->name, name) == 0)
1252 if (iter->destroyer)
1253 iter->destroyer (iter, iter->context ());
1255 if (iter->hookee_pre)
1256 iter->hookee_pre->hook_pre = 0;
1257 *prehook = iter->hook_pre;
1258 *prehookee = iter->hookee_pre;
1259 if (iter->hookee_post)
1260 iter->hookee_post->hook_post = 0;
1261 *posthook = iter->hook_post;
1262 *posthookee = iter->hookee_post;
1264 /* Update the link. */
1265 *previous_chain_ptr = iter->next;
1267 aliases = std::move (iter->aliases);
1269 /* If this command was an alias, remove it from the list of
1271 if (iter->is_alias ())
1273 auto it = iter->alias_target->aliases.iterator_to (*iter);
1274 iter->alias_target->aliases.erase (it);
1279 /* We won't see another command with the same name. */
1283 previous_chain_ptr = &iter->next;
1289 /* Shorthands to the commands above. */
1291 /* Add an element to the list of info subcommands. */
1293 struct cmd_list_element *
1294 add_info (const char *name, cmd_simple_func_ftype *fun, const char *doc)
1296 return add_cmd (name, class_info, fun, doc, &infolist);
1299 /* Add an alias to the list of info subcommands. */
1302 add_info_alias (const char *name, cmd_list_element *target, int abbrev_flag)
1304 return add_alias_cmd (name, target, class_run, abbrev_flag, &infolist);
1307 /* Add an element to the list of commands. */
1309 struct cmd_list_element *
1310 add_com (const char *name, enum command_class theclass,
1311 cmd_simple_func_ftype *fun,
1314 return add_cmd (name, theclass, fun, doc, &cmdlist);
1317 /* Add an alias or abbreviation command to the list of commands.
1318 For aliases predefined by GDB (such as bt), THECLASS must be
1319 different of class_alias, as class_alias is used to identify
1320 user defined aliases. */
1323 add_com_alias (const char *name, cmd_list_element *target,
1324 command_class theclass, int abbrev_flag)
1326 return add_alias_cmd (name, target, theclass, abbrev_flag, &cmdlist);
1329 /* Add an element with a suppress notification to the list of commands. */
1331 struct cmd_list_element *
1332 add_com_suppress_notification (const char *name, enum command_class theclass,
1333 cmd_simple_func_ftype *fun, const char *doc,
1334 bool *suppress_notification)
1336 return add_cmd_suppress_notification (name, theclass, fun, doc,
1337 &cmdlist, suppress_notification);
1340 /* Print the prefix of C followed by name of C in title style. */
1343 fput_command_name_styled (const cmd_list_element &c, struct ui_file *stream)
1345 std::string prefixname
1346 = c.prefix == nullptr ? "" : c.prefix->prefixname ();
1348 fprintf_styled (stream, title_style.style (), "%s%s",
1349 prefixname.c_str (), c.name);
1352 /* True if ALIAS has a user-defined documentation. */
1355 user_documented_alias (const cmd_list_element &alias)
1357 gdb_assert (alias.is_alias ());
1358 /* Alias is user documented if it has an allocated documentation
1359 that differs from the aliased command. */
1360 return (alias.doc_allocated
1361 && strcmp (alias.doc, alias.alias_target->doc) != 0);
1364 /* Print the definition of alias C using title style for alias
1365 and aliased command. */
1368 fput_alias_definition_styled (const cmd_list_element &c,
1369 struct ui_file *stream)
1371 gdb_assert (c.is_alias ());
1372 gdb_puts (" alias ", stream);
1373 fput_command_name_styled (c, stream);
1374 gdb_printf (stream, " = ");
1375 fput_command_name_styled (*c.alias_target, stream);
1376 gdb_printf (stream, " %s\n", c.default_args.c_str ());
1379 /* Print the definition of CMD aliases not deprecated and having default args
1380 and not specifically documented by the user. */
1383 fput_aliases_definition_styled (const cmd_list_element &cmd,
1384 struct ui_file *stream)
1386 for (const cmd_list_element &alias : cmd.aliases)
1387 if (!alias.cmd_deprecated
1388 && !user_documented_alias (alias)
1389 && !alias.default_args.empty ())
1390 fput_alias_definition_styled (alias, stream);
1393 /* If C has one or more aliases, style print the name of C and the name of its
1394 aliases not documented specifically by the user, separated by commas.
1395 If ALWAYS_FPUT_C_NAME, print the name of C even if it has no aliases.
1396 If one or more names are printed, POSTFIX is printed after the last name.
1400 fput_command_names_styled (const cmd_list_element &c,
1401 bool always_fput_c_name, const char *postfix,
1402 struct ui_file *stream)
1404 /* First, check if we are going to print something. That is, either if
1405 ALWAYS_FPUT_C_NAME is true or if there exists at least one non-deprecated
1406 alias not documented specifically by the user. */
1408 auto print_alias = [] (const cmd_list_element &alias)
1410 return !alias.cmd_deprecated && !user_documented_alias (alias);
1413 bool print_something = always_fput_c_name;
1414 if (!print_something)
1415 for (const cmd_list_element &alias : c.aliases)
1417 if (!print_alias (alias))
1420 print_something = true;
1424 if (print_something)
1425 fput_command_name_styled (c, stream);
1427 for (const cmd_list_element &alias : c.aliases)
1429 if (!print_alias (alias))
1432 gdb_puts (", ", stream);
1433 stream->wrap_here (3);
1434 fput_command_name_styled (alias, stream);
1437 if (print_something)
1438 gdb_puts (postfix, stream);
1441 /* If VERBOSE, print the full help for command C and highlight the
1442 documentation parts matching HIGHLIGHT,
1443 otherwise print only one-line help for command C. */
1446 print_doc_of_command (const cmd_list_element &c, const char *prefix,
1447 bool verbose, compiled_regex &highlight,
1448 struct ui_file *stream)
1450 /* When printing the full documentation, add a line to separate
1451 this documentation from the previous command help, in the likely
1452 case that apropos finds several commands. */
1454 gdb_puts ("\n", stream);
1456 fput_command_names_styled (c, true,
1457 verbose ? "" : " -- ", stream);
1460 gdb_puts ("\n", stream);
1461 fput_aliases_definition_styled (c, stream);
1462 fputs_highlighted (c.doc, highlight, stream);
1463 gdb_puts ("\n", stream);
1467 print_doc_line (stream, c.doc, false);
1468 gdb_puts ("\n", stream);
1469 fput_aliases_definition_styled (c, stream);
1473 /* Recursively walk the commandlist structures, and print out the
1474 documentation of commands that match our regex in either their
1475 name, or their documentation.
1476 If VERBOSE, prints the complete documentation and highlight the
1477 documentation parts matching REGEX, otherwise prints only
1481 apropos_cmd (struct ui_file *stream,
1482 struct cmd_list_element *commandlist,
1483 bool verbose, compiled_regex ®ex, const char *prefix)
1485 struct cmd_list_element *c;
1488 /* Walk through the commands. */
1489 for (c=commandlist;c;c=c->next)
1491 if (c->is_alias () && !user_documented_alias (*c))
1493 /* Command aliases/abbreviations not specifically documented by the
1494 user are skipped to ensure we print the doc of a command only once,
1495 when encountering the aliased command. */
1499 returnvalue = -1; /* Needed to avoid double printing. */
1500 if (c->name != NULL)
1502 size_t name_len = strlen (c->name);
1504 /* Try to match against the name. */
1505 returnvalue = regex.search (c->name, name_len, 0, name_len, NULL);
1506 if (returnvalue >= 0)
1507 print_doc_of_command (*c, prefix, verbose, regex, stream);
1509 /* Try to match against the name of the aliases. */
1510 for (const cmd_list_element &alias : c->aliases)
1512 name_len = strlen (alias.name);
1513 returnvalue = regex.search (alias.name, name_len, 0, name_len, NULL);
1514 if (returnvalue >= 0)
1516 print_doc_of_command (*c, prefix, verbose, regex, stream);
1521 if (c->doc != NULL && returnvalue < 0)
1523 size_t doc_len = strlen (c->doc);
1525 /* Try to match against documentation. */
1526 if (regex.search (c->doc, doc_len, 0, doc_len, NULL) >= 0)
1527 print_doc_of_command (*c, prefix, verbose, regex, stream);
1529 /* Check if this command has subcommands. */
1530 if (c->is_prefix ())
1532 /* Recursively call ourselves on the subcommand list,
1533 passing the right prefix in. */
1534 apropos_cmd (stream, *c->subcommands, verbose, regex,
1535 c->prefixname ().c_str ());
1540 /* This command really has to deal with two things:
1541 1) I want documentation on *this string* (usually called by
1542 "help commandname").
1544 2) I want documentation on *this list* (usually called by giving a
1545 command that requires subcommands. Also called by saying just
1548 I am going to split this into two separate commands, help_cmd and
1552 help_cmd (const char *command, struct ui_file *stream)
1554 struct cmd_list_element *c, *alias, *prefix_cmd, *c_cmd;
1558 help_list (cmdlist, "", all_classes, stream);
1562 if (strcmp (command, "all") == 0)
1568 const char *orig_command = command;
1569 c = lookup_cmd (&command, cmdlist, "", NULL, 0, 0);
1574 lookup_cmd_composition (orig_command, &alias, &prefix_cmd, &c_cmd);
1576 /* There are three cases here.
1577 If c->subcommands is nonzero, we have a prefix command.
1578 Print its documentation, then list its subcommands.
1580 If c->func is non NULL, we really have a command. Print its
1581 documentation and return.
1583 If c->func is NULL, we have a class name. Print its
1584 documentation (as if it were a command) and then set class to the
1585 number of this class so that the commands in the class will be
1588 if (alias == nullptr || !user_documented_alias (*alias))
1590 /* Case of a normal command, or an alias not explictly
1591 documented by the user. */
1592 /* If the user asked 'help somecommand' and there is no alias,
1593 the false indicates to not output the (single) command name. */
1594 fput_command_names_styled (*c, false, "\n", stream);
1595 fput_aliases_definition_styled (*c, stream);
1596 gdb_puts (c->doc, stream);
1600 /* Case of an alias explictly documented by the user.
1601 Only output the alias definition and its explicit documentation. */
1602 fput_alias_definition_styled (*alias, stream);
1603 fput_command_names_styled (*alias, false, "\n", stream);
1604 gdb_puts (alias->doc, stream);
1606 gdb_puts ("\n", stream);
1608 if (!c->is_prefix () && !c->is_command_class_help ())
1611 gdb_printf (stream, "\n");
1613 /* If this is a prefix command, print it's subcommands. */
1614 if (c->is_prefix ())
1615 help_list (*c->subcommands, c->prefixname ().c_str (),
1616 all_commands, stream);
1618 /* If this is a class name, print all of the commands in the class. */
1619 if (c->is_command_class_help ())
1620 help_list (cmdlist, "", c->theclass, stream);
1622 if (c->hook_pre || c->hook_post)
1624 "\nThis command has a hook (or hooks) defined:\n");
1628 "\tThis command is run after : %s (pre hook)\n",
1632 "\tThis command is run before : %s (post hook)\n",
1633 c->hook_post->name);
1637 * Get a specific kind of help on a command list.
1640 * CMDTYPE is the prefix to use in the title string.
1641 * CLASS is the class with which to list the nodes of this list (see
1642 * documentation for help_cmd_list below), As usual, ALL_COMMANDS for
1643 * everything, ALL_CLASSES for just classes, and non-negative for only things
1644 * in a specific class.
1645 * and STREAM is the output stream on which to print things.
1646 * If you call this routine with a class >= 0, it recurses.
1649 help_list (struct cmd_list_element *list, const char *cmdtype,
1650 enum command_class theclass, struct ui_file *stream)
1653 char *cmdtype1, *cmdtype2;
1655 /* If CMDTYPE is "foo ", CMDTYPE1 gets " foo" and CMDTYPE2 gets "foo sub".
1657 len = strlen (cmdtype);
1658 cmdtype1 = (char *) alloca (len + 1);
1660 cmdtype2 = (char *) alloca (len + 4);
1665 memcpy (cmdtype1 + 1, cmdtype, len - 1);
1667 memcpy (cmdtype2, cmdtype, len - 1);
1668 strcpy (cmdtype2 + len - 1, " sub");
1671 if (theclass == all_classes)
1672 gdb_printf (stream, "List of classes of %scommands:\n\n", cmdtype2);
1674 gdb_printf (stream, "List of %scommands:\n\n", cmdtype2);
1676 help_cmd_list (list, theclass, theclass >= 0, stream);
1678 if (theclass == all_classes)
1680 gdb_printf (stream, "\n\
1681 Type \"help%s\" followed by a class name for a list of commands in ",
1683 stream->wrap_here (0);
1684 gdb_printf (stream, "that class.");
1686 gdb_printf (stream, "\n\
1687 Type \"help all\" for the list of all commands.");
1690 gdb_printf (stream, "\nType \"help%s\" followed by %scommand name ",
1691 cmdtype1, cmdtype2);
1692 stream->wrap_here (0);
1693 gdb_puts ("for ", stream);
1694 stream->wrap_here (0);
1695 gdb_puts ("full ", stream);
1696 stream->wrap_here (0);
1697 gdb_puts ("documentation.\n", stream);
1698 gdb_puts ("Type \"apropos word\" to search "
1699 "for commands related to \"word\".\n", stream);
1700 gdb_puts ("Type \"apropos -v word\" for full documentation", stream);
1701 stream->wrap_here (0);
1702 gdb_puts (" of commands related to \"word\".\n", stream);
1703 gdb_puts ("Command name abbreviations are allowed if unambiguous.\n",
1708 help_all (struct ui_file *stream)
1710 struct cmd_list_element *c;
1711 int seen_unclassified = 0;
1713 for (c = cmdlist; c; c = c->next)
1717 /* If this is a class name, print all of the commands in the
1720 if (c->is_command_class_help ())
1722 gdb_printf (stream, "\nCommand class: %s\n\n", c->name);
1723 help_cmd_list (cmdlist, c->theclass, true, stream);
1727 /* While it's expected that all commands are in some class,
1728 as a safety measure, we'll print commands outside of any
1729 class at the end. */
1731 for (c = cmdlist; c; c = c->next)
1736 if (c->theclass == no_class)
1738 if (!seen_unclassified)
1740 gdb_printf (stream, "\nUnclassified commands\n\n");
1741 seen_unclassified = 1;
1743 print_help_for_command (*c, true, stream);
1749 /* See cli-decode.h. */
1752 print_doc_line (struct ui_file *stream, const char *str,
1753 bool for_value_prefix)
1755 static char *line_buffer = 0;
1756 static int line_size;
1762 line_buffer = (char *) xmalloc (line_size);
1765 /* Searches for the first end of line or the end of STR. */
1767 while (*p && *p != '\n')
1769 if (p - str > line_size - 1)
1771 line_size = p - str + 1;
1772 xfree (line_buffer);
1773 line_buffer = (char *) xmalloc (line_size);
1775 strncpy (line_buffer, str, p - str);
1776 if (for_value_prefix)
1778 if (islower (line_buffer[0]))
1779 line_buffer[0] = toupper (line_buffer[0]);
1780 gdb_assert (p > str);
1781 if (line_buffer[p - str - 1] == '.')
1782 line_buffer[p - str - 1] = '\0';
1784 line_buffer[p - str] = '\0';
1787 line_buffer[p - str] = '\0';
1788 gdb_puts (line_buffer, stream);
1791 /* Print one-line help for command C.
1792 If RECURSE is non-zero, also print one-line descriptions
1793 of all prefixed subcommands. */
1795 print_help_for_command (const cmd_list_element &c,
1796 bool recurse, struct ui_file *stream)
1798 fput_command_names_styled (c, true, " -- ", stream);
1799 print_doc_line (stream, c.doc, false);
1800 gdb_puts ("\n", stream);
1801 if (!c.default_args.empty ())
1802 fput_alias_definition_styled (c, stream);
1803 fput_aliases_definition_styled (c, stream);
1807 && c.abbrev_flag == 0)
1808 /* Subcommands of a prefix command typically have 'all_commands'
1809 as class. If we pass CLASS to recursive invocation,
1810 most often we won't see anything. */
1811 help_cmd_list (*c.subcommands, all_commands, true, stream);
1815 * Implement a help command on command list LIST.
1816 * RECURSE should be non-zero if this should be done recursively on
1817 * all sublists of LIST.
1818 * STREAM is the stream upon which the output should be written.
1819 * THECLASS should be:
1820 * A non-negative class number to list only commands in that
1821 * ALL_COMMANDS to list all commands in list.
1822 * ALL_CLASSES to list all classes in list.
1824 * Note that aliases are only shown when THECLASS is class_alias.
1825 * In the other cases, the aliases will be shown together with their
1828 * Note that RECURSE will be active on *all* sublists, not just the
1829 * ones selected by the criteria above (ie. the selection mechanism
1830 * is at the low level, not the high-level).
1834 help_cmd_list (struct cmd_list_element *list, enum command_class theclass,
1835 bool recurse, struct ui_file *stream)
1837 struct cmd_list_element *c;
1839 for (c = list; c; c = c->next)
1841 if (c->abbrev_flag == 1 || c->cmd_deprecated)
1843 /* Do not show abbreviations or deprecated commands. */
1847 if (c->is_alias () && theclass != class_alias)
1849 /* Do not show an alias, unless specifically showing the
1850 list of aliases: for all other classes, an alias is
1851 shown (if needed) together with its aliased command. */
1855 if (theclass == all_commands
1856 || (theclass == all_classes && c->is_command_class_help ())
1857 || (theclass == c->theclass && !c->is_command_class_help ()))
1860 - showing all commands
1861 - showing all classes and C is a help class
1862 - showing commands of THECLASS and C is not the help class */
1864 /* If we show the class_alias and C is an alias, do not recurse,
1865 as this would show the (possibly very long) not very useful
1866 list of sub-commands of the aliased command. */
1867 print_help_for_command
1869 recurse && (theclass != class_alias || !c->is_alias ()),
1875 && (theclass == class_user || theclass == class_alias)
1878 /* User-defined commands or aliases may be subcommands. */
1879 help_cmd_list (*c->subcommands, theclass, recurse, stream);
1883 /* Do not show C or recurse on C, e.g. because C does not belong to
1884 THECLASS or because C is a help class. */
1889 /* Search the input clist for 'command'. Return the command if
1890 found (or NULL if not), and return the number of commands
1893 static struct cmd_list_element *
1894 find_cmd (const char *command, int len, struct cmd_list_element *clist,
1895 int ignore_help_classes, int *nfound)
1897 struct cmd_list_element *found, *c;
1901 for (c = clist; c; c = c->next)
1902 if (!strncmp (command, c->name, len)
1903 && (!ignore_help_classes || !c->is_command_class_help ()))
1907 if (c->name[len] == '\0')
1916 /* Return the length of command name in TEXT. */
1919 find_command_name_length (const char *text)
1921 const char *p = text;
1923 /* Treating underscores as part of command words is important
1924 so that "set args_foo()" doesn't get interpreted as
1925 "set args _foo()". */
1926 /* Some characters are only used for TUI specific commands.
1927 However, they are always allowed for the sake of consistency.
1929 Note that this is larger than the character set allowed when
1930 creating user-defined commands. */
1932 /* Recognize the single character commands so that, e.g., "!ls"
1933 works as expected. */
1934 if (*p == '!' || *p == '|')
1937 while (valid_cmd_char_p (*p)
1938 /* Characters used by TUI specific commands. */
1939 || *p == '+' || *p == '<' || *p == '>' || *p == '$')
1945 /* See command.h. */
1948 valid_cmd_char_p (int c)
1950 /* Alas "42" is a legitimate user-defined command.
1951 In the interests of not breaking anything we preserve that. */
1953 return isalnum (c) || c == '-' || c == '_' || c == '.';
1956 /* See command.h. */
1959 valid_user_defined_cmd_name_p (const char *name)
1966 for (p = name; *p != '\0'; ++p)
1968 if (valid_cmd_char_p (*p))
1977 /* See command.h. */
1979 struct cmd_list_element *
1980 lookup_cmd_1 (const char **text, struct cmd_list_element *clist,
1981 struct cmd_list_element **result_list, std::string *default_args,
1982 int ignore_help_classes, bool lookup_for_completion_p)
1986 struct cmd_list_element *found, *c;
1987 bool found_alias = false;
1988 const char *line = *text;
1990 while (**text == ' ' || **text == '\t')
1993 /* Identify the name of the command. */
1994 len = find_command_name_length (*text);
1996 /* If nothing but whitespace, return 0. */
2000 /* *text and p now bracket the first command word to lookup (and
2001 it's length is len). We copy this into a local temporary. */
2004 command = (char *) alloca (len + 1);
2005 memcpy (command, *text, len);
2006 command[len] = '\0';
2011 found = find_cmd (command, len, clist, ignore_help_classes, &nfound);
2013 /* If nothing matches, we have a simple failure. */
2019 if (result_list != nullptr)
2020 /* Will be modified in calling routine
2021 if we know what the prefix command is. */
2023 if (default_args != nullptr)
2024 *default_args = std::string ();
2025 return CMD_LIST_AMBIGUOUS; /* Ambiguous. */
2028 /* We've matched something on this list. Move text pointer forward. */
2032 if (found->is_alias ())
2034 /* We drop the alias (abbreviation) in favor of the command it
2035 is pointing to. If the alias is deprecated, though, we need to
2036 warn the user about it before we drop it. Note that while we
2037 are warning about the alias, we may also warn about the command
2038 itself and we will adjust the appropriate DEPRECATED_WARN_USER
2041 if (found->deprecated_warn_user && !lookup_for_completion_p)
2042 deprecated_cmd_warning (line, clist);
2045 /* Return the default_args of the alias, not the default_args
2046 of the command it is pointing to. */
2047 if (default_args != nullptr)
2048 *default_args = found->default_args;
2049 found = found->alias_target;
2052 /* If we found a prefix command, keep looking. */
2054 if (found->is_prefix ())
2056 c = lookup_cmd_1 (text, *found->subcommands, result_list, default_args,
2057 ignore_help_classes, lookup_for_completion_p);
2060 /* Didn't find anything; this is as far as we got. */
2061 if (result_list != nullptr)
2062 *result_list = clist;
2063 if (!found_alias && default_args != nullptr)
2064 *default_args = found->default_args;
2067 else if (c == CMD_LIST_AMBIGUOUS)
2069 /* We've gotten this far properly, but the next step is
2070 ambiguous. We need to set the result list to the best
2071 we've found (if an inferior hasn't already set it). */
2072 if (result_list != nullptr)
2074 /* This used to say *result_list = *found->subcommands.
2075 If that was correct, need to modify the documentation
2076 at the top of this function to clarify what is
2077 supposed to be going on. */
2078 *result_list = found;
2079 /* For ambiguous commands, do not return any default_args args. */
2080 if (default_args != nullptr)
2081 *default_args = std::string ();
2092 if (result_list != nullptr)
2093 *result_list = clist;
2094 if (!found_alias && default_args != nullptr)
2095 *default_args = found->default_args;
2100 /* All this hair to move the space to the front of cmdtype */
2103 undef_cmd_error (const char *cmdtype, const char *q)
2105 error (_("Undefined %scommand: \"%s\". Try \"help%s%.*s\"."),
2108 *cmdtype ? " " : "",
2109 (int) strlen (cmdtype) - 1,
2113 /* Look up the contents of *LINE as a command in the command list LIST.
2114 LIST is a chain of struct cmd_list_element's.
2115 If it is found, return the struct cmd_list_element for that command,
2116 update *LINE to point after the command name, at the first argument
2117 and update *DEFAULT_ARGS (if DEFAULT_ARGS is not null) to the default
2118 args to prepend to the user provided args when running the command.
2119 Note that if the found cmd_list_element is found via an alias,
2120 the default args of the alias are returned.
2122 If not found, call error if ALLOW_UNKNOWN is zero
2123 otherwise (or if error returns) return zero.
2124 Call error if specified command is ambiguous,
2125 unless ALLOW_UNKNOWN is negative.
2126 CMDTYPE precedes the word "command" in the error message.
2128 If IGNORE_HELP_CLASSES is nonzero, ignore any command list
2129 elements which are actually help classes rather than commands (i.e.
2130 the function field of the struct cmd_list_element is 0). */
2132 struct cmd_list_element *
2133 lookup_cmd (const char **line, struct cmd_list_element *list,
2134 const char *cmdtype,
2135 std::string *default_args,
2136 int allow_unknown, int ignore_help_classes)
2138 struct cmd_list_element *last_list = 0;
2139 struct cmd_list_element *c;
2141 /* Note: Do not remove trailing whitespace here because this
2142 would be wrong for complete_command. Jim Kingdon */
2145 error (_("Lack of needed %scommand"), cmdtype);
2147 c = lookup_cmd_1 (line, list, &last_list, default_args, ignore_help_classes);
2154 int len = find_command_name_length (*line);
2156 q = (char *) alloca (len + 1);
2157 strncpy (q, *line, len);
2159 undef_cmd_error (cmdtype, q);
2164 else if (c == CMD_LIST_AMBIGUOUS)
2166 /* Ambigous. Local values should be off subcommands or called
2168 int local_allow_unknown = (last_list ? last_list->allow_unknown :
2170 std::string local_cmdtype
2171 = last_list ? last_list->prefixname () : cmdtype;
2172 struct cmd_list_element *local_list =
2173 (last_list ? *(last_list->subcommands) : list);
2175 if (local_allow_unknown < 0)
2178 return last_list; /* Found something. */
2180 return 0; /* Found nothing. */
2184 /* Report as error. */
2189 ((*line)[amb_len] && (*line)[amb_len] != ' '
2190 && (*line)[amb_len] != '\t');
2195 for (c = local_list; c; c = c->next)
2196 if (!strncmp (*line, c->name, amb_len))
2198 if (strlen (ambbuf) + strlen (c->name) + 6
2199 < (int) sizeof ambbuf)
2201 if (strlen (ambbuf))
2202 strcat (ambbuf, ", ");
2203 strcat (ambbuf, c->name);
2207 strcat (ambbuf, "..");
2211 error (_("Ambiguous %scommand \"%s\": %s."),
2212 local_cmdtype.c_str (), *line, ambbuf);
2217 if (c->type == set_cmd && **line != '\0' && !isspace (**line))
2218 error (_("Argument must be preceded by space."));
2220 /* We've got something. It may still not be what the caller
2221 wants (if this command *needs* a subcommand). */
2222 while (**line == ' ' || **line == '\t')
2225 if (c->is_prefix () && **line && !c->allow_unknown)
2226 undef_cmd_error (c->prefixname ().c_str (), *line);
2228 /* Seems to be what he wants. Return it. */
2234 /* See command.h. */
2236 struct cmd_list_element *
2237 lookup_cmd_exact (const char *name,
2238 struct cmd_list_element *list,
2239 bool ignore_help_classes)
2241 const char *tem = name;
2242 struct cmd_list_element *cmd = lookup_cmd (&tem, list, "", NULL, -1,
2243 ignore_help_classes);
2244 if (cmd != nullptr && strcmp (name, cmd->name) != 0)
2249 /* We are here presumably because an alias or command in TEXT is
2250 deprecated and a warning message should be generated. This
2251 function decodes TEXT and potentially generates a warning message
2254 Example for 'set endian big' which has a fictitious alias 'seb'.
2256 If alias wasn't used in TEXT, and the command is deprecated:
2257 "warning: 'set endian big' is deprecated."
2259 If alias was used, and only the alias is deprecated:
2260 "warning: 'seb' an alias for the command 'set endian big' is deprecated."
2262 If alias was used and command is deprecated (regardless of whether
2263 the alias itself is deprecated:
2265 "warning: 'set endian big' (seb) is deprecated."
2267 After the message has been sent, clear the appropriate flags in the
2268 command and/or the alias so the user is no longer bothered.
2272 deprecated_cmd_warning (const char *text, struct cmd_list_element *list)
2274 struct cmd_list_element *alias = nullptr;
2275 struct cmd_list_element *cmd = nullptr;
2277 /* Return if text doesn't evaluate to a command. We place this lookup
2278 within its own scope so that the PREFIX_CMD local is not visible
2279 later in this function. The value returned in PREFIX_CMD is based on
2280 the prefix found in TEXT, and is our case this prefix can be missing
2281 in some situations (when LIST is not the global CMDLIST).
2283 It is better for our purposes to use the prefix commands directly from
2284 the ALIAS and CMD results. */
2286 struct cmd_list_element *prefix_cmd = nullptr;
2287 if (!lookup_cmd_composition_1 (text, &alias, &prefix_cmd, &cmd, list))
2291 /* Return if nothing is deprecated. */
2292 if (!((alias != nullptr ? alias->deprecated_warn_user : 0)
2293 || cmd->deprecated_warn_user))
2296 /* Join command prefix (if any) and the command name. */
2297 std::string tmp_cmd_str;
2298 if (cmd->prefix != nullptr)
2299 tmp_cmd_str += cmd->prefix->prefixname ();
2300 tmp_cmd_str += std::string (cmd->name);
2302 /* Display the appropriate first line, this warns that the thing the user
2303 entered is deprecated. */
2304 if (alias != nullptr)
2306 /* Join the alias prefix (if any) and the alias name. */
2307 std::string tmp_alias_str;
2308 if (alias->prefix != nullptr)
2309 tmp_alias_str += alias->prefix->prefixname ();
2310 tmp_alias_str += std::string (alias->name);
2312 if (cmd->cmd_deprecated)
2313 gdb_printf (_("Warning: command '%ps' (%ps) is deprecated.\n"),
2314 styled_string (title_style.style (),
2315 tmp_cmd_str.c_str ()),
2316 styled_string (title_style.style (),
2317 tmp_alias_str.c_str ()));
2319 gdb_printf (_("Warning: '%ps', an alias for the command '%ps', "
2320 "is deprecated.\n"),
2321 styled_string (title_style.style (),
2322 tmp_alias_str.c_str ()),
2323 styled_string (title_style.style (),
2324 tmp_cmd_str.c_str ()));
2327 gdb_printf (_("Warning: command '%ps' is deprecated.\n"),
2328 styled_string (title_style.style (),
2329 tmp_cmd_str.c_str ()));
2331 /* Now display a second line indicating what the user should use instead.
2332 If it is only the alias that is deprecated, we want to indicate the
2333 new alias, otherwise we'll indicate the new command. */
2334 const char *replacement;
2335 if (alias != nullptr && !cmd->cmd_deprecated)
2336 replacement = alias->replacement;
2338 replacement = cmd->replacement;
2339 if (replacement != nullptr)
2340 gdb_printf (_("Use '%ps'.\n\n"),
2341 styled_string (title_style.style (),
2344 gdb_printf (_("No alternative known.\n\n"));
2346 /* We've warned you, now we'll keep quiet. */
2347 if (alias != nullptr)
2348 alias->deprecated_warn_user = 0;
2349 cmd->deprecated_warn_user = 0;
2352 /* Look up the contents of TEXT as a command in the command list CUR_LIST.
2353 Return 1 on success, 0 on failure.
2355 If TEXT refers to an alias, *ALIAS will point to that alias.
2357 If TEXT is a subcommand (i.e. one that is preceded by a prefix
2358 command) set *PREFIX_CMD.
2360 Set *CMD to point to the command TEXT indicates.
2362 If any of *ALIAS, *PREFIX_CMD, or *CMD cannot be determined or do not
2363 exist, they are NULL when we return.
2368 lookup_cmd_composition_1 (const char *text,
2369 struct cmd_list_element **alias,
2370 struct cmd_list_element **prefix_cmd,
2371 struct cmd_list_element **cmd,
2372 struct cmd_list_element *cur_list)
2375 *prefix_cmd = cur_list->prefix;
2378 text = skip_spaces (text);
2380 /* Go through as many command lists as we need to, to find the command
2384 /* Identify the name of the command. */
2385 int len = find_command_name_length (text);
2387 /* If nothing but whitespace, return. */
2391 /* TEXT is the start of the first command word to lookup (and
2392 it's length is LEN). We copy this into a local temporary. */
2393 std::string command (text, len);
2397 *cmd = find_cmd (command.c_str (), len, cur_list, 1, &nfound);
2399 /* We only handle the case where a single command was found. */
2400 if (*cmd == CMD_LIST_AMBIGUOUS || *cmd == nullptr)
2404 if ((*cmd)->is_alias ())
2406 /* If the command was actually an alias, we note that an
2407 alias was used (by assigning *ALIAS) and we set *CMD. */
2409 *cmd = (*cmd)->alias_target;
2414 text = skip_spaces (text);
2416 if ((*cmd)->is_prefix () && *text != '\0')
2418 cur_list = *(*cmd)->subcommands;
2426 /* Look up the contents of TEXT as a command in the command list 'cmdlist'.
2427 Return 1 on success, 0 on failure.
2429 If TEXT refers to an alias, *ALIAS will point to that alias.
2431 If TEXT is a subcommand (i.e. one that is preceded by a prefix
2432 command) set *PREFIX_CMD.
2434 Set *CMD to point to the command TEXT indicates.
2436 If any of *ALIAS, *PREFIX_CMD, or *CMD cannot be determined or do not
2437 exist, they are NULL when we return.
2442 lookup_cmd_composition (const char *text,
2443 struct cmd_list_element **alias,
2444 struct cmd_list_element **prefix_cmd,
2445 struct cmd_list_element **cmd)
2447 return lookup_cmd_composition_1 (text, alias, prefix_cmd, cmd, cmdlist);
2450 /* Helper function for SYMBOL_COMPLETION_FUNCTION. */
2452 /* Return a vector of char pointers which point to the different
2453 possible completions in LIST of TEXT.
2455 WORD points in the same buffer as TEXT, and completions should be
2456 returned relative to this position. For example, suppose TEXT is
2457 "foo" and we want to complete to "foobar". If WORD is "oo", return
2458 "oobar"; if WORD is "baz/foo", return "baz/foobar". */
2461 complete_on_cmdlist (struct cmd_list_element *list,
2462 completion_tracker &tracker,
2463 const char *text, const char *word,
2464 int ignore_help_classes)
2466 struct cmd_list_element *ptr;
2467 int textlen = strlen (text);
2469 int saw_deprecated_match = 0;
2471 /* We do one or two passes. In the first pass, we skip deprecated
2472 commands. If we see no matching commands in the first pass, and
2473 if we did happen to see a matching deprecated command, we do
2474 another loop to collect those. */
2475 for (pass = 0; pass < 2; ++pass)
2477 bool got_matches = false;
2479 for (ptr = list; ptr; ptr = ptr->next)
2480 if (!strncmp (ptr->name, text, textlen)
2481 && !ptr->abbrev_flag
2482 && (!ignore_help_classes || !ptr->is_command_class_help ()
2483 || ptr->is_prefix ()))
2487 if (ptr->cmd_deprecated)
2489 saw_deprecated_match = 1;
2494 tracker.add_completion
2495 (make_completion_match_str (ptr->name, text, word));
2502 /* If we saw no matching deprecated commands in the first pass,
2504 if (!saw_deprecated_match)
2509 /* Helper function for SYMBOL_COMPLETION_FUNCTION. */
2511 /* Add the different possible completions in ENUMLIST of TEXT.
2513 WORD points in the same buffer as TEXT, and completions should be
2514 returned relative to this position. For example, suppose TEXT is "foo"
2515 and we want to complete to "foobar". If WORD is "oo", return
2516 "oobar"; if WORD is "baz/foo", return "baz/foobar". */
2519 complete_on_enum (completion_tracker &tracker,
2520 const char *const *enumlist,
2521 const char *text, const char *word)
2523 int textlen = strlen (text);
2527 for (i = 0; (name = enumlist[i]) != NULL; i++)
2528 if (strncmp (name, text, textlen) == 0)
2529 tracker.add_completion (make_completion_match_str (name, text, word));
2532 /* Call the command function. */
2534 cmd_func (struct cmd_list_element *cmd, const char *args, int from_tty)
2536 if (!cmd->is_command_class_help ())
2538 gdb::optional<scoped_restore_tmpl<bool>> restore_suppress;
2540 if (cmd->suppress_notification != NULL)
2541 restore_suppress.emplace (cmd->suppress_notification, true);
2543 cmd->func (args, from_tty, cmd);
2546 error (_("Invalid command"));
2550 cli_user_command_p (struct cmd_list_element *cmd)
2552 return cmd->theclass == class_user && cmd->func == do_simple_func;