


BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


NAME
       bash,  :,  .,  alias,  bg, bind, break, builtin, case, cd,
       command, continue, declare, dirs,  disown,  echo,  enable,
       eval,  exec,  exit,  export,  fc,  fg, for, getopts, hash,
       help, history, if, jobs, kill, let, local,  logout,  popd,
       pushd,  pwd,  read,  readonly,  return, set, shift, shopt,
       source, suspend, test, times, trap, type, typeset, ulimit,
       umask,  unalias, unset, until, wait, while - bash built-in
       commands, see bash(1)

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

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

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

       bg [jobspec]
              Resume the suspended job jobspec in the background,



GNU                        1996 Mar 20                          1





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

       bind [-m keymap] [-lpsvPSV]
       bind [-m keymap] [-q function] [-u function] [-r keyseq]
       bind [-m keymap] -f filename
       bind [-m keymap] -x keyseq:shell-command
       bind [-m keymap] keyseq:function-name
              Display current readline key and function bindings,
              or  bind  a  key sequence to a readline function or
              macro.  The binding syntax accepted is identical to
              that  of  .inputrc, but each binding must be passed
              as  a   separate   argument;   e.g.,   '"\C-x\C-r":
              re-read-init-file'.  Options, if supplied, have the
              following meanings:
              -m keymap
                     Use keymap as the keymap to be  affected  by
                     the  subsequent bindings.  Acceptable keymap
                     names are emacs, emacs-standard, emacs-meta,
                     emacs-ctlx,  vi,  vi-move,  vi-command,  and
                     vi-insert.  vi is equivalent to  vi-command;
                     emacs is equivalent to emacs-standard.
              -l     List the names of all readline functions.
              -p     Display readline function names and bindings
                     in such a way that they can be re-read.
              -P     List current  readline  function  names  and
                     bindings.
              -v     Display  readline  variable names and values
                     in such a way that they can be re-read.
              -V     List current  readline  variable  names  and
                     values.
              -s     Display  readline  key  sequences  bound  to
                     macros and the strings they output in such a
                     way that they can be re-read.
              -S     Display  readline  key  sequences  bound  to
                     macros and the strings they output.
              -f filename
                     Read key bindings from filename.
              -q function
                     Query about  which  keys  invoke  the  named
                     function.
              -u function
                     Unbind all keys bound to the named function.
              -r keyseq
                     Remove any current binding for keyseq.
              -x keyseq::shell-command
                     Cause shell-command to be executed  whenever
                     keyseq is entered.

              The return value is 0 unless an unrecognized option



GNU                        1996 Mar 20                          2





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              is given or an error occurred.

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

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

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

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



GNU                        1996 Mar 20                          3





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

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

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

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

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

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




GNU                        1996 Mar 20                          4





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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



GNU                        1996 Mar 20                          5





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

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

       continue [_n]
              Resume  the  next  iteration  of the enclosing for,
              while, until, or select loop.  If _n  is  specified,
              resume  at the _nth enclosing loop.  _n must be >= 1.



GNU                        1996 Mar 20                          6





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              If _n is greater than the number of enclosing loops,
              the last enclosing loop (the ``top-level'' loop) is
              resumed.  The return value is 0 unless the shell is
              not executing a loop when continue is executed.

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

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

       dirs [-clpv] [[++_n]] [[--_n]]
              Without options, displays  the  list  of  currently
              remembered  directories.  The default display is on
              a single line with  directory  names  separated  by
              spaces.  Directories are added to the list with the
              pushd command; the  popd  command  removes  entries
              from the list.



