1 This file is help.def, from which is created help.c.
2 It implements the builtin "help" in Bash.
4 Copyright (C) 1987-2009 Free Software Foundation, Inc.
6 This file is part of GNU Bash, the Bourne Again SHell.
8 Bash is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
11 (at your option) any later version.
13 Bash is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with Bash. If not, see <http://www.gnu.org/licenses/>.
24 $FUNCTION help_builtin
25 $DEPENDS_ON HELP_BUILTIN
26 $SHORT_DOC help [-ds] [pattern ...]
27 Display information about builtin commands.
29 Displays brief summaries of builtin commands. If PATTERN is
30 specified, gives detailed help on all commands matching PATTERN,
31 otherwise the list of help topics is printed.
34 -d output short description for each topic
35 -m display usage in pseudo-manpage format
36 -s output only a short usage synopsis for each topic matching
40 PATTERN Pattern specifiying a help topic
43 Returns success unless PATTERN is not found or an invalid option is given.
48 #if defined (HELP_BUILTIN)
51 #if defined (HAVE_UNISTD_H)
53 # include <sys/types.h>
62 #include "../bashintl.h"
65 #include "../builtins.h"
66 #include "../pathexp.h"
68 #include "bashgetopt.h"
70 #include <glob/strmatch.h>
71 #include <glob/glob.h>
77 extern const char * const bash_copyright;
78 extern const char * const bash_license;
80 static void show_builtin_command_help __P((void));
81 static int open_helpfile __P((char *));
82 static void show_desc __P((char *, int));
83 static void show_manpage __P((char *, int));
84 static void show_longdoc __P((int));
86 /* Print out a list of the known functions in the shell, and what they do.
87 If LIST is supplied, print out the list which matches for each pattern
95 int plen, match_found, sflag, dflag, mflag;
97 dflag = sflag = mflag = 0;
98 reset_internal_getopt ();
99 while ((i = internal_getopt (list, "dms")) != -1)
121 show_shell_version (0);
122 show_builtin_command_help ();
123 return (EXECUTION_SUCCESS);
126 /* We should consider making `help bash' do something. */
128 if (glob_pattern_p (list->word->word))
130 printf (ngettext ("Shell commands matching keyword `", "Shell commands matching keywords `", (list->next ? 2 : 1)));
131 print_word_list (list, ", ");
135 for (match_found = 0, pattern = ""; list; list = list->next)
137 pattern = list->word->word;
138 plen = strlen (pattern);
140 for (i = 0; name = shell_builtins[i].name; i++)
143 if ((strncmp (pattern, name, plen) == 0) ||
144 (strmatch (pattern, name, FNMATCH_EXTFLAG) != FNM_NOMATCH))
154 show_manpage (name, i);
158 printf ("%s: %s\n", name, shell_builtins[i].short_doc);
166 if (match_found == 0)
168 builtin_error (_("no help topics match `%s'. Try `help help' or `man -k %s' or `info %s'."), pattern, pattern, pattern);
169 return (EXECUTION_FAILURE);
173 return (EXECUTION_SUCCESS);
182 fd = open (name, O_RDONLY);
185 builtin_error (_("%s: cannot open: %s"), name, strerror (errno));
191 /* By convention, enforced by mkbuiltins.c, if separate help files are being
192 used, the long_doc array contains one string -- the full pathname of the
193 help file for this builtin. */
202 doc = shell_builtins[i].long_doc;
204 if (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL)
206 fd = open_helpfile (doc[0]);
209 zcatfd (fd, 1, doc[0]);
213 for (j = 0; doc[j]; j++)
214 printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
226 doc = (char **)shell_builtins[i].long_doc;
228 usefile = (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL);
231 fd = open_helpfile (doc[0]);
234 zmapfd (fd, &line, doc[0]);
238 line = doc ? doc[0] : (char *)NULL;
240 printf ("%s - ", name);
241 for (j = 0; line && line[j]; j++)
254 /* Print builtin help in pseudo-manpage format. */
256 show_manpage (name, i)
264 doc = (char **)shell_builtins[i].long_doc;
266 usefile = (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL);
269 fd = open_helpfile (doc[0]);
272 zmapfd (fd, &line, doc[0]);
276 line = doc ? _(doc[0]) : (char *)NULL;
280 printf ("%*s%s - ", BASE_INDENT, " ", name);
281 for (j = 0; line && line[j]; j++)
290 printf ("SYNOPSIS\n");
291 printf ("%*s%s\n\n", BASE_INDENT, " ", shell_builtins[i].short_doc);
294 printf ("DESCRIPTION\n");
297 for (j = 0; doc[j]; j++)
298 printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
302 for (j = 0; line && line[j]; j++)
306 printf ("%*s", BASE_INDENT, " ");
312 printf ("SEE ALSO\n");
313 printf ("%*sbash(1)\n\n", BASE_INDENT, " ");
316 printf ("IMPLEMENTATION\n");
317 printf ("%*s", BASE_INDENT, " ");
318 show_shell_version (0);
319 printf ("%*s", BASE_INDENT, " ");
320 printf ("%s\n", _(bash_copyright));
321 printf ("%*s", BASE_INDENT, " ");
322 printf ("%s\n", _(bash_license));
330 show_builtin_command_help ()
337 _("These shell commands are defined internally. Type `help' to see this list.\n\
338 Type `help name' to find out more about the function `name'.\n\
339 Use `info bash' to find out more about the shell in general.\n\
340 Use `man -k' or `info' to find out more about commands not in this list.\n\
342 A star (*) next to a name means that the command is disabled.\n\
345 t = get_string_value ("COLUMNS");
346 width = (t && *t) ? atoi (t) : 80;
351 if (width > sizeof (blurb))
352 width = sizeof (blurb);
353 height = (num_shell_builtins + 1) / 2; /* number of rows */
355 for (i = 0; i < height; i++)
360 blurb[0] = (shell_builtins[i].flags & BUILTIN_ENABLED) ? ' ' : '*';
361 strncpy (blurb + 1, shell_builtins[i].short_doc, width - 2);
362 blurb[width - 2] = '>'; /* indicate truncation */
363 blurb[width - 1] = '\0';
364 printf ("%s", blurb);
365 if (((i << 1) >= num_shell_builtins) || (i+height >= num_shell_builtins))
372 for (j = strlen (blurb); j < width; j++)
376 blurb[0] = (shell_builtins[i+height].flags & BUILTIN_ENABLED) ? ' ' : '*';
377 strncpy (blurb + 1, shell_builtins[i+height].short_doc, width - 3);
378 blurb[width - 3] = '>'; /* indicate truncation */
379 blurb[width - 2] = '\0';
380 printf ("%s\n", blurb);
383 #endif /* HELP_BUILTIN */