builtins/help.def

   1 This file is help.def, from which is created help.c.
   2 It implements the builtin "help" in Bash.
   3
   4 Copyright (C) 1987-2008 Free Software Foundation, Inc.
   5
   6 This file is part of GNU Bash, the Bourne Again SHell.
   7
   8 Bash is free software; you can redistribute it and/or modify it under
   9 the terms of the GNU General Public License as published by the Free
  10 Software Foundation; either version 2, or (at your option) any later
  11 version.
  12
  13 Bash is distributed in the hope that it will be useful, but WITHOUT ANY
  14 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  15 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16 for more details.
  17
  18 You should have received a copy of the GNU General Public License along
  19 with Bash; see the file COPYING.  If not, write to the Free Software
  20 Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA.
  21
  22 $PRODUCES help.c
  23
  24 $BUILTIN help
  25 $FUNCTION help_builtin
  26 $DEPENDS_ON HELP_BUILTIN
  27 $SHORT_DOC help [-s] [pattern ...]
  28 Displays brief information about builtin commands.  If PATTERN is
  29 specified, gives detailed help on all commands matching PATTERN,
  30 otherwise the list of help topics is printed.
  31
  32 Options:
  33   -s    output only a short usage synopsis for each topic matching
  34         PATTERN
  35 $END
  36
  37 #include <config.h>
  38
  39 #if defined (HELP_BUILTIN)
  40 #include <stdio.h>
  41
  42 #if defined (HAVE_UNISTD_H)
  43 #  ifdef _MINIX
  44 #    include <sys/types.h>
  45 #  endif
  46 #  include <unistd.h>
  47 #endif
  48
  49 #include <errno.h>
  50
  51 #include <filecntl.h>
  52
  53 #include "../bashintl.h"
  54
  55 #include "../shell.h"
  56 #include "../builtins.h"
  57 #include "../pathexp.h"
  58 #include "common.h"
  59 #include "bashgetopt.h"
  60
  61 #include <glob/strmatch.h>
  62 #include <glob/glob.h>
  63
  64 #ifndef errno
  65 extern int errno;
  66 #endif
  67
  68 static void show_builtin_command_help __P((void));
  69 static void show_longdoc __P((int));
  70
  71 /* Print out a list of the known functions in the shell, and what they do.
  72    If LIST is supplied, print out the list which matches for each pattern
  73    specified. */
  74 int
  75 help_builtin (list)
  76      WORD_LIST *list;
  77 {
  78   register int i;
  79   char *pattern, *name;
  80   int plen, match_found, sflag;
  81
  82   sflag = 0;
  83   reset_internal_getopt ();
  84   while ((i = internal_getopt (list, "s")) != -1)
  85     {
  86       switch (i)
  87         {
  88         case 's':
  89           sflag = 1;
  90           break;
  91         default:
  92           builtin_usage ();
  93           return (EX_USAGE);
  94         }
  95     }
  96   list = loptend;
  97
  98   if (list == 0)
  99     {
 100       show_shell_version (0);
 101       show_builtin_command_help ();
 102       return (EXECUTION_SUCCESS);
 103     }
 104
 105   /* We should consider making `help bash' do something. */
 106
 107   if (glob_pattern_p (list->word->word))
 108     {
 109       if (list->next)
 110         printf (_("Shell commands matching keywords `"));
 111       else
 112         printf (_("Shell commands matching keyword `"));
 113       print_word_list (list, ", ");
 114       printf ("'\n\n");
 115     }
 116
 117   for (match_found = 0, pattern = ""; list; list = list->next)
 118     {
 119       pattern = list->word->word;
 120       plen = strlen (pattern);
 121
 122       for (i = 0; name = shell_builtins[i].name; i++)
 123         {
 124           QUIT;
 125           if ((strncmp (pattern, name, plen) == 0) ||
 126               (strmatch (pattern, name, FNMATCH_EXTFLAG) != FNM_NOMATCH))
 127             {
 128               printf ("%s: %s\n", name, shell_builtins[i].short_doc);
 129
 130               if (sflag == 0)
 131                 show_longdoc (i);
 132
 133               match_found++;
 134             }
 135         }
 136     }
 137
 138   if (match_found == 0)
 139     {
 140       builtin_error (_("no help topics match `%s'.  Try `help help' or `man -k %s' or `info %s'."), pattern, pattern, pattern);
 141       return (EXECUTION_FAILURE);
 142     }
 143
 144   fflush (stdout);
 145   return (EXECUTION_SUCCESS);
 146 }
 147
 148 /* By convention, enforced by mkbuiltins.c, if separate help files are being
 149    used, the long_doc array contains one string -- the full pathname of the
 150    help file for this builtin.  */
 151 static void
 152 show_longdoc (i)
 153      int i;
 154 {
 155   register int j;
 156   char * const *doc;
 157   int fd;
 158
 159   doc = shell_builtins[i].long_doc;
 160
 161   if (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL)
 162     {
 163       fd = open (doc[0], O_RDONLY);
 164       if (fd == -1)
 165         {
 166           builtin_error (_("%s: cannot open: %s"), doc[0], strerror (errno));
 167           return;
 168         }
 169       zcatfd (fd, 1, doc[0]);
 170       close (fd);
 171     }
 172   else
 173     for (j = 0; doc[j]; j++)
 174       printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
 175 }
 176
 177 static void
 178 show_builtin_command_help ()
 179 {
 180   int i, j;
 181   int height, width;
 182   char *t, blurb[128];
 183
 184   printf (
 185 _("These shell commands are defined internally.  Type `help' to see this list.\n\
 186 Type `help name' to find out more about the function `name'.\n\
 187 Use `info bash' to find out more about the shell in general.\n\
 188 Use `man -k' or `info' to find out more about commands not in this list.\n\
 189 \n\
 190 A star (*) next to a name means that the command is disabled.\n\
 191 \n"));
 192
 193   t = get_string_value ("COLUMNS");
 194   width = (t && *t) ? atoi (t) : 80;
 195   if (width <= 0)
 196     width = 80;
 197
 198   width /= 2;
 199   if (width > sizeof (blurb))
 200     width = sizeof (blurb);
 201   height = (num_shell_builtins + 1) / 2;        /* number of rows */
 202
 203   for (i = 0; i < height; i++)
 204     {
 205       QUIT;
 206
 207       /* first column */
 208       blurb[0] = (shell_builtins[i].flags & BUILTIN_ENABLED) ? ' ' : '*';
 209       strncpy (blurb + 1, shell_builtins[i].short_doc, width - 2);
 210       blurb[width - 2] = '>';           /* indicate truncation */
 211       blurb[width - 1] = '\0';
 212       printf ("%s", blurb);
 213       if (((i << 1) >= num_shell_builtins) || (i+height >= num_shell_builtins))
 214         {
 215           printf ("\n");
 216           break;
 217         }
 218
 219       /* two spaces */
 220       for (j = strlen (blurb); j < width; j++)
 221         putc (' ', stdout);
 222
 223       /* second column */
 224       blurb[0] = (shell_builtins[i+height].flags & BUILTIN_ENABLED) ? ' ' : '*';
 225       strncpy (blurb + 1, shell_builtins[i+height].short_doc, width - 3);
 226       blurb[width - 3] = '>';           /* indicate truncation */
 227       blurb[width - 2] = '\0';
 228       printf ("%s\n", blurb);
 229     }
 230 }
 231 #endif /* HELP_BUILTIN */