


BASH(1)                                                   BASH(1)


NAME
       bash - GNU Bourne-Again SHell

SYNOPSIS
       bash [options] [file]

COPYRIGHT
       Bash is Copyright (C) 1989-1999 by the Free Software Foun-
       dation, Inc.

DESCRIPTION
       Bash is an sh-compatible command language interpreter that
       executes  commands  read from the standard input or from a
       file.  Bash also incorporates  useful  features  from  the
       Korn and _C shells (ksh and csh).

       Bash  is intended to be a conformant implementation of the
       IEEE POSIX Shell and  Tools  specification  (IEEE  Working
       Group 1003.2).

OPTIONS
       In  addition  to  the single-character shell options docu-
       mented in the description of the set builtin command, bash
       interprets the following options when it is invoked:

       -c string If  the  -c option is present, then commands are
                 read from string.  If there are arguments  after
                 the  string, they are assigned to the positional
                 parameters, starting with $$00.
       -r        If the -r option is present, the  shell  becomes
                 restricted (see RESTRICTED SHELL below).
       -i        If the -i option is present, the shell is inter-
                 active.
       -s        If the -s option is present, or if no  arguments
                 remain  after  option  processing, then commands
                 are read from the standard input.   This  option
                 allows  the positional parameters to be set when
                 invoking an interactive shell.
       -D        A list of all double-quoted strings preceded  by
                 $$  is  printed on the standard ouput.  These are
                 the strings that are subject to language  trans-
                 lation  when  the  current  locale  is  not C or
                 POSIX.  This implies the -n option; no  commands
                 will be executed.
       ----        A  ----  signals  the  end of options and disables
                 further option processing.  Any arguments  after
                 the  ----  are treated as filenames and arguments.
                 An argument of -- is equivalent to ----.

       Bash also interprets a number of multi-character  options.
       These  options  must appear on the command line before the
       single-character options in order for them  to  be  recog-
       nized.




GNU                        1999 Jan 20                          1





BASH(1)                                                   BASH(1)


       --dump-po-strings
              Equivalent to -D, but the output is in the GNU get-
              text po (portable object) file format.
       --dump-strings
              Equivalent to -D.
       --help Display a usage message on standard output and exit
              successfully.
       --login
              Make  bash act as if it had been invoked as a login
              shell (see INVOCATION below).
       --noediting
              Do not use the GNU readline library to read command
              lines if interactive.
       --noprofile
              Do  not  read  either  the system-wide startup file
              /etc/profile or any of the personal  initialization
              files  ~/.bash__profile,  ~/.bash__login,  or ~/.pro-
              file.  By default, bash reads these files  when  it
              is invoked as a login shell (see INVOCATION below).
       --norc Do not read and execute the personal initialization
              file  ~/.bashrc  if the shell is interactive.  This
              option is on by default if the shell is invoked  as
              sh.
       --posix
              Change the behavior of bash where the default oper-
              ation differs from the  POSIX  1003.2  standard  to
              match the standard.
       --rcfile file
              Execute  commands from file instead of the standard
              personal initialization file ~/.bashrc if the shell
              is interactive (see INVOCATION below).
       --restricted
              The  shell becomes restricted (see RESTRICTED SHELL
              below).
       --verbose
              Equivalent to  -v.
       --version
              Show version information for this instance of  bash
              on the standard output and exit successfully.

ARGUMENTS
       If  arguments  remain after option processing, and neither
       the -c nor the -s option  has  been  supplied,  the  first
       argument  is  assumed  to be the name of a file containing
       shell commands.  If bash is invoked in this fashion, $$00 is
       set to the name of the file, and the positional parameters
       are set to the remaining arguments.  Bash reads  and  exe-
       cutes  commands  from  this file, then exits.  Bash's exit
       status is the exit status of the last command executed  in
       the  script.  If no commands are executed, the exit status
       is 0.

INVOCATION
       A login shell is one whose  first  character  of  argument



GNU                        1999 Jan 20                          2





BASH(1)                                                   BASH(1)


       zero is a --, or one started with the --login option.

       An  interactive shell is one whose standard input and out-
       put are both connected  to  terminals  (as  determined  by
       isatty(3)), or one started with the -i option.  PS1 is set
       and $$-- includes ii if bash is interactive, allowing a shell
       script or a startup file to test this state.

       The  following  paragraphs  describe how bash executes its
       startup files.  If any of the files exist  but  cannot  be
       read,  bash reports an error.  Tildes are expanded in file
       names as described below  under  Tilde  Expansion  in  the
       EXPANSION section.

       When  bash is invoked as an interactive login shell, or as
       a non-interactive shell with the --login option, it  first
       reads and executes commands from the file /etc/profile, if
       that file exists.  After reading that file, it  looks  for
       ~/.bash__profile,  ~/.bash__login,  and  ~/.profile, in that
       order, and reads and executes commands from the first  one
       that  exists  and is readable.  The --noprofile option may
       be used when the shell is started to inhibit  this  behav-
       ior.

       When a login shell exits, bash reads and executes commands
       from the file ~/.bash__logout, if it exists.

       When an interactive shell that is not  a  login  shell  is
       started,  bash reads and executes commands from ~/.bashrc,
       if that file exists.  This may be inhibited by  using  the
       --norc  option.   The --rcfile file option will force bash
       to  read  and  execute  commands  from  file  instead   of
       ~/.bashrc.

       When  bash  is  started  non-interactively, to run a shell
       script, for example, it looks for the variable BASH_ENV in
       the  environment,  expands  its value if it appears there,
       and uses the expanded value as the name of a file to  read
       and  execute.   Bash  behaves  as if the following command
       were executed:
              if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
       but the value of the PATH variable is not used  to  search
       for the file name.

       If bash is invoked with the name sh, it tries to mimic the
       startup behavior of historical versions of sh  as  closely
       as  possible,  while  conforming  to the POSIX standard as
       well.  When invoked as an interactive login  shell,  or  a
       non-interactive  shell  with  the --login option, it first
       attempts to read and execute  commands  from  /etc/profile
       and ~/.profile, in that order.  The --noprofile option may
       be used to inhibit this  behavior.   When  invoked  as  an
       interactive  shell  with  the  name sh, bash looks for the
       variable ENV, expands its value if it is defined, and uses



GNU                        1999 Jan 20                          3





BASH(1)                                                   BASH(1)


       the  expanded value as the name of a file to read and exe-
       cute.  Since a shell invoked as sh  does  not  attempt  to
       read  and  execute  commands from any other startup files,
       the --rcfile option  has  no  effect.   A  non-interactive
       shell  invoked  with  the name sh does not attempt to read
       any other startup files.  When invoked as sh, bash  enters
       posix mode after the startup files are read.

       When  bash  is  started in posix mode, as with the --posix
       command line option, it follows  the  POSIX  standard  for
       startup  files.   In  this mode, interactive shells expand
       the ENV variable and commands are read and  executed  from
       the  file  whose  name  is  the  expanded value.  No other
       startup files are read.

       Bash attempts to determine when it is  being  run  by  the
       remote  shell daemon, usually rshd.  If bash determines it
       is being run by rshd, it reads and executes commands  from
       ~/.bashrc,  if  that file exists and is readable.  It will
       not do this if invoked as sh.  The --norc  option  may  be
       used to inhibit this behavior, and the --rcfile option may
       be used to force another file to be read,  but  rshd  does
       not generally invoke the shell with those options or allow
       them to be specified.

       If the shell is started with the effective user (group) id
       not  equal  to the real user (group) id, and the -p option
       is not supplied, no startup files are  read,  shell  func-
       tions  are  not  inherited from the environment, the SHEL-
       LOPTS variable, if  it  appears  in  the  environment,  is
       ignored, and the effective user id is set to the real user
       id.  If the -p  option  is  supplied  at  invocation,  the
       startup behavior is the same, but the effective user id is
       not reset.

DEFINITIONS
       The following definitions are used throughout the rest  of
       this document.
       blank  A space or tab.
       word   A  sequence  of  characters  considered as a single
              unit by the shell.  Also known as a token.
       name   A word consisting only of  alphanumeric  characters
              and  underscores,  and beginning with an alphabetic
              character or an underscore.  Also referred to as an
              identifier.
       metacharacter
              A  character  that, when unquoted, separates words.
              One of the following:
              ||  && ;; (( )) << >> space tab
       control operator
              A token that performs a control  function.   It  is
              one of the following symbols:
              |||| && &&&& ;; ;;;; (( )) || <newline>




GNU                        1999 Jan 20                          4





BASH(1)                                                   BASH(1)


RESERVED WORDS
       Reserved  words  are  words that have a special meaning to
       the shell.  The following words are recognized as reserved
       when  unquoted  and either the first word of a simple com-
       mand (see SHELL GRAMMAR below) or the third word of a case
       or for command:

       !!  case   do  done  elif  else  esac fi for function if in
       select then until while {{ }} time [[[[ ]]]]

