commit bash-20080410 snapshot

builtins/Makefile.in

@@ -140,7 +140,7 @@ DEFSRC =  $(srcdir)/alias.def $(srcdir)/bind.def $(srcdir)/break.def \
 	  $(srcdir)/times.def $(srcdir)/trap.def $(srcdir)/type.def \
 	  $(srcdir)/ulimit.def $(srcdir)/umask.def $(srcdir)/wait.def \
 	  $(srcdir)/reserved.def $(srcdir)/pushd.def $(srcdir)/shopt.def \
-	  $(srcdir)/printf.def $(srcdir)/complete.def
+	  $(srcdir)/printf.def $(srcdir)/complete.def $(srcdir)/mapfile.def
 
 STATIC_SOURCE = common.c evalstring.c evalfile.c getopt.c bashgetopt.c \
 		getopt.h 
@@ -148,8 +148,8 @@ STATIC_SOURCE = common.c evalstring.c evalfile.c getopt.c bashgetopt.c \
 OFILES = builtins.o \
 	alias.o bind.o break.o builtin.o caller.o cd.o colon.o command.o \
 	common.o declare.o echo.o enable.o eval.o evalfile.o \
-	evalstring.o exec.o \
-	exit.o fc.o fg_bg.o hash.o help.o history.o jobs.o kill.o let.o \
+	evalstring.o exec.o exit.o fc.o fg_bg.o hash.o help.o history.o \
+	jobs.o kill.o let.o mapfile.o \
 	pushd.o read.o return.o set.o setattr.o shift.o source.o \
 	suspend.o test.o times.o trap.o type.o ulimit.o umask.o \
 	wait.o getopts.o shopt.o printf.o getopt.o bashgetopt.o complete.o
@@ -271,6 +271,7 @@ history.o: history.def
 jobs.o: jobs.def
 kill.o: kill.def
 let.o: let.def
+mapfile.o: mapfile.def
 printf.o: printf.def
 pushd.o: pushd.def
 read.o: read.def
@@ -595,6 +596,12 @@ complete.o: ${topdir}/bashtypes.h ${topdir}/bashansi.h ${BASHINCDIR}/ansi_stdlib
 complete.o: ${topdir}/builtins.h
 complete.o: ${topdir}/pcomplete.h
 complete.o: ${srcdir}/common.h ${srcdir}/bashgetopt.h
+mapfile.o: $(topdir)/command.h ../config.h $(BASHINCDIR)/memalloc.h
+mapfile.o: $(topdir)/error.h $(topdir)/general.h $(topdir)/xmalloc.h
+mapfile.o: $(topdir)/quit.h $(topdir)/dispose_cmd.h $(topdir)/make_cmd.h
+mapfile.o: $(topdir)/subst.h $(topdir)/externs.h $(BASHINCDIR)/maxpath.h
+mapfile.o: $(topdir)/shell.h $(topdir)/syntax.h $(topdir)/variables.h $(topdir)/conftypes.h
+mapfile.o: $(topdir)/arrayfunc.h
 
 #bind.o: $(RL_LIBSRC)chardefs.h $(RL_LIBSRC)readline.h $(RL_LIBSRC)keymaps.h
 
@@ -620,6 +627,7 @@ inlib.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 jobs.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 kill.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 let.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
+mapfile.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 mkbuiltins.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 printf.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 pushd.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h

builtins/Makefile.in~

@@ -44,7 +44,7 @@ datarootdir = @datarootdir@
 
 includedir = @includedir@
 datadir = @datadir@
-localedir = $(datadir)/locale
+localedir = @localedir@
 
 # Support an alternate destination root directory for package building
 DESTDIR =
@@ -66,7 +66,7 @@ LOCAL_DEFS = @LOCAL_DEFS@
 
 LIBS = @LIBS@
 LDFLAGS = @LDFLAGS@ $(LOCAL_LDFLAGS) $(CFLAGS)
-LDFLAGS_FOR_BUILD = $(LDFLAGS)
+LDFLAGS_FOR_BUILD = @LDFLAGS_FOR_BUILD@ $(LOCAL_LDFLAGS) $(CFLAGS_FOR_BUILD)
 LOCAL_LDFLAGS = @LOCAL_LDFLAGS@
 #LIBS_FOR_BUILD = @LIBS_FOR_BUILD@
 LIBS_FOR_BUILD = $(LIBS)
@@ -140,7 +140,7 @@ DEFSRC =  $(srcdir)/alias.def $(srcdir)/bind.def $(srcdir)/break.def \
 	  $(srcdir)/times.def $(srcdir)/trap.def $(srcdir)/type.def \
 	  $(srcdir)/ulimit.def $(srcdir)/umask.def $(srcdir)/wait.def \
 	  $(srcdir)/reserved.def $(srcdir)/pushd.def $(srcdir)/shopt.def \
-	  $(srcdir)/printf.def $(srcdir)/complete.def
+	  $(srcdir)/printf.def $(srcdir)/complete.def $(srcdir)/mapfile.def
 
 STATIC_SOURCE = common.c evalstring.c evalfile.c getopt.c bashgetopt.c \
 		getopt.h 
@@ -148,8 +148,8 @@ STATIC_SOURCE = common.c evalstring.c evalfile.c getopt.c bashgetopt.c \
 OFILES = builtins.o \
 	alias.o bind.o break.o builtin.o caller.o cd.o colon.o command.o \
 	common.o declare.o echo.o enable.o eval.o evalfile.o \
-	evalstring.o exec.o \
-	exit.o fc.o fg_bg.o hash.o help.o history.o jobs.o kill.o let.o \
+	evalstring.o exec.o exit.o fc.o fg_bg.o hash.o help.o history.o
+	jobs.o kill.o let.o mapfile.o \
 	pushd.o read.o return.o set.o setattr.o shift.o source.o \
 	suspend.o test.o times.o trap.o type.o ulimit.o umask.o \
 	wait.o getopts.o shopt.o printf.o getopt.o bashgetopt.o complete.o
@@ -271,6 +271,7 @@ history.o: history.def
 jobs.o: jobs.def
 kill.o: kill.def
 let.o: let.def
+mapfile.o: mapfile.def
 printf.o: printf.def
 pushd.o: pushd.def
 read.o: read.def
@@ -595,6 +596,12 @@ complete.o: ${topdir}/bashtypes.h ${topdir}/bashansi.h ${BASHINCDIR}/ansi_stdlib
 complete.o: ${topdir}/builtins.h
 complete.o: ${topdir}/pcomplete.h
 complete.o: ${srcdir}/common.h ${srcdir}/bashgetopt.h
+mapfile.o: $(topdir)/command.h ../config.h $(BASHINCDIR)/memalloc.h
+mapfile.o: $(topdir)/error.h $(topdir)/general.h $(topdir)/xmalloc.h
+mapfile.o: $(topdir)/quit.h $(topdir)/dispose_cmd.h $(topdir)/make_cmd.h
+mapfile.o: $(topdir)/subst.h $(topdir)/externs.h $(BASHINCDIR)/maxpath.h
+mapfile.o: $(topdir)/shell.h $(topdir)/syntax.h $(topdir)/variables.h $(topdir)/conftypes.h
+mapfile.o: $(topdir)/arrayfunc.h
 
 #bind.o: $(RL_LIBSRC)chardefs.h $(RL_LIBSRC)readline.h $(RL_LIBSRC)keymaps.h
 
@@ -620,6 +627,7 @@ inlib.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 jobs.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 kill.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 let.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
+mapfile.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 mkbuiltins.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 printf.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h
 pushd.o: ${topdir}/bashintl.h ${LIBINTL_H} $(BASHINCDIR)/gettext.h

builtins/alias.def

@@ -24,6 +24,8 @@ $FUNCTION alias_builtin
 $DEPENDS_ON ALIAS
 $PRODUCES alias.c
 $SHORT_DOC alias [-p] [name[=value] ... ]
+Define or display aliases.
+
 Without arguments, `alias' prints the list of aliases in the reusable
 form `alias NAME=VALUE' on standard output.
 
@@ -34,7 +36,8 @@ alias substitution when the alias is expanded.
 Options:
   -p	Print all defined aliases in a reusable format
 
-Alias returns true unless a NAME is supplied for which no alias has been
+Exit Status:
+alias returns true unless a NAME is supplied for which no alias has been
 defined.
 $END
 

builtins/alias.def~

@@ -24,6 +24,8 @@ $FUNCTION alias_builtin
 $DEPENDS_ON ALIAS
 $PRODUCES alias.c
 $SHORT_DOC alias [-p] [name[=value] ... ]
+Define or display aliases.
+
 Without arguments, `alias' prints the list of aliases in the reusable
 form `alias NAME=VALUE' on standard output.
 
@@ -158,7 +160,6 @@ $SHORT_DOC unalias [-a] name [name ...]
 Remove each NAME from the list of defined aliases.
 
 Options:
-
   -a	remove all alias definitions.
 
 Return success unless a NAME is not an existing alias.

builtins/bind.def

@@ -27,10 +27,12 @@ $BUILTIN bind
 $DEPENDS_ON READLINE
 $FUNCTION bind_builtin
 $SHORT_DOC bind [-lpvsPVS] [-m keymap] [-f filename] [-q name] [-u name] [-r keyseq] [-x keyseq:shell-command] [keyseq:readline-function or readline-command]
-Bind a key sequence to a Readline function or a macro, or set a Readline
-variable.  The non-option argument syntax is equivalent to that found in
-~/.inputrc, but must be passed as a single argument:  e.g.,
-bind '"\C-x\C-r": re-read-init-file'.
+Set Readline key bindings and variables.
+
+Bind a key sequence to a Readline function or a macro, or set a
+Readline variable.  The non-option argument syntax is equivalent to
+that found in ~/.inputrc, but must be passed as a single argument:
+e.g., bind '"\C-x\C-r": re-read-init-file'.
 
 Options:
   -m  keymap         Use KEYMAP as the keymap for the duration of this
@@ -53,6 +55,9 @@ Options:
   -f  filename       Read key bindings from FILENAME.
   -x  keyseq:shell-command	Cause SHELL-COMMAND to be executed when
 				KEYSEQ is entered.
+
+Exit Status:
+bind returns 0 unless an unrecognized option is given or an error occurs.
 $END
 
 #if defined (READLINE)

builtins/bind.def~

@@ -1,7 +1,7 @@
 This file is bind.def, from which is created bind.c.
 It implements the builtin "bind" in Bash.
 
-Copyright (C) 1987-2006 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -27,11 +27,14 @@ $BUILTIN bind
 $DEPENDS_ON READLINE
 $FUNCTION bind_builtin
 $SHORT_DOC bind [-lpvsPVS] [-m keymap] [-f filename] [-q name] [-u name] [-r keyseq] [-x keyseq:shell-command] [keyseq:readline-function or readline-command]
-Bind a key sequence to a Readline function or a macro, or set
-a Readline variable.  The non-option argument syntax is equivalent
-to that found in ~/.inputrc, but must be passed as a single argument:  e.g.,
-bind '"\C-x\C-r": re-read-init-file'.
-bind accepts the following options:
+Set Readline key bindings and variables.
+
+Bind a key sequence to a Readline function or a macro, or set a
+Readline variable.  The non-option argument syntax is equivalent to
+that found in ~/.inputrc, but must be passed as a single argument:
+e.g., bind '"\C-x\C-r": re-read-init-file'.
+
+Options:
   -m  keymap         Use KEYMAP as the keymap for the duration of this
                      command.  Acceptable keymap names are emacs,
                      emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,

builtins/break.def

@@ -24,8 +24,13 @@ $PRODUCES break.c
 $BUILTIN break
 $FUNCTION break_builtin
 $SHORT_DOC break [n]
+Exit for, while, or until loops.
+
 Exit a FOR, WHILE or UNTIL loop.  If N is specified, break N enclosing
 loops.
+
+Exit Status:
+The exit status is 0 unless the shell is not executing a loop. 
 $END
 #include <config.h>
 
@@ -86,8 +91,13 @@ break_builtin (list)
 $BUILTIN continue
 $FUNCTION continue_builtin
 $SHORT_DOC continue [n]
+Resume for, while, or until loops.
+
 Resumes the next iteration of the enclosing FOR, WHILE or UNTIL loop.
 If N is specified, resumes the Nth enclosing loop.
+
+Exit Status:
+The exit status is 0 unless the shell is not executing a loop. 
 $END
 
 /* Set up to continue x levels, where x defaults to 1, but can be specified

builtins/break.def~

@@ -24,7 +24,10 @@ $PRODUCES break.c
 $BUILTIN break
 $FUNCTION break_builtin
 $SHORT_DOC break [n]
-Exit a FOR, WHILE or UNTIL loop.  If N is specified, break N enclosing loops.
+Exit for, while, or until loops.
+
+Exit a FOR, WHILE or UNTIL loop.  If N is specified, break N enclosing
+loops.
 $END
 #include <config.h>
 
@@ -85,6 +88,8 @@ break_builtin (list)
 $BUILTIN continue
 $FUNCTION continue_builtin
 $SHORT_DOC continue [n]
+Resume for, while, or until loops.
+
 Resumes the next iteration of the enclosing FOR, WHILE or UNTIL loop.
 If N is specified, resumes the Nth enclosing loop.
 $END

builtins/builtin.def

@@ -24,9 +24,15 @@ $PRODUCES builtin.c
 $BUILTIN builtin
 $FUNCTION builtin_builtin
 $SHORT_DOC builtin [shell-builtin [arg ...]]
+Execute shell builtins.
+
 Execute SHELL-BUILTIN with arguments ARGs without performing command
 lookup.  This is useful when you wish to reimplement a shell builtin
 as a shell function, but need to execute the builtin within the function.
+
+Exit Status:
+Returns the exit status of SHELL-BUILTIN, or false if SHELL-BUILTIN is
+not a shell builtin..
 $END
 #include <config.h>
 

builtins/builtin.def~

@@ -24,9 +24,11 @@ $PRODUCES builtin.c
 $BUILTIN builtin
 $FUNCTION builtin_builtin
 $SHORT_DOC builtin [shell-builtin [arg ...]]
-Execute SHELL-BUILTIN with arguments ARGs without performing command lookup.
-This is useful when you wish to reimplement a shell builtin as a shell
-function, but need to execute the builtin within the function.
+Execute shell builtins.
+
+Execute SHELL-BUILTIN with arguments ARGs without performing command
+lookup.  This is useful when you wish to reimplement a shell builtin
+as a shell function, but need to execute the builtin within the function.
 $END
 #include <config.h>
 

builtins/caller.def

@@ -25,7 +25,7 @@ $BUILTIN caller
 $FUNCTION caller_builtin
 $DEPENDS_ON DEBUGGER
 $SHORT_DOC caller [expr]
-Returns the context of the current subroutine call.
+Return the context of the current subroutine call.
 
 Without EXPR, returns "$line $filename".  With EXPR, returns
 "$line $subroutine $filename"; this extra information can be used to
@@ -33,6 +33,10 @@ provide a stack trace.
 
 The value of EXPR indicates how many call frames to go back before the
 current one; the top frame is frame 0.
+
+Exit Status:
+Returns 0 unless the shell is not executing a shell function or EXPR
+is invalid.
 $END
 
 #include <config.h>

builtins/caller.def~

@@ -25,7 +25,7 @@ $BUILTIN caller
 $FUNCTION caller_builtin
 $DEPENDS_ON DEBUGGER
 $SHORT_DOC caller [expr]
-Returns the context of the current subroutine call.  
+Return the context of the current subroutine call.
 
 Without EXPR, returns "$line $filename".  With EXPR, returns
 "$line $subroutine $filename"; this extra information can be used to
@@ -129,9 +129,9 @@ caller_builtin (list)
 static char *caller_doc[] = {
 N_("Returns the context of the current subroutine call.\n\
     \n\
-    Without EXPR, returns \"$line $filename\".  With EXPR,\n\
-    returns \"$line $subroutine $filename\"; this extra information\n\
-    can be used used to provide a stack trace.\n\
+    Without EXPR, returns "$line $filename".  With EXPR, returns\n\
+    "$line $subroutine $filename"; this extra information can be used to\n\
+    provide a stack trace.\n\
     \n\
     The value of EXPR indicates how many call frames to go back before the\n\
     current one; the top frame is frame 0."),

builtins/cd.def

@@ -71,6 +71,8 @@ int cdable_vars;
 $BUILTIN cd
 $FUNCTION cd_builtin
 $SHORT_DOC cd [-L|-P] [dir]
+Change the shell working directory.
+
 Change the current directory to DIR.  The default DIR is the value of the
 HOME shell variable.
 
@@ -89,6 +91,9 @@ Options:
 	links
 
 The default is to follow symbolic links, as if `-L' were specified.
+
+Exit Status:
+Returns 0 if the directory is changed; non-zero otherwise.
 $END
 
 /* Just set $PWD, don't change OLDPWD.  Used by `pwd -P' in posix mode. */
@@ -332,6 +337,10 @@ Options:
   -P	print the physical directory, without any symbolic links
 
 By default, `pwd' behaves as if `-L' were specified.
+
+Exit Status:
+Returns 0 unless an invalid option is given or the current directory
+cannot be read.
 $END
 
 /* Non-zero means that pwd always prints the physical directory, without

builtins/cd.def~

@@ -63,8 +63,6 @@ static void setpwd __P((char *));
 static char *resetpwd __P((char *));
 static int change_to_directory __P((char *, int));
 
-static char *cdspell __P((char *));
-
 /* Change this to 1 to get cd spelling correction by default. */
 int cdspelling = 0;
 
@@ -73,6 +71,8 @@ int cdable_vars;
 $BUILTIN cd
 $FUNCTION cd_builtin
 $SHORT_DOC cd [-L|-P] [dir]
+Change the shell working directory.
+
 Change the current directory to DIR.  The default DIR is the value of the
 HOME shell variable.
 