GNU                        1996 Mar 20                          7





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              ++_n     Displays  the  _nth  entry  counting from the
                     left of the list shown by dirs when  invoked
                     without options, starting with zero.
              --_n     Displays  the  _nth  entry  counting from the
                     right of the list shown by dirs when invoked
                     without options, starting with zero.
              -c     Clears  the  directory stack by deleting all
                     of the entries.
              -l     Produces a longer listing; the default list-
                     ing  format  uses a tilde to denote the home
                     directory.
              -p     Print the directory stack with one entry per
                     line.
              -v     Print the directory stack with one entry per
                     line, prefixing each entry with its index in
                     the stack.

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

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

       echo [-neE] [arg ...]
              Output the args, separated by spaces, followed by a
              newline.   The return status is always 0.  If -n is
              specified, the trailing newline is suppressed.   If
              the  -e option is given, interpretation of the fol-
              lowing  backslash-escaped  characters  is  enabled.
              The  -E option disables the interpretation of these
              escape characters, even on systems where  they  are
              interpreted  by default.  The xpg_echo shell option
              may be used to dynamically determine whether or not
              echo  expands  these  escape characters by default.
              echo does not interpret  ----  to  mean  the  end  of
              options.   echo  interprets  the  following  escape
              sequences:
              \a     alert (bell)
              \b     backspace
              \c     suppress trailing newline
              \e     an escape character
              \f     form feed



GNU                        1996 Mar 20                          8





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              \n     new line
              \r     carriage return
              \t     horizontal tab
              \v     vertical tab
              \\\\     backslash
              \\nnn   the character whose ASCII code is the  octal
                     value nnn (one to three digits)
              \\xxnnn  the  character  whose ASCII code is the hex-
                     adecimal value nnn (one to three digits)

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

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

       exec [-cl] [-a name] [command [arguments]]
              If command is specified, it replaces the shell.  No
              new process is created.  The arguments  become  the
              arguments  to  command.   If  the -l option is sup-
              plied, the shell places a dash at the beginning  of
              the  zeroth  arg  passed  to command.  This is what
              login(1) does.  The -c option causes command to  be
              executed  with an empty environment.  If -a is sup-
              plied, the shell passes name as the zeroth argument
              to the executed command.  If command cannot be exe-
              cuted for  some  reason,  a  non-interactive  shell



GNU                        1996 Mar 20                          9





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              exits, unless the shell option execfail is enabled,
              in which case it returns failure.   An  interactive
              shell  returns  failure  if the file cannot be exe-
              cuted.  If command is not specified,  any  redirec-
              tions  take  effect  in  the current shell, and the
              return status is 0.   If  there  is  a  redirection
              error, the return status is 1.

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

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

       fc [-e ename] [-nlr] [first] [last]
       fc -s [pat=rep] [cmd]
              Fix Command.  In the first form, a  range  of  com-
              mands  from first to last is selected from the his-
              tory list.  First and last may be  specified  as  a
              string  (to  locate the last command beginning with
              that string) or as a number (an index into the his-
              tory  list,  where  a negative number is used as an
              offset from the current command number).   If  last
              is  not  specified it is set to the current command
              for listing (so that ``fc -l -10'' prints the  last
              10  commands)  and to first otherwise.  If first is
              not specified it is set to the previous command for
              editing and -16 for listing.

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




GNU                        1996 Mar 20                         10





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

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

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

       getopts optstring name [args]
              getopts is used by shell procedures to parse  posi-
              tional  parameters.   optstring contains the option
              characters to be recognized; if a character is fol-
              lowed by a colon, the option is expected to have an
              argument, which should  be  separated  from  it  by
              white  space.   The colon and question mark charac-
              ters may not be used as  option  characters.   Each
              time  it is invoked, getopts places the next option
              in the shell variable name, initializing name if it
              does  not exist, and the index of the next argument
              to be processed into the variable  OPTIND.   OPTIND
              is  initialized to 1 each time the shell or a shell
              script is invoked.   When  an  option  requires  an
              argument,  getopts  places  that  argument into the
              variable OPTARG.  The shell does not  reset  OPTIND
              automatically;  it  must  be manually reset between
              multiple calls to getopts  within  the  same  shell
              invocation  if  a  new  set  of parameters is to be
              used.

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



GNU                        1996 Mar 20                         11





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

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

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

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

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

       hash [-r] [-p filename] [name]
              For each name, the full file name of the command is
              determined by searching the  directories  in  $PATH
              and  remembered.   If the -p option is supplied, no
              path search is performed, and filename is  used  as
              the  full  file name of the command.  The -r option
              causes the shell to  forget  all  remembered  loca-
              tions.   If  no  arguments  are  given, information
              about remembered commands is printed.   The  return
              status  is  true  unless  a name is not found or an
              invalid option is supplied.

       help [-s] [pattern]
              Display helpful information about builtin commands.
              If  pattern  is specified, help gives detailed help
              on all commands matching  pattern;  otherwise  help
              for  all  the builtins and shell control structures
              is printed.  The -s option restricts  the  informa-
              tion  displayed  to  a  short  usage synopsis.  The
              return status is 0 unless no command  matches  pat-
              tern.

       history [[_n]]