SHELL GRAMMAR
   Simple Commands
       A simple  command  is  a  sequence  of  optional  variable
       assignments followed by blank-separated words and redirec-
       tions, and terminated by a control  operator.   The  first
       word  specifies the command to be executed.  The remaining
       words are passed as arguments to the invoked command.

       The return value of a simple command is its  exit  status,
       or 128+_n if the command is terminated by signal _n.

   Pipelines
       A pipeline is a sequence of one or more commands separated
       by the character ||.  The format for a pipeline is:

              [time [-p] [ ! ] command [ || command2 ... ]

       The standard output of command is connected to  the  stan-
       dard  input  of  command2.   This  connection is performed
       before any redirections  specified  by  the  command  (see
       REDIRECTION below).

       If the reserved word !!  precedes a pipeline, the exit sta-
       tus of that pipeline is the logical NOT of the exit status
       of  the  last  command.   Otherwise,  the  status  of  the
       pipeline is the exit status  of  the  last  command.   The
       shell  waits for all commands in the pipeline to terminate
       before returning a value.

       If the time reserved word precedes a pipeline, the elapsed
       as  well as user and system time consumed by its execution
       are reported when the pipeline terminates.  The -p  option
       changes the output format to that specified by POSIX.  The
       TIMEFORMAT variable may be set to  a  format  string  that
       specifies  how the timing information should be displayed;
       see the description of TIMEFORMAT  under  Shell  Variables
       below.

       Each  command in a pipeline is executed as a separate pro-
       cess (i.e., in a subshell).

   Lists
       A list is a sequence of one or more pipelines separated by
       one  of  the  operators  ;;,  &&,  &&&&, or ||||, and optionally



GNU                        1999 Jan 20                          5





BASH(1)                                                   BASH(1)


       terminated by one of ;;, &&, or <newline>.

       Of these list operators, &&&& and |||| have equal  precedence,
       followed by ;; and &&,, which have equal precedence.

       If  a command is terminated by the control operator &&, the
       shell executes the command in the  background  in  a  sub-
       shell.  The shell does not wait for the command to finish,
       and the return status is 0.  Commands separated by a ;; are
       executed sequentially; the shell waits for each command to
       terminate in turn.  The return status is the  exit  status
       of the last command executed.

       The  control  operators  &&&& and |||| denote AND lists and OR
       lists, respectively.  An AND list has the form

              command &&&& command2

       command2 is executed if, and only if, command  returns  an
       exit status of zero.

       An OR list has the form

              command |||| command2


       command2 is executed if and only if command returns a non-
       zero exit status.  The return status of AND and  OR  lists
       is  the  exit  status  of the last command executed in the
       list.

   Compound Commands
       A compound command is one of the following:

       (list) list is executed in a subshell.   Variable  assign-
              ments  and builtin commands that affect the shell's
              environment do not remain in effect after the  com-
              mand completes.  The return status is the exit sta-
              tus of list.

       { list; }
              list is simply executed in the current shell  envi-
              ronment.  list must be terminated with a newline or
              semicolon.  This is known as a group command.   The
              return status is the exit status of list.

       ((expression))
              The  expression is evaluated according to the rules
              described below under  ARITHMETIC  EVALUATION.   If
              the value of the expression is non-zero, the return
              status is 0; otherwise  the  return  status  is  1.
              This is exactly equivalent to let ""expression"".





GNU                        1999 Jan 20                          6





BASH(1)                                                   BASH(1)


       [[[[ expression ]]]]
              Return  a status of 0 or 1 depending on the evalua-
              tion  of  the  conditional  expression  expression.
              Expressions are composed of the primaries described
              below under CONDITIONAL EXPRESSIONS.   Word  split-
              ting  and  pathname  expansion are not performed on
              the words between the [[[[ and ]]]];  tilde  expansion,
              parameter and variable expansion, arithmetic expan-
              sion, command substitution,  process  substitution,
              and quote removal are performed.

              When  the  ==== and !!== operators are used, the string
              to the right of the operator is considered  a  pat-
              tern  and  matched according to the rules described
              below under Pattern Matching.  The return value  is
              0  if the string matches or does not match the pat-
              tern, respectively, and 1 otherwise.  Any  part  of
              the pattern may be quoted to force it to be matched
              as a string.

              Expressions may be  combined  using  the  following
              operators,  listed  in  decreasing  order of prece-
              dence:

              (( expression ))
                     Returns the value of expression.   This  may
                     be used to override the normal precedence of
                     operators.
              !! expression
                     True if expression is false.
              expression1 &&&& expression2
                     True if both expression1 and expression2 are
                     true.
              expression1 |||| expression2
                     True if either expression1 or expression2 is
                     true.

       The &&&& and |||| operators do not execute expression2 if  the
       value of expression1 is sufficient to determine the return
       value of the entire conditional expression.

       for name [ in word ] ; do list ; done
              The list of words following in is expanded,  gener-
              ating a list of items.  The variable name is set to
              each element of this list in turn, and list is exe-
              cuted  each  time.   If the in word is omitted, the
              for command executes list once for each  positional
              parameter  that is set (see PARAMETERS below).  The
              return status is the exit status of the  last  com-
              mand  that executes.  If the expansion of the items
              following in results in an empty list, no  commands
              are executed, and the return status is 0.





GNU                        1999 Jan 20                          7





BASH(1)                                                   BASH(1)


       select name [ in word ] ; do list ; done
              The  list of words following in is expanded, gener-
              ating a list of items.  The set of  expanded  words
              is  printed on the standard error, each preceded by
              a number.  If the in word  is  omitted,  the  posi-
              tional   parameters  are  printed  (see  PARAMETERS
              below).  The PS3 prompt is  then  displayed  and  a
              line  read  from  the  standard input.  If the line
              consists of a number corresponding to  one  of  the
              displayed  words,  then the value of name is set to
              that word.  If the line is  empty,  the  words  and
              prompt  are  displayed  again.  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.  The  list  is  executed  after
              each  selection  until a break or return command is
              executed.  The exit status of select  is  the  exit
              status  of  the  last  command executed in list, or
              zero if no commands were executed.

       case word in [ ( pattern [ || pattern ] ... ) list ;; ] ...
              esac
              A  case  command  first  expands word, and tries to
              match it against each pattern in  turn,  using  the
              same  matching rules as for pathname expansion (see
              Pathname Expansion below).  When a match is  found,
              the  corresponding  list  is  executed.   After the
              first match, no subsequent matches  are  attempted.
              The  exit  status  is  zero  if no pattern matches.
              Otherwise, it is the exit status of the  last  com-
              mand executed in list.

       if  list; then list; [ elif list; then list; ] ... [ else
              list; ] fi
              The  if  list  is  executed.  If its exit status is
              zero, the then list is executed.   Otherwise,  each
              elif list is executed in turn, and if its exit sta-
              tus is zero, the corresponding then  list  is  exe-
              cuted  and  the  command completes.  Otherwise, the
              else list is executed, if present.  The exit status
              is the exit status of the last command executed, or
              zero if no condition tested true.

       while list; do list; done
       until list; do list; done
              The while command continuously executes the do list
              as long as the last command in list returns an exit
              status of zero.  The until command is identical  to
              the while command, except that the test is negated;
              the do list is executed as long as the last command
              in  list  returns a non-zero exit status.  The exit
              status of the while and until commands is the  exit
              status  of  the  last  do list command executed, or
              zero if none was executed.



GNU                        1999 Jan 20                          8





BASH(1)                                                   BASH(1)


       [ function ] name () { list; }
              This defines a function named name.   The  body  of
              the  function is the list of commands between { and
              }.  This list is executed whenever name  is  speci-
              fied  as  the  name  of a simple command.  The exit
              status of a function is the exit status of the last
              command  executed  in  the  body.   (See  FUNCTIONS
              below.)

COMMENTS
       In a non-interactive shell, or  an  interactive  shell  in
       which the interactive_comments option to the shopt builtin
       is enabled (see SHELL  BUILTIN  COMMANDS  below),  a  word
       beginning  with ## causes that word and all remaining char-
       acters on that line to be ignored.  An  interactive  shell
       without  the  interactive_comments option enabled does not
       allow comments.  The interactive_comments option is on  by
       default in interactive shells.

QUOTING
       Quoting  is  used to remove the special meaning of certain
       characters or words to the shell.  Quoting can be used  to
       disable  special treatment for special characters, to pre-
       vent reserved words from being recognized as such, and  to
       prevent parameter expansion.

       Each  of the metacharacters listed above under DEFINITIONS
       has special meaning to the shell and  must  be  quoted  if
       they are to represent themselves.  There are three quoting
       mechanisms: the escape character, single quotes, and  dou-
       ble quotes.

       A  non-quoted  backslash  (\\) is the escape character.  It
       preserves the literal value of  the  next  character  that
       follows, with the exception of <newline>.  If a \\<newline>
       pair appears, and the backslash is not itself quoted,  the
       \\<newline>  is treated as a line continuation (that is, it
       is removed from the input stream and effectively ignored).

       Enclosing  characters  in single quotes preserves the lit-
       eral value of each character within the quotes.  A  single
       quote  may not occur between single quotes, even when pre-
       ceded by a backslash.

       Enclosing characters in double quotes preserves  the  lit-
       eral  value  of all characters within the quotes, with the
       exception of $$, ``, and \\.  The characters $$ and  ``  retain
       their special meaning within double quotes.  The backslash
       retains its special meaning only when followed by  one  of
       the  following  characters:  $$,  ``, "", \\, or <newline>.  A
       double quote may be quoted within double quotes by preced-
       ing it with a backslash.

       The  special  parameters ** and @@ have special meaning when



GNU                        1999 Jan 20                          9





BASH(1)                                                   BASH(1)


       in double quotes (see PARAMETERS below).

       Words of the form $$'string' are  treated  specially.   The
       word  expands to string, with backslash-escaped characters
       replaced as specifed by the ANSI  C  standard.   Backslash
       escape sequences, if present, are decoded as follows:
              \a     alert (bell)
              \b     backspace
              \e     an escape character
              \f     form feed
              \n     new line
              \r     carriage return
              \t     horizontal tab
              \v     vertical tab
              \\\\     backslash
              \\nnn   the  character whose ASCII code is the octal
                     value nnn (one to three digits)
              \\xxnnn  the character whose ASCII code is  the  hex-
                     adecimal value nnn (one to three digits)

       The  translated  result is single-quoted, as if the dollar
       sign had not been present.

       A double-quoted string preceded by a dollar sign ($$)  will
       cause the string to be translated according to the current
       locale.  If the current locale is CC or POSIX,  the  dollar
       sign   is  ignored.   If  the  string  is  translated  and
       replaced, the replacement is double-quoted.

PARAMETERS
       A parameter is an entity that stores values.  It can be  a
       name,  a  number,  or one of the special characters listed
       below under Special Parameters.  For the shell's purposes,
       a variable is a parameter denoted by a name.

       A  parameter  is set if it has been assigned a value.  The
       null string is a valid value.  Once a variable is set,  it
       may  be unset only by using the unset builtin command (see
       SHELL BUILTIN COMMANDS below).

       A variable may be assigned to by a statement of the form

              name=[value]

       If value is not given, the variable is assigned  the  null
       string.  All values undergo tilde expansion, parameter and
       variable expansion, string  expansion,  command  substitu-
       tion,  arithmetic expansion, and quote removal (see EXPAN-
       SION below).  If the variable has  its  integer  attribute
       set  (see  declare  below  in SHELL BUILTIN COMMANDS) then
       value is subject  to  arithmetic  expansion  even  if  the
       $((...))  expansion  is not used (see Arithmetic Expansion
       below).  Word splitting is not performed, with the  excep-
       tion  of ""$$@@"" as explained below under Special Parameters.



GNU                        1999 Jan 20                         10





BASH(1)                                                   BASH(1)


       Pathname expansion is not performed.

   Positional Parameters
       A positional parameter is a parameter denoted  by  one  or
       more  digits,  other  than the single digit 0.  Positional
       parameters are assigned from the shell's arguments when it
       is  invoked,  and  may be reassigned using the set builtin
       command.  Positional parameters may  not  be  assigned  to
       with assignment statements.  The positional parameters are
       temporarily replaced when a  shell  function  is  executed
       (see FUNCTIONS below).

       When a positional parameter consisting of more than a sin-
       gle digit is expanded, it must be enclosed in braces  (see
       EXPANSION below).

   Special Parameters
       The  shell  treats  several  parameters  specially.  These
       parameters may only be referenced; assignment to  them  is
       not allowed.
       **      Expands to the positional parameters, starting from
              one.   When  the  expansion  occurs  within  double
              quotes,  it expands to a single word with the value
              of each parameter separated by the first  character
              of  the  IFS  special  variable.   That is, "$$**" is
              equivalent to "$$11_c$$22_c......", where  _c  is  the  first
              character of the value of the IFS variable.  If IFS
              is unset, the parameters are separated  by  spaces.
              If  IFS  is null, the parameters are joined without
              intervening separators.
       @@      Expands to the positional parameters, starting from
              one.   When  the  expansion  occurs  within  double
              quotes, each parameter expands to a separate  word.
              That  is, "$$@@" is equivalent to "$$11" "$$22" ...  When
              there are no positional  parameters,  "$$@@"  and  $$@@
              expand to nothing (i.e., they are removed).
       ##      Expands  to  the number of positional parameters in
              decimal.
       ??      Expands to the status of the most recently executed
              foreground pipeline.
       --      Expands  to  the  current option flags as specified
              upon invocation, by the  set  builtin  command,  or
              those  set  by  the  shell  itself  (such as the -i
              option).
       $$      Expands to the process ID of the shell.   In  a  ()
              subshell,  it expands to the process ID of the cur-
              rent shell, not the subshell.
       !!      Expands to the process ID of the most recently exe-
              cuted background (asynchronous) command.
       00      Expands  to  the name of the shell or shell script.
              This is set at shell initialization.   If  bash  is
              invoked  with  a file of commands, $$00 is set to the
              name of that file.  If bash is started with the  -c
              option,  then $$00 is set to the first argument after



GNU                        1999 Jan 20                         11





BASH(1)                                                   BASH(1)


              the string to be executed, if one is present.  Oth-
              erwise,  it  is set to the file name used to invoke
              bash, as given by argument zero.
       __      At shell startup, set to the absolute file name  of
              the  shell or shell script being executed as passed
              in the argument list.  Subsequently, expands to the
              last argument to the previous command, after expan-
              sion.  Also set to the full file name of each  com-
              mand   executed   and  placed  in  the  environment
              exported to that command.  When checking mail, this
              parameter holds the name of the mail file currently
              being checked.

   Shell Variables
       The following variables are set by the shell:

       PPID   The process ID of the shell's parent.   This  vari-
              able is readonly.
       PWD    The current working directory as set by the cd com-
              mand.
       OLDPWD The previous working directory as  set  by  the  cd
              command.
       REPLY  Set  to  the line of input read by the read builtin
              command when no arguments are supplied.
       UID    Expands to the user ID of the  current  user,  ini-
              tialized  at shell startup.  This variable is read-
              only.
       EUID   Expands to the effective user  ID  of  the  current
              user,  initialized at shell startup.  This variable
              is readonly.
       GROUPS An array variable containing the list of groups  of
              which  the current user is a member.  This variable
              is readonly.
       BASH   Expands to the full file name used to  invoke  this
              instance of bash.
       BASH_VERSION
              Expands  to a string describing the version of this
              instance of bash.
       BASH_VERSINFO
              A readonly array variable whose members  hold  ver-
              sion  information  for  this instance of bash.  The
              values assigned to the array members  are  as  fol-
              lows:
              BBAASSHH__VVEERRSSIINNFFOO[[0]]        The  major  version  number
                                      (the release).
              BBAASSHH__VVEERRSSIINNFFOO[[1]]        The  minor  version  number
                                      (the version).
              BBAASSHH__VVEERRSSIINNFFOO[[2]]        The patch level.
              BBAASSHH__VVEERRSSIINNFFOO[[3]]        The build version.
              BBAASSHH__VVEERRSSIINNFFOO[[4]]        The  release  status (e.g.,
                                      beta1).
              BBAASSHH__VVEERRSSIINNFFOO[[5]]        The value of MACHTYPE.

       SHLVL  Incremented by one each time an instance of bash is



GNU                        1999 Jan 20                         12





BASH(1)                                                   BASH(1)


              started.

       RANDOM Each  time  this  parameter is referenced, a random
              integer between 0  and  32767  is  generated.   The
              sequence  of  random  numbers may be initialized by
              assigning a value to RANDOM.  If RANDOM  is  unset,
              it loses its special properties, even if it is sub-
              sequently reset.

       SECONDS
              Each time this parameter is referenced, the  number
              of  seconds since shell invocation is returned.  If
              a value is assigned to SECONDS, the value  returned
              upon subsequent references is the number of seconds
              since the assignment plus the value  assigned.   If
              SECONDS  is unset, it loses its special properties,
              even if it is subsequently reset.

       LINENO Each time this parameter is referenced,  the  shell
              substitutes  a decimal number representing the cur-
              rent  sequential  line  number  (starting  with  1)
              within  a script or function.  When not in a script
              or function, the value substituted is  not  guaran-
              teed  to  be  meaningful.   If  LINENO is unset, it
              loses its special properties, even if it is  subse-
              quently reset.

       HISTCMD
              The  history  number, or index in the history list,
              of the current command.  If HISTCMD  is  unset,  it
              loses  its special properties, even if it is subse-
              quently reset.

       DIRSTACK
              An array variable (see Arrays below) containing the
              current  contents of the directory stack.  Directo-
              ries appear in the stack in the order they are dis-
              played  by  the dirs builtin.  Assigning to members
              of this array variable may be used to modify direc-
              tories already in the stack, but the pushd and popd
              builtins must be used to add  and  remove  directo-
              ries.   Assignment to this variable will not change
              the current directory.  If DIRSTACK  is  unset,  it
              loses  its special properties, even if it is subse-
              quently reset.

       PIPESTATUS
              An array variable (see Arrays below)  containing  a
              list  of  exit  status values from the processes in
              the  most-recently-executed   foreground   pipeline
              (which may contain only a single command).

       OPTARG The  value of the last option argument processed by
              the getopts  builtin  command  (see  SHELL  BUILTIN



GNU                        1999 Jan 20                         13





BASH(1)                                                   BASH(1)


              COMMANDS below).

       OPTIND The  index  of the next argument to be processed by
              the getopts builtin command (see SHELL BUILTIN COM-
              MANDS below).

       HOSTNAME
              Automatically  set to the name of the current host.

       HOSTTYPE
              Automatically  set  to  a  string   that   uniquely
              describes the type of machine on which bash is exe-
              cuting.  The default is system-dependent.

       OSTYPE Automatically set to a string  that  describes  the
              operating  system  on which bash is executing.  The
              default is system-dependent.

       MACHTYPE
              Automatically set to a string that fully  describes
              the  system type on which bash is executing, in the
              standard  GNU   cpu-company-system   format.    The
              default is system-dependent.

       SHELLOPTS
              A  colon-separated  list  of enabled shell options.
              Each word in the list is a valid argument  for  the
              -o  option  to  the  set builtin command (see SHELL
              BUILTIN COMMANDS below).  The options appearing  in
              SHELLOPTS  are  those reported as on by set -o.  If
              this variable  is  in  the  environment  when  bash
              starts  up,  each  shell option in the list will be
              enabled before reading  any  startup  files.   This
              variable is read-only.

       The  following  variables  are used by the shell.  In some
       cases, bash assigns a default value to a  variable;  these
       cases are noted below.

       IFS    The  Internal Field Separator that is used for word
              splitting after expansion and to split  lines  into
              words  with  the read builtin command.  The default
              value is ``<space><tab><newline>''.
       PATH   The search path for commands.  It is a  colon-sepa-
              rated  list of directories in which the shell looks
              for commands (see COMMAND  EXECUTION  below).   The
              default path is system-dependent, and is set by the
              administrator who installs bash.  A common value is
              ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin:.''.
       HOME   The home directory of the current user; the default
              argument  for the cd builtin command.  The value of
              this variable is also used  when  performing  tilde
              expansion.
       CDPATH The  search  path  for  the  cd command.  This is a



GNU                        1999 Jan 20                         14





BASH(1)                                                   BASH(1)


              colon-separated list of directories  in  which  the
              shell  looks  for destination directories specified
              by the cd command.  A sample value is ``.:~:/usr''.
       BASH_ENV
              If  this  parameter is set when bash is executing a
              shell script, its value is interpreted as  a  file-
              name  containing  commands to initialize the shell,
              as in ~/.bashrc.  The value  of  BASH_ENV  is  sub-
              jected  to  parameter  expansion, command substitu-
              tion, and arithmetic expansion before being  inter-
              preted  as a file name.  PATH is not used to search
              for the resultant file name.
       MAIL   If this parameter is set to a  file  name  and  the
              MAILPATH variable is not set, bash informs the user
              of the arrival of mail in the specified file.
       MAILCHECK
              Specifies how often (in seconds)  bash  checks  for
              mail.   The default is 60 seconds.  When it is time
              to check for mail, the shell does  so  before  dis-
              playing  the  primary  prompt.  If this variable is
              unset, the shell disables mail checking.
       MAILPATH
              A colon-separated list of file names to be  checked
              for  mail.   The  message  to  be printed when mail
              arrives in a particular file may  be  specified  by
              separating  the  file  name from the message with a
              `?'.  When used in the  text  of  the  message,  $$__
              expands to the name of the current mailfile.  Exam-
              ple:
              MAILPATH='/usr/spool/mail/bfox?"You            have
              mail":~/shell-mail?"$_ has mail!"'
              Bash  supplies  a  default value for this variable,
              but the location of the user  mail  files  that  it
              uses      is      system      dependent      (e.g.,
              /usr/spool/mail/$USER).
       PS1    The  value  of  this  parameter  is  expanded  (see
              PROMPTING  below)  and  used  as the primary prompt
              string.  The default value is `\s-\v\$ ''.
       PS2    The value of this parameter is expanded as with PS1
              and  used  as  the  secondary  prompt  string.  The
              default is ``>> ''.
       PS3    The value of this parameter is used as  the  prompt
              for the select command (see SHELL GRAMMAR above).
       PS4    The value of this parameter is expanded as with PS1
              and the value is printed before each  command  bash
              displays  during  an  execution  trace.   The first
              character of PS4 is replicated multiple  times,  as
              necessary,  to indicate multiple levels of indirec-
              tion.  The default is ``++ ''.
       TIMEFORMAT
              The value of this parameter is  used  as  a  format
              string  specifying  how  the timing information for
              pipelines prefixed  with  the  time  reserved  word
              should be displayed.  The %% character introduces an



GNU                        1999 Jan 20                         15





BASH(1)                                                   BASH(1)


              escape sequence that is expanded to a time value or
              other  information.  The escape sequences and their
              meanings are as follows; the braces denote optional
              portions.
              %%%%        A literal %%.
              %%[[_p]][[ll]]RR  The elapsed time in seconds.
              %%[[_p]][[ll]]UU  The  number  of CPU seconds spent in user
                        mode.
              %%[[_p]][[ll]]SS  The number of CPU seconds spent in system
                        mode.
              %P        The CPU percentage, computed as (%U + %S)
                        / %R.

              The optional _p is a digit specifying the precision,
              the  number  of  fractional  digits after a decimal
              point.  A value of 0 causes  no  decimal  point  or
              fraction  to be output.  At most three places after
              the decimal point may be  specified;  values  of  _p
              greater than 3 are changed to 3.  If _p is not spec-
              ified, the value 3 is used.

              The optional ll specifies a longer format, including
              minutes,  of  the  form  _M_Mm_S_S._F_Fs.  The value of _p
              determines whether or not the fraction is included.

              If this variable is not set, bash acts as if it had
              the value $'\nreal\t%3lR\nuser\t%3lU\nsys%3lS'.  If
              the  value  is  null, no timing information is dis-
              played.  A trailing newline is added when the  for-
              mat string is displayed.

       HISTSIZE
              The  number  of commands to remember in the command
              history (see HISTORY below).  The default value  is
              500.

       HISTFILE
              The  name  of  the file in which command history is
              saved (see HISTORY below).  The  default  value  is
              ~/.bash__history.   If unset, the command history is
              not saved when an interactive shell exits.

       HISTFILESIZE
              The maximum number of lines contained in  the  his-
              tory file.  When this variable is assigned a value,
              the history file is  truncated,  if  necessary,  to
              contain  no  more  than  that number of lines.  The
              default value is 500.  The  history  file  is  also
              truncated  to  this  size  after writing it when an
              interactive shell exits.

       OPTERR If set to the value 1, bash displays error messages
              generated by the getopts builtin command (see SHELL
              BUILTIN COMMANDS below).  OPTERR is initialized  to



GNU                        1999 Jan 20                         16





BASH(1)                                                   BASH(1)


              1  each time the shell is invoked or a shell script
              is executed.

       LANG   Used to determine the locale category for any cate-
              gory  not  specifically  selected  with  a variable
              starting with LC_.

       LC_ALL This variable overrides the value of LANG  and  any
              other LC_ variable specifying a locale category.

       LC_COLLATE
              This  variable  determines the collation order used
              when sorting the results of pathname expansion, and
              determines   the  behavior  of  range  expressions,
              equivalence classes, and collating sequences within
              pathname expansion and pattern matching.

       LC_CTYPE
              This  variable  determines  the  interpretation  of
              characters and the behavior  of  character  classes
              within pathname expansion and pattern matching.

       LC_MESSAGES
              This  variable determines the locale used to trans-
              late double-quoted strings preceded by a $$.

       PROMPT_COMMAND
              If set, the value is executed as a command prior to
              issuing each primary prompt.

       IGNOREEOF
              Controls  the  action  of  an  interactive shell on
              receipt of an EOF character as the sole input.   If
              set,  the  value  is  the number of consecutive EOF
              characters which must be typed as the first charac-
              ters  on  an  input line before bash exits.  If the
              variable exists but does not have a numeric  value,
              or  has  no  value, the default value is 10.  If it
              does not exist, EOF signifies the end of  input  to
              the shell.

       TMOUT  If  set  to a value greater than zero, the value is
              interpreted as the number of seconds  to  wait  for
              input  after issuing the primary prompt.  Bash ter-
              minates after waiting for that number of seconds if
              input does not arrive.

       FCEDIT The default editor for the fc builtin command.

       FIGNORE
              A  colon-separated  list of suffixes to ignore when
              performing  filename   completion   (see   READLINE
              below).  A filename whose suffix matches one of the
              entries in FIGNORE is excluded  from  the  list  of



GNU                        1999 Jan 20                         17





BASH(1)                                                   BASH(1)


              matched filenames.  A sample value is ``.o:~''.

       GLOBIGNORE
              A colon-separated list of patterns defining the set
              of filenames to be ignored by  pathname  expansion.
              If  a filename matched by a pathname expansion pat-
              tern also matches one of the  patterns  in  GLOBIG-
              NORE, it is removed from the list of matches.

       INPUTRC
              The  filename  for the readline startup file, over-
              riding the  default  of  ~/.inputrc  (see  READLINE
              below).

       HISTCONTROL
              If set to a value of ignorespace, lines which begin
              with a space character are not entered on the  his-
              tory  list.  If set to a value of ignoredups, lines
              matching the last history line are not entered.   A
              value  of  ignoreboth combines the two options.  If
              unset, or if set to  any  other  value  than  those
              above,  all  lines  read by the parser are saved on
              the history list, subject to the value  of  HISTIG-
              NORE.   This  variable's  function is superseded by
              HISTIGNORE.  The second and subsequent lines  of  a
              multi-line compound command are not tested, and are
              added to the history regardless  of  the  value  of
              HISTCONTROL.

       HISTIGNORE
              A  colon-separated  list of patterns used to decide
              which command lines should be saved on the  history
              list.  Each pattern is anchored at the beginning of
              the line  and  must  fully  specify  the  line  (no
              implicit  `**' is appended).  Each pattern is tested
              against the line  after  the  checks  specified  by
              HISTCONTROL are applied.  In addition to the normal
              shell pattern matching characters, `&&' matches  the
              previous  history line.  `&&' may be escaped using a
              backslash.   The  backslash   is   removed   before
              attempting  a  match.   The  second  and subsequent
              lines of a  multi-line  compound  command  are  not
              tested,  and are added to the history regardless of
              the value of HISTIGNORE.

       histchars
              The two or three characters which  control  history
              expansion  and  tokenization (see HISTORY EXPANSION
              below).  The first character is the history  expan-
              sion  character,  the  character  which signals the
              start of a history expansion,  normally  `!!'.   The
              second  character is the quick substitution charac-
              ter, which is used as shorthand for re-running  the
              previous  command  entered, substituting one string



GNU                        1999 Jan 20                         18





BASH(1)                                                   BASH(1)


              for another in the command.  The  default  is  `^^'.
              The optional third character is the character which
              indicates that the remainder of the line is a  com-
              ment  when  found as the first character of a word,
              normally `##'.  The history comment character causes
              history  substitution to be skipped for the remain-
              ing words on the line.   It  does  not  necessarily
              cause  the  shell  parser  to treat the rest of the
              line as a comment.

       HOSTFILE
              Contains the name of a file in the same  format  as
              /etc/hosts that should be read when the shell needs
              to complete a hostname.  The file  may  be  changed
              interactively; the next time hostname completion is
              attempted bash adds the contents of the new file to
              the already existing database.

       auto_resume
              This variable controls how the shell interacts with
              the user and job control.  If this variable is set,
              single  word  simple  commands without redirections
              are treated as  candidates  for  resumption  of  an
              existing   stopped  job.   There  is  no  ambiguity
              allowed; if there is more than  one  job  beginning
              with  the  string  typed,  the  job  most  recently
              accessed is selected.  The name of a  stopped  job,
              in  this context, is the command line used to start
              it.  If set to the value exact, the string supplied
              must  match  the  name of a stopped job exactly; if
              set to substring,  the  string  supplied  needs  to
              match  a  substring  of  the name of a stopped job.
              The substring value provides  functionality  analo-
              gous  to  the  %%??   job identifier (see JOB CONTROL
              below).  If set to any other  value,  the  supplied
              string  must  be  a prefix of a stopped job's name;
              this provides functionality analogous to the %%  job
              identifier.

   Arrays
       Bash  provides one-dimensional array variables.  Any vari-
       able may be used as an array;  the  declare  builtin  will
       explicitly declare an array.  There is no maximum limit on
       the size of an array, nor any requirement that members  be
       indexed  or  assigned  contiguously.   Arrays  are indexed
       using integers and are zero-based.

       An array is  created  automatically  if  any  variable  is
       assigned  to  using the syntax name[subscript]=value.  The
       subscript is treated as an arithmetic expression that must
       evaluate  to  a  number greater than or equal to zero.  To
       explicitly declare an array,  use  declare  -a  name  (see
       SHELL BUILTIN COMMANDS below).  declare -a name[[subscript]]
       is also accepted; the subscript  is  ignored.   Attributes



GNU                        1999 Jan 20                         19





BASH(1)                                                   BASH(1)


       may  be  specified for an array variable using the declare
       and readonly builtins.  Each attribute applies to all mem-
       bers of an array.

       Arrays  are  assigned to using compound assignments of the
       form name=((value_1 ... value_n)), where each value is of  the
       form [subscript]=string.  Only string is required.  If the
       optional brackets and subscript are supplied,  that  index
       is  assigned  to;  otherwise  the  index  of  the  element
       assigned is the last index assigned to  by  the  statement
       plus  one.   Indexing starts at zero.  This syntax is also
       accepted by the declare builtin.   Individual  array  ele-
       ments  may  be assigned to using the name[subscript]=value
       syntax introduced above.

       Any  element  of  an  array  may   be   referenced   using
       ${name[subscript]}.  The braces are required to avoid con-
       flicts with pathname expansion.  If subscript is @@  or  **,
       the word expands to all members of name.  These subscripts
       differ only when the word appears  within  double  quotes.
       If the word is double-quoted, ${name[*]} expands to a sin-
       gle word with the value of each array member separated  by
       the  first  character  of  the  IFS  special variable, and
       ${name[@]} expands each element  of  name  to  a  separate
       word.  When there are no array members, ${name[@]} expands
       to nothing.  This is analogous to  the  expansion  of  the
       special parameters ** and @@ (see Special Parameters above).
       ${#name[subscript]} expands to the length  of  ${name[sub-
       script]}.   If  subscript  is ** or @@, the expansion is the
       number of elements in the  array.   Referencing  an  array
       variable  without a subscript is equivalent to referencing
       element zero.

       The unset  builtin  is  used  to  destroy  arrays.   unset
       name[subscript]  destroys  the array element at index sub-
       script.  unset name, where name  is  an  array,  or  unset
       name[subscript],  where  subscript  is ** or @@, removes the
       entire array.

       The declare, local, and readonly builtins each accept a -a
       option to specify an array.  The read builtin accepts a -a
       option to assign a list of words read  from  the  standard
       input  to  an array.  The set and declare builtins display
       array values in a way that allows them  to  be  reused  as
       assignments.

EXPANSION
       Expansion  is  performed  on the command line after it has
       been split into words.  There are seven kinds of expansion
       performed: brace expansion, tilde expansion, parameter and
       variable  expansion,  command   substitution,   arithmetic
       expansion, word splitting, and pathname expansion.

       The   order  of  expansions  is:  brace  expansion,  tilde



GNU                        1999 Jan 20                         20





BASH(1)                                                   BASH(1)


       expansion, parameter, variable  and  arithmetic  expansion
       and  command  substitution  (done in a left-to-right fash-
       ion), word splitting, and pathname expansion.

       On systems that can support it,  there  is  an  additional
       expansion available: process substitution.

       Only  brace expansion, word splitting, and pathname expan-
       sion can change the number  of  words  of  the  expansion;
       other  expansions  expand  a single word to a single word.
       The only exceptions to this are the expansions of "$$@@" and
       "$${{name[[@@]]}}" as explained above (see PARAMETERS).

   Brace Expansion
       Brace  expansion is a mechanism by which arbitrary strings
       may be generated.  This mechanism is similar  to  pathname
       expansion,  but  the  filenames  generated need not exist.
       Patterns to be brace expanded take the form of an optional
       preamble,  followed by a series of comma-separated strings
       between  a  pair  of  braces,  followed  by  an   optional
       postscript.   The preamble is prefixed to each string con-
       tained within the  braces,  and  the  postscript  is  then
       appended  to  each  resulting  string,  expanding  left to
       right.

       Brace expansions may  be  nested.   The  results  of  each
       expanded  string  are  not  sorted; left to right order is
       preserved.  For example, a{{d,c,b}}e expands into  `ade  ace
       abe'.

       Brace  expansion is performed before any other expansions,
       and any characters special to other  expansions  are  pre-
       served  in the result.  It is strictly textual.  Bash does
       not apply any syntactic interpretation to the  context  of
       the expansion or the text between the braces.

       A  correctly-formed  brace expansion must contain unquoted
       opening and closing braces,  and  at  least  one  unquoted
       comma.   Any  incorrectly  formed  brace expansion is left
       unchanged.  A {{ or ,, may be quoted  with  a  backslash  to
       prevent its being considered part of a brace expression.

       This  construct  is  typically  used as shorthand when the
       common prefix of the strings to  be  generated  is  longer
       than in the above example:

              mkdir /usr/local/src/bash/{old,new,dist,bugs}
       or
              chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}

       Brace expansion introduces a slight  incompatibility  with
       historical  versions  of sh.  sh does not treat opening or
       closing braces specially when they appear  as  part  of  a
       word,  and  preserves  them  in  the output.  Bash removes



GNU                        1999 Jan 20                         21





BASH(1)                                                   BASH(1)


       braces from words as a  consequence  of  brace  expansion.
       For  example,  a  word  entered to sh as file{1,2} appears
       identically in the output.  The same  word  is  output  as
       file1  file2  after expansion by bash.  If strict compati-
       bility with sh is desired, start bash with the  +B  option
       or  disable  brace expansion with the +B option to the set
       command (see SHELL BUILTIN COMMANDS below).

   Tilde Expansion
       If a word begins with an unquoted tilde  character  (`~~'),
       all  of  the characters preceding the first unquoted slash
       (or all characters, if there is  no  unquoted  slash)  are
       considered  a  tilde-prefix.  If none of the characters in
       the tilde-prefix are quoted, the characters in the  tilde-
       prefix following the tilde are treated as a possible login
       name.  If this login name is the null string, the tilde is
       replaced  with  the value of the shell parameter HOME.  If
       HOME is unset, the home directory of  the  user  executing
       the  shell  is substituted instead.  Otherwise, the tilde-
       prefix is replaced with the home directory associated with
       the specified login name.

       If  the  tilde-prefix  is  a  `~+', the value of the shell
       variable PWD replaces the tilde-prefix.  If the tilde-pre-
       fix  is a `~-', the value of the shell variable OLDPWD, if
       it is set, is substituted.  If  the  characters  following
       the  tilde  in  the  tilde-prefix  consist  of a number _N,
       optionally prefixed by a `+' or a `-', the tilde-prefix is
       replaced with the corresponding element from the directory
       stack, as it  would  be  displayed  by  the  dirs  builtin
       invoked  with  the  tilde-prefix  as  an argument.  If the
       characters following the tilde in the tilde-prefix consist
       of  a number without a leading `+' or `-', `+' is assumed.

       If the login name  is  invalid,  or  the  tilde  expansion
       fails, the word is unchanged.

       Each  variable  assignment  is checked for unquoted tilde-
       prefixes immediately following a :: or ==.  In these  cases,
       tilde  expansion is also performed.  Consequently, one may
       use file names with tildes in assignments to  PATH,  MAIL-
       PATH,  and  CDPATH,  and  the  shell  assigns the expanded
       value.

   Parameter Expansion
       The `$$' character introduces parameter expansion,  command
       substitution, or arithmetic expansion.  The parameter name
       or symbol to be expanded may be enclosed in braces,  which
       are  optional  but  serve  to  protect  the variable to be
       expanded from characters immediately  following  it  which
       could be interpreted as part of the name.

       When  braces  are  used,  the matching ending brace is the
       first `}}' not escaped by a backslash or  within  a  quoted



