


BASH(1)                                                   BASH(1)


NAME
       bash - GNU Bourne-Again SHell

SYNOPSIS
       bash [options] [file]

COPYRIGHT
       Bash is Copyright (C) 1989-2001 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 CC 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 Bash-2.05               2001 Mar 5                          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.
       --init-file file
       --rcfile file
              Execute  commands from file instead of the standard
              personal initialization file ~/.bashrc if the shell
              is interactive (see INVOCATION below).

       --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 when the shell is 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 (posix mode).

       --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



GNU Bash-2.05               2001 Mar 5                          2





BASH(1)                                                   BASH(1)


       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
       zero is a --, or one started with the --login option.

       An  interactive  shell  is  one started without non-option
       arguments and without the -c option whose  standard  input
       and  output 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.




GNU Bash-2.05               2001 Mar 5                          3





BASH(1)                                                   BASH(1)


       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
       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



GNU Bash-2.05               2001 Mar 5                          4





BASH(1)                                                   BASH(1)


              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>

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



GNU Bash-2.05               2001 Mar 5                          5





BASH(1)                                                   BASH(1)


       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  ter-
       minated 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

              command1 &&&& command2

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

       An OR list has the form

              command1 |||| command2


       command2 is executed if and only  if  command1  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



GNU Bash-2.05               2001 Mar 5                          6