@@ -309,7 +309,7 @@ cd_builtin (list)
      typo.  This is similar to the UNIX 8th and 9th Edition shells. */
   if (lflag & LCD_DOSPELL)
     {
-      temp = cdspell (dirname);
+      temp = dirspell (dirname);
       if (temp && change_to_directory (temp, no_symlinks))
 	{
 	  printf ("%s\n", temp);
@@ -505,28 +505,3 @@ change_to_directory (newdir, nolinks)
   free (tdir);
   return r;
 }
-
-/* Code for cd spelling correction.  Original patch submitted by
-   Neil Russel (caret@c-side.com). */
-
-static char *
-cdspell (dirname)
-     char *dirname;
-{
-  int n;
-  char *guess;
-
-  n = (strlen (dirname) * 3 + 1) / 2 + 1;
-  guess = (char *)xmalloc (n);
-
-  switch (spname (dirname, guess))
-    {
-    case -1:
-    default:
-      free (guess);
-      return (char *)NULL;
-    case 0:
-    case 1:
-      return guess;
-    }
-}

builtins/colon.def

@@ -25,19 +25,30 @@ $BUILTIN :
 $DOCNAME colon
 $FUNCTION colon_builtin
 $SHORT_DOC :
-No effect; the command does nothing.  A successful exit code is returned.
+Null command.
+
+No effect; the command does nothing.
+
+Exit Status:
+Always succeeds.
 $END
 
 $BUILTIN true
 $FUNCTION colon_builtin
 $SHORT_DOC true
-Returns a successful result.
+Return a successful result.
+
+Exit Status:
+Always succeeds.
 $END
 
 $BUILTIN false
 $FUNCTION false_builtin
 $SHORT_DOC false
-Returns an unsuccessful result.
+Return an unsuccessful result.
+
+Exit Status:
+Always fails.
 $END
 
 /* Return a successful result. */

builtins/colon.def~

@@ -25,7 +25,9 @@ $BUILTIN :
 $DOCNAME colon
 $FUNCTION colon_builtin
 $SHORT_DOC :
-No effect; the command does nothing.  A successful exit code is returned.
+Null command.
+
+No effect; the command does nothing.  Returns a successful exit value.
 $END
 
 $BUILTIN true

builtins/command.def

@@ -24,6 +24,8 @@ $PRODUCES command.c
 $BUILTIN command
 $FUNCTION command_builtin
 $SHORT_DOC command [-pVv] command [arg ...]
+Execute a simple command or display information about commands.
+
 Runs COMMAND with ARGS suppressing  shell function lookup, or display
 information about the specified COMMANDs.  Can be used to invoke commands
 on disk when a function with the same name exists.
@@ -33,6 +35,9 @@ Options:
 	the standard utilities
   -v	print a description of COMMAND similar to the `type' builtin
   -V	print a more verbose description of each COMMAND
+
+Exit Status:
+Returns exit status of COMMAND, or failure if COMMAND is not found.
 $END
 
 #include <config.h>

builtins/command.def~

@@ -24,13 +24,15 @@ $PRODUCES command.c
 $BUILTIN command
 $FUNCTION command_builtin
 $SHORT_DOC command [-pVv] command [arg ...]
+Execute a simple command or display information about commands.
+
 Runs COMMAND with ARGS suppressing  shell function lookup, or display
 information about the specified COMMANDs.  Can be used to invoke commands
 on disk when a function with the same name exists.
 
 Options:
   -p	use a default value for PATH that is guaranteed to find all of
-	the standard utilities.
+	the standard utilities
   -v	print a description of COMMAND similar to the `type' builtin
   -V	print a more verbose description of each COMMAND
 $END

builtins/complete.def

@@ -38,6 +38,9 @@ Options:
 
 When completion is attempted, the actions are applied in the order the
 uppercase-letter options are listed above.
+
+Exit Status:
+Returns success unless an invalid option is supplied or an error occurs.
 $END
 
 #include <config.h>
@@ -65,10 +68,18 @@ $END
 
 #define STRDUP(x)       ((x) ? savestring (x) : (char *)NULL)
 
+/* Structure containing all the non-action (binary) options; filled in by
+   build_actions(). */
+struct _optflags {
+  int pflag;
+  int rflag;
+  int Eflag;
+};
+
 static int find_compact __P((char *));
 static int find_compopt __P((char *));
 
-static int build_actions __P((WORD_LIST *, int *, int *, unsigned long *, unsigned long *));
+static int build_actions __P((WORD_LIST *, struct _optflags *, unsigned long *, unsigned long *));
 
 static int remove_cmd_completions __P((WORD_LIST *));
 
@@ -165,9 +176,9 @@ find_compopt (name)
 */
 
 static int
-build_actions (list, pp, rp, actp, optp)
+build_actions (list, flagp, actp, optp)
      WORD_LIST *list;
-     int *pp, *rp;
+     struct _optflags *flagp;
      unsigned long *actp, *optp;
 {
   int opt, ind, opt_given;
@@ -177,15 +188,15 @@ build_actions (list, pp, rp, actp, optp)
   opt_given = 0;
 
   reset_internal_getopt ();
-  while ((opt = internal_getopt (list, "abcdefgjko:prsuvA:G:W:P:S:X:F:C:")) != -1)
+  while ((opt = internal_getopt (list, "abcdefgjko:prsuvA:G:W:P:S:X:F:C:E")) != -1)
     {
       opt_given = 1;
       switch (opt)
 	{
 	case 'r':
-	  if (rp)
+	  if (flagp)
 	    {
-	      *rp = 1;
+	      flagp->rflag = 1;
 	      break;
 	    }
 	  else
@@ -196,9 +207,9 @@ build_actions (list, pp, rp, actp, optp)
 	    }
 
 	case 'p':
-	  if (pp)
+	  if (flagp)
 	    {
-	      *pp = 1;
+	      flagp->pflag = 1;
 	      break;
 	    }
 	  else
@@ -265,6 +276,18 @@ build_actions (list, pp, rp, actp, optp)
 	case 'C':
 	  Carg = list_optarg;
 	  break;
+	case 'E':
+	  if (flagp)
+	    {
+	      flagp->Eflag = 1;
+	      break;
+	    }
+	  else
+	    {
+	      sh_invalidopt ("-E");
+	      builtin_usage ();
+	      return (EX_USAGE);
+	    }
 	case 'F':
 	  Farg = list_optarg;
 	  break;
@@ -300,9 +323,11 @@ int
 complete_builtin (list)
      WORD_LIST *list;
 {
-  int opt_given, pflag, rflag, rval;
+  int opt_given, rval;
   unsigned long acts, copts;
   COMPSPEC *cs;
+  struct _optflags oflags;
+  WORD_LIST *l, *wl;
 
   if (list == 0)
     {
@@ -310,24 +335,33 @@ complete_builtin (list)
       return (EXECUTION_SUCCESS);
     }
 
-  opt_given = pflag = rflag = 0;
+  opt_given = oflags.pflag = oflags.rflag = oflags.Eflag = 0;
+
   acts = copts = (unsigned long)0L;
   Garg = Warg = Parg = Sarg = Xarg = Farg = Carg = (char *)NULL;
   cs = (COMPSPEC *)NULL;
 
   /* Build the actions from the arguments.  Also sets the [A-Z]arg variables
      as a side effect if they are supplied as options. */
-  rval = build_actions (list, &pflag, &rflag, &acts, &copts);
+  rval = build_actions (list, &oflags, &acts, &copts);
   if (rval == EX_USAGE)
     return (rval);
   opt_given = rval != EXECUTION_FAILURE;
 
   list = loptend;
 
+  wl = oflags.Eflag ? make_word_list (make_bare_word ("_EmptycmD_"), (WORD_LIST *)NULL) : 0;
+
   /* -p overrides everything else */
-  if (pflag || (list == 0 && opt_given == 0))
+  if (oflags.pflag || (list == 0 && opt_given == 0))
     {
-      if (list == 0)
+      if (wl)
+	{
+	  rval = print_cmd_completions (wl);
+	  dispose_words (wl);
+	  return rval;
+	}
+      else if (list == 0)
 	{
 	  print_all_completions ();
 	  return (EXECUTION_SUCCESS);
@@ -336,9 +370,15 @@ complete_builtin (list)
     }
 
   /* next, -r overrides everything else. */
-  if (rflag)
+  if (oflags.rflag)
     {
-      if (list == 0)
+      if (wl)
+	{
+	  rval = remove_cmd_completions (wl);
+	  dispose_words (wl);
+	  return rval;
+	}
+      else if (list == 0)
 	{
 	  progcomp_flush ();
 	  return (EXECUTION_SUCCESS);
@@ -346,7 +386,7 @@ complete_builtin (list)
       return (remove_cmd_completions (list));
     }
 
-  if (list == 0 && opt_given)
+  if (wl == 0 && list == 0 && opt_given)
     {
       builtin_usage ();
       return (EX_USAGE);
@@ -366,13 +406,14 @@ complete_builtin (list)
   cs->command = STRDUP (Carg);
   cs->filterpat = STRDUP (Xarg);
 
-  for (rval = EXECUTION_SUCCESS ; list; list = list->next)
+  for (rval = EXECUTION_SUCCESS, l = wl ? wl : list ; l; l = l->next)
     {
       /* Add CS as the compspec for the specified commands. */
-      if (progcomp_insert (list->word->word, cs) == 0)
+      if (progcomp_insert (l->word->word, cs) == 0)
 	rval = EXECUTION_FAILURE;
     }
 
+  dispose_words (wl);
   return (rval);
 }
 
@@ -589,6 +630,9 @@ Display possible completions depending on the options.
 Intended to be used from within a shell function generating possible
 completions.  If the optional WORD argument is supplied, matches against
 WORD are generated.
+
+Exit Status:
+Returns success unless an invalid option is supplied or an error occurs.
 $END
 
 int
@@ -610,7 +654,7 @@ compgen_builtin (list)
 
   /* Build the actions from the arguments.  Also sets the [A-Z]arg variables
      as a side effect if they are supplied as options. */
-  rval = build_actions (list, (int *)NULL, (int *)NULL, &acts, &copts);
+  rval = build_actions (list, (struct _optflags *)NULL, &acts, &copts);
   if (rval == EX_USAGE)
     return (rval);
   if (rval == EXECUTION_FAILURE)
@@ -696,13 +740,17 @@ have previously been defined using the `complete' builtin.  If no NAMEs
 are supplied, compopt must be called by a function currently generating
 completions, and the options for that currently-executing completion
 generator are modified.
+
+Exit Status:
+Returns success unless an invalid option is supplied or NAME does not
+have a completion specification defined.
 $END
 
 int
 compopt_builtin (list)
      WORD_LIST *list;
 {
-  int opts_on, opts_off, *opts, opt, oind, ret;
+  int opts_on, opts_off, *opts, opt, oind, ret, Eflag;
   WORD_LIST *l;
   COMPSPEC *cs;
 

builtins/complete.def~

@@ -38,6 +38,9 @@ Options:
 
 When completion is attempted, the actions are applied in the order the
 uppercase-letter options are listed above.
+
+Exit Status:
+Returns success unless an invalid option is supplied or an error occurs.
 $END
 
 #include <config.h>
@@ -65,10 +68,18 @@ $END
 
 #define STRDUP(x)       ((x) ? savestring (x) : (char *)NULL)
 
+/* Structure containing all the non-action (binary) options; filled in by
+   build_actions(). */
+struct _optflags {
+  int pflag;
+  int rflag;
+  int Eflag;
+};
+
 static int find_compact __P((char *));
 static int find_compopt __P((char *));
 
-static int build_actions __P((WORD_LIST *, int *, int *, unsigned long *, unsigned long *));
+static int build_actions __P((WORD_LIST *, struct _optflags *, unsigned long *, unsigned long *));
 
 static int remove_cmd_completions __P((WORD_LIST *));
 
@@ -165,9 +176,9 @@ find_compopt (name)
 */
 
 static int
-build_actions (list, pp, rp, actp, optp)
+build_actions (list, flagp, actp, optp)
      WORD_LIST *list;
-     int *pp, *rp;
+     struct _optflags *flagp;
      unsigned long *actp, *optp;
 {
   int opt, ind, opt_given;
@@ -177,15 +188,15 @@ build_actions (list, pp, rp, actp, optp)
   opt_given = 0;
 
   reset_internal_getopt ();
-  while ((opt = internal_getopt (list, "abcdefgjko:prsuvA:G:W:P:S:X:F:C:")) != -1)
+  while ((opt = internal_getopt (list, "abcdefgjko:prsuvA:G:W:P:S:X:F:C:E")) != -1)
     {
       opt_given = 1;
       switch (opt)
 	{
 	case 'r':
-	  if (rp)
+	  if (flagp)
 	    {
-	      *rp = 1;
+	      flagp->rflag = 1;
 	      break;
 	    }
 	  else
@@ -196,9 +207,9 @@ build_actions (list, pp, rp, actp, optp)
 	    }
 
 	case 'p':
-	  if (pp)
+	  if (flagp)
 	    {
-	      *pp = 1;
+	      flagp->pflag = 1;
 	      break;
 	    }
 	  else
@@ -265,6 +276,18 @@ build_actions (list, pp, rp, actp, optp)
 	case 'C':
 	  Carg = list_optarg;
 	  break;
+	case 'E':
+	  if (flagp)
+	    {
+	      flagp->Eflag = 1;
+	      break;
+	    }
+	  else
+	    {
+	      sh_invalidopt ("-E");
+	      builtin_usage ();
+	      return (EX_USAGE);
+	    }
 	case 'F':
 	  Farg = list_optarg;
 	  break;
@@ -300,9 +323,11 @@ int
 complete_builtin (list)
      WORD_LIST *list;
 {
-  int opt_given, pflag, rflag, rval;
+  int opt_given, rval;
   unsigned long acts, copts;
   COMPSPEC *cs;
+  struct _optflags oflags;
+  WORD_LIST *l, *wl;
 
   if (list == 0)
     {
@@ -310,24 +335,33 @@ complete_builtin (list)
       return (EXECUTION_SUCCESS);
     }
 
-  opt_given = pflag = rflag = 0;
+  oflags.pflag = oflags.rflag = oflags.Eflag = 0;
+
   acts = copts = (unsigned long)0L;
   Garg = Warg = Parg = Sarg = Xarg = Farg = Carg = (char *)NULL;
   cs = (COMPSPEC *)NULL;
 
   /* Build the actions from the arguments.  Also sets the [A-Z]arg variables
      as a side effect if they are supplied as options. */
-  rval = build_actions (list, &pflag, &rflag, &acts, &copts);
+  rval = build_actions (list, &oflags, &acts, &copts);
   if (rval == EX_USAGE)
     return (rval);
   opt_given = rval != EXECUTION_FAILURE;
 
   list = loptend;
 
+  wl = oflags.Eflag ? make_word_list (make_bare_word ("_EmptycmD_"), (WORD_LIST *)NULL) : 0;
+
   /* -p overrides everything else */
-  if (pflag || (list == 0 && opt_given == 0))
+  if (oflags.pflag || (list == 0 && opt_given == 0))
     {
-      if (list == 0)
+      if (wl)
+	{
+	  rval = print_cmd_completions (wl);
+	  dispose_words (wl);
+	  return rval;
+	}
+      else if (list == 0)
 	{
 	  print_all_completions ();
 	  return (EXECUTION_SUCCESS);
@@ -336,9 +370,15 @@ complete_builtin (list)
     }
 
   /* next, -r overrides everything else. */
-  if (rflag)
+  if (oflags.rflag)
     {
-      if (list == 0)
+      if (wl)
+	{
+	  rval = remove_cmd_completions (wl);
+	  dispose_words (wl);
+	  return rval;
+	}
+      else if (list == 0)
 	{
 	  progcomp_flush ();
 	  return (EXECUTION_SUCCESS);
@@ -346,7 +386,7 @@ complete_builtin (list)
       return (remove_cmd_completions (list));
     }
 
-  if (list == 0 && opt_given)
+  if (wl == 0 && list == 0 && opt_given)
     {
       builtin_usage ();
       return (EX_USAGE);
@@ -366,13 +406,14 @@ complete_builtin (list)
   cs->command = STRDUP (Carg);
   cs->filterpat = STRDUP (Xarg);
 
-  for (rval = EXECUTION_SUCCESS ; list; list = list->next)
+  for (rval = EXECUTION_SUCCESS, l = wl ? wl : list ; l; l = l->next)
     {
       /* Add CS as the compspec for the specified commands. */
-      if (progcomp_insert (list->word->word, cs) == 0)
+      if (progcomp_insert (l->word->word, cs) == 0)
 	rval = EXECUTION_FAILURE;
     }
 
+  dispose_words (wl);
   return (rval);
 }
 
@@ -584,11 +625,14 @@ $BUILTIN compgen
 $DEPENDS_ON PROGRAMMABLE_COMPLETION
 $FUNCTION compgen_builtin
 $SHORT_DOC compgen [-abcdefgjksuv] [-o option]  [-A action] [-G globpat] [-W wordlist]  [-F function] [-C command] [-X filterpat] [-P prefix] [-S suffix] [word]
-Display the possible completions depending on the options.
+Display possible completions depending on the options.
 
 Intended to be used from within a shell function generating possible
 completions.  If the optional WORD argument is supplied, matches against
 WORD are generated.
+
+Exit Status:
+Returns success unless an invalid option is supplied or an error occurs.
 $END
 
 int
@@ -610,7 +654,7 @@ compgen_builtin (list)
 
   /* Build the actions from the arguments.  Also sets the [A-Z]arg variables
      as a side effect if they are supplied as options. */
-  rval = build_actions (list, (int *)NULL, (int *)NULL, &acts, &copts);
+  rval = build_actions (list, (struct _optflags *)NULL, &acts, &copts);
   if (rval == EX_USAGE)
     return (rval);
   if (rval == EXECUTION_FAILURE)
@@ -696,13 +740,17 @@ have previously been defined using the `complete' builtin.  If no NAMEs
 are supplied, compopt must be called by a function currently generating
 completions, and the options for that currently-executing completion
 generator are modified.
+
+Exit Status:
+Returns success unless an invalid option is supplied or NAME does not
+have a completion specification defined.
 $END
 
 int
 compopt_builtin (list)
      WORD_LIST *list;
 {
-  int opts_on, opts_off, *opts, opt, oind, ret;
+  int opts_on, opts_off, *opts, opt, oind, ret, Eflag;
   WORD_LIST *l;
   COMPSPEC *cs;
 

builtins/declare.def

@@ -24,6 +24,8 @@ $PRODUCES declare.c
 $BUILTIN declare
 $FUNCTION declare_builtin
 $SHORT_DOC declare [-afFirtx] [-p] [name[=value] ...]
+Set variable values and attributes.
+
 Declare variables and give them attributes.  If no NAMEs are given,
 display the attributes and values of all variables.
 
@@ -47,11 +49,16 @@ the `let' command) performed when the variable is assigned a value.
 
 When used in a function, `declare' makes NAMEs local, as with the `local'
 command.
+
+Exit Status:
+Returns success unless an invalid option is supplied or an error occurs.
 $END
 
 $BUILTIN typeset
 $FUNCTION declare_builtin
 $SHORT_DOC typeset [-afFirtx] [-p] name[=value] ...
+Set variable values and attributes.
+
 Obsolete.  See `help declare'.
 $END
 
@@ -90,11 +97,17 @@ declare_builtin (list)
 $BUILTIN local
 $FUNCTION local_builtin
 $SHORT_DOC local [option] name[=value] ...
+Define local variables.
+
 Create a local variable called NAME, and give it VALUE.  OPTION can
 be any option accepted by `declare'.
 
 Local variables can only be used within a function; they are visible
 only to the function where they are defined and its children.
+
+Exit Status:
+Returns success unless an invalid option is supplied, an error occurs,
+or the shell is not executing a function.
 $END
 int
 local_builtin (list)
@@ -390,11 +403,8 @@ declare_internal (list, local_var)
 	    {
 	      int vlen;
 	      vlen = STRLEN (value);
-#if 0
-	      if (value[0] == '(' && strchr (value, ')'))
-#else
+
 	      if (value[0] == '(' && value[vlen-1] == ')')
-#endif
 		compound_array_assign = 1;
 	      else
 		simple_array_assign = 1;

builtins/declare.def~

@@ -24,6 +24,8 @@ $PRODUCES declare.c
 $BUILTIN declare
 $FUNCTION declare_builtin
 $SHORT_DOC declare [-afFirtx] [-p] [name[=value] ...]
+Set variable values and attributes.
+
 Declare variables and give them attributes.  If no NAMEs are given,
 display the attributes and values of all variables.
 
@@ -47,11 +49,16 @@ the `let' command) performed when the variable is assigned a value.
 
 When used in a function, `declare' makes NAMEs local, as with the `local'
 command.
+
+Exit Status:
+Returns success unless an invalid option is supplied or an error occurs.
 $END
 
 $BUILTIN typeset
 $FUNCTION declare_builtin
 $SHORT_DOC typeset [-afFirtx] [-p] name[=value] ...
+Set variable values and attributes.
+
 Obsolete.  See `help declare'.
 $END
 
@@ -90,11 +97,17 @@ declare_builtin (list)
 $BUILTIN local
 $FUNCTION local_builtin
 $SHORT_DOC local [option] name[=value] ...
+Define local variables.
+
 Create a local variable called NAME, and give it VALUE.  OPTION can
 be any option accepted by `declare'.
 
 Local variables can only be used within a function; they are visible
 only to the function where they are defined and its children.
+
+Exit Status:
+Returns success unless an invalid option is supplied, an error occurs,
+or the shell is not executing a function.
 $END
 int
 local_builtin (list)
@@ -193,9 +206,7 @@ declare_internal (list, local_var)
 	    }
 	}
       else if (pflag && (flags_on == 0 || flags_on == att_function))
-	{
-	  show_all_var_attributes (flags_on == 0, nodefs);
-	}	  
+	show_all_var_attributes (flags_on == 0, nodefs);
       else if (flags_on == 0)
 	return (set_builtin ((WORD_LIST *)NULL));
       else

builtins/echo.def

@@ -37,6 +37,8 @@ $BUILTIN echo
 $FUNCTION echo_builtin
 $DEPENDS_ON V9_ECHO
 $SHORT_DOC echo [-neE] [arg ...]
+Write arguments to the standard output.
+
 Display the ARGs on the standard output followed by a newline.
 
 Options:
@@ -59,16 +61,24 @@ Options:
 	0 to 3 octal digits
   \xHH	the eight-bit character whose value is HH (hexadecimal).  HH
 	can be one or two hex digits
+
+Exit Status:
+Returns success unless a write error occurs.
 $END
 
 $BUILTIN echo
 $FUNCTION echo_builtin
 $DEPENDS_ON !V9_ECHO
 $SHORT_DOC echo [-n] [arg ...]
+Write arguments to the standard output.
+
 Display the ARGs on the standard output followed by a newline.
 
 Options:
   -n	do not append a newline
+
+Exit Status:
+Returns success unless a write error occurs.
 $END
 
 #if defined (V9_ECHO)

builtins/echo.def~

@@ -37,10 +37,12 @@ $BUILTIN echo
 $FUNCTION echo_builtin
 $DEPENDS_ON V9_ECHO
 $SHORT_DOC echo [-neE] [arg ...]
-Display each ARG on the standard output.
+Write arguments to the standard output.
+
+Display the ARGs on the standard output followed by a newline.
 
 Options:
-  -n	do not append a trailing newline
+  -n	do not append a newline
   -e	enable interpretation of the following backslash escapes
   -E	explicitly suppress interpretation of backslash escapes
 
@@ -59,17 +61,16 @@ Options:
 	0 to 3 octal digits
   \xHH	the eight-bit character whose value is HH (hexadecimal).  HH
 	can be one or two hex digits
-
 $END
 
 $BUILTIN echo
 $FUNCTION echo_builtin
 $DEPENDS_ON !V9_ECHO
 $SHORT_DOC echo [-n] [arg ...]
-Display each ARG on the standard output.
+Display the ARGs on the standard output followed by a newline.
 
 Options:
-  -n	do not append a trailing newline
+  -n	do not append a newline
 $END
 
 #if defined (V9_ECHO)

builtins/enable.def

@@ -24,6 +24,8 @@ $PRODUCES enable.c
 $BUILTIN enable
 $FUNCTION enable_builtin
 $SHORT_DOC enable [-a] [-dnps] [-f filename] [name ...]
+Enable and disable shell builtins.
+
 Enables and disables builtin shell commands.  Disabling allows you to
 execute a disk command which has the same name as a shell builtin
 without using a full pathname.
@@ -42,6 +44,9 @@ Without options, each NAME is enabled.
 
 To use the `test' found in $PATH instead of the shell builtin
 version, type `enable -n test'.
+
+Exit Status:
+Returns success unless NAME is not a shell builtin or an error occurs.
 $END
 
 #include <config.h>

builtins/enable.def~

@@ -24,19 +24,19 @@ $PRODUCES enable.c
 $BUILTIN enable
 $FUNCTION enable_builtin
 $SHORT_DOC enable [-a] [-dnps] [-f filename] [name ...]
+Enable and disable shell builtins.
+
 Enables and disables builtin shell commands.  Disabling allows you to
 execute a disk command which has the same name as a shell builtin
 without using a full pathname.
 
 Options:
-
   -a	print a list of builtins showing whether or not each is enabled
   -n	disable each NAME or display a list of disabled builtins
   -p	print the list of builtins in a reusable format
   -s	print only the names of Posix `special' builtins
 
 Options controlling dynamic loading:
-
   -f	Load builtin NAME from shared object FILENAME
   -d	Remove a builtin loaded with -f
 

builtins/eval.def

@@ -24,8 +24,13 @@ $PRODUCES eval.c
 $BUILTIN eval
 $FUNCTION eval_builtin
 $SHORT_DOC eval [arg ...]
+Execute arguments as a shell command.
+
 Combine ARGs into a single string, use the result as input to the shell,
 and execute the resulting commands.
+
+Exit Status:
+Returns exit status of command or success if command is null.
 $END
 
 #include <config.h>

builtins/eval.def~

@@ -1,7 +1,7 @@
 This file is eval.def, from which is created eval.c.
 It implements the builtin "eval" in Bash.
 
-Copyright (C) 1987-2002 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -24,7 +24,10 @@ $PRODUCES eval.c
 $BUILTIN eval
 $FUNCTION eval_builtin
 $SHORT_DOC eval [arg ...]
-Read ARGs as input to the shell and execute the resulting command(s).
+Execute arguments as a shell command.
+
+Combine ARGs into a single string, use the result as input to the shell,
+and execute the resulting commands.
 $END
 
 #include <config.h>

builtins/evalstring.c

@@ -79,6 +79,12 @@ parse_and_execute_cleanup ()
   run_unwind_frame ("parse_and_execute_top");
 }
 
+static void
+set_history_remembering ()
+{
+  remember_on_history = enable_history_list;
+}
+
 /* Parse and execute the commands in STRING.  Returns whatever
    execute_command () returns.  This frees STRING.  FLAGS is a
    flags word; look in common.h for the possible values.  Actions
@@ -115,7 +121,10 @@ parse_and_execute (string, from_file, flags)
   lreset = flags & SEVAL_RESETLINE;
 
 #if defined (HISTORY)
-  unwind_protect_int (remember_on_history);	/* can be used in scripts */
+  if (parse_and_execute_level == 0)
+    add_unwind_protect (set_history_remembering, (char *)NULL);
+  else
+    unwind_protect_int (remember_on_history);
 #  if defined (BANG_HISTORY)
   if (interactive_shell)
     {

builtins/evalstring.c~

@@ -0,0 +1,358 @@
+/* Evaluate a string as one or more shell commands.
+
+   Copyright (C) 1996-2005 Free Software Foundation, Inc.
+
+   This file is part of GNU Bash, the Bourne Again SHell.
+
+   Bash is free software; you can redistribute it and/or modify it under
+   the terms of the GNU General Public License as published by the Free
+   Software Foundation; either version 2, or (at your option) any later
+   version.
+
+   Bash is distributed in the hope that it will be useful, but WITHOUT ANY
+   WARRANTY; without even the implied warranty of MERCHANTABILITY or
+   FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+   for more details.
+   
+   You should have received a copy of the GNU General Public License along
+   with Bash; see the file COPYING.  If not, write to the Free Software
+   Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. */
+
+#include <config.h>
+
+#if defined (HAVE_UNISTD_H)
+#  ifdef _MINIX
+#    include <sys/types.h>
+#  endif
+#  include <unistd.h>
+#endif
+
+#include <stdio.h>
+#include <signal.h>
+
+#include <errno.h>
+
+#include "filecntl.h"
+#include "../bashansi.h"
+
+#include "../shell.h"
+#include "../jobs.h"
+#include "../builtins.h"
+#include "../flags.h"
+#include "../input.h"
+#include "../execute_cmd.h"
+#include "../redir.h"
+#include "../trap.h"
+
+#if defined (HISTORY)
+#  include "../bashhist.h"
+#endif
+
+#include "common.h"
+
+#if !defined (errno)
+extern int errno;
+#endif
+
+#define IS_BUILTIN(s)	(builtin_address_internal(s, 0) != (struct builtin *)NULL)
+
+extern int indirection_level, subshell_environment;
+extern int line_number;
+extern int last_command_exit_value;
+extern int running_trap;
+extern int loop_level;
+extern int posixly_correct;
+
+int parse_and_execute_level = 0;
+
+static int cat_file __P((REDIRECT *));
+
+/* How to force parse_and_execute () to clean up after itself. */
+void
+parse_and_execute_cleanup ()
+{
+  if (running_trap)
+    {
+      run_trap_cleanup (running_trap - 1);
+      unfreeze_jobs_list ();
+    }
+  run_unwind_frame ("parse_and_execute_top");
+}
+
+static void
+set_history_remembering ()
+{
+  remember_on_history = enable_history_list;
+}
+
+/* Parse and execute the commands in STRING.  Returns whatever
+   execute_command () returns.  This frees STRING.  FLAGS is a
+   flags word; look in common.h for the possible values.  Actions
+   are:
+   	(flags & SEVAL_NONINT) -> interactive = 0;
+   	(flags & SEVAL_INTERACT) -> interactive = 1;
+   	(flags & SEVAL_NOHIST) -> call bash_history_disable ()
+   	(flags & SEVAL_NOFREE) -> don't free STRING when finished
+   	(flags & SEVAL_RESETLINE) -> reset line_number to 1
+*/
+
+int
+parse_and_execute (string, from_file, flags)
+     char *string;
+     const char *from_file;
+     int flags;
+{
+  int code, x, lreset;
+  volatile int should_jump_to_top_level, last_result;
+  char *orig_string;
+  COMMAND *volatile command;
+
+  orig_string = string;
+  /* Unwind protect this invocation of parse_and_execute (). */
+  begin_unwind_frame ("parse_and_execute_top");
+  unwind_protect_int (parse_and_execute_level);
+  unwind_protect_jmp_buf (top_level);
+  unwind_protect_int (indirection_level);
+  unwind_protect_int (line_number);
+  unwind_protect_int (loop_level);
+  if (flags & (SEVAL_NONINT|SEVAL_INTERACT))
+    unwind_protect_int (interactive);
+
+  lreset = flags & SEVAL_RESETLINE;
+
+#if defined (HISTORY)
+  add_unwind_protect (set_history_remembering, (char *)NULL);
+#  if defined (BANG_HISTORY)
+  if (interactive_shell)
+    {
+      unwind_protect_int (history_expansion_inhibited);
+    }
+#  endif /* BANG_HISTORY */
+#endif /* HISTORY */
+
+  if (interactive_shell)
+    {
+      x = get_current_prompt_level ();
+      add_unwind_protect (set_current_prompt_level, x);
+    }
+  
+  add_unwind_protect (pop_stream, (char *)NULL);
+  if (orig_string && ((flags & SEVAL_NOFREE) == 0))
+    add_unwind_protect (xfree, orig_string);
+  end_unwind_frame ();
+
+  parse_and_execute_level++;
+
+  /* Reset the line number if the caller wants us to.  If we don't reset the
+     line number, we have to subtract one, because we will add one just
+     before executing the next command (resetting the line number sets it to
+     0; the first line number is 1). */
+  push_stream (lreset);
+  if (lreset == 0)
+    line_number--;
+    
+  indirection_level++;
+  if (flags & (SEVAL_NONINT|SEVAL_INTERACT))
+    interactive = (flags & SEVAL_NONINT) ? 0 : 1;
+
+#if defined (HISTORY)
+  if (flags & SEVAL_NOHIST)
+    bash_history_disable ();
+#endif /* HISTORY */
+
+  code = should_jump_to_top_level = 0;
+  last_result = EXECUTION_SUCCESS;
+
+  with_input_from_string (string, from_file);
+  while (*(bash_input.location.string))
+    {
+      command = (COMMAND *)NULL;
+
+      if (interrupt_state)
+	{
+	  last_result = EXECUTION_FAILURE;
+	  break;
+	}
+
+      /* Provide a location for functions which `longjmp (top_level)' to
+	 jump to.  This prevents errors in substitution from restarting
+	 the reader loop directly, for example. */
+      code = setjmp (top_level);
+
+      if (code)
+	{
+	  should_jump_to_top_level = 0;
+	  switch (code)
+	    {
+	    case FORCE_EOF:
+	    case ERREXIT:
+	    case EXITPROG:
+	      if (command)
+		run_unwind_frame ("pe_dispose");
+	      /* Remember to call longjmp (top_level) after the old
+		 value for it is restored. */
+	      should_jump_to_top_level = 1;
+	      goto out;
+
+	    case DISCARD:
+	      if (command)
+		run_unwind_frame ("pe_dispose");
+	      last_result = last_command_exit_value = EXECUTION_FAILURE; /* XXX */
+	      if (subshell_environment)
+		{
+		  should_jump_to_top_level = 1;
+		  goto out;
+		}
+	      else
+		{
+#if 0
+		  dispose_command (command);	/* pe_dispose does this */
+#endif
+		  continue;
+		}
+
+	    default:
+	      command_error ("parse_and_execute", CMDERR_BADJUMP, code, 0);
+	      break;
+	    }
+	}
+	  
+      if (parse_command () == 0)
+	{
+	  if (interactive_shell == 0 && read_but_dont_execute)
+	    {
+	      last_result = EXECUTION_SUCCESS;
+	      dispose_command (global_command);
+	      global_command = (COMMAND *)NULL;
+	    }
+	  else if (command = global_command)
+	    {
+	      struct fd_bitmap *bitmap;
+
+	      bitmap = new_fd_bitmap (FD_BITMAP_SIZE);
+	      begin_unwind_frame ("pe_dispose");
+	      add_unwind_protect (dispose_fd_bitmap, bitmap);
+	      add_unwind_protect (dispose_command, command);	/* XXX */
+
+	      global_command = (COMMAND *)NULL;
+
+#if defined (ONESHOT)
+	      /*
+	       * IF
+	       *   we were invoked as `bash -c' (startup_state == 2) AND
+	       *   parse_and_execute has not been called recursively AND
+	       *   we're not running a trap AND
+	       *   we have parsed the full command (string == '\0') AND
+	       *   we have a simple command without redirections AND
+	       *   the command is not being timed AND
+	       *   the command's return status is not being inverted
+	       * THEN
+	       *   tell the execution code that we don't need to fork
+	       */
+	      if (startup_state == 2 && parse_and_execute_level == 1 &&
+		  running_trap == 0 &&
+		  *bash_input.location.string == '\0' &&
+		  command->type == cm_simple &&
+		  !command->redirects && !command->value.Simple->redirects &&
+		  ((command->flags & CMD_TIME_PIPELINE) == 0) &&
+		  ((command->flags & CMD_INVERT_RETURN) == 0))
+		{
+		  command->flags |= CMD_NO_FORK;
+		  command->value.Simple->flags |= CMD_NO_FORK;
+		}
+#endif /* ONESHOT */
+
+	      /* See if this is a candidate for $( <file ). */
+	      if (startup_state == 2 &&
+		  (subshell_environment & SUBSHELL_COMSUB) &&
+		  *bash_input.location.string == '\0' &&
+		  command->type == cm_simple && !command->redirects &&
+		  (command->flags & CMD_TIME_PIPELINE) == 0 &&
+		  command->value.Simple->words == 0 &&
+		  command->value.Simple->redirects &&
+		  command->value.Simple->redirects->next == 0 &&
+		  command->value.Simple->redirects->instruction == r_input_direction)
+		{
+		  int r;
+		  r = cat_file (command->value.Simple->redirects);
+		  last_result = (r < 0) ? EXECUTION_FAILURE : EXECUTION_SUCCESS;
+		}
+	      else
+		last_result = execute_command_internal
+				(command, 0, NO_PIPE, NO_PIPE, bitmap);
+
+	      dispose_command (command);
+	      dispose_fd_bitmap (bitmap);
+	      discard_unwind_frame ("pe_dispose");
+	    }
+	}
+      else
+	{
+	  last_result = EXECUTION_FAILURE;
+
+	  /* Since we are shell compatible, syntax errors in a script
+	     abort the execution of the script.  Right? */
+	  break;
+	}
+    }
+
+ out:
+
+  run_unwind_frame ("parse_and_execute_top");
+
+  if (interrupt_state && parse_and_execute_level == 0)
+    {
+      /* An interrupt during non-interactive execution in an
+	 interactive shell (e.g. via $PROMPT_COMMAND) should
+	 not cause the shell to exit. */
+      interactive = interactive_shell;
+      throw_to_top_level ();
+    }
+
+  if (should_jump_to_top_level)
+    jump_to_top_level (code);
+
+  return (last_result);
+}
+
+/* Handle a $( < file ) command substitution.  This expands the filename,
+   returning errors as appropriate, then just cats the file to the standard
+   output. */
+static int
+cat_file (r)
+     REDIRECT *r;
+{
+  char *fn;
+  int fd, rval;
+
+  if (r->instruction != r_input_direction)
+    return -1;
+
+  /* Get the filename. */
+  if (posixly_correct && !interactive_shell)
+    disallow_filename_globbing++;
+  fn = redirection_expand (r->redirectee.filename);
+  if (posixly_correct && !interactive_shell)
+    disallow_filename_globbing--;
+
+  if (fn == 0)
+    {
+      redirection_error (r, AMBIGUOUS_REDIRECT);
+      return -1;
+    }
+
+  fd = open(fn, O_RDONLY);
+  if (fd < 0)
+    {
+      file_error (fn);
+      free (fn);
+      return -1;
+    }
+
+  rval = zcatfd (fd, 1, fn);
+
+  free (fn);
+  close (fd);
+
+  return (rval);
+}

builtins/exec.def

@@ -24,6 +24,8 @@ $PRODUCES exec.c
 $BUILTIN exec
 $FUNCTION exec_builtin
 $SHORT_DOC exec [-cl] [-a name] [command [arguments ...]] [redirection ...]
+Replace the shell with the given command.
+
 Execute COMMAND, replacing this shell with the specified program.
 ARGUMENTS become the arguments to COMMAND.  If COMMAND is not specified,
 any redirections take effect in the current shell.
@@ -35,6 +37,9 @@ Options:
 
 If the command cannot be executed, a non-interactive shell exits, unless
 the shell option `execfail' is set.
+
+Exit Status:
+Returns success unless COMMAND is not found or a redirection error occurs.
 $END
 
 #include <config.h>

builtins/exec.def~

@@ -24,12 +24,13 @@ $PRODUCES exec.c
 $BUILTIN exec
 $FUNCTION exec_builtin
 $SHORT_DOC exec [-cl] [-a name] [command [arguments ...]] [redirection ...]
+Replace the shell with the given command.
+
 Execute COMMAND, replacing this shell with the specified program.
 ARGUMENTS become the arguments to COMMAND.  If COMMAND is not specified,
 any redirections take effect in the current shell.
 
 Options:
-
   -a name	pass NAME as the zeroth argument to COMMAND
   -c		execute COMMAND with an empty environment
   -l		place a dash in the zeroth argument to COMMAND

builtins/exit.def

@@ -24,6 +24,8 @@ $PRODUCES exit.c
 $BUILTIN exit
 $FUNCTION exit_builtin
 $SHORT_DOC exit [n]
+Exit the shell.
+
 Exits the shell with a status of N.  If N is omitted, the exit status
 is that of the last command executed.
 $END
@@ -70,8 +72,11 @@ exit_builtin (list)
 
 $BUILTIN logout
 $FUNCTION logout_builtin
-$SHORT_DOC logout
-Exits a login shell.  Returns an error if not executed in a login shell.
+$SHORT_DOC logout [n]
+Exit a login shell.
+
+Exits a login shell with exit status N.  Returns an error if not executed
+in a login shell.
 $END
 
 /* How to logout. */

builtins/exit.def~

@@ -1,7 +1,7 @@
 This file is exit.def, from which is created exit.c.
 It implements the builtins "exit", and "logout" in Bash.
 
-Copyright (C) 1987-2006 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -24,7 +24,9 @@ $PRODUCES exit.c
 $BUILTIN exit
 $FUNCTION exit_builtin
 $SHORT_DOC exit [n]
-Exit the shell with a status of N.  If N is omitted, the exit status
+Exit the shell.
+
+Exits the shell with a status of N.  If N is omitted, the exit status
 is that of the last command executed.
 $END
 
@@ -70,8 +72,11 @@ exit_builtin (list)
 
 $BUILTIN logout
 $FUNCTION logout_builtin
-$SHORT_DOC logout
-Logout of a login shell.
+$SHORT_DOC logout [n]
+Exit a login shell.
+
+Exits a login shell with exit status N.  Returns an error if not executed
+in a login shell.
 $END
 
 /* How to logout. */

builtins/fc.def

@@ -25,6 +25,8 @@ $BUILTIN fc
 $FUNCTION fc_builtin
 $DEPENDS_ON HISTORY
 $SHORT_DOC fc [-e ename] [-lnr] [first] [last] or fc -s [pat=rep] [command]
+Display or execute commands from the history list.
+
 fc is used to list or edit and re-execute commands from the history list.
 FIRST and LAST can be numbers specifying the range, or FIRST can be a
 string, which means the most recent command beginning with that
@@ -43,6 +45,9 @@ re-executed after the substitution OLD=NEW is performed.
 A useful alias to use with this is r='fc -s', so that typing `r cc'
 runs the last command beginning with `cc' and typing `r' re-executes
 the last command.
+
+Exit Status:
+Returns success or status of executed command; non-zero if an error occurs.
 $END
 
 #include <config.h>

builtins/fc.def~

@@ -25,6 +25,8 @@ $BUILTIN fc
 $FUNCTION fc_builtin
 $DEPENDS_ON HISTORY
 $SHORT_DOC fc [-e ename] [-lnr] [first] [last] or fc -s [pat=rep] [command]
+Display or execute commands from the history list.
+
 fc is used to list or edit and re-execute commands from the history list.
 FIRST and LAST can be numbers specifying the range, or FIRST can be a
 string, which means the most recent command beginning with that
@@ -290,11 +292,6 @@ fc_builtin (list)
      line was actually added (HISTIGNORE may have caused it to not be),
      so we check hist_last_line_added. */
 
-  /* "When not listing, the fc command that caused the editing shall not be
-     entered into the history list." */
-  if (listing == 0 && hist_last_line_added)
-    delete_last_history ();
-
   last_hist = i - remember_on_history - hist_last_line_added;
 
   if (list)
@@ -322,6 +319,11 @@ fc_builtin (list)
 	histbeg = histend = last_hist;
     }
 
+  /* "When not listing, the fc command that caused the editing shall not be
+     entered into the history list." */
+  if (listing == 0 && hist_last_line_added)
+    delete_last_history ();
+
   /* We print error messages for line specifications out of range. */
   if ((histbeg < 0) || (histend < 0))
     {

builtins/fg_bg.def

@@ -25,9 +25,14 @@ $BUILTIN fg
 $FUNCTION fg_builtin
 $DEPENDS_ON JOB_CONTROL
 $SHORT_DOC fg [job_spec]
+Move job to the foreground.
+
 Place the job identified by JOB_SPEC in the foreground, making it the
 current job.  If JOB_SPEC is not present, the shell's notion of the
 current job is used.
+
+Exit Status:
+Status of command placed in foreground, or failure if an error occurs.
 $END
 
 #include <config.h>
@@ -83,9 +88,14 @@ $BUILTIN bg
 $FUNCTION bg_builtin
 $DEPENDS_ON JOB_CONTROL
 $SHORT_DOC bg [job_spec ...]
+Move jobs to the background.
+
 Place the jobs identified by each JOB_SPEC in the background, as if they
 had been started with `&'.  If JOB_SPEC is not present, the shell's notion
 of the current job is used.
+
+Exit Status:
+Returns success unless job control is not enabled or an error occurs.
 $END
 
 #if defined (JOB_CONTROL)

builtins/fg_bg.def~

@@ -25,9 +25,11 @@ $BUILTIN fg
 $FUNCTION fg_builtin
 $DEPENDS_ON JOB_CONTROL
 $SHORT_DOC fg [job_spec]
+Move job to the foreground.
+
 Place the job identified by JOB_SPEC in the foreground, making it the
-current job.  If JOB_SPEC is not present, the shell's notion of the current
-job is used.
+current job.  If JOB_SPEC is not present, the shell's notion of the
+current job is used.
 $END
 
 #include <config.h>
@@ -83,6 +85,8 @@ $BUILTIN bg
 $FUNCTION bg_builtin
 $DEPENDS_ON JOB_CONTROL
 $SHORT_DOC bg [job_spec ...]
+Move jobs to the background.
+
 Place the jobs identified by each JOB_SPEC in the background, as if they
 had been started with `&'.  If JOB_SPEC is not present, the shell's notion
 of the current job is used.

builtins/getopts.def

@@ -24,7 +24,10 @@ $PRODUCES getopts.c
 $BUILTIN getopts
 $FUNCTION getopts_builtin
 $SHORT_DOC getopts optstring name [arg]
-Getopts is used by shell procedures to parse positional parameters.
+Parse option arguments.
+
+Getopts is used by shell procedures to parse positional parameters
+as options.
 
 OPTSTRING contains the option letters to be recognized; if a letter
 is followed by a colon, the option is expected to have an argument,
@@ -54,6 +57,10 @@ OPTSTRING is not a colon.  OPTERR has the value 1 by default.
 
 Getopts normally parses the positional parameters ($0 - $9), but if
 more arguments are given, they are parsed instead.
+
+Exit Status:
+Returns success if an option is found; fails if the end of options is
+encountered or an error occurs.
 $END
 
 #include <config.h>

builtins/getopts.def~

@@ -0,0 +1,326 @@
+This file is getopts.def, from which is created getopts.c.
+It implements the builtin "getopts" in Bash.
+
+Copyright (C) 1987-2004 Free Software Foundation, Inc.
+
+This file is part of GNU Bash, the Bourne Again SHell.
+
+Bash is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free
+Software Foundation; either version 2, or (at your option) any later
+version.
+
+Bash is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License along
+with Bash; see the file COPYING.  If not, write to the Free Software
+Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA.
+
+$PRODUCES getopts.c
+
+$BUILTIN getopts
+$FUNCTION getopts_builtin
+$SHORT_DOC getopts optstring name [arg]
+Parse option arguments.
+
+Getopts is used by shell procedures to parse positional parameters
+as options.
+
+OPTSTRING contains the option letters to be recognized; if a letter
+is followed by a colon, the option is expected to have an argument,
+which should be separated from it by white space.
+
+Each time it is invoked, getopts will place the next option in the
+shell variable $name, initializing name if it does not exist, and
+the index of the next argument to be processed into the shell
+variable OPTIND.  OPTIND is initialized to 1 each time the shell or
+a shell script is invoked.  When an option requires an argument,
+getopts places that argument into the shell variable OPTARG.
+
+getopts reports errors in one of two ways.  If the first character
+of OPTSTRING is a colon, getopts uses silent error reporting.  In
+this mode, no error messages are printed.  If an invalid option is
+seen, getopts places the option character found into OPTARG.  If a
+required argument is not found, getopts places a ':' into NAME and
+sets OPTARG to the option character found.  If getopts is not in
+silent mode, and an invalid option is seen, getopts places '?' into
+NAME and unsets OPTARG.  If a required argument is not found, a '?'
+is placed in NAME, OPTARG is unset, and a diagnostic message is
+printed.
+
+If the shell variable OPTERR has the value 0, getopts disables the
+printing of error messages, even if the first character of
+OPTSTRING is not a colon.  OPTERR has the value 1 by default.
+
+Getopts normally parses the positional parameters ($0 - $9), but if
+more arguments are given, they are parsed instead.
+$END
+
+#include <config.h>
+
+#include <stdio.h>
+
+#if defined (HAVE_UNISTD_H)
+#  ifdef _MINIX
+#    include <sys/types.h>
+#  endif
+#  include <unistd.h>
+#endif
+
+#include "../bashansi.h"
+
+#include "../shell.h"
+#include "common.h"
+#include "bashgetopt.h"
+#include "getopt.h"
+
+#define G_EOF		-1
+#define G_INVALID_OPT	-2
+#define G_ARG_MISSING	-3
+
+extern char *this_command_name;
+
+static int getopts_bind_variable __P((char *, char *));
+static int dogetopts __P((int, char **));
+
+/* getopts_reset is magic code for when OPTIND is reset.  N is the
+   value that has just been assigned to OPTIND. */
+void
+getopts_reset (newind)
+     int newind;
+{
+  sh_optind = newind;
+  sh_badopt = 0;
+}
+
+static int
+getopts_bind_variable (name, value)
+     char *name, *value;
+{
+  SHELL_VAR *v;
+
+  if (legal_identifier (name))
+    {
+      v = bind_variable (name, value, 0);
+      return (v && (readonly_p (v) == 0)) ? EXECUTION_SUCCESS : EXECUTION_FAILURE;
+    }
+  else
+    {
+      sh_invalidid (name);
+      return (EXECUTION_FAILURE);
+    }
+}
+
+/* Error handling is now performed as specified by Posix.2, draft 11
+   (identical to that of ksh-88).  The special handling is enabled if
+   the first character of the option string is a colon; this handling
+   disables diagnostic messages concerning missing option arguments
+   and invalid option characters.  The handling is as follows.
+
+   INVALID OPTIONS:
+        name -> "?"
+        if (special_error) then
+                OPTARG = option character found
+                no error output
+        else
+                OPTARG unset
+                diagnostic message
+        fi
+ 
+  MISSING OPTION ARGUMENT;
+        if (special_error) then
+                name -> ":"
+                OPTARG = option character found
+        else
+                name -> "?"
+                OPTARG unset
+                diagnostic message
+        fi
+ */
+
+static int
+dogetopts (argc, argv)
+     int argc;
+     char **argv;
+{
+  int ret, special_error, old_opterr, i, n;
+  char strval[2], numval[16];
+  char *optstr;			/* list of options */
+  char *name;			/* variable to get flag val */
+  char *t;
+
+  if (argc < 3)
+    {
+      builtin_usage ();
+      return (EX_USAGE);
+    }
+
+  /* argv[0] is "getopts". */
+
+  optstr = argv[1];
+  name = argv[2];
+  argc -= 2;
+  argv += 2;
+
+  special_error = optstr[0] == ':';
+
+  if (special_error)
+    {
+      old_opterr = sh_opterr;
+      optstr++;
+      sh_opterr = 0;		/* suppress diagnostic messages */
+    }
+
+  if (argc > 1)
+    {
+      sh_getopt_restore_state (argv);
+      t = argv[0];
+      argv[0] = dollar_vars[0];
+      ret = sh_getopt (argc, argv, optstr);
+      argv[0] = t;
+    }
+  else if (rest_of_args == (WORD_LIST *)NULL)
+    {
+      for (i = 0; i < 10 && dollar_vars[i]; i++)
+	;
+
+      sh_getopt_restore_state (dollar_vars);
+      ret = sh_getopt (i, dollar_vars, optstr);
+    }
+  else
+    {
+      register WORD_LIST *words;
+      char **v;
+
+      for (i = 0; i < 10 && dollar_vars[i]; i++)
+	;
+      for (words = rest_of_args; words; words = words->next, i++)
+	;
+      v = strvec_create (i + 1);
+      for (i = 0; i < 10 && dollar_vars[i]; i++)
+	v[i] = dollar_vars[i];
+      for (words = rest_of_args; words; words = words->next, i++)
+	v[i] = words->word->word;
+      v[i] = (char *)NULL;
+      sh_getopt_restore_state (v);
+      ret = sh_getopt (i, v, optstr);
+      free (v);
+    }
+
+  if (special_error)
+    sh_opterr = old_opterr;
+
+  /* Set the OPTIND variable in any case, to handle "--" skipping.  It's
+     highly unlikely that 14 digits will be too few. */
+  if (sh_optind < 10)
+    {
+      numval[14] = sh_optind + '0';
+      numval[15] = '\0';
+      i = 14;
+    }
+  else
+    {
+      numval[i = 15] = '\0';
+      n = sh_optind;
+      do
+	{
+	  numval[--i] = (n % 10) + '0';
+	}
+      while (n /= 10);
+    }
+  bind_variable ("OPTIND", numval + i, 0);
+
+  /* If an error occurred, decide which one it is and set the return
+     code appropriately.  In all cases, the option character in error
+     is in OPTOPT.  If an invalid option was encountered, OPTARG is
+     NULL.  If a required option argument was missing, OPTARG points
+     to a NULL string (that is, sh_optarg[0] == 0). */
+  if (ret == '?')
+    {
+      if (sh_optarg == NULL)
+	ret = G_INVALID_OPT;
+      else if (sh_optarg[0] == '\0')
+	ret = G_ARG_MISSING;
+    }
+	    
+  if (ret == G_EOF)
+    {
+      unbind_variable ("OPTARG");
+      getopts_bind_variable (name, "?");
+      return (EXECUTION_FAILURE);
+    }
+
+  if (ret == G_INVALID_OPT)
+    {
+      /* Invalid option encountered. */
+      ret = getopts_bind_variable (name, "?");
+
+      if (special_error)
+	{
+	  strval[0] = (char)sh_optopt;
+	  strval[1] = '\0';
+	  bind_variable ("OPTARG", strval, 0);
+	}
+      else
+	unbind_variable ("OPTARG");
+
+      return (ret);
+    }
+
+  if (ret == G_ARG_MISSING)
+    {
+      /* Required argument missing. */
+      if (special_error)
+	{
+	  ret = getopts_bind_variable (name, ":");
+
+	  strval[0] = (char)sh_optopt;
+	  strval[1] = '\0';
+	  bind_variable ("OPTARG", strval, 0);
+	}
+      else
+	{
+	  ret = getopts_bind_variable (name, "?");
+	  unbind_variable ("OPTARG");
+	}
+      return (ret);
+    }			
+
+  bind_variable ("OPTARG", sh_optarg, 0);
+
+  strval[0] = (char) ret;
+  strval[1] = '\0';
+  return (getopts_bind_variable (name, strval));
+}
+
+/* The getopts builtin.  Build an argv, and call dogetopts with it. */
+int
+getopts_builtin (list)
+     WORD_LIST *list;
+{
+  char **av;
+  int ac, ret;
+
+  if (list == 0)
+    {
+      builtin_usage ();
+      return EX_USAGE;
+    }
+
+  reset_internal_getopt ();
+  if (internal_getopt (list, "") != -1)
+    {
+      builtin_usage ();
+      return (EX_USAGE);
+    }
+  list = loptend;
+
+  av = make_builtin_argv (list, &ac);
+  ret = dogetopts (ac, av);
+  free ((char *)av);
+
+  return (ret);
+}

builtins/hash.def

@@ -24,6 +24,8 @@ $PRODUCES hash.c
 $BUILTIN hash
 $FUNCTION hash_builtin
 $SHORT_DOC hash [-lr] [-p pathname] [-dt] [name ...]
+Remember or display program locations.
+
 Determine and remember the full pathname of each command NAME.  If
 no arguments are given, information about remembered commands is displayed.
 
@@ -35,6 +37,12 @@ Options:
   -t		print the remembered location of each NAME, preceding
 		each location with the corresponding NAME if multiple
 		NAMEs are given
+Arguments:
+  NAME		Each NAME is searched for in $PATH and added to the list
+		of remembered commands.
+
+Exit Status:
+Returns success unless NAME is not found or an invalid option is given.
 $END
 
 #include <config.h>

builtins/hash.def~

@@ -1,7 +1,7 @@
 This file is hash.def, from which is created hash.c.
 It implements the builtin "hash" in Bash.
 
-Copyright (C) 1987-2006 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -24,16 +24,22 @@ $PRODUCES hash.c
 $BUILTIN hash
 $FUNCTION hash_builtin
 $SHORT_DOC hash [-lr] [-p pathname] [-dt] [name ...]
-For each NAME, the full pathname of the command is determined and
-remembered.  If the -p option is supplied, PATHNAME is used as the
-full pathname of NAME, and no path search is performed.  The -r
-option causes the shell to forget all remembered locations.  The -d
-option causes the shell to forget the remembered location of each NAME.
-If the -t option is supplied the full pathname to which each NAME
-corresponds is printed.  If multiple NAME arguments are supplied with
--t, the NAME is printed before the hashed full pathname.  The -l option
-causes output to be displayed in a format that may be reused as input.
-If no arguments are given, information about remembered commands is displayed.
+Remember or display program locations.
+
+Determine and remember the full pathname of each command NAME.  If
+no arguments are given, information about remembered commands is displayed.
+
+Options:
+  -d		forget the remembered location of each NAME
+  -l		display in a format that may be reused as input
+  -p pathname	use PATHNAME is the full pathname of NAME
+  -r		forget all remembered locations
+  -t		print the remembered location of each NAME, preceding
+		each location with the corresponding NAME if multiple
+		NAMEs are given
+Arguments:
+  NAME		Each NAME is searched for in $PATH and added to the list
+		of remembered commands.
 $END
 
 #include <config.h>

builtins/help.def

@@ -24,14 +24,24 @@ $PRODUCES help.c
 $BUILTIN help
 $FUNCTION help_builtin
 $DEPENDS_ON HELP_BUILTIN
-$SHORT_DOC help [-s] [pattern ...]
-Displays brief information about builtin commands.  If PATTERN is
+$SHORT_DOC help [-ds] [pattern ...]
+Display information about builtin commands.
+
+Displays brief summaries of builtin commands.  If PATTERN is
 specified, gives detailed help on all commands matching PATTERN,
 otherwise the list of help topics is printed.
 
 Options:
+  -d	output short description for each topic
+  -m	display usage in pseudo-manpage format
   -s	output only a short usage synopsis for each topic matching
 	PATTERN
+
+Arguments:
+  PATTERN	Pattern specifiying a help topic
+
+Exit Status:
+Returns success unless PATTERN is not found or an invalid option is given.
 $END
 
 #include <config.h>
@@ -66,6 +76,9 @@ extern int errno;
 #endif
 
 static void show_builtin_command_help __P((void));
+static int open_helpfile __P((char *));
+static void show_desc __P((char *, int));
+static void show_manpage __P((char *, int));
 static void show_longdoc __P((int));
 
 /* Print out a list of the known functions in the shell, and what they do.
@@ -77,14 +90,20 @@ help_builtin (list)
 {
   register int i;
   char *pattern, *name;
-  int plen, match_found, sflag;
+  int plen, match_found, sflag, dflag, mflag;
 
-  sflag = 0;
+  dflag = sflag = mflag = 0;
   reset_internal_getopt ();
-  while ((i = internal_getopt (list, "s")) != -1)
+  while ((i = internal_getopt (list, "dms")) != -1)
     {
       switch (i)
 	{
+	case 'd':
+	  dflag = 1;
+	  break;
+	case 'm':
+	  mflag = 1;
+	  break;
 	case 's':
 	  sflag = 1;
 	  break;
@@ -125,12 +144,22 @@ help_builtin (list)
 	  if ((strncmp (pattern, name, plen) == 0) ||
 	      (strmatch (pattern, name, FNMATCH_EXTFLAG) != FNM_NOMATCH))
 	    {
+	      match_found++;
+	      if (dflag)
+		{
+		  show_desc (name, i);
+		  continue;
+		}
+	      else if (mflag)
+		{
+		  show_manpage (name, i);
+		  continue;
+		}
+
 	      printf ("%s: %s\n", name, shell_builtins[i].short_doc);
 
 	      if (sflag == 0)
 		show_longdoc (i);
-
-	      match_found++;
 	    }
 	}
     }
@@ -145,6 +174,21 @@ help_builtin (list)
   return (EXECUTION_SUCCESS);
 }
 
+static int
+open_helpfile (name)
+     char *name;
+{
+  int fd;
+
+  fd = open (name, O_RDONLY);
+  if (fd == -1)
+    {
+      builtin_error (_("%s: cannot open: %s"), name, strerror (errno));
+      return -1;
+    }
+  return fd;
+}
+
 /* By convention, enforced by mkbuiltins.c, if separate help files are being
    used, the long_doc array contains one string -- the full pathname of the
    help file for this builtin.  */
@@ -160,12 +204,9 @@ show_longdoc (i)
 
   if (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL)
     {
-      fd = open (doc[0], O_RDONLY);
-      if (fd == -1)
-	{
-	  builtin_error (_("%s: cannot open: %s"), doc[0], strerror (errno));
-	  return;
-	}
+      fd = open_helpfile (doc[0]);
+      if (fd < 0)
+	return;
       zcatfd (fd, 1, doc[0]);
       close (fd);
     }
@@ -174,6 +215,118 @@ show_longdoc (i)
       printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
 }
 
+static void
+show_desc (name, i)
+     char *name;
+     int i;
+{
+  register int j;
+  char **doc, *line;
+  int fd, usefile;
+
+  doc = (char **)shell_builtins[i].long_doc;
+
+  usefile = (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL);
+  if (usefile)
+    {
+      fd = open_helpfile (doc[0]);
+      if (fd < 0)
+	return;
+      zmapfd (fd, &line, doc[0]);
+      close (fd);
+    }
+  else
+    line = doc ? doc[0] : (char *)NULL;
+
+  printf ("%s - ", name);
+  for (j = 0; line && line[j]; j++)
+    {
+      putchar (line[j]);
+      if (line[j] == '\n')
+	break;
+    }
+  
+  fflush (stdout);
+
+  if (usefile)
+    free (line);
+}
+
+/* Print builtin help in pseudo-manpage format. */
+static void
+show_manpage (name, i)
+     char *name;
+     int i;
+{
+  register int j;
+  char **doc, *line;
+  int fd, usefile;
+
+  doc = (char **)shell_builtins[i].long_doc;
+
+  usefile = (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL);
+  if (usefile)
+    {
+      fd = open_helpfile (doc[0]);
+      if (fd < 0)
+	return;
+      zmapfd (fd, &line, doc[0]);
+      close (fd);
+    }
+  else
+    line = doc ? _(doc[0]) : (char *)NULL;
+
+  /* NAME */
+  printf ("NAME\n");
+  printf ("%*s%s - ", BASE_INDENT, " ", name);
+  for (j = 0; line && line[j]; j++)
+    {
+      putchar (line[j]);
+      if (line[j] == '\n')
+	break;
+    }
+  printf ("\n");
+
+  /* SYNOPSIS */
+  printf ("SYNOPSIS\n");
+  printf ("%*s%s\n\n", BASE_INDENT, " ", shell_builtins[i].short_doc);
+
+  /* DESCRIPTION */
+  printf ("DESCRIPTION\n");
+  if (usefile == 0)
+    {
+      for (j = 0; doc[j]; j++)
+        printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
+    }
+  else
+    {
+      for (j = 0; line && line[j]; j++)
+	{
+	  putchar (line[j]);
+	  if (line[j] == '\n')
+	    printf ("%*s", BASE_INDENT, " ");
+	}
+    }
+  putchar ('\n');
+
+  /* SEE ALSO */
+  printf ("SEE ALSO\n");
+  printf ("%*sbash(1)\n\n", BASE_INDENT, " ");
+
+  /* IMPLEMENTATION */
+  printf ("IMPLEMENTATION\n");
+  printf ("%*s", BASE_INDENT, " ");
+  show_shell_version (0);
+  printf ("%*s", BASE_INDENT, " ");
+  printf (_("Copyright (C) 2008 Free Software Foundation, Inc.\n"));
+  printf ("%*s", BASE_INDENT, " ");
+  printf (_("License: GNU General Public License, version 2\n"));
+
+  fflush (stdout);
+  if (usefile)
+    free (line);
+}
+
 static void
 show_builtin_command_help ()
 {

builtins/help.def~

@@ -24,13 +24,24 @@ $PRODUCES help.c
 $BUILTIN help
 $FUNCTION help_builtin
 $DEPENDS_ON HELP_BUILTIN
-$SHORT_DOC help [-s] [pattern ...]
-Displays brief information about builtin commands.  If PATTERN is
+$SHORT_DOC help [-ds] [pattern ...]
+Display information about builtin commands.
+
+Displays brief summaries of builtin commands.  If PATTERN is
 specified, gives detailed help on all commands matching PATTERN,
 otherwise the list of help topics is printed.
 
 Options:
-  -s	output only a short usage synopsis for each topic matching PATTERN
+  -d	output short description for each topic
+  -m	display usage in pseudo-manpage format
+  -s	output only a short usage synopsis for each topic matching
+	PATTERN
+
+Arguments:
+  PATTERN	Pattern specifiying a help topic
+
+Exit Status:
+Returns success unless PATTERN is not found or an invalid option is given.
 $END
 
 #include <config.h>
@@ -65,6 +76,9 @@ extern int errno;
 #endif
 
 static void show_builtin_command_help __P((void));
+static int open_helpfile __P((char *));
+static void show_desc __P((char *, int));
+static void show_manpage __P((char *, int));
 static void show_longdoc __P((int));
 
 /* Print out a list of the known functions in the shell, and what they do.
@@ -76,14 +90,20 @@ help_builtin (list)
 {
   register int i;
   char *pattern, *name;
-  int plen, match_found, sflag;
+  int plen, match_found, sflag, dflag, mflag;
 
-  sflag = 0;
+  dflag = sflag = mflag = 0;
   reset_internal_getopt ();
-  while ((i = internal_getopt (list, "s")) != -1)
+  while ((i = internal_getopt (list, "dms")) != -1)
     {
       switch (i)
 	{
+	case 'd':
+	  dflag = 1;
+	  break;
+	case 'm':
+	  mflag = 1;
+	  break;
 	case 's':
 	  sflag = 1;
 	  break;
@@ -124,12 +144,22 @@ help_builtin (list)
 	  if ((strncmp (pattern, name, plen) == 0) ||
 	      (strmatch (pattern, name, FNMATCH_EXTFLAG) != FNM_NOMATCH))
 	    {
+	      match_found++;
+	      if (dflag)
+		{
+		  show_desc (name, i);
+		  continue;
+		}
+	      else if (mflag)
+		{
+		  show_manpage (name, i);
+		  continue;
+		}
+
 	      printf ("%s: %s\n", name, shell_builtins[i].short_doc);
 
 	      if (sflag == 0)
 		show_longdoc (i);
-
-	      match_found++;
 	    }
 	}
     }
@@ -144,6 +174,21 @@ help_builtin (list)
   return (EXECUTION_SUCCESS);
 }
 
+static int
+open_helpfile (name)
+     char *name;
+{
+  int fd;
+
+  fd = open (name, O_RDONLY);
+  if (fd == -1)
+    {
+      builtin_error (_("%s: cannot open: %s"), name, strerror (errno));
+      return -1;
+    }
+  return fd;
+}
+
 /* By convention, enforced by mkbuiltins.c, if separate help files are being
    used, the long_doc array contains one string -- the full pathname of the
    help file for this builtin.  */
@@ -159,12 +204,7 @@ show_longdoc (i)
 
   if (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL)
     {
-      fd = open (doc[0], O_RDONLY);
-      if (fd == -1)
-	{
-	  builtin_error (_("%s: cannot open: %s"), doc[0], strerror (errno));
-	  return;
-	}
+      fd = open_helpfile (doc[0]);
       zcatfd (fd, 1, doc[0]);
       close (fd);
     }
@@ -173,6 +213,114 @@ show_longdoc (i)
       printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
 }
 
+static void
+show_desc (name, i)
+     char *name;
+     int i;
+{
+  register int j;
+  char **doc, *line;
+  int fd, usefile;
+
+  doc = (char **)shell_builtins[i].long_doc;
+
+  usefile = (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL);
+  if (usefile)
+    {
+      fd = open_helpfile (doc[0]);
+      zmapfd (fd, &line, doc[0]);
+      close (fd);
+    }
+  else
+    line = doc ? doc[0] : (char *)NULL;
+
+  printf ("%s - ", name);
+  for (j = 0; line && line[j]; j++)
+    {
+      putchar (line[j]);
+      if (line[j] == '\n')
+	break;
+    }
+  
+  fflush (stdout);
+
+  if (usefile)
+    free (line);
+}
+
+/* Print builtin help in pseudo-manpage format. */
+static void
+show_manpage (name, i)
+     char *name;
+     int i;
+{
+  register int j;
+  char **doc, *line;
+  int fd, usefile;
+
+  doc = (char **)shell_builtins[i].long_doc;
+
+  usefile = (doc && doc[0] && *doc[0] == '/' && doc[1] == (char *)NULL);
+  if (usefile)
+    {
+      fd = open_helpfile (doc[0]);
+      zmapfd (fd, &line, doc[0]);
+      close (fd);
+    }
+  else
+    line = doc ? _(doc[0]) : (char *)NULL;
+
+  /* NAME */
+  printf ("NAME\n");
+  printf ("%*s%s - ", BASE_INDENT, " ", name);
+  for (j = 0; line && line[j]; j++)
+    {
+      putchar (line[j]);
+      if (line[j] == '\n')
+	break;
+    }
+  printf ("\n");
+
+  /* SYNOPSIS */
+  printf ("SYNOPSIS\n");
+  printf ("%*s%s\n\n", BASE_INDENT, " ", shell_builtins[i].short_doc);
+
+  /* DESCRIPTION */
+  printf ("DESCRIPTION\n");
+  if (usefile == 0)
+    {
+      for (j = 0; doc[j]; j++)
+        printf ("%*s%s\n", BASE_INDENT, " ", _(doc[j]));
+    }
+  else
+    {
+      for (j = 0; line && line[j]; j++)
+	{
+	  putchar (line[j]);
+	  if (line[j] == '\n')
+	    printf ("%*s", BASE_INDENT, " ");
+	}
+    }
+  putchar ('\n');
+
+  /* SEE ALSO */
+  printf ("SEE ALSO\n");
+  printf ("%*sbash(1)\n\n", BASE_INDENT, " ");
+
+  /* IMPLEMENTATION */
+  printf ("IMPLEMENTATION\n");
+  printf ("%*s", BASE_INDENT, " ");
+  show_shell_version (0);
+  printf ("%*s", BASE_INDENT, " ");
+  printf (_("Copyright (C) 2008 Free Software Foundation, Inc.\n"));
+  printf ("%*s", BASE_INDENT, " ");
+  printf (_("License: GNU General Public License, version 2\n"));
+
+  fflush (stdout);
+  if (usefile)
+    free (line);
+}
+
 static void
 show_builtin_command_help ()
 {

builtins/history.def

@@ -25,6 +25,8 @@ $BUILTIN history
 $FUNCTION history_builtin
 $DEPENDS_ON HISTORY
 $SHORT_DOC history [-c] [-d offset] [n] or history -anrw [filename] or history -ps arg [arg...]
+Display or manipulate the history list.
+
 Display the history list with line numbers, prefixing each modified
 entry with a `*'.  An argument of N lists only the last N entries.
 
@@ -49,6 +51,9 @@ if $HISTFILE has a value, that is used, else ~/.bash_history.
 If the $HISTTIMEFORMAT variable is set and not null, its value is used
 as a format string for strftime(3) to print the time stamp associated
 with each displayed history entry.  No time stamps are printed otherwise.
+
+Exit Status:
+Returns success unless an invalid option is given or an error occurs.
 $END
 
 #include <config.h>

builtins/history.def~

@@ -25,8 +25,10 @@ $BUILTIN history
 $FUNCTION history_builtin
 $DEPENDS_ON HISTORY
 $SHORT_DOC history [-c] [-d offset] [n] or history -anrw [filename] or history -ps arg [arg...]
-Display the history list with line numbers, prefixing each modified entry
-with a `*'.  An argument of N lists only the last N entries.
+Display or manipulate the history list.
+
+Display the history list with line numbers, prefixing each modified
+entry with a `*'.  An argument of N lists only the last N entries.
 
 Options:
   -c	clear the history list by deleting all of the entries

builtins/inlib.def

@@ -29,12 +29,17 @@ $BUILTIN inlib
 $FUNCTION inlib_builtin
 $DEPENDS_ON apollo
 $SHORT_DOC inlib pathname [pathname...]
+Install user-supplied library.
+
 Install a user-supplied library specified by pathname in the current
 shell process. The library is used to resolve external references
 in programs and libraries loaded after its installation.  Note
 that the library is not loaded into the address space unless it is
 needed to resolve an external reference.  The list of inlibed
 libraries is passed to all children of the current shell.
+
+Exit Status:
+Returns success unless PATHNAME is not found or an error occurs.
 $END
 
 #if defined (apollo)

builtins/inlib.def~

@@ -29,6 +29,8 @@ $BUILTIN inlib
 $FUNCTION inlib_builtin
 $DEPENDS_ON apollo
 $SHORT_DOC inlib pathname [pathname...]
+Install user-supplied library.
+
 Install a user-supplied library specified by pathname in the current
 shell process. The library is used to resolve external references
 in programs and libraries loaded after its installation.  Note
@@ -64,7 +66,7 @@ inlib_builtin (list)
 
       if (status.all != status_$ok)
 	{
-	  builtin_error ("%s: inlib failed", list->word->word);
+	  builtin_error (_("%s: inlib failed"), list->word->word);
 	  return_value = EXECUTION_FAILURE;
 	}
 

builtins/jobs.def

@@ -25,6 +25,8 @@ $BUILTIN jobs
 $FUNCTION jobs_builtin
 $DEPENDS_ON JOB_CONTROL
 $SHORT_DOC jobs [-lnprs] [jobspec ...] or jobs -x command [args]
+Display status of jobs.
+
 Lists the active jobs.  JOBSPEC restricts output to that job.
 Without options, the status of all active jobs is displayed.
 
@@ -39,6 +41,10 @@ Options:
 If -x is supplied, COMMAND is run after all job specifications that
 appear in ARGS have been replaced with the process ID of that job's
 process group leader.
+
+Exit Status:
+Returns success unless an invalid option is given or an error occurs.
+If -x is used, returns the exit status of COMMAND.
 $END
 
 #include <config.h>
@@ -208,6 +214,8 @@ $BUILTIN disown
 $FUNCTION disown_builtin
 $DEPENDS_ON JOB_CONTROL
 $SHORT_DOC disown [-h] [-ar] [jobspec ...]
+Remove jobs from current shell.
+
 Removes each JOBSPEC argument from the table of active jobs.  Without
 any JOBSPECs, the shell uses its notion of the current job.
 
@@ -216,6 +224,9 @@ Options:
   -h	mark each JOBSPEC so that SIGHUP is not sent to the job if the
 	shell receives a SIGHUP
   -r	remove only running jobs
+
+Exit Status:
+Returns success unless an invalid option or JOBSPEC is given.
 $END
 
 #if defined (JOB_CONTROL)

builtins/jobs.def~

@@ -1,7 +1,7 @@
 This file is jobs.def, from which is created jobs.c.
 It implements the builtins "jobs" and "disown" in Bash.
 
-Copyright (C) 1987-2006 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -25,6 +25,8 @@ $BUILTIN jobs
 $FUNCTION jobs_builtin
 $DEPENDS_ON JOB_CONTROL
 $SHORT_DOC jobs [-lnprs] [jobspec ...] or jobs -x command [args]
+Display status of jobs.
+
 Lists the active jobs.  JOBSPEC restricts output to that job.
 Without options, the status of all active jobs is displayed.
 
@@ -208,6 +210,8 @@ $BUILTIN disown
 $FUNCTION disown_builtin
 $DEPENDS_ON JOB_CONTROL
 $SHORT_DOC disown [-h] [-ar] [jobspec ...]
+Remove jobs from current shell.
+
 Removes each JOBSPEC argument from the table of active jobs.  Without
 any JOBSPECs, the shell uses its notion of the current job.
 

builtins/kill.def

@@ -24,6 +24,8 @@ $PRODUCES kill.c
 $BUILTIN kill
 $FUNCTION kill_builtin
 $SHORT_DOC kill [-s sigspec | -n signum | -sigspec] pid | jobspec ... or kill -l [sigspec]
+Send a signal to a job.
+
 Send the processes identified by PID or JOBSPEC the signal named by
 SIGSPEC or SIGNUM.  If neither SIGSPEC nor SIGNUM is present, then
 SIGTERM is assumed.
@@ -37,6 +39,9 @@ Options:
 Kill is a shell builtin for two reasons: it allows job IDs to be used
 instead of process IDs, and allows processes to be killed if the limit
 on processes that you can create is reached.
+
+Exit Status:
+Returns success unless an invalid option is given or an error occurs.
 $END
 
 #include <config.h>

builtins/kill.def~

@@ -24,6 +24,8 @@ $PRODUCES kill.c
 $BUILTIN kill
 $FUNCTION kill_builtin
 $SHORT_DOC kill [-s sigspec | -n signum | -sigspec] pid | jobspec ... or kill -l [sigspec]
+Send a signal to a job.
+
 Send the processes identified by PID or JOBSPEC the signal named by
 SIGSPEC or SIGNUM.  If neither SIGSPEC nor SIGNUM is present, then
 SIGTERM is assumed.
@@ -31,8 +33,8 @@ SIGTERM is assumed.
 Options:
   -s sig	SIG is a signal name
   -n sig	SIG is a signal number
-  -l	list the signal names; if arguments follow `-l' they are assumed
-	to be signal numbers for which names should be listed
+  -l	list the signal names; if arguments follow `-l' they are
+	assumed to be signal numbers for which names should be listed
 
 Kill is a shell builtin for two reasons: it allows job IDs to be used
 instead of process IDs, and allows processes to be killed if the limit

builtins/let.def

@@ -23,7 +23,9 @@ $BUILTIN let
 $FUNCTION let_builtin
 $PRODUCES let.c
 $SHORT_DOC let arg [arg ...]
-Evaluates ach ARG as an arithmetic expression.  Evaluation is done in
+Evaluate arithmetic expressions.
+
+Evaluate each ARG as an arithmetic expression.  Evaluation is done in
 fixed-width integers with no check for overflow, though division by 0
 is trapped and flagged as an error.  The following list of operators is
 grouped into levels of equal-precedence operators.  The levels are listed
@@ -59,8 +61,8 @@ Operators are evaluated in order of precedence.  Sub-expressions in
 parentheses are evaluated first and may override the precedence
 rules above.
 
-If the last ARG evaluates to 0, let returns 1; 0 is returned
-otherwise.
+Exit Status:
+If the last ARG evaluates to 0, let returns 1; let returns 0 otherwise..
 $END
 
 #include <config.h>

builtins/let.def~

@@ -1,7 +1,7 @@
 This file is let.def, from which is created let.c.
 It implements the builtin "let" in Bash.
 
-Copyright (C) 1987-2002 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -23,11 +23,13 @@ $BUILTIN let
 $FUNCTION let_builtin
 $PRODUCES let.c
 $SHORT_DOC let arg [arg ...]
-Each ARG is an arithmetic expression to be evaluated.  Evaluation
-is done in fixed-width integers with no check for overflow, though
-division by 0 is trapped and flagged as an error.  The following
-list of operators is grouped into levels of equal-precedence operators.
-The levels are listed in order of decreasing precedence.
+Evaluate arithmetic expressions.
+
+Evaluate each ARG as an arithmetic expression.  Evaluation is done in
+fixed-width integers with no check for overflow, though division by 0
+is trapped and flagged as an error.  The following list of operators is
+grouped into levels of equal-precedence operators.  The levels are listed
+in order of decreasing precedence.
 
 	id++, id--	variable post-increment, post-decrement
 	++id, --id	variable pre-increment, pre-decrement

builtins/mapfile.def

@@ -0,0 +1,318 @@
+This file is mapfile.def, from which is created mapfile.c.
+It implements the builtin "mapfile" in Bash.
+
+Copyright (C) 2005-2006 Rocky Bernstein for Free Software Foundation, Inc.
+Copyright (C) 2008 Free Software Foundation, Inc.
+
+This file is part of GNU Bash, the Bourne Again SHell.
+
+Bash is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free
+Software Foundation; either version 2, or (at your option) any later
+version.
+
+Bash is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License along
+with Bash; see the file COPYING.  If not, write to the Free Software
+Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA.
+
+$PRODUCES mapfile.c
+
+$BUILTIN mapfile
+$FUNCTION mapfile_builtin
+$SHORT_DOC mapfile [-n count] [-O origin] [-s count] [-t] [-u fd] [-C callback] [-c quantum] [array]
+Read lines from a file into an array variable.
+
+Read lines from the standard input into the array variable ARRAY, or from
+file descriptor FD if the -u option is supplied.  The variable MAPFILE is
+the default ARRAY.
+
+Options:
+  -n count	Copy at most COUNT lines.  If COUNT is 0, all lines are copied.
+  -O origin	Begin assigning to ARRAY at index ORIGIN.  The default index is 0.
+  -s count 	Discard the first COUNT lines read.
+  -t		Remove a trailing newline from each line read.
+  -u fd		Read lines from file descriptor FD instead of the standard input.
+  -C callback	Evaluate CALLBACK each time QUANTUM lines are read.
+  -c quantum	Specify the number of lines read between each call to CALLBACK.
+
+Arguments:
+  ARRAY		Array variable name to use for file data.
+
+If -C is supplied without -c, the default quantum is 5000.
+
+If not supplied with an explicit origin, mapfile will clear ARRAY before
+assigning to it.
+
+Exit Status:
+Returns success unless an invald option is given or ARRAY is readonly.
+$END
+
+#include <config.h>
+
+#include "builtins.h"
+#include "posixstat.h"
+
+#if defined (HAVE_UNISTD_H)
+#  include <unistd.h>
+#endif
+
+#include "bashansi.h"
+
+#include <stdio.h>
+#include <errno.h>
+
+#include "../bashintl.h"
+#include "../shell.h"
+#include "common.h"
+#include "bashgetopt.h"
+
+
+#if !defined (errno)
+extern int errno;
+#endif
+
+#if defined (ARRAY_VARS)
+
+#define DEFAULT_ARRAY_NAME	"MAPFILE"
+
+/* The value specifying how frequently `mapfile'  calls the callback. */
+#define DEFAULT_QUANTUM 5000
+
+/* Values for FLAGS */
+#define MAPF_CLEARARRAY	0x01
+#define MAPF_CHOP	0x02
+
+static int
+run_callback(callback, current_index)
+     const char *callback;
+     unsigned int current_index;
+{
+  unsigned int execlen;
+  char  *execstr;
+
+  execlen = strlen (callback) + 10;
+  /* 1 for space between %s and %d,
+     another 1 for the last nul char for C string. */
+  execlen += 2;
+  execstr = xmalloc (execlen);
+
+  snprintf (execstr, execlen, "%s %d", callback, current_index);
+  return parse_and_execute(execstr, NULL, 0);
+}
+
+static void
+do_chop(line)
+     char * line;
+{
+  int length;
+
+  length = strlen (line);
+  if (length && line[length-1] == '\n') 
+    line[length-1] = '\0';
+}
+
+static int
+mapfile (fd, line_count_goal, origin, nskip, callback_quantum, callback, array_name, flags)
+     int fd;
+     long line_count_goal, origin, nskip, callback_quantum;
+     char *callback, *array_name;
+     int flags;
+{
+  char *line;
+  size_t line_length;
+  unsigned int array_index, line_count;
+  SHELL_VAR *entry;
+  int unbuffered_read;
+  
+  line = NULL;
+  line_length = 0;
+  unbuffered_read = 0;
+
+  /* The following check should be done before reading any lines.  Doing it
+     here allows us to call bind_array_element instead of bind_array_variable
+     and skip the variable lookup on every call. */
+  entry = find_or_make_array_variable (array_name, 1);
+  if (entry == 0)
+    return (EXECUTION_FAILURE);
+  if (flags & MAPF_CLEARARRAY)
+    array_flush (array_cell (entry));
+
+#ifndef __CYGWIN__
+  unbuffered_read = (lseek (fd, 0L, SEEK_CUR) < 0) && (errno == ESPIPE);
+#else
+  unbuffered_read = 1;
+#endif
+
+  /* Skip any lines at beginning of file? */
+  for (line_count = 0; line_count < nskip; line_count++)
+    zgetline(fd, &line, &line_length, unbuffered_read);
+  line = 0;
+  line_length = 0;    
+
+  /* Reset the buffer for bash own stream */
+  for (array_index = origin, line_count = 0; 
+       zgetline(fd, &line, &line_length, unbuffered_read) != -1;
+       array_index++, line_count++) 
+    {
+      /* Have we exceeded # of lines to store? */
+      if (line_count_goal != 0 && line_count >= line_count_goal) 
+	break;
+
+      /* Remove trailing newlines? */
+      if (flags & MAPF_CHOP)
+	do_chop (line);
+	  
+      /* Has a callback been registered and if so is it time to call it? */
+      if (callback && line_count && (line_count % callback_quantum) == 0) 
+	{
+	  run_callback (callback, array_index);
+
+	  /* Reset the buffer for bash own stream. */
+	  if (unbuffered_read == 0)
+	    zsyncfd (fd);
+	}
+
+      bind_array_element (entry, array_index, line, 0);
+    }
+
+  xfree (line);
+
+  if (unbuffered_read == 0)
+    zsyncfd (fd);
+
+  return EXECUTION_SUCCESS;
+}
+
+int
+mapfile_builtin (list)
+     WORD_LIST *list;
+{
+  int opt, code, fd, clear_array, flags;
+  intmax_t intval;
+  long lines, origin, nskip, callback_quantum;
+  char *array_name, *callback;
+
+  clear_array = 1;
+  fd = 0;
+  lines = origin = nskip = 0;
+  flags = MAPF_CLEARARRAY;
+  callback_quantum = DEFAULT_QUANTUM;
+  callback = 0;
+
+  reset_internal_getopt ();
+  while ((opt = internal_getopt (list, "u:n:O:tC:c:s:")) != -1)
+    {
+      switch (opt)
+	{
+	case 'u':
+	  code = legal_number (list_optarg, &intval);
+	  if (code == 0 || intval < 0 || intval != (int)intval)
+	    {
+	      builtin_error (_("%s: invalid file descriptor specification"), list_optarg);
+	      return (EXECUTION_FAILURE);
+	    }
+	  else
+	    fd = intval;
+
+	  if (sh_validfd (fd) == 0)
+	    {
+	      builtin_error (_("%d: invalid file descriptor: %s"), fd, strerror (errno));
+	      return (EXECUTION_FAILURE);
+	    }
+	  break;	  
+
+	case 'n':
+	  code = legal_number (list_optarg, &intval);
+	  if (code == 0 || intval < 0 || intval != (unsigned)intval)
+	    {
+	      builtin_error (_("%s: invalid line count"), list_optarg);
+	      return (EXECUTION_FAILURE);
+	    }
+	  else
+	    lines = intval;
+	  break;
+
+	case 'O':
+	  code = legal_number (list_optarg, &intval);
+	  if (code == 0 || intval < 0 || intval != (unsigned)intval)
+	    {
+	      builtin_error (_("%s: invalid array origin"), list_optarg);
+	      return (EXECUTION_FAILURE);
+	    }
+	  else
+	    origin = intval;
+	  flags &= ~MAPF_CLEARARRAY;
+	  break;
+	case 't':
+	  flags |= MAPF_CHOP;
+	  break;
+	case 'C':
+	  callback = list_optarg;
+	  break;
+	case 'c':
+	  code = legal_number (list_optarg, &intval);
+	  if (code == 0 || intval < 0 || intval != (unsigned)intval)
+	    {
+	      builtin_error (_("%s: invalid callback quantum"), list_optarg);
+	      return (EXECUTION_FAILURE);
+	    }
+	  else
+	    callback_quantum = intval;
+	  break;
+	case 's':
+	  code = legal_number (list_optarg, &intval);
+	  if (code == 0 || intval < 0 || intval != (unsigned)intval)
+	    {
+	      builtin_error (_("%s: invalid line count"), list_optarg);
+	      return (EXECUTION_FAILURE);
+	    }
+	  else
+	    nskip = intval;
+	  break;
+	default:
+	  builtin_usage ();
+	  return (EX_USAGE);
+	}
+    }
+  list = loptend;
+
+  if (list == 0) 
+    array_name = DEFAULT_ARRAY_NAME;
+  else if (list->word == 0 || list->word->word == 0)
+    {
+      builtin_error ("internal error: getting variable name");
+      return (EXECUTION_FAILURE);
+    }
+  else if (list->word->word[0] == '\0')
+    {
+      builtin_error (_("empty array variable name"));
+      return (EX_USAGE);
+    } 
+  else
+    array_name = list->word->word;
+  
+  if (legal_identifier (array_name) == 0 && valid_array_reference (array_name) == 0)
+    {
+      sh_invalidid (array_name);
+      return (EXECUTION_FAILURE);
+    }
+
+  return mapfile (fd, lines, origin, nskip, callback_quantum, callback, array_name, flags);
+}
+
+#else
+
+int
+mapfile_builtin (list)
+     WORD_LIST *list;
+{
+  builtin_error (_("array variable support required"));
+  return (EXECUTION_FAILURE);
+}
+
+#endif  /* ARRAY_VARS */

builtins/printf.def

@@ -41,6 +41,10 @@ and printf(3), printf interprets:
 
   %b	expand backslash escape sequences in the corresponding argument
   %q	quote the argument in a way that can be reused as shell input
+
+Exit Status:
+Returns success unless an invalid option is given or a write or assignment
+error occurs.
 $END
 
 #include <config.h>

builtins/printf.def~

@@ -175,8 +175,7 @@ static int printstr __P((char *, char *, int, int, int));
 static int tescape __P((char *, char *, int *));
 static char *bexpand __P((char *, int, int *, int *));
 static char *vbadd __P((char *, int));
-static int vbprintf __P((const char *, ...))
- __attribute__((__format__ (printf, 1, 2)));
+static int vbprintf __P((const char *, ...)) __attribute__((__format__ (printf, 1, 2)));
 static char *mklong __P((char *, char *, size_t));
 static int getchr __P((void));
 static char *getstr __P((void));

builtins/pushd.def

@@ -25,6 +25,8 @@ $BUILTIN pushd
 $FUNCTION pushd_builtin
 $DEPENDS_ON PUSHD_AND_POPD
 $SHORT_DOC pushd [-n] [+N | -N | dir]
+Add directories to stack.
+
 Adds a directory to the top of the directory stack, or rotates
 the stack, making the new top of the stack the current working
 directory.  With no arguments, exchanges the top two directories.
@@ -46,12 +48,18 @@ Arguments:
 	new current working directory.
 
 The `dirs' builtin displays the directory stack.
+
+Exit Status:
+Returns success unless an invalid argument is supplied or the directory
+change fails.
 $END
 
 $BUILTIN popd
 $FUNCTION popd_builtin
 $DEPENDS_ON PUSHD_AND_POPD
 $SHORT_DOC popd [-n] [+N | -N]
+Remove directories from stack.
+
 Removes entries from the directory stack.  With no arguments, removes
 the top directory from the stack, and changes to the new top directory.
 
@@ -69,12 +77,18 @@ Arguments:
 	removes the last directory, `popd -1' the next to last.
 
 The `dirs' builtin displays the directory stack.
+
+Exit Status:
+Returns success unless an invalid argument is supplied or the directory
+change fails.
 $END
 
 $BUILTIN dirs
 $FUNCTION dirs_builtin
 $DEPENDS_ON PUSHD_AND_POPD
 $SHORT_DOC dirs [-clpv] [+N] [-N]
+Display directory stack.
+
 Display the list of currently remembered directories.  Directories
 find their way onto the list with the `pushd' command; you can get
 back up through the list with the `popd' command.
@@ -93,6 +107,9 @@ Arguments:
 
   -N	Displays the Nth entry counting from the right of the list shown by
 	dirs when invoked without options, starting with zero.
+
+Exit Status:
+Returns success unless an invalid option is supplied or an error occurs.
 $END
 
 #include <config.h>

builtins/pushd.def~

@@ -25,6 +25,8 @@ $BUILTIN pushd
 $FUNCTION pushd_builtin
 $DEPENDS_ON PUSHD_AND_POPD
 $SHORT_DOC pushd [-n] [+N | -N | dir]
+Add directories to stack.
+
 Adds a directory to the top of the directory stack, or rotates
 the stack, making the new top of the stack the current working
 directory.  With no arguments, exchanges the top two directories.
@@ -52,6 +54,8 @@ $BUILTIN popd
 $FUNCTION popd_builtin
 $DEPENDS_ON PUSHD_AND_POPD
 $SHORT_DOC popd [-n] [+N | -N]
+Remove directories from stack.
+
 Removes entries from the directory stack.  With no arguments, removes
 the top directory from the stack, and changes to the new top directory.
 
@@ -75,6 +79,8 @@ $BUILTIN dirs
 $FUNCTION dirs_builtin
 $DEPENDS_ON PUSHD_AND_POPD
 $SHORT_DOC dirs [-clpv] [+N] [-N]
+Display directory stack.
+
 Display the list of currently remembered directories.  Directories
 find their way onto the list with the `pushd' command; you can get
 back up through the list with the `popd' command.
@@ -711,22 +717,23 @@ N_("Adds a directory to the top of the directory stack, or rotates\n\
 };
 
 char * const popd_doc[] = {
-N_("Removes entries from the directory stack.  With no arguments,\n\
-    removes the top directory from the stack, and cd's to the new\n\
-    top directory.\n\
+N_("Removes entries from the directory stack.  With no arguments, removes\n\
+    the top directory from the stack, and changes to the new top directory.\n\
     \n\
-    -n  Suppresses the normal change of directory when removing directories\n\
-        from the stack, so only the stack is manipulated.\n\
+    Options:\n\
+      -n	Suppresses the normal change of directory when removing\n\
+    	directories from the stack, so only the stack is manipulated.\n\
     \n\
-    +N  Removes the Nth entry counting from the left of the list\n\
-        shown by `dirs', starting with zero.  For example: `popd +0'\n\
-        removes the first directory, `popd +1' the second.\n\
+    Arguments:\n\
+      +N	Removes the Nth entry counting from the left of the list\n\
+    	shown by `dirs', starting with zero.  For example: `popd +0'\n\
+    	removes the first directory, `popd +1' the second.\n\
     \n\
-    -N  Removes the Nth entry counting from the right of the list\n\
-        shown by `dirs', starting with zero.  For example: `popd -0'\n\
-        removes the last directory, `popd -1' the next to last.\n\
+      -N	Removes the Nth entry counting from the right of the list\n\
+    	shown by `dirs', starting with zero.  For example: `popd -0'\n\
+    	removes the last directory, `popd -1' the next to last.\n\
     \n\
-    You can see the directory stack with the `dirs' command."),
+    The `dirs' builtin displays the directory stack."),
   (char *)NULL
 };
 

builtins/read.def

@@ -53,6 +53,7 @@ Options:
 		variable is the default timeout.
   -u fd		read from file descriptor FD instead of the standard input
 
+Exit Status:
 The return code is zero, unless end-of-file is encountered, read times out,
 or an invalid file descriptor is supplied as the argument to -u.
 $END

builtins/read.def~

@@ -23,7 +23,7 @@ $PRODUCES read.c
 
 $BUILTIN read
 $FUNCTION read_builtin
-$SHORT_DOC read [-ers] [-a array] [-d delim] [-n nchars] [-p prompt] [-t timeout] [-u fd] [name ...]
+$SHORT_DOC read [-ers] [-a array] [-d delim] [-i text] [-n nchars] [-p prompt] [-t timeout] [-u fd] [name ...]
 Read a line from the standard input and split it into fields.
 
 Reads a single line from the standard input, or from file descriptor FD
@@ -41,6 +41,7 @@ Options:
   -d delim	continue until the first character of DELIM is read, rather
 		than newline
   -e		use Readline to obtain the line in an interactive shell
+  -i text	Use TEXT as the initial text for Readline
   -n nchars	return after reading NCHARS characters rather than waiting
 		for a newline
   -p prompt	output the string PROMPT without a trailing newline before
@@ -104,7 +105,8 @@ struct ttsave
 
 #if defined (READLINE)
 static void reset_attempted_completion_function __P((char *));
-static char *edit_line __P((char *));
+static int set_itext __P((void));
+static char *edit_line __P((char *, char *));
 static void set_eol_delim __P((int));
 static void reset_eol_delim __P((char *));
 #endif
@@ -162,7 +164,7 @@ read_builtin (list)
   WORD_LIST *alist;
 #endif
 #if defined (READLINE)
-  char *rlbuf;
+  char *rlbuf, *itext;
   int rlind;
 #endif
 
@@ -183,6 +185,7 @@ read_builtin (list)
 #if defined (READLINE)
   USE_VAR(rlbuf);
   USE_VAR(rlind);
+  USE_VAR(itext);
 #endif
   USE_VAR(list);
   USE_VAR(ps2);
@@ -194,7 +197,7 @@ read_builtin (list)
   fd = 0;		/* file descriptor to read from */
 
 #if defined (READLINE)
-  rlbuf = (char *)0;
+  rlbuf = itext = (char *)0;
   rlind = 0;
 #endif
 
@@ -203,7 +206,7 @@ read_builtin (list)
   delim = '\n';		/* read until newline */
 
   reset_internal_getopt ();
-  while ((opt = internal_getopt (list, "ersa:d:n:p:t:u:")) != -1)
+  while ((opt = internal_getopt (list, "ersa:d:i:n:p:t:u:")) != -1)
     {
       switch (opt)
 	{
@@ -219,6 +222,11 @@ read_builtin (list)
 	case 'e':
 #if defined (READLINE)
 	  edit = 1;
+#endif
+	  break;
+	case 'i':
+#if defined (READLINE)
+	  itext = list_optarg;
 #endif
 	  break;
 #if defined (ARRAY_VARS)
@@ -320,6 +328,9 @@ read_builtin (list)
   if ((prompt || edit || silent) && input_is_tty == 0)
     {
       prompt = (char *)NULL;
+#if defined (READLINE)
+      itext = (char *)NULL;
+#endif
       edit = silent = 0;
     }
 
@@ -442,7 +453,7 @@ read_builtin (list)
 	    }
 	  if (rlbuf == 0)
 	    {
-	      rlbuf = edit_line (prompt ? prompt : "");
+	      rlbuf = edit_line (prompt ? prompt : "", itext);
 	      rlind = 0;
 	    }
 	  if (rlbuf == 0)
@@ -831,6 +842,8 @@ ttyrestore (ttp)
 
 #if defined (READLINE)
 static rl_completion_func_t *old_attempted_completion_function = 0;
+static rl_hook_func_t *old_startup_hook;
+static char *deftext;
 
 static void
 reset_attempted_completion_function (cp)
@@ -840,9 +853,28 @@ reset_attempted_completion_function (cp)
     rl_attempted_completion_function = old_attempted_completion_function;
 }
 
+static int
+set_itext ()
+{
+  int r1, r2;
+
+  r1 = r2 = 0;
+  if (old_startup_hook)
+    r1 = (*old_startup_hook) ();
+  if (deftext)
+    {
+      r2 = rl_insert_text (deftext);
+      deftext = (char *)NULL;
+      rl_startup_hook = old_startup_hook;
+      old_startup_hook = (rl_hook_func_t *)NULL;
+    }
+  return (r1 || r2);
+}
+
 static char *
-edit_line (p)
+edit_line (p, itext)
      char *p;
+     char *itext;
 {
   char *ret;
   int len;
@@ -852,6 +884,12 @@ edit_line (p)
 
   old_attempted_completion_function = rl_attempted_completion_function;
   rl_attempted_completion_function = (rl_completion_func_t *)NULL;
+  if (itext)
+    {
+      old_startup_hook = rl_startup_hook;
+      rl_startup_hook = set_itext;
+      deftext = itext;
+    }
   ret = readline (p);
   rl_attempted_completion_function = old_attempted_completion_function;
   old_attempted_completion_function = (rl_completion_func_t *)NULL;

builtins/reserved.def

@@ -22,15 +22,22 @@ Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA.
 
 $BUILTIN for
 $SHORT_DOC for NAME [in WORDS ... ] ; do COMMANDS; done
+Execute commands for each member in a list.
+
 The `for' loop executes a sequence of commands for each member in a
 list of items.  If `in WORDS ...;' is not present, then `in "$@"' is
 assumed.  For each element in WORDS, NAME is set to that element, and
 the COMMANDS are executed.
+
+Exit Status:
+Returns the status of the last command executed.
 $END
 
 $BUILTIN for ((
 $DOCNAME arith_for
 $SHORT_DOC for (( exp1; exp2; exp3 )); do COMMANDS; done
+Arithmetic for loop.
+
 Equivalent to
 	(( EXP1 ))
 	while (( EXP2 )); do
@@ -39,10 +46,15 @@ Equivalent to
 	done
 EXP1, EXP2, and EXP3 are arithmetic expressions.  If any expression is
 omitted, it behaves as if it evaluates to 1.
+
+Exit Status:
+Returns the status of the last command executed.
 $END
 
 $BUILTIN select
 $SHORT_DOC select NAME [in WORDS ... ;] do COMMANDS; done
+Select words from a list and execute commands..
+
 The WORDS are expanded, generating a list of words.  The
 set of expanded words is printed on the standard error, each
 preceded by a number.  If `in WORDS' is not present, `in "$@"'
@@ -54,28 +66,42 @@ redisplayed.  If EOF is read, the command completes.  Any other
 value read causes NAME to be set to null.  The line read is saved
 in the variable REPLY.  COMMANDS are executed after each selection
 until a break command is executed.
+
+Exit Status:
+Returns the status of the last command executed.
 $END
 
 $BUILTIN time
 $SHORT_DOC time [-p] pipeline
+Report time consumed by pipeline's execution.
+
 Execute PIPELINE and print a summary of the real time, user CPU time,
 and system CPU time spent executing PIPELINE when it terminates.
 
 Options:
   -p	print the timing summary in the portable Posix format
 
-The value of the TIMEFORMAT variable is used as the output format.  The
-return status is the return status of PIPELINE.
+The value of the TIMEFORMAT variable is used as the output format.
+
+Exit Status:
+The return status is the return status of PIPELINE.
 $END
 
 $BUILTIN case
 $SHORT_DOC case WORD in [PATTERN [| PATTERN]...) COMMANDS ;;]... esac
+Execute commands based on pattern matching.
+
 Selectively execute COMMANDS based upon WORD matching PATTERN.  The
 `|' is used to separate multiple patterns.
+
+Exit Status:
+Returns the status of the last command executed.
 $END
 
 $BUILTIN if
 $SHORT_DOC if COMMANDS; then COMMANDS; [ elif COMMANDS; then COMMANDS; ]... [ else COMMANDS; ] fi
+Execute commands based on conditional.
+
 The `if COMMANDS' list is executed.  If its exit status is zero, then the
 `then COMMANDS' list is executed.  Otherwise, each `elif COMMANDS' list is
 executed in turn, and if its exit status is zero, the corresponding
@@ -83,55 +109,90 @@ executed in turn, and if its exit status is zero, the corresponding
 the `else COMMANDS' list is executed, if present.  The exit status of the
 entire construct is the exit status of the last command executed, or zero
 if no condition tested true.
+
+Exit Status:
+Returns the status of the last command executed.
 $END
 
 $BUILTIN while
 $SHORT_DOC while COMMANDS; do COMMANDS; done
+Execute commands as long as a test succeeds.
+
 Expand and execute COMMANDS as long as the final command in the
 `while' COMMANDS has an exit status of zero.
+
+Exit Status:
+Returns the status of the last command executed.
 $END
 
 $BUILTIN until
 $SHORT_DOC until COMMANDS; do COMMANDS; done
+Execute commands as long as a test does not succeed.
+
 Expand and execute COMMANDS as long as the final command in the
 `until' COMMANDS has an exit status which is not zero.
+
+Exit Status:
+Returns the status of the last command executed.
 $END
 
 $BUILTIN function
 $SHORT_DOC function name { COMMANDS ; } or name () { COMMANDS ; }
+Define shell function.
+
 Create a shell function named NAME.  When invoked as a simple command,
 NAME runs COMMANDs in the calling shell's context.  When NAME is invoked,
 the arguments are passed to the function as $1...$n, and the function's
 name is in $FUNCNAME.
+
+Exit Status:
+Returns success unless NAME is readonly.
 $END
 
 $BUILTIN { ... }
 $DOCNAME grouping_braces
 $SHORT_DOC { COMMANDS ; }
+Group commands as a unit.
+
 Run a set of commands in a group.  This is one way to redirect an
 entire set of commands.
+
+Exit Status:
+Returns the status of the last command executed.
 $END
 
 $BUILTIN %
 $DOCNAME fg_percent
 $SHORT_DOC job_spec [&]
+Resume job in foreground.
+
 Equivalent to the JOB_SPEC argument to the `fg' command.  Resume a
 stopped or background job.  JOB_SPEC can specify either a job name
 or a job number.  Following JOB_SPEC with a `&' places the job in
 the background, as if the job specification had been supplied as an
 argument to `bg'.
+
+Exit Status:
+Returns the status of the resumed job.
 $END
 
 $BUILTIN (( ... ))
 $DOCNAME arith
 $SHORT_DOC (( expression ))
+Evaluate arithmetic expression.
+
 The EXPRESSION is evaluated according to the rules for arithmetic
 evaluation.  Equivalent to "let EXPRESSION".
+
+Exit Status:
+Returns 1 if EXPRESSION evaluates to 0; returns 0 otherwise.
 $END
 
 $BUILTIN [[ ... ]]
 $DOCNAME conditional
 $SHORT_DOC [[ expression ]]
+Execute conditional command.
+
 Returns a status of 0 or 1 depending on the evaluation of the conditional
 expression EXPRESSION.  Expressions are composed of the same primaries used
 by the `test' builtin, and may be combined using the following operators:
@@ -148,11 +209,16 @@ is matched as a regular expression.
 
 The && and || operators do not evaluate EXPR2 if EXPR1 is sufficient to
 determine the expression's value.
+
+Exit Status:
+0 or 1 depending on value of EXPRESSION.
 $END
 
 $BUILTIN variables
 $DOCNAME variable_help
 $SHORT_DOC variables - Names and meanings of some shell variables
+Common shell variable names and usage.
+
 BASH_VERSION	Version information for this Bash.
 CDPATH	A colon-separated list of directories to search
 		for directories given as arguments to `cd'.

builtins/reserved.def~

@@ -22,6 +22,8 @@ Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA.
 
 $BUILTIN for
 $SHORT_DOC for NAME [in WORDS ... ] ; do COMMANDS; done
+Execute commands for each member in a list.
+
 The `for' loop executes a sequence of commands for each member in a
 list of items.  If `in WORDS ...;' is not present, then `in "$@"' is
 assumed.  For each element in WORDS, NAME is set to that element, and
@@ -31,6 +33,8 @@ $END
 $BUILTIN for ((
 $DOCNAME arith_for
 $SHORT_DOC for (( exp1; exp2; exp3 )); do COMMANDS; done
+Arithmetic for loop.
+
 Equivalent to
 	(( EXP1 ))
 	while (( EXP2 )); do
@@ -58,6 +62,8 @@ $END
 
 $BUILTIN time
 $SHORT_DOC time [-p] pipeline
+Report time consumed by pipeline's execution.
+
 Execute PIPELINE and print a summary of the real time, user CPU time,
 and system CPU time spent executing PIPELINE when it terminates.
 
@@ -70,12 +76,16 @@ $END
 
 $BUILTIN case
 $SHORT_DOC case WORD in [PATTERN [| PATTERN]...) COMMANDS ;;]... esac
+Execute commands based on pattern matching.
+
 Selectively execute COMMANDS based upon WORD matching PATTERN.  The
 `|' is used to separate multiple patterns.
 $END
 
 $BUILTIN if
 $SHORT_DOC if COMMANDS; then COMMANDS; [ elif COMMANDS; then COMMANDS; ]... [ else COMMANDS; ] fi
+Execute commands based on conditional.
+
 The `if COMMANDS' list is executed.  If its exit status is zero, then the
 `then COMMANDS' list is executed.  Otherwise, each `elif COMMANDS' list is
 executed in turn, and if its exit status is zero, the corresponding
@@ -87,18 +97,24 @@ $END
 
 $BUILTIN while
 $SHORT_DOC while COMMANDS; do COMMANDS; done
+Execute commands as long as a test succeeds.
+
 Expand and execute COMMANDS as long as the final command in the
 `while' COMMANDS has an exit status of zero.
 $END
 
 $BUILTIN until
 $SHORT_DOC until COMMANDS; do COMMANDS; done
+Execute commands as long as a test does not succeed.
+
 Expand and execute COMMANDS as long as the final command in the
 `until' COMMANDS has an exit status which is not zero.
 $END
 
 $BUILTIN function
 $SHORT_DOC function name { COMMANDS ; } or name () { COMMANDS ; }
+Define shell function.
+
 Create a shell function named NAME.  When invoked as a simple command,
 NAME runs COMMANDs in the calling shell's context.  When NAME is invoked,
 the arguments are passed to the function as $1...$n, and the function's
@@ -108,6 +124,8 @@ $END
 $BUILTIN { ... }
 $DOCNAME grouping_braces
 $SHORT_DOC { COMMANDS ; }
+Group commands as a unit.
+
 Run a set of commands in a group.  This is one way to redirect an
 entire set of commands.
 $END
@@ -115,6 +133,8 @@ $END
 $BUILTIN %
 $DOCNAME fg_percent
 $SHORT_DOC job_spec [&]
+Resume job in foreground.
+
 Equivalent to the JOB_SPEC argument to the `fg' command.  Resume a
 stopped or background job.  JOB_SPEC can specify either a job name
 or a job number.  Following JOB_SPEC with a `&' places the job in
@@ -125,6 +145,8 @@ $END
 $BUILTIN (( ... ))
 $DOCNAME arith
 $SHORT_DOC (( expression ))
+Evaluate arithmetic expression.
+
 The EXPRESSION is evaluated according to the rules for arithmetic
 evaluation.  Equivalent to "let EXPRESSION".
 $END
@@ -132,6 +154,8 @@ $END
 $BUILTIN [[ ... ]]
 $DOCNAME conditional
 $SHORT_DOC [[ expression ]]
+Execute conditional command.
+
 Returns a status of 0 or 1 depending on the evaluation of the conditional
 expression EXPRESSION.  Expressions are composed of the same primaries used
 by the `test' builtin, and may be combined using the following operators:
@@ -141,10 +165,10 @@ by the `test' builtin, and may be combined using the following operators:
   EXPR1 && EXPR2	True if both EXPR1 and EXPR2 are true; else false
   EXPR1 || EXPR2	True if either EXPR1 or EXPR2 is true; else false
 
-When the `==' and `!=' operators are used, the string to the right of the
-operator is used as a pattern and pattern matching is performed.  When
-the `=~' operator is used, the string to the right of the operator is
-matched as a regular expression.
+When the `==' and `!=' operators are used, the string to the right of
+the operator is used as a pattern and pattern matching is performed.
+When the `=~' operator is used, the string to the right of the operator
+is matched as a regular expression.
 
 The && and || operators do not evaluate EXPR2 if EXPR1 is sufficient to
 determine the expression's value.
@@ -153,6 +177,8 @@ $END
 $BUILTIN variables
 $DOCNAME variable_help
 $SHORT_DOC variables - Names and meanings of some shell variables
+Common shell variable names and usage.
+
 BASH_VERSION	Version information for this Bash.
 CDPATH	A colon-separated list of directories to search
 		for directories given as arguments to `cd'.

builtins/return.def

@@ -1,7 +1,7 @@
 This file is return.def, from which is created return.c.
 It implements the builtin "return" in Bash.
 
-Copyright (C) 1987-2003 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -25,9 +25,14 @@ $BUILTIN return
 
 $FUNCTION return_builtin
 $SHORT_DOC return [n]
+Return from a shell function.
+
 Causes a function or sourced script to exit with the return value
 specified by N.  If N is omitted, the return status is that of the
 last command executed within the function or script.
+
+Exit Status:
+Returns N, or failure if the shell is not executing a function or script.
 $END
 
 #include <config.h>

builtins/return.def~

@@ -1,7 +1,7 @@
 This file is return.def, from which is created return.c.
 It implements the builtin "return" in Bash.
 
-Copyright (C) 1987-2003 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -25,8 +25,11 @@ $BUILTIN return
 
 $FUNCTION return_builtin
 $SHORT_DOC return [n]
-Causes a function to exit with the return value specified by N.  If N
-is omitted, the return status is that of the last command.
+Return from a shell function.
+
+Causes a function or sourced script to exit with the return value
+specified by N.  If N is omitted, the return status is that of the
+last command executed within the function or script.
 $END
 
 #include <config.h>

builtins/set.def

@@ -61,8 +61,10 @@ extern int no_line_editing;
 $BUILTIN set
 $FUNCTION set_builtin
 $SHORT_DOC set [--abefhkmnptuvxBCHP] [-o option-name] [arg ...]
-Changes the value of shell attributes and positional parameters, or
-displays the names and values of shell variables.
+Set or unset values of shell options and positional parameters.
+
+Change the value of shell attributes and positional parameters, or
+display the names and values of shell variables.
 
 Options:
   -a  Mark variables which are modified or created for export.
@@ -145,6 +147,9 @@ flags can also be used upon invocation of the shell.  The current
 set of flags may be found in $-.  The remaining n ARGs are positional
 parameters and are assigned, in order, to $1, $2, .. $n.  If no
 ARGs are given, all shell variables are printed.
+
+Exit Status:
+Returns success unless an invalid option is given.
 $END
 
 typedef int setopt_set_func_t __P((int, char *));
@@ -193,7 +198,7 @@ const struct {
   { "histexpand", 'H', (int *)NULL, (setopt_set_func_t *)NULL, (setopt_get_func_t *)NULL  },
 #endif /* BANG_HISTORY */
 #if defined (HISTORY)
-  { "history",   '\0', &remember_on_history, bash_set_history, (setopt_get_func_t *)NULL },
+  { "history",   '\0', &enable_history_list, bash_set_history, (setopt_get_func_t *)NULL },
 #endif
   { "ignoreeof", '\0', &ignoreeof, set_ignoreeof, (setopt_get_func_t *)NULL },
   { "interactive-comments", '\0', &interactive_comments, (setopt_set_func_t *)NULL, (setopt_get_func_t *)NULL },
@@ -385,13 +390,17 @@ bash_set_history (on_or_off, option_name)
 {
   if (on_or_off == FLAG_ON)
     {
+      enable_history_list = 1;
       bash_history_enable ();
       if (history_lines_this_session == 0)
 	load_history ();
     }
   else
-    bash_history_disable ();
-  return (1 - remember_on_history);
+    {
+      enable_history_list = 0;
+      bash_history_disable ();
+    }
+  return (1 - enable_history_list);
 }
 #endif
 
@@ -569,7 +578,7 @@ void
 reset_shell_options ()
 {
 #if defined (HISTORY)
-  remember_on_history = 1;
+  remember_on_history = enable_history_list = 1;
 #endif
   ignoreeof = 0;
 }
@@ -708,6 +717,8 @@ set_builtin (list)
 $BUILTIN unset
 $FUNCTION unset_builtin
 $SHORT_DOC unset [-f] [-v] [name ...]
+Unset values and attributes of shell variables and functions.
+
 For each NAME, remove the corresponding variable or function.
 
 Options:
@@ -718,6 +729,9 @@ Without options, unset first tries to unset a variable, and if that fails,
 tries to unset a function.
 
 Some variables cannot be unset; also see `readonly'.
+
+Exit Status:
+Returns success unless an invalid option is given or a NAME is read-only.
 $END
 
 #define NEXT_VARIABLE()	any_failed++; list = list->next; continue;

builtins/set.def~

@@ -61,8 +61,10 @@ extern int no_line_editing;
 $BUILTIN set
 $FUNCTION set_builtin
 $SHORT_DOC set [--abefhkmnptuvxBCHP] [-o option-name] [arg ...]
-Changes the value of shell attributes and positional parameters, or
-displays the names and values of shell variables.
+Set or unset values of shell options and positional parameters.
+
+Change the value of shell attributes and positional parameters, or
+display the names and values of shell variables.
 
 Options:
   -a  Mark variables which are modified or created for export.
@@ -108,7 +110,7 @@ Options:
                        the last command to exit with a non-zero status,
                        or zero if no command exited with a non-zero status
           posix        change the behavior of bash where the default
-                       operation differs from the 1003.2 standard to
+                       operation differs from the Posix standard to
                        match the standard
           privileged   same as -p
           verbose      same as -v
@@ -193,7 +195,7 @@ const struct {
   { "histexpand", 'H', (int *)NULL, (setopt_set_func_t *)NULL, (setopt_get_func_t *)NULL  },
 #endif /* BANG_HISTORY */
 #if defined (HISTORY)
-  { "history",   '\0', &remember_on_history, bash_set_history, (setopt_get_func_t *)NULL },
+  { "history",   '\0', &enable_history_list, bash_set_history, (setopt_get_func_t *)NULL },
 #endif
   { "ignoreeof", '\0', &ignoreeof, set_ignoreeof, (setopt_get_func_t *)NULL },
   { "interactive-comments", '\0', &interactive_comments, (setopt_set_func_t *)NULL, (setopt_get_func_t *)NULL },
@@ -385,13 +387,17 @@ bash_set_history (on_or_off, option_name)
 {
   if (on_or_off == FLAG_ON)
     {
+      enable_history_list = 1;
       bash_history_enable ();
       if (history_lines_this_session == 0)
 	load_history ();
     }
   else
-    bash_history_disable ();
-  return (1 - remember_on_history);
+    {
+      enable_history_list = 0;
+      bash_history_disable ();
+    }
+  return (1 - enable_history_list);
 }
 #endif
 
@@ -569,7 +575,7 @@ void
 reset_shell_options ()
 {
 #if defined (HISTORY)
-  remember_on_history = 1;
+  remember_on_history = enable_history_list = 1;
 #endif
   ignoreeof = 0;
 }
@@ -708,6 +714,8 @@ set_builtin (list)
 $BUILTIN unset
 $FUNCTION unset_builtin
 $SHORT_DOC unset [-f] [-v] [name ...]
+Unset values and attributes of shell variables and functions.
+
 For each NAME, remove the corresponding variable or function.
 
 Options:

builtins/setattr.def

@@ -53,6 +53,8 @@ extern int declare_builtin __P((WORD_LIST *));
 $BUILTIN export
 $FUNCTION export_builtin
 $SHORT_DOC export [-fn] [name[=value] ...] or export -p
+Set export attribute for shell variables.
+
 Marks each NAME for automatic export to the environment of subsequently
 executed commands.  If VALUE is supplied, assign VALUE before exporting.
 
@@ -62,6 +64,9 @@ Options:
   -p	display a list of all exported variables and functions
 
 An argument of `--' disables further option processing.
+
+Exit Status:
+Returns success unless an invalid option is given or NAME is invalid.
 $END
 
 /* For each variable name in LIST, make that variable appear in the
@@ -79,6 +84,8 @@ export_builtin (list)
 $BUILTIN readonly
 $FUNCTION readonly_builtin
 $SHORT_DOC readonly [-af] [name[=value] ...] or readonly -p
+Mark shell variables as unchangeable.
+
 Mark each NAME as read-only; the values of these NAMEs may not be
 changed by subsequent assignment.  If VALUE is supplied, assign VALUE
 before marking as read-only.
@@ -89,6 +96,9 @@ Options:
   -p	display a list of all readonly variables and functions
 
 An argument of `--' disables further option processing.
+
+Exit Status:
+Returns success unless an invalid option is given or NAME is invalid.
 $END
 
 /* For each variable name in LIST, make that variable readonly.  Given an
@@ -323,7 +333,7 @@ show_var_attributes (var, pattr, nodefs)
      SHELL_VAR *var;
      int pattr, nodefs;
 {
-  char flags[8], *x;
+  char flags[16], *x;
   int i;
 
   i = 0;

builtins/setattr.def~

@@ -53,6 +53,8 @@ extern int declare_builtin __P((WORD_LIST *));
 $BUILTIN export
 $FUNCTION export_builtin
 $SHORT_DOC export [-fn] [name[=value] ...] or export -p
+Set export attribute for shell variables.
+
 Marks each NAME for automatic export to the environment of subsequently
 executed commands.  If VALUE is supplied, assign VALUE before exporting.
 
@@ -62,6 +64,9 @@ Options:
   -p	display a list of all exported variables and functions
 
 An argument of `--' disables further option processing.
+
+Exit Status:
+Returns success unless an invalid option is given or NAME is invalid.
 $END
 
 /* For each variable name in LIST, make that variable appear in the
@@ -79,6 +84,8 @@ export_builtin (list)
 $BUILTIN readonly
 $FUNCTION readonly_builtin
 $SHORT_DOC readonly [-af] [name[=value] ...] or readonly -p
+Mark shell variables as unchangeable.
+
 Mark each NAME as read-only; the values of these NAMEs may not be
 changed by subsequent assignment.  If VALUE is supplied, assign VALUE
 before marking as read-only.
@@ -89,6 +96,9 @@ Options:
   -p	display a list of all readonly variables and functions
 
 An argument of `--' disables further option processing.
+
+Exit Status:
+Returns success unless an invalid option is given or NAME is invalid.
 $END
 
 /* For each variable name in LIST, make that variable readonly.  Given an
@@ -294,7 +304,7 @@ int
 show_all_var_attributes (v, nodefs)
      int v, nodefs;
 {
-  SHELL_VAR **variable_list;
+  SHELL_VAR **variable_list, *var;
   int any_failed;
   register int i;
 

builtins/shift.def

@@ -39,8 +39,13 @@ $PRODUCES shift.c
 $BUILTIN shift
 $FUNCTION shift_builtin
 $SHORT_DOC shift [n]
+Shift positional parameters.
+
 Rename the positional parameters $N+1,$N+2 ... to $1,$2 ...  If N is
 not given, it is assumed to be 1.
+
+Exit Status:
+Returns success unless N is negative or greater than $#.
 $END
 
 int print_shift_error;

builtins/shift.def~

@@ -1,7 +1,7 @@
 This file is shift.def, from which is created shift.c.
 It implements the builtin "shift" in Bash.
 
-Copyright (C) 1987-2003 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -39,8 +39,10 @@ $PRODUCES shift.c
 $BUILTIN shift
 $FUNCTION shift_builtin
 $SHORT_DOC shift [n]
-Rename the positional parameters $N+1 ... to $1 ...  If N is not
-given, it is assumed to be 1.
+Shift positional parameters.
+
+Rename the positional parameters $N+1,$N+2 ... to $1,$2 ...  If N is
+not given, it is assumed to be 1.
 $END
 
 int print_shift_error;

builtins/shopt.def

@@ -24,8 +24,11 @@ $PRODUCES shopt.c
 $BUILTIN shopt
 $FUNCTION shopt_builtin
 $SHORT_DOC shopt [-pqsu] [-o] [optname ...]
-Set and unset shell options.  Without any option arguments, list all
-shell options with an indication of whether or not each is set.
+Set and unset shell options.
+
+Change the setting of each shell option OPTNAME.  Without any option
+arguments, list all shell options with an indication of whether or not each
+is set. 
 
 Options:
   -o	restrict OPTNAMEs to those defined for use with `set -o'
@@ -34,7 +37,9 @@ Options:
   -s	enable (set) each OPTNAME
   -u	disable (unset) each OPTNAME
 
-The exit status indicates whether or not each OPTNAME is set.
+Exit Status:
+Returns success if OPTNAME is enabled; fails if an invalid option is
+given or OPTNAME is disabled.
 $END
 
 #include <config.h>
@@ -129,7 +134,9 @@ static struct {
   { "cdable_vars", &cdable_vars, (shopt_set_func_t *)NULL },
   { "cdspell", &cdspelling, (shopt_set_func_t *)NULL },
   { "checkhash", &check_hashed_filenames, (shopt_set_func_t *)NULL },
+#if defined (JOB_CONTROL)
   { "checkjobs", &check_jobs_at_exit, (shopt_set_func_t *)NULL },
+#endif
   { "checkwinsize", &check_window_size, (shopt_set_func_t *)NULL },
 #if defined (HISTORY)
   { "cmdhist", &command_oriented_history, (shopt_set_func_t *)NULL },

builtins/shopt.def~

@@ -24,8 +24,11 @@ $PRODUCES shopt.c
 $BUILTIN shopt
 $FUNCTION shopt_builtin
 $SHORT_DOC shopt [-pqsu] [-o] [optname ...]
-Set and unset shell options.  Without any option arguments, list all
-shell options with an indication of whether or not each is set.
+Set and unset shell options.
+
+Change the setting of each shell option OPTNAME.  Without any option
+arguments, list all shell options with an indication of whether or not each
+is set. 
 
 Options:
   -o	restrict OPTNAMEs to those defined for use with `set -o'
@@ -34,7 +37,9 @@ Options:
   -s	enable (set) each OPTNAME
   -u	disable (unset) each OPTNAME
 
-The exit status indicates whether or not each OPTNAME is set.
+Exit Status:
+Returns success if OPTNAME is enabled; fails if an invalid option is
+given or OPTNAME is disabled.
 $END
 
 #include <config.h>
@@ -116,6 +121,7 @@ static int set_restricted_shell __P((int));
 
 static int shopt_login_shell;
 static int shopt_compat31;
+static int shopt_compat32;
 
 typedef int shopt_set_func_t __P((int));
 
@@ -476,8 +482,13 @@ static int
 set_compatibility_level (mode)
      int mode;
 {
-  /* Need to change logic here if we add more compatibility levels */
-  shell_compatibility_level = shopt_compat31 ? 31 : DEFAULT_COMPAT_LEVEL;
+  /* Need to change logic here as we add more compatibility levels */
+  if (shopt_compat31)
+    shell_compatibility_level = 31;
+  else if (shopt_compat32)
+    shell_compatibility_level = 32;
+  else
+    shell_compatibility_level = DEFAULT_COMPAT_LEVEL;
   return 0;
 }
 

builtins/source.def

@@ -24,19 +24,32 @@ $PRODUCES source.c
 $BUILTIN source
 $FUNCTION source_builtin
 $SHORT_DOC source filename [arguments]
+Execute commands from a file in the current shell.
+
 Read and execute commands from FILENAME in the current shell.  The
 entries in $PATH are used to find the directory containing FILENAME.
 If any ARGUMENTS are supplied, they become the positional parameters
 when FILENAME is executed.
+
+Exit Status:
+Returns the status of the last command executed in FILENAME; fails if
+FILENAME cannot be read.
 $END
+
 $BUILTIN .
 $DOCNAME dot
 $FUNCTION source_builtin
 $SHORT_DOC . filename [arguments]
+Execute commands from a file in the current shell.
+
 Read and execute commands from FILENAME in the current shell.  The
 entries in $PATH are used to find the directory containing FILENAME.
 If any ARGUMENTS are supplied, they become the positional parameters
 when FILENAME is executed.
+
+Exit Status:
+Returns the status of the last command executed in FILENAME; fails if
+FILENAME cannot be read.
 $END
 
 #include <config.h>

builtins/source.def~

@@ -24,19 +24,23 @@ $PRODUCES source.c
 $BUILTIN source
 $FUNCTION source_builtin
 $SHORT_DOC source filename [arguments]
-Read and execute commands from FILENAME in the current shell.  The entries
-in $PATH are used to find the directory containing FILENAME.  If any
-ARGUMENTS are supplied, they become the positional parameters when
-FILENAME is executed.
+Execute commands from a file in the current shell.
+
+Read and execute commands from FILENAME in the current shell.  The
+entries in $PATH are used to find the directory containing FILENAME.
+If any ARGUMENTS are supplied, they become the positional parameters
+when FILENAME is executed.
 $END
 $BUILTIN .
 $DOCNAME dot
 $FUNCTION source_builtin
 $SHORT_DOC . filename [arguments]
-Read and execute commands from FILENAME in the current shell.  The entries
-in $PATH are used to find the directory containing FILENAME.  If any
-ARGUMENTS are supplied, they become the positional parameters when
-FILENAME is executed.
+Execute commands from a file in the current shell.
+
+Read and execute commands from FILENAME in the current shell.  The
+entries in $PATH are used to find the directory containing FILENAME.
+If any ARGUMENTS are supplied, they become the positional parameters
+when FILENAME is executed.
 $END
 
 #include <config.h>
@@ -67,6 +71,8 @@ $END
 extern int errno;
 #endif /* !errno */
 
+extern int posixly_correct;
+
 static void maybe_pop_dollar_vars __P((void));
 
 /* If non-zero, `.' uses $PATH to look up the script to be sourced. */
@@ -125,7 +131,12 @@ source_builtin (list)
 #endif
 
   filename = (char *)NULL;
-  if (source_uses_path)
+  /* XXX -- should this be absolute_pathname? */
+  if (posixly_correct && strchr (list->word->word, '/'))
+    filename = savestring (list->word->word);
+  else if (absolute_pathname (list->word->word))
+    filename = savestring (list->word->word);
+  else if (source_uses_path)
     filename = find_path_file (list->word->word);
   if (filename == 0)
     {

builtins/suspend.def

@@ -25,10 +25,15 @@ $BUILTIN suspend
 $DEPENDS_ON JOB_CONTROL
 $FUNCTION suspend_builtin
 $SHORT_DOC suspend [-f]
+Suspend shell execution.
+
 Suspend the execution of this shell until it receives a SIGCONT signal.
 
 Options:
   -f	force the suspend, even if the shell is a login shell
+
+Exit Status:
+Returns success unless job control is not enabled or an error occurs.
 $END
 
 #include <config.h>

builtins/suspend.def~

@@ -25,10 +25,11 @@ $BUILTIN suspend
 $DEPENDS_ON JOB_CONTROL
 $FUNCTION suspend_builtin
 $SHORT_DOC suspend [-f]
+Suspend shell execution.
+
 Suspend the execution of this shell until it receives a SIGCONT signal.
 
 Options:
-
   -f	force the suspend, even if the shell is a login shell
 $END
 

builtins/test.def

@@ -24,6 +24,8 @@ $PRODUCES test.c
 $BUILTIN test
 $FUNCTION test_builtin
 $SHORT_DOC test [expr]
+Evaluate conditional expression.
+
 Exits with a status of 0 (true) or 1 (false) depending on
 the evaluation of EXPR.  Expressions may be unary or binary.  Unary
 expressions are often used to examine the status of a file.  There
@@ -89,12 +91,18 @@ Other operators:
 Arithmetic binary operators return true if ARG1 is equal, not-equal,
 less-than, less-than-or-equal, greater-than, or greater-than-or-equal
 than ARG2.
+
+Exit Status:
+Returns success if EXPR evaluates to true; fails if EXPR evaluates to
+false or an invalid argument is given.
 $END
 
 $BUILTIN [
 $DOCNAME test_bracket
 $FUNCTION test_builtin
 $SHORT_DOC [ arg... ]
+Evaluate conditional expression.
+
 This is a synonym for the "test" builtin, but the last argument must
 be a literal `]', to match the opening `['.
 $END

builtins/test.def~

@@ -1,7 +1,7 @@
 This file is test.def, from which is created test.c.
 It implements the builtin "test" in Bash.
 
-Copyright (C) 1987-2006 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -24,6 +24,8 @@ $PRODUCES test.c
 $BUILTIN test
 $FUNCTION test_builtin
 $SHORT_DOC test [expr]
+Evaluate conditional expression.
+
 Exits with a status of 0 (true) or 1 (false) depending on
 the evaluation of EXPR.  Expressions may be unary or binary.  Unary
 expressions are often used to examine the status of a file.  There
@@ -31,27 +33,27 @@ are string operators as well, and numeric comparison operators.
 
 File operators:
 
-    -a FILE        True if file exists.
-    -b FILE        True if file is block special.
-    -c FILE        True if file is character special.
-    -d FILE        True if file is a directory.
-    -e FILE        True if file exists.
-    -f FILE        True if file exists and is a regular file.
-    -g FILE        True if file is set-group-id.
-    -h FILE        True if file is a symbolic link.
-    -L FILE        True if file is a symbolic link.
-    -k FILE        True if file has its `sticky' bit set.
-    -p FILE        True if file is a named pipe.
-    -r FILE        True if file is readable by you.
-    -s FILE        True if file exists and is not empty.
-    -S FILE        True if file is a socket.
-    -t FD          True if FD is opened on a terminal.
-    -u FILE        True if the file is set-user-id.
-    -w FILE        True if the file is writable by you.
-    -x FILE        True if the file is executable by you.
-    -O FILE        True if the file is effectively owned by you.
-    -G FILE        True if the file is effectively owned by your group.
-    -N FILE        True if the file has been modified since it was last read.
+  -a FILE        True if file exists.
+  -b FILE        True if file is block special.
+  -c FILE        True if file is character special.
+  -d FILE        True if file is a directory.
+  -e FILE        True if file exists.
+  -f FILE        True if file exists and is a regular file.
+  -g FILE        True if file is set-group-id.
+  -h FILE        True if file is a symbolic link.
+  -L FILE        True if file is a symbolic link.
+  -k FILE        True if file has its `sticky' bit set.
+  -p FILE        True if file is a named pipe.
+  -r FILE        True if file is readable by you.
+  -s FILE        True if file exists and is not empty.
+  -S FILE        True if file is a socket.
+  -t FD          True if FD is opened on a terminal.
+  -u FILE        True if the file is set-user-id.
+  -w FILE        True if the file is writable by you.
+  -x FILE        True if the file is executable by you.
+  -O FILE        True if the file is effectively owned by you.
+  -G FILE        True if the file is effectively owned by your group.
+  -N FILE        True if the file has been modified since it was last read.
 
   FILE1 -nt FILE2  True if file1 is newer than file2 (according to
                    modification date).
@@ -62,29 +64,29 @@ File operators:
 
 String operators:
 
-    -z STRING      True if string is empty.
+  -z STRING      True if string is empty.
 
-    -n STRING
-    STRING         True if string is not empty.
+  -n STRING
+     STRING      True if string is not empty.
 
-    STRING1 = STRING2
-                   True if the strings are equal.
-    STRING1 != STRING2
-                   True if the strings are not equal.
-    STRING1 < STRING2
-                   True if STRING1 sorts before STRING2 lexicographically.
-    STRING1 > STRING2
-                   True if STRING1 sorts after STRING2 lexicographically.
+  STRING1 = STRING2
+                 True if the strings are equal.
+  STRING1 != STRING2
+                 True if the strings are not equal.
+  STRING1 < STRING2
+                 True if STRING1 sorts before STRING2 lexicographically.
+  STRING1 > STRING2
+                 True if STRING1 sorts after STRING2 lexicographically.
 
 Other operators:
 
-    -o OPTION      True if the shell option OPTION is enabled.
-    ! EXPR         True if expr is false.
-    EXPR1 -a EXPR2 True if both expr1 AND expr2 are true.
-    EXPR1 -o EXPR2 True if either expr1 OR expr2 is true.
+  -o OPTION      True if the shell option OPTION is enabled.
+  ! EXPR         True if expr is false.
+  EXPR1 -a EXPR2 True if both expr1 AND expr2 are true.
+  EXPR1 -o EXPR2 True if either expr1 OR expr2 is true.
 
-    arg1 OP arg2   Arithmetic tests.  OP is one of -eq, -ne,
-                   -lt, -le, -gt, or -ge.
+  arg1 OP arg2   Arithmetic tests.  OP is one of -eq, -ne,
+                 -lt, -le, -gt, or -ge.
 
 Arithmetic binary operators return true if ARG1 is equal, not-equal,
 less-than, less-than-or-equal, greater-than, or greater-than-or-equal
@@ -95,8 +97,10 @@ $BUILTIN [
 $DOCNAME test_bracket
 $FUNCTION test_builtin
 $SHORT_DOC [ arg... ]
-This is a synonym for the "test" builtin, but the last
-argument must be a literal `]', to match the opening `['.
+Evaluate conditional expression.
+
+This is a synonym for the "test" builtin, but the last argument must
+be a literal `]', to match the opening `['.
 $END
 
 #include <config.h>

builtins/times.def

@@ -24,8 +24,13 @@ $PRODUCES times.c
 $BUILTIN times
 $FUNCTION times_builtin
 $SHORT_DOC times
+Display process times.
+
 Prints the accumulated user and system times for the shell and all of its
 child processes.
+
+Exit Status:
+Always succeeds.
 $END
 
 #include <config.h>

builtins/times.def~

@@ -24,6 +24,8 @@ $PRODUCES times.c
 $BUILTIN times
 $FUNCTION times_builtin
 $SHORT_DOC times
+Display process times.
+
 Prints the accumulated user and system times for the shell and all of its
 child processes.
 $END

builtins/trap.def

@@ -24,6 +24,8 @@ $PRODUCES trap.c
 $BUILTIN trap
 $FUNCTION trap_builtin
 $SHORT_DOC trap [-lp] [[arg] signal_spec ...]
+Trap signals and other events.
+
 Defines and activates handlers to be run when the shell receives signals
 or other conditions.
 
@@ -46,6 +48,9 @@ Options:
 Each SIGNAL_SPEC is either a signal name in <signal.h> or a signal number.
 Signal names are case insensitive and the SIG prefix is optional.  A
 signal may be sent to the shell with "kill -signal $$".
+
+Exit Status:
+Returns success unless a SIGSPEC is invalid or an invalid option is given.
 $END
 
 #include <config.h>

builtins/trap.def~

@@ -24,6 +24,8 @@ $PRODUCES trap.c
 $BUILTIN trap
 $FUNCTION trap_builtin
 $SHORT_DOC trap [-lp] [[arg] signal_spec ...]
+Trap signals and other events.
+
 Defines and activates handlers to be run when the shell receives signals
 or other conditions.
 
@@ -45,7 +47,7 @@ Options:
 
 Each SIGNAL_SPEC is either a signal name in <signal.h> or a signal number.
 Signal names are case insensitive and the SIG prefix is optional.  A
-signal can be sent to the shell with "kill -signal $$".
+signal may be sent to the shell with "kill -signal $$".
 $END
 
 #include <config.h>

builtins/type.def

@@ -24,6 +24,8 @@ $PRODUCES type.c
 $BUILTIN type
 $FUNCTION type_builtin
 $SHORT_DOC type [-afptP] name [name ...]
+Display information about command type.
+
 For each NAME, indicate how it would be interpreted if used as a
 command name.
 
@@ -41,6 +43,12 @@ Options:
 	`function', `builtin', `file' or `', if NAME is an alias, shell
 	reserved word, shell function, shell builtin, disk file, or not 
 	found, respectively
+
+Arguments:
+  NAME	Command name to be interpreted.
+
+Exit Status:
+Returns success if all of the NAMEs are found; fails if any are not found.
 $END
 
 #include <config.h>

builtins/type.def~

@@ -24,6 +24,8 @@ $PRODUCES type.c
 $BUILTIN type
 $FUNCTION type_builtin
 $SHORT_DOC type [-afptP] name [name ...]
+Display information about command type.
+
 For each NAME, indicate how it would be interpreted if used as a
 command name.
 
@@ -37,9 +39,13 @@ Options:
 	that would be executed
   -p	returns either the name of the disk file that would be executed,
 	or nothing if `type -t NAME' would not return `file'.
-  -t	output a single word which is one of `alias', `keyword', `function',
-	`builtin', `file' or `', if NAME is an alias, shell reserved word,
-	shell function, shell builtin, disk file, or not found, respectively
+  -t	output a single word which is one of `alias', `keyword',
+	`function', `builtin', `file' or `', if NAME is an alias, shell
+	reserved word, shell function, shell builtin, disk file, or not 
+	found, respectively
+
+Arguments:
+  NAME	Command name to be interpreted.
 $END
 
 #include <config.h>

builtins/ulimit.def

@@ -25,6 +25,8 @@ $BUILTIN ulimit
 $FUNCTION ulimit_builtin
 $DEPENDS_ON !_MINIX
 $SHORT_DOC ulimit [-SHacdefilmnpqrstuvx] [limit]
+Modify shell resource limits.
+
 Provides control over the resources available to the shell and processes
 it creates, on systems that allow such control.
 
@@ -59,6 +61,9 @@ no option is given, then -f is assumed.
 Values are in 1024-byte increments, except for -t, which is in seconds,
 -p, which is in increments of 512 bytes, and -u, which is an unscaled
 number of processes.
+
+Exit Status:
+Returns success unless an invalid option is supplied or an error occurs.
 $END
 
 #if !defined (_MINIX)

builtins/ulimit.def~

@@ -25,6 +25,8 @@ $BUILTIN ulimit
 $FUNCTION ulimit_builtin
 $DEPENDS_ON !_MINIX
 $SHORT_DOC ulimit [-SHacdefilmnpqrstuvx] [limit]
+Modify shell resource limits.
+
 Provides control over the resources available to the shell and processes
 it creates, on systems that allow such control.
 
@@ -32,6 +34,7 @@ Options:
   -S	use the `soft' resource limit
   -H	use the `hard' resource limit
   -a	all current limits are reported
+  -b	the socket buffer size
   -c	the maximum size of core files created
   -d	the maximum size of a process's data segment
   -e	the maximum scheduling priority (`nice')
@@ -199,6 +202,12 @@ typedef struct {
 } RESOURCE_LIMITS;
 
 static RESOURCE_LIMITS limits[] = {
+#ifdef RLIMIT_PTHREAD
+  { 'T',	RLIMIT_PTHREAD,  1,	"number of threads",	(char *)NULL },
+#endif
+#ifdef RLIMIT_SBSIZE
+  { 'b',	RLIMIT_SBSIZE,  1,	"socket buffer size",	"bytes" },
+#endif
 #ifdef RLIMIT_CORE
   { 'c',	RLIMIT_CORE,  512,	"core file size",	"blocks" },
 #endif

builtins/umask.def

@@ -24,6 +24,8 @@ $PRODUCES umask.c
 $BUILTIN umask
 $FUNCTION umask_builtin
 $SHORT_DOC umask [-p] [-S] [mode]
+Display or set file mode mask.
+
 Sets the user file-creation mask to MODE.  If MODE is omitted, prints
 the current value of the mask.
 
@@ -33,6 +35,9 @@ otherwise it is a symbolic mode string like that accepted by chmod(1).
 Options:
   -p	if MODE is omitted, output in a form that may be reused as input
   -S	makes the output symbolic; otherwise an octal number is output
+
+Exit Status:
+Returns success unless MODE is invalid or an invalid option is given.
 $END
 
 #include <config.h>

builtins/umask.def~

@@ -24,6 +24,8 @@ $PRODUCES umask.c
 $BUILTIN umask
 $FUNCTION umask_builtin
 $SHORT_DOC umask [-p] [-S] [mode]
+Display or set file mode mask.
+
 Sets the user file-creation mask to MODE.  If MODE is omitted, prints
 the current value of the mask.
 
@@ -31,7 +33,6 @@ If MODE begins with a digit, it is interpreted as an octal number;
 otherwise it is a symbolic mode string like that accepted by chmod(1).
 
 Options:
-
   -p	if MODE is omitted, output in a form that may be reused as input
   -S	makes the output symbolic; otherwise an octal number is output
 $END

builtins/wait.def

@@ -24,20 +24,32 @@ $FUNCTION wait_builtin
 $DEPENDS_ON JOB_CONTROL
 $PRODUCES wait.c
 $SHORT_DOC wait [id]
+Wait for job completion and return exit status.
+
 Waits for the process identified by ID, which may be a process ID or a
 job specification, and reports its termination status.  If ID is not
 given, waits for all currently active child processes, and the return
 status is zero.  If ID is a a job specification, waits for all processes
 in the job's pipeline.
+
+Exit Status:
+Returns the status of ID; fails if ID is invalid or an invalid option is
+given.
 $END
 
 $BUILTIN wait
 $FUNCTION wait_builtin
 $DEPENDS_ON !JOB_CONTROL
 $SHORT_DOC wait [pid]
+Wait for process completion and return exit status.
+
 Waits for the specified process and reports its termination status.  If
 PID is not given, all currently active child processes are waited for,
 and the return code is zero.  PID must be a process ID.
+
+Exit Status:
+Returns the status of ID; fails if ID is invalid or an invalid option is
+given.
 $END
 
 #include <config.h>

builtins/wait.def~

@@ -1,7 +1,7 @@
 This file is wait.def, from which is created wait.c.
 It implements the builtin "wait" in Bash.
 
-Copyright (C) 1987-2006 Free Software Foundation, Inc.
+Copyright (C) 1987-2008 Free Software Foundation, Inc.
 
 This file is part of GNU Bash, the Bourne Again SHell.
 
@@ -23,21 +23,25 @@ $BUILTIN wait
 $FUNCTION wait_builtin
 $DEPENDS_ON JOB_CONTROL
 $PRODUCES wait.c
-$SHORT_DOC wait [n]
-Wait for the specified process and report its termination status.  If
-N is not given, all currently active child processes are waited for,
-and the return code is zero.  N may be a process ID or a job
-specification; if a job spec is given, all processes in the job's
-pipeline are waited for.
+$SHORT_DOC wait [id]
+Wait for job completion and return exit status.
+
+Waits for the process identified by ID, which may be a process ID or a
+job specification, and reports its termination status.  If ID is not
+given, waits for all currently active child processes, and the return
+status is zero.  If ID is a a job specification, waits for all processes
+in the job's pipeline.
 $END
 
 $BUILTIN wait
 $FUNCTION wait_builtin
 $DEPENDS_ON !JOB_CONTROL
-$SHORT_DOC wait [n]
-Wait for the specified process and report its termination status.  If
-N is not given, all currently active child processes are waited for,
-and the return code is zero.  N must be a process ID.
+$SHORT_DOC wait [pid]
+Wait for process completion and return exit status.
+
+Waits for the specified process and reports its termination status.  If
+PID is not given, all currently active child processes are waited for,
+and the return code is zero.  PID must be a process ID.
 $END
 
 #include <config.h>