1
This file is help.def, from which is created help.c.
2
It implements the builtin "help" in Bash.
4
Copyright (C) 1987-2013 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 [-dms] [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, m, pass, this_found;
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 (pass = 1, this_found = 0; pass < 3; pass++)
142
for (i = 0; name = shell_builtins[i].name; i++)
146
/* First pass: look for exact string or pattern matches.
147
Second pass: look for prefix matches like bash-4.2 */
149
m = (strcmp (pattern, name) == 0) ||
150
(strmatch (pattern, name, FNMATCH_EXTFLAG) != FNM_NOMATCH);
152
m = strncmp (pattern, name, plen) == 0;
165
show_manpage (name, i);
169
printf ("%s: %s\n", name, _(shell_builtins[i].short_doc));
175
if (pass == 1 && this_found == 1)
180
if (match_found == 0)
182
builtin_error (_("no help topics match `%s'. Try `help help' or `man -k %s' or `info %s'."), pattern, pattern, pattern);
183
return (EXECUTION_FAILURE);
187
return (EXECUTION_SUCCESS);
196
fd = open (name, O_RDONLY);
199
builtin_error (_("%s: cannot open: %s"), name, strerror (errno));
205
/* By convention, enforced by mkbuiltins.c, if separate help files are being
206
used, the long_doc array contains one string -- the full pathname of the
207
help file for this builtin. */
216
doc = shell_builtins[i].long_doc;
218
if (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL)
220
fd = open_helpfile (doc[0]);
223
zcatfd (fd, 1, doc[0]);
227
for (j = 0; doc[j]; j++)
228
printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
240
doc = (char **)shell_builtins[i].long_doc;
242
usefile = (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL);
245
fd = open_helpfile (doc[0]);
248
zmapfd (fd, &line, doc[0]);
252
line = doc ? doc[0] : (char *)NULL;
254
printf ("%s - ", name);
255
for (j = 0; line && line[j]; j++)
268
/* Print builtin help in pseudo-manpage format. */
270
show_manpage (name, i)
278
doc = (char **)shell_builtins[i].long_doc;
280
usefile = (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL);
283
fd = open_helpfile (doc[0]);
286
zmapfd (fd, &line, doc[0]);
290
line = doc ? _(doc[0]) : (char *)NULL;
294
printf ("%*s%s - ", BASE_INDENT, " ", name);
295
for (j = 0; line && line[j]; j++)
304
printf ("SYNOPSIS\n");
305
printf ("%*s%s\n\n", BASE_INDENT, " ", _(shell_builtins[i].short_doc));
308
printf ("DESCRIPTION\n");
311
for (j = 0; doc[j]; j++)
312
printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
316
for (j = 0; line && line[j]; j++)
320
printf ("%*s", BASE_INDENT, " ");
326
printf ("SEE ALSO\n");
327
printf ("%*sbash(1)\n\n", BASE_INDENT, " ");
330
printf ("IMPLEMENTATION\n");
331
printf ("%*s", BASE_INDENT, " ");
332
show_shell_version (0);
333
printf ("%*s", BASE_INDENT, " ");
334
printf ("%s\n", _(bash_copyright));
335
printf ("%*s", BASE_INDENT, " ");
336
printf ("%s\n", _(bash_license));
344
dispcolumn (i, buf, bufsize, width, height)
355
helpdoc = _(shell_builtins[i].short_doc);
357
buf[0] = (shell_builtins[i].flags & BUILTIN_ENABLED) ? ' ' : '*';
358
strncpy (buf + 1, helpdoc, width - 2);
359
buf[width - 2] = '>'; /* indicate truncation */
360
buf[width - 1] = '\0';
362
if (((i << 1) >= num_shell_builtins) || (i+height >= num_shell_builtins))
368
displen = strlen (buf);
370
for (j = displen; j < width; j++)
374
helpdoc = _(shell_builtins[i+height].short_doc);
376
buf[0] = (shell_builtins[i+height].flags & BUILTIN_ENABLED) ? ' ' : '*';
377
strncpy (buf + 1, helpdoc, width - 3);
378
buf[width - 3] = '>'; /* indicate truncation */
379
buf[width - 2] = '\0';
381
printf ("%s\n", buf);
384
#if defined (HANDLE_MULTIBYTE)
386
wdispcolumn (i, buf, bufsize, width, height)
400
helpdoc = _(shell_builtins[i].short_doc);
403
slen = mbstowcs ((wchar_t *)0, helpdoc, 0);
406
dispcolumn (i, buf, bufsize, width, height);
410
/* No bigger than the passed max width */
413
wcstr = (wchar_t *)xmalloc (sizeof (wchar_t) * (width + 2));
414
n = mbstowcs (wcstr+1, helpdoc, slen + 1);
417
/* Turn tabs and newlines into spaces for column display, since wcwidth
418
returns -1 for them */
419
for (j = 1; j < n; j++)
420
if (wcstr[j] == L'\n' || wcstr[j] == L'\t')
423
displen = wcsnwidth (wcstr+1, slen, width - 2) + 1; /* +1 for ' ' or '*' */
425
wcstr[0] = (shell_builtins[i].flags & BUILTIN_ENABLED) ? L' ' : L'*';
427
/* This assumes each wide char takes up one column position when displayed */
428
wcstr[width - 2] = L'>'; /* indicate truncation */
429
wcstr[width - 1] = L'\0';
431
printf ("%ls", wcstr);
432
if (((i << 1) >= num_shell_builtins) || (i+height >= num_shell_builtins))
438
/* at least one space */
439
for (j = displen; j < width; j++)
443
helpdoc = _(shell_builtins[i+height].short_doc);
444
slen = mbstowcs ((wchar_t *)0, helpdoc, 0);
448
printf ("%c%s\n", (shell_builtins[i+height].flags & BUILTIN_ENABLED) ? ' ' : '*', helpdoc);
452
/* Reuse wcstr since it is already width wide chars long */
455
n = mbstowcs (wcstr+1, helpdoc, slen + 1);
456
wcstr[n+1] = L'\0'; /* make sure null-terminated */
458
/* Turn tabs and newlines into spaces for column display */
459
for (j = 1; j < n; j++)
460
if (wcstr[j] == L'\n' || wcstr[j] == L'\t')
463
displen = wcsnwidth (wcstr+1, slen, width - 2);
465
wcstr[0] = (shell_builtins[i+height].flags & BUILTIN_ENABLED) ? L' ' : L'*';
467
/* This assumes each wide char takes up one column position when displayed */
468
wcstr[width - 3] = L'>'; /* indicate truncation */
469
wcstr[width - 2] = L'\0';
471
printf ("%ls\n", wcstr);
475
#endif /* HANDLE_MULTIBYTE */
478
show_builtin_command_help ()
485
_("These shell commands are defined internally. Type `help' to see this list.\n\
486
Type `help name' to find out more about the function `name'.\n\
487
Use `info bash' to find out more about the shell in general.\n\
488
Use `man -k' or `info' to find out more about commands not in this list.\n\
490
A star (*) next to a name means that the command is disabled.\n\
493
t = get_string_value ("COLUMNS");
494
width = (t && *t) ? atoi (t) : 80;
499
if (width > sizeof (blurb))
500
width = sizeof (blurb);
503
height = (num_shell_builtins + 1) / 2; /* number of rows */
505
for (i = 0; i < height; i++)
509
#if defined (HANDLE_MULTIBYTE)
511
wdispcolumn (i, blurb, sizeof (blurb), width, height);
514
dispcolumn (i, blurb, sizeof (blurb), width, height);
517
#endif /* HELP_BUILTIN */
added
removed
builtins/help.def