BASH(1)                                                   BASH(1)


              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"".

       [[[[ 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



GNU Bash-2.05               2001 Mar 5                          7





BASH(1)                                                   BASH(1)


              executed 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.

       for (( expr1 ; expr2 ; expr3 )) ; do list ; done
              First, the arithmetic expression expr1 is evaluated
              according to the rules described below under ARITH-
              METIC EVALUATION.  The arithmetic expression  expr2
              is  then evaluated repeatedly until it evaluates to
              zero.  Each time  expr2  evaluates  to  a  non-zero
              value,  list is executed and the arithmetic expres-
              sion expr3 is  evaluated.   If  any  expression  is
              omitted,  it  behaves as if it evaluates to 1.  The
              return value is the exit status of the last command
              in  list  that  is executed, or false if any of the
              expressions is invalid.

       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.





GNU Bash-2.05               2001 Mar 5                          8





BASH(1)                                                   BASH(1)


       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.

       [ 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  it
       is to represent itself.

       When  the  command  history expansion facilities are being



GNU Bash-2.05               2001 Mar 5                          9





BASH(1)                                                   BASH(1)


       used, the history expansion character, usually !!, must  be
       quoted to prevent history expansion.

       There  are three quoting mechanisms: the escape character,
       single quotes, and double 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
       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
              \\''     single quote
              \\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 expanded 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



GNU Bash-2.05               2001 Mar 5                         10





BASH(1)                                                   BASH(1)


       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,   command  substitution,  arithmetic
       expansion, and quote removal (see  EXPANSION  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  exception of ""$$@@"" as explained
       below under Special Parameters.  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



GNU Bash-2.05               2001 Mar 5                         11





BASH(1)                                                   BASH(1)


              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
              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,



GNU Bash-2.05               2001 Mar 5                         12





BASH(1)                                                   BASH(1)


              initialized at shell  startup.   This  variable  is
              readonly.
       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.  Assignments to
              GROUPS  have  no effect and return an error status.
              If GROUPS is unset, it loses  its  special  proper-
              ties, even if it is subsequently reset.
       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
              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



GNU Bash-2.05               2001 Mar 5                         13





BASH(1)                                                   BASH(1)


              guaranteed to be meaningful.  If LINENO  is  unset,
              it loses its special properties, even if it is sub-
              sequently 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.

       FUNCNAME
              The name of any currently-executing shell function.
              This variable exists only when a shell function  is
              executing.   Assignments to FUNCNAME have no effect
              and return an error status.  If FUNCNAME is  unset,
              it loses its special properties, even if it is sub-
              sequently 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 COM-
              MANDS 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



GNU Bash-2.05               2001 Mar 5                         14





BASH(1)                                                   BASH(1)


              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.

       COMP_WORDS
              An  array variable (see Arrays below) consisting of
              the individual words in the current  command  line.
              This  variable is available only in shell functions
              invoked by the programmable  completion  facilities
              (see Programmable Completion below).

       COMP_CWORD
              An  index into ${COMP_WORDS} of the word containing
              the current  cursor  position.   This  variable  is
              available  only  in  shell functions invoked by the
              programmable  completion   facilities   (see   Pro-
              grammable Completion below).

       COMP_LINE
              The  current command line.  This variable is avail-
              able only in shell functions and external  commands
              invoked  by  the programmable completion facilities
              (see Programmable Completion below).

       COMP_POINT
              The index of the current cursor  position  relative
              to  the  beginning  of the current command.  If the
              current cursor position is at the end of  the  cur-
              rent  command,  the value of this variable is equal
              to ${#COMP_LINE}.  This variable is available  only
              in shell functions and external commands invoked by
              the programmable completion  facilities  (see  Pro-
              grammable Completion below).

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




GNU Bash-2.05               2001 Mar 5                         15





BASH(1)                                                   BASH(1)


       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
              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, or set to a  value  that  is  not  a  number
              greater  than  or equal to zero, 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='/var/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., /var/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\$ ''.



GNU Bash-2.05               2001 Mar 5                         16





BASH(1)                                                   BASH(1)


       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
              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



GNU Bash-2.05               2001 Mar 5                         17





BASH(1)                                                   BASH(1)


              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
              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 $$.

       LC_NUMERIC
              This  variable  determines the locale category used
              for number formatting.

       LINES  Used by the select builtin command to determine the
              column  length for printing selection lists.  Auto-
              matically set upon receipt of a SIGWINCH.

       COLUMNS
              Used by the select builtin command to determine the
              terminal   width  when  printing  selection  lists.
              Automatically set upon receipt of a SIGWINCH.



GNU Bash-2.05               2001 Mar 5                         18





BASH(1)                                                   BASH(1)


       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
              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



GNU Bash-2.05               2001 Mar 5                         19





BASH(1)                                                   BASH(1)


              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  match  the  complete  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 attempt-
              ing  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
              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 list of possible host-
              name  completions may be changed while the shell is
              running;  the  next  time  hostname  completion  is
              attempted after the value is changed, bash adds the
              contents of the new file to the existing list.   If
              HOSTFILE is set, but has no value, bash attempts to
              read /etc/hosts to  obtain  the  list  of  possible
              hostname  completions.  When HOSTFILE is unset, the
              hostname list is cleared.

       auto_resume
              This variable controls how the shell interacts with
              the user and job control.  If this variable is set,



GNU Bash-2.05               2001 Mar 5                         20





BASH(1)                                                   BASH(1)


              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.

       COMPREPLY
              An array variable from which bash reads the  possi-
              ble  completions  generated  by  a  shell  function
              invoked by  the  programmable  completion  facility
              (see Programmable Completion below).

   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
       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.




GNU Bash-2.05               2001 Mar 5                         21





BASH(1)                                                   BASH(1)


       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 expan-
       sion, parameter, variable  and  arithmetic  expansion  and
       command  substitution  (done  in a left-to-right fashion),
       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



GNU Bash-2.05               2001 Mar 5                         22





BASH(1)                                                   BASH(1)


       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.
       To avoid conflicts with parameter expansion, the string $${{
       is not considered eligible for brace expansion.

       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
       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



GNU Bash-2.05               2001 Mar 5                         23





BASH(1)                                                   BASH(1)


       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
       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



GNU Bash-2.05               2001 Mar 5                         24





BASH(1)                                                   BASH(1)


       of parameter as the name of the variable; this variable is
       then expanded and that value is used in the  rest  of  the
       substitution,  rather  than the value of parameter itself.
       This is known as indirect  expansion.   The  exception  to
       this is the expansion of ${!prefix*} described below.

       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 character spec-
              ified  by offset.  If length is omitted, expands to
              the substring of parameter starting at the  charac-
              ter  specified  by  offset.   length and offset are
              arithmetic expressions (see  ARITHMETIC  EVALUATION
              below).   length  must evaluate to a number greater
              than or equal to zero.  If offset  evaluates  to  a
              number less than zero, the value is used as an off-
              set from the end of the  value  of  parameter.   If
              parameter  is  @@,  the  result is length positional
              parameters beginning at offset.  If parameter is an
              array  name  indexed  by  @ or *, the result is the
              length members of the array beginning with ${param-
              eter[offset]}.   Substring  indexing  is zero-based
              unless the positional parameters are used, in which
              case the indexing starts at 1.




GNU Bash-2.05               2001 Mar 5                         25





BASH(1)                                                   BASH(1)


       ${!!prefix**}
              Expands to the names of variables whose names begin
              with prefix, separated by the  first  character  of
              the IFS special variable.

       ${##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.

       ${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



GNU Bash-2.05               2001 Mar 5                         26





BASH(1)                                                   BASH(1)


              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.

   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



GNU Bash-2.05               2001 Mar 5                         27





BASH(1)                                                   BASH(1)


       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.

       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.



GNU Bash-2.05               2001 Mar 5                         28





BASH(1)                                                   BASH(1)


   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  nullglob  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  alpha-
       betic  characters.   When  a  pattern is used for pathname
       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:

       **      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 hyphen denotes a range
              expression;  any character that sorts between those
              two  characters,  inclusive,  using   the   current
              locale's  collating  sequence and character set, is
              matched.  If the first character following the [[ is
              a  !!   or  a  ^^  then any character not enclosed is



GNU Bash-2.05               2001 Mar 5                         29





BASH(1)                                                   BASH(1)


              matched.  The sorting order of characters in  range
              expressions is determined by the current locale and
              the value of the LC_COLLATE shell variable, if set.
              A  -- may be matched by including it as the first or
              last character 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
       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



GNU Bash-2.05               2001 Mar 5                         30





BASH(1)                                                   BASH(1)


       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,
       pathname expansion, and word splitting.  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.

       Bash  handles  several  filenames  specially when they are
       used in redirections, as described in the following table:

              /dev/fd/fd
                     If fd is a valid integer, file descriptor fd
                     is duplicated.
              /dev/stdin
                     File descriptor 0 is duplicated.
              /dev/stdout
                     File descriptor 1 is duplicated.
              /dev/stderr
                     File descriptor 2 is duplicated.
              /dev/tcp/host//port
                     If host is  a  valid  hostname  or  Internet
                     address, and port is an integer port number,
                     bash attempts to open a  TCP  connection  to
                     the corresponding socket.
              /dev/udp/host//port
                     If  host  is  a  valid  hostname or Internet



GNU Bash-2.05               2001 Mar 5                         31





BASH(1)                                                   BASH(1)


                     address, and port is an integer port number,
                     bash  attempts  to  open a UDP connection to
                     the corresponding socket.

       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

   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 file 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.



GNU Bash-2.05               2001 Mar 5                         32





BASH(1)                                                   BASH(1)


       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
       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, arithmetic
       expansion, or pathname 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 character sequence  \<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.




GNU Bash-2.05               2001 Mar 5                         33





BASH(1)                                                   BASH(1)


       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

       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 (see FUNCTIONS below).

       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).




GNU Bash-2.05               2001 Mar 5                         34





BASH(1)                                                   BASH(1)


       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.

       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.
       When the name of a shell function is used as a simple com-
       mand name, the list of commands associated with that func-
       tion name is executed.  Functions are executed in the con-
       text  of  the  current shell; no new process is created to
       interpret them (contrast 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  special  parameter  ## is updated to
       reflect the change.  Positional parameter 0 is  unchanged.
       The  FUNCNAME  variable is set to the name of the function
       while the function is executing.  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



GNU Bash-2.05               2001 Mar 5                         35





BASH(1)                                                   BASH(1)


       automatically  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 operators and
       their precedence and associativity are the same as in  the
       C  language.   The  following list of operators is grouped
       into levels of equal-precedence operators.  The levels are
       listed in order of decreasing precedence.

       id++++ id----
              variable post-increment and post-decrement
       ++++id ----id
              variable pre-increment and pre-decrement
       -- ++    unary minus and plus
       !! ~~    logical and bitwise negation
       ****     exponentiation
       ** // %%  multiplication, division, remainder
       ++ --    addition, subtraction
       <<<< >>>>  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
       expr1 ,, expr2
              comma

       Shell  variables are allowed as operands; parameter expan-
       sion is performed  before  the  expression  is  evaluated.
       Within  an  expression, shell variables may also be refer-
       enced by name without using the parameter  expansion  syn-
       tax.   The  value  of a variable is evaluated as an arith-
       metic expression when it is referenced.  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



GNU Bash-2.05               2001 Mar 5                         36





BASH(1)                                                   BASH(1)


       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.   If the file argument to one of the primaries is
       one  of  /dev/stdin,  /dev/stdout,  or  /dev/stderr,  file
       descriptor 0, 1, or 2, respectively, 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.
       -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.




GNU Bash-2.05               2001 Mar 5                         37





BASH(1)                                                   BASH(1)


       -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.
       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



GNU Bash-2.05               2001 Mar 5                         38





BASH(1)                                                   BASH(1)


       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
       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.



GNU Bash-2.05               2001 Mar 5                         39





BASH(1)                                                   BASH(1)


       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 path-
       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
       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



GNU Bash-2.05               2001 Mar 5                         40





BASH(1)                                                   BASH(1)


              assignment  or  with  set  or  inherited  from  the
              shell's parent 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

       +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.




GNU Bash-2.05               2001 Mar 5                         41





BASH(1)                                                   BASH(1)


       The shell provides several ways to manipulate the environ-
       ment.  On invocation, the shell scans its own  environment
       and creates a parameter for each name found, automatically
       marking it for export to child processes.   Executed  com-
       mands  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
       indicates success.  A non-zero exit status indicates fail-
       ure.   When a command terminates on a fatal signal _N, bash
       uses the value of 128+_N 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.





GNU Bash-2.05               2001 Mar 5                         42





BASH(1)                                                   BASH(1)


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
       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



GNU Bash-2.05               2001 Mar 5                         43





BASH(1)                                                   BASH(1)


       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 operating system maintains the notion  of
       a current terminal process group ID.  Members of this pro-
       cess group (processes whose process group ID is  equal  to
       the  current  terminal process group ID) receive keyboard-
       generated signals such as  SIGINT.   These  processes  are
       said  to  be  in the foreground.  Background processes are
       those whose process 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 terminal.  Background processes which attempt
       to read from (write to) the terminal are  sent  a  SIGTTIN
       (SIGTTOU)  signal  by  the  terminal driver, which, unless
       caught, suspends the process.

       If the operating system on which bash is running  supports
       job  control,  bash contains facilities to use it.  Typing
       the suspend character (typically ^^ZZ,  Control-Z)  while  a
       process  is  running causes that process to be stopped and
       returns control to bash.  Typing the delayed suspend char-
       acter  (typically  ^^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 foreground, 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  dis-
       carded.

       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  &&''''



GNU Bash-2.05               2001 Mar 5                         44





BASH(1)                                                   BASH(1)


       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
              \j     the number of jobs currently managed by  the
                     shell
              \l     the  basename of the shell's terminal device
                     name
              \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
              \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



GNU Bash-2.05               2001 Mar 5                         45





BASH(1)                                                   BASH(1)


              \\[[     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,   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.)

       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.





GNU Bash-2.05               2001 Mar 5                         46





BASH(1)                                                   BASH(1)


   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, key-
       name is the name 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).



GNU Bash-2.05               2001 Mar 5                         47





BASH(1)                                                   BASH(1)


       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, but the
       symbolic character names are not recognized.

              "\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 1''.

       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,
       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



GNU Bash-2.05               2001 Mar 5                         48





BASH(1)                                                   BASH(1)


       customize 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 prefixing 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
              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.




GNU Bash-2.05               2001 Mar 5                         49





BASH(1)                                                   BASH(1)


       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.
       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



GNU Bash-2.05               2001 Mar 5                         50





BASH(1)                                                   BASH(1)


       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, ter-
              minates 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:



GNU Bash-2.05               2001 Mar 5                         51





BASH(1)                                                   BASH(1)


              $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 execute that command.  For instance, a  newline
       will  terminate  the  search  and accept the line, thereby
       executing the command 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.  In the following descriptions,  point
       refers  to the current cursor position, and mark refers to
       a cursor position saved by the set-mark command.  The text
       between the point and mark is referred to as the region.

   Commands for Moving
       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.



GNU Bash-2.05               2001 Mar 5                         52





BASH(1)                                                   BASH(1)


       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 the current or 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.
       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 point.  This is a non-incremental search.



GNU Bash-2.05               2001 Mar 5                         53





BASH(1)                                                   BASH(1)


       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.   With  an  argument  _n, insert the _nth word
              from the previous command (the words in the  previ-
              ous  command  begin with word 0).  A negative argu-
              ment inserts the _nth word from the end of the  pre-
              vious 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.

   Commands for Changing Text
       delete-char (C-d)
              Delete the character at point.  If point is at  the
              beginning  of  the line, there are no characters 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



GNU Bash-2.05               2001 Mar 5                         54





BASH(1)                                                   BASH(1)


              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, moving point forward as well.
              If point is at the  end  of  the  line,  then  this
              transposes  the two characters before point.  Nega-
              tive arguments have no effect.
       transpose-words (M-t)
              Drag the word before  point  past  the  word  after
              point, moving point 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 point 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
              line.  The killed text is saved on the kill-ring.
       kill-whole-line
              Kill all characters on the current line, no  matter
              where point is.
       kill-word (M-d)
              Kill  from point 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 for-
              ward-word.
       backward-kill-word (M-Rubout)
              Kill the word behind point.   Word  boundaries  are



GNU Bash-2.05               2001 Mar 5                         55





BASH(1)                                                   BASH(1)


              the same as those used by backward-word.
       unix-word-rubout (C-w)
              Kill  the word behind point, using white space as a
              word boundary.  The killed text  is  saved  on  the
              kill-ring.
       delete-horizontal-space (M-\)
              Delete all spaces and tabs around point.
       kill-region
              Kill the text in the current 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
              point.
       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  ini-
              tially  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.




GNU Bash-2.05               2001 Mar 5                         56





BASH(1)                                                   BASH(1)


       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 (subject
              to the setting of  Bbell-style))  and  the  original
              text  is  restored.  An argument of _n moves _n posi-
              tions forward in the list of  matches;  aa  negative
              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
              identically 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.
       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,



GNU Bash-2.05               2001 Mar 5                         57





BASH(1)                                                   BASH(1)


              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 insert 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.
       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 point.  If a numeric argument



GNU Bash-2.05               2001 Mar 5                         58





BASH(1)                                                   BASH(1)


              is supplied, the mark is set to that position.
       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.   The  default value of comment-begin causes
              this command to make 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.
       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.

   Programmable Completion
       When  word  completion  is  attempted for an argument to a
       command for which a completion specification (a  compspec)
       has  been  defined  using  the complete builtin (see SHELL
       BUILTIN  COMMANDS  below),  the  programmable   completion



GNU Bash-2.05               2001 Mar 5                         59





BASH(1)                                                   BASH(1)


       facilities are invoked.

       First,  the command name is identified.  If a compspec has
       been defined for that command, the  compspec  is  used  to
       generate  the  list  of possible completions for the word.
       If the command word is a full pathname, a compspec for the
       full  pathname  is  searched for first.  If no compspec is
       found for the full pathname, an attempt is made to find  a
       compspec for the portion following the final slash.

       Once a compspec has been found, it is used to generate the
       list of matching words.  If a compspec is not  found,  the
       default  bash completion as described above under Complet-
       ing is performed.

       First, the actions specified by  the  compspec  are  used.
       Only  matches  which  are  prefixed by the word being com-
       pleted are returned.  When the -f or -d option is used for
       filename  or directory name completion, the shell variable
       FIGNORE is used to filter the matches.

       Any completions specified by a filename expansion  pattern
       to  the -G option are generated next.  The words generated
       by the pattern need not match the  word  being  completed.
       The  GLOBIGNORE  shell  variable is not used to filter the
       matches, but the FIGNORE variable is used.

       Next, the string specified  as  the  argument  to  the  -W
       option is considered.  The string is first split using the
       characters in the  IFS  special  variable  as  delimiters.
       Shell  quoting  is  honored.   Each  word is then expanded
       using brace  expansion,  tilde  expansion,  parameter  and
       variable   expansion,   command  substitution,  arithmetic
       expansion, and  pathname  expansion,  as  described  above
       under  EXPANSION.   The  results are split using the rules
       described above under Word Splitting.  The results of  the
       expansion  are  prefix-matched against the word being com-
       pleted, and the matching words become the possible comple-
       tions.

       After  these  matches have been generated, any shell func-
       tion or command specified with the -F and  -C  options  is
       invoked.   When  the  command  or function is invoked, the
       COMP_LINE and COMP_POINT variables are assigned values  as
       described  above  under Shell Variables.  If a shell func-
       tion is being invoked, the COMP_WORDS and COMP_CWORD vari-
       ables  are  also  set.   When  the  function or command is
       invoked, the first argument is the  name  of  the  command
       whose  arguments  are being completed, the second argument
       is the word being completed, and the third argument is the
       word  preceding  the  word  being completed on the current
       command line.  No filtering of the  generated  completions
       against  the  word being completed is performed; the func-
       tion or command has complete  freedom  in  generating  the



GNU Bash-2.05               2001 Mar 5                         60





BASH(1)                                                   BASH(1)


       matches.

       Any  function  specified  with  -F  is invoked first.  The
       function may use any of the  shell  facilities,  including
       the  compgen  builtin  described  below,  to  generate the
       matches.  It must put the possible completions in the COM-
       PREPLY array variable.

       Next,  any command specified with the -C option is invoked
       in an environment equivalent to command substitution.   It
       should  print  a list of completions, one per line, to the
       standard output.  Backslash may be used to escape  a  new-
       line, if necessary.

       After  all  of the possible completions are generated, any
       filter specified with the -X  option  is  applied  to  the
       list.  The filter is a pattern as used for pathname expan-
       sion; a && in the pattern is replaced with the text of  the
       word  being  completed.  A literal && may be escaped with a
       backslash; the backslash is removed  before  attempting  a
       match.   Any  completion  that matches the pattern will be
       removed from the list.  A leading !! negates  the  pattern;
       in  this case any completion not matching the pattern will
       be removed.

       Finally, any prefix and suffix specified with the  -P  and
       -S  options  are  added  to  each member of the completion
       list, and the result is returned to the  readline  comple-
       tion code as the list of possible completions.

       If  the  previously-applied  actions  do  not generate any
       matches, and the -o dirnames option was supplied  to  com-
       plete  when  the compspec was defined, directory name com-
       pletion is attempted.

       By default, if a compspec is found, whatever it  generates
       is returned to the completion code as the full set of pos-
       sible completions.  The default bash completions  are  not
       attempted, and the readline default of filename completion
       is disabled.  If the -o default  option  was  supplied  to
       complete when the compspec was defined, readline's default
       completion will be performed if the compspec generates  no
       matches.

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 value of the HISTSIZE
       variable is used as the number of commands to  save  in  a
       history  list.   The  text  of  the last HISTSIZE commands
       (default 500) is saved.  The shell stores each command  in
       the history list prior to parameter and variable expansion
       (see EXPANSION above) but after history expansion is  per-
       formed,  subject  to  the  values  of  the shell variables



GNU Bash-2.05               2001 Mar 5                         61





BASH(1)                                                   BASH(1)


       HISTIGNORE and HISTCONTROL.

       On startup, the history is initialized from the file named
       by  the  variable HISTFILE (default ~/.bash__history).  The
       file named by the value of HISTFILE is truncated, if  nec-
       essary, to contain no more than the number of lines speci-
       fied by the value of HISTFILESIZE.   When  an  interactive
       shell  exits, the last $HISTSIZE lines are copied from the
       history list to $HISTFILE.  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 may be used to dis-
       play or modify the history list and manipulate the history
       file.  When using command-line  editing,  search  commands
       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.

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.




GNU Bash-2.05               2001 Mar 5                         62





BASH(1)                                                   BASH(1)


       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
       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.



GNU Bash-2.05               2001 Mar 5                         63





BASH(1)                                                   BASH(1)


       ^^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 `:'.

       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



GNU Bash-2.05               2001 Mar 5                         64





BASH(1)                                                   BASH(1)


              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.  When bash is not in posix mode, 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 positional parameters are
              unchanged.  The return status is the status of  the
              last command exited within the script (0 if no com-
              mands 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



GNU Bash-2.05               2001 Mar 5                         65





BASH(1)                                                   BASH(1)


              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] -x keyseq:shell-command
       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-move,  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
                     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.




GNU Bash-2.05               2001 Mar 5                         66





BASH(1)                                                   BASH(1)


              -r keyseq
                     Remove any current binding for keyseq.
              -x keyseq::shell-command
                     Cause  shell-command to be executed whenever
                     keyseq is entered.

              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.

       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



GNU Bash-2.05               2001 Mar 5                         67





BASH(1)                                                   BASH(1)


              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.

       compgen [option] [word]
              Generate  possible  completion  matches  for   word
              according  to  the options, which may be any option
              accepted by the complete builtin with the exception
              of -p and -r, and write the matches to the standard
              output.  When using the -F or -C options, the vari-
              ous shell variables set by the programmable comple-
              tion facilities, while  available,  will  not  have
              useful values.

              The matches will be generated in the same way as if
              the programmable completion code had generated them
              directly  from  a completion specification with the
              same flags.  If word is specified, only those  com-
              pletions matching word will be displayed.

              The  return  value is true unless an invalid option
              is supplied, or no matches were generated.

       complete [-abcdefjkvu] [-o comp-option] [-A action] [-G
       globpat] [-W wordlist] [-P prefix] [-S suffix]
              [-X filterpat]  [-F  function]  [-C  command]  name
              [name _._._.]
       complete -pr [name ...]
              Specify  how  arguments to each name should be com-
              pleted.  If the -p option is  supplied,  or  if  no
              options  are supplied, existing completion specifi-
              cations are printed in a way that allows them to be
              reused  as  input.  The -r option removes a comple-
              tion specification for each name, or, if  no  names
              are supplied, all completion specifications.

              The process of applying these completion specifica-
              tions  when  word  completion   is   attempted   is
              described above under Programmable Completion.

              Other  options,  if  specified,  have the following
              meanings.  The arguments to  the  -G,  -W,  and  -X
              options  (and, if necessary, the -P and -S options)
              should be quoted to  protect  them  from  expansion
              before the complete builtin is invoked.
              -o comp-option
                      The comp-option controls several aspects of
                      the compspec's behavior beyond  the  simple
                      generation of completions.  comp-option may
                      be one of:



GNU Bash-2.05               2001 Mar 5                         68





BASH(1)                                                   BASH(1)


                      default Use readline's  default  completion
                              if   the   compspec   generates  no
                              matches.
                      dirnames
                              Perform directory  name  completion
                              if   the   compspec   generates  no
                              matches.
                      filenames
                              Tell  readline  that  the  compspec
                              generates filenames, so it can per-
                              form any filename-specific process-
                              ing  (like adding a slash to direc-
                              tory names or suppressing  trailing
                              spaces).   Intended to be used with
                              shell functions.
              -A action
                      The action may be one of the  following  to
                      generate a list of possible completions:
                      alias   Alias names.  May also be specified
                              as -a.
                      arrayvar
                              Array variable names.
                      binding Readline key binding names.
                      builtin Names of  shell  builtin  commands.
                              May also be specified as -b.
                      command Command  names.  May also be speci-
                              fied as -c.
                      directory
                              Directory names.  May also be spec-
                              ified as -d.
                      disabled
                              Names of disabled shell builtins.
                      enabled Names of enabled shell builtins.
                      export  Names  of exported shell variables.
                              May also be specified as -e.
                      file    File names.  May also be  specified
                              as -f.
                      function
                              Names of shell functions.
                      helptopic
                              Help topics as accepted by the help
                              builtin.
                      hostname
                              Hostnames, as taken from  the  file
                              specified  by  the  HOSTFILE  shell
                              variable.
                      job     Job  names,  if  job   control   is
                              active.   May  also be specified as
                              -j.
                      keyword Shell reserved words.  May also  be
                              specified as -k.
                      running Names  of running jobs, if job con-
                              trol is active.
                      setopt  Valid arguments for the  -o  option



GNU Bash-2.05               2001 Mar 5                         69





BASH(1)                                                   BASH(1)


                              to the set builtin.
                      shopt   Shell  option  names as accepted by
                              the shopt builtin.
                      signal  Signal names.
                      stopped Names of stopped jobs, if job  con-
                              trol is active.
                      user    User  names.  May also be specified
                              as -u.
                      variable
                              Names of all shell variables.   May
                              also be specified as -v.
              -G globpat
                      The  filename  expansion pattern globpat is
                      expanded to generate the  possible  comple-
                      tions.
              -W wordlist
                      The  wordlist is split using the characters
                      in the IFS special variable as  delimiters,
                      and  each  resultant word is expanded.  The
                      possible completions are the members of the
                      resultant  list  which match the word being
                      completed.
              -C command
                      command is executed in a subshell  environ-
                      ment,  and its output is used as the possi-
                      ble completions.
              -F function
                      The shell function function is executed  in
                      the  current  shell  environment.   When it
                      finishes,  the  possible  completions   are
                      retrieved  from  the value of the COMPREPLY
                      array variable.
              -X filterpat
                      filterpat is a pattern as used for filename
                      expansion.   It  is  applied to the list of
                      possible completions generated by the  pre-
                      ceding options and arguments, and each com-
                      pletion matching filterpat is removed  from
                      the list.  A leading !! in filterpat negates
                      the pattern; in this case,  any  completion
                      not matching filterpat is removed.
              -P prefix
                      prefix  is  added  at the beginning of each
                      possible completion after all other options
                      have been applied.
              -S suffix
                      suffix is appended to each possible comple-
                      tion after  all  other  options  have  been
                      applied.

              The  return  value is true unless an invalid option
              is supplied, an option other than -p or -r is  sup-
              plied  without  a name argument, an attempt is made
              to remove a completion specification for a name for



GNU Bash-2.05               2001 Mar 5                         70





BASH(1)                                                   BASH(1)


              which  no  specification exists, or an error occurs
              adding a completion specification.

       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
              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.




GNU Bash-2.05               2001 Mar 5                         71





BASH(1)                                                   BASH(1)


       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
              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.  The xpg_echo shell  option
              may be used to dynamically determine whether or not
              echo expands these escape  characters  by  default.
              echo  does  not  interpret  ----  to  mean the end of



GNU Bash-2.05               2001 Mar 5                         72





BASH(1)                                                   BASH(1)


              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
              without 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
              support 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 an
              error 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



GNU Bash-2.05               2001 Mar 5                         73





BASH(1)                                                   BASH(1)


              supplied,  the shell places a dash at the beginning
              of 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  sup-
              plied, the shell passes name as the zeroth argument
              to the executed command.  If command cannot be exe-
              cuted  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  exe-
              cuted.   If  command is not specified, any redirec-
              tions 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
              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 -10'' 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



GNU Bash-2.05               2001 Mar 5                         74





BASH(1)                                                   BASH(1)


              editor given by ename is invoked on a file contain-
              ing  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 vari-
              able 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
              characters to be recognized; if a character is fol-
              lowed by a colon, the option is expected to have an
              argument,  which  should  be  separated  from it by
              white space.  The colon and question  mark  charac-
              ters  may  not  be used as option characters.  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



GNU Bash-2.05               2001 Mar 5                         75





BASH(1)                                                   BASH(1)


              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
              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 [-s] [pattern]
              Display helpful information about builtin commands.
              If pattern is specified, help gives  detailed  help
              on  all  commands  matching pattern; otherwise help



GNU Bash-2.05               2001 Mar 5                         76





BASH(1)                                                   BASH(1)


              for all the builtins and shell  control  structures
              is  printed.   The -s option restricts the informa-
              tion displayed to  a  short  usage  synopsis.   The
              return  status  is 0 unless no command matches pat-
              tern.

       history [[_n]]
       history -c
       history -d offset
       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:
              -c     Clear the history list by deleting  all  the
                     entries.
              -d offset
                     Delete the history entry at position offset.
              -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.
              -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, an error occurs while reading or writ-
              ing the history file, an invalid offset is supplied
              as an argument to -d, or the history expansion sup-
              plied as an argument to -p fails.

       jobs [-lnprs] [ jobspec ... ]
       jobs -x command [ args ... ]
              The  first form lists the active jobs.  The options



GNU Bash-2.05               2001 Mar 5                         77





BASH(1)                                                   BASH(1)


              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 [option] [name[=value] ...]
              For  each  argument, a local variable named name is
              created, and assigned value.  The option can be any
              of  the options accepted by declare.  When local is
              used within a function, it causes the variable name
              to have a visible scope restricted to that function
              and its children.  With no operands, local writes a



GNU Bash-2.05               2001 Mar 5                         78





BASH(1)                                                   BASH(1)


              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, an invalid name is supplied, or
              name is a readonly variable.

       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,
              as  appropriate,  had  been  supplied.   The return



GNU Bash-2.05               2001 Mar 5                         79





BASH(1)                                                   BASH(1)


              value is zero on success, non-zero on failure.

       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 pathname of the current working
              directory.  The pathname 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, the pathname
              printed may contain  symbolic  links.   The  return
              status  is  0  unless an error occurs while reading
              the name of the current  directory  or  an  invalid
              option is supplied.

       read  [-ers]  [-t timeout] [-a aname] [-p prompt] [-n
       nchars] [-d delim] [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



GNU Bash-2.05               2001 Mar 5                         80





BASH(1)                                                   BASH(1)


              read  and  for line continuation.  Options, if sup-
              plied, have the following meanings:
              -a aname
                     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.
              -d delim
                     The first character of delim is used to ter-
                     minate  the input line, rather than newline.
              -e     If the standard input is coming from a  ter-
                     minal, readline (see READLINE above) is used
                     to obtain the line.
              -n nchars
                     read returns after reading nchars characters
                     rather  than  waiting for a complete line of
                     input.
              -p prompt
                     Display prompt, without a trailing  newline,
                     before  attempting  to  read any input.  The
                     prompt is displayed only if input is  coming
                     from a terminal.
              -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.
              -s     Silent mode.  If input is coming from a ter-
                     minal, characters are not echoed.
              -t timeout
                     Cause read to time out and return failure if
                     a  complete line of input is not read within
                     timeout seconds.  This option has no  effect
                     if read is not reading input from the termi-
                     nal or a pipe.

              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  or  read  times
              out.

       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  that may 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



GNU Bash-2.05               2001 Mar 5                         81





BASH(1)                                                   BASH(1)


              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,
              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 and  functions
                      which are modified or created for export to
                      the environment 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.



GNU Bash-2.05               2001 Mar 5                         82





BASH(1)                                                   BASH(1)


              -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.
                      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 exe-
                              cuted  (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 (posix mode).
                      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



GNU Bash-2.05               2001 Mar 5                         83





BASH(1)                                                   BASH(1)


                      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
                      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



GNU Bash-2.05               2001 Mar 5                         84





BASH(1)                                                   BASH(1)


                      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 $$##
              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:



GNU Bash-2.05               2001 Mar 5                         85





BASH(1)                                                   BASH(1)


              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.
              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



GNU Bash-2.05               2001 Mar 5                         86





BASH(1)                                                   BASH(1)


                      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).
                      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.
              no_empty_cmd_completion
                      If set, and readline is  being  used,  bash
                      will  not  attempt  to  search the PATH for
                      possible  completions  when  completion  is
                      attempted on an empty line.
              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.
              progcomp
                      If set, the programmable completion facili-
                      ties (see  Programmable  Completion  above)
                      are  enabled.   This  option  is enabled by
                      default.
              promptvars
                      If set, prompt strings undergo variable and
                      parameter expansion after being expanded as
                      described in PROMPTING above.  This  option
                      is enabled by default.




GNU Bash-2.05               2001 Mar 5                         87





BASH(1)                                                   BASH(1)


              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.
              xpg_echo
                      If set, the echo builtin expands backslash-
                      escape sequences 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.
              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.




GNU Bash-2.05               2001 Mar 5                         88





BASH(1)                                                   BASH(1)


              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
                     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
              not present and -p has been supplied, then the trap
              commands associated  with  each  sigspec  are  dis-
              played.  If no arguments are supplied or if only -p



GNU Bash-2.05               2001 Mar 5                         89





BASH(1)                                                   BASH(1)


              is given, trap prints the list of commands  associ-
              ated  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 exe-
              cutable 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  con-
              sulted  when using -a.  type returns true if any of
              the arguments 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:



GNU Bash-2.05               2001 Mar 5                         90





BASH(1)                                                   BASH(1)


              -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
              octal number; otherwise it is interpreted as a sym-
              bolic   mode  mask  similar  to  that  accepted  by
              chmod(1).  If mode is omitted, 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
              argument was supplied, and false otherwise.

       unalias [-aa] [name ...]
              Remove  each name from the list of defined aliases.
              If  -a  is  supplied,  all  alias  definitions  are
              removed.   The  return  value is true unless a sup-
              plied 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



GNU Bash-2.05               2001 Mar 5                         91





BASH(1)                                                   BASH(1)


              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, FUNCNAME, GROUPS, or
              DIRSTACK are unset, they lose their special proper-
              ties, 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

       +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      Specifying a filename  containing  a  slash  as  an
              argument  to the -p option to the hash builtin com-
              mand

       +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



GNU Bash-2.05               2001 Mar 5                         92





BASH(1)                                                   BASH(1)


       +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 Reference Manual, 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
              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.org

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





GNU Bash-2.05               2001 Mar 5                         93





BASH(1)                                                   BASH(1)


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.

       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 Bash-2.05               2001 Mar 5                         94