GNU                        1999 Jan 20                         22





BASH(1)                                                   BASH(1)


       string,  and  not within an embedded arithmetic expansion,
       command substitution, or paramter expansion.

       ${parameter}
              The value of parameter is substituted.  The  braces
              are required when parameter is a positional parame-
              ter with more than one digit, or when parameter  is
              followed  by  a character which is not to be inter-
              preted as part of its name.

       If the first character  of  parameter  is  an  exclamation
       point,  a  level  of  variable  indirection is introduced.
       Bash uses the value of the variable formed from  the  rest
       of parameter as the name of the variable; this variable is
       then expanded and that value used in the rest of the  sub-
       stitution,  rather  than  the  value  of parameter itself.
       This is known as indirect expansion.

       In each of the cases  below,  word  is  subject  to  tilde
       expansion,  parameter expansion, command substitution, and
       arithmetic  expansion.   When  not  performing   substring
       expansion,  bash  tests  for  a parameter that is unset or
       null; omitting the colon results in  a  test  only  for  a
       parameter that is unset.

       ${parameter::--word}
              Use Default Values.  If parameter is unset or null,
              the expansion of word is  substituted.   Otherwise,
              the value of parameter is substituted.
       ${parameter::==word}
              Assign  Default  Values.   If parameter is unset or
              null, the expansion of word is assigned to  parame-
              ter.   The  value of parameter is then substituted.
              Positional parameters and  special  parameters  may
              not be assigned to in this way.
       ${parameter::??word}
              Display  Error  if  Null or Unset.  If parameter is
              null or unset, the expansion of word (or a  message
              to  that  effect if word is not present) is written
              to the standard error and the shell, if it  is  not
              interactive, exits.  Otherwise, the value of param-
              eter is substituted.
       ${parameter::++word}
              Use Alternate  Value.   If  parameter  is  null  or
              unset, nothing is substituted, otherwise the expan-
              sion of word is substituted.
       ${parameter::offset}
       ${parameter::offset::length}
              Substring Expansion.  Expands to up to length char-
              acters  of  parameter,  starting  at the characters
              specified by offset.  If length is omitted, expands
              to  the  substring  of  parameter,  starting at the
              character specified by offset.  length  and  offset
              are    arithmetic   expressions   (see   ARITHMETIC



GNU                        1999 Jan 20                         23





BASH(1)                                                   BASH(1)


              EVALUATION below).  length must evaluate to a  num-
              ber greater than or equal to zero.  If offset eval-
              uates to a number less than zero, the value is used
              as  an  offset from the end of the value of parame-
              ter.  If parameter is @@, the result is length posi-
              tional  parameters beginning at offset.  If parame-
              ter is an array name indexed by @ or *, the  result
              is  the  length members of the array beginning with
              ${parameter[offset]}.  Substring indexing is  zero-
              based unless the positional parameters are used, in
              which case the indexing starts at 1.

       ${##parameter}
              The length in characters of the value of  parameter
              is  substituted.  If parameter is ** or @@, the value
              substituted is the number of positional parameters.
              If  parameter  is an array name subscripted by ** or
              @@, the value substituted is the number of  elements
              in the array.

       ${parameter##word}
       ${parameter####word}
              The  word  is expanded to produce a pattern just as
              in pathname expansion.  If the pattern matches  the
              beginning  of  the  value  of  parameter,  then the
              result of the expansion is the  expanded  value  of
              parameter  with  the shortest matching pattern (the
              ``##'' case) or the longest  matching  pattern  (the
              ``####''  case) deleted.  If parameter is @@ or **, the
              pattern removal operation is applied to each  posi-
              tional  parameter in turn, and the expansion is the
              resultant list.  If parameter is an array  variable
              subscripted with @@ or **, the pattern removal opera-
              tion is applied to each  member  of  the  array  in
              turn, and the expansion is the resultant list.

       ${parameter%%word}
       ${parameter%%%%word}
              The  word  is expanded to produce a pattern just as
              in pathname expansion.  If the  pattern  matches  a
              trailing  portion  of the expanded value of parame-
              ter, then  the  result  of  the  expansion  is  the
              expanded  value  of  parameter  with  the  shortest
              matching pattern (the ``%%'' case)  or  the  longest
              matching  pattern  (the  ``%%%%''  case) deleted.  If
              parameter is @@ or **, the pattern removal  operation
              is  applied  to  each positional parameter in turn,
              and the expansion is the resultant list.  If param-
              eter  is an array variable subscripted with @@ or **,
              the pattern removal operation is  applied  to  each
              member  of  the array in turn, and the expansion is
              the resultant list.





GNU                        1999 Jan 20                         24





BASH(1)                                                   BASH(1)


       ${parameter//pattern//string}
       ${parameter////pattern//string}
              The pattern is expanded to produce a  pattern  just
              as  in  pathname  expansion.  Parameter is expanded
              and the longest match of pattern against its  value
              is  replaced  with string.  In the first form, only
              the first  match  is  replaced.   The  second  form
              causes  all  matches of pattern to be replaced with
              string.  If pattern begins with ##, it must match at
              the  beginning  of the expanded value of parameter.
              If pattern begins with %%, it must match at the  end
              of  the  expanded value of parameter.  If string is
              null, matches of pattern are deleted and the // fol-
              lowing  pattern  may be omitted.  If parameter is @@
              or **, the substitution operation is applied to each
              positional  parameter in turn, and the expansion is
              the resultant list.  If parameter is an array vari-
              able  subscripted  with  @@  or  **, the substitution
              operation is applied to each member of the array in
              turn, and the expansion is the resultant list.

   Command Substitution
       Command  substitution  allows  the  output of a command to
       replace the command name.  There are two forms:


              $$((command))
       or
              ``command``

       Bash performs  the  expansion  by  executing  command  and
       replacing  the command substitution with the standard out-
       put of the command, with any  trailing  newlines  deleted.
       Embedded newlines are not deleted, but they may be removed
       during word splitting.   The  command  substitution  $(cat
       file))  can  be  replaced  by the equivalent but faster $$((<<
       file)).

       When the old-style backquote form of substitution is used,
       backslash retains its literal meaning except when followed
       by $$, ``, or \\.  The first  backquote  not  preceded  by  a
       backslash terminates the command substitution.  When using
       the $(command) form, all characters between the  parenthe-
       ses make up the command; none are treated specially.

       Command  substitutions  may be nested.  To nest when using
       the backquoted form,  escape  the  inner  backquotes  with
       backslashes.

       If  the  substitution  appears  within double quotes, word
       splitting and pathname expansion are not performed on  the
       results.





GNU                        1999 Jan 20                         25





BASH(1)                                                   BASH(1)


   Arithmetic Expansion
       Arithmetic  expansion  allows  the evaluation of an arith-
       metic expression and the substitution of the result.   The
       format for arithmetic expansion is:

              $$((((expression))))

       The  expression  is  treated  as  if it were within double
       quotes, but a double quote inside the parentheses  is  not
       treated  specially.   All tokens in the expression undergo
       parameter expansion, string expansion,  command  substitu-
       tion,  and quote removal.  Arithmetic substitutions may be
       nested.

       The evaluation is performed according to the rules  listed
       below  under  ARITHMETIC  EVALUATION.   If  expression  is
       invalid, bash prints a message indicating failure  and  no
       substitution occurs.

   Process Substitution
       Process  substitution is supported on systems that support
       named pipes (FIFOs) or the /dev/fd method of  naming  open
       files.  It takes the form of <<((list)) or >>((list)).  The pro-
       cess list is run with its input or output connected  to  a
       FIFO  or  some  file in /dev/fd.  The name of this file is
       passed as an argument to the current command as the result
       of the expansion.  If the >>((list)) form is used, writing to
       the file will provide input for list.  If the <<((list)) form
       is  used, the file passed as an argument should be read to
       obtain the output of list.

       When available, process substitution is performed simulta-
       neously  with  parameter  and  variable expansion, command
       substitution, and arithmetic expansion.

   Word Splitting
       The shell scans the results of parameter  expansion,  com-
       mand  substitution,  and arithmetic expansion that did not
       occur within double quotes for word splitting.

       The shell treats each character of IFS as a delimiter, and
       splits  the  results of the other expansions into words on
       these characters.  If  IFS  is  unset,  or  its  value  is
       exactly   <space><tab><newline>,  the  default,  then  any
       sequence of IFS characters serves to  delimit  words.   If
       IFS  has a value other than the default, then sequences of
       the whitespace characters space and tab are ignored at the
       beginning  and  end of the word, as long as the whitespace
       character is in the value of IFS (an IFS whitespace  char-
       acter).   Any character in IFS that is not IFS whitespace,
       along with any adjacent IFS whitespace characters,  delim-
       its  a  field.  A sequence of IFS whitespace characters is
       also treated as a delimiter.  If the value of IFS is null,
       no word splitting occurs.



GNU                        1999 Jan 20                         26





BASH(1)                                                   BASH(1)


       Explicit null arguments ("""" or '''') are retained.  Unquoted
       implicit null arguments, resulting from the  expansion  of
       parameters that have no values, are removed.  If a parame-
       ter with no value is expanded within double quotes, a null
       argument results and is retained.

       Note  that  if  no  expansion occurs, no splitting is per-
       formed.

   Pathname Expansion
       After word splitting, unless the -f option has  been  set,
       bash  scans  each  word for the characters **, ??, ((, and [[.
       If one of these  characters  appears,  then  the  word  is
       regarded as a pattern, and replaced with an alphabetically
       sorted list of file names matching  the  pattern.   If  no
       matching  file names are found, and the shell option null-
       glob is disabled, the word  is  left  unchanged.   If  the
       nullglob option is set, and no matches are found, the word
       is removed.  If the shell option  nocaseglob  is  enabled,
       the  match  is  performed  without  regard  to the case of
       alphabetic characters.  When a pattern is used  for  path-
       name  expansion,  the  character  ````..''''  at the start of a
       name or immediately following  a  slash  must  be  matched
       explicitly,  unless the shell option dotglob is set.  When
       matching a pathname, the slash character  must  always  be
       matched  explicitly.  In other cases, the ````..''''  character
       is not treated specially.  See the  description  of  shopt
       below  under  SHELL  BUILTIN COMMANDS for a description of
       the nocaseglob, nullglob, and dotglob shell options.

       The GLOBIGNORE shell variable may be used to restrict  the
       set  of  file  names matching a pattern.  If GLOBIGNORE is
       set, each matching file name that also matches one of  the
       patterns  in  GLOBIGNORE  is  removed  from  the  list  of
       matches.  The file names ````..''''   and  ````....''''   are  always
       ignored,  even  when  GLOBIGNORE is set.  However, setting
       GLOBIGNORE has the effect of enabling  the  dotglob  shell
       option,  so  all  other  file names beginning with a ````..''''
       will match.  To get the  old  behavior  of  ignoring  file
       names beginning with a ````..'''', make ````..**''''  one of the pat-
       terns in GLOBIGNORE.  The dotglob option is disabled  when
       GLOBIGNORE is unset.

       Pattern Matching

       Any  character  that  appears in a pattern, other than the
       special  pattern  characters  described   below,   matches
       itself.   The  NUL  character  may not occur in a pattern.
       The special pattern characters must be quoted if they  are
       to be matched literally.

       The  special  pattern  characters have the following mean-
       ings:




GNU                        1999 Jan 20                         27





BASH(1)                                                   BASH(1)


       **      Matches any string, including the null string.
       ??      Matches any single character.
       [[......]]  Matches any one of the enclosed characters.  A pair
              of  characters  separated by a minus sign denotes a
              range; any character lexically  between  those  two
              characters,  inclusive,  is  matched.  If the first
              character following the [[ is a !!  or a ^^  then  any
              character  not  enclosed  is  matched.   A -- may be
              matched by including it as the first or last  char-
              acter  in the set.  A ]] may be matched by including
              it as the first character in the set.

              Within [[ and ]], character classes can be  specified
              using  the  syntax [[::class::]], where class is one of
              the following classes defined in the POSIX.2  stan-
              dard:
              alnum  alpha  ascii  blank  cntrl digit graph lower
              print punct space upper xdigit
              A character class matches any  character  belonging
              to that class.

              Within  [[ and ]], an equivalence class can be speci-
              fied using the  syntax  [[==_c==]],  which  matches  all
              characters  with  the  same  collation  weight  (as
              defined by the current locale) as the character  _c.

              Within  [[  and ]], the syntax [[..symbol..]] matches the
              collating symbol symbol.

       If the extglob shell option is  enabled  using  the  shopt
       builtin,  several  extended pattern matching operators are
       recognized.  In the following description, a  pattern-list
       is  a list of one or more patterns separated by a ||.  Com-
       posite patterns may be formed using one  or  more  of  the
       following sub-patterns:

              ??((pattern-list))
                     Matches  zero or one occurrence of the given
                     patterns
              **((pattern-list))
                     Matches zero  or  more  occurrences  of  the
                     given patterns
              ++((pattern-list))
                     Matches one or more occurrences of the given
                     patterns
              @@((pattern-list))
                     Matches exactly one of the given patterns
              !!((pattern-list))
                     Matches anything except  one  of  the  given
                     patterns

   Quote Removal
       After  the  preceding expansions, all unquoted occurrences
       of the characters \\, '', and "" that did not result from one



GNU                        1999 Jan 20                         28





BASH(1)                                                   BASH(1)


       of the above expansions are removed.

REDIRECTION
       Before  a command is executed, its input and output may be
       redirected using a special  notation  interpreted  by  the
       shell.   Redirection  may  also  be used to open and close
       files for the current shell  execution  environment.   The
       following redirection operators may precede or appear any-
       where within a simple command or  may  follow  a  command.
       Redirections  are processed in the order they appear, from
       left to right.

       In the following descriptions, if the file descriptor num-
       ber is omitted, and the first character of the redirection
       operator is <<, the  redirection  refers  to  the  standard
       input  (file descriptor 0).  If the first character of the
       redirection operator is >>, the redirection refers  to  the
       standard output (file descriptor 1).

       The word following the redirection operator in the follow-
       ing descriptions, unless otherwise noted, is subjected  to
       brace  expansion,  tilde  expansion,  parameter expansion,
       command substitution, arithmetic expansion, quote removal,
       and  pathname  expansion.   If it expands to more than one
       word, bash reports an error.

       Note that the order of redirections is  significant.   For
       example, the command

              ls >> dirlist 2>>&&1

       directs  both  standard  output  and standard error to the
       file dirlist, while the command

              ls 2>>&&1 >> dirlist

       directs only the standard output to file dirlist,  because
       the  standard  error  was  duplicated  as  standard output
       before the standard output was redirected to dirlist.

       A failure to open or create a file causes the  redirection
       to fail.

   Redirecting Input
       Redirection  of  input  causes the file whose name results
       from the expansion of word to be  opened  for  reading  on
       file  descriptor _n, or the standard input (file descriptor
       0) if _n is not specified.

       The general format for redirecting input is:

              [_n]<<word





GNU                        1999 Jan 20                         29





BASH(1)                                                   BASH(1)


   Redirecting Output
       Redirection of output causes the file whose  name  results
       from  the  expansion  of  word to be opened for writing on
       file descriptor _n, or the standard output (file descriptor
       1)  if  _n is not specified.  If the file does not exist it
       is created; if it does exist it is truncated to zero size.

       The general format for redirecting output is:

              [_n]>>word

       If the redirection operator is >>, and the noclobber option
       to the set builtin has been enabled, the redirection  will
       fail if the filename whose name results from the expansion
       of word exists and is a regular file.  If the  redirection
       operator  is  >>||, or the redirection operator is >> and the
       noclobber  option  to  the  set  builtin  command  is  not
       enabled,  the  redirection  is  attempted even if the file
       named by word exists.

   Appending Redirected Output
       Redirection of output in  this  fashion  causes  the  file
       whose name results from the expansion of word to be opened
       for appending on file descriptor _n, or the standard output
       (file  descriptor  1)  if _n is not specified.  If the file
       does not exist it is created.

       The general format for appending output is:

              [_n]>>>>word


   Redirecting Standard Output and Standard Error
       Bash allows both the standard output (file  descriptor  1)
       and  the  standard  error output (file descriptor 2) to be
       redirected to the file whose name is the expansion of word
       with this construct.

       There  are two formats for redirecting standard output and
       standard error:

              &&>>word
       and
              >>&&word

       Of the two forms, the first is preferred.  This is  seman-
       tically equivalent to

              >>word 2>>&&1

   Here Documents
       This type of redirection instructs the shell to read input
       from the current source until a line containing only  word
       (with  no trailing blanks) is seen.  All of the lines read



GNU                        1999 Jan 20                         30





BASH(1)                                                   BASH(1)


       up to that point are then used as the standard input for a
       command.

       The format of here-documents is as follows:

              <<<<[--]word
                      here-document
              delimiter

       No  parameter  expansion,  command  substitution, pathname
       expansion, or arithmetic expansion is performed  on  word.
       If any characters in word are quoted, the delimiter is the
       result of quote removal on word,  and  the  lines  in  the
       here-document  are not expanded.  If word is unquoted, all
       lines of the  here-document  are  subjected  to  parameter
       expansion, command substitution, and arithmetic expansion.
       In the latter case, the pair \<newline> is ignored, and  \\
       must be used to quote the characters \\, $$, and ``.

       If  the  redirection operator is <<<<--, then all leading tab
       characters are stripped from input lines and the line con-
       taining  delimiter.   This  allows  here-documents  within
       shell scripts to be indented in a natural fashion.

   Duplicating File Descriptors
       The redirection operator

              [_n]<<&&word

       is used to duplicate  input  file  descriptors.   If  word
       expands to one or more digits, the file descriptor denoted
       by _n is made to be a copy of that file descriptor.  If the
       digits  in  word do not specify a file descriptor open for
       input, a redirection error occurs.  If word  evaluates  to
       --,  file  descriptor  _n is closed.  If _n is not specified,
       the standard input (file descriptor 0) is used.

       The operator

              [_n]>>&&word

       is used similarly to duplicate  output  file  descriptors.
       If  _n is not specified, the standard output (file descrip-
       tor 1) is used.  If the digits in word do  not  specify  a
       file  descriptor  open  for  output,  a  redirection error
       occurs.  As a special case, if _n is omitted, and word does
       not  expand to one or more digits, the standard output and
       standard error are redirected as described previously.

   Opening File Descriptors for Reading and Writing
       The redirection operator

              [_n]<<>>word




GNU                        1999 Jan 20                         31





BASH(1)                                                   BASH(1)


       causes the file whose name is the expansion of word to  be
       opened  for both reading and writing on file descriptor _n,
       or on file descriptor 0 if _n is  not  specified.   If  the
       file does not exist, it is created.

ALIASES
       Aliases  allow  a string to be substituted for a word when
       it is used as the first word of  a  simple  command.   The
       shell  maintains  a  list  of  aliases that may be set and
       unset with the alias and  unalias  builtin  commands  (see
       SHELL  BUILTIN  COMMANDS  below).   The first word of each
       command, if unquoted, is checked  to  see  if  it  has  an
       alias.   If  so,  that word is replaced by the text of the
       alias.  The alias name and the replacement text  may  con-
       tain  any  valid shell input, including the metacharacters
       listed above, with the exception that the alias  name  may
       not  contain _=.  The first word of the replacement text is
       tested for aliases, but a word that  is  identical  to  an
       alias  being expanded is not expanded a second time.  This
       means that one may alias ls to ls -F,  for  instance,  and
       bash  does  not  try to recursively expand the replacement
       text.  If the last character  of  the  alias  value  is  a
       blank,  then  the next command word following the alias is
       also checked for alias expansion.

       Aliases are created and listed with the alias command, and
       removed with the unalias command.

       There  is no mechanism for using arguments in the replace-
       ment text.  If arguments  are  needed,  a  shell  function
       should be used.

       Aliases  are  not  expanded when the shell is not interac-
       tive, unless the expand_aliases shell option is set  using
       shopt  (see  the  description of shopt under SHELL BUILTIN
       COMMANDS below).

       The rules concerning the definition and use of aliases are
       somewhat  confusing.   Bash always reads at least one com-
       plete line of input before executing any of  the  commands
       on  that  line.   Aliases  are  expanded when a command is
       read, not when it is executed.  Therefore, an alias  defi-
       nition  appearing on the same line as another command does
       not take effect until the next line of input is read.  The
       commands  following  the alias definition on that line are
       not affected by the new alias.  This behavior is  also  an
       issue  when  functions are executed.  Aliases are expanded
       when a function definition is read, not when the  function
       is  executed,  because  a  function definition is itself a
       compound command.  As a consequence, aliases defined in  a
       function  are  not  available until after that function is
       executed.  To be safe, always put alias definitions  on  a
       separate  line, and do not use alias in compound commands.




GNU                        1999 Jan 20                         32





BASH(1)                                                   BASH(1)


       For almost every purpose, aliases are superseded by  shell
       functions.

FUNCTIONS
       A  shell  function, defined as described above under SHELL
       GRAMMAR, stores a series of commands for later  execution.
       Functions  are  executed  in  the  context  of the current
       shell; no new process is created to interpret  them  (con-
       trast  this with the execution of a shell script).  When a
       function is executed, the arguments to the function become
       the  positional parameters during its execution.  The spe-
       cial parameter ## is updated to reflect the change.   Posi-
       tional parameter 0 is unchanged.  All other aspects of the
       shell execution environment are identical between a  func-
       tion and its caller with the exception that the DEBUG trap
       (see the description  of  the  trap  builtin  under  SHELL
       BUILTIN COMMANDS below) is not inherited.

       Variables  local  to the function may be declared with the
       local builtin command.  Ordinarily,  variables  and  their
       values are shared between the function and its caller.

       If  the  builtin command return is executed in a function,
       the function completes and execution resumes with the next
       command  after  the  function  call.  When a function com-
       pletes, the values of the positional  parameters  and  the
       special  parameter  ##  are restored to the values they had
       prior to the function's execution.

       Function names and definitions may be listed with  the  -f
       option to the declare or typeset builtin commands.  The -F
       option to declare or typeset will list the function  names
       only.   Functions  may be exported so that subshells auto-
       matically have them defined with  the  -f  option  to  the
       export builtin.

       Functions  may  be  recursive.  No limit is imposed on the
       number of recursive calls.

ARITHMETIC EVALUATION
       The shell allows arithmetic expressions to  be  evaluated,
       under  certain  circumstances (see the let builtin command
       and Arithmetic Expansion).  Evaluation  is  done  in  long
       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 oper-
       ators.  The levels  are  listed  in  order  of  decreasing
       precedence.

       -- ++    unary minus and plus
       !! ~~    logical and bitwise negation
       ****     exponentiation
       ** // %%  multiplication, division, remainder
       ++ --    addition, subtraction



GNU                        1999 Jan 20                         33





BASH(1)                                                   BASH(1)


       <<<< >>>>  left and right bitwise shifts
       <<== >>== << >>
              comparison
       ==== !!==  equality and inequality
       &&      bitwise AND
       ^^      bitwise exclusive OR
       ||      bitwise OR
       &&&&     logical AND
       ||||     logical OR
       expr??expr::expr
              conditional evaluation
       == **== //== %%== ++== --== <<<<== >>>>== &&== ^^== ||==
              assignment

       Shell  variables are allowed as operands; parameter expan-
       sion is performed before the expression is evaluated.  The
       value  of  a parameter is coerced to a long integer within
       an expression.  A shell variable need not have its integer
       attribute turned on to be used in an expression.

       Constants  with  a leading 0 are interpreted as octal num-
       bers.  A leading 0x or 0X denotes hexadecimal.  Otherwise,
       numbers  take  the  form [base#]n, where base is a decimal
       number between 2 and 64 representing the arithmetic  base,
       and  _n is a number in that base.  If base is omitted, then
       base 10 is used.  The digits greater  than  9  are  repre-
       sented by the lowercase letters, the uppercase letters, _,
       and @, in that order.  If base is less than  or  equal  to
       36,  lowercase  and  uppercase  letters may be used inter-
       changably to represent numbers between 10 and 35.

       Operators are evaluated  in  order  of  precedence.   Sub-
       expressions  in  parentheses  are  evaluated first and may
       override the precedence rules above.

CONDITIONAL EXPRESSIONS
       Conditional expressions are used by the [[[[  compound  com-
       mand  and  the  test  and  [[ builtin commands to test file
       attributes and perform string and arithmetic  comparisons.
       Expressions  are formed from the following unary or binary
       primaries.  If any file argument to one of  the  primaries
       is  of  the  form  /dev/fd/_n,  then  file  descriptor _n is
       checked.

       -a file
              True if file exists.
       -b file
              True if file exists and is a block special file.
       -c file
              True if file exists  and  is  a  character  special
              file.
       -d file
              True if file exists and is a directory.




GNU                        1999 Jan 20                         34





BASH(1)                                                   BASH(1)


       -e file
              True if file exists.
       -f file
              True if file exists and is a regular file.
       -g file
              True if file exists and is set-group-id.
       -h file
              True if file exists and is a symbolic link.
       -k file
              True  if file exists and its ``sticky'' bit is set.
       -p file
              True if file exists and is a named pipe (FIFO).
       -r file
              True if file exists and is readable.
       -s file
              True if file exists and has  a  size  greater  than
              zero.
       -t fd  True  if file descriptor fd is open and refers to a
              terminal.
       -u file
              True if file exists and its set-user-id bit is set.
       -w file
              True if file exists and is writable.
       -x file
              True if file exists and is executable.
       -O file
              True  if  file exists and is owned by the effective
              user id.
       -G file
              True if file exists and is owned by  the  effective
              group id.
       -L file
              True if file exists and is a symbolic link.
       -S file
              True if file exists and is a socket.
       -N file
              True  if file exists and has been modified since it
              was last read.
       file1 -nt file2
              True if file1 is newer (according  to  modification
              date) than file2.
       file1 -ot file2
              True if file1 is older than file2.
       file1 -ef file2
              True  if  file1  and file2 have the same device and
              inode numbers.
       -o optname
              True if shell option optname is enabled.   See  the
              list  of  options  under  the description of the -o
              option to the set builtin below.
       -z string
              True if the length of string is zero.
       -n string
       string True if the length of string is non-zero.



GNU                        1999 Jan 20                         35





BASH(1)                                                   BASH(1)


       string1 ==== string2
              True if the strings are equal.  == may  be  used  in
              place of ====.
       string1 !!== string2
              True if the strings are not equal.
       string1 << string2
              True  if string1 sorts before string2 lexicographi-
              cally in the current locale.
       string1 >> string2
              True if string1 sorts after  string2  lexicographi-
              cally in the current locale.
       arg1 OP arg2
              OP  is  one  of  -eq,  -ne,  -lt, -le, -gt, or -ge.
              These arithmetic binary operators  return  true  if
              arg1  is  equal  to,  not equal to, less than, less
              than or equal to, greater than, or greater than  or
              equal  to arg2, respectively.  Arg1 and arg2 may be
              positive or negative integers.

SIMPLE COMMAND EXPANSION
       When a simple command is executed, the shell performs  the
       following  expansions, assignments, and redirections, from
       left to right.

       1.     The words that the parser has  marked  as  variable
              assignments  (those preceding the command name) and
              redirections are saved for later processing.

       2.     The words that  are  not  variable  assignments  or
              redirections  are  expanded.   If  any words remain
              after expansion, the first word is taken to be  the
              name of the command and the remaining words are the
              arguments.

       3.     Redirections are performed as described above under
              REDIRECTION.

       4.     The  text  after  the == in each variable assignment
              undergoes  tilde  expansion,  parameter  expansion,
              command  substitution,  arithmetic  expansion,  and
              quote removal before being assigned  to  the  vari-
              able.

       If  no  command  name  results,  the  variable assignments
       affect the  current  shell  environment.   Otherwise,  the
       variables  are  added  to  the environment of the executed
       command and do not affect the current  shell  environment.
       If  any of the assignments attempts to assign a value to a
       readonly variable, an error occurs, and the command  exits
       with a non-zero status.

       If  no  command  name results, redirections are performed,
       but do not affect the current shell environment.  A  redi-
       rection  error  causes the command to exit with a non-zero



GNU                        1999 Jan 20                         36





BASH(1)                                                   BASH(1)


       status.

       If there is a command name left after expansion, execution
       proceeds  as  described  below.   Otherwise,  the  command
       exits.  If one of the expansions contained a command  sub-
       stitution, the exit status of the command is the exit sta-
       tus of the last command substitution performed.  If  there
       were  no  command  substitutions, the command exits with a
       status of zero.

COMMAND EXECUTION
       After a command has been split into words, if  it  results
       in a simple command and an optional list of arguments, the
       following actions are taken.

       If  the  command  name  contains  no  slashes,  the  shell
       attempts  to  locate it.  If there exists a shell function
       by that name, that function is invoked as described  above
       in  FUNCTIONS.  If the name does not match a function, the
       shell searches for it in the list of shell builtins.  If a
       match is found, that builtin is invoked.

       If the name is neither a shell function nor a builtin, and
       contains no slashes, bash searches  each  element  of  the
       PATH for a directory containing an executable file by that
       name.  Bash uses a hash table to remember  the  full  file
       names  of  executable  files (see hash under SHELL BUILTIN
       COMMANDS below).  A full search of the directories in PATH
       is  performed only if the command is not found in the hash
       table.  If the search is unsuccessful, the shell prints an
       error message and returns an exit status of 127.

       If  the  search is successful, or if the command name con-
       tains one or more slashes, the shell  executes  the  named
       program  in  a separate execution environment.  Argument 0
       is set to the name given, and the remaining  arguments  to
       the command are set to the arguments given, if any.

       If  this  execution  fails because the file is not in exe-
       cutable format, and the file is not  a  directory,  it  is
       assumed to be a shell script, a file containing shell com-
       mands.  A subshell is spawned to execute  it.   This  sub-
       shell  reinitializes itself, so that the effect is as if a
       new shell had been invoked to handle the script, with  the
       exception that the locations of commands remembered by the
       parent (see hash below under SHELL BUILTIN  COMMANDS)  are
       retained by the child.

       If  the program is a file beginning with ##!!, the remainder
       of the first line specifies an interpreter  for  the  pro-
       gram.   The  shell  executes  the specified interpreter on
       operating systems that do not handle this executable  for-
       mat  themselves.  The arguments to the interpreter consist
       of a single optional argument  following  the  interpreter



GNU                        1999 Jan 20                         37





BASH(1)                                                   BASH(1)


       name  on  the  first  line of the program, followed by the
       name of the program, followed by the command arguments, if
       any.

COMMAND EXECUTION ENVIRONMENT
       The  shell has an execution environment, which consists of
       the following:


       +o      open files inherited by the shell at invocation, as
              modified  by  redirections  supplied  to  the  exec
              builtin

       +o      the current working directory as set by cd,  pushd,
              or popd, or inherited by the shell at invocation

       +o      the  file  creation  mode  mask  as set by umask or
              inherited from the shell's parent

       +o      current traps set by trap

       +o      shell parameters that are set by  variable  assign-
              ment or with set or inherited from the shell's par-
              ent in the environment

       +o      shell functions defined during execution or  inher-
              ited from the shell's parent in the environment

       +o      options enabled at invocation (either by default or
              with command-line arguments) or by set

       +o      options enabled by shopt

       +o      shell aliases defined with alias

       +o      various process IDs, including those of  background
              jobs, the value of $$$$, and the value of $PPID

       When  a simple command other than a builtin or shell func-
       tion is to be executed, it is invoked in a separate execu-
       tion  environment  that consists of the following.  Unless
       otherwise noted, the values are inherited from the  shell.


       +o      the  shell's open files, plus any modifications and
              additions specified by redirections to the command

       +o      the current working directory

       +o      the file creation mode mask

       +o      shell variables marked for export, along with vari-
              ables exported for the command, passed in the envi-
              ronment



GNU                        1999 Jan 20                         38





BASH(1)                                                   BASH(1)


       +o      traps caught by the shell are reset to  the  values
              the  inherited  from  the shell's parent, and traps
              ignored by the shell are ignored

       A command invoked  in  this  separate  environment  cannot
       affect the shell's execution environment.

       Command substitution and asynchronous commands are invoked
       in a subshell environment that is a duplicate of the shell
       environment,  except  that  traps  caught by the shell are
       reset to the values that the shell inherited from its par-
       ent  at  invocation.  Builtin commands that are invoked as
       part of a pipeline are also executed in a  subshell  envi-
       ronment.   Changes made to the subshell environment cannot
       affect the shell's execution environment.

ENVIRONMENT
       When a program is invoked it is given an array of  strings
       called  the  environment.   This  is  a list of name-value
       pairs, of the form name=value.

       The shell allows you to manipulate the environment in sev-
       eral  ways.   On invocation, the shell scans its own envi-
       ronment and creates a parameter for each name found, auto-
       matically  marking it for export to child processes.  Exe-
       cuted commands inherit the environment.   The  export  and
       declare  -x  commands allow parameters and functions to be
       added to and deleted from the environment.  If  the  value
       of  a  parameter  in  the environment is modified, the new
       value becomes part of the environment, replacing the  old.
       The environment inherited by any executed command consists
       of the shell's initial environment, whose  values  may  be
       modified in the shell, less any pairs removed by the unset
       command, plus any additions via the export and declare  -x
       commands.

       The  environment for any simple command or function may be
       augmented  temporarily  by  prefixing  it  with  parameter
       assignments,  as  described  above  in  PARAMETERS.  These
       assignment statements affect only the environment seen  by
       that command.

       If  the  -k  option  is  set  (see the set builtin command
       below), then all parameter assignments are placed  in  the
       environment for a command, not just those that precede the
       command name.

       When bash invokes an external command, the variable  __  is
       set  to  the  full  file name of the command and passed to
       that command in its environment.

EXIT STATUS
       For the shell's purposes, a command  which  exits  with  a
       zero  exit  status  has succeeded.  An exit status of zero



GNU                        1999 Jan 20                         39





BASH(1)                                                   BASH(1)


       indicates success.  A non-zero exit status indicates fail-
       ure.   When  a  command terminates on a fatal signal, bash
       uses the value of 128+signal as the exit status.

       If a command is not found, the child  process  created  to
       execute it returns a status of 127.  If a command is found
       but is not executable, the return status is 126.

       If a command fails because of an error during expansion or
       redirection, the exit status is greater than zero.

       Shell builtin commands return a status of 0 (true) if suc-
       cessful, and non-zero (false) if  an  error  occurs  while
       they  execute.  All builtins return an exit status of 2 to
       indicate incorrect usage.

       Bash itself returns the exit status of  the  last  command
       executed,  unless  a syntax error occurs, in which case it
       exits with a non-zero value.  See also  the  exit  builtin
       command below.

SIGNALS
       When  bash is interactive, in the absence of any traps, it
       ignores SIGTERM (so that kill 00 does not kill an  interac-
       tive shell), and SIGINT is caught and handled (so that the
       wait  builtin  is  interruptible).   In  all  cases,  bash
       ignores  SIGQUIT.   If  job  control  is  in  effect, bash
       ignores SIGTTIN, SIGTTOU, and SIGTSTP.

       Synchronous jobs started by bash have signal handlers  set
       to  the  values  inherited  by  the shell from its parent.
       When job control is not in effect,  asynchronous  commands
       ignore  SIGINT  and  SIGQUIT  as  well.  Commands run as a
       result of command substitution ignore the  keyboard-gener-
       ated job control signals SIGTTIN, SIGTTOU, and SIGTSTP.

       The  shell  exits  by  default  upon  receipt of a SIGHUP.
       Before exiting, it resends the SIGHUP to all jobs, running
       or  stopped.  Stopped jobs are sent SIGCONT to ensure that
       they receive the SIGHUP.  To prevent the shell from  send-
       ing  the  signal to a particular job, it should be removed
       from the jobs table with the  disown  builtin  (see  SHELL
       BUILTIN  COMMANDS  below)  or marked to not receive SIGHUP
       using disown -h.

       If the huponexit shell option has  been  set  with  shopt,
       bash  sends a SIGHUP to all jobs when an interactive login
       shell exits.

       When bash receives a signal for which a trap has been  set
       while waiting for a command to complete, the trap will not
       be executed until the command  completes.   When  bash  is
       waiting  for an asynchronous command via the wait builtin,
       the reception of a signal for which a trap  has  been  set



GNU                        1999 Jan 20                         40





BASH(1)                                                   BASH(1)


       will  cause the wait builtin to return immediately with an
       exit status greater than 128, immediately after which  the
       trap is executed.

JOB CONTROL
       Job  control  refers  to  the  ability to selectively stop
       (suspend) the execution of processes and continue (resume)
       their  execution  at  a  later  point.   A  user typically
       employs this facility via an  interactive  interface  sup-
       plied jointly by the system's terminal driver and bash.

       The shell associates a job with each pipeline.  It keeps a
       table of currently executing jobs,  which  may  be  listed
       with  the  jobs  command.   When  bash  starts a job asyn-
       chronously (in the background),  it  prints  a  line  that
       looks like:

              [1] 25647

       indicating that this job is job number 1 and that the pro-
       cess ID of the last process  in  the  pipeline  associated
       with  this job is 25647.  All of the processes in a single
       pipeline are members of the same job.  Bash uses  the  job
       abstraction as the basis for job control.

       To  facilitate the implementation of the user interface to
       job control, the system maintains the notion of a  current
       terminal  process group ID.  Members of this process group
       (processes whose process group ID is equal to the  current
       terminal process group ID) receive keyboard-generated sig-
       nals such as SIGINT.  These processes are said  to  be  in
       the foreground.  Background processes are those whose pro-
       cess group ID differs from the terminal's; such  processes
       are immune to keyboard-generated signals.  Only foreground
       processes are allowed to read from or write to the  termi-
       nal.   Background  processes  which  attempt  to read from
       (write to) the terminal are sent a SIGTTIN (SIGTTOU)  sig-
       nal by the terminal driver, which, unless caught, suspends
       the process.

       If the operating system on which bash is running  supports
       job  control,  bash allows you to use it.  Typing the sus-
       pend character (typically ^^ZZ, Control-Z) while  a  process
       is  running  causes that process to be stopped and returns
       you to bash.  Typing the delayed suspend character  (typi-
       cally ^^YY, Control-Y) causes the process to be stopped when
       it attempts to read input from the terminal,  and  control
       to  be returned to bash.  The user may then manipulate the
       state of this job, using the bg command to continue it  in
       the background, the fg command to continue it in the fore-
       ground, or the kill command to kill it.  A ^Z takes effect
       immediately, and has the additional side effect of causing
       pending output and typeahead to be discarded.




GNU                        1999 Jan 20                         41





BASH(1)                                                   BASH(1)


       There are a number of ways to refer to a job in the shell.
       The  character  %% introduces a job name.  Job number _n may
       be referred to as %%nn.  A job may also be referred to using
       a  prefix  of  the  name used to start it, or using a sub-
       string that appears in its command line.  For example, %ce
       refers to a stopped ce job.  If a prefix matches more than
       one job, bash reports an error.  Using %?ce, on the  other
       hand,  refers  to  any job containing the string ce in its
       command line.  If the substring matches more than one job,
       bash reports an error.  The symbols %%%% and %%++ refer to the
       shell's notion of the current job, which is the  last  job
       stopped  while  it was in the foreground or started in the
       background.  The previous job may be referenced using  %%--.
       In output pertaining to jobs (e.g., the output of the jobs
       command), the current job is always flagged with a ++,  and
       the previous job with a --.

       Simply naming a job can be used to bring it into the fore-
       ground: %%11 is a synonym for ``fg %%11'''', bringing job 1 from
       the  background  into the foreground.  Similarly, ````%%11 &&''''
       resumes job 1 in the background, equivalent to ``bg  %%11''''.

       The shell learns immediately whenever a job changes state.
       Normally, bash waits until it is about to print  a  prompt
       before  reporting  changes  in a job's status so as to not
       interrupt any other output.  If the -b option to  the  set
       builtin  command  is  enabled,  bash  reports such changes
       immediately.

       If an attempt to exit bash is made while jobs are stopped,
       the  shell prints a warning message.  The jobs command may
       then be used to inspect their status.  If a second attempt
       to  exit is made without an intervening command, the shell
       does not print another warning, and the stopped  jobs  are
       terminated.

PROMPTING
       When  executing  interactively,  bash displays the primary
       prompt PS1 when it is ready to read  a  command,  and  the
       secondary  prompt PS2 when it needs more input to complete
       a command.  Bash allows these prompt strings  to  be  cus-
       tomized by inserting a number of backslash-escaped special
       characters that are decoded as follows:
              \a     an ASCII bell character (07)
              \d     the date  in  "Weekday  Month  Date"  format
                     (e.g., "Tue May 26")
              \e     an ASCII escape character (033)
              \h     the hostname up to the first `.'
              \H     the hostname
              \n     newline
              \r     carriage return
              \s     the  name  of  the shell, the basename of $$00
                     (the portion following the final slash)
              \t     the current time in 24-hour HH:MM:SS format



GNU                        1999 Jan 20                         42





BASH(1)                                                   BASH(1)


              \T     the current time in 12-hour HH:MM:SS format
              \\@@     the current time in 12-hour am/pm format
              \u     the username of the current user
              \v     the version of bash (e.g., 2.00)
              \V     the release of bash,  version  +  patchlevel
                     (e.g., 2.00.0)
              \w     the current working directory
              \W     the  basename  of the current working direc-
                     tory
              \\!!     the history number of this command
              \\##     the command number of this command
              \\$$     if the effective UID is 0, a ##, otherwise  a
                     $$
              \\nnn   the  character  corresponding  to  the octal
                     number nnn
              \\\\     a backslash
              \\[[     begin a sequence of non-printing characters,
                     which could be used to embed a terminal con-
                     trol sequence into the prompt
              \\]]     end a sequence of non-printing characters

       The command number and the history number are usually dif-
       ferent: the history number of a command is its position in
       the history list, which may include commands restored from
       the  history  file  (see HISTORY below), while the command
       number is the position in the sequence  of  commands  exe-
       cuted  during the current shell session.  After the string
       is decoded, it is expanded via parameter  expansion,  com-
       mand substitution, arithmetic expansion, string expansion,
       and quote removal, subject to the value of the  promptvars
       shell  option  (see  the  description of the shopt command
       under SHELL BUILTIN COMMANDS below).

READLINE
       This is the library that handles reading input when  using
       an  interactive  shell,  unless  the --noediting option is
       given at shell invocation.  By default, the  line  editing
       commands  are  similar to those of emacs.  A vi-style line
       editing interface is also available.   To  turn  off  line
       editing after the shell is running, use the +o emacs or +o
       vi options to the set builtin (see SHELL BUILTIN  COMMANDS
       below).

   Readline Notation
       In  this  section,  the  emacs-style  notation  is used to
       denote keystrokes.  Control keys  are  denoted  by  C-key,
       e.g.,  C-n  means  Control-N.   Similarly,  meta  keys are
       denoted by M-key, so  M-x  means  Meta-X.   (On  keyboards
       without  a  meta  key,  M-_x  means  ESC _x, i.e., press the
       Escape key then the _x key.  This makes ESC the  meta  pre-
       fix.   The combination M-C-_x means ESC-Control-_x, or press
       the Escape key then hold the Control  key  while  pressing
       the _x key.)




GNU                        1999 Jan 20                         43





BASH(1)                                                   BASH(1)


       Readline  commands  may  be given numeric arguments, which
       normally act as a repeat count.  Sometimes, however, it is
       the  sign  of the argument that is significant.  Passing a
       negative argument to a command that acts  in  the  forward
       direction  (e.g., kill-line) causes that command to act in
       a backward direction.  Commands whose behavior with  argu-
       ments deviates from this are noted below.

       When  a  command  is  described  as killing text, the text
       deleted is saved for possible future retrieval  (yanking).
       The  killed  text  is  saved  in a kill ring.  Consecutive
       kills cause the text to  be  accumulated  into  one  unit,
       which  can  be  yanked all at once.  Commands which do not
       kill text separate the chunks of text on the kill ring.

   Readline Initialization
       Readline is customized by putting commands in an  initial-
       ization file (the inputrc file).  The name of this file is
       taken from the value of the  INPUTRC  variable.   If  that
       variable is unset, the default is ~/.inputrc.  When a pro-
       gram which uses the readline library starts up,  the  ini-
       tialization  file  is read, and the key bindings and vari-
       ables are set.  There are  only  a  few  basic  constructs
       allowed  in the readline initialization file.  Blank lines
       are ignored.  Lines  beginning  with  a  ##  are  comments.
       Lines  beginning with a $$ indicate conditional constructs.
       Other lines denote key bindings and variable settings.

       The default key-bindings may be changed  with  an  inputrc
       file.   Other programs that use this library may add their
       own commands and bindings.

       For example, placing

              M-Control-u: universal-argument
       or
              C-Meta-u: universal-argument
       into the inputrc would make  M-C-u  execute  the  readline
       command universal-argument.

       The  following  symbolic  character  names are recognized:
       RUBOUT, DEL, ESC, LFD, NEWLINE, RET, RETURN,  SPC,  SPACE,
       and  TAB.   In  addition to command names, readline allows
       keys to be bound to a string that is inserted when the key
       is pressed (a macro).

   Readline Key Bindings
       The  syntax  for  controlling  key bindings in the inputrc
       file is simple.  All that is required is the name  of  the
       command or the text of a macro and a key sequence to which
       it should be bound. The name may be specified  in  one  of
       two  ways:  as a symbolic key name, possibly with Meta- or
       Control- prefixes, or as a key sequence.  When  using  the
       form  keyname:function-name  or macro, keyname is the name



GNU                        1999 Jan 20                         44





BASH(1)                                                   BASH(1)


       of a key spelled out in English.  For example:

              Control-u: universal-argument
              Meta-Rubout: backward-kill-word
              Control-o: "> output"

       In the above example, C-u is bound to the function univer-
       sal-argument,   M-DEL  is  bound  to  the  function  back-
       ward-kill-word,  and  C-o  is  bound  to  run  the   macro
       expressed  on  the right hand side (that is, to insert the
       text _> output into the line).

       In the second form, "keyseq":function-name or macro,  key-
       seq differs from keyname above in that strings denoting an
       entire key  sequence  may  be  specified  by  placing  the
       sequence  within  double quotes.  Some GNU Emacs style key
       escapes can be used, as in the following example.

              "\C-u": universal-argument
              "\C-x\C-r": re-read-init-file
              "\e[11~": "Function Key 1"

       In this example, C-u is again bound to the  function  uni-
       versal-argument.    C-x  C-r  is  bound  to  the  function
       re-read-init-file, and ESC _[ _1 _1 _~ is bound to insert  the
       text  Function  Key  11.   The  full set of GNU Emacs style
       escape sequences is
              \C-    control prefix
              \M-    meta prefix
              \e     an escape character
              \\\\     backslash
              \\""     literal "
              \\''     literal '

       In addition to the GNU Emacs  style  escape  sequences,  a
       second set of backslash escapes is available:
              \a     alert (bell)
              \b     backspace
              \d     delete
              \f     form feed
              \n     newline
              \r     carriage return
              \t     horizontal tab
              \v     vertical tab
              \\nnn   the  character whose ASCII code is the octal
                     value nnn (one to three digits)
              \\xxnnn  the character whose ASCII code is  the  hex-
                     adecimal value nnn (one to three digits)

       When entering the text of a macro, single or double quotes
       must be used to indicate  a  macro  definition.   Unquoted
       text is assumed to be a function name.  In the macro body,
       the backslash escapes described above are expanded.  Back-
       slash  will  quote  any other character in the macro text,



GNU                        1999 Jan 20                         45





BASH(1)                                                   BASH(1)


       including " and '.

       Bash allows the current readline key bindings to  be  dis-
       played  or  modified  with  the bind builtin command.  The
       editing mode may be switched  during  interactive  use  by
       using  the -o option to the set builtin command (see SHELL
       BUILTIN COMMANDS below).

   Readline Variables
       Readline has variables that can be used  to  further  cus-
       tomize its behavior.  A variable may be set in the inputrc
       file with a statement of the form

              set variable-name value

       Except where noted, readline variables can take the values
       On or Off.  The variables and their default values are:

       bell-style (audible)
              Controls  what  happens when readline wants to ring
              the terminal bell.  If set to none, readline  never
              rings the bell.  If set to visible, readline uses a
              visible bell if one is available.  If set to  audi-
              ble, readline attempts to ring the terminal's bell.
       comment-begin ((````##''''))
              The string  that  is  inserted  when  the  readline
              insert-comment  command  is executed.  This command
              is bound to M-# in emacs mode and to ## in  vi  com-
              mand mode.
       completion-ignore-case (Off)
              If  set  to On, readline performs filename matching
              and completion in a case-insensitive fashion.
       completion-query-items ((110000))
              This determines when  the  user  is  queried  about
              viewing  the  number of possible completions gener-
              ated by the possible-completions command.   It  may
              be  set  to any integer value greater than or equal
              to zero.  If the number of possible completions  is
              greater  than  or  equal to the value of this vari-
              able, the user is asked whether or not he wishes to
              view  them; otherwise they are simply listed on the
              terminal.
       convert-meta (On)
              If set to On, readline will convert characters with
              the  eighth  bit  set  to  an ASCII key sequence by
              stripping the eighth bit and prepending  an  escape
              character (in effect, using escape as the meta pre-
              fix).
       disable-completion (Off)
              If set to On, readline will  inhibit  word  comple-
              tion.   Completion characters will be inserted into
              the line as if they had been mapped to self-insert.
       editing-mode (emacs)
              Controls  whether readline begins with a set of key



GNU                        1999 Jan 20                         46





BASH(1)                                                   BASH(1)


              bindings similar to emacs or vi.  editing-mode  can
              be set to either emacs or vi.
       enable-keypad (Off)
              When  set  to  On,  readline will try to enable the
              application keypad when it is called.  Some systems
              need this to enable the arrow keys.
       expand-tilde (Off)
              If  set  to  on,  tilde expansion is performed when
              readline attempts word completion.
       horizontal-scroll-mode (Off)
              When set to On, makes readline use  a  single  line
              for  display, scrolling the input horizontally on a
              single screen line when it becomes longer than  the
              screen width rather than wrapping to a new line.
       input-meta (Off)
              If  set to On, readline will enable eight-bit input
              (that is, it will not strip the high bit  from  the
              characters it reads), regardless of what the termi-
              nal claims it can support.  The name meta-flag is a
              synonym for this variable.
       isearch-terminators (``C-[C-J'')
              The  string  of characters that should terminate an
              incremental search without  subsequently  executing
              the  character  as a command.  If this variable has
              not been given a value, the characters ESC and  C-J
              will terminate an incremental search.
       keymap (emacs)
              Set  the current readline keymap.  The set of valid
              keymap names is emacs, emacs-standard,  emacs-meta,
              emacs-ctlx,  vi,  vi-command, and vi-insert.  vi is
              equivalent to vi-command; emacs  is  equivalent  to
              emacs-standard.   The  default  value is emacs; the
              value of  editing-mode  also  affects  the  default
              keymap.
       mark-directories (On)
              If  set  to  On,  completed  directory names have a
              slash appended.
       mark-modified-lines (Off)
              If set to On, history lines that have been modified
              are displayed with a preceding asterisk (**).
       output-meta (Off)
              If set to On, readline will display characters with
              the eighth bit set directly rather than as a  meta-
              prefixed escape sequence.
       print-completions-horizontally (Off)
              If  set  to  On,  readline will display completions
              with matches sorted  horizontally  in  alphabetical
              order, rather than down the screen.
       show-all-if-ambiguous (Off)
              This  alters the default behavior of the completion
              functions.  If set to on,  words  which  have  more
              than  one  possible completion cause the matches to
              be listed immediately instead of ringing the  bell.




GNU                        1999 Jan 20                         47





BASH(1)                                                   BASH(1)


       visible-stats (Off)
              If set to On, a character denoting a file's type as
              reported by stat(2) is  appended  to  the  filename
              when listing possible completions.

   Readline Conditional Constructs
       Readline  implements  a  facility similar in spirit to the
       conditional compilation features  of  the  C  preprocessor
       which allows key bindings and variable settings to be per-
       formed as the result of  tests.   There  are  four  parser
       directives used.

       $if    The  $if construct allows bindings to be made based
              on the editing mode, the terminal  being  used,  or
              the  application  using  readline.  The text of the
              test extends to the end of the line; no  characters
              are required to isolate it.

              mode   The  mode= form of the $if directive is used
                     to test whether readline is in emacs  or  vi
                     mode.   This may be used in conjunction with
                     the set keymap command, for instance, to set
                     bindings    in    the   emacs-standard   and
                     emacs-ctlx  keymaps  only  if  readline   is
                     starting out in emacs mode.

              term   The term= form may be used to include termi-
                     nal-specific key bindings, perhaps  to  bind
                     the  key  sequences output by the terminal's
                     function keys.  The word on the  right  side
                     of  the  ==  is  tested against the both full
                     name of the terminal and the portion of  the
                     terminal  name  before  the  first  --.  This
                     allows sun to match both  sun  and  sun-cmd,
                     for instance.

              application
                     The application construct is used to include
                     application-specific settings.  Each program
                     using the readline library sets the applica-
                     tion name, and an  initialization  file  can
                     test  for a particular value.  This could be
                     used to bind key sequences to functions use-
                     ful  for  a specific program.  For instance,
                     the following command adds  a  key  sequence
                     that  quotes the current or previous word in
                     Bash:

                     $if Bash
                     # Quote the current or previous word
                     "\C-xq": "\eb\"\ef\""
                     $endif

       $endif This command, as  seen  in  the  previous  example,



GNU                        1999 Jan 20                         48





BASH(1)                                                   BASH(1)


              terminates an $if command.

       $else  Commands  in  this  branch of the $if directive are
              executed if the test fails.

       $include
              This directive takes a single filename as an  argu-
              ment  and  reads  commands  and  bindings from that
              file.  For example, the following  directive  would
              read /etc/inputrc:

              $include  /etc/inputrc

   Searching
       Readline  provides commands for searching through the com-
       mand history (see HISTORY below) for  lines  containing  a
       specified string.  There are two search modes: incremental
       and non-incremental.

       Incremental searches begin before the  user  has  finished
       typing the search string.  As each character of the search
       string is typed, readline displays the next entry from the
       history  matching the string typed so far.  An incremental
       search requires only as many characters as needed to  find
       the  desired history entry.  The characters present in the
       value of the isearch-terminators variable are used to ter-
       minate  an  incremental  search.  If that variable has not
       been assigned a value the Escape and Control-J  characters
       will  terminate  an  incremental  search.   Control-G will
       abort an incremental search and restore the original line.
       When  the search is terminated, the history entry contain-
       ing the search string becomes the current line.   To  find
       other matching entries in the history list, type Control-S
       or Control-R as appropriate.  This will search backward or
       forward  in  the  history  for the next entry matching the
       search string typed so far.  Any other key sequence  bound
       to  a  readline command will terminate the search and exe-
       cute that command.  For instance, a newline will terminate
       the search and accept the line, thereby executing the com-
       mand from the history list.

       Non-incremental searches read  the  entire  search  string
       before starting to search for matching history lines.  The
       search string may be typed by the user or be part  of  the
       contents of the current line.

   Readline Command Names
       The  following  is a list of the names of the commands and
       the default key sequences to which they are  bound.   Com-
       mand  names  without  an  accompanying  key  sequence  are
       unbound by default.

   Commands for Moving




GNU                        1999 Jan 20                         49





BASH(1)                                                   BASH(1)


       beginning-of-line (C-a)
              Move to the start of the current line.
       end-of-line (C-e)
              Move to the end of the line.
       forward-char (C-f)
              Move forward a character.
       backward-char (C-b)
              Move back a character.
       forward-word (M-f)
              Move forward to the end of the  next  word.   Words
              are  composed  of  alphanumeric characters (letters
              and digits).
       backward-word (M-b)
              Move back to the start of this,  or  the  previous,
              word.   Words  are composed of alphanumeric charac-
              ters (letters and digits).
       clear-screen (C-l)
              Clear the screen leaving the current  line  at  the
              top  of  the screen.  With an argument, refresh the
              current line without clearing the screen.
       redraw-current-line
              Refresh the current line.

   Commands for Manipulating the History
       accept-line (Newline, Return)
              Accept the line regardless of where the cursor  is.
              If  this  line  is non-empty, add it to the history
              list according to  the  state  of  the  HISTCONTROL
              variable.   If the line is a modified history line,
              then restore  the  history  line  to  its  original
              state.
       previous-history (C-p)
              Fetch  the  previous command from the history list,
              moving back in the list.
       next-history (C-n)
              Fetch the next command from the history list,  mov-
              ing forward in the list.
       beginning-of-history (M-<)
              Move to the first line in the history.
       end-of-history (M->)
              Move  to  the  end  of the input history, i.e., the
              line currently being entered.
       reverse-search-history (C-r)
              Search backward starting at the  current  line  and
              moving `up' through the history as necessary.  This
              is an incremental search.
       forward-search-history (C-s)
              Search forward starting at  the  current  line  and
              moving  `down'  through  the  history as necessary.
              This is an incremental search.
       non-incremental-reverse-search-history (M-p)
              Search backward through the history starting at the
              current  line  using a non-incremental search for a
              string supplied by the user.



GNU                        1999 Jan 20                         50





BASH(1)                                                   BASH(1)


       non-incremental-forward-search-history (M-n)
              Search forward through the  history  using  a  non-
              incremental  search  for  a  string supplied by the
              user.
       history-search-forward
              Search forward through the history for  the  string
              of characters between the start of the current line
              and the current cursor position (the point).   This
              is a non-incremental search.
       history-search-backward
              Search  backward through the history for the string
              of characters between the start of the current line
              and the point.  This is a non-incremental search.
       yank-nth-arg (M-C-y)
              Insert  the  first argument to the previous command
              (usually the second word on the previous  line)  at
              point (the current cursor position).  With an argu-
              ment _n, insert the _nth word from the previous  com-
              mand  (the words in the previous command begin with
              word 0).  A negative argument inserts the _nth  word
              from the end of the previous command.
       yank-last-arg (M-., M-_)
              Insert  the  last  argument to the previous command
              (the last word  of  the  previous  history  entry).
              With an argument, behave exactly like yank-nth-arg.
              Successive calls to yank-last-arg move back through
              the  history  list,  inserting the last argument of
              each line in turn.
       shell-expand-line (M-C-e)
              Expand the line as the shell does.   This  performs
              alias  and  history expansion as well as all of the
              shell word expansions.  See HISTORY EXPANSION below
              for a description of history expansion.
       history-expand-line (M-^)
              Perform history expansion on the current line.  See
              HISTORY EXPANSION below for a description  of  his-
              tory expansion.
       magic-space
              Perform  history  expansion on the current line and
              insert a space.  See HISTORY EXPANSION below for  a
              description of history expansion.
       alias-expand-line
              Perform  alias  expansion on the current line.  See
              ALIASES above for a description of alias expansion.
       history-and-alias-expand-line
              Perform  history and alias expansion on the current
              line.
       insert-last-argument (M-., M-_)
              A synonym for yank-last-arg.
       operate-and-get-next (C-o)
              Accept the current line for execution and fetch the
              next  line  relative  to  the current line from the
              history for editing.  Any argument is ignored.




GNU                        1999 Jan 20                         51





BASH(1)                                                   BASH(1)


   Commands for Changing Text
       delete-char (C-d)
              Delete the character under the cursor.  If point is
              at  the beginning of the line, there are no charac-
              ters in the line, and the last character typed  was
              not bound to delete-char, then return EOF.
       backward-delete-char (Rubout)
              Delete the character behind the cursor.  When given
              a numeric argument, save the deleted  text  on  the
              kill ring.
       forward-backward-delete-char
              Delete  the  character under the cursor, unless the
              cursor is at the end of the line, in which case the
              character   behind   the  cursor  is  deleted.   By
              default, this is not bound to a key.
       quoted-insert (C-q, C-v)
              Add the next character typed to the line  verbatim.
              This  is  how  to  insert  characters like C-q, for
              example.
       tab-insert (C-v TAB)
              Insert a tab character.
       self-insert (a, b, A, 11,, !!,, ......))
              Insert the character typed.
       transpose-chars (C-t)
              Drag the character before point  forward  over  the
              character  at  point.  Point moves forward as well.
              If point is at the end of the line, then  transpose
              the  two  characters  before point.  Negative argu-
              ments don't work.
       transpose-words (M-t)
              Drag the word behind the cursor past  the  word  in
              front  of  the  cursor  moving the cursor over that
              word as well.
       upcase-word (M-u)
              Uppercase the current (or following) word.  With  a
              negative argument, uppercase the previous word, but
              do not move point.
       downcase-word (M-l)
              Lowercase the current (or following) word.  With  a
              negative argument, lowercase the previous word, but
              do not move point.
       capitalize-word (M-c)
              Capitalize the current (or following) word.  With a
              negative  argument,  capitalize  the previous word,
              but do not move point.

   Killing and Yanking
       kill-line (C-k)
              Kill the text from the current cursor  position  to
              the end of the line.
       backward-kill-line (C-x Rubout)
              Kill backward to the beginning of the line.
       unix-line-discard (C-u)
              Kill  backward  from  point to the beginning of the



GNU                        1999 Jan 20                         52





BASH(1)                                                   BASH(1)


              line.  The killed text is saved on the kill-ring.

       kill-whole-line
              Kill all characters on the current line, no  matter
              where the cursor is.
       kill-word (M-d)
              Kill  from  the  cursor  to  the end of the current
              word, or if between words, to the end of  the  next
              word.   Word  boundaries are the same as those used
              by forward-word.
       backward-kill-word (M-Rubout)
              Kill the word behind the cursor.   Word  boundaries
              are the same as those used by backward-word.
       unix-word-rubout (C-w)
              Kill  the word behind the cursor, using white space
              as a word boundary.  The word boundaries  are  dif-
              ferent from backward-kill-word.
       delete-horizontal-space (M-\)
              Delete all spaces and tabs around point.
       kill-region
              Kill  the  text  between  the point and mark (saved
              cursor position).  This text is referred to as  the
              region.
       copy-region-as-kill
              Copy the text in the region to the kill buffer.
       copy-backward-word
              Copy the word before point to the kill buffer.  The
              word boundaries are the same as backward-word.
       copy-forward-word
              Copy the word following point to the  kill  buffer.
              The word boundaries are the same as forward-word.
       yank (C-y)
              Yank  the  top  of the kill ring into the buffer at
              the cursor.
       yank-pop (M-y)
              Rotate the kill ring, and yank the new  top.   Only
              works following yank or yank-pop.

   Numeric Arguments
       digit-argument (M-0, M-1, ......,, M--)
              Add  this  digit to the argument already accumulat-
              ing, or start a new argument.  M-- starts  a  nega-
              tive argument.
       universal-argument
              This  is  another  way  to specify an argument.  If
              this command is followed by  one  or  more  digits,
              optionally  with a leading minus sign, those digits
              define the argument.  If the command is followed by
              digits, executing universal-argument again ends the
              numeric argument, but is otherwise ignored.   As  a
              special  case,  if this command is immediately fol-
              lowed by a character that is  neither  a  digit  or
              minus sign, the argument count for the next command
              is multiplied  by  four.   The  argument  count  is



GNU                        1999 Jan 20                         53





BASH(1)                                                   BASH(1)


              initially one, so executing this function the first
              time makes the argument count four, a  second  time
              makes the argument count sixteen, and so on.

   Completing
       complete (TAB)
              Attempt  to  perform  completion on the text before
              point.  Bash attempts completion treating the  text
              as a variable (if the text begins with $$), username
              (if the text begins with ~~), hostname (if the  text
              begins  with  @@), or command (including aliases and
              functions) in turn.  If none of  these  produces  a
              match, filename completion is attempted.
       possible-completions (M-?)
              List  the  possible  completions of the text before
              point.
       insert-completions (M-*)
              Insert all completions of  the  text  before  point
              that  would have been generated by possible-comple-
              tions.
       menu-complete
              Similar to complete, but replaces the  word  to  be
              completed with a single match from the list of pos-
              sible completions.  Repeated execution of menu-com-
              plete  steps  through  the list of possible comple-
              tions, inserting each match in turn.  At the end of
              the  list  of completions, the bell is rung and the
              original text is restored.  An argument of _n  moves
              _n positions forward in the list of matches; a nega-
              tive argument may be used to move backward  through
              the  list.  This command is intended to be bound to
              TAB, but is unbound by default.
       delete-char-or-list
              Deletes the character under the cursor  if  not  at
              the  beginning  or  end  of  the line (like delete-
              char).  If at the end of the line, behaves  identi-
              cally  to  possible-completions.   This  command is
              unbound by default.
       complete-filename (M-/)
              Attempt filename  completion  on  the  text  before
              point.
       possible-filename-completions (C-x //))
              List  the  possible  completions of the text before
              point, treating it as a filename.
       complete-username (M-~)
              Attempt completion on the text before point, treat-
              ing it as a username.
       possible-username-completions (C-x ~~))
              List  the  possible  completions of the text before
              point, treating it as a username.
       complete-variable (M-$)
              Attempt completion on the text before point, treat-
              ing it as a shell variable.




GNU                        1999 Jan 20                         54





BASH(1)                                                   BASH(1)


       possible-variable-completions (C-x $$))
              List  the  possible  completions of the text before
              point, treating it as a shell variable.
       complete-hostname (M-@)
              Attempt completion on the text before point, treat-
              ing it as a hostname.
       possible-hostname-completions (C-x @@))
              List  the  possible  completions of the text before
              point, treating it as a hostname.
       complete-command (M-!)
              Attempt completion on the text before point, treat-
              ing  it  as  a  command  name.   Command completion
              attempts  to  match  the  text   against   aliases,
              reserved  words,  shell  functions, shell builtins,
              and finally executable filenames, in that order.
       possible-command-completions (C-x !!))
              List the possible completions of  the  text  before
              point, treating it as a command name.
       dynamic-complete-history (M-TAB)
              Attempt  completion  on the text before point, com-
              paring the text against lines from the history list
              for possible completion matches.
       complete-into-braces (M-{)
              Perform  filename completion and return the list of
              possible completions enclosed within braces so  the
              list is available to the shell (see Brace Expansion
              above).

   Keyboard Macros
       start-kbd-macro (C-x (())
              Begin saving the characters typed into the  current
              keyboard macro.
       end-kbd-macro (C-x ))))
              Stop  saving  the characters typed into the current
              keyboard macro and store the definition.
       call-last-kbd-macro (C-x e)
              Re-execute the last keyboard macro defined, by mak-
              ing  the characters in the macro appear as if typed
              at the keyboard.

   Miscellaneous
       re-read-init-file (C-x C-r)
              Read in the  contents  of  the  inputrc  file,  and
              incorporate  any  bindings  or variable assignments
              found there.
       abort (C-g)
              Abort the current editing command and ring the ter-
              minal's   bell   (subject   to   the   setting   of
              bell-style).
       do-uppercase-version (M-a, M-b, MM--_x,, ......))
              If the metafied character _x is lowercase,  run  the
              command  that  is bound to the corresponding upper-
              case character.




GNU                        1999 Jan 20                         55





BASH(1)                                                   BASH(1)


       prefix-meta (ESC)
              Metafy the next character typed.  ESC ff is  equiva-
              lent to Meta-f.
       undo (C-_, C-x C-u)
              Incremental  undo,  separately  remembered for each
              line.
       revert-line (M-r)
              Undo all changes made to this line.  This  is  like
              executing  the  undo command enough times to return
              the line to its initial state.
       tilde-expand (M-&)
              Perform tilde expansion on the current word.
       set-mark (C-@, M-<space>)
              Set the mark to the current point.   If  a  numeric
              argument is supplied, the mark is set to that posi-
              tion.
       exchange-point-and-mark (C-x C-x)
              Swap the point with the mark.  The  current  cursor
              position  is set to the saved position, and the old
              cursor position is saved as the mark.
       character-search (C-])
              A character is read and point is moved to the  next
              occurrence  of  that  character.   A negative count
              searches for previous occurrences.
       character-search-backward (M-C-])
              A character is read and point is moved to the  pre-
              vious  occurrence  of  that  character.  A negative
              count searches for subsequent occurrences.
       insert-comment (M-#)
              The value of the readline comment-begin variable is
              inserted  at the beginning of the current line, and
              the line is accepted  as  if  a  newline  had  been
              typed.   This  makes  the current line a shell com-
              ment.
       glob-expand-word (C-x **))
              The word before point is treated as a  pattern  for
              pathname  expansion,  and the list of matching file
              names is inserted, replacing the word.
       glob-list-expansions (C-x g)
              The list of expansions that would have been  gener-
              ated by glob-expand-word is displayed, and the line
              is redrawn.
       dump-functions
              Print all of the functions and their  key  bindings
              to  the readline output stream.  If a numeric argu-
              ment is supplied, the output is formatted in such a
              way that it can be made part of an inputrc file.
       dump-variables
              Print  all  of  the settable readline variables and
              their values to the readline output stream.   If  a
              numeric argument is supplied, the output is format-
              ted in such a way that it can be made  part  of  an
              inputrc file.




GNU                        1999 Jan 20                         56





BASH(1)                                                   BASH(1)


       dump-macros
              Print  all  of  the readline key sequences bound to
              macros and the strings they ouput.   If  a  numeric
              argument  is  supplied,  the output is formatted in
              such a way that it can be made part of  an  inputrc
              file.
       display-shell-version (C-x C-v)
              Display   version  information  about  the  current
              instance of bash.

HISTORY
       When the -o history option to the set builtin is  enabled,
       the shell provides access to the command history, the list
       of commands previously typed.  The text of the last  HIST-
       SIZE  commands  (default  500) is saved in a history list.
       The shell stores each command in the history list prior to
       parameter and variable expansion (see EXPANSION above) but
       after history expansion is performed, subject to the  val-
       ues of the shell variables HISTIGNORE and HISTCONTROL.  On
       startup, the history is initialized from the file named by
       the variable HISTFILE (default ~/.bash__history).  HISTFILE
       is truncated, if necessary, to contain no more than  HIST-
       FILESIZE lines.  When an interactive shell exits, the last
       HISTSIZE lines are copied from the history list  to  HIST-
       FILE.   If the histappend shell option is enabled (see the
       description of shopt under SHELL BUILTIN COMMANDS  below),
       the  lines are appended to the history file, otherwise the
       history file is overwritten.  If HISTFILE is unset, or  if
       the  history file is unwritable, the history is not saved.
       After saving the history, the history file is truncated to
       contain  no more than HISTFILESIZE lines.  If HISTFILESIZE
       is not set, no truncation is performed.

       The builtin command fc (see SHELL BUILTIN COMMANDS  below)
       may  be  used  to list or edit and re-execute a portion of
       the history list.  The history builtin can be used to dis-
       play or modify the history list and manipulate the history
       file.  When using the command-line  editing,  search  com-
       mands  are  available  in  each  editing mode that provide
       access to the history list.

       The shell allows control over which commands are saved  on
       the  history  list.   The HISTCONTROL and HISTIGNORE vari-
       ables may be set to cause the shell to save only a  subset
       of  the  commands  entered.   The cmdhist shell option, if
       enabled, causes the shell to attempt to save each line  of
       a  multi-line  command  in  the same history entry, adding
       semicolons where necessary to preserve syntactic  correct-
       ness.   The  lithist shell option causes the shell to save
       the command with embedded newlines instead of  semicolons.
       See the description of the shopt builtin below under SHELL
       BUILTIN COMMANDS for information on setting and  unsetting
       shell options.




GNU                        1999 Jan 20                         57





BASH(1)                                                   BASH(1)


HISTORY EXPANSION
       The  shell  supports  a  history expansion feature that is
       similar to the history expansion  in  csh.   This  section
       describes  what  syntax features are available.  This fea-
       ture is enabled by default for interactive shells, and can
       be disabled using the +H option to the set builtin command
       (see  SHELL  BUILTIN  COMMANDS  below).    Non-interactive
       shells do not perform history expansion by default.

       History  expansions  introduce words from the history list
       into the input stream, making it easy to repeat  commands,
       insert  the  arguments to a previous command into the cur-
       rent input  line,  or  fix  errors  in  previous  commands
       quickly.

       History  expansion  is  performed immediately after a com-
       plete line is read, before the shell breaks it into words.
       It  takes  place  in two parts.  The first is to determine
       which line from the history list to use  during  substitu-
       tion.   The  second is to select portions of that line for
       inclusion into the current one.  The  line  selected  from
       the  history  is  the event, and the portions of that line
       that are acted upon  are  words.   Various  modifiers  are
       available  to  manipulate the selected words.  The line is
       broken into words in the  same  fashion  as  when  reading
       input,  so that several metacharacter-separated words sur-
       rounded by quotes are considered one word.  History expan-
       sions  are  introduced  by  the  appearance of the history
       expansion character, which is !! by  default.   Only  back-
       slash  (\\)  and single quotes can quote the history expan-
       sion character.

       Several shell options settable with the shopt builtin  may
       be  used  to tailor the behavior of history expansion.  If
       the histverify shell option is enabled (see  the  descrip-
       tion  of  the  shopt builtin), and readline is being used,
       history substitutions are not immediately  passed  to  the
       shell parser.  Instead, the expanded line is reloaded into
       the readline editing buffer for further modification.   If
       readline is being used, and the histreedit shell option is
       enabled, a failed history substitution  will  be  reloaded
       into  the  readline editing buffer for correction.  The -p
       option to the history builtin command may be used  to  see
       what  a history expansion will do before using it.  The -s
       option to the history builtin may be used to add  commands
       to  the end of the history list without actually executing
       them, so that they are available for subsequent recall.

       The shell allows control of the various characters used by
       the  history  expansion  mechanism (see the description of
       histchars above under Shell Variables).

   Event Designators
       An event designator is a reference to a command line entry



GNU                        1999 Jan 20                         58





BASH(1)                                                   BASH(1)


       in the history list.

       !!      Start  a history substitution, except when followed
              by a blank, newline, = or (.
       !!_n     Refer to command line _n.
       !!--_n    Refer to the current command line minus _n.
       !!!!     Refer to the previous command.  This is  a  synonym
              for `!-1'.
       !!string
              Refer  to  the  most  recent  command starting with
              string.
       !!??string[[??]]
              Refer to the most recent command containing string.
              The trailing ?? may be omitted if string is followed
              immediately by a newline.
       ^^string1^^string2^^
              Quick  substitution.   Repeat  the  last   command,
              replacing  string1  with  string2.   Equivalent  to
              ``!!:s/string1/string2/'' (see Modifiers below).
       !!##     The entire command line typed so far.

   Word Designators
       Word designators are used to select desired words from the
       event.   A  ::  separates  the event specification from the
       word designator.  It may be omitted if the word designator
       begins  with  a ^^, $$, **, --, or %%.  Words are numbered from
       the beginning of the  line,  with  the  first  word  being
       denoted  by 0 (zero).  Words are inserted into the current
       line separated by single spaces.

       00 (zero)
              The zeroth word.  For the shell, this is  the  com-
              mand word.
       _n      The _nth word.
       ^^      The first argument.  That is, word 1.
       $$      The last argument.
       %%      The  word  matched  by  the  most recent `?string?'
              search.
       _x--_y    A range of words; `-_y' abbreviates `0-_y'.
       **      All of the words but the zeroth.  This is a synonym
              for `_1_-_$'.  It is not an error to use ** if there is
              just one word in the event;  the  empty  string  is
              returned in that case.
       x*     Abbreviates _x_-_$.
       x-     Abbreviates x-$ like xx**, but omits the last word.

       If a word designator is supplied without an event specifi-
       cation, the previous command is used as the event.

   Modifiers
       After the optional word designator,  there  may  appear  a
       sequence  of  one or more of the following modifiers, each
       preceded by a `:'.




GNU                        1999 Jan 20                         59





BASH(1)                                                   BASH(1)


       hh      Remove a trailing file name component, leaving only
              the head.
       tt      Remove  all  leading  file name components, leaving
              the tail.
       rr      Remove a trailing suffix of the form .xxx,  leaving
              the basename.
       ee      Remove all but the trailing suffix.
       pp      Print the new command but do not execute it.
       qq      Quote  the substituted words, escaping further sub-
              stitutions.
       xx      Quote the substituted words as with  qq,  but  break
              into words at blanks and newlines.
       ss//old//new//
              Substitute  new  for the first occurrence of old in
              the event line.  Any delimiter can be used in place
              of /.  The final delimiter is optional if it is the
              last character of the event  line.   The  delimiter
              may  be  quoted  in old and new with a single back-
              slash.  If & appears in new, it is replaced by old.
              A  single  backslash  will  quote the &.  If old is
              null, it is set to the last old substituted, or, if
              no  previous  history substitutions took place, the
              last string in a !!??string[[??]]  search.
       &&      Repeat the previous substitution.
       gg      Cause changes to be applied over the  entire  event
              line.  This is used in conjunction with `::ss' (e.g.,
              `:gs/old//new//') or `::&&'.  If used  with  `::ss',  any
              delimiter  can be used in place of /, and the final
              delimiter is optional if it is the  last  character
              of the event line.

SHELL BUILTIN COMMANDS
       Unless otherwise noted, each builtin command documented in
       this section as accepting options preceded by -- accepts ----
       to signify the end of the options.
       :: [arguments]
              No  effect; the command does nothing beyond expand-
              ing arguments and performing any specified redirec-
              tions.  A zero exit code is returned.

        ..  filename [arguments]
       source filename [arguments]
              Read and execute commands from filename in the cur-
              rent shell environment and return the  exit  status
              of  the  last  command  executed from filename.  If
              filename does not contain a slash,  file  names  in
              PATH  are  used  to  find  the directory containing
              filename.  The file searched for in PATH  need  not
              be  executable.   The current directory is searched
              if no file is found in  PATH.   If  the  sourcepath
              option  to the shopt builtin command is turned off,
              the PATH is not searched.   If  any  arguments  are
              supplied,  they  become  the  positional parameters
              when   filename   is   executed.    Otherwise   the



GNU                        1999 Jan 20                         60





BASH(1)                                                   BASH(1)


              positional  parameters  are  unchanged.  The return
              status is the status of  the  last  command  exited
              within  the script (0 if no commands are executed),
              and false if filename is not  found  or  cannot  be
              read.

       alias [-p] [name[=value] ...]
              Alias  with  no  arguments  or  with  the -p option
              prints the  list  of  aliases  in  the  form  alias
              name=value  on standard output.  When arguments are
              supplied, an alias is defined for each  name  whose
              value  is given.  A trailing space in  value causes
              the next word to be checked for alias  substitution
              when  the  alias is expanded.  For each name in the
              argument list for which no value is  supplied,  the
              name  and  value  of  the  alias is printed.  Alias
              returns true unless a name is given  for  which  no
              alias has been defined.

       bg [jobspec]
              Resume the suspended job jobspec in the background,
              as if it had been started with &&.   If  jobspec  is
              not  present, the shell's notion of the current job
              is used.  bg jobspec returns 0 unless run when  job
              control  is  disabled or, when run with job control
              enabled, if jobspec was not found or started  with-
              out job control.

       bind [-m keymap] [-lpsvPSV]
       bind [-m keymap] [-q function] [-u function] [-r keyseq]
       bind [-m keymap] -f filename
       bind [-m keymap] keyseq:function-name
              Display current readline key and function bindings,
              or bind a key sequence to a  readline  function  or
              macro.  The binding syntax accepted is identical to
              that of .inputrc, but each binding must  be  passed
              as   a   separate   argument;   e.g.,  '"\C-x\C-r":
              re-read-init-file'.  Options, if supplied, have the
              following meanings:
              -m keymap
                     Use  keymap  as the keymap to be affected by
                     the subsequent bindings.  Acceptable  keymap
                     names are emacs, emacs-standard, emacs-meta,
                     emacs-ctlx, vi, vi-command,  and  vi-insert.
                     vi  is  equivalent  to  vi-command; emacs is
                     equivalent to emacs-standard.
              -l     List the names of all readline functions.
              -p     Display readline function names and bindings
                     in such a way that they can be re-read.
              -P     List  current  readline  function  names and
                     bindings.
              -v     Display readline variable names  and  values
                     in such a way that they can be re-read.
              -V     List  current  readline  variable  names and



GNU                        1999 Jan 20                         61





BASH(1)                                                   BASH(1)


                     values.
              -s     Display  readline  key  sequences  bound  to
                     macros and the strings they output in such a
                     way that they can be re-read.
              -S     Display  readline  key  sequences  bound  to
                     macros and the strings they output.
              -f filename
                     Read key bindings from filename.
              -q function
                     Query  about  which  keys  invoke  the named
                     function.
              -u function
                     Unbind all keys bound to the named function.
              -r keyseq
                     Remove any current binding for keyseq.

              The return value is 0 unless an unrecognized option
              is given or an error occurred.

       break [_n]
              Exit from within a for,  while,  until,  or  select
              loop.   If  _n is specified, break _n levels.  _n must
              be >= 1.  If  _n  is  greater  than  the  number  of
              enclosing  loops,  all  enclosing loops are exited.
              The return value is 0 unless the shell is not  exe-
              cuting a loop when break is executed.

       builtin shell-builtin [arguments]
              Execute  the  specified  shell  builtin, passing it
              arguments, and return its  exit  status.   This  is
              useful  when  defining a function whose name is the
              same as a shell builtin, retaining the  functional-
              ity  of  the  builtin  within the function.  The cd
              builtin is commonly redefined this way.  The return
              status  is  false  if  shell-builtin is not a shell
              builtin command.

       cd [-LP] [dir]
              Change the current directory to dir.  The  variable
              HOME  is  the  default  dir.   The  variable CDPATH
              defines the search path for the directory  contain-
              ing dir.  Alternative directory names in CDPATH are
              separated by a colon (:).  A null directory name in
              CDPATH  is the same as the current directory, i.e.,
              ``..''.  If dir begins with a slash (/), then CDPATH
              is not used. The -P option says to use the physical
              directory structure instead of  following  symbolic
              links  (see  also  the -P option to the set builtin
              command); the -L option forces symbolic links to be
              followed.   An argument of -- is equivalent to $OLD-
              PWD.  The return value is true if the directory was
              successfully changed; false otherwise.





GNU                        1999 Jan 20                         62





BASH(1)                                                   BASH(1)


       command [-pVv] command [arg ...]
              Run  command with args suppressing the normal shell
              function lookup. Only builtin commands or  commands
              found  in  the PATH are executed.  If the -p option
              is given, the search for command is performed using
              a default value for PATH that is guaranteed to find
              all of the standard utilities.  If either the -V or
              -v  option is supplied, a description of command is
              printed.  The -v option causes a single word  indi-
              cating the command or file name used to invoke com-
              mand to be displayed; the -V option produces a more
              verbose  description.   If  the  -V or -v option is
              supplied, the exit  status  is  0  if  command  was
              found, and 1 if not.  If neither option is supplied
              and an error occurred or command cannot  be  found,
              the exit status is 127.  Otherwise, the exit status
              of the command builtin is the exit status  of  com-
              mand.

       continue [_n]
              Resume  the  next  iteration  of the enclosing for,
              while, until, or select loop.  If _n  is  specified,
              resume  at the _nth enclosing loop.  _n must be >= 1.
              If _n is greater than the number of enclosing loops,
              the last enclosing loop (the ``top-level'' loop) is
              resumed.  The return value is 0 unless the shell is
              not executing a loop when continue is executed.

       declare [-afFirx] [-p] [name[=value]]
       typeset [-afFirx] [-p] [name[=value]]
              Declare  variables and/or give them attributes.  If
              no names are given then display the values of vari-
              ables.   The  -p option will display the attributes
              and values of each name.  When -p  is  used,  addi-
              tional options are ignored.  The -F option inhibits
              the display of function definitions; only the func-
              tion  name  and  attributes  are  printed.   The -F
              option implies -f.  The following  options  can  be
              used to restrict output to variables with the spec-
              ified attribute or to give variables attributes:
              -a     Each name is an array variable  (see  Arrays
                     above).
              -f     Use function names only.
              -i     The  variable  is  treated  as  an  integer;
                     arithmetic evaluation (see ARITHMETIC EVALU-
                     ATION  ))  is  performed when the variable is
                     assigned a value.
              -r     Make names  readonly.   These  names  cannot
                     then   be   assigned  values  by  subsequent
                     assignment statements or unset.
              -x     Mark names for export to subsequent commands
                     via the environment.

              Using  `+'  instead  of `-' turns off the attribute



GNU                        1999 Jan 20                         63





BASH(1)                                                   BASH(1)


              instead, with the exception that +a may not be used
              to destroy an array variable.  When used in a func-
              tion, makes each name local, as with the local com-
              mand.   The  return  value  is  0 unless an invalid
              option is encountered, an attempt is made to define
              a  function  using "-f foo=bar", an attempt is made
              to assign  a  value  to  a  readonly  variable,  an
              attempt is made to assign a value to an array vari-
              able without using the compound  assignment  syntax
              (see Arrays above), one of the names is not a valid
              shell variable name, an attempt is made to turn off
              readonly status for a readonly variable, an attempt
              is made to turn off array status for an array vari-
              able,  or an attempt is made to display a non-exis-
              tent function with -f.

       dirs [-clpv] [[++_n]] [[--_n]]
              Without options, displays  the  list  of  currently
              remembered  directories.  The default display is on
              a single line with  directory  names  separated  by
              spaces.  Directories are added to the list with the
              pushd command; the  popd  command  removes  entries
              from the list.
              ++_n     Displays  the  _nth  entry  counting from the
                     left of the list shown by dirs when  invoked
                     without options, starting with zero.
              --_n     Displays  the  _nth  entry  counting from the
                     right of the list shown by dirs when invoked
                     without options, starting with zero.
              -c     Clears  the  directory stack by deleting all
                     of the entries.
              -l     Produces a longer listing; the default list-
                     ing  format  uses a tilde to denote the home
                     directory.
              -p     Print the directory stack with one entry per
                     line.
              -v     Print the directory stack with one entry per
                     line, prefixing each entry with its index in
                     the stack.

              The  return  value is 0 unless an invalid option is
              supplied or _n indexes beyond the end of the  direc-
              tory stack.

       disown [-ar] [-h] [jobspec ...]
              Without  options,  each jobspec is removed from the
              table of active jobs.  If the -h option  is  given,
              each  jobspec is not removed from the table, but is
              marked so that SIGHUP is not sent to the job if the
              shell receives a SIGHUP.  If no jobspec is present,
              and neither the -a nor the -r option  is  supplied,
              the  current  job  is  used.  If no jobspec is sup-
              plied, the -a option means to remove  or  mark  all
              jobs;  the  -r  option  without  a jobspec argument



GNU                        1999 Jan 20                         64





BASH(1)                                                   BASH(1)


              restricts operation to running  jobs.   The  return
              value  is  0  unless  a  jobspec does not specify a
              valid job.

       echo [-neE] [arg ...]
              Output the args, separated by spaces, followed by a
              newline.   The return status is always 0.  If -n is
              specified, the trailing newline is suppressed.   If
              the  -e option is given, interpretation of the fol-
              lowing  backslash-escaped  characters  is  enabled.
              The  -E option disables the interpretation of these
              escape characters, even on systems where  they  are
              interpreted by default.  echo does not interpret ----
              to mean the end of options.   echo  interprets  the
              following escape sequences:
              \a     alert (bell)
              \b     backspace
              \c     suppress trailing newline
              \e     an escape character
              \f     form feed
              \n     new line
              \r     carriage return
              \t     horizontal tab
              \v     vertical tab
              \\\\     backslash
              \\nnn   the  character whose ASCII code is the octal
                     value nnn (one to three digits)
              \\xxnnn  the character whose ASCII code is  the  hex-
                     adecimal value nnn (one to three digits)

       enable [-adnps] [-f filename] [name ...]
              Enable  and  disable  builtin shell commands.  Dis-
              abling a builtin allows a disk  command  which  has
              the  same  name  as  a shell builtin to be executed
              with specifying a full pathname,  even  though  the
              shell  normally  searches  for builtins before disk
              commands.  If -n is used, each  name  is  disabled;
              otherwise,  names are enabled.  For example, to use
              the test binary found via the PATH instead  of  the
              shell  builtin version, run enable -n test..  The -f
              option means to load the new builtin  command  name
              from  shared  object filename, on systems that sup-
              port dynamic loading.  The -d option will delete  a
              builtin  previously  loaded  with  -f.   If no name
              arguments are given, or if the -p  option  is  sup-
              plied,  a  list of shell builtins is printed.  With
              no other option arguments, the list consists of all
              enabled  shell  builtins.   If -n is supplied, only
              disabled builtins are printed.  If -a is  supplied,
              the  list  printed  includes  all builtins, with an
              indication of whether or not each is  enabled.   If
              -s  is  supplied,  the  output is restricted to the
              POSIX special builtins.   The  return  value  is  0
              unless  a name is not a shell builtin or there is a



GNU                        1999 Jan 20                         65





BASH(1)                                                   BASH(1)


              problem loading a new builtin from a shared object.

       eval [arg ...]
              The  args are read and concatenated together into a
              single command.  This command is then read and exe-
              cuted by the shell, and its exit status is returned
              as the value of eval.  If there  are  no  args,  or
              only null arguments, eval returns 0.

       exec [-cl] [-a name] [command [arguments]]
              If command is specified, it replaces the shell.  No
              new process is created.  The arguments  become  the
              arguments  to  command.   If  the -l option is sup-
              plied, the shell places a dash in  the  zeroth  arg
              passed  to  command.   This  is what login(1) does.
              The -c option causes command to be executed with an
              empty  environment.   If  -a is supplied, the shell
              passes name as the zeroth argument to the  executed
              command.   If  command  cannot be executed for some
              reason, a non-interactive shell exits,  unless  the
              shell  option execfail is enabled, in which case it
              returns  failure.   An  interactive  shell  returns
              failure if the file cannot be executed.  If command
              is not specified, any redirections take  effect  in
              the  current shell, and the return status is 0.  If
              there is a redirection error, the return status  is
              1.

       exit [_n]
              Cause  the  shell to exit with a status of _n.  If _n
              is omitted, the exit status is  that  of  the  last
              command  executed.   A  trap  on  EXIT  is executed
              before the shell terminates.

       export [-fn] [name[=word]] ...
       export -p
              The supplied names are marked for automatic  export
              to  the  environment  of subsequently executed com-
              mands.  If the -f option is given, the names  refer
              to  functions.  If no names are given, or if the -p
              option is supplied, a list of all  names  that  are
              exported  in  this shell is printed.  The -n option
              causes the export property to be removed  from  the
              named  variables.  export returns an exit status of
              0 unless an invalid option is encountered,  one  of
              the names is not a valid shell variable name, or -f
              is supplied with a name that is not a function.

       fc [-e ename] [-nlr] [first] [last]
       fc -s [pat=rep] [cmd]
              Fix Command.  In the first form, a  range  of  com-
              mands  from first to last is selected from the his-
              tory list.  First and last may be  specified  as  a
              string  (to  locate the last command beginning with



GNU                        1999 Jan 20                         66





BASH(1)                                                   BASH(1)


              that string) or as a number (an index into the his-
              tory  list,  where  a negative number is used as an
              offset from the current command number).   If  last
              is  not  specified it is set to the current command
              for listing (so that fc -l --1100 prints the  last  10
              commands)  and to first otherwise.  If first is not
              specified it is set to  the  previous  command  for
              editing and -16 for listing.

              The  -n  option suppresses the command numbers when
              listing.  The -r option reverses the order  of  the
              commands.   If the -l option is given, the commands
              are listed on standard output.  Otherwise, the edi-
              tor  given by ename is invoked on a file containing
              those commands.  If ename is not given,  the  value
              of  the  FCEDIT  variable is used, and the value of
              EDITOR if FCEDIT is not set.  If  neither  variable
              is  set, vi is used.  When editing is complete, the
              edited commands are echoed and executed.

              In the second form, command  is  re-executed  after
              each  instance of pat is replaced by rep.  A useful
              alias to use with this is ``r=fc -s'', so that typ-
              ing  ``r  c' runs the last command beginning with
              `c' and typing ``r'' re-executes the  last  com-
              mand.

              If  the  first  form is used, the return value is 0
              unless an invalid option is encountered or first or
              last specify history lines out of range.  If the -e
              option is supplied, the return value is  the  value
              of the last command executed or failure if an error
              occurs with the temporary file of commands.  If the
              second  form  is used, the return status is that of
              the command re-executed, unless cmd does not  spec-
              ify  a valid history line, in which case fc returns
              failure.

       fg [jobspec]
              Resume jobspec in the foreground, and make  it  the
              current  job.   If  jobspec  is  not  present,  the
              shell's notion of the current  job  is  used.   The
              return value is that of the command placed into the
              foreground, or failure if run when job  control  is
              disabled  or, when run with job control enabled, if
              jobspec does not specify a  valid  job  or  jobspec
              specifies  a  job that was started without job con-
              trol.

       getopts optstring name [args]
              getopts is used by shell procedures to parse  posi-
              tional  parameters.   optstring contains the option
              letters to be recognized; if a letter  is  followed
              by  a  colon,  the  option  is  expected to have an



GNU                        1999 Jan 20                         67





BASH(1)                                                   BASH(1)


              argument, which should  be  separated  from  it  by
              white  space.   Each  time  it  is invoked, getopts
              places 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
              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 variable OPTARG.  The shell  does
              not reset OPTIND automatically; it must be manually
              reset between multiple calls to getopts within  the
              same shell invocation if a new set of parameters is
              to be used.

              When the end of  options  is  encountered,  getopts
              exits  with  a  return  value  greater  than  zero.
              OPTIND is set to the index of the first  non-option
              argument, and name is set to ?.

              getopts  normally parses the positional parameters,
              but if more arguments are given  in  args,  getopts
              parses those instead.

              getopts  can  report  errors  in  two ways.  If the
              first character of optstring  is  a  colon,  silent
              error reporting is used.  In normal operation diag-
              nostic messages are printed when invalid options or
              missing  option  arguments are encountered.  If the
              variable OPTERR is set to 0, no error messages will
              be  displayed,  even if the first character of opt-
              string is not a colon.

              If an invalid option is seen, getopts places ? into
              name  and,  if  not silent, prints an error message
              and unsets  OPTARG.   If  getopts  is  silent,  the
              option  character  found is placed in OPTARG and no
              diagnostic message is printed.

              If a required argument is not found, and getopts is
              not  silent, a question mark (??) is placed in name,
              OPTARG  is  unset,  and  a  diagnostic  message  is
              printed.  If getopts is silent, then a colon (::) is
              placed in name and OPTARG  is  set  to  the  option
              character found.

              getopts  returns  true  if  an option, specified or
              unspecified, is found.  It returns false if the end
              of options is encountered or an error occurs.

       hash [-r] [-p filename] [name]
              For each name, the full file name of the command is
              determined by searching the  directories  in  $PATH
              and  remembered.   If the -p option is supplied, no
              path search is performed, and filename is  used  as



GNU                        1999 Jan 20                         68





BASH(1)                                                   BASH(1)


              the  full  file name of the command.  The -r option
              causes the shell to  forget  all  remembered  loca-
              tions.   If  no  arguments  are  given, information
              about remembered commands is printed.   The  return
              status  is  true  unless  a name is not found or an
              invalid option is supplied.

       help [pattern]
              Display helpful information about builtin commands.
              If  pattern  is specified, help gives detailed help
              on all commands matching  pattern;  otherwise  help
              for  all  the builtins and shell control structures
              is printed.  The return status is 0 unless no  com-
              mand matches pattern.

       history [-c] [_n]
       history -anrw [filename]
       history -p arg [arg _._._.]
       history -s arg [arg _._._.]
              With  no  options, display the command history list
              with line numbers.  Lines listed with a ** have been
              modified.   An  argument of _n lists only the last _n
              lines.  If filename is supplied, it is used as  the
              name  of  the  history  file;  if not, the value of
              HISTFILE is used.  Options, if supplied,  have  the
              following meanings:
              -a     Append  the  ``new''  history lines (history
                     lines entered since  the  beginning  of  the
                     current bash session) to the history file.
              -n     Read the history lines not already read from
                     the history file into  the  current  history
                     list.   These are lines appended to the his-
                     tory file since the beginning of the current
                     bash session.
              -r     Read  the  contents  of the history file and
                     use them as the current history.
              -w     Write the current  history  to  the  history
                     file,  overwriting  the  history file's con-
                     tents.
              -c     Clear the history list by deleting  all  the
                     entries.
              -p     Perform  history substitution on the follow-
                     ing args and display the result on the stan-
                     dard  output.  Does not store the results in
                     the history list.  Each arg must  be  quoted
                     to disable normal history expansion.
              -s     Store the args in the history list as a sin-
                     gle entry.  The last command in the  history
                     list is removed before the args are added.

              The  return  value is 0 unless an invalid option is
              encountered or an error  occurs  while  reading  or
              writing the history file.




GNU                        1999 Jan 20                         69





BASH(1)                                                   BASH(1)


       jobs [-lnprs] [ jobspec ... ]
       jobs -x command [ args ... ]
              The  first form lists the active jobs.  The options
              have the following meanings:
              -l     List process IDs in addition to  the  normal
                     information.
              -p     List  only  the process ID of the job's pro-
                     cess group leader.
              -n     Display information  only  about  jobs  that
                     have  changed status since the user was last
                     notified of their status.
              -r     Restrict output to running jobs.
              -s     Restrict output to stopped jobs.

              If jobspec is given, output is restricted to infor-
              mation  about  that  job.   The  return status is 0
              unless an  invalid  option  is  encountered  or  an
              invalid jobspec is supplied.

              If  the  -x  option  is supplied, jobs replaces any
              jobspec found in command or args  with  the  corre-
              sponding  process  group  ID,  and executes command
              passing it args, returning its exit status.

       kill [-s sigspec | -n signum | --sigspec] [pid | jobspec]
              ...
       kill -l [sigspec | exit__status]
              Send  the  signal named by sigspec or signum to the
              processes named by  pid  or  jobspec.   sigspec  is
              either  a  signal  name such as SIGKILL or a signal
              number; signum is a signal number.  If sigspec is a
              signal  name, the name may be given with or without
              the SIG prefix.  If sigspec is  not  present,  then
              SIGTERM  is  assumed.   An argument of -l lists the
              signal names.  If any arguments are  supplied  when
              -l is given, the names of the signals corresponding
              to the arguments are listed, and the return  status
              is  0.   The exit__status argument to -l is a number
              specifying either a signal number or the exit  sta-
              tus  of  a  process  terminated  by a signal.  kill
              returns true if at least one  signal  was  success-
              fully  sent,  or  false  if  an  error occurs or an
              invalid option is encountered.

       let arg [arg ...]
              Each arg is an arithmetic expression to  be  evalu-
              ated  (see ARITHMETIC EVALUATION).  If the last arg
              evaluates to 0, let returns 1; 0 is returned other-
              wise.

       local [name[=value] ...]
              For  each  argument, a local variable named name is
              created, and assigned value.  When  local  is  used
              within  a  function, it causes the variable name to



GNU                        1999 Jan 20                         70





BASH(1)                                                   BASH(1)


              have a visible scope restricted  to  that  function
              and its children.  With no operands, local writes a
              list of local variables to the standard output.  It
              is  an  error  to use local when not within a func-
              tion.  The return status is 0 unless local is  used
              outside a function, or an invalid name is supplied.

       logout Exit a login shell.

       popd [-nn] [+_n] [-_n]
              Removes entries from the directory stack.  With  no
              arguments,  removes  the  top  directory  from  the
              stack, and performs a cd to the new top  directory.
              Arguments,  if  supplied,  have the following mean-
              ings:
              ++_n     Removes the _nth entry counting from the left
                     of  the  list  shown  by dirs, starting with
                     zero.  For example: ``popd +0'' removes  the
                     first directory, ``popd +1'' the second.
              --_n     Removes  the  _nth  entry  counting  from the
                     right of the list shown  by  dirs,  starting
                     with zero.  For example: ``popd -0'' removes
                     the last directory, ``popd -1'' the next  to
                     last.
              -n     Suppresses  the  normal  change of directory
                     when removing directories from the stack, so
                     that only the stack is manipulated.

              If  the  popd command is successful, a dirs is per-
              formed as well, and the return status is  0.   popd
              returns  false if an invalid option is encountered,
              the directory stack is empty, a non-existent direc-
              tory  stack  entry  is  specified, or the directory
              change fails.

       printf format [arguments]
              Write the formatted arguments to the standard  out-
              put under the control of the format.  The format is
              a character string which contains  three  types  of
              objects:  plain characters, which are simply copied
              to standard  output,  character  escape  sequences,
              which are converted and copied to the standard out-
              put,  and  format  specifications,  each  of  which
              causes  printing  of  the next successive argument.
              In addition to the standard printf(1)  formats,  %b
              causes  printf to expand backslash escape sequences
              in the corresponding argument, and %q causes printf
              to  output  the  corresponding argument in a format
              that can be reused as shell input.

              The format is reused as necessary to consume all of
              the  arguments.   If the format requires more argu-
              ments than are supplied, the extra format  specifi-
              cations  behave  as if a zero value or null string,



GNU                        1999 Jan 20                         71





BASH(1)                                                   BASH(1)


              as appropriate, had been supplied.

       pushd [-n] [dir]
       pushd [-n] [+_n] [-_n]
              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 argu-
              ments,   exchanges  the  top  two  directories  and
              returns 0, unless the  directory  stack  is  empty.
              Arguments,  if  supplied,  have the following mean-
              ings:
              ++_n     Rotates the stack so that the _nth  directory
                     (counting from the left of the list shown by
                     dirs, starting with zero) is at the top.
              --_n     Rotates the stack so that the _nth  directory
                     (counting  from  the right of the list shown
                     by dirs, starting with zero) is at the  top.
              -n     Suppresses  the  normal  change of directory
                     when adding directories  to  the  stack,  so
                     that only the stack is manipulated.
              dir    Adds  dir to the directory stack at the top,
                     making it the new current working directory.

              If  the pushd command is successful, a dirs is per-
              formed as well.  If the first form is  used,  pushd
              returns  0  unless  the  cd to dir fails.  With the
              second form, pushd returns 0 unless  the  directory
              stack is empty, a non-existent directory stack ele-
              ment is specified, or the directory change  to  the
              specified new current directory fails.

       pwd [-LP]
              Print the absolute file name of the current working
              directory.  The file name printed contains no  sym-
              bolic  links if the -P option is supplied or the -o
              physical option  to  the  set  builtin  command  is
              enabled.   If the -L option is used, symbolic links
              are followed.  The return status  is  0  unless  an
              error  occurs while reading the name of the current
              directory or an invalid option is supplied.

       read [-er] [-a aname] [-p prompt] [name ...]
              One line is read from the standard input,  and  the
              first  word is assigned to the first name, the sec-
              ond word to the second name, and so on, with  left-
              over   words   and   their  intervening  separators
              assigned to the last  name.   If  there  are  fewer
              words  read from the standard input than names, the
              remaining names are  assigned  empty  values.   The
              characters  in  IFS are used to split the line into
              words.  The backslash character (\\) may be used  to
              remove  any  special meaning for the next character
              read and for line continuation.  Options,  if  sup-
              plied, have the following meanings:



GNU                        1999 Jan 20                         72





BASH(1)                                                   BASH(1)


              -r     Backslash  does not act as an escape charac-
                     ter.  The backslash is considered to be part
                     of  the  line.   In particular, a backslash-
                     newline pair may not be used as a line  con-
                     tinuation.
              -p     Display  prompt, without a trailing newline,
                     before attempting to read  any  input.   The
                     prompt  is displayed only if input is coming
                     from a terminal.
              -a     The words are assigned to sequential indices
                     of  the array variable aname, starting at 0.
                     aname is unset before  any  new  values  are
                     assigned.  Other name arguments are ignored.
              -e     If the standard input is coming from a  ter-
                     minal, readline (see READLINE above) is used
                     to obtain the line.

              If no names are supplied, the line read is assigned
              to  the  variable  REPLY.  The return code is zero,
              unless end-of-file is encountered.

       readonly [-apf] [name ...]
              The given names are marked readonly; the values  of
              these  names  may  not  be  changed  by  subsequent
              assignment.  If the  -f  option  is  supplied,  the
              functions corresponding to the names are so marked.
              The -a option restricts the  variables  to  arrays.
              If no name arguments are given, or if the -p option
              is supplied,  a  list  of  all  readonly  names  is
              printed.   The  -p  option causes output to be dis-
              played in a format thatmay be reused as input.  The
              return  status  is  0  unless  an invalid option is
              encountered, one of the names is not a valid  shell
              variable  name,  or -f is supplied with a name that
              is not a function.

       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 executed in  the  func-
              tion  body.  If used outside a function, but during
              execution of a script by the ..   (source)  command,
              it  causes  the shell to stop executing that script
              and return either _n or the exit status of the  last
              command executed within the script as the exit sta-
              tus of the script.  If used outside a function  and
              not  during  execution of a script by .., the return
              status is false.

       set [--abefhkmnptuvxBCHP] [-o option] [arg ...]
              Without options, the name and value of  each  shell
              variable  are  displayed  in  a  format that can be
              reused as input.  The output is sorted according to
              the  current  locale.   When options are specified,



GNU                        1999 Jan 20                         73





BASH(1)                                                   BASH(1)


              they set or unset shell attributes.  Any  arguments
              remaining  after  the  options  are  processed  are
              treated as values for the positional parameters and
              are  assigned,  in  order,  to  $$11,  $$22,  ......   $$_n.
              Options, if specified, have the following meanings:
              -a      Automatically mark variables which are mod-
                      ified or created for export to the environ-
                      ment of subsequent commands.
              -b      Report  the status of terminated background
                      jobs immediately, rather  than  before  the
                      next  primary  prompt.   This  is effective
                      only when job control is enabled.
              -e      Exit immediately if a simple  command  (see
                      SHELL  GRAMMAR above) exits with a non-zero
                      status.  The shell does  not  exit  if  the
                      command  that  fails is part of an until or
                      while loop, part of an if  statement,  part
                      of  a  &&&&  or  |||| list, or if the command's
                      return value is being inverted via !!.
              -f      Disable pathname expansion.
              -h      Remember the location of commands  as  they
                      are  looked  up  for  execution.   This  is
                      enabled by default.
              -k      All arguments in  the  form  of  assignment
                      statements  are  placed  in the environment
                      for a command, not just those that  precede
                      the command name.
              -m      Monitor  mode.   Job  control  is  enabled.
                      This option is on by default  for  interac-
                      tive shells on systems that support it (see
                      JOB CONTROL above).   Background  processes
                      run  in a separate process group and a line
                      containing their  exit  status  is  printed
                      upon their completion.
              -n      Read  commands  but  do  not  execute them.
                      This may be used to check  a  shell  script
                      for  syntax  errors.   This  is  ignored by
                      interactive shells.
              -o option-name
                      The option-name can be one of  the  follow-
                      ing:
                      allexport
                              Same as -a.
                      braceexpand
                              Same as -B.
                      emacs   Use  an  emacs-style  command  line
                              editing interface.  This is enabled
                              by default when the shell is inter-
                              active, unless the shell is started
                              with the --noediting option.
                      errexit Same as -e.
                      hashall Same as -h.
                      histexpand
                              Same as -H.



GNU                        1999 Jan 20                         74





BASH(1)                                                   BASH(1)


                      history Enable    command    history,    as
                              described  above   under   HISTORY.
                              This  option  is  on  by default in
                              interactive shells.
                      ignoreeof
                              The effect is as if the shell  com-
                              mand IGNOREEOF=10 had been executed
                              (see Shell Variables above).
                      keyword Same as -k.
                      monitor Same as -m.
                      noclobber
                              Same as -C.
                      noexec  Same as -n.
                      noglob  Same as -f.
                      notify  Same as -b.
                      nounset Same as -u.
                      onecmd  Same as -t.
                      physical
                              Same as -P.
                      posix   Change the behavior of  bash  where
                              the  default operation differs from
                              the POSIX 1003.2 standard to  match
                              the standard.
                      privileged
                              Same as -p.
                      verbose Same as -v.
                      vi      Use a vi-style command line editing
                              interface.
                      xtrace  Same as -x.
                      If -o is supplied with no option-name,  the
                      values  of the current options are printed.
                      If +o is supplied with  no  option-name,  a
                      series of set commands to recreate the cur-
                      rent option settings is  displayed  on  the
                      standard output.
              -p      Turn on privileged mode.  In this mode, the
                      $ENV and $BASH_ENV files are not processed,
                      shell  functions are not inherited from the
                      environment, and the SHELLOPTS variable, if
                      it  appears in the environment, is ignored.
                      If the shell is started with the  effective
                      user  (group) id not equal to the real user
                      (group) id, and the -p option is  not  sup-
                      plied,  these  actions  are  taken  and the
                      effective user id is set to the  real  user
                      id.   If  the  -p  option  is  supplied  at
                      startup,  the  effective  user  id  is  not
                      reset.   Turning this option off causes the
                      effective user and group ids to be  set  to
                      the real user and group ids.
              -t      Exit  after  reading and executing one com-
                      mand.
              -u      Treat unset variables as an error when per-
                      forming  parameter expansion.  If expansion



GNU                        1999 Jan 20                         75





BASH(1)                                                   BASH(1)


                      is attempted  on  an  unset  variable,  the
                      shell  prints an error message, and, if not
                      interactive, exits with a non-zero  status.
              -v      Print shell input lines as they are read.
              -x      After  expanding  each simple command, dis-
                      play the expanded value of PS4, followed by
                      the command and its expanded arguments.
              -B      The  shell  performs  brace  expansion (see
                      Brace Expansion  above).   This  is  on  by
                      default.
              -C      If set, bash does not overwrite an existing
                      file with the >>,  >>&&,  and  <<>>  redirection
                      operators.   This  may  be  overridden when
                      creating output files by using the redirec-
                      tion operator >>|| instead of >>.
              -H      Enable !!  style history substitution.  This
                      option is on by default when the  shell  is
                      interactive.
              -P      If  set, the shell does not follow symbolic
                      links when executing commands  such  as  cd
                      that  change the current working directory.
                      It uses the  physical  directory  structure
                      instead.  By default, bash follows the log-
                      ical chain of directories  when  performing
                      commands  which  change  the current direc-
                      tory.
              ----      If no arguments follow  this  option,  then
                      the  positional parameters are unset.  Oth-
                      erwise, the positional parameters  are  set
                      to  the  args,  even  if some of them begin
                      with a --.
              --       Signal  the  end  of  options,  cause   all
                      remaining  args to be assigned to the posi-
                      tional parameters.  The -x and  -v  options
                      are  turned off.  If there are no args, the
                      positional parameters remain unchanged.

              The options are off  by  default  unless  otherwise
              noted.   Using + rather than - causes these options
              to be turned off.  The options can also  be  speci-
              fied  as  arguments  to an invocation of the shell.
              The current set of options may be found in $$--.  The
              return  status  is  always  true  unless an invalid
              option is encountered.

       shift [_n]
              The positional parameters from _n+1 ... are  renamed
              to  $$11  ........  Parameters represented by the numbers
              $$## down to $$##-_n+1 are unset.  _n must be a non-nega-
              tive  number  less than or equal to $$##.  If _n is 0,
              no parameters are changed.  If _n is not  given,  it
              is  assumed  to be 1.  If _n is greater than $$##, the
              positional parameters are not changed.  The  return
              status is greater than zero if _n is greater than $$##



GNU                        1999 Jan 20                         76





BASH(1)                                                   BASH(1)


              or less than zero; otherwise 0.

       shopt [-pqsu] [-o] [optname ...]
              Toggle the values of variables controlling optional
              shell  behavior.   With  no options, or with the -p
              option, a list of  all  settable  options  is  dis-
              played,  with  an indication of whether or not each
              is set.  The -p option causes  output  to  be  dis-
              played  in  a  form  that  may  be reused as input.
              Other options have the following meanings:
              -s     Enable (set) each optname.
              -u     Disable (unset) each optname.
              -q     Suppresses normal output (quiet  mode);  the
                     return  status indicates whether the optname
                     is set or unset.  If multiple optname  argu-
                     ments  are  given with -q, the return status
                     is zero if all optnames  are  enabled;  non-
                     zero otherwise.
              -o     Restricts  the values of optname to be those
                     defined  for  the  -o  option  to  the   set
                     builtin.

              If  either  -s  or -u is used with no optname argu-
              ments, the display  is  limited  to  those  options
              which  are set or unset, respectively.  Unless oth-
              erwise  noted,  the  shopt  options  are   disabled
              (unset) by default.

              The  return  status when listing options is zero if
              all optnames are enabled, non-zero otherwise.  When
              setting  or unsetting options, the return status is
              zero unless an optname is not a valid shell option.

              The list of shopt options is:

              cdable_vars
                      If  set, an argument to the cd builtin com-
                      mand that is not a directory is assumed  to
                      be  the  name  of a variable whose value is
                      the directory to change to.
              cdspell If set, minor errors in the spelling  of  a
                      directory component in a cd command will be
                      corrected.   The  errors  checked  for  are
                      transposed characters, a missing character,
                      and one character too many.  If  a  correc-
                      tion  is  found, the corrected file name is
                      printed, and the  command  proceeds.   This
                      option  is only used by interactive shells.
              checkhash
                      If set, bash checks that a command found in
                      the hash table exists before trying to exe-
                      cute it.  If a  hashed  command  no  longer
                      exists,  a normal path search is performed.




GNU                        1999 Jan 20                         77





BASH(1)                                                   BASH(1)


              checkwinsize
                      If set, bash checks the window  size  after
                      each command and, if necessary, updates the
                      values of LINES and COLUMNS.
              cmdhist If set, bash attempts to save all lines  of
                      a multiple-line command in the same history
                      entry.   This  allows  easy  re-editing  of
                      multi-line commands.
              dotglob If  set,  bash includes filenames beginning
                      with a  `.'  in  the  results  of  pathname
                      expansion.
              execfail
                      If  set,  a  non-interactive shell will not
                      exit if it cannot execute the  file  speci-
                      fied  as  an  argument  to the exec builtin
                      command.  An  interactive  shell  does  not
                      exit if exec fails.
              expand_aliases
                      If  set,  aliases are expanded as described
                      above  under  ALIASES.   This   option   is
                      enabled  by default for interactive shells.
              extglob If set, the extended pattern matching  fea-
                      tures described above under Pathname Expan-
                      sion are enabled.
              histappend
                      If set, the history list is appended to the
                      file  named  by  the  value of the HISTFILE
                      variable when the shell exits, rather  than
                      overwriting the file.
              histreedit
                      If  set, and readline is being used, a user
                      is  given  the  opportunity  to  re-edit  a
                      failed history substitution.
              histverify
                      If  set,  and  readline  is being used, the
                      results of  history  substitution  are  not
                      immediately  passed  to  the  shell parser.
                      Instead, the resulting line is loaded  into
                      the  readline editing buffer, allowing fur-
                      ther modification.
              hostcomplete
                      If set, and readline is  being  used,  bash
                      will attempt to perform hostname completion
                      when a word containing a @@  is  being  com-
                      pleted   (see   Completing  under  READLINE
                      above).  This is enabled by default.
              huponexit
                      If set, bash will send SIGHUP to  all  jobs
                      when an interactive login shell exits.
              interactive_comments
                      If  set,  allow  a word beginning with ## to
                      cause that word and all  remaining  charac-
                      ters  on  that  line  to  be  ignored in an
                      interactive  shell  (see  COMMENTS  above).



GNU                        1999 Jan 20                         78





BASH(1)                                                   BASH(1)


                      This option is enabled by default.
              lithist If  set, and the cmdhist option is enabled,
                      multi-line commands are saved to  the  his-
                      tory  with  embedded  newlines  rather than
                      using semicolon separators where  possible.
              mailwarn
                      If  set,  and  a file that bash is checking
                      for mail has been accessed since  the  last
                      time it was checked, the message ``The mail
                      in mailfile has been read'' is displayed.
              nocaseglob
                      If  set,  bash  matches  filenames   in   a
                      case-insensitive  fashion  when  performing
                      pathname expansion (see Pathname  Expansion
                      above).
              nullglob
                      If set, bash allows patterns which match no
                      files (see  Pathname  Expansion  above)  to
                      expand  to a null string, rather than them-
                      selves.
              promptvars
                      If set, prompt strings undergo variable and
                      parameter expansion after being expanded as
                      described in PROMPTING above.  This  option
                      is enabled by default.
              restricted_shell
                      The shell sets this option if it is started
                      in restricted mode  (see  RESTRICTED  SHELL
                      below).   The  value  may  not  be changed.
                      This is not reset when  the  startup  files
                      are executed, allowing the startup files to
                      discover  whether  or  not   a   shell   is
                      restricted.
              shift_verbose
                      If  set,  the shift builtin prints an error
                      message when the shift  count  exceeds  the
                      number of positional parameters.
              sourcepath
                      If  set,  the  source  (..) builtin uses the
                      value of PATH to find  the  directory  con-
                      taining  the  file supplied as an argument.
                      This option is enabled by default.
       suspend [-f]
              Suspend  the  execution  of  this  shell  until  it
              receives  a SIGCONT signal.  The -f option says not
              to complain if this is a login shell; just  suspend
              anyway.  The return status is 0 unless the shell is
              a login shell and -f is not  supplied,  or  if  job
              control is not enabled.
       test expr
       [[ expr ]]
              Return  a status of 0 or 1 depending on the evalua-
              tion of  the  conditional  expression  expr.   Each
              operator  and  operand must be a separate argument.



GNU                        1999 Jan 20                         79





BASH(1)                                                   BASH(1)


              Expressions are composed of the primaries described
              above under CONDITIONAL EXPRESSIONS.

              Expressions  may  be  combined  using the following
              operators, listed in  decreasing  order  of  prece-
              dence.
              !! expr True if expr is false.
              (( expr ))
                     Returns the value of expr.  This may be used
                     to override the normal precedence of  opera-
                     tors.
              expr1 -aa expr2
                     True if both expr1 and expr2 are true.
              expr1 -oo expr2
                     True if either expr1 or expr2 is true.

              test and [[ evaluate conditional expressions using a
              set of rules based on the number of arguments.

              0 arguments
                     The expression is false.
              1 argument
                     The expression is true if and  only  if  the
                     argument is not null.
              2 arguments
                     If  the  first argument is !!, the expression
                     is true if and only if the  second  argument
                     is  null.   If  the first argument is one of
                     the unary conditional operators listed above
                     under  CONDITIONAL  EXPRESSIONS, the expres-
                     sion is true if the unary test is true.   If
                     the first argument is not a valid unary con-
                     ditional operator, the expression is  false.
              3 arguments
                     If  the second argument is one of the binary
                     conditional  operators  listed  above  under
                     CONDITIONAL  EXPRESSIONS,  the result of the
                     expression is the result of the binary  test
                     using  the  first  and  third  arguments  as
                     operands.  If the first argument is  !!,  the
                     value  is  the  negation of the two-argument
                     test using the second and  third  arguments.
                     If  the  first argument is exactly (( and the
                     third argument is exactly )), the  result  is
                     the  one-argument  test  of the second argu-
                     ment.  Otherwise, the expression  is  false.
                     The  -a  and  -o  operators  are  considered
                     binary operators in this case.
              4 arguments
                     If the first argument is !!,  the  result  is
                     the  negation  of the three-argument expres-
                     sion composed of  the  remaining  arguments.
                     Otherwise,  the  expression  is  parsed  and
                     evaluated according to precedence using  the



GNU                        1999 Jan 20                         80





BASH(1)                                                   BASH(1)


                     rules listed above.
              5 or more arguments
                     The   expression  is  parsed  and  evaluated
                     according  to  precedence  using  the  rules
                     listed above.

       times  Print the accumulated user and system times for the
              shell and for processes run from  the  shell.   The
              return status is 0.

       trap [-lp] [arg] [sigspec ...]
              The command arg is to be read and executed when the
              shell receives signal(s) sigspec.  If arg is absent
              or  --,  all  specified  signals  are reset to their
              original values (the values they had upon  entrance
              to  the shell).  If arg is the null string the sig-
              nal specified by each sigspec  is  ignored  by  the
              shell and by the commands it invokes.  If arg is -p
              then the trap commands associated with each sigspec
              are  displayed.  If no arguments are supplied or if
              only -p is given, trap prints the list of  commands
              associated  with  each signal number.  Each sigspec
              is either a signal name defined in <signal.h>, or a
              signal  number.   If a sigspec is EXIT (0) the com-
              mand arg is executed on exit from the shell.  If  a
              sigspec is DEBUG, the command arg is executed after
              every simple command  (see  SHELL  GRAMMAR  above).
              The  -l  option causes the shell to print a list of
              signal names and their corresponding numbers.  Sig-
              nals  ignored  upon  entry  to  the shell cannot be
              trapped or reset.  Trapped  signals  are  reset  to
              their original values in a child process when it is
              created.  The return status is false if any sigspec
              is invalid; otherwise trap returns true.

       type [-atp] name [name ...]
              With  no  options,  indicate how each name would be
              interpreted if used as a command name.  If  the  -t
              option  is  used, type prints a string which is one
              of alias, keyword, function, builtin,  or  file  if
              name  is  an  alias, shell reserved word, function,
              builtin, or disk file, respectively.  If  the  name
              is  not found, then nothing is printed, and an exit
              status of false is returned.  If the -p  option  is
              used, type either returns the name of the disk file
              that would be executed if name were specified as  a
              command  name, or nothing if type -t name would not
              return file.  If a command is hashed, -p prints the
              hashed value, not necessarily the file that appears
              first in PATH.  If the  -a  option  is  used,  type
              prints all of the places that contain an executable
              named name.  This includes aliases  and  functions,
              if and only if the -p option is not also used.  The
              table of hashed  commands  is  not  consulted  when



GNU                        1999 Jan 20                         81





BASH(1)                                                   BASH(1)


              using  -a.   type  returns true if any of the argu-
              ments are found, false if none are found.

       ulimit [-SHacdflmnpstuv [limit]]
              Provides control over the  resources  available  to
              the  shell  and to processes started by it, on sys-
              tems that allow such control.  The value  of  limit
              can  be  a  number  in  the  unit specified for the
              resource, or the value unlimited.  The  -H  and  -S
              options  specify that the hard or soft limit is set
              for the given resource.  A  hard  limit  cannot  be
              increased  once  it  is  set;  a  soft limit may be
              increased up to the value of the  hard  limit.   If
              neither  -H  nor -S is specified, both the soft and
              hard limits are set.  If limit is omitted, the cur-
              rent  value  of  the  soft limit of the resource is
              printed, unless the -H option is given.  When  more
              than  one resource is specified, the limit name and
              unit are printed before the value.   Other  options
              are interpreted as follows:
              -a     All current limits are reported
              -c     The maximum size of core files created
              -d     The maximum size of a process's data segment
              -f     The maximum size of  files  created  by  the
                     shell
              -l     The  maximum  size  that  may be locked into
                     memory
              -m     The maximum resident set size
              -n     The maximum number of open file  descriptors
                     (most  systems do not allow this value to be
                     set)
              -p     The pipe size in 512-byte blocks  (this  may
                     not be set)
              -s     The maximum stack size
              -t     The maximum amount of cpu time in seconds
              -u     The maximum number of processes available to
                     a single user
              -v     The maximum amount of virtual memory  avail-
                     able to the shell

              If limit is given, it is the new value of the spec-
              ified resource (the -a option is display only).  If
              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 units of 512-byte blocks,
              and -n and -u,  which  are  unscaled  values.   The
              return  status  is  0  unless  an invalid option is
              encountered,  a  non-numeric  argument  other  than
              unlimited  is supplied as limit, or an error occurs
              while setting a new limit.

       umask [-p] [-S] [mode]
              The user file-creation mask is  set  to  mode.   If
              mode  begins  with a digit, it is interpreted as an



GNU                        1999 Jan 20                         82





BASH(1)                                                   BASH(1)


              octal number; otherwise it is interpreted as a sym-
              bolic   mode  mask  similar  to  that  accepted  by
              chmod(1).  If mode is omitted, or if the -S  option
              is  supplied,  the  current  value  of  the mask is
              printed.  The -S  option  causes  the  mask  to  be
              printed  in symbolic form; the default output is an
              octal number.  If the -p option  is  supplied,  and
              mode  is  omitted, the output is in a form that may
              be reused as input.  The return status is 0 if  the
              mode  was  successfully changed or if no mode argu-
              ment was supplied, and false otherwise.

       unalias [-aa] [name ...]
              Remove names from the list of defined aliases.   If
              -a  is supplied, all alias definitions are removed.
              The return value is true unless a supplied name  is
              not a defined alias.

       unset [-fv] [name ...]
              For each name, remove the corresponding variable or
              function.  If no options are supplied,  or  the  -v
              option  is given, each name refers to a shell vari-
              able.  Read-only variables may not be unset.  If -f
              is  specifed, each name refers to a shell function,
              and the function definition is removed.  Each unset
              variable  or  function is removed from the environ-
              ment passed to subsequent commands.  If any of RAN-
              DOM,  SECONDS,  LINENO,  HISTCMD,  or  DIRSTACK are
              unset, they lose their special properties, even  if
              they  are  subsequently  reset.  The exit status is
              true unless a name does not exist or is readonly.

       wait [_n]
              Wait for the specified process and return its  ter-
              mination  status.   _n  may be a process ID or a job
              specification; if a job spec  is  given,  all  pro-
              cesses in that job's pipeline are waited for.  If _n
              is not given, all currently active child  processes
              are  waited for, and the return status is zero.  If
              _n specifies a  non-existent  process  or  job,  the
              return status is 127.  Otherwise, the return status
              is the exit status  of  the  last  process  or  job
              waited for.

RESTRICTED SHELL
       If  bash  is started with the name rbash, or the -r option
       is supplied at invocation, the shell  becomes  restricted.
       A  restricted  shell is used to set up an environment more
       controlled than the standard shell.   It  behaves  identi-
       cally  to  bash  with the exception that the following are
       disallowed or not performed:

       +o      changing directories with cd




GNU                        1999 Jan 20                         83





BASH(1)                                                   BASH(1)


       +o      setting or unsetting the  values  of  SHELL,  PATH,
              ENV, or BASH_ENV

       +o      specifying command names containing //

       +o      specifying  a  file name containing a // as an argu-
              ment to the ..  builtin command

       +o      importing function definitions from the shell envi-
              ronment at startup

       +o      parsing the value of SHELLOPTS from the shell envi-
              ronment at startup

       +o      redirecting output using the >, >|, <>, >&, &>, and
              >> redirection operators

       +o      using the exec builtin command to replace the shell
              with another command

       +o      adding or deleting builtin commands with the -f and
              -d options to the enable builtin command

       +o      specifying  the  -p  option  to the command builtin
              command

       +o      turning off restricted mode with set +r or  set  +o
              restricted.

       These  restrictions  are  enforced after any startup files
       are read.

       When a command that is found to be a shell script is  exe-
       cuted  (see  COMMAND EXECUTION above), rbash turns off any
       restrictions in the shell spawned to execute the script.

SEE ALSO
       Bash Features, Brian Fox and Chet Ramey
       The Gnu Readline Library, Brian Fox and Chet Ramey
       The Gnu History Library, Brian Fox and Chet Ramey
       Portable Operating System Interface (POSIX)  Part  2:
              Shell  and Utilities, IEEE
       sh(1), ksh(1), csh(1)
       emacs(1), vi(1)
       readline(3)

FILES
       /bin/bash
              The bash executable
       /etc/profile
              The systemwide initialization  file,  executed  for
              login shells
       ~/.bash__profile
              The  personal  initialization  file,  executed  for



GNU                        1999 Jan 20                         84





BASH(1)                                                   BASH(1)


              login shells
       ~/.bashrc
              The individual per-interactive-shell startup file
       ~/.bash__logout
              The individual login shell cleanup  file,  executed
              when a login shell exits
       ~/.inputrc
              Individual readline initialization file

AUTHORS
       Brian Fox, Free Software Foundation
       bfox@gnu.ai.MIT.Edu

       Chet Ramey, Case Western Reserve University
       chet@ins.CWRU.Edu

BUG REPORTS
       If  you  find  a  bug  in bash, you should report it.  But
       first, you should make sure that it really is a  bug,  and
       that  it  appears  in  the latest version of bash that you
       have.

       Once you have determined that a bug actually  exists,  use
       the bashbug command to submit a bug report.  If you have a
       fix, you are encouraged to mail that as well!  Suggestions
       and  `philosophical'  bug  reports  may  be mailed to bug-
       bash@gnu.org   or   posted   to   the   Usenet   newsgroup
       gnu.bash.bug.

       ALL bug reports should include:

       The version number of bash
       The hardware and operating system
       The compiler used to compile
       A description of the bug behaviour
       A short script or `recipe' which exercises the bug

       bashbug  inserts  the first three items automatically into
       the template it provides for filing a bug report.

       Comments and  bug  reports  concerning  this  manual  page
       should be directed to chet@ins.CWRU.Edu.

BUGS
       It's too big and too slow.

       There  are some subtle differences between bash and tradi-
       tional versions of sh, mostly because of the POSIX  speci-
       fication.

       Aliases are confusing in some uses.

       Shell   builtin  commands  and  functions  are  not  stop-
       pable/restartable.



GNU                        1999 Jan 20                         85





BASH(1)                                                   BASH(1)


       Compound commands and command sequences of the form `a ; b
       ; c' are not handled gracefully when process suspension is
       attempted.  When a process is stopped, the  shell  immedi-
       ately  executes the next command in the sequence.  It suf-
       fices to place the sequence of commands between  parenthe-
       ses to force it into a subshell, which may be stopped as a
       unit.

       Commands inside of $$((...))  command  substitution  are  not
       parsed  until  substitution is attempted.  This will delay
       error reporting until  some  time  after  the  command  is
       entered.

       Array variables may not (yet) be exported.











































GNU                        1999 Jan 20                         86