GNU                        1996 Mar 20                         12





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

              The return value is 0 unless an invalid  option  is
              encountered, an error occurs while reading or writ-
              ing the history file, an invalid offset is supplied
              as an argument to -d, or the history expansion sup-
              plied as an argument to -p fails.

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



GNU                        1996 Mar 20                         13





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


                     notified of their status.
              -r     Restrict output to running jobs.
              -s     Restrict output to stopped jobs.

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

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

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

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

       local [option] [name[=value] ...]
              For each argument, a local variable named  name  is
              created, and assigned value.  The option can be any
              of the options accepted by declare.  When local  is
              used within a function, it causes the variable name
              to have a visible scope restricted to that function
              and its children.  With no operands, local writes a
              list of local variables to the standard output.  It
              is  an  error  to use local when not within a func-
              tion.  The return status is 0 unless local is  used
              outside a function, an invalid name is supplied, or
              name is a readonly variable.

       logout Exit a login shell.



GNU                        1996 Mar 20                         14





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

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

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

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

       pushd [-n] [dir]
       pushd [-n] [+_n] [-_n]
              Adds a directory to the top of the directory stack,
              or rotates the stack, making the  new  top  of  the
              stack the current working directory.  With no argu-
              ments,  exchanges  the  top  two  directories   and



GNU                        1996 Mar 20                         15





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              returns  0,  unless  the  directory stack is empty.
              Arguments, if supplied, have  the  following  mean-
              ings:
              ++_n     Rotates  the stack so that the _nth directory
                     (counting from the left of the list shown by
                     dirs, starting with zero) is at the top.
              --_n     Rotates  the stack so that the _nth directory
                     (counting from the right of the  list  shown
                     by  dirs, starting with zero) is at the top.
              -n     Suppresses the normal  change  of  directory
                     when  adding  directories  to  the stack, so
                     that only the stack is manipulated.
              dir    Adds dir to the directory stack at the  top,
                     making it the new current working directory.

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

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

       read [-ers] [-t timeout] [-a aname] [-p prompt] [-n
       nchars]  [-d delim] [name ...]
              One line is read from the standard input,  and  the
              first  word is assigned to the first name, the sec-
              ond word to the second name, and so on, with  left-
              over   words   and   their  intervening  separators
              assigned to the last  name.   If  there  are  fewer
              words  read from the standard input than names, the
              remaining names are  assigned  empty  values.   The
              characters  in  IFS are used to split the line into
              words.  The backslash character (\\) may be used  to
              remove  any  special meaning for the next character
              read and for line continuation.  Options,  if  sup-
              plied, have the following meanings:
              -a aname
                     The words are assigned to sequential indices
                     of the array variable aname, starting at  0.
                     aname  is  unset  before  any new values are
                     assigned.  Other name arguments are ignored.




GNU                        1996 Mar 20                         16





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              -d delim
                     The first character of delim is used to ter-
                     minate the input line, rather than  newline.
              -e     If  the standard input is coming from a ter-
                     minal, readline (see READLINE above) is used
                     to obtain the line.
              -n nchars
                     read returns after reading nchars characters
                     rather than waiting for a complete  line  of
                     input.
              -p prompt
                     Display  prompt, without a trailing newline,
                     before attempting to read  any  input.   The
                     prompt  is displayed only if input is coming
                     from a terminal.
              -r     Backslash does not act as an escape  charac-
                     ter.  The backslash is considered to be part
                     of the line.  In  particular,  a  backslash-
                     newline  pair may not be used as a line con-
                     tinuation.
              -s     Silent mode.  If input is coming from a ter-
                     minal, characters are not echoed.
              -t timeout
                     Cause read to time out and return failure if
                     a complete line of input is not read  within
                     timeout  seconds.  This option has no effect
                     if read is not reading input from the termi-
                     nal or a pipe.

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

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

       return [_n]
              Causes a function to exit  with  the  return  value
              specified by _n.  If _n is omitted, the return status
              is that of the last command executed in  the  func-
              tion  body.  If used outside a function, but during



