


BASH(1)                                                   BASH(1)


NNAAMMEE
       bash - GNU Bourne-Again SHell

SSYYNNOOPPSSIISS
       bbaasshh [options] [file]

CCOOPPYYRRIIGGHHTT
       Copyright  (C) 1989, 1991 by the Free Software Foundation,
       Inc.

DDEESSCCRRIIPPTTIIOONN
       BBaasshh is an sshh-compatible command language interpreter that
       executes  commands  read from the standard input or from a
       file.  BBaasshh also incorporates  useful  features  from  the
       _K_o_r_n and _C shells (kksshh and ccsshh).

       BBaasshh  is  ultimately intended to be a faithful implementa-
       tion of the IEEE Posix Shell and Tools specification (IEEE
       Working Group 1003.2).

OOPPTTIIOONNSS
       In  addition  to  the single-character shell options docu-
       mented in the description of the sseett builtin command, bbaasshh
       interprets the following flags when it is invoked:

       --cc _s_t_r_i_n_g If  the  --cc  flag  is present, then commands are
                 read from _s_t_r_i_n_g.
       --ii        If the --ii flag is present, the shell is _i_n_t_e_r_a_c_-
                 _t_i_v_e.
       --ss        If  the  --ss  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.
       --         A  single  -- signals the end of options and dis-
                 ables further option processing.  Any  arguments
                 after  the  -- are treated as filenames and argu-
                 ments.  An argument of ---- is  equivalent  to  an
                 argument of --.

       BBaasshh  also interprets a number of multi-character options.
       These options must appear on the command line  before  the
       single-character options to be recognized.

       --nnoorrcc     Do  not  load  the  personal initialization file
                 _~_/_._b_a_s_h_r_c if the shell is interactive.  This  is
                 the default if the shell name is sshh.
       --nnoopprrooffiillee
                 Do    not    read    either    _/_e_t_c_/_p_r_o_f_i_l_e   or
                 _~_/_._b_a_s_h___p_r_o_f_i_l_e_.   By  default,  bbaasshh   normally
                 reads  these files when it is invoked as a login
                 shell.
       --rrccffiillee _f_i_l_e
                 Execute  commands  from  _f_i_l_e  instead  of   the



GNU                      1991 November 24                       1





BASH(1)                                                   BASH(1)


                 standard personal initialization file _~_/_._b_a_s_h_r_c,
                 if the shell is interactive.
       --vveerrssiioonn  Show the version number of this instance of bbaasshh
                 when starting.
       --qquuiieett    Do  not be verbose when starting up (do not show
                 the shell version or any other information).
       --llooggiinn    Make bbaasshh act as  if  it  had  been  invoked  by
                 login(1).
       --nnoobbrraacceeeexxppaannssiioonn
                 Do not perform curly brace expansion a la ccsshh.
       --nnoolliinneeeeddiittiinngg
                 Do not use the GNU _r_e_a_d_l_i_n_e library to read com-
                 mand lines if interactive.

AARRGGUUMMEENNTTSS
       If arguments remain after option processing,  and  neither
       the  --cc  nor  the  --ss  option has been supplied, the first
       argument is assumed to be the name of  a  file  containing
       shell commands.  If bbaasshh is invoked in this fashion, $$00 is
       set to the name of the file, and the positional parameters
       are  set  to the remaining arguments.  BBaasshh reads and exe-
       cutes commands from this file, then exits.

DDEEFFIINNIITTIIOONNSS
       bbllaannkk  A space or tab.
       wwoorrdd   A sequence of characters  considered  as  a  single
              unit by the shell.  Also known as a ttookkeenn.
       nnaammee   A  _w_o_r_d  consisting only of alphanumeric characters
              and underscores, and beginning with  an  alphabetic
              character or an underscore.  Also referred to as an
              iiddeennttiiffiieerr.
       mmeettaacchhaarraacctteerr
              A character that, when unquoted,  separates  words.
              One of the following:
              ||  && ;; (( )) << >> <<ssppaaccee>> <<ttaabb>>
       ccoonnttrrooll ooppeerraattoorr
              A  _t_o_k_e_n  that  performs a control function.  It is
              one of the following symbols:
              |||| && &&&& ;; ;;;; (( )) || <<nneewwlliinnee>>

RREESSEERRVVEEDD WWOORRDDSS
       _R_e_s_e_r_v_e_d _w_o_r_d_s 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 SSHHEELLLL GGRRAAMMMMAARR below) or the third word of a ccaassee
       or ffoorr command:

       !! ccaassee  ddoo ddoonnee eelliiff eellssee eessaacc ffii ffoorr ffuunnccttiioonn iiff iinn  tthheenn
       uunnttiill wwhhiillee {{ }}

SSHHEELLLL GGRRAAMMMMAARR
   SSiimmppllee CCoommmmaannddss
       A  _s_i_m_p_l_e  _c_o_m_m_a_n_d  is  a  sequence  of  optional variable
       assignments  followed   by   _b_l_a_n_k-separated   words   and



GNU                      1991 November 24                       2





BASH(1)                                                   BASH(1)


       redirections,  and  terminated by a _c_o_n_t_r_o_l _o_p_e_r_a_t_o_r.  The
       first word specifies the  command  to  be  executed.   The
       remaining  words  are  passed  as arguments to the invoked
       command.

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

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

              [ ! ] _c_o_m_m_a_n_d [ || _c_o_m_m_a_n_d_2 ... ]

       The standard output of _c_o_m_m_a_n_d is connected to  the  stan-
       dard  input  of  _c_o_m_m_a_n_d_2.   This  connection is performed
       before any redirections  specified  by  the  command  (see
       RREEDDIIRREECCTTIIOONN 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.

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

   LLiissttss
       A _l_i_s_t is a sequence of one or more pipelines separated by
       one of the operators ;;, &&, &&&&, or ||||, and optionally  ter-
       minated by one of ;;, &&, or <<nneewwlliinnee>>.

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

       If  a command is terminated by the control operator &&, the
       shell executes the command in the  _b_a_c_k_g_r_o_u_n_d  in  a  sub-
       shell.  The shell does not wait for the command to finish.
       Commands separated by a ;; are executed  sequentially;  the
       shell waits for each command to terminate in turn.

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

              _c_o_m_m_a_n_d &&&& _c_o_m_m_a_n_d_2

       _c_o_m_m_a_n_d_2 is executed if, and only if, _c_o_m_m_a_n_d  returns  an
       exit status of zero.

       An OR list has the form




GNU                      1991 November 24                       3





BASH(1)                                                   BASH(1)


              _c_o_m_m_a_n_d |||| _c_o_m_m_a_n_d_2


       _c_o_m_m_a_n_d_2 is executed if and only if _c_o_m_m_a_n_d returns a non-
       zero exit status.

   CCoommppoouunndd CCoommmmaannddss
       A _c_o_m_p_o_u_n_d _c_o_m_m_a_n_d is one of the following:

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

       { _l_i_s_t; }
              _l_i_s_t  is simply executed in the current shell envi-
              ronment.  This is known as a _g_r_o_u_p _c_o_m_m_a_n_d.

       ffoorr _n_a_m_e [ iinn _w_o_r_d; ] ddoo _l_i_s_t ; ddoonnee
              The list of words following iinn is expanded,  gener-
              ating a list of items.  The variable _n_a_m_e is set to
              each element of this list in turn, and _l_i_s_t is exe-
              cuted  each  time.   If the iinn _w_o_r_d is omitted, the
              ffoorr command executes _l_i_s_t once for each  positional
              parameter  that is set (see PPAARRAAMMEETTEERRSS below).  The
              exit status is the exit status of the last command,
              or zero if no commands were executed.

       ccaassee _w_o_r_d iinn [ _p_a_t_t_e_r_n [ || _p_a_t_t_e_r_n ] ... ) _l_i_s_t ;; ] ...
              eessaacc
              A ccaassee command first expands  _w_o_r_d,  and  tries  to
              match  it  against  each  _p_a_t_t_e_r_n  in turn.  When a
              match is found, the corresponding _l_i_s_t is executed.
              After  the  first  match, no subsequent matches are
              attempted.  The exit status is zero if no  patterns
              are  matches.   Otherwise, it is the exit status of
              the last command executed in _l_i_s_t.

       iiff _l_i_s_t tthheenn _l_i_s_t [ eelliiff _l_i_s_t tthheenn _l_i_s_t ] ... [ eellssee _l_i_s_t
              ] ffii
              The  iiff  _l_i_s_t  is  executed.  If its exit status is
              zero, the tthheenn _l_i_s_t is executed.   Otherwise,  each
              eelliiff _l_i_s_t is executed in turn, and if its exit sta-
              tus is zero, the corresponding tthheenn  _l_i_s_t  is  exe-
              cuted  and  the  command completes.  Otherwise, the
              eellssee _l_i_s_t is executed, if present.  The exit status
              is the exit status of the last command executed, or
              zero if no condition tested true.

       wwhhiillee _l_i_s_t ddoo _l_i_s_t ddoonnee
       uunnttiill _l_i_s_t ddoo _l_i_s_t ddoonnee
              The wwhhiillee command continuously executes the ddoo _l_i_s_t
              as long as the last command in _l_i_s_t returns an exit
              status of zero.  The uunnttiill command is identical  to



GNU                      1991 November 24                       4





BASH(1)                                                   BASH(1)


              the wwhhiillee command, except that the test is negated;
              the ddoo _l_i_s_t is executed as long as the last command
              in  _l_i_s_t  returns a non-zero exit status.  The exit
              status of the wwhhiillee and uunnttiill commands is the  exit
              status  of  the  last  ddoo _l_i_s_t command executed, or
              zero if none was executed.

       [ ffuunnccttiioonn ] _n_a_m_e () { _l_i_s_t; }
              This defines a function named _n_a_m_e.   The  _b_o_d_y  of
              the  function is the _l_i_s_t of commands between { and
              }.  This list is executed whenever _n_a_m_e  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  FFUUNNCCTTIIOONNSS
              below.)

CCOOMMMMEENNTTSS
       In a non-interactive shell, a word beginning with ## causes
       that  word and all remaining characters on that line to be
       ignored.

QQUUOOTTIINNGG
       _Q_u_o_t_i_n_g 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 _m_e_t_a_c_h_a_r_a_c_t_e_r_s listed above under  DDEEFFIINNIITTIIOONNSS
       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  _e_s_c_a_p_e  _c_h_a_r_a_c_t_e_r.   It
       preserves  the  literal  value  of the next character that
       follows, with the exception of <newline>.  If a \\<newline>
       pair  appears,  it is treated as a line continuation (that
       is, it is effectively ignored), if the backslash  is  non-
       quoted.

       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 <<nneewwlliinnee>>.  A
       double quote may be quoted within double quotes by preced-
       ing it with a backslash.



GNU                      1991 November 24                       5





BASH(1)                                                   BASH(1)


       The  special  parameters ** and @@ have special meaning when
       in double quotes (see PPAARRAAMMEETTEERRSS below).

PPAARRAAMMEETTEERRSS
       A _p_a_r_a_m_e_t_e_r is an entity that stores values, somewhat like
       a variable in a conventional programming language.  It can
       be a _n_a_m_e, a number, or  one  of  the  special  characters
       listed  below  under  SSppeecciiaall PPaarraammeetteerrss.  For the shell's
       purposes, a _v_a_r_i_a_b_l_e is a parameter denoted by a _n_a_m_e.

       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 uunnsseett builtin command  (see
       SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below).

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

              _n_a_m_e=[_v_a_l_u_e]

       If  _v_a_l_u_e  is not given, the variable is assigned the null
       string.  All _v_a_l_u_e_s undergo tilde expansion, parameter and
       variable   expansion,   command  substitution,  arithmetic
       expansion, and quote removal.  If the variable has its  --ii
       attribute  set  (see  ddeeccllaarree  below in SSHHEELLLL BBUUIILLTTIINN CCOOMM--
       MMAANNDDSS) then _v_a_l_u_e is subject to arithmetic expansion  even
       if  the  $[...] syntax does not appear.  Word splitting is
       not performed, with the exception  of  ""$$@@""  as  explained
       below under SSppeecciiaall PPaarraammeetteerrss.  Pathname expansion is not
       performed.

   PPoossiittiioonnaall PPaarraammeetteerrss
       A _p_o_s_i_t_i_o_n_a_l _p_a_r_a_m_e_t_e_r 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 sseett builtin
       command.   The  positional  parameters   are   temporarily
       replaced  when a shell function is executed (see FFUUNNCCTTIIOONNSS
       below).

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

   SSppeecciiaall PPaarraammeetteerrss
       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 IIFFSS special variable.  That  is,  ``$$**''  is
              equivalent  to  ``$$11_c$$22_c......'', where _c is the first
              character of the value of the IIFFSS variable.  If IIFFSS



