


BASH(1)                                                   BASH(1)


NAME
       bash - GNU Bourne-Again SHell

SYNOPSIS
       bash [options] [file]

COPYRIGHT
       Bash  is Copyright (C) 1989, 1991, 1993, 1995, 1996 by the
       Free Software Foundation, 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 ultimately intended to be a conformant implementa-
       tion 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 flags when it is invoked:

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

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




GNU                        1997 May 19                          1





BASH(1)                                                   BASH(1)


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

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

INVOCATION
       A  login  shell  is  one whose first character of argument
       zero is a -, or one started with the --login option.

       An interactive shell  is  one  whose  standard  input  and



GNU                        1997 May 19                          2





BASH(1)                                                   BASH(1)


       output  are  both connected to terminals (as determined by
       isatty(3)), or one started with the -i option.  PS1 is set
       and $- includes i 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,  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 behavior.

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

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

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

       If bash is invoked with the name sh, it tries to mimic the
       startup behavior of historical versions of sh  as  closely
       as  possible,  while  conforming  to the POSIX standard as
       well.  When invoked as a login shell, it first attempts to
       read  and  execute  commands from /etc/profile and ~/.pro-
       file, 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 execute.  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 startup files.   When



GNU                        1997 May 19                          3





BASH(1)                                                   BASH(1)


       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, the ENV variable is expanded
       and  commands  are  read  and executed from the file whose
       name is the expanded value.  No other  startup  files  are
       read.  This is done by interactive shells only.

       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.

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

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



GNU                        1997 May 19                          4





BASH(1)                                                   BASH(1)


       word specifies the command to be executed.  The  remaining
       words are passed as arguments to the invoked command.

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

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

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

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

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

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

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

   Lists
       A list is a sequence of one or more pipelines separated by
       one of the operators ;, &, &&, or ||, and optionally  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



GNU                        1997 May 19                          5





BASH(1)                                                   BASH(1)


              command && command2

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

       An OR list has the form

              command || command2


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

   Compound Commands
       A compound command is one of the following:

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

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

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

       for name [ in word; ] do list ; done
              The list of words following in is expanded,  gener-
              ating a list of items.  The variable name is set to
              each element of this list in turn, and list is exe-
              cuted  each  time.   If the in word is omitted, the
              for command executes list once for each  positional
              parameter that is set (see PARAMETERS below).

       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



GNU                        1997 May 19                          6





BASH(1)                                                   BASH(1)


              displayed  words,  then the value of name is set to
              that word.  If the line is  empty,  the  words  and
              prompt  are  displayed  again.  If EOF is read, the
              command completes.  Any  other  value  read  causes
              name  to be set to null.  The line read is saved in
              the variable REPLY.  The  list  is  executed  after
              each  selection  until a break or return command is
              executed.  The exit status of select  is  the  exit
              status  of  the  last  command executed in list, or
              zero if no commands were executed.

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

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

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

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



GNU                        1997 May 19                          7





BASH(1)                                                   BASH(1)


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 shopt option enabled does
       not allow comments.  The interactive_comments option is on
       by default in interactive shells.

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

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

       A  non-quoted  backslash  (\) is the escape character.  It
       preserves the literal value of  the  next  character  that
       follows, with the exception of <newline>.  If a \<newline>
       pair appears, and the backslash is not quoted, the  \<new-
       line>  is  treated  as a line continuation (that is, it is
       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



GNU                        1997 May 19                          8





BASH(1)                                                   BASH(1)


              \f     form feed
              \n     new line
              \r     carriage return
              \t     horizontal tab
              \v     vertical tab
              \\     backslash
              \nnn   the  character  whose  ASCII  code  is   nnn
                     (octal)

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

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

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

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

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

              name=[value]

       If value is not given, the variable is assigned  the  null
       string.  All values undergo tilde expansion, parameter and
       variable expansion, string  expansion,  command  substitu-
       tion,  arithmetic expansion, and quote removal (see EXPAN-
       SION below).  If the variable has  its  -i  attribute  set
       (see  declare  below in SHELL BUILTIN COMMANDS) then value
       is subject to arithmetic expansion even  if  the  $((...))
       syntax  does  not appear (see Arithmetic Expansion below).
       Word splitting is not performed,  with  the  exception  of
       "$@"  as  explained below under Special Parameters.  Path-
       name 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).



GNU                        1997 May 19                          9





BASH(1)                                                   BASH(1)


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

   Special Parameters
       The  shell  treats  several  parameters  specially.  These
       parameters may only be referenced; assignment to  them  is
       not allowed.
       *      Expands to the positional parameters, starting from
              one.   When  the  expansion  occurs  within  double
              quotes,  it expands to a single word with the value
              of each parameter separated by the first  character
              of  the  IFS  special variable.  That is, ``$*'' is
              equivalent to ``$1c$2c...'', 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 as a separate  word.
              That is, `` $@'' is equivalent to ``$1'' ``$2'' ...
              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
              flag).
       $      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.
       0      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, $0 is set to the
              name of that file.  If bash is started with the  -c
              option,  then $0 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.



GNU                        1997 May 19                         10