GNU                        1996 Mar 20                         17





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              execution of a script by the ..   (source)  command,
              it  causes  the shell to stop executing that script
              and return either _n or the exit status of the  last
              command executed within the script as the exit sta-
              tus of the script.  If used outside a function  and
              not  during  execution of a script by .., the return
              status is false.

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



GNU                        1996 Mar 20                         18





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


                      allexport
                              Same as -a.
                      braceexpand
                              Same as -B.
                      emacs   Use  an  emacs-style  command  line
                              editing interface.  This is enabled
                              by default when the shell is inter-
                              active, unless the shell is started
                              with the --noediting option.
                      errexit Same as -e.
                      hashall Same as -h.
                      histexpand
                              Same as -H.
                      history Enable    command    history,    as
                              described  above   under   HISTORY.
                              This  option  is  on  by default in
                              interactive shells.
                      ignoreeof
                              The effect is as if the shell  com-
                              mand ``IGNOREEOF=10'' had been exe-
                              cuted (see Shell Variables  above).
                      keyword Same as -k.
                      monitor Same as -m.
                      noclobber
                              Same as -C.
                      noexec  Same as -n.
                      noglob  Same as -f.
                      notify  Same as -b.
                      nounset Same as -u.
                      onecmd  Same as -t.
                      physical
                              Same as -P.
                      posix   Change  the  behavior of bash where
                              the default operation differs  from
                              the  POSIX 1003.2 standard to match
                              the standard (posix mode).
                      privileged
                              Same as -p.
                      verbose Same as -v.
                      vi      Use a vi-style command line editing
                              interface.
                      xtrace  Same as -x.
                      If  -o is supplied with no option-name, the
                      values of the current options are  printed.
                      If  +o  is  supplied with no option-name, a
                      series of set commands to recreate the cur-
                      rent  option  settings  is displayed on the
                      standard output.
              -p      Turn on privileged mode.  In this mode, the
                      $ENV and $BASH_ENV files are not processed,
                      shell functions are not inherited from  the
                      environment, and the SHELLOPTS variable, if
                      it appears in the environment, is  ignored.
                      If  the shell is started with the effective



GNU                        1996 Mar 20                         19





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

              The  options  are  off  by default unless otherwise
              noted.  Using + rather than - causes these  options
              to  be  turned off.  The options can also be speci-
              fied as arguments to an invocation  of  the  shell.



GNU                        1996 Mar 20                         20





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              The current set of options may be found in $$--.  The
              return status is  always  true  unless  an  invalid
              option is encountered.

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

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

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

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

              The list of shopt options is:

              cdable_vars
                      If set, an argument to the cd builtin  com-
                      mand  that is not a directory is assumed to
                      be the name of a variable  whose  value  is
                      the directory to change to.
              cdspell If  set,  minor errors in the spelling of a