GNU                      1991 November 24                       6





BASH(1)                                                   BASH(1)


              is  null  or unset, the parameters are separated by
              spaces.
       @@      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 ``$$11'' ``$$22'' ...
              When there are no positional parameters, ``$$@@'' and
              $$@@ expand to nothing (i.e. they are removed).
       ##      Expands  to  the number of positional parameters in
              decimal.
       ??      Expands to the status of the most recently executed
              foreground pipeline.
       --      Expands  to  the  current option flags as specified
              upon invocation, by the  sseett  builtin  command,  or
              those  set  by  the  shell  itself  (such as the --ii
              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.
       00      Expands  to  the name of the shell or shell script.
              This is set at shell initialization.   If  bbaasshh  is
              invoked  with  a file of commands, $$00 is set to the
              name of that file.  Otherwise, it  is  set  to  the
              pathname  used to invoke bbaasshh, as given by argument
              zero.
       __      Expands to the last argument to the  previous  com-
              mand,  after expansion.  Also set to the full path-
              name of each command executed  and  placed  in  the
              environment exported to that command.

   SShheellll VVaarriiaabblleess
       The following variables are set by the shell:

       PPPPIIDD   The process ID of the shell's parent.
       PPWWDD    The current working directory as set by the ccdd com-
              mand.
       OOLLDDPPWWDD The previous working directory as  set  by  the  ccdd
              command.
       RREEPPLLYY  Set  to  the line of input read by the rreeaadd builtin
              command when no arguments are supplied.
       UUIIDD    Expands to the user ID of the current user.
       EEUUIIDD   Expands to the effective user  ID  of  the  current
              user.
       BBAASSHH   Expands  to  the  full pathname used to invoke this
              instance of bbaasshh.
       BBAASSHH__VVEERRSSIIOONN
              Expands to the version number of this  instance  of
              bbaasshh.
       SSHHLLVVLL  Incremented by one each time an instance of bbaasshh is
              started.
       RRAANNDDOOMM Each time this parameter is  referenced,  a  random
              integer  is  generated.   The  sequence  of  random



GNU                      1991 November 24                       7





BASH(1)                                                   BASH(1)


              numbers may be initialized by assigning a value  to
              RRAANNDDOOMM.   If  RRAANNDDOOMM is unset, it loses its special
              properties, even if it is subsequently reset.
       SSEECCOONNDDSS
              Each time this parameter is referenced, the  number
              of  seconds since shell invocation is returned.  If
              a value is assigned to SSEECCOONNDDSS, the value  returned
              upon subsequent references is the number of seconds
              since the assignment plus the value  assigned.   If
              SSEECCOONNDDSS  is unset, it loses its special properties,
              even if it is subsequently reset.
       LLIINNEENNOO 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.   When in a function, the
              value is not the number of the source line that the
              command  appears on (that information has been lost
              by the time the function is executed),  but  is  an
              approximation of the number of _s_i_m_p_l_e _c_o_m_m_a_n_d_s exe-
              cuted in the current function.  If LLIINNEENNOO is unset,
              it loses its special properties, even if it is sub-
              sequently reset.
       OOPPTTAARRGG The value of the last option argument processed  by
              the ggeettooppttss builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMM--
              MMAANNDDSS below).
       OOPPTTIINNDD The index of  the  last  option  processed  by  the
              ggeettooppttss builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS
              below).

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

       IIFFSS    The _I_n_t_e_r_n_a_l _F_i_e_l_d _S_e_p_a_r_a_t_o_r that is used for  word
              splitting  after  expansion and to split lines into
              words with the rreeaadd builtin command.   The  default
              value is ``<space><tab><newline>''.
       PPAATTHH   The  search  path  for  commands.   It  is a colon-
              separated list of directories in  which  the  shell
              looks  for  commands (see CCOOMMMMAANNDD EEXXEECCUUTTIIOONN below).
              The default path is system-dependent, and is set by
              the  administrator  who  installs  bbaasshh.   A common
              value                                            is
              ``.:/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin:/etc:/usr/etc''.
              Note that in some circumstances, however, a leading
              `.' in PPAATTHH can be a security hazard.
       HHOOMMEE   The home directory of the current user; the default
              argument for the ccdd builtin command.
       CCDDPPAATTHH The search path for the  ccdd  command.   This  is  a
              colon-separated  list  of  directories in which the
              shell looks for destination  directories  specified
              by the ccdd command.  A sample value is ``.:~:/usr''.



GNU                      1991 November 24                       8





BASH(1)                                                   BASH(1)


       EENNVV    If this parameter is set when bbaasshh is  executing  a
              shell  script,  its value is interpreted as a file-
              name containing commands to initialize  the  shell,
              as  in  _._b_a_s_h_r_c.   The value of EENNVV is subjected to
              parameter  expansion,  command  substitution,   and
              arithmetic  expansion before being interpreted as a
              pathname.  PPAATTHH is  not  used  to  search  for  the
              resultant pathname.
       MMAAIILL   If  this  parameter  is  set  to a filename and the
              MMAAIILLPPAATTHH variable is not set, bbaasshh informs the user
              of the arrival of mail in the specified file.
       MMAAIILLCCHHEECCKK
              Specifies  how  often  (in seconds) bbaasshh checks for
              mail.  The default is 60 seconds.  When it is  time
              to check for mail, the shell does so before prompt-
              ing.  If this variable is unset, the shell disables
              mail checking.
       MMAAIILLPPAATTHH
              A  colon-separated  list of pathnames to be checked
              for mail.  The message to be printed may be  speci-
              fied  by  separating  the pathname from the message
              with a `?'.  $_ stands for the name of the  current
              mailfile.  Example:
              MMAAIILLPPAATTHH='/usr/spool/mail/bfox?"You            have
              mail":~/shell-mail?"$_ has mail!"'
              BBaasshh 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/$$UUSSEERR).
       MMAAIILL__WWAARRNNIINNGG
              If  set,  and a file that bbaasshh is checking for mail
              has been  accessed  since  the  last  time  it  was
              checked,  the  message  ``The mail in` _m_a_i_l_f_i_l_e has
              been read'' is printed.
       PPSS11    The  value  of  this  parameter  is  expanded  (see
              PPRROOMMPPTTIINNGG  below)  and  used  as the primary prompt
              string.  The default value is ````bbaasshh\\$$ ''''.
       PPSS22    The value of this parameter is  expanded  like  PPSS11
              and  used  as  the  secondary  prompt  string.  The
              default is ````>> ''''.
       PPSS44    The value of this parameter is  expanded  like  PPSS11
              and  the  value is printed before each command bbaasshh
              displays during  an  execution  trace.   The  first
              character  of  PPSS44 is replicated multiple times, as
              necessary, to indicate multiple levels of  indirec-
              tion.  The default is ``+ ''.
       NNOO__PPRROOMMPPTT__VVAARRSS
              If  set, the decoded prompt string does not undergo
              further expansion (see PPRROOMMPPTTIINNGG below).
       HHIISSTTSSIIZZEE
              The number of commands to remember in  the  command
              history (see HHIISSTTOORRYY below).
       HHIISSTTFFIILLEE
              The  name  of  the file in which command history is



GNU                      1991 November 24                       9





BASH(1)                                                   BASH(1)


              saved.  (See HHIISSTTOORRYY below.)
       HHIISSTTFFIILLEESSIIZZEE
              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.
       OOPPTTEERRRR If set to the value 1, bbaasshh displays error messages
              generated by the ggeettooppttss builtin command (see SSHHEELLLL
              BBUUIILLTTIINN  CCOOMMMMAANNDDSS below).  OOPPTTEERRRR is initialized to
              1 each time the shell is invoked or a shell  script
              is executed.
       PPRROOMMPPTT__CCOOMMMMAANNDD
              If set, the value is executed as a command prior to
              issuing each primary prompt.
       IIGGNNOORREEEEOOFF
       iiggnnoorreeeeooff
              Controls the action of the shell on receipt  of  an
              EEOOFF character as the sole input.  If set, the value
              is the number of consecutive EEOOFF  characters  typed
              before bbaasshh 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, EEOOFF
              signifies the end of input to the shell.   This  is
              only in effect for interactive shells.
       HHOOSSTTTTYYPPEE
              Automatically   set   to  a  string  that  uniquely
              describes the type of machine on which bbaasshh is exe-
              cuting.  The default is system-dependent.
       TTMMOOUUTT  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.  BBaasshh ter-
              minates after waiting for that number of seconds if
              input does not arrive.
       FFCCEEDDIITT The default editor for the ffcc builtin command.
       FFIIGGNNOORREE
              A  colon-separated  list of suffixes to ignore when
              performing  filename   completion   (see   RREEAADDLLIINNEE
              below).  A filename whose suffix matches one of the
              entries in FFIIGGNNOORREE is excluded  from  the  list  of
              matched filenames.  A sample value is ``.o:~''.
       nnoottiiffyy If  set,  bbaasshh  reports  terminated background jobs
              immediately,  rather  than  waiting  until   before
              printing the next primary prompt.
       hhiissttoorryy__ccoonnttrrooll
              If  set  to  a value of _i_g_n_o_r_e_s_p_a_c_e, it means don't
              enter lines which begin with a <<ssppaaccee>> on the  his-
              tory  list.   If  set  to a value of _i_g_n_o_r_e_d_u_p_s, it
              means  don't  enter  lines  which  match  the  last
              entered  line.   If  unset,  or if set to any other
              value than those  above,  all  lines  read  by  the
              parser are saved on the history list.
       ccoommmmaanndd__oorriieenntteedd__hhiissttoorryy
              If set, bbaasshh attempts to save all lines of a multi-
              ple-line command in the same history  entry.   This



GNU                      1991 November 24                      10





BASH(1)                                                   BASH(1)


              allows easy re-editing of multi-line commands.
       gglloobb__ddoott__ffiilleennaammeess
              If  set,  bbaasshh  includes filenames beginning with a
              `.' in the results of pathname expansion.
       aallllooww__nnuullll__gglloobb__eexxppaannssiioonn
              If set, bbaasshh allows pathname patterns  which  match
              no  files  (see PPaatthhnnaammee EExxppaannssiioonn below) to expand
              to a null string, rather than themselves.
       hhiissttcchhaarrss
              The two characters which control history  expansion
              and  tokenization.  The first character is the _h_i_s_-
              _t_o_r_y _e_x_p_a_n_s_i_o_n _c_h_a_r_a_c_t_e_r, that  is,  the  character
              which  signals  the  start  of a history expansion,
              normally `!!'.  The second character is the  charac-
              ter  which signifies that the remainder of the line
              is a comment, when found as the first character  of
              a word.
       nnoolliinnkkss
              If  set,  the  shell does not follow symbolic links
              when executing commands  that  change  the  current
              working  directory.  It uses the physical directory
              structure instead.  By default,  bbaasshh  follows  the
              logical  chain  of directories when performing com-
              mands such as ccdd.
       hhoossttnnaammee__ccoommpplleettiioonn__ffiillee
              Contains the name of a file in the same  format  as
              _/_e_t_c_/_h_o_s_t_s that should be read when the shell needs
              to complete a hostname.  You can  change  the  file
              interactively; the next time you want to complete a
              hostname bbaasshh adds the contents of the new file  to
              the already existing database.
       nnoocclloobbbbeerr
              If  set,  bbaasshh  does not overwrite an existing file
              with the >>, >>&&, and <<>> redirection operators.  This
              variable  may  be  overridden  when creating output
              files by using the redirection operator >>||  instead
              of  >>  (see  also  the --CC option to the sseett builtin
              command).
       aauuttoo__rreessuummee
              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.
       nnoo__eexxiitt__oonn__ffaaiilleedd__eexxeecc
              If this variable exists, the shell does not exit if
              it cannot execute the file specified  in  the  eexxeecc
              command.
       ccddaabbllee__vvaarrss
              If  this is set, an argument to the ccdd builtin com-
              mand that is not a directory is assumed to  be  the



GNU                      1991 November 24                      11





BASH(1)                                                   BASH(1)


              name  of a variable whose value is the directory to
              change to.
       ppuusshhdd__ssiilleenntt
              If set, the ppuusshhdd and ppooppdd builtin commands do  not
              print  the current directory stack after successful
              execution.

EEXXPPAANNSSIIOONN
       Expansion is performed on the command line  after  it  has
       been split into words.  There are seven kinds of expansion
       performed: _b_r_a_c_e _e_x_p_a_n_s_i_o_n, _t_i_l_d_e _e_x_p_a_n_s_i_o_n, _p_a_r_a_m_e_t_e_r _a_n_d
       _v_a_r_i_a_b_l_e   _e_x_p_a_n_s_i_o_n,   _c_o_m_m_a_n_d  _s_u_b_s_t_i_t_u_t_i_o_n,  _a_r_i_t_h_m_e_t_i_c
       _e_x_p_a_n_s_i_o_n, _w_o_r_d _s_p_l_i_t_t_i_n_g, and _p_a_t_h_n_a_m_e _e_x_p_a_n_s_i_o_n.

       The order of expansions is: brace expansion, tilde  expan-
       sion, parameter, variable, command, and arithmetic substi-
       tution (done in a left-to-right fashion), word  splitting,
       and pathname expansion.

       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 single exception to this is the expansion of ``$$@@'' as
       explained above (see PPAARRAAMMEETTEERRSS).

   BBrraaccee EExxppaannssiioonn
       _B_r_a_c_e  _e_x_p_a_n_s_i_o_n is a mechanism by which arbitrary strings
       may be generated.  This mechanism is similar  to  _p_a_t_h_n_a_m_e
       _e_x_p_a_n_s_i_o_n,  but  the  filenames  generated need not exist.
       Patterns to be brace expanded take the form of an optional
       _p_r_e_a_m_b_l_e,  followed by a series of comma-separated strings
       between a pair of braces, followed by an optional  _p_o_s_t_a_m_-
       _b_l_e.   The  preamble is prepended 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.  BBaasshh  does
       not  apply  any syntactic interpretation to the context of
       the expansion or the text between the braces.

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



GNU                      1991 November 24                      12





BASH(1)                                                   BASH(1)


       Brace  expansion  introduces a slight incompatibility with
       traditional versions of sshh, the Bourne shell.  sshh does not
       treat opening or closing braces specially when they appear
       as part of a word, and preserves them in the output.  BBaasshh
       removes braces from words as a consequence of brace expan-
       sion.  For example, a word  entered  to  sshh  as  _f_i_l_e_{_1_,_2_}
       appears  identically in the output.  The same word is out-
       put as _f_i_l_e_1 _f_i_l_e_2 after expansion  by  bbaasshh.   If  strict
       compatibility  with  sshh  is  desired,  start bbaasshh with the
       --nnoobbrraacceeeexxppaannssiioonn flag  (see  OOPPTTIIOONNSS  above)  or  disable
       brace  expansion with the ++oo bbrraacceeeexxppaanndd option to the sseett
       command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below).

   TTiillddee EExxppaannssiioonn
       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  _l_o_g_i_n
       _n_a_m_e.  If this _l_o_g_i_n _n_a_m_e is the null string, the tilde is
       replaced with the value of the parameter HHOOMMEE.  If HHOOMMEE is
       unset,  the home directory of the user executing the shell
       is substituted instead.

       If a `+' follows the tilde, the value of  PPWWDD  is  substi-
       tuted.  If a `-' follows, the value of OOLLDDPPWWDD is used.

       Each variable assignment is checked for unquoted instances
       of tildes following a :: or ==.  In these cases, tilde  sub-
       stitution  is  also  performed.  Consequently, one may use
       pathnames with tildes in PPAATTHH, MMAAIILLPPAATTHH, and  CCDDPPAATTHH,  and
       the shell will export the expanded variables.

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

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

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

       ${_p_a_r_a_m_e_t_e_r::--_w_o_r_d}
              UUssee DDeeffaauulltt VVaalluueess.  If _p_a_r_a_m_e_t_e_r is unset or null,



GNU                      1991 November 24                      13





BASH(1)                                                   BASH(1)


              the  expansion  of _w_o_r_d is substituted.  Otherwise,
              the value of _p_a_r_a_m_e_t_e_r is substituted.
       ${_p_a_r_a_m_e_t_e_r::==_w_o_r_d}
              AAssssiiggnn DDeeffaauulltt VVaalluueess.  If _p_a_r_a_m_e_t_e_r  is  unset  or
              null,  the expansion of _w_o_r_d is assigned to _p_a_r_a_m_e_-
              _t_e_r.  The value of _p_a_r_a_m_e_t_e_r is  then  substituted.
              Positional  parameters  and  special parameters may
              not be assigned to in this way.
       ${_p_a_r_a_m_e_t_e_r::??_w_o_r_d}
              DDiissppllaayy EErrrroorr iiff NNuullll oorr UUnnsseett.   If  _p_a_r_a_m_e_t_e_r  is
              null  or unset, the expansion of _w_o_r_d (or a message
              to that effect if _w_o_r_d is not present)  is  written
              to  the  standard error and the shell, if it is not
              interactive, exits.  Otherwise, the value of _p_a_r_a_m_-
              _e_t_e_r is substituted.
       ${_p_a_r_a_m_e_t_e_r::++_w_o_r_d}
              UUssee  AAlltteerrnnaattee  VVaalluuee.   If  _p_a_r_a_m_e_t_e_r  is  null or
              unset, nothing is substituted, otherwise the expan-
              sion of _w_o_r_d is substituted.
       ${##_p_a_r_a_m_e_t_e_r}
              The  length in characters of the value of _p_a_r_a_m_e_t_e_r
              is substituted.  If _p_a_r_a_m_e_t_e_r is ** or @@, the length
              substituted is the length of ** expanded within dou-
              ble quotes.
       ${_p_a_r_a_m_e_t_e_r##_w_o_r_d}
       ${_p_a_r_a_m_e_t_e_r####_w_o_r_d}
              The _w_o_r_d is expanded to produce a pattern  just  as
              in  pathname expansion.  If the pattern matches the
              beginning of  the  value  of  _p_a_r_a_m_e_t_e_r,  then  the
              expansion is the value of _p_a_r_a_m_e_t_e_r with the short-
              est matching pattern deleted (the  ``##''  case)  or
              the  longest  matching  pattern deleted (the ``####''
              case).

       ${_p_a_r_a_m_e_t_e_r%%_w_o_r_d}
       ${_p_a_r_a_m_e_t_e_r%%%%_w_o_r_d}
              The _w_o_r_d is expanded to produce a pattern  just  as
              in  pathname  expansion.   If the pattern matches a
              trailing portion of the value  of  _p_a_r_a_m_e_t_e_r,  then
              the  expansion  is  the value of _p_a_r_a_m_e_t_e_r with the
              shortest matching pattern deleted (the ``%%''  case)
              or the longest matching pattern deleted (the ``%%%%''
              case).

   CCoommmmaanndd SSuubbssttiittuuttiioonn
       _C_o_m_m_a_n_d _s_u_b_s_t_i_t_u_t_i_o_n allows the output  of  a  command  to
       replace the command name.  There are two forms:


              $$((_c_o_m_m_a_n_d))
       or
              ``_c_o_m_m_a_n_d``

       BBaasshh  performs  the  expansion  by  executing  _c_o_m_m_a_n_d and



GNU                      1991 November 24                      14





BASH(1)                                                   BASH(1)


       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 $(_c_o_m_m_a_n_d) 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.

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

              $$[[_e_x_p_r_e_s_s_i_o_n]]

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

       The  evaluation is performed according to the rules listed
       below  under  AARRIITTHHMMEETTIICC  EEVVAALLUUAATTIIOONN.   If  _e_x_p_r_e_s_s_i_o_n  is
       invalid,  bbaasshh  prints a message indicating failure and no
       substitution occurs.

   WWoorrdd SSpplliittttiinngg
       The shell scans the results of parameter  expansion,  com-
       mand  substitution,  and arithmetic expansion that did not
       occur within double quotes for _w_o_r_d _s_p_l_i_t_t_i_n_g.

       The shell treats each character of IIFFSS as a delimiter, and
       splits  the  results of the other expansions into words on
       these  characters.   If  the  value  of  IIFFSS  is   exactly
       <<ssppaaccee>><<ttaabb>><<nneewwlliinnee>>,  the  default, then any sequence of
       IIFFSS characters serves to  delimit  words;  otherwise  each
       occurrence  of an IIFFSS character is treated as a delimiter.
       If the value of IIFFSS is null,  no  word  splitting  occurs.
       IIFFSS cannot be unset.

       Explicit null arguments ("""" or '''') are retained.  Implicit
       null arguments, resulting from the expansion of _p_a_r_a_m_e_t_e_r_s
       that have no values, are removed.

       Note   that  if  no  expansion  occurs,  no  splitting  is



GNU                      1991 November 24                      15





BASH(1)                                                   BASH(1)


       performed.

   PPaatthhnnaammee EExxppaannssiioonn
       After word splitting, bbaasshh scans each _w_o_r_d for the charac-
       ters **, ??, and [[, unless the --ff flag has been set.  If one
       of these characters appears, then the word is regarded  as
       a _p_a_t_t_e_r_n, and replaced with an alphabetically sorted list
       of pathnames matching the pattern.  If no  matching  path-
       names     are    found,    and    the    shell    variable
       aallllooww__nnuullll__gglloobb__eexxppaannssiioonn  is  unset,  the  word  is  left
       unchanged.  If the variable is set, the word is removed if
       no matches are found.  When a pattern is used for pathname
       generation, the character ````..''''  at the start of a name or
       immediately following a slash must be matched  explicitly,
       unless  the shell variable gglloobb__ddoott__ffiilleennaammeess is set.  The
       slash character must always  be  matched  explicitly.   In
       other  cases,  the  ````..''''   character  is not treated spe-
       cially.

       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
              _r_a_n_g_e;  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 -- or ]] may be
              matched  by including it as the first or last char-
              acter in the set.

   QQuuoottee RReemmoovvaall
       After the preceding expansions, all  unquoted  occurrences
       of the characters \\, ``, and "" are removed.

RREEDDIIRREECCTTIIOONN
       Before  a command is executed, its input and output may be
       _r_e_d_i_r_e_c_t_e_d using a special  notation  interpreted  by  the
       shell.   Redirection  may  also  be used to open and close
       files for the current shell  execution  environment.   The
       following  redirection  operators may appear anywhere in a
       _s_i_m_p_l_e _c_o_m_m_a_n_d or may precede or follow a _c_o_m_m_a_n_d.   Redi-
       rections 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).




GNU                      1991 November 24                      16





BASH(1)                                                   BASH(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, bbaasshh reports
       an error.

   RReeddiirreeccttiinngg IInnppuutt
       Redirection of input causes the file  whose  name  results
       from  the  expansion  of  _w_o_r_d 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]<<_w_o_r_d

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

       The general format for redirecting output is:

              [_n]>>_w_o_r_d

       If the redirection  operator  is  >>||,  then  the  variable
       nnoocclloobbbbeerr  is  not  consulted,  and  the  file  is created
       regardless of the value of nnoocclloobbbbeerr (see SShheellll  VVaarriiaabblleess
       above).

   AAppppeennddiinngg RReeddiirreecctteedd OOuuttppuutt
       Redirection  of  output  in  this  fashion causes the file
       whose name results from the expansion of _w_o_r_d 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]>>>>_w_o_r_d


   RReeddiirreeccttiinngg SSttaannddaarrdd OOuuttppuutt aanndd SSttaannddaarrdd EErrrroorr
       BBaasshh  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 _w_o_r_d
       with this construct.

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




GNU                      1991 November 24                      17





BASH(1)                                                   BASH(1)


              &&>>_w_o_r_d
       and
              >>&&_w_o_r_d

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

              >>_w_o_r_d 2>>&&1

   HHeerree DDooccuummeennttss
       This type of redirection instructs the shell to read input
       from  the current source until a line containing only _w_o_r_d
       (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:

              <<<<[--]_w_o_r_d
                      _h_e_r_e_-_d_o_c_u_m_e_n_t
              _d_e_l_i_m_i_t_e_r

       No parameter  expansion,  command  substitution,  pathname
       expansion,  or  arithmetic expansion is performed on _w_o_r_d.
       If any characters in _w_o_r_d are quoted, the _d_e_l_i_m_i_t_e_r is the
       result  of  quote  removal  on  _w_o_r_d, 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 \\<<nneewwlliinnee>> 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  _d_e_l_i_m_i_t_e_r.   This  allows  here-documents  within
       shell scripts to be indented in a natural fashion.

   DDuupplliiccaattiinngg FFiillee DDeessccrriippttoorrss
       The redirection operator

              [_n]<<&&_w_o_r_d

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

       The operator

              [_n]>>&&_w_o_r_d

       is used similarly to duplicate  output  file  descriptors.



GNU                      1991 November 24                      18





BASH(1)                                                   BASH(1)


       If  _n is not specified, the standard output (file descrip-
       tor 1) is used.

   OOppeenniinngg FFiillee DDeessccrriippttoorrss ffoorr RReeaaddiinngg aanndd WWrriittiinngg
       The redirection operator

              [_n]<<>>_w_o_r_d

       causes the file whose name is the expansion of _w_o_r_d to  be
       opened  for both reading and writing on file descriptor _n,
       or as the standard input and standard output if _n  is  not
       specified.

       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 _d_i_r_l_i_s_t, while the command

              ls 2>>&&1 >> dirlist

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

FFUUNNCCTTIIOONNSS
       A  shell  function, defined as described above under SSHHEELLLL
       GGRRAAMMMMAARR, stores a series of commands for later  execution.
       However, functions are executed in the context of the cur-
       rent shell; no new process is created  to  interpret  them
       (contrast  this  with  the  execution  of a shell script).
       When a function is executed, the arguments to the function
       become  the  positional  parameters  during its execution.
       The special parameter ## is updated to reflect the  change.
       Positional parameter 0 is unchanged.

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

       If  the  builtin command rreettuurrnn 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 may be listed with the  --ff  option  to  the
       ddeeccllaarree  or  ttyyppeesseett  builtin  commands.  Functions may be
       exported so that subshells automatically have them defined
       with the --ff option to the eexxppoorrtt builtin.




GNU                      1991 November 24                      19





BASH(1)                                                   BASH(1)


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

AALLIIAASSEESS
       The shell maintains a list of _a_l_i_a_s_e_s that may be set  and
       unset  with  the  aalliiaass and uunnaalliiaass builtin commands.  The
       first word of each command is checked to see if it has  an
       alias.   If  so,  that word is replaced by the text of the
       alias.  The aalliiaass name and the replacement text  may  con-
       tain  any  valid shell input, including the _m_e_t_a_c_h_a_r_a_c_t_e_r_s
       listed above.  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 llss to llss --FF, for instance, and
       bbaasshh does not try to recursively  expand  the  replacement
       text.   If  the  last  character  of  the alias value is a
       _b_l_a_n_k, then the next command word following the  alias  is
       also checked for alias expansion.

       Aliases are created and listed with the aalliiaass command, and
       removed with the uunnaalliiaass command.

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

       The rules concerning the definition and use of aliases are
       somewhat  confusing.   BBaasshh 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.
       This  means  that the commands following the alias defini-
       tion 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 function is executed, because a function def-
       inition 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 aalliiaass
       in compound commands.

       Aliases are not expanded when the shell  is  not  interac-
       tive.

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

JJOOBB CCOONNTTRROOLL
       _J_o_b _c_o_n_t_r_o_l refers to  the  ability  to  selectively  stop
       (_s_u_s_p_e_n_d) the execution of processes and continue (_r_e_s_u_m_e)
       their execution  at  a  later  point.   A  user  typically



GNU                      1991 November 24                      20





BASH(1)                                                   BASH(1)


       employs  this  facility  via an interactive interface sup-
       plied jointly by the system's terminal driver and bbaasshh.

       The shell associates a _j_o_b with each pipeline.  It keeps a
       table  of  currently  executing  jobs, which may be listed
       with the jjoobbss command.   When  bbaasshh  starts  a  job  asyn-
       chronously  (in  the  _b_a_c_k_g_r_o_u_n_d),  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 single process in the job is 25647.  BBaasshh
       uses the _j_o_b 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 _c_u_r_r_e_n_t
       _t_e_r_m_i_n_a_l _p_r_o_c_e_s_s _g_r_o_u_p _I_D.  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  SSIIGGIINNTT.  These processes are said to be in
       the _f_o_r_e_g_r_o_u_n_d.  _B_a_c_k_g_r_o_u_n_d 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 SSIIGGTTTTIINN ((SSIIGGTTTTOOUU)) sig-
       nal by the terminal driver, which, unless  caught,  causes
       the process to stop.

       If  the operating system on which bbaasshh is running supports
       job control, bbaasshh allows you to use it.  Typing  the  _s_u_s_-
       _p_e_n_d  character  (typically ^^ZZ, Control-Z) while a process
       is running causes that process to be stopped  and  returns
       you  to bbaasshh.  Typing the _d_e_l_a_y_e_d _s_u_s_p_e_n_d character (typi-
       cally ^^YY, Control-Y) causes the process to be stopped when
       it  attempts  to read input from the terminal, and control
       to be returned to bbaasshh.  You may then manipulate the state
       of  this  job,  using the bbgg command to continue it in the
       background, the ffgg command to continue  it  in  the  fore-
       ground, or the kkiillll command to kill it.  A ^^ZZ 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 %%nn.  A job may also be referred to using
       a prefix of the name used to start it,  or  using  a  sub-
       string that appears in its command line.  For example, %%ccee
       refers to a stopped ccee job.  If a prefix matches more than
       one  job, bbaasshh reports an error.  Using %%??ccee, on the other
       hand, would refer to any job containing the string  ccee  in
       its  command line.  If the substring matches more than one
       job, bbaasshh reports an error.  The symbols %%%% and  %%++  refer



GNU                      1991 November 24                      21





BASH(1)                                                   BASH(1)


       to  the  shell's  notion  of the _c_u_r_r_e_n_t _j_o_b, which is the
       last job stopped while it was in the foreground.  The _p_r_e_-
       _v_i_o_u_s  _j_o_b may be referenced using %%--.  In output pertain-
       ing to jobs (e.g. the output of  the  jjoobbss  command),  the
       current  job  is always flagged with a ++, and the previous
       job with a --.

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

       The shell learns immediately whenever a job changes state.
       Normally,  bbaasshh  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 variable nnoottiiffyy is
       set, bbaasshh reports such changes immediately.  (See also the
       --oo nnoottiiffyy option to the sseett builtin command.)

       If  you  attempt  to exit bbaasshh while jobs are stopped, the
       shell prints a message warning you.  You may then use  the
       jjoobbss  command to inspect their status.  If you do this, or
       try to exit again immediately, you are not  warned  again,
       and the stopped jobs are terminated.

SSIIGGNNAALLSS
       When bbaasshh is interactive, it ignores SSIIGGTTEERRMM (so that kkiillll
       00 does not kill  an  interactive  shell),  and  SSIIGGIINNTT  is
       caught  and  handled  (so that wwaaiitt is interruptible).  In
       all cases, bbaasshh ignores SSIIGGQQUUIITT.  If  job  control  is  in
       effect, bbaasshh ignores SSIIGGTTTTIINN, SSIIGGTTTTOOUU, and SSIIGGTTSSTTPP.

       Synchronous  jobs  started by bbaasshh have signals set to the
       values inherited by the shell from its parent.  Background
       jobs  (jobs  started  with  &&)  ignore SSIIGGIINNTT and SSIIGGQQUUIITT.
       Commands run as a result of  command  substitution  ignore
       the  keyboard-generated job control signals SSIIGGTTTTIINN, SSIIGGTT--
       TTOOUU, and SSIIGGTTSSTTPP.

CCOOMMMMAANNDD EEXXEECCUUTTIIOONN
       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  FFUUNNCCTTIIOONNSS.  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, bbaasshh searches  each  element  of  the
       PPAATTHH for a directory containing an executable file by that



GNU                      1991 November 24                      22





BASH(1)                                                   BASH(1)


       name.  If the search is unsuccessful, the shell prints  an
       error message and returns a nonzero 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 exe-
       cutable format, and the file is not  a  directory,  it  is
       assumed to be a _s_h_e_l_l _s_c_r_i_p_t, 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 hhaasshh below under SSHHEELLLL BBUUIILLTTIINN  CCOOMMMMAANNDDSS)  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.

EENNVVIIRROONNMMEENNTT
       When  a program is invoked it is given an array of strings
       called the _e_n_v_i_r_o_n_m_e_n_t.  This  is  a  list  of  _n_a_m_e-_v_a_l_u_e
       pairs, of the form _n_a_m_e=_v_a_l_u_e.

       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 _e_x_p_o_r_t to child processes.   Exe-
       cuted  commands  inherit  the environment.  The eexxppoorrtt and
       ddeeccllaarree --xx 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 uunnsseett
       command,  plus any additions via the eexxppoorrtt and ddeeccllaarree --xx
       commands.

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



GNU                      1991 November 24                      23





BASH(1)                                                   BASH(1)


       If the --kk flag is set (see the sseett builtin command below),
       then  _a_l_l parameter assignments are placed in the environ-
       ment for a command, not just those that precede  the  com-
       mand name.

EEXXIITT SSTTAATTUUSS
       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,  bbaasshh
       uses the value of 128+ssiiggnnaall as the exit status.

       BBaasshh  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 eexxiitt builtin
       command below.

PPRROOMMPPTTIINNGG
       When executing interactively, bbaasshh  displays  the  primary
       prompt  PPSS11  when  it  is ready to read a command, and the
       secondary prompt PPSS22 when it needs more input to  complete
       a  command.   BBaasshh  allows  the prompt to be customized by
       inserting a number of backslash-escaped special characters
       that are decoded as follows:
              \\tt     the time
              \\dd     the date
              \\nn     CRLF
              \\ss     the  name  of  the shell, the basename of $$00
                     (the portion following the final slash)
              \\ww     the current working directory
              \\WW     the basename of the current  working  direc-
                     tory
              \\uu     the username of the current user
              \\hh     the hostname
              \\##     the command number of this command
              \\!!     the history number of this command
              \\$$     if  the effective UID is 0, a ##, otherwise a
                     $$
              \\nnnnnn   character code in octal
              \\\\     a backslash

       After   the   string   is   decoded,   if   the   variable
       NNOO__PPRROOMMPPTT__VVAARRSS  is  not  set, it is expanded via parameter
       expansion, command substitution, arithmetic expansion, and
       word splitting.

RREEAADDLLIINNEE
       This  is the library that handles reading input when using
       an interactive shell, unless the --nnoolliinneeeeddiittiinngg option  is
       given.   By default, the line editing commands are similar
       to those of emacs.  A vi-style line editing  interface  is
       also available.

       In  this  section,  the  emacs-style  notation  is used to



GNU                      1991 November 24                      24





BASH(1)                                                   BASH(1)


       denote keystrokes.  Control keys  are  denoted  by  C-_k_e_y,
       e.g.  C-n  means  Control-N.   Similarly,  _m_e_t_a  keys  are
       denoted by M-_k_e_y, so  M-x  means  Meta-X.   (On  keyboards
       without a _m_e_t_a key, M-_x means ESC _x, i.e. press the Escape
       key  then  the  _x  key.   The  combination   M-C-_x   means
       ESC-Control-_x,  or press the Escape key then hold the Con-
       trol key while pressing the _x key.)

       The default key-bindings may be changed with an _~_/_._i_n_p_u_t_r_c
       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 _~_/_._i_n_p_u_t_r_c would make M-C-u execute  the  command
       _u_n_i_v_e_r_s_a_l_-_a_r_g_u_m_e_n_t.

       The  following  symbolic  character  names are recognized:
       RUBOUT, DEL, ESC, NEWLINE, SPACE, RETURN, LFD, TAB.

       Placing

              set editing-mode vi

       into a _~_/_._i_n_p_u_t_r_c file causes bbaasshh to start with a _v_i-like
       editing  mode.   The  editing  mode may be switched during
       interactive use by using the --oo option to the sseett  builtin
       command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below).

       You  can  have  readline  use  a  single line for display,
       scrolling the input between the two borders by placing

              set horizontal-scroll-mode On

       into a _~_/_._i_n_p_u_t_r_c file.

       The following is a list of the names of the  commands  and
       the default key-strokes to get them.

   CCoommmmaannddss ffoorr MMoovviinngg
       bbeeggiinnnniinngg--ooff--lliinnee ((CC--aa))
              Move to the start of the current line.
       eenndd--ooff--lliinnee ((CC--ee))
              Move to the end of the line.
       ffoorrwwaarrdd--cchhaarr ((CC--ff))
              Move forward a character.
       bbaacckkwwaarrdd--cchhaarr ((CC--bb))
              Move back a character.
       ffoorrwwaarrdd--wwoorrdd ((MM--ff))
              Move forward to the end of the next word.




GNU                      1991 November 24                      25





BASH(1)                                                   BASH(1)


       bbaacckkwwaarrdd--wwoorrdd ((MM--bb))
              Move  back  to  the start of this, or the previous,
              word.
       cclleeaarr--ssccrreeeenn ((CC--ll))
              Clear the screen leaving the current  line  at  the
              top of the screen.

   CCoommmmaannddss ffoorr MMaanniippuullaattiinngg tthhee HHiissttoorryy
       aacccceepptt--lliinnee ((NNeewwlliinnee,, RReettuurrnn))
              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 hhiissttoorryy__ccoonnttrrooll
              variable.  If this line was a  history  line,  then
              restore the history line to its original state.
       pprreevviioouuss--hhiissttoorryy ((CC--pp))
              Fetch  the  previous command from the history list,
              moving back in the list.
       nneexxtt--hhiissttoorryy ((CC--nn))
              Fetch the next command from the history list,  mov-
              ing forward in the list.
       bbeeggiinnnniinngg--ooff--hhiissttoorryy ((MM--<<))
              Move  to  the  first line in the history, the first
              line entered.
       eenndd--ooff--hhiissttoorryy ((MM-->>))
              Move to the end of the  input  history,  i.e.,  the
              line you are entering.
       rreevveerrssee--sseeaarrcchh--hhiissttoorryy ((CC--rr))
              Search  backward  starting  at the current line and
              moving `up' through the history as necessary.  This
              is an incremental search.
       ffoorrwwaarrdd--sseeaarrcchh--hhiissttoorryy ((CC--ss))
              Search  forward  starting  at  the current line and
              moving `down' through the history as necessary.
       sshheellll--eexxppaanndd--lliinnee ((MM--CC--ee))
              Expand the line the way  the  shell  does  when  it
              reads  it.   This performs alias and history expan-
              sion.  See HHIISSTTOORRYY below.
       iinnsseerrtt--llaasstt--aarrgguummeenntt ((MM--..,, MM--__))
              Insert the last argument to  the  previous  command
              (the last word on the previous line).
       ooppeerraattee--aanndd--ggeett--nneexxtt ((CC--OO))
              Accept the current line for execution and fetch the
              next line relative to the  current  line  from  the
              history file for editing.

   CCoommmmaannddss ffoorr CChhaannggiinngg TTeexxtt
       ddeelleettee--cchhaarr ((CC--dd))
              Delete the character under the cursor.  If the cur-
              sor is at the beginning of the line, and there  are
              no  characters  in the line, and the last character
              typed was not CC--dd, then return EEOOFF.
       bbaacckkwwaarrdd--ddeelleettee--cchhaarr ((RRuubboouutt))
              Delete the character behind the cursor.  A  numeric
              arg says to kill the characters instead of deleting



GNU                      1991 November 24                      26





BASH(1)                                                   BASH(1)


              them.
       qquuootteedd--iinnsseerrtt ((CC--qq,, CC--vv))
              Add the next character that you type  to  the  line
              verbatim.   This  is  how to insert characters like
              C-q, for example.
       ttaabb--iinnsseerrtt ((MM--TTAABB))
              Insert a tab character.
       sseellff--iinnsseerrtt ((aa,, bb,, AA,, 11,, !!,, ......))
              Insert the character typed.
       ttrraannssppoossee--cchhaarrss ((CC--tt))
              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.
       ttrraannssppoossee--wwoorrddss ((MM--tt))
              Drag the word behind the cursor past  the  word  in
              front  of  the  cursor  moving the cursor over that
              word as well.
       uuppccaassee--wwoorrdd ((MM--uu))
              Uppercase the current (or following) word.  With  a
              negative argument, do the previous word, but do not
              move point.
       ddoowwnnccaassee--wwoorrdd ((MM--ll))
              Lowercase the current (or following) word.  With  a
              negative argument, do the previous word, but do not
              move point.
       ccaappiittaalliizzee--wwoorrdd ((MM--cc))
              Capitalize the current (or following) word.  With a
              negative argument, do the previous word, but do not
              move point.

   KKiilllliinngg aanndd YYaannkkiinngg
       kkiillll--lliinnee ((CC--kk))
              Kill the text from the current cursor  position  to
              the end of the line.  This saves the killed text on
              the kill-ring.  (see below)
       bbaacckkwwaarrdd--kkiillll--lliinnee
              Kill backward to the beginning of the  line.   This
              is normally unbound, in favor of uunniixx--lliinnee--ddiissccaarrdd,
              which emulates the behavior of  the  standard  Unix
              terminal driver.
       kkiillll--wwoorrdd ((MM--dd))
              Kill  from  the  cursor  to  the end of the current
              word, or if between words, to the end of  the  next
              word.
       bbaacckkwwaarrdd--kkiillll--wwoorrdd ((MM--RRuubboouutt))
              Kill the word behind the cursor.
       uunniixx--lliinnee--ddiissccaarrdd ((CC--uu))
              Do what C-u used to do in Unix line input.  We save
              the killed text on the kill-ring, though.
       uunniixx--wwoorrdd--rruubboouutt ((CC--ww))
              Do what C-w used to do in  Unix  line  input.   The
              killed  text  is  saved  on the kill-ring.  This is



GNU                      1991 November 24                      27





BASH(1)                                                   BASH(1)


              different than backward-kill-word because the  word
              boundaries differ.
       yyaannkk ((CC--yy))
              Yank  the  top  of the kill ring into the buffer at
              point.
       yyaannkk--ppoopp ((MM--yy))
              Rotate the kill-ring, and yank the new  top.   Only
              works following `yank' or `yank-pop'.

   AArrgguummeennttss
       ddiiggiitt--aarrgguummeenntt ((MM--00,, MM--11,, ......,, MM----))
              Add  this  digit to the argument already accumulat-
              ing, or start a new argument.  M-- starts  a  nega-
              tive argument.
       uunniivveerrssaall--aarrgguummeenntt
              Do what C-u does in _e_m_a_c_s_.  By default, this is not
              bound to a key.

   CCoommpplleettiinngg
       ccoommpplleettee ((TTAABB))
              Attempt to perform completion on  the  text  before
              point.   BBaasshh attempts completion treating the text
              as a variable (if the text begins with $$), username
              (if  the text begins with ~~), hostname (if the text
              begins with @@), or command (including  aliases  and
              functions)  in  turn.   If none of these produces a
              match, filename completion is attempted.
       ppoossssiibbllee--ccoommpplleettiioonnss ((MM--??))
              List the possible completions of  the  text  before
              point.
       ccoommpplleettee--ffiilleennaammee ((MM--//))
              Attempt  filename  completion  on  the  text before
              point.
       ppoossssiibbllee--ffiilleennaammee--ccoommpplleettiioonnss ((CC--xx //))
              List the possible completions of  the  text  before
              point, treating it as a filename.
       ccoommpplleettee--uusseerrnnaammee ((MM--~~))
              Attempt completion on the text before point, treat-
              ing it as a username.
       ppoossssiibbllee--uusseerrnnaammee--ccoommpplleettiioonnss ((CC--xx ~~))
              List the possible completions of  the  text  before
              point, treating it as a username.
       ccoommpplleettee--vvaarriiaabbllee ((MM--$$))
              Attempt completion on the text before point, treat-
              ing it as a shell variable.
       ppoossssiibbllee--vvaarriiaabbllee--ccoommpplleettiioonnss ((CC--xx $$))
              List the possible completions of  the  text  before
              point, treating it as a shell variable.
       ccoommpplleettee--hhoossttnnaammee ((MM--@@))
              Attempt completion on the text before point, treat-
              ing it as a hostname.
       ppoossssiibbllee--hhoossttnnaammee--ccoommpplleettiioonnss ((CC--xx @@))
              List the possible completions of  the  text  before
              point, treating it as a hostname.



GNU                      1991 November 24                      28





BASH(1)                                                   BASH(1)


   MMiisscceellllaanneeoouuss
       aabboorrtt ((CC--gg))
              Abort the current editing command and ring the ter-
              minal's bell.
       ddoo--uuppppeerrccaassee--vveerrssiioonn ((MM--aa,, MM--bb,, ......))
              Run the command that is  bound  to  the  uppercased
              key.
       pprreeffiixx--mmeettaa ((EESSCC))
              Metafy  the next character typed.  This is for peo-
              ple without a meta key.  EESSCC  f  is  equivalent  to
              MMeettaa--ff.
       uunnddoo ((CC--__))
              Incremental  undo,  separately  remembered for each
              line.
       rreevveerrtt--lliinnee ((MM--rr))
              Undo all changes made to this line.  This  is  like
              typing  the `undo' command enough times to get back
              to the beginning.
       ddiissppllaayy--sshheellll--vveerrssiioonn ((CC--xx CC--vv))
              Display  version  information  about  the   current
              instance of bbaasshh.
       eemmaaccss--eeddiittiinngg--mmooddee ((CC--ee))
              When  in  vvii  editing mode, this causes a switch to
              eemmaaccss editing mode.
       vvii--eeddiittiinngg--mmooddee ((MM--CC--jj oorr MM--CC--mm))
              When in eemmaaccss editing mode, this causes a switch to
              vvii editing mode.

HHIISSTTOORRYY
       The  shell  supports  a  history expansion feature that is
       similar to the history expansion  in  ccsshh..   This  section
       describes what syntax features are available.

       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 determining
       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 _e_v_e_n_t, and the portions of
       that line that are acted upon are _w_o_r_d_s.  The line is bro-
       ken  into words in the same fashion as when reading input,
       so that several English,  or  Unix,  words  surrounded  by
       quotes are considered as one word.  Only backslash (\\) can
       quote the history escape character, which is !! by default.

   EEvveenntt DDeessiiggnnaattoorrss
       An event designator is a reference to a command line entry
       in the history list.

       !!      Start a history substitution, except when  followed
              by a <space>, <tab>, <newline>, = or (.
       !!!!     Refer  to  the previous command.  This is a synonym
              for `!-1'.



GNU                      1991 November 24                      29





BASH(1)                                                   BASH(1)


       !!_n     Refer to command line _n.
       !!--_n    Refer to the current command line minus _n.
       !!_s_t_r_i_n_g
              Refer to the  most  recent  command  starting  with
              _s_t_r_i_n_g.
       !!??_s_t_r_i_n_g[[??]]
              Refer to the most recent command containing _s_t_r_i_n_g.

   WWoorrdd DDeessiiggnnaattoorrss
       A :: separates the event specification from the word desig-
       nator.   It  can  be omitted if the word designator begins
       with a ^^, $$, **, or %%.  Words are numbered from the  begin-
       ning of the line, with the first word being denoted by a 0
       (zero).

       ##      The entire command line typed so far.   This  means
              the  current  command, not the previous command, so
              it really isn't  a  word  designator,  and  doesn't
              belong in this section.
       00 ((zzeerroo))
              The  zeroth  word.  For the shell, this is the com-
              mand word.
       _n      The _nth word.
       ^^      The first argument.  That is, word 1.
       $$      The last argument.
       %%      The word matched  by  the  most  recent  `?_s_t_r_i_n_g?'
              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.

   MMooddiiffiieerrss
       After the optional word designator, you can add a sequence
       of  one  or more of the following modifiers, each preceded
       by a `:'.

       hh      Remove a trailing pathname component, leaving  only
              the head.
       rr      Remove  a trailing suffix of the form ".xxx", leav-
              ing the basename.
       ee      Remove all but the suffix.
       tt      Remove all leading pathname components, leaving the
              tail.
       pp      Print  the new command but do not execute it.  This
              takes effect immediately, so it should be the  last
              specifier on the line.

AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN
       The  shell  allows arithmetic expressions to be evaluated,
       under certain circumstances (see the lleett  builtin  command
       and  AArriitthhmmeettiicc  EExxppaannssiioonn).   Evaluation  is done in long
       integers with no check for overflow, though division by  0



GNU                      1991 November 24                      30





BASH(1)                                                   BASH(1)


       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
       !!      logical NOT
       ** // %%  multiplication, division, remainder
       ++ --    addition, subtraction
       <<== >>== << >>
              comparison
       ==== !!==  equality and inequality
       ==      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.

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

SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS
       :: [_a_r_g_u_m_e_n_t_s]
              No effect; the command does nothing beyond  expand-
              ing _a_r_g_u_m_e_n_t_s and performing any specified redirec-
              tions.  A zero exit code is returned.
       .. _f_i_l_e_n_a_m_e
       ssoouurrccee _f_i_l_e_n_a_m_e
              Read and execute commands from _f_i_l_e_n_a_m_e in the cur-
              rent  shell  environment and return the exit status
              of the last command executed from _f_i_l_e_n_a_m_e.   Path-
              names  in  PPAATTHH are used to find the directory con-
              taining _f_i_l_e_n_a_m_e, if _f_i_l_e_n_a_m_e does  not  contain  a
              slash.   The  file searched for in PPAATTHH need not be
              executable.  The current directory is  searched  if
              no file is found in PPAATTHH.  The return status is the
              status of the last command exited within the script
              (ttrruuee  if  no  commands are executed), and false if
              _f_i_l_e_n_a_m_e is not found.

       aalliiaass [_n_a_m_e[=_v_a_l_u_e] ...]
              AAlliiaass with no arguments prints the list of  aliases
              in  the  form  _n_a_m_e=_v_a_l_u_e on standard output.  When
              arguments are supplied, an  alias  is  defined  for
              each  _n_a_m_e  whose _v_a_l_u_e is given.  A trailing space
              in _v_a_l_u_e causes the next word  to  be  checked  for
              alias  substitution  when  the  alias  is expanded.
              AAlliiaass returns true unless a _n_a_m_e is given for which
              no alias has been defined.





GNU                      1991 November 24                      31





BASH(1)                                                   BASH(1)


       bbgg [_j_o_b_s_p_e_c]
              Place  _j_o_b_s_p_e_c in the background, as if it had been
              started with &&.  If _j_o_b_s_p_e_c  is  not  present,  the
              shell's notion of the _c_u_r_r_e_n_t _j_o_b is used.

       bbiinndd [--llvvdd] [--qq _n_a_m_e]
       bbiinndd --ff _f_i_l_e_n_a_m_e
       bbiinndd _k_e_y_s_e_q:_f_u_n_c_t_i_o_n_-_n_a_m_e
              Display current rreeaaddlliinnee key and function bindings,
              or bind a key sequence to a  rreeaaddlliinnee  function  or
              macro.  The binding syntax accepted is identical to
              that of _._i_n_p_u_t_r_c, 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 follow-
              ing meanings:
              --ll     List the names of all rreeaaddlliinnee functions
              --vv     List current function names and bindings
              --dd     Dump  function  names and bindings in such a
                     way that they can be re-read
              --ff _f_i_l_e_n_a_m_e
                     Read key bindings from _f_i_l_e_n_a_m_e
              --qq _f_u_n_c_t_i_o_n
                     Query about  which  keys  invoke  the  named
                     _f_u_n_c_t_i_o_n

       bbrreeaakk [_n]
              Exit from within a ffoorr, wwhhiillee, or uunnttiill 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 executing a loop when
              bbrreeaakk is executed.

       bbuuiillttiinn [_s_h_e_l_l_-_b_u_i_l_t_i_n [_a_r_g_u_m_e_n_t_s]]
              Execute the specified  shell  builtin,  passing  it
              _a_r_g_u_m_e_n_t_s,  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 ccdd builtin is commonly redefined this
              way.

       ccdd [_d_i_r]
              Change the current directory to _d_i_r.  The  variable
              HHOOMMEE  is  the  default  _d_i_r.   The  variable CCDDPPAATTHH
              defines the search path for the directory  contain-
              ing _d_i_r.  Alternative directory names are separated
              by a colon (:).  A null directory name in CCDDPPAATTHH is
              the  same as the current directory, i.e. ``..''.  If
              _d_i_r begins with a slash (/),  then  CCDDPPAATTHH  is  not
              used.   An  argument of -- is equivalent to $$OOLLDDPPWWDD.
              The return value is true if the directory was  suc-
              cessfully changed; false otherwise.




GNU                      1991 November 24                      32





BASH(1)                                                   BASH(1)


       ccoommmmaanndd [--pp] [_c_o_m_m_a_n_d [_a_r_g ...]]
              Run  _c_o_m_m_a_n_d with _a_r_g_s suppressing the normal shell
              function lookup. Only builtin commands or  commands
              found  in  the PPAATTHH are executed.  If the --pp option
              is given, the search for _c_o_m_m_a_n_d is performed using
              a default value for PPAATTHH that is guaranteed to find
              all of the standard utilities.  An argument  of  ----
              disables  option checking for the rest of the argu-
              ments.  If an error occurred or _c_o_m_m_a_n_d  cannot  be
              found, the exit status is 127.  Otherwise, the exit
              status of the ccoommmmaanndd builtin is the exit status of
              _c_o_m_m_a_n_d.

       ccoonnttiinnuuee [_n]
              Resume  the  next  iteration  of the enclosing ffoorr,
              wwhhiillee, or uunnttiill 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 ccoonnttiinnuuee is executed.

       ddeeccllaarree [--ffrrxxii] [_n_a_m_e[=_v_a_l_u_e]]
       ttyyppeesseett [--ffrrxxii] [_n_a_m_e[=_v_a_l_u_e]]
              Declare  variables and/or give them attributes.  If
              no _n_a_m_es are given,  then  display  the  values  of
              variables instead.
              --ff     Use function names only
              --rr     Make  _n_a_m_es  readonly.   These  names cannot
                     then  be  assigned  values   by   subsequent
                     assignment statements.
              --xx     Mark _n_a_m_es for export to subsequent commands
                     via the environment.
              --ii     The  variable  is  treated  as  an  integer;
                     arithmetic evaluation (see AARRIITTHHMMEETTIICC EEVVAALLUU--
                     AATTIIOONN )) is performed when  the  variable  is
                     assigned a value.

              Using  `+'  instead  of `-' turns off the attribute
              instead.  When used  in  a  function,  makes  _n_a_m_es
              local, as with the llooccaall command.

       ddiirrss [[--ll]]
              Display  the  list of currently remembered directo-
              ries.  Directories are added to the list  with  the
              ppuusshhdd  command;  the  ppooppdd  command  moves  back up
              through the list.  The --ll option produces a  longer
              listing; the default listing format uses a tilde to
              denote the home directory.

       eecchhoo [--nnee] [_a_r_g ...]
              Output the _a_r_gs, separated by  spaces.   If  --nn  is
              specified,  the trailing newline is suppressed.  If
              the --ee  option  is  given,  interpretation  of  the



GNU                      1991 November 24                      33





BASH(1)                                                   BASH(1)


              following backslash-escaped characters is enabled:
              \\aa     alert (bell)
              \\bb     backspace
              \\cc     suppress trailing newline
              \\ff     form feed
              \\nn     new line
              \\rr     carriage return
              \\tt     horizontal tab
              \\vv     vertical tab
              \\\\     backslash
              \\nnnnnn   the   character  whose  ASCII  code  is  _n_n_n
                     (octal)

       eennaabbllee [--nn] [_n_a_m_e ...]
              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 pathname.  If --nn is used, each _n_a_m_e is dis-
              abled; otherwise, _n_a_m_e_s are enabled.  For  example,
              to  use the tteesstt found in PPAATTHH instead of the shell
              builtin version, type ``enable -n test''.

       eevvaall [_a_r_g ...]
              The _a_r_gs 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 the eevvaall command.  If there are no
              _a_r_g_s, or only null arguments, eevvaall returns true.

       eexxeecc [[--] _c_o_m_m_a_n_d [_a_r_g_u_m_e_n_t_s]]
              If _c_o_m_m_a_n_d is specified, it replaces the shell.  No
              new  process  is created.  The _a_r_g_u_m_e_n_t_s become the
              arguments to _c_o_m_m_a_n_d.  If the first argument is  --,
              the shell places a dash in the zeroth arg passed to
              _c_o_m_m_a_n_d.  This is what login  does.   If  the  file
              cannot  be  executed  for  some  reason,  the shell
              exits,     unless      the      shell      variable
              nnoo__eexxiitt__oonn__ffaaiilleedd__eexxeecc  exists.   If _c_o_m_m_a_n_d is not
              specified, any redirections take effect in the cur-
              rent shell.

       eexxiitt [_n]
       bbyyee [_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  EEXXIITT  is executed
              before the shell terminates.

       eexxppoorrtt [--nnppff] [_n_a_m_e[=_w_o_r_d]] ...
              The supplied _n_a_m_e_s are marked for automatic  export
              to  the  environment  of subsequently executed com-
              mands.  If the --ff option is given, the _n_a_m_e_s  refer
              to  functions.  If no _n_a_m_e_s are given, or if the --pp
              option is supplied, a list of all  names  that  are



GNU                      1991 November 24                      34





BASH(1)                                                   BASH(1)


              exported  in  this shell is printed.  The --nn option
              causes the export property to be removed  from  the
              named variables.  An argument of ---- disables option
              checking for the rest  of  the  arguments.   eexxppoorrtt
              returns  an  exit  status of true unless an illegal
              option is encountered.

       ffcc [--ee _e_n_a_m_e] [--nnllrr] [_f_i_r_s_t] [_l_a_s_t]
       ffcc --ss [_p_a_t=_r_e_p] [_c_m_d]
              Fix Command.  In the first form, a  range  of  com-
              mands  from _f_i_r_s_t to _l_a_s_t is selected from the his-
              tory list.  _F_i_r_s_t and _l_a_s_t 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  _l_a_s_t
              is  not  specified it is set to the current command
              for listing (so that ffcc --ll --1100 prints the  last  10
              commands)  and to _f_i_r_s_t otherwise.  If _f_i_r_s_t is not
              specified it is set to  the  previous  command  for
              editing and -16 for listing.

              The  --nn  flag  suppresses  the command numbers when
              listing.  The --rr flag reverses  the  order  of  the
              commands.   If  the  --ll flag is given, the commands
              are listed on standard output.  Otherwise, the edi-
              tor  given by _e_n_a_m_e is invoked on a file containing
              those commands.  If _e_n_a_m_e is not given,  the  value
              of  the  FFCCEEDDIITT  variable is used, and the value of
              EEDDIITTOORR if FFCCEEDDIITT is not set.  If  neither  variable
              is  set, _v_i is used.  When editing is complete, the
              edited commands are echoed and executed.

              In the second  form,  the  command  is  re-executed
              after  the  substitution  _o_l_d=_n_e_w  is performed.  A
              useful alias to use with this is  ``r=fc  -s'',  so
              that  typing  ``r cc'' runs the last command begin-
              ning with ``cc'' and typing ``r''  re-executes  the
              last command.

       ffgg [_j_o_b_s_p_e_c]
              Place  _j_o_b_s_p_e_c  in  the foreground, and make it the
              current  job.   If  _j_o_b_s_p_e_c  is  not  present,  the
              shell's notion of the _c_u_r_r_e_n_t _j_o_b is used.

       ggeettooppttss _o_p_t_s_t_r_i_n_g _n_a_m_e [_a_r_g_s]
              ggeettooppttss  is used by shell procedures to parse posi-
              tional parameters.  _o_p_t_s_t_r_i_n_g contains  the  option
              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, ggeettooppttss places the
              next  option in the shell variable _n_a_m_e, initializ-
              ing _n_a_m_e if it does not exist, and the index of the



GNU                      1991 November 24                      35





BASH(1)                                                   BASH(1)


              next  argument  to  be  processed into the variable
              OOPPTTIINNDD.  OOPPTTIINNDD is initialized to 1 each  time  the
              shell or a shell script is invoked.  When an option
              requires an argument, ggeettooppttss places that  argument
              into the variable OOPPTTAARRGG.  The shell does not reset
              OOPPTTIINNDD automatically; it  must  be  manually  reset
              between  multiple  calls to ggeettooppttss within the same
              shell invocation if a new set of parameters  is  to
              be used.

              ggeettooppttss  can  report  errors  in  two ways.  If the
              first character of _o_p_t_s_t_r_i_n_g  is  a  colon,  _s_i_l_e_n_t
              error reporting is used.  In normal operation diag-
              nostic messages are printed when illegal options or
              missing  option  arguments are encountered.  If the
              variable OOPPTTEERRRR is set to 0, no error message  will
              be  displayed,  even if the first character of _o_p_t_-
              _s_t_r_i_n_g is not a colon.

              If an illegal option is seen, ggeettooppttss places ? into
              _n_a_m_e  and,  if  not silent, prints an error message
              and unsets  OOPPTTAARRGG.   If  ggeettooppttss  is  silent,  the
              option  character  found is placed in OOPPTTAARRGG and no
              diagnostic message is printed.

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

              ggeettooppttss  normally parses the positional parameters,
              but if more arguments are given  in  _a_r_g_s,  ggeettooppttss
              parses  those  instead.  ggeettooppttss returns true if an
              option, specified or  unspecified,  is  found.   It
              returns  false if the end of options is encountered
              or an error occurs.

       hhaasshh [--rr] [_n_a_m_e]
              For each _n_a_m_e, the full pathname of the command  is
              determined  and  remembered.   The --rr option causes
              the shell to forget all remembered  locations.   If
              no  arguments  are  given, information about remem-
              bered commands is printed.  An argument of ----  dis-
              ables  option  checking  for  the rest of the argu-
              ments.  The return status is true unless a _n_a_m_e  is
              not found or an illegal option is supplied.

       hheellpp [_p_a_t_t_e_r_n]
              Display helpful information about builtin commands.
              If _p_a_t_t_e_r_n is specified, hheellpp gives  detailed  help
              on  all commands matching _p_a_t_t_e_r_n; otherwise a list
              of the builtins is printed.



GNU                      1991 November 24                      36





BASH(1)                                                   BASH(1)


       hhiissttoorryy [_n]
       hhiissttoorryy --rrwwaann [_f_i_l_e_n_a_m_e]
              With no options, display the command  history  list
              with line numbers.  Lines listed with with a ** have
              been modified.  An argument of  _n  lists  only  the
              last  _n  lines.   If  a non-option argument is sup-
              plied, it is used as the name of the history  file;
              if    not,   the   value   of   HHIISSTTFFIILLEE   (default
              _~_/_._b_a_s_h___h_i_s_t_o_r_y) is used.   Options,  if  supplied,
              have the following meanings:
              --aa     Append  the  ``new''  history lines (history
                     lines entered since  the  beginning  of  the
                     current bash session) to the history file
              --nn     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.
              --rr     read  the  contents  of the history file and
                     use them as the current history
              --ww     write the current  history  to  the  history
                     file,  overwriting  the  history file's con-
                     tents.

       jjoobbss [--llnnpp] [ _j_o_b_s_p_e_c ... ]
       jjoobbss --xx _c_o_m_m_a_n_d [ _a_r_g_s ... ]
              The first form  lists  the  active  jobs.   The  --ll
              option  lists process IDs in addition to the normal
              information; the --pp option lists only  the  process
              ID  of  the  job's  process  group  leader.  The --nn
              option displays only jobs that have changed  status
              since last notfied.  If _j_o_b_s_p_e_c is given, output is
              restricted to information about that job.

              If the --xx option is  supplied,  jjoobbss  replaces  any
              _j_o_b_s_p_e_c  found  in  _c_o_m_m_a_n_d or _a_r_g_s with the corre-
              sponding process group  ID,  and  executes  _c_o_m_m_a_n_d
              passing it _a_r_g_s.

       kkiillll [--ss ssiiggssppeecc | --ssiiggssppeecc] [_p_i_d | _j_o_b_s_p_e_c] ...
       kkiillll --ll [_s_i_g_n_u_m]
              Send  the  signal named by _s_i_g_s_p_e_c to the processes
              named by _p_i_d or _j_o_b_s_p_e_c.  _s_i_g_s_p_e_c is either a  sig-
              nal  name  such  as SSIIGGKKIILLLL or a signal number.  If
              _s_i_g_s_p_e_c is a signal name, the name is case insensi-
              tive  and may be given with or without the SSIIGG pre-
              fix.  If _s_i_g_s_p_e_c is not present,  then  SSIIGGTTEERRMM  is
              assumed.  An argument of --ll lists the signal names.
              If any arguments are supplied when --ll is given, the
              names  of  the  specified  signals  are listed.  An
              argument of ---- disables  option  checking  for  the
              rest  of  the  arguments.   kkiillll returns true if at
              least one signal was successfully sent, or false if
              an error occurs.



GNU                      1991 November 24                      37





BASH(1)                                                   BASH(1)


       lleett _a_r_g [_a_r_g ...]
              Each  _a_r_g  is an arithmetic expression to be evalu-
              ated (see AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN).  If the last  _a_r_g
              evaluates to 0, lleett returns 1; 0 is returned other-
              wise.

       llooccaall [_n_a_m_e[=_v_a_l_u_e]]
              Create a local variable named _n_a_m_e, and  assign  it
              _v_a_l_u_e.   When  llooccaall  is used within a function, it
              causes the variable _n_a_m_e to have  a  visible  scope
              restricted to that function and its children.  With
              no operands, llooccaall writes a list of local variables
              to  the  standard  output.   It  is an error to use
              llooccaall when not within a function.

       llooggoouutt Exit a login shell.

       ppooppdd [++//--nn]
              Removes entries from the directory stack.  With  no
              arguments,  removes  the  top  directory  from  the
              stack, and performs a ccdd to the new top  directory.
              ++nn     removes the _nth entry counting from the left
                     of the list shown  by  ddiirrss,  starting  with
                     zero.   For example: ``popd +0'' removes the
                     first directory, ``popd +1'' the second.
              --nn     removes the  _nth  entry  counting  from  the
                     right  of  the  list shown by ddiirrss, starting
                     with zero.  For example: ``popd -0'' removes
                     the  last directory, ``popd -1'' the next to
                     last.

              If the variable ppuusshhdd__ssiilleenntt is unset and the  ppooppdd
              command is successful, a ddiirrss is performed as well.

       ppuusshhdd _d_i_r
       ppuusshhdd ++//--nn
              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.
              ++nn     Rotates  the stack so that the _nth directory
                     (counting from the left of the list shown by
                     ddiirrss) is at the top.
              --nn     Rotates  the stack so that the _nth directory
                     (counting from the right) is at the top.
              ddiirr    adds _d_i_r to the directory stack at the  top,
                     making it the new current working directory.

              If the variable ppuusshhdd__ssiilleenntt is  not  set  and  the
              ppuusshhdd command is successful, a ddiirrss is performed as
              well.

       ppwwdd    Print the absolute pathname of the current  working
              directory.   The  path printed contains no symbolic



GNU                      1991 November 24                      38





BASH(1)                                                   BASH(1)


              links (but see the  description  of  nnoolliinnkkss  under
              SShheellll VVaarriiaabblleess above).

       rreeaadd [--rr] [_n_a_m_e ...]
              One  line  is read from the standard input, and the
              first word is assigned to the first _n_a_m_e, the  sec-
              ond  word to the second _n_a_m_e, and so on, with left-
              over words assigned to the  last  _n_a_m_e.   Only  the
              characters  in  IIFFSS  are  recognized as word delim-
              iters.  The return code is zero, unless end-of-file
              is encountered.  If the --rr option is given, a back-
              slash-newline pair is not ignored,  and  the  back-
              slash is considered to be part of the line.

       rreeaaddoonnllyy [--ppff] [_n_a_m_e ...]
              The  given _n_a_m_e_s are marked readonly and the values
              of these _n_a_m_e_s may not  be  changed  by  subsequent
              assignment.   If  the  --ff  option  is supplied, the
              functions corresponding to the _n_a_m_e_s are so marked.
              If  no  arguments are given, or if the --pp option is
              supplied, a list of all readonly names is  printed.
              An  argument of ---- disables option checking for the
              rest of the arguments.

       rreettuurrnn [_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 ..   (ssoouurrccee)  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.

       sseett [--aaeeffhhkknnoottuuvvxxllddCCHH] [_a_r_g ...]
              --aa      Automatically mark variables which are mod-
                      ified or created for export to the environ-
                      ment of subsequent commands.
              --ee      Exit immediately if a  _s_i_m_p_l_e_-_c_o_m_m_a_n_d  (see
                      SSHHEELLLL  GGRRAAMMMMAARR above) exits with a non-zero
                      status.  The shell does  not  exit  if  the
                      command  that  fails is part of an _u_n_t_i_l or
                      _w_h_i_l_e loop, part of an _i_f  statement,  part
                      of  a  &&&&  or  |||| list, or if the command's
                      return value is being inverted via !!.
              --ff      Disable pathname expansion.
              --hh      Locate and remember  function  commands  as
                      functions  are  defined.  Function commands
                      are normally looked up when the function is
                      executed.
              --kk      All  keyword  arguments  are  placed in the
                      environment for a command, not  just  those
                      that precede the command name.



GNU                      1991 November 24                      39





BASH(1)                                                   BASH(1)


              --mm      Monitor  mode.   Job  control  is  enabled.
                      This flag is on by default for  interactive
                      shells  on systems that support it (see JJOOBB
                      CCOONNTTRROOLL above).  Background  processes  run
                      in a separate process group and a line con-
                      taining their exit status is  printed  upon
                      their completion.
              --nn      Read  commands  but  do  not  execute them.
                      This may be used to check  a  shell  script
                      for  syntax  errors.   This  is ignored for
                      interactive shells.
              --oo _o_p_t_i_o_n_-_n_a_m_e
                      The _o_p_t_i_o_n_-_n_a_m_e can be one of  the  follow-
                      ing:
                      aalllleexxppoorrtt
                              Same as --aa.
                      bbrraacceeeexxppaanndd
                              The   shell  performs  curly  brace
                              expansion  (see   BBrraaccee   EExxppaannssiioonn
                              above).  This is on by default.
                      eemmaaccss   Use  an  emacs-style  command  line
                              editing interface.
                      eerrrreexxiitt Same as --ee.
                      hhiisstteexxppaanndd
                              Same as --HH.
                      iiggnnoorreeeeooff
                              The effect is as if the shell  com-
                              mand  `IGNOREEOF=10'  had been exe-
                              cuted (see SShheellll VVaarriiaabblleess  above).
                      mmoonniittoorr Same as --mm.
                      nnoocclloobbbbeerr
                              Same as --CC.
                      nnooeexxeecc  Same as --nn.
                      nnoogglloobb  Same as --ff.
                      nnoohhaasshh  Same as --dd.
                      nnoottiiffyy  The  effect is as if the shell com-
                              mand `notify='  had  been  executed
                              (see SShheellll VVaarriiaabblleess above).
                      nnoouunnsseett Same as --uu.
                      vveerrbboossee Same as --vv.
                      vvii      Use a vi-style command line editing
                              interface.
                      xxttrraaccee  Same as --xx.
                      If no _o_p_t_i_o_n_-_n_a_m_e is supplied,  the  values
                      of the current options are printed.
              --tt      Exit  after  reading and executing one com-
                      mand.
              --uu      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.
              --vv      Print shell input lines as they are read.
              --xx      After  expanding  each _s_i_m_p_l_e_-_c_o_m_m_a_n_d, bbaasshh



GNU                      1991 November 24                      40





BASH(1)                                                   BASH(1)


                      displays the expanded value  of  PPSS44,  fol-
                      lowed by the command and its expanded argu-
                      ments.
              --ll      Save and restore the binding of _n_a_m_e  in  a
                      ffoorr _n_a_m_e [in wwoorrdd] command (see SSHHEELLLL GGRRAAMM--
                      MMAARR above).
              --dd      Disable the hashing of  commands  that  are
                      looked  up  for  execution.  Normally, com-
                      mands are remembered in a hash  table,  and
                      once  found,  do  not  have to be looked up
                      again.
              --CC      The effect  is  as  if  the  shell  command
                      `noclobber='  had  been executed (see SShheellll
                      VVaarriiaabblleess above).
              --HH      Enable !!  style history substitution.  This
                      flag is on by by default.
              ----      If  no arguments follow this flag, then the
                      positional parameters  are  unset.   Other-
                      wise,  the positional parameters are set to
                      the _a_r_gs, even if some of them begin with a
                      --.
              --       Signal   the  end  of  options,  cause  all
                      remaining _a_r_gs to be assigned to the  posi-
                      tional  parameters.   The --xx and --vv options
                      are turned off.  If there are no _a_r_gs,  the
                      positional parameters remain unchanged.

              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 $$--.  After the  option
              arguments  are  processed,  the  remaining _a_r_gs are
              treated as values for the positional parameters and
              are  assigned, in order, to $$11, $$22, ......  $$99.  If no
              options or _a_r_gs are supplied, all  shell  variables
              are  printed.   The  return  status  is always true
              unless an illegal option is encountered.

       sshhiifftt [_n]
              The positional parameters from _n+1 ... are  renamed
              to  $$11 ........  If _n is not given, it is assumed to be
              1.  The exit status is 1 if _n is greater  than  $$##;
              otherwise 0.

       ssuussppeenndd [--ff]
              Suspend  the  execution  of  this  shell  until  it
              receives a SSIIGGCCOONNTT signal.  The --ff option says  not
              to  complain if this is a login shell; just suspend
              anyway.

       tteesstt _e_x_p_r
       [[ _e_x_p_r ]]
              Return a status of 0 (true) or 1 (false)  depending
              on  the  evaluation  of  the conditional expression



GNU                      1991 November 24                      41





BASH(1)                                                   BASH(1)


              _e_x_p_r.  Expressions 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.
              --bb _f_i_l_e
                     True if _f_i_l_e exists and is block special.
              --cc _f_i_l_e
                     True  if  _f_i_l_e  exists and is character spe-
                     cial.
              --dd _f_i_l_e
                     True if _f_i_l_e exists and is a directory.
              --ee _f_i_l_e
                     True if _f_i_l_e exists
              --ff _f_i_l_e
                     True if _f_i_l_e exists and is a regular file.
              --gg _f_i_l_e
                     True if _f_i_l_e exists and is set-group-id.
              --kk _f_i_l_e
                     True if _f_i_l_e has its ``sticky'' bit set.
              --LL _f_i_l_e
                     True if _f_i_l_e exists and is a symbolic  link.
              --pp _f_i_l_e
                     True if _f_i_l_e exists and is a named pipe.
              --rr _f_i_l_e
                     True if _f_i_l_e exists and is readable.
              --ss _f_i_l_e
                     True  if  _f_i_l_e exists and has a size greater
                     than zero.
              --SS _f_i_l_e
                     True if _f_i_l_e exists and is a socket.
              --tt [[_f_d]]
                     True if _f_d is opened on a terminal.   If  _f_d
                     is  omitted, it defaults to 1 (standard out-
                     put).
              --uu _f_i_l_e
                     True if _f_i_l_e exists and its set-user-id  bit
                     is set.
              --ww _f_i_l_e
                     True if _f_i_l_e exists and is writable.
              --xx _f_i_l_e
                     True if _f_i_l_e exists and is executable.
              --OO _f_i_l_e
                     True  if  _f_i_l_e  exists  and  is owned by the
                     effective user id.
              --GG _f_i_l_e
                     True if _f_i_l_e exists  and  is  owned  by  the
                     effective group id.
              _f_i_l_e_1 -nntt _f_i_l_e_2
                     True if _f_i_l_e_1 is newer (according to modifi-
                     cation date) than _f_i_l_e_2.
              _f_i_l_e_1 -oott _f_i_l_e_2
                     True if _f_i_l_e_1 is older than file2.
              _f_i_l_e_1 --eeff _f_i_l_e
                     True if _f_i_l_e_1 and _f_i_l_e_2 have the same device



GNU                      1991 November 24                      42





BASH(1)                                                   BASH(1)


                     and inode numbers.
              --zz _s_t_r_i_n_g
                     True if the length of _s_t_r_i_n_g is zero.
              --nn _s_t_r_i_n_g
              _s_t_r_i_n_g True if the length of _s_t_r_i_n_g is non-zero.
              _s_t_r_i_n_g_1 == _s_t_r_i_n_g_2
                     True if the strings are equal.
              _s_t_r_i_n_g_1 !!== _s_t_r_i_n_g_2
                     True if the strings are not equal.
              !! _e_x_p_r True if _e_x_p_r is false.
              _e_x_p_r_1 -aa _e_x_p_r_2
                     True if both _e_x_p_r_1 AND _e_x_p_r_2 are true.
              _e_x_p_r_1 -oo _e_x_p_r_2
                     True if either _e_x_p_r_1 OR _e_x_p_r_2 is true.
              _a_r_g_1 OOPP _a_r_g_2
                     OOPP  is  one  of  --eeqq, --nnee, --lltt, --llee, --ggtt, or
                     --ggee.   These  arithmetic  binary   operators
                     return  true  if  _a_r_g_1  is equal, not-equal,
                     less-than, less-than-or-equal, greater-than,
                     or  greater-than-or-equal than _a_r_g_2, respec-
                     tively.  _A_r_g_1 and _a_r_g_2 may be positive inte-
                     gers,  negative  integers,  or  the  special
                     expression --ll _s_t_r_i_n_g, which evaluates to the
                     length of _s_t_r_i_n_g.

       ttiimmeess  Print the accumulated user and system times for the
              shell and for processes run from the shell.

       ttrraapp [_a_r_g] [_s_i_g_s_p_e_c]
              The command _a_r_g is to be read and executed when the
              shell receives signal(s) _s_i_g_s_p_e_c.  If _a_r_g is absent
              or --, all specified signals are are reset to  their
              original  values (the values they had upon entrance
              to the shell).  If _a_r_g is the null string this sig-
              nal  is ignored by the shell and by the commands it
              invokes.  _s_i_g_s_p_e_c is either a signal name in  <sig-
              nal.h>, or a signal number.  If _s_i_g_s_p_e_c is EEXXIITT (0)
              the command _a_r_g is executed on exit from the shell.
              With no arguments, ttrraapp prints the list of commands
              associated with each signal number.  The --ll  option
              causes  the  shell  to print a list of signal names
              and their corresponding numbers.  An argument of ----
              disables  option checking for the rest of the argu-
              ments.  Signals 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
              either then trap name or number is invalid;  other-
              wise ttrraapp returns true.

       ttyyppee [--aallll] [--ttyyppee | --ppaatthh] [_n_a_m_e ...]
              With  no  options,  indicate how each _n_a_m_e would be
              interpreted if used as  a  command  name.   If  the
              --ttyyppee  flag  is used, ttyyppee prints a phrase which is



GNU                      1991 November 24                      43





BASH(1)                                                   BASH(1)


              one of _a_l_i_a_s, _k_e_y_w_o_r_d, _f_u_n_c_t_i_o_n, _b_u_i_l_t_i_n,  or  _f_i_l_e
              if _n_a_m_e 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 --ppaatthh flag  is
              used, ttyyppee either returns the name of the disk file
              that would be executed if _n_a_m_e were specified as  a
              command  name, or nothing if --ttyyppee would not return
              _f_i_l_e.  If a command is  hashed,  --ppaatthh  prints  the
              hashed value, not necessarily the file that appears
              first in PPAATTHH.  If the  --aallll  flag  is  used,  ttyyppee
              prints all of the places that contain an executable
              named _n_a_m_e.  This includes aliases  and  functions,
              if  and  only  if  the --ppaatthh flag is not also used.
              The table of hashed commands is not consulted  when
              using  --aallll.   ttyyppee accepts --aa, --tt, and --pp in place
              of --aallll, --ttyyppee, and --ppaatthh, respectively.  An  argu-
              ment of ---- disables option checking for the rest of
              the arguments.  ttyyppee returns true  if  any  of  the
              arguments are found, false if none are found.

       uulliimmiitt [--SSHHaaccddffmmssttppnn [_l_i_m_i_t]]
              UUlliimmiitt  provides  control over the resources avail-
              able to the shell and to processes started  by  it,
              on  systems  that allow such control.  The value of
              _l_i_m_i_t can be a number in the unit specified for the
              resource,  or  the  value  uunnlliimmiitteedd.   The HH and SS
              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 HH nor SS is specified, the  command  applies
              to  the  soft limit.  If _l_i_m_i_t is omitted, the cur-
              rent value of the soft limit  of  the  resource  is
              printed,  unless  the HH option is given.  When more
              than one resource is specified, the limit name  and
              unit  is  printed  before the value.  Other options
              are interpreted as follows:
              --aa     all current limits are reported
              --cc     the maximum size of core files created
              --dd     the maximum size of a process's data segment
              --ff     the  maximum  size  of  files created by the
                     shell
              --mm     the maximum resident set size
              --ss     the maximum stack size
              --tt     the maximum amount of cpu time in seconds
              --pp     the pipe size in 512-byte blocks  (this  may
                     not be set)
              --nn     the  maximum number of open file descriptors
                     (most systems do not allow this value to  be
                     set, only displayed)

              An  argument of ---- disables option checking for the
              rest of the arguments.  If _l_i_m_i_t is  given,  it  is



GNU                      1991 November 24                      44





BASH(1)                                                   BASH(1)


              the  new  value  of  the specified resource (the --aa
              option is display only).  If no  option  is  given,
              then --ff is assumed.  Values are in 1024-byte incre-
              ments, except for --tt, which is in seconds, and  --pp,
              which is in units of 512-byte blocks.

       uummaasskk [--SS] [_m_o_d_e]
              The  user  file-creation  mask  is set to _m_o_d_e.  If
              _m_o_d_e 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
              _c_h_m_o_d_(_1_).   If _m_o_d_e is omitted, or if the --SS option
              is supplied, the  current  value  of  the  mask  is
              printed.   The  --SS  option  causes  the  mask to be
              printed in symbolic form; the default output is  an
              octal  number.   An  argument of ---- disables option
              checking for the rest of the arguments.

       uunnaalliiaass [_n_a_m_e ...]
              Remove _n_a_m_es from the list of defined aliases.  The
              return  value  is true unless _n_a_m_e is not a defined
              alias.

       uunnsseett [-ffvv] [_n_a_m_e ...]
              For each _n_a_m_e, remove  the  corresponding  variable
              or,  given the --ff option, function.  An argument of
              ---- disables option checking for  the  rest  of  the
              arguments.   Note  that  PPAATTHH, IIFFSS, PPPPIIDD, PPSS11, PPSS22,
              UUIIDD, and EEUUIIDD cannot be unset.  If any  of  RRAANNDDOOMM,
              SSEECCOONNDDSS,  or LLIINNEENNOO are unset, they lose their spe-
              cial properties,  even  if  they  are  subsequently
              reset.  The exit status is true unless the variable
              _n_a_m_e does not exist or is non-unsettable.

       wwaaiitt [_n]
              Wait for the specified process and report 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 code is zero.

IINNVVOOCCAATTIIOONN
       A  _l_o_g_i_n  _s_h_e_l_l  is  one whose first character of argument
       zero is a -- ,, or one started with the --llooggiinn flag.

       An _i_n_t_e_r_a_c_t_i_v_e shell is one whose standard input and  out-
       put  are  both  connected  to  terminals (as determined by
       _i_s_a_t_t_y(3)), or one started with the --ii flag.  PPSS11  is  set
       and  $$--  includes ii if bbaasshh is interactive, allowing a way
       to test this state from a shell script or a startup  file.

       Login shells:
         On login:



GNU                      1991 November 24                      45





BASH(1)                                                   BASH(1)


               if _/_e_t_c_/_p_r_o_f_i_l_e exists, source it.

               if _~_/_._b_a_s_h___p_r_o_f_i_l_e exists, source it,
                 else if _~_/_._b_a_s_h___l_o_g_i_n exists, source it,
                   else if _~_/_._p_r_o_f_i_l_e exists, source it.

         On logout:
               if _~_/_._b_a_s_h___l_o_g_o_u_t exists, source it.

       Non-login interactive shells:
         On startup:
               if _~_/_._b_a_s_h_r_c exists, source it.

       Non-interactive shells:
         On startup:
               if the environment variable EENNVV is non-null, expand
            it and source the file it names.


SSEEEE AALLSSOO
       _T_h_e _G_n_u _R_e_a_d_l_i_n_e _L_i_b_r_a_r_y, Brian Fox
       _T_h_e _G_n_u _H_i_s_t_o_r_y _L_i_b_r_a_r_y, Brian Fox
       _A _S_y_s_t_e_m _V _C_o_m_p_a_t_i_b_l_e _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _4_._2_B_S_D _J_o_b
              _C_o_n_t_r_o_l, David Lennert
       _H_o_w _t_o _w_e_a_r _w_e_i_r_d _p_a_n_t_s _f_o_r _f_u_n _a_n_d _p_r_o_f_i_t, Brian Fox
       _s_h(1), _k_s_h(1), _c_s_h(1)

FFIILLEESS
       _/_b_i_n_/_b_a_s_h
              The bbaasshh executable
       _/_e_t_c_/_p_r_o_f_i_l_e
              The  systemwide  initialization  file, executed for
              login shells
       _~_/_._b_a_s_h___p_r_o_f_i_l_e
              The  personal  initialization  file,  executed  for
              login shells
       _~_/_._b_a_s_h_r_c
              The individual per-interactive-shell startup file
       _~_/_._i_n_p_u_t_r_c
              Individual _R_e_a_d_l_i_n_e initialization file

AAUUTTHHOORRSS
              Brian   Fox,   Free  Software  Foundation  (primary
              author)
              bfox@ai.MIT.Edu

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

BBUUGG RREEPPOORRTTSS
       If you find a bug in bbaasshh,,  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  bbaasshh  that  you
       have.



GNU                      1991 November 24                      46





BASH(1)                                                   BASH(1)


       Once  you have determined that a bug actually exists, mail
       a bug report to _b_a_s_h_-_m_a_i_n_t_a_i_n_e_r_s@_a_i_._M_I_T_._E_d_u.  If you  have
       a  fix, you are welcome to mail that as well!  Suggestions
       and `philosophical' bug reports  may  be  mailed  to  _b_u_g_-
       _b_a_s_h@_a_i_._M_I_T_._E_d_u   or   posted   to  the  Usenet  newsgroup
       ggnnuu..bbaasshh..bbuugg.

       ALL bug reports should include:

       The version number of bbaasshh
       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

       Comments and  bug  reports  concerning  this  manual  page
       should be directed to _c_h_e_t_@_i_n_s_._C_W_R_U_._E_d_u.

BBUUGGSS
       It's too big and too slow.

       There  are some subtle differences between bbaasshh and tradi-
       tional versions of sshh, mostly because of the PPOOSSIIXX  speci-
       fication.

       Aliases are confusing in some uses.































GNU                      1991 November 24                      47