BASH(1)                                                   BASH(1)


   Shell Variables
       The following variables are set by the shell:

       PPID   The process ID of the shell's parent.
       PWD    The current working directory as set by the cd com-
              mand.
       OLDPWD The  previous  working  directory  as set by the cd
              command.
       REPLY  Set to the line of input read by the  read  builtin
              command when no arguments are supplied.
       UID    Expands  to  the  user ID of the current user, ini-
              tialized at shell startup.
       EUID   Expands to the effective user  ID  of  the  current
              user, initialized at shell startup.
       GROUPS An  array variable containing the list of groups of
              which the current user is a member.
       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
              An array variable whose members hold version infor-
              mation  for  this  instance  of  bash.   The values
              assigned to the array members are as follows:
              BASH_VERSINFO[0]        The  major  version  number
                                      (the release).
              BASH_VERSINFO[1]        The  minor  version  number
                                      (the version).
              BASH_VERSINFO[2]        The patch level.
              BASH_VERSINFO[3]        The build version.
              BASH_VERSINFO[4]        The release  status  (e.g.,
                                      beta1).
              BASH_VERSINFO[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.




GNU                        1997 May 19                         11





BASH(1)                                                   BASH(1)


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

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

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

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

       OPTARG The value of the last option argument processed  by
              the getopts builtin command (see SHELL BUILTIN 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
              operating system on which bash is  executing.   The
              default is system-dependent.




GNU                        1997 May 19                         12





BASH(1)                                                   BASH(1)


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

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

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

       IFS    The Internal Field Separator that is used for  word
              splitting  after  expansion and to split lines into
              words with the read builtin command.   The  default
              value is ``<space><tab><newline>''.
       PATH   The  search  path  for  commands.   It  is a colon-
              separated 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.
       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  subjected
              to  parameter  expansion, command substitution, and
              arithmetic expansion before being interpreted 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



GNU                        1997 May 19                         13





BASH(1)                                                   BASH(1)


              displaying the primary prompt.  If this variable is
              unset, the shell disables mail checking.
       MAILPATH
              A colon-separated list of file names to be  checked
              for  mail.  The message to be printed may be speci-
              fied by separating the file name from  the  message
              with  a `?'.  $_ stands for the name of the current
              mailfile.  Example:
              MAILPATH='/usr/spool/mail/bfox?"You            have
              mail":~/shell-mail?"$_ has mail!"'
              Bash  supplies  a  default value for this variable,
              but the location of the user  mail  files  that  it
              uses      is      system      dependent      (e.g.,
              /usr/spool/mail/$USER).
       PS1    The  value  of  this  parameter  is  expanded  (see
              PROMPTING  below)  and  used  as the primary prompt
              string.  The default value is ``\s-\v\$ ''.
       PS2    The value of this parameter is expanded as with PS1
              and  used  as  the  secondary  prompt  string.  The
              default is ``> ''.
       PS3    The value of this parameter is used as  the  prompt
              for the select command (see SHELL GRAMMAR above).
       PS4    The value of this parameter is expanded as with PS1
              and the value is printed before each  command  bash
              displays  during  an  execution  trace.   The first
              character of PS4 is replicated multiple  times,  as
              necessary,  to indicate multiple levels of indirec-
              tion.  The default is ``+ ''.
       TIMEFORMAT
              The value of this parameter is  used  as  a  format
              string  specifying  how  the timing information for
              pipelines prefixed  with  the  time  reserved  word
              should be displayed.  The % character introduces an
              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][l]R  The elapsed time in seconds.
              %[p][l]U  The  number  of CPU seconds spent in user
                        mode.
              %[p][l]S  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.




GNU                        1997 May 19                         14





BASH(1)                                                   BASH(1)


              The optional l specifies a longer format, including
              minutes,  of  the  form  MMmSS.FFs.  The value of p
              determines whether or not the fraction is included.

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

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

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

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

       OPTERR If set to the value 1, bash displays error messages
              generated by the getopts builtin command (see SHELL
              BUILTIN COMMANDS below).  OPTERR is initialized  to
              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.

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

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



GNU                        1997 May 19                         15





BASH(1)                                                   BASH(1)


       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.

       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



GNU                        1997 May 19                         16





BASH(1)                                                   BASH(1)


              the line  and  must  fully  specify  the  line  (no
              implicit  `*' is appended).  Each pattern is tested
              against the line  after  the  checks  specified  by
              HISTCONTROL are applied.  In addition to the normal
              shell pattern matching characters, `&' matches  the
              previous  history line.  `&' may be escaped using a
              backslash.   The  backslash   is   removed   before
              attempting a match.

       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, that is, the character  which  sig-
              nals  the  start  of  a history expansion, normally
              `!'.  The second character is the  quick  substitu-
              tion  character, 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  char-
              acter  which  signifies  that  the remainder of the
              line is a comment when found as the first character
              of a word, normally `#'.  The history comment char-
              acter causes history substitution to be skipped for
              the  remaining words on the line.  It does not nec-
              essarily cause the shell parser to treat  the  rest
              of the line as a comment.

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

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



GNU                        1997 May 19                         17





BASH(1)                                                   BASH(1)


              this  provides functionality analogous to the % job
              identifier.

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

       An  array  is  created  automatically  if  any variable is
       assigned to using the syntax  name[subscript]=value.   The
       subscript is treated as an arithmetic expression that must
       evaluate to a number greater than or equal  to  zero.   To
       explicitly  declare  an  array,  use  declare -a name (see
       SHELL BUILTIN COMMANDS below).  declare -a name[subscript]
       is  also  accepted;  the subscript is ignored.  Attributes
       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=(value1 ... valuen), where each value is of the
       form [subscript]=string.  Only string is required.  If the
       optional  brackets  and subscript are supplied, that index
       is  assigned  to;  otherwise  the  index  of  the  element
       assigned  is  the  last index assigned to by the statement
       plus one.  Indexing starts at zero.  This syntax  is  also
       accepted  by  the  declare builtin.  Individual array ele-
       ments may be assigned to using  the  name[subscript]=value
       syntax introduced above.

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



GNU                        1997 May 19                         18





BASH(1)                                                   BASH(1)


       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
       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 postam-
       ble.  The preamble is prefixed to  each  string  contained
       within  the  braces, and the postamble 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



GNU                        1997 May 19                         19





BASH(1)                                                   BASH(1)


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

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

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

       Brace expansion introduces a slight  incompatibility  with
       historical  versions  of sh.  sh does not treat opening or
       closing braces specially when they appear  as  part  of  a
       word,  and  preserves  them  in  the output.  Bash removes
       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 a tilde character (`~'), all of  the
       characters  preceding  the first slash (or all characters,
       if there is no slash) are  treated  as  a  possible  login
       name.  If this login name is the null string, the tilde is
       replaced with the value of the parameter HOME.  If HOME is
       unset,  the home directory of the user executing the shell
       is substituted instead.

       If a `+' follows the tilde, the value of PWD replaces  the
       tilde  and  `+'.  If a `-' follows, the value of OLDPWD is
       substituted.  If the value following the tilde is a  valid
       login name, the tilde and login name are replaced with the
       home directory associated with that name.  If the name  is
       invalid,  or  the  tilde  expansion  fails,  the  word  is
       unchanged.

       Each variable assignment is checked  for  unquoted  tildes
       immediately  following  a  :  or =.  In these cases, tilde
       substitution is also performed.  Consequently, one may use
       file  names  with tildes in assignments to PATH, MAILPATH,
       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



GNU                        1997 May 19                         20





BASH(1)                                                   BASH(1)


       could be interpreted as part of the name.

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

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

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

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



GNU                        1997 May 19                         21





BASH(1)                                                   BASH(1)


              offset evaluates to a number less  than  zero,  the
              value  is  used  as  an  offset from the end of the
              value of parameter.  If parameter is @, the  result
              is  length  positional parameters beginning at off-
              set.  If parameter is an array name indexed by @ or
              *,  the  result  is the length members of the array
              beginning  with  ${parameter[offset]}.    Substring
              indexing is zero-based unless the positional param-
              eters are used, in which case the  indexing  starts
              at 1.

       ${#parameter}
              The  length in characters of the value of parameter
              is substituted.  If parameter is * or @, the length
              substituted is the number of positional parameters.
              If parameter is an array name subscripted by  *  or
              @, the length 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
              expansion is the value of parameter with the short-
              est  matching  pattern  (the  ``#''  case)  or  the
              longest matching pattern (the ``##'' case) deleted.
              If parameter is @ or *, the pattern removal  opera-
              tion  is  applied  to  each positional parameter in
              turn, and the expansion is the resultant list.   If
              parameter  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%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 value  of  parameter,  then
              the  expansion  is  the 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  opera-
              tion  is  applied  to  each positional parameter in
              turn, and the expansion is the resultant list.   If
              parameter  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



GNU                        1997 May 19                         22





BASH(1)                                                   BASH(1)


              as  in  pathname  expansion.  Parameter is expanded
              and the longest match of pattern against its  value
              is  replaced  with string.  In the first form, only
              the first  match  is  replaced.   The  second  form
              causes  all  matches of pattern to be replaced with
              string.  If pattern begins with #, it must match at
              the beginning of string.  If pattern begins with %,
              it must match at the end of string.  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.

       When the old-style backquote form of substitution is used,
       backslash retains its literal meaning except when followed
       by  $, `, or \.  When using the $(command) form, all char-
       acters between the parentheses make up the  command;  none
       are treated specially.

       Command  substitutions  may be nested.  To nest when using
       the old form,  escape  the  inner  backquotes  with  back-
       slashes.

       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
       treated  specially.   All tokens in the expression undergo



GNU                        1997 May 19                         23





BASH(1)                                                   BASH(1)


       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.

       On systems that support it, process substitution  is  per-
       formed  simultaneously  with parameter and variable expan-
       sion, 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                        1997 May 19                         24





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  option  is
       set,  and no matches are found, the word is removed.  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.   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 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.

       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 minus sign  denotes  a
              range;  any  character  lexically between those two
              characters, inclusive, is matched.   If  the  first
              character  following  the [ is a !  or a ^ then any
              character not enclosed is  matched.   A  -  may  be
              matched  by including it as the first or last char-
              acter in the set.  A ] may be matched by  including
              it as the first character in the set.

   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                        1997 May 19                         25





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 that follows the redirection operator in the fol-
       lowing descriptions is subjected to brace expansion, tilde
       expansion,   parameter  expansion,  command  substitution,
       arithmetic expansion, quote removal, and  pathname  expan-
       sion.   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.

   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:




GNU                        1997 May 19                         26





BASH(1)                                                   BASH(1)


              [n]>word

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

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

       The general format for appending output is:

              [n]>>word


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

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

              &>word
       and
              >&word

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

              >word 2>&1

   Here Documents
       This type of redirection instructs the shell to read input
       from the current source until a line containing only  word
       (with  no trailing blanks) is seen.  All of the lines read
       up to that point are then used as the standard input for a
       command.

       The format of here-documents is as follows:

              <<[-]word
                      here-document
              delimiter

       No  parameter  expansion,  command  substitution, pathname



GNU                        1997 May 19                         27





BASH(1)                                                   BASH(1)


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

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

   Duplicating File Descriptors
       The redirection operator

              [n]<&word

       is used to duplicate  input  file  descriptors.   If  word
       expands to one or more digits, the file descriptor denoted
       by n is made to be a copy of  that  file  descriptor.   If
       word evaluates to -, file descriptor n is closed.  If n is
       not specified, the standard input (file descriptor  0)  is
       used.

       The operator

              [n]>&word

       is  used  similarly  to duplicate output file descriptors.
       If n is not specified, the standard output (file  descrip-
       tor  1)  is used.  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 pre-
       viously.

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



GNU                        1997 May 19                         28





BASH(1)                                                   BASH(1)


       contain  any  valid shell input, including the metacharac-
       ters listed above, with the exception that the alias  name
       may not contain =.  The first word of the replacement text
       is tested for aliases, but a word that is identical to  an
       alias  being expanded is not expanded a second time.  This
       means that one may alias ls to ls -F,  for  instance,  and
       bash  does  not  try to recursively expand the replacement
       text.  If the last character  of  the  alias  value  is  a
       blank,  then  the next command word following the alias is
       also checked for alias expansion.

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

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

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

       The rules concerning the definition and use of aliases are
       somewhat  confusing.   Bash always reads at least one com-
       plete line of input before executing any of  the  commands
       on  that  line.   Aliases  are  expanded when a command is
       read, not when it is executed.  Therefore, an alias  defi-
       nition  appearing on the same line as another command does
       not take effect until the next line of input is read.  The
       commands  following  the alias definition on that line are
       not affected by the new alias.  This behavior is  also  an
       issue  when  functions are executed.  Aliases are expanded
       when the function definition is read, not when  the  func-
       tion  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.

       Note that for almost every purpose, aliases are superseded
       by shell functions.

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



GNU                        1997 May 19                         29





BASH(1)                                                   BASH(1)


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

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

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

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

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

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

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

       If  this  execution  fails  because  the  file  is  not in



GNU                        1997 May 19                         30





BASH(1)                                                   BASH(1)


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

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

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

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

       If the -k flag is set (see the set builtin command below),
       then  all parameter assignments are placed in the environ-
       ment for a command, not just those that precede  the  com-
       mand 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.




GNU                        1997 May 19                         31





BASH(1)                                                   BASH(1)


EXIT STATUS
       For  the purposes of the shell, 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,  bash
       uses the value of 128+signal as the exit status.

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

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

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

SIGNALS
       When bash is interactive, it ignores SIGTERM (so that kill
       0 does not kill  an  interactive  shell),  and  SIGINT  is
       caught and handled (so that the wait builtin is interrupt-
       ible).  In all cases, bash ignores SIGQUIT.  If  job  con-
       trol  is  in  effect,  bash  ignores SIGTTIN, SIGTTOU, and
       SIGTSTP.

       Synchronous jobs started by bash have signals set  to  the
       values  inherited  by the shell from its parent.  When job
       control is not in effect, background  jobs  (jobs  started
       with  &)  ignore  SIGINT  and  SIGQUIT.  Commands run as a
       result  of  command  substitution  ignore  the   keyboard-
       generated  job control signals SIGTTIN, SIGTTOU, and SIGT-
       STP.

       The shell exits by  default  upon  receipt  of  a  SIGHUP.
       Before exiting, it resends the SIGHUP to all jobs, running
       or stopped.  To prevent the shell from sending the  signal
       to  a  particular  job, remove it from the jobs table with
       the disown builtin (see SHELL BUILTIN COMMANDS  below)  or
       use disown -h to mark it to not receive SIGHUP.

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



GNU                        1997 May 19                         32





BASH(1)                                                   BASH(1)


       asynchronously (in the background), it prints a line  that
       looks like:

              [1] 25647

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

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

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

       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 %n.  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.  The previous job
       may be referenced using %-.  In output pertaining to  jobs
       (e.g., the output of the jobs command), the current job is



GNU                        1997 May 19                         33





BASH(1)                                                   BASH(1)


       always flagged with a +, and the previous job with a -.

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

       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 set, bash reports such changes  immedi-
       ately.

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

PROMPTING
       When executing interactively, bash  displays  the  primary
       prompt  PS1  when  it  is ready to read a command, and the
       secondary prompt PS2 when it needs more input to  complete
       a  command.   Bash  allows these prompt strings to be cus-
       tomized by inserting a number of backslash-escaped special
       characters that are decoded as follows:
              \a     an ASCII bell character (07)
              \d     the  date  in  "Weekday  Month  Date" format
                     (e.g., "Tue May 26")
              \e     an ASCII escape character (033)
              \h     the hostname up to the first `.'
              \H     the hostname
              \n     newline
              \s     the name of the shell, the  basename  of  $0
                     (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                        1997 May 19                         34





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, string expansion,
       and  quote removal, subject to the value of the promptvars
       shell option (see the description  of  the  shopt  command
       under SHELL BUILTIN COMMANDS below).

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

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

       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                        1997 May 19                         35





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

       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



GNU                        1997 May 19                         36





BASH(1)                                                   BASH(1)


       sequence within double quotes.  Some GNU Emacs  style  key
       escapes can be used, as in the following example.

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

       In  this  example, C-u is again bound to the function uni-
       versal-argument.   C-x  C-r  is  bound  to  the   function
       re-read-init-file,  and ESC [ 1 1 ~ is bound to insert the
       text Function Key 1.  The full set of escape sequences is

              \C-    control prefix

              \M-    meta prefix

              \e     an escape character

              \\     backslash

              \"     literal "

              \'     literal '

       When entering the text of a macro, single or double quotes
       should  be  used to indicate a macro definition.  Unquoted
       text is assumed to be a  function  name.   Backslash  will
       quote  any 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  cus-
       tomize its behavior.  A variable may be set in the inputrc
       file with a statement of the form

              set variable-name value

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

       bell-style (audible)
              Controls  what  happens when readline wants to ring
              the terminal bell.  If set to none, readline  never
              rings the bell.  If set to visible, readline uses a
              visible bell if one is available.  If set to  audi-
              ble, readline attempts to ring the terminal's bell.
       comment-begin (``#'')
              The string  that  is  inserted  when  the  readline
              insert-comment  command  is executed.  This command



GNU                        1997 May 19                         37





BASH(1)                                                   BASH(1)


              is bound to M-# in emacs mode and to # in  vi  com-
              mand mode.
       completion-query-items (100)
              This  determines  when  the  user  is queried about
              viewing the number of possible  completions  gener-
              ated  by  the possible-completions command.  It may
              be set to any integer value greater than  or  equal
              to  zero.  If the number of possible completions is
              greater than or equal to the value  of  this  vari-
              able, the user is asked whether or not he wishes to
              view them; otherwise they are simply listed on  the
              terminal.
       convert-meta (On)
              If set to On, readline will convert characters with
              the eighth bit set to  an  ASCII  key  sequence  by
              stripping  the  eighth bit and prepending an escape
              character (in effect, using escape as the meta pre-
              fix).
       disable-completion (Off)
              If  set  to  On, readline will inhibit word comple-
              tion.  Completion characters will be inserted  into
              the line as if they had been mapped to self-insert.
       editing-mode (emacs)
              Controls whether readline begins with a set of  key
              bindings  similar to emacs or vi.  editing-mode can
              be set to either emacs or vi.
       enable-keypad (Off)
              When set to On, readline will  try  to  enable  the
              application keypad when it is called.  Some systems
              need this to enable the arrow keys.
       expand-tilde (Off)
              If set to on, tilde  expansion  is  performed  when
              readline attempts word completion.
       horizontal-scroll-mode (Off)
              When  set  to  On, makes readline use a single line
              for display, scrolling the input horizontally on  a
              single  screen line when it becomes longer than the
              screen width rather than wrapping to a new line.
       input-meta (Off)
              If set to On, readline will enable eight-bit  input
              (that  is,  it will not strip the high bit from the
              characters it reads), regardless of what the termi-
              nal claims it can support.  The name meta-flag is a
              synonym for this variable.
       keymap (emacs)
              Set the current readline keymap.  The set of  legal
              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



GNU                        1997 May 19                         38





BASH(1)                                                   BASH(1)


              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.
       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 three parser
       directives used.

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

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

              term   The term= form may be used to include termi-
                     nal-specific  key  bindings, perhaps to bind
                     the key sequences output by  the  terminal's
                     function  keys.   The word on the right side
                     of the = is tested against the 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



GNU                        1997 May 19                         39





BASH(1)                                                   BASH(1)


                     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 you saw in the  previous  example,
              terminates an $if command.

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

   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 Escape character  is  used
       to  terminate  an incremental search.  Control-J will also
       terminate the search.  Control-G will abort an incremental
       search  and restore the original line.  When the search is
       terminated, the history entry containing the search string
       becomes  the current line.  To find other matching entries
       in the history list, type Control-S or Control-R as appro-
       priate.   This will search backward or forward in the his-
       tory for the next entry matching the search  string  typed
       so  far.   Any other key sequence bound to a readline com-
       mand 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 part of the con-
       tents 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.





GNU                        1997 May 19                         40





BASH(1)                                                   BASH(1)


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

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



GNU                        1997 May 19                         41





BASH(1)                                                   BASH(1)


              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 current cursor position (the point).  This
              is a non-incremental search.
       history-search-backward
              Search backward through the history for the  string
              of characters between the start of the current line
              and the point.  This is a non-incremental search.
       yank-nth-arg (M-C-y)
              Insert the first argument to the  previous  command
              (usually  the  second word on the previous line) at
              point (the current cursor position).  With an argu-
              ment  n, insert the nth word from the previous com-
              mand (the words in the previous command begin  with
              word  0).  A negative argument inserts the nth word
              from the end of the previous command.
       yank-last-arg (M-., M-_)
              Insert the last argument to  the  previous  command
              (the  last  word  of  the  previous history entry).
              With an argument, behave exactly like yank-nth-arg.
       shell-expand-line (M-C-e)
              Expand  the  line  the  way  the shell does when it
              reads it.  This performs alias and  history  expan-
              sion  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.
       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 under the cursor.  If point is
              at  the beginning of the line, there are no charac-
              ters in the line, and the last character typed  was



GNU                        1997 May 19                         42





BASH(1)                                                   BASH(1)


              not C-d, then return EOF.
       backward-delete-char (Rubout)
              Delete the character behind the cursor.  When given
              a numeric argument, save the deleted  text  on  the
              kill ring.
       quoted-insert (C-q, C-v)
              Add  the  next  character that you type 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, 1, !, ...)
              Insert the character typed.
       transpose-chars (C-t)
              Drag  the  character  before point forward over the
              character at point.  Point moves forward  as  well.
              If  point is at the end of the line, then transpose
              the two characters before  point.   Negative  argu-
              ments don't work.
       transpose-words (M-t)
              Drag  the  word  behind the cursor past the word in
              front of the cursor moving  the  cursor  over  that
              word as well.
       upcase-word (M-u)
              Uppercase  the current (or following) word.  With a
              negative argument, do the previous word, but do not
              move point.
       downcase-word (M-l)
              Lowercase  the current (or following) word.  With a
              negative argument, do the previous word, but do not
              move point.
       capitalize-word (M-c)
              Capitalize the current (or following) word.  With a
              negative argument, do the previous word, but do not
              move point.

   Killing and Yanking
       kill-line (C-k)
              Kill  the  text from the current cursor position to
              the end of the line.
       backward-kill-line (C-x Rubout)
              Kill backward to the beginning of the line.
       unix-line-discard (C-u)
              Kill backward from point to the  beginning  of  the
              line.
       kill-whole-line
              Kill  all characters on the current line, no matter
              where the cursor is.
       kill-word (M-d)
              Kill from the cursor to  the  end  of  the  current
              word,  or  if between words, to the end of the next
              word.  Word boundaries are the same as  those  used
              by forward-word.




GNU                        1997 May 19                         43





BASH(1)                                                   BASH(1)


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

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



GNU                        1997 May 19                         44





BASH(1)                                                   BASH(1)


              match, filename completion is attempted.
       possible-completions (M-?)
              List the possible completions of  the  text  before
              point.
       insert-completions (M-*)
              Insert  all  completions  of  the text before point
              that  would   have   been   generated   by   possi-
              ble-completions.
       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,
              reserved  words,  shell  functions,  builtins,  and
              finally executable filenames, in that order.
       possible-command-completions (C-x !)
              List  the  possible  completions of the text before
              point, treating it as a command name.
       dynamic-complete-history (M-TAB)
              Attempt completion on the text before  point,  com-
              paring the text against lines from the history list
              for possible completion matches.
       complete-into-braces (M-{)
              Perform filename completion and return the list  of
              possible  completions enclosed within braces so the
              list is available to the shell (see Brace Expansion
              above).

   Keyboard Macros
       start-kbd-macro (C-x ()
              Begin  saving the characters typed into the current



GNU                        1997 May 19                         45





BASH(1)                                                   BASH(1)


              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, M-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 f 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
              typing the undo command enough times to return  the
              line to its initial state.
       tilde-expand (M-~)
              Perform tilde expansion on the current word.
       set-mark (C-@, M-<space>)
              Set  the  mark  to the current point.  If a numeric
              argument is supplied, the mark is set to that posi-
              tion.
       exchange-point-and-mark (C-x C-x)
              Swap  the  point with the mark.  The current cursor
              position is set to the saved position, and the  old
              cursor position is saved as the mark.
       character-search (C-])
              A  character is read and point is moved to the next
              occurrence of that  character.   A  negative  count
              searches for previous occurrences.
       character-search-backward (M-C-])
              A  character is read and point is moved to the pre-
              vious occurrence of  that  character.   A  negative
              count searches for subsequent occurrences.
       insert-comment (M-#)
              The value of the readline comment-begin variable is
              inserted at the beginning of the current line,  and
              the  line  is  accepted  as  if  a newline had been



GNU                        1997 May 19                         46





BASH(1)                                                   BASH(1)


              typed.  This makes the current line  a  shell  com-
              ment.
       glob-expand-word (C-x *)
              The  word  before point is treated as a pattern for
              pathname expansion, and the list of  matching  file
              names is inserted, replacing the word.
       glob-list-expansions (C-x g)
              The  list of expansions that would have been gener-
              ated by glob-expand-word is displayed, and the line
              is redrawn.
       dump-functions
              Print  all  of the functions and their key bindings
              to the readline output stream.  If a numeric  argu-
              ment is supplied, the output is formatted in such a
              way that it can be made part of an inputrc file.
       dump-variables
              Print all of the settable  readline  variables  and
              their  values  to the readline output stream.  If a
              numeric argument is supplied, the output is format-
              ted  in  such  a way that it can be made part of an
              inputrc file.
       dump-macros
              Print all of the readline key  sequences  bound  to
              macros  and  the  strings they ouput.  If a numeric
              argument is supplied, the output  is  formatted  in
              such  a  way that it can be made part of an inputrc
              file.
       display-shell-version (C-x C-v)
              Display  version  information  about  the   current
              instance of bash.

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




GNU                        1997 May 19                         47





BASH(1)                                                   BASH(1)


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

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

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

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

       History expansion is performed immediately  after  a  com-
       plete line is read, before the shell breaks it into words.
       It takes place in two parts.  The first  is  to  determine
       which line from the previous history to use during substi-
       tution.  The second is to select portions of that line for
       inclusion  into  the  current one.  The line selected from
       the previous history is the event,  and  the  portions  of
       that  line  that  are acted upon are words.  Various modi-
       fiers 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  surrounded  by  quotes  are considered as one word.
       History expansions are introduced by the appearance of the
       history  expansion character, which is ! by default.  Only
       backslash (\) and single  quotes  can  quote  the  history
       expansion character.

       Several  shell options settable with the shopt builtin may



GNU                        1997 May 19                         48





BASH(1)                                                   BASH(1)


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

       0 (zero)
              The  zeroth  word.  For the shell, this is the com-
              mand word.



GNU                        1997 May 19                         49





BASH(1)                                                   BASH(1)


       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 x*, 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 `:'.

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

ARITHMETIC EVALUATION
       The shell allows arithmetic expressions to  be  evaluated,



GNU                        1997 May 19                         50





BASH(1)                                                   BASH(1)


       under  certain  circumstances (see the let builtin command
       and Arithmetic Expansion).  Evaluation  is  done  in  long
       integers  with no check for overflow, though division by 0
       is trapped and flagged as an error.  The following list of
       operators is grouped into levels of equal-precedence oper-
       ators.  The levels  are  listed  in  order  of  decreasing
       precedence.

       - +    unary minus and plus
       ! ~    logical and bitwise negation
       * / %  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

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

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

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

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



GNU                        1997 May 19                         51





BASH(1)                                                   BASH(1)


              redirections.  A zero exit code is returned.

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

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

       bg [jobspec]
              Place  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 job-
              spec returns 0 unless run when job control is  dis-
              abled  or,  when  run  with job control enabled, if
              jobspec was not found or started without  job  con-
              trol.

       bind [-m keymap] [-lpsvPSV] [-q name] [-r keyseq]
       bind [-m keymap] -f filename
       bind [-m keymap] keyseq:function-name
              Display current readline key and function bindings,
              or bind a key sequence to a  readline  function  or
              macro.  The binding syntax accepted is identical to
              that of .inputrc, but each binding must  be  passed
              as   a   separate   argument;   e.g.,  '"\C-x\C-r":
              re-read-init-file'.  Options, if supplied, have the
              following meanings:




GNU                        1997 May 19                         52





BASH(1)                                                   BASH(1)


              -m keymap
                     Use  keymap  as the keymap to be affected by
                     the subsequent bindings.  Acceptable  keymap
                     names are emacs, emacs-standard, emacs-meta,
                     emacs-ctlx, vi, vi-command,  and  vi-insert.
                     vi  is  equivalent  to  vi-command; emacs is
                     equivalent to emacs-standard.
              -l     List the names of all readline functions.
              -p     Display readline function names and bindings
                     in such a way that they can be re-read.
              -P     List  current  readline  function  names and
                     bindings.
              -v     Display readline variable names  and  values
                     in such a way that they can be re-read.
              -V     List  current  readline  variable  names and
                     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.
              -r keyseq
                     Remove any current binding for keyseq.

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

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

       builtin shell-builtin [arguments]
              Execute the specified  shell  builtin,  passing  it
              arguments,  and  return  its  exit status.  This is
              useful when you wish to  define  a  function  whose
              name  is  the same as a shell builtin, but need the
              functionality of the builtin  within  the  function
              itself.   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



GNU                        1997 May 19                         53





BASH(1)                                                   BASH(1)


              containing dir.   Alternative  directory  names  in
              CDPATH are separated by a colon (:).  A null direc-
              tory 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 sym-
              bolic links to be followed.  An argument  of  -  is
              equivalent to $OLDPWD.  The return value is true if
              the directory was successfully changed; false  oth-
              erwise.

       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 printed; the -V option produces  a  more
              verbose  description.   If  the  -V or -v option is
              supplied, the exit  status  is  0  if  command  was
              found, and 1 if not.  If neither option is supplied
              and an error occurred or command cannot  be  found,
              the exit status is 127.  Otherwise, the exit status
              of the command builtin is the exit status  of  com-
              mand.

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

       declare [-afFirx] [-p] [name[=value]]
       typeset [-afFirx] [-p] [name[=value]]
              Declare  variables and/or give them attributes.  If
              no names are given then display the values of vari-
              ables.   The  -p option will display the attributes
              and values of each name.  When -p  is  used,  addi-
              tional options are ignored.  The -F option inhibits
              the display of function definitions; only the func-
              tion  name  and  attributes  are  printed.   The -F
              option implies -f.  The following  options  can  be
              used to restrict output to variables with the spec-
              ified attribute or to give variables attributes:
              -a     Each name is an array variable  (see  Arrays



GNU                        1997 May 19                         54





BASH(1)                                                   BASH(1)


                     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.
              -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 illegal
              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 legal
              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-
              existent function with -f.

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

              The  return  value is 0 unless an illegal option is



GNU                        1997 May 19                         55





BASH(1)                                                   BASH(1)


              supplied or n indexes beyond the end of the  direc-
              tory stack.

       disown [-h] [jobspec ...]
              Without  options,  each jobspec is removed from the
              table of active jobs.  If the -h option  is  given,
              the  job  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,
              the current job is used.  The  return  value  is  0
              unless a jobspec does not specify a valid job.

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

       enable [-adnps] [-f filename] [name ...]
              Enable  and  disable  builtin shell commands.  This
              allows the execution of a disk  command  which  has
              the same name as a shell builtin without specifying
              a full file name.  If -n is used, each name is dis-
              abled;  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



GNU                        1997 May 19                         56





BASH(1)                                                   BASH(1)


              indication of whether or not each is  enabled.   If
              -s  is  supplied,  the  output is restricted to the
              POSIX special builtins.   The  return  value  is  0
              unless  a name is not a shell builtin or there is a
              problem loading a new builtin from a shared object.

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

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

       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 illegal option is encountered,  one  of
              the names is not a legal 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



GNU                        1997 May 19                         57





BASH(1)                                                   BASH(1)


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

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

              If  the  first  form is used, the return value is 0
              unless an illegal 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]
              Place 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



GNU                        1997 May 19                         58





BASH(1)                                                   BASH(1)


              letters to be recognized; if a letter  is  followed
              by a colon, the option is expected to have an argu-
              ment, which should be separated from  it  by  white
              space.  Each time it is invoked, getopts places the
              next option in the shell variable name,  initializ-
              ing name if it does not exist, and the index of the
              next argument to be  processed  into  the  variable
              OPTIND.   OPTIND  is initialized to 1 each time the
              shell or a shell script is invoked.  When an option
              requires  an argument, getopts places that argument
              into the variable OPTARG.  The shell does not reset
              OPTIND  automatically;  it  must  be manually reset
              between multiple calls to getopts within  the  same
              shell  invocation  if a new set of parameters is to
              be used.

              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 illegal options or
              missing option arguments are encountered.   If  the
              variable  OPTERR is set to 0, no error message will
              be displayed, even if the first character  of  opt-
              string is not a colon.

              If an illegal 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 normally parses the positional  parameters,
              but  if  more  arguments are given in args, getopts
              parses those instead.  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



GNU                        1997 May 19                         59





BASH(1)                                                   BASH(1)


              status  is  true  unless  a name is not found or an
              illegal option is supplied.

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

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

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

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



GNU                        1997 May 19                         60





BASH(1)                                                   BASH(1)


              -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 illegal option is encountered or an ille-
              gal 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 [signum | sigspec]
              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 specified signals are
              listed, and the return status is 0.  The  arguments
              to -l may be either signal names or signal numbers;
              if signal names are given, the corresponding signal
              number is displayed.  kill returns true if at least
              one signal was successfully sent, or  false  if  an
              error occurs or an illegal option is encountered.

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

       local [name[=value] ...]
              For each argument, create a  local  variable  named
              name,  and  assign  it  value.   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
              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



GNU                        1997 May 19                         61





BASH(1)                                                   BASH(1)


              outside a function, or an illegal name is supplied.

       logout Exit a login shell.

       popd [-n] [+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 illegal option is  encountered,
              the directory stack is empty, a non-existent direc-
              tory stack entry is  specified,  or  the  directory
              change fails.

       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



GNU                        1997 May 19                         62





BASH(1)                                                   BASH(1)


              second  form,  pushd returns 0 unless the directory
              stack is empty, a non-existent directory stack ele-
              ment  is  specified, or the directory change to the
              specified new current directory fails.

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

       read [-er] [-a aname] [-p prompt] [name ...]
              One  line  is read from the standard input, and the
              first word is assigned to the first name, the  sec-
              ond  word to the second name, and so on, with left-
              over words assigned to the  last  name.   Only  the
              characters  in  IFS  are  recognized as word delim-
              iters.  Options, if supplied,  have  the  following
              meanings:
              -r     A backslash-newline pair is not ignored, and
                     the backslash is considered to  be  part  of
                     the line.
              -p     Display  prompt, without a trailing newline,
                     before attempting to read  any  input.   The
                     prompt  is displayed only if input is coming
                     from a terminal.
              -a     The words are assigned to sequential indices
                     of  the array variable aname, starting at 0.
                     aname is unset before  any  new  values  are
                     assigned.
              -e     If  the standard input is coming from a ter-
                     minal, readline (see READLINE above) is used
                     to obtain the line.

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

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



GNU                        1997 May 19                         63





BASH(1)                                                   BASH(1)


       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  re-
              used  as  input.   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  $1,  $2,  ...   $n.
              Options, if specified, have the following meanings:
              -a      Automatically mark variables which are mod-
                      ified or created for export to the environ-
                      ment of subsequent commands.
              -b      Report  the status of terminated background
                      jobs immediately, rather  than  before  the
                      next  primary  prompt.   This  is effective
                      only when job control is enabled.
              -e      Exit immediately if a simple  command  (see
                      SHELL  GRAMMAR above) exits with a non-zero
                      status.  The shell does  not  exit  if  the
                      command  that  fails is part of an until or
                      while loop, part of an if  statement,  part
                      of  a  &&  or  || list, or if the command's
                      return value is being inverted via !.
              -f      Disable pathname expansion.
              -h      Remember the location of commands  as  they
                      are looked up for execution.  This is on 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 flag is on by default for  interactive
                      shells  on systems that support it (see JOB
                      CONTROL above).  Background  processes  run
                      in a separate process group and a line con-
                      taining their exit status is  printed  upon
                      their completion.
              -n      Read  commands  but  do  not  execute them.
                      This may be used to check  a  shell  script
                      for  syntax  errors.   This  is  ignored by



GNU                        1997 May 19                         64





BASH(1)                                                   BASH(1)


                      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 executed
                              (see Shell Variables above).
                      keyword Same as -k.
                      monitor Same as -m.
                      noclobber
                              Same as -C.
                      noexec  Same as -n.
                      noglob  Same as -f.
                      notify  Same as -b.
                      nounset Same as -u.
                      onecmd  Same as -t.
                      physical
                              Same as -P.
                      posix   Change the behavior of  bash  where
                              the  default operation differs from
                              the POSIX 1003.2 standard to  match
                              the standard.
                      privileged
                              Same as -p.
                      verbose Same as -v.
                      vi      Use a vi-style command line editing
                              interface.
                      xtrace  Same as -x.
                      If -o is supplied with no option-name,  the
                      values  of the current options are printed.
                      If +o is supplied with  no  option-name,  a
                      series of set commands to recreate the cur-
                      rent option settings is  displayed  on  the
                      standard output.
              -p      Turn on privileged mode.  In this mode, the
                      $ENV  file  is  not  processed,  and  shell



GNU                        1997 May 19                         65





BASH(1)                                                   BASH(1)


                      functions  are not inherited from the envi-
                      ronment.  This is enabled automatically  on
                      startup if the effective user (group) id is
                      not equal to  the  real  user  (group)  id.
                      Turning  this  option off causes the effec-
                      tive 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
                      flag 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 flag, then  the
                      positional  parameters  are  unset.  Other-
                      wise, the positional parameters are set  to
                      the args, even if some of them begin with a
                      -.
              -       Signal  the  end  of  options,  cause   all
                      remaining  args to be assigned to the posi-
                      tional parameters.  The -x and  -v  options
                      are  turned off.  If there are no args, the
                      positional parameters remain unchanged.

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



GNU                        1997 May 19                         66





BASH(1)                                                   BASH(1)


              encountered.

       shift [n]
              The positional parameters from n+1 ... are  renamed
              to  $1  ....  Parameters represented by the numbers
              $# down to $#-n+1 are unset.   n  must  be  a  non-
              negative  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.  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 legal shell option.

              The list of shopt options is:

              cdable_vars
                      If set, an argument to the cd builtin  com-
                      mand  that is not a directory is assumed to
                      be the name of a variable  whose  value  is
                      the directory to change to.
              cdspell If  set,  minor errors in the spelling of a
                      directory component in a cd command will be
                      corrected.   The  errors  checked  for  are
                      transposed characters, a missing character,
                      and   one   character   too   many.   If  a



GNU                        1997 May 19                         67





BASH(1)                                                   BASH(1)


                      correction 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.
              histappend
                      If set, the history list is appended to the
                      file named by the  value  of  the  HISTFILE
                      variable  when the shell exits, rather than
                      overwriting the file.
              histreedit
                      If set, and readline is being used, a  user
                      is  given  the  opportunity  to  re-edit  a
                      failed history substitution.
              histverify
                      If set, and readline  is  being  used,  the
                      results  of  history  substitution  are not
                      immediately passed  to  the  shell  parser.
                      Instead,  the resulting line is loaded into
                      the readline editing buffer, allowing  fur-
                      ther modification.
              hostcomplete
                      If  set,  and  readline is being used, bash
                      will attempt to perform hostname completion
                      when  a word beginning with @ is being com-
                      pleted  (see  Completing   under   READLINE
                      above).  This is enabled by default.
              interactive_comments
                      If  set,  allow  a word beginning with # to



GNU                        1997 May 19                         68





BASH(1)                                                   BASH(1)


                      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.
              nullglob
                      If set, bash allows patterns which match no
                      files  (see  Pathname  Expansion  above) to
                      expand to a null string, rather than  them-
                      selves.
              promptvars
                      If set, prompt strings undergo variable and
                      parameter expansion after being expanded as
                      described  in PROMPTING above.  This option
                      is enabled by default.
              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 is enabled by default.
       suspend [-f]
              Suspend  the  execution  of  this  shell  until  it
              receives a SIGCONT signal.  The -f option says  not
              to  complain if this is a login shell; just suspend
              anyway.  The return status is 0 unless the shell is
              a  login  shell  and  -f is not supplied, or if job
              control is not enabled.
       test expr
       [ expr ]
              Return a status of 0 or 1 depending on the  evalua-
              tion  of  the conditional expression expr.  Expres-
              sions may be unary or  binary.   Unary  expressions
              are  often  used  to  examine the status of a file.
              There are string operators and  numeric  comparison
              operators  as well.  Each operator and operand must
              be a separate argument.  If file  is  of  the  form
              /dev/fd/n,  then  file  descriptor  n  is  checked.
              Expressions are  composed  of  the  following  pri-
              maries:
              -b file
                     True  if  file exists and is a block special
                     file.



GNU                        1997 May 19                         69





BASH(1)                                                   BASH(1)


              -c file
                     True if file exists and is a character  spe-
                     cial 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.
              -k file
                     True if file has its ``sticky'' bit set.
              -L file
                     True  if file exists and is a symbolic link.
              -p file
                     True if file exists and is a named pipe.
              -r file
                     True if file exists and is readable.
              -s file
                     True if file exists and has a  size  greater
                     than zero.
              -S file
                     True if file exists and is a socket.
              -t fd  True if fd is opened on a terminal.
              -u file
                     True  if file exists and its set-user-id bit
                     is set.
              -w file
                     True if file exists and is writable.
              -x file
                     True if file exists and is executable.
              -O file
                     True if file exists  and  is  owned  by  the
                     effective user id.
              -G file
                     True  if  file  exists  and  is owned by the
                     effective group id.
              file1 -nt file2
                     True if file1 is newer (according to modifi-
                     cation 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 descrip-
                     tion of the -o option  to  the  set  builtin
                     above.
              -z string
                     True if the length of string is zero.




GNU                        1997 May 19                         70





BASH(1)                                                   BASH(1)


              -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 lexico-
                     graphically.
              string1 > string2
                     True  if string1 sorts after string2 lexico-
                     graphically.
              ! expr True if expr is false.
              expr1 -a expr2
                     True if both expr1 AND expr2 are true.
              expr1 -o expr2
                     True if either expr1 OR expr2 is true.
              arg1 OP arg2
                     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.

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

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



GNU                        1997 May 19                         71





BASH(1)                                                   BASH(1)


              is invalid; otherwise trap returns true.

       type [-all] [-type | -path] name [name ...]
              With no options, indicate how each  name  would  be
              interpreted  if  used  as  a  command name.  If the
              -type flag 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 -path flag 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 would not  return
              file.   If  a  command  is hashed, -path prints the
              hashed value, not necessarily the file that appears
              first  in  PATH.   If  the  -all flag is used, type
              prints all of the places that contain an executable
              named  name.   This includes aliases and functions,
              if and only if the -path flag  is  not  also  used.
              The  table of hashed commands is not consulted when
              using -all.  type accepts -a, -t, and -p  in  place
              of  -all,  -type,  and  -path,  respectively.  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:
              -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)



GNU                        1997 May 19                         72





BASH(1)                                                   BASH(1)


              -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  illegal  option  is
              encountered,  a  non-numeric  argument  other  than
              unlimited is supplied as limit, or an error  occurs
              while setting a new limit.

       umask [-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, or if the -S option
              is supplied, the  current  value  of  the  mask  is
              printed.   The  -S  option  causes  the  mask to be
              printed in symbolic form; the default output is  an
              octal  number.   The return status is 0 if the mode
              was successfully changed or if no mode argument was
              supplied, and false otherwise.

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

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





GNU                        1997 May 19                         73





BASH(1)                                                   BASH(1)


       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:

       o      changing directories with cd

       o      setting or unsetting the values of SHELL or PATH

       o      specifying command names containing /

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

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

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

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

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

       o      specifying the -p option  to  the  command  builtin
              command

       o      turning off restricted mode with set +r.

       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.





GNU                        1997 May 19                         74





BASH(1)                                                   BASH(1)


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

FILES
       /bin/bash
              The bash executable
       /etc/profile
              The systemwide initialization  file,  executed  for
              login shells
       ~/.bash_profile
              The  personal  initialization  file,  executed  for
              login shells
       ~/.bashrc
              The individual per-interactive-shell startup file
       ~/.inputrc
              Individual readline initialization file

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

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

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

       Once  you  have determined that a bug actually exists, use
       the bashbug command to submit a bug report.  If you have a
       fix, you are encouraged to mail that as well!  Suggestions
       and `philosophical' bug reports  may  be  mailed  to  bug-
       bash@prep.ai.MIT.Edu  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.



GNU                        1997 May 19                         75





BASH(1)                                                   BASH(1)


       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                        1997 May 19                         76