GNU                        1996 Mar 20                         21





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


                      directory component in a cd command will be
                      corrected.   The  errors  checked  for  are
                      transposed characters, a missing character,
                      and  one  character too many.  If a correc-
                      tion is found, the corrected file  name  is
                      printed,  and  the  command proceeds.  This
                      option is only used by interactive  shells.
              checkhash
                      If set, bash checks that a command found in
                      the hash table exists before trying to exe-
                      cute  it.   If  a  hashed command no longer
                      exists, a normal path search is  performed.
              checkwinsize
                      If  set,  bash checks the window size after
                      each command and, if necessary, updates the
                      values of LINES and COLUMNS.
              cmdhist If  set, bash attempts to save all lines of
                      a multiple-line command in the same history
                      entry.   This  allows  easy  re-editing  of
                      multi-line commands.
              dotglob If set, bash includes  filenames  beginning
                      with  a  `.'  in  the  results  of pathname
                      expansion.
              execfail
                      If set, a non-interactive  shell  will  not
                      exit  if  it cannot execute the file speci-
                      fied as an argument  to  the  exec  builtin
                      command.   An  interactive  shell  does not
                      exit if exec fails.
              expand_aliases
                      If set, aliases are expanded  as  described
                      above   under   ALIASES.   This  option  is
                      enabled by default for interactive  shells.
              extglob If  set, the extended pattern matching fea-
                      tures described above under Pathname Expan-
                      sion are enabled.
              histappend
                      If set, the history list is appended to the
                      file named by the  value  of  the  HISTFILE
                      variable  when the shell exits, rather than
                      overwriting the file.
              histreedit
                      If set, and readline is being used, a  user
                      is  given  the  opportunity  to  re-edit  a
                      failed history substitution.
              histverify
                      If set, and readline  is  being  used,  the
                      results  of  history  substitution  are not
                      immediately passed  to  the  shell  parser.
                      Instead,  the resulting line is loaded into
                      the readline editing buffer, allowing  fur-
                      ther modification.
              hostcomplete
                      If  set,  and  readline is being used, bash



GNU                        1996 Mar 20                         22





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


                      will attempt to perform hostname completion
                      when  a  word  containing a @@ is being com-
                      pleted  (see  Completing   under   READLINE
                      above).  This is enabled by default.
              huponexit
                      If  set,  bash will send SIGHUP to all jobs
                      when an interactive login shell exits.
              interactive_comments
                      If set, allow a word beginning  with  ##  to
                      cause  that  word and all remaining charac-
                      ters on that  line  to  be  ignored  in  an
                      interactive  shell  (see  COMMENTS  above).
                      This option is enabled by default.
              lithist If set, and the cmdhist option is  enabled,
                      multi-line  commands  are saved to the his-
                      tory with  embedded  newlines  rather  than
                      using  semicolon separators where possible.
              mailwarn
                      If set, and a file that  bash  is  checking
                      for  mail  has been accessed since the last
                      time it was checked, the message ``The mail
                      in mailfile has been read'' is displayed.
              no_empty_cmd_completion
                      If  set,  and  readline is being used, bash
                      will not attempt to  search  the  PATH  for
                      possible  completions  when  completion  is
                      attempted on an empty line.
              nocaseglob
                      If  set,  bash  matches  filenames   in   a
                      case-insensitive  fashion  when  performing
                      pathname expansion (see Pathname  Expansion
                      above).
              nullglob
                      If set, bash allows patterns which match no
                      files (see  Pathname  Expansion  above)  to
                      expand  to a null string, rather than them-
                      selves.
              progcomp
                      If set, the programmable completion facili-
                      ties  (see  Programmable  Completion above)
                      are enabled.  This  option  is  enabled  by
                      default.
              promptvars
                      If set, prompt strings undergo variable and
                      parameter expansion after being expanded as
                      described  in PROMPTING above.  This option
                      is enabled by default.
              restricted_shell
                      The shell sets this option if it is started
                      in  restricted  mode  (see RESTRICTED SHELL
                      below).  The  value  may  not  be  changed.
                      This  is  not  reset when the startup files
                      are executed, allowing the startup files to
                      discover   whether   or   not  a  shell  is



GNU                        1996 Mar 20                         23





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


                      restricted.
              shift_verbose
                      If set, the shift builtin prints  an  error
                      message  when  the  shift count exceeds the
                      number of positional parameters.
              sourcepath
                      If set, the source  (..)  builtin  uses  the
                      value  of  PATH  to find the directory con-
                      taining the file supplied as  an  argument.
                      This option is enabled by default.
              xpg_echo
                      If set, the echo builtin expands backslash-
                      escape sequences by default.
       suspend [-f]
              Suspend  the  execution  of  this  shell  until  it
              receives  a SIGCONT signal.  The -f option says not
              to complain if this is a login shell; just  suspend
              anyway.  The return status is 0 unless the shell is
              a login shell and -f is not  supplied,  or  if  job
              control is not enabled.
       test expr
       [[ expr ]]
              Return  a status of 0 or 1 depending on the evalua-
              tion of  the  conditional  expression  expr.   Each
              operator  and  operand must be a separate argument.
              Expressions are composed of the primaries described
              above under CONDITIONAL EXPRESSIONS.

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

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

              0 arguments
                     The expression is false.
              1 argument
                     The expression is true if and  only  if  the
                     argument is not null.
              2 arguments
                     If  the  first argument is !!, the expression
                     is true if and only if the  second  argument
                     is  null.   If  the first argument is one of
                     the unary conditional operators listed above



GNU                        1996 Mar 20                         24





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


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

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

       trap [-lp] [arg] [sigspec ...]
              The command arg is to be read and executed when the
              shell receives signal(s) sigspec.  If arg is absent
              or  --,  all  specified  signals  are reset to their
              original values (the values they had upon  entrance
              to  the shell).  If arg is the null string the sig-
              nal specified by each sigspec  is  ignored  by  the
              shell  and  by  the commands it invokes.  If arg is
              not present and -p has been supplied, then the trap
              commands  associated  with  each  sigspec  are dis-
              played.  If no arguments are supplied or if only -p
              is  given, trap prints the list of commands associ-
              ated with each  signal  number.   Each  sigspec  is
              either  a  signal  name defined in <signal.h>, or a
              signal number.  If a sigspec is EXIT (0)  the  com-
              mand  arg is executed on exit from the shell.  If a
              sigspec is DEBUG, the command arg is executed after
              every  simple  command  (see  SHELL GRAMMAR above).
              The -l option causes the shell to print a  list  of



GNU                        1996 Mar 20                         25





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              signal names and their corresponding numbers.  Sig-
              nals ignored upon entry  to  the  shell  cannot  be
              trapped  or  reset.   Trapped  signals are reset to
              their original values in a child process when it is
              created.  The return status is false if any sigspec
              is invalid; otherwise trap returns true.

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

       ulimit [-SHacdflmnpstuv [limit]]
              Provides  control  over  the resources available to
              the shell and to processes started by it,  on  sys-
              tems  that  allow such control.  The value of limit
              can be a number  in  the  unit  specified  for  the
              resource,  or  the  value unlimited.  The -H and -S
              options specify that the hard or soft limit is  set
              for  the  given  resource.   A hard limit cannot be
              increased once it is  set;  a  soft  limit  may  be
              increased  up  to  the value of the hard limit.  If
              neither -H nor -S is specified, both the  soft  and
              hard limits are set.  If limit is omitted, the cur-
              rent value of the soft limit  of  the  resource  is
              printed,  unless the -H option is given.  When more
              than one resource is specified, the limit name  and
              unit  are  printed before the value.  Other options
              are interpreted as follows:
              -a     All current limits are reported
              -c     The maximum size of core files created
              -d     The maximum size of a process's data segment
              -f     The  maximum  size  of  files created by the
                     shell
              -l     The maximum size that  may  be  locked  into
                     memory
              -m     The maximum resident set size



GNU                        1996 Mar 20                         26





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              -n     The  maximum number of open file descriptors
                     (most systems do not allow this value to  be
                     set)
              -p     The  pipe  size in 512-byte blocks (this may
                     not be set)
              -s     The maximum stack size
              -t     The maximum amount of cpu time in seconds
              -u     The maximum number of processes available to
                     a single user
              -v     The  maximum amount of virtual memory avail-
                     able to the shell

              If limit is given, it is the new value of the spec-
              ified resource (the -a option is display only).  If
              no option is given, then -f is assumed.  Values are
              in 1024-byte increments, except for -t, which is in
              seconds, -p, which is in units of 512-byte  blocks,
              and  -n  and  -u,  which  are unscaled values.  The
              return status is 0  unless  an  invalid  option  is
              encountered,  a  non-numeric  argument  other  than
              unlimited is supplied as limit, or an error  occurs
              while setting a new limit.

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

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

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



GNU                        1996 Mar 20                         27





BASH_BUILTINS(1)                                 BASH_BUILTINS(1)


              properties,  even  if  they are subsequently reset.
              The exit status is true  unless  a  name  does  not
              exist or is readonly.

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

SEE ALSO
       bash(1), sh(1)







































GNU                        1996 Mar 20                         28


