path: root/documentation/builtins.txt

BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



NAME
     bash, :, ., alias, bg, bind, break, builtin, bye, case,  cd,
     command,  continue, declare, dirs, 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, source, suspend, test,  times,
     trap,  type,  typeset, ulimit, umask, unalias, unset, until,
     wait, while - bash built-in commands, see bash(1)

BASH BUILTIN COMMANDS
     : [_a_r_g_u_m_e_n_t_s]
          No effect; the command does  nothing  beyond  expanding
          _a_r_g_u_m_e_n_t_s and performing any specified redirections.  A
          zero exit code is returned.

      .  _f_i_l_e_n_a_m_e [_a_r_g_u_m_e_n_t_s]
     source _f_i_l_e_n_a_m_e [_a_r_g_u_m_e_n_t_s]
          Read and execute commands from _f_i_l_e_n_a_m_e in the  current
          shell  environment  and  return  the exit status of the
          last command executed from _f_i_l_e_n_a_m_e.  If _f_i_l_e_n_a_m_e  does
          not contain a slash, pathnames in PATH are used to find
          the directory containing _f_i_l_e_n_a_m_e.  The  file  searched
          for in PATH need not be executable.  The current direc-
          tory is searched if no file is found in PATH.   If  any
          _a_r_g_u_m_e_n_t_s  are  supplied,  they  become  the positional
          parameters when _f_i_l_e is executed.  Otherwise the  posi-
          tional  parameters are unchanged.  The return status is
          the status of the last command exited within the script
          (0  if no commands are executed), and false if _f_i_l_e_n_a_m_e
          is not found.

     alias [_n_a_m_e[=_v_a_l_u_e] ...]
          Alias 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.  For each _n_a_m_e in the argument list
          for which no _v_a_l_u_e is supplied, the name and  value  of
          the alias is printed.  Alias returns true unless a _n_a_m_e
          is given for which no alias has been defined.

     bg [_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.  bg _j_o_b_s_p_e_c  returns
          0  unless run when job control is disabled or, when run
          with job control enabled, if _j_o_b_s_p_e_c was not  found  or
          started without job control.

     bind [-m _k_e_y_m_a_p] [-lvd] [-q _n_a_m_e]
     bind [-m _k_e_y_m_a_p] -f _f_i_l_e_n_a_m_e



GNU              Last change: 1993 September 16                 1






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



     bind [-m _k_e_y_m_a_p] _k_e_y_s_e_q:_f_u_n_c_t_i_o_n-_n_a_m_e
          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
          ._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 following meanings:
          -m _k_e_y_m_a_p
               Use _k_e_y_m_a_p as the keymap to  be  affected  by  the
               subsequent  bindings.  Acceptable _k_e_y_m_a_p names are
               _e_m_a_c_s, _e_m_a_c_s-_s_t_a_n_d_a_r_d, _e_m_a_c_s-_m_e_t_a, _e_m_a_c_s-_c_t_l_x, _v_i,
               _v_i-_m_o_v_e,   _v_i-_c_o_m_m_a_n_d,   and   _v_i-_i_n_s_e_r_t.   _v_i  is
               equivalent to _v_i-_c_o_m_m_a_n_d; _e_m_a_c_s is  equivalent  to
               _e_m_a_c_s-_s_t_a_n_d_a_r_d.
          -l   List the names of all readline functions
          -v   List current function names and bindings
          -d   Dump function names and bindings  in  such  a  way
               that they can be re-read
          -f _f_i_l_e_n_a_m_e
               Read key bindings from _f_i_l_e_n_a_m_e
          -q _f_u_n_c_t_i_o_n
               Query about which keys invoke the named _f_u_n_c_t_i_o_n

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

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

     builtin _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 cd builtin  is
          commonly  redefined  this  way.   The  return status is
          false if _s_h_e_l_l-_b_u_i_l_t_i_n is not a shell builtin command.

     cd [_d_i_r]
          Change the current directory to _d_i_r.  The variable HOME
          is  the  default  _d_i_r.  The variable CDPATH defines the
          search path for the directory containing _d_i_r.  Alterna-
          tive  directory  names are separated by a colon (:).  A
          null directory name  in  CDPATH  is  the  same  as  the
          current  directory,  i.e., ``.''.  If _d_i_r begins with a
          slash (/), then CDPATH is not used.  An argument  of  -
          is  equivalent to $OLDPWD.  The return value is true if
          the   directory   was   successfully   changed;   false



GNU              Last change: 1993 September 16                 2






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          otherwise.

     command [-pVv] _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 PATH are executed.  If the  -p  option  is
          given,  the  search  for  _c_o_m_m_a_n_d  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  _c_o_m_m_a_n_d   is
          printed.  The -v option causes a single word indicating
          the command or pathname used to invoke  _c_o_m_m_a_n_d  to  be
          printed; the -V option produces a more verbose descrip-
          tion.  An argument of -- disables option  checking  for
          the  rest  of the arguments.  If the -V or -v option is
          supplied, the exit status is 0 if  _c_o_m_m_a_n_d  was  found,
          and  1  if  not.   If neither option is supplied and 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 com-
          mand builtin is the exit status of _c_o_m_m_a_n_d.

     continue [_n]
          Resume the next iteration of the enclosing for,  while,
          or  until  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 con-
          tinue is executed.

     declare [-frxi] [_n_a_m_e[=_v_a_l_u_e]]
     typeset [-frxi] [_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.  The options can be used to restrict output to
          variables with the specified attribute.
          -f   Use function names only
          -r   Make _n_a_m_es readonly.  These names cannot  then  be
               assigned  values  by  subsequent assignment state-
               ments.
          -x   Mark _n_a_m_es for export to subsequent  commands  via
               the environment.
          -i   The variable is treated as an integer;  arithmetic
               evaluation  (see  ARITHMETIC  EVALUATION ) is per-
               formed 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 local  command.   The  return  value  is  0
          unless  an illegal option is encountered, an attempt is
          made to define a function using "-f  foo=bar",  one  of
          the  _n_a_m_e_s  is  not  a  legal  shell  variable name, an



GNU              Last change: 1993 September 16                 3






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          attempt is made to  turn  off  readonly  status  for  a
          readonly  variable,  or an attempt is made to display a
          non-existant function with -f.

     dirs [-l] [+/-n]
          Display the list of currently  remembered  directories.
          Directories  are  added to the list with the pushd com-
          mand; the popd command moves back up through the list.
          +n   displays the _nth entry counting from the  left  of
               the  list  shown  by  dirs  when  invoked  without
               options, starting with zero.
          -n   displays the _nth entry counting from the right  of
               the  list  shown  by  dirs  when  invoked  without
               options, starting with zero.
          -l   produces a longer  listing;  the  default  listing
               format uses a tilde to denote the home directory.

          The return value is 0 unless an illegal option is  sup-
          plied  or  _n  indexes  beyond  the end of the directory
          stack.

     echo [-neE] [_a_r_g ...]
          Output the  _a_r_gs,  separated  by  spaces.   The  return
          status  is  always 0.  If -n is specified, the trailing
          newline is suppressed.  If  the  -e  option  is  given,
          interpretation of the following backslash-escaped char-
          acters  is  enabled.   The  -E  option   disables   the
          interpretation of these escape characters, even on sys-
          tems where they are interpreted by default.
          \a   alert (bell)
          \b   backspace
          \c   suppress trailing newline
          \f   form feed
          \n   new line
          \r   carriage return
          \t   horizontal tab
          \v   vertical tab
          \\   backslash
          \nnn the character whose ASCII code is _n_n_n (octal)

     enable [-n] [-all] [_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  -n is used, each _n_a_m_e is disabled; otherwise, _n_a_m_e_s
          are enabled.  For example, to use the test binary found
          via the PATH instead of the shell builtin version, type
          ``enable -n test''.  If no arguments are given, a  list
          of  all  enabled shell builtins is printed.  If only -n
          is  supplied,  a  list  of  all  disabled  builtins  is
          printed.   If  only  -all is supplied, the list printed
          includes all builtins, with an indication of whether or



GNU              Last change: 1993 September 16                 4






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          not  each  is  enabled.  enable accepts -a as a synonym
          for -all.  The return value is 0 unless a _n_a_m_e is not a
          shell builtin.

     eval [_a_r_g ...]
          The _a_r_gs are read and concatenated together into a sin-
          gle command.  This command is then read and executed by
          the shell, and its exit status is returned as the value
          of  the  eval  command.   If there are no _a_r_g_s, or only
          null arguments, eval returns true.

     exec [[-] _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  exe-
          cuted  for  some reason, a non-interactive shell exits,
          unless  the   shell   variable   no_exit_on_failed_exec
          exists,  in which case it returns failure.  An interac-
          tive shell returns failure if the file cannot  be  exe-
          cuted.   If  _c_o_m_m_a_n_d is not specified, any redirections
          take effect in the current shell, and the return status
          is 0.

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

     export [-nf] [_n_a_m_e[=_w_o_r_d]] ...
     export -p
          The supplied _n_a_m_e_s are marked for automatic  export  to
          the  environment of subsequently executed commands.  If
          the -f option is given, the _n_a_m_e_s refer  to  functions.
          If no _n_a_m_e_s 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.  An argument of --
          disables option checking for the rest of the arguments.
          export returns an exit status of 0  unless  an  illegal
          option  is encountered, one of the _n_a_m_e_s is not a legal
          shell variable name, or -f is supplied with a _n_a_m_e that
          is not a function.

     fc [-e _e_n_a_m_e] [-nlr] [_f_i_r_s_t] [_l_a_s_t]
     fc -s [_p_a_t=_r_e_p] [_c_m_d]
          Fix Command.  In the first form, a  range  of  commands
          from  _f_i_r_s_t  to _l_a_s_t is selected from the history 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



GNU              Last change: 1993 September 16                 5






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          number (an index into the history list, where  a  nega-
          tive  number is used as an offset from the current com-
          mand number).  If _l_a_s_t is not specified it  is  set  to
          the  current  command  for  listing  (so that fc -l -10
          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 -n flag suppresses the command numbers  when  list-
          ing.   The  -r flag reverses the order of the commands.
          If the -l flag is given, the  commands  are  listed  on
          standard  output.  Otherwise, the editor 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 FCEDIT variable is
          used, and the value of EDITOR if FCEDIT is not set.  If
          neither variable is set, is used.  When editing is com-
          plete, the edited commands are echoed and executed.

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

          If the first form is used, the return value is 0 unless
          an  illegal  option  is  encountered  or  _f_i_r_s_t or _l_a_s_t
          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  _c_m_d does not specify a valid history
          line, in which case fc returns failure.

     fg [_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.  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  _j_o_b_s_p_e_c does not
          specify a valid job or _j_o_b_s_p_e_c specifies a job that was
          started without job control.

     getopts _o_p_t_s_t_r_i_n_g _n_a_m_e [_a_r_g_s]
          getopts is used by shell procedures to parse positional
          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 argument, which should be
          separated from it by white  space.   Each  time  it  is
          invoked,  getopts  places  the next option in the shell
          variable _n_a_m_e, initializing _n_a_m_e if it does not  exist,



GNU              Last change: 1993 September 16                 6






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          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  argu-
          ment  into  the  variable  OPTARG.   The shell does not
          reset OPTIND automatically; it must be  manually  reset
          between multiple calls to getopts within the same shell
          invocation if a new set of parameters is to be used.

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

          If an illegal option is seen,  getopts  places  ?  into
          _n_a_m_e  and,  if  not silent, prints an error message and
          unsets OPTARG.  If getopts is silent, the option  char-
          acter  found is placed in OPTARG and no diagnostic mes-
          sage is printed.

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

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

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

     help [_p_a_t_t_e_r_n]
          Display helpful information about builtin commands.  If
          _p_a_t_t_e_r_n  is  specified, help gives detailed help on all
          commands matching _p_a_t_t_e_r_n;  otherwise  a  list  of  the
          builtins  is printed.  The return status is 0 unless no
          command matches _p_a_t_t_e_r_n.



GNU              Last change: 1993 September 16                 7






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



     history [_n]
     history -rwan [_f_i_l_e_n_a_m_e]
          With no options, display the command history list  with
          line  numbers.   Lines  listed with a * have been modi-
          fied.  An argument of _n lists only the  last  _n  lines.
          If a non-option argument is supplied, it is used as the
          name of the history file; if not, the value of HISTFILE
          is  used.   Options,  if  supplied,  have the following
          meanings:
          -a   Append the ``new'' history  lines  (history  lines
               entered  since  the  beginning of the current bash
               session) to the history file
          -n   Read the history lines not already read  from  the
               history file into the current history list.  These
               are lines appended to the history 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 contents.

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

     jobs [-lnp] [ _j_o_b_s_p_e_c ... ]
     jobs -x _c_o_m_m_a_n_d [ _a_r_g_s ... ]
          The first form lists the active jobs.   The  -l  option
          lists  process  IDs  in addition to the normal informa-
          tion; the -p option lists only the process  ID  of  the
          job's  process  group  leader.   The -n option displays
          only jobs that have changed status since last notified.
          If  _j_o_b_s_p_e_c  is given, output is restricted to informa-
          tion about that job.  The return status is 0 unless  an
          illegal  option is encountered or an illegal _j_o_b_s_p_e_c is
          supplied.

          If the -x option is supplied, jobs 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 corresponding process
          group ID, and executes _c_o_m_m_a_n_d passing it _a_r_g_s, return-
          ing its exit status.

     kill [-s sigspec | -sigspec] [_p_i_d | _j_o_b_s_p_e_c] ...
     kill -l [_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 signal name
          such as SIGKILL or a signal number.  If  _s_i_g_s_p_e_c  is  a
          signal  name,  the  name is case insensitive and may be
          given with or without the SIG prefix.   If  _s_i_g_s_p_e_c  is
          not  present,  then SIGTERM is assumed.  An argument of
          -l lists the signal names.  If any arguments  are  sup-
          plied  when  -l  is  given,  the names of the specified



GNU              Last change: 1993 September 16                 8






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          signals are listed, and the return  status  is  0.   An
          argument of -- disables option checking for the rest of
          the arguments.  kill returns true if at least one  sig-
          nal  was successfully sent, or false if an error occurs
          or an illegal option is encountered.

     let _a_r_g [_a_r_g ...]
          Each _a_r_g is an arithmetic expression  to  be  evaluated
          (see ARITHMETIC EVALUATION).  If the last _a_r_g evaluates
          to 0, let returns 1; 0 is returned otherwise.

     local [_n_a_m_e[=_v_a_l_u_e] ...]
          For each argument, create a local variable named  _n_a_m_e,
          and assign it _v_a_l_u_e.  When local is used within a func-
          tion, it causes the variable _n_a_m_e  to  have  a  visible
          scope  restricted  to  that  function and its children.
          With no operands, local writes a list  of  local  vari-
          ables  to  the  standard output.  It is an error to use
          local when not within a function.  The return status is
          0  unless local is used outside a function, or an ille-
          gal _n_a_m_e is supplied.

     logout
          Exit a login shell.

     popd [+/-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.
          +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.

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

     pushd [_d_i_r]
     pushd +/-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   arguments,
          exchanges the top two directories and returns 0, unless
          the directory stack is empty.
          +n   Rotates  the  stack  so  that  the  _nth  directory



GNU              Last change: 1993 September 16                 9






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



               (counting from the left of the list shown by dirs)
               is at the top.
          -n   Rotates  the  stack  so  that  the  _nth  directory
               (counting from the right) is at the top.
          dir  adds _d_i_r to the directory stack at the top, making
               it the new current working directory.

          If the pushd command is successful, a dirs is performed
          as  well.   If  the first form is used, pushd returns 0
          unless the cd to _d_i_r  fails.   With  the  second  form,
          pushd  returns 0 unless the directory stack is empty, a
          non-existant directory stack element is  specified,  or
          the  directory  change  to  the  specified  new current
          directory fails.

     pwd  Print the absolute  pathname  of  the  current  working
          directory.  The path printed contains no symbolic links
          if the -P option to the set  builtin  command  is  set.
          See  also  the description of nolinks under Shell Vari-
          ables above).  The return status is 0 unless  an  error
          occurs while reading the pathname of the current direc-
          tory.

     read [-r] [_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 second word to
          the  second  _n_a_m_e,  and  so  on,  with  leftover  words
          assigned  to the last _n_a_m_e.  Only the characters in IFS
          are recognized as word delimiters.   If  no  _n_a_m_e_s  are
          supplied,  the  line  read  is assigned to the variable
          REPLY.  The return code is zero, unless end-of-file  is
          encountered.   If  the -r option is given, a backslash-
          newline pair is not ignored, and the backslash is  con-
          sidered to be part of the line.

     readonly [-f] [_n_a_m_e ...]
     readonly -p
          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 assign-
          ment.  If the -f  option  is  supplied,  the  functions
          corresponding  to the _n_a_m_e_s are so marked.  If no argu-
          ments are given, or if the -p  option  is  supplied,  a
          list  of all readonly names is printed.  An argument of
          -- disables option checking for the rest of  the  argu-
          ments.  The return status is 0 unless an illegal option
          is encountered, one of the _n_a_m_e_s is not a  legal  shell
          variable  name,  or  -f is supplied with a _n_a_m_e that is
          not a function.

     return [_n]
          Causes a function to exit with the return value  speci-
          fied  by _n.  If _n is omitted, the return status is that



GNU              Last change: 1993 September 16                10






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



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

     set [--abefhkmnptuvxldCHP] [-o _o_p_t_i_o_n] [_a_r_g ...]
          -a      Automatically mark variables which are modified
                  or  created  for  export  to the environment of
                  subsequent commands.
          -b      Cause the status of terminated background  jobs
                  to  be reported immediately, rather than before
                  the next  primary  prompt.   (Also  see  notify
                  under Shell Variables above).
          -e      Exit immediately if a _s_i_m_p_l_e-_c_o_m_m_a_n_d (see SHELL
                  GRAMMAR  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 !.
          -f      Disable pathname expansion.
          -h      Locate and remember function commands as  func-
                  tions  are defined.  Function commands are nor-
                  mally looked up when the function is executed.
          -k      All  keyword  arguments  are  placed   in   the
                  environment  for a command, not just those that
                  precede the command name.
          -m      Monitor mode.  Job control  is  enabled.   This
                  flag is on by default for interactive shells on
                  systems  that  support  it  (see  JOB   CONTROL
                  above).  Background processes run in a separate
                  process group and a line 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   for   interactive
                  shells.
          -o _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 following:
                  allexport
                          Same as -a.
                  braceexpand
                          The shell performs brace expansion (see
                          Brace  Expansion above).  This is on by
                          default.
                  emacs   Use an emacs-style command line editing
                          interface.   This is enabled by default
                          when the shell is  interactive,  unless



GNU              Last change: 1993 September 16                11






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



                          the  shell  is  started  with the -nol-
                          ineediting option.
                  errexit Same as -e.
                  histexpand
                          Same as -H.
                  ignoreeof
                          The effect is as if the  shell  command
                          `IGNOREEOF=10'  had  been executed (see
                          Shell Variables above).
                  interactive-comments
                          Allow a word beginning with # to  cause
                          that  word and all remaining characters
                          on  that  line  to  be  ignored  in  an
                          interactive shell (see COMMENTS above).
                  monitor Same as -m.
                  noclobber
                          Same as -C.
                  noexec  Same as -n.
                  noglob  Same as -f.
                  nohash  Same as -d.
                  notify  Same as -b.
                  nounset Same as -u.
                  physical
                          Same as -P.
                  posix   Change the behavior of bash  where  the
                          default   operation  differs  from  the
                          Posix  1003.2  standard  to  match  the
                          standard.
                  privileged
                          Same as -p.
                  verbose Same as -v.
                  vi      Use a  vi-style  command  line  editing
                          interface.
                  xtrace  Same as -x.
                  If no _o_p_t_i_o_n-_n_a_m_e is supplied,  the  values  of
                  the current options are printed.
          -p      Turn on _p_r_i_v_i_l_e_g_e_d mode.   In  this  mode,  the
                  $ENV file is not processed, and shell functions
                  are not inherited from the  environment.   This
                  is  enabled  automatically  on  startup  if the
                  effective user (group) id is not equal  to  the
                  real  user (group) id.  Turning this option off
                  causes the effective user and group ids  to  be
                  set to the real user and group ids.
          -t      Exit after reading and executing one command.
          -u      Treat unset variables as an error when perform-
                  ing   parameter  expansion.   If  expansion  is
                  attempted  on  an  unset  variable,  the  shell
                  prints  an  error message, and, if not interac-
                  tive, exits with a non-zero status.
          -v      Print shell input lines as they are read.
          -x      After  expanding  each   _s_i_m_p_l_e-_c_o_m_m_a_n_d,   bash



GNU              Last change: 1993 September 16                12






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



                  displays the expanded value of PS4, followed by
                  the command and its expanded arguments.
          -l      Save and restore the binding of _n_a_m_e in  a  for
                  _n_a_m_e  [in  word]  command  (see  SHELL  GRAMMAR
                  above).
          -d      Disable the hashing of commands that are looked
                  up   for  execution.   Normally,  commands  are
                  remembered in a hash table, and once found,  do
                  not have to be looked up again.
          -C      The  effect  is  as  if   the   shell   command
                  `noclobber=' had been executed (see Shell Vari-
                  ables above).
          -H      Enable ! style history substitution.  This flag
                  is on by default when the shell is interactive.
          -P      If set, do not follow symbolic links when  per-
                  forming  commands  such  as cd which change the
                  current directory.  The physical  directory  is
                  used instead.
          --      If no arguments  follow  this  flag,  then  the
                  positional  parameters  are  unset.  Otherwise,
                  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 positional parame-
                  ters.  The -x and -v options  are  turned  off.
                  If there are no _a_r_gs, the positional parameters
                  remain unchanged.

          The flags are off by default  unless  otherwise  noted.
          Using  +  rather than - causes these flags to be turned
          off.  The flags can also be specified as options to  an
          invocation  of the shell.  The current set of flags may
          be found in $-.  After the option  arguments  are  pro-
          cessed,  the remaining _n _a_r_gs are treated as values for
          the positional parameters and are assigned,  in  order,
          to $1, $2, ... $_n.  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.

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

     suspend [-f]
          Suspend the execution of this shell until it receives a
          SIGCONT  signal.  The -f option says not to complain if



GNU              Last change: 1993 September 16                13






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          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 _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 _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.  Each operator and operand must be a separate
          argument.  If _f_i_l_e is of the form /dev/fd/_n, then  file
          descriptor _n is checked.
          -b _f_i_l_e
               True if _f_i_l_e exists and is block special.
          -c _f_i_l_e
               True if _f_i_l_e exists and is character special.
          -d _f_i_l_e
               True if _f_i_l_e exists and is a directory.
          -e _f_i_l_e
               True if _f_i_l_e exists.
          -f _f_i_l_e
               True if _f_i_l_e exists and is a regular file.
          -g _f_i_l_e
               True if _f_i_l_e exists and is set-group-id.
          -k _f_i_l_e
               True if _f_i_l_e has its ``sticky'' bit set.
          -L _f_i_l_e
               True if _f_i_l_e exists and is a symbolic link.
          -p _f_i_l_e
               True if _f_i_l_e exists and is a named pipe.
          -r _f_i_l_e
               True if _f_i_l_e exists and is readable.
          -s _f_i_l_e
               True if _f_i_l_e exists and has a  size  greater  than
               zero.
          -S _f_i_l_e
               True if _f_i_l_e exists and is a socket.
          -t _f_d
               True if _f_d is opened on a terminal.
          -u _f_i_l_e
               True if _f_i_l_e exists and  its  set-user-id  bit  is
               set.
          -w _f_i_l_e
               True if _f_i_l_e exists and is writable.
          -x _f_i_l_e
               True if _f_i_l_e exists and is executable.
          -O _f_i_l_e
               True if _f_i_l_e exists and is owned by the  effective
               user id.
          -G _f_i_l_e



GNU              Last change: 1993 September 16                14






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



               True if _f_i_l_e exists and is owned by the  effective
               group id.
          _f_i_l_e_1 -nt _f_i_l_e_2
               True if _f_i_l_e_1 is newer (according to  modification
               date) than _f_i_l_e_2.
          _f_i_l_e_1 -ot _f_i_l_e_2
               True if _f_i_l_e_1 is older than file2.
          _f_i_l_e_1 -ef _f_i_l_e
               True if _f_i_l_e_1 and _f_i_l_e_2 have the same  device  and
               inode numbers.
          -z _s_t_r_i_n_g
               True if the length of _s_t_r_i_n_g is zero.
          -n _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 -a _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 -o _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 OP _a_r_g_2
               OP is one of -eq, -ne,  -lt,  -le,  -gt,  or  -ge.
               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, respectively.  _A_r_g_1  and  _a_r_g_2  may  be
               positive  integers, negative integers, or the spe-
               cial expression -l _s_t_r_i_n_g, which evaluates to  the
               length of _s_t_r_i_n_g.

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

     trap [-l] [_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 reset  to  their  original
          values  (the  values  they  had  upon  entrance  to the
          shell).  If _a_r_g is  the  null  string  this  signal  is
          ignored  by  the  shell and by the commands it invokes.
          _s_i_g_s_p_e_c is either a signal name defined in  <_s_i_g_n_a_l._h>,
          or  a signal number. If _s_i_g_s_p_e_c is EXIT (0) the command
          _a_r_g is executed on exit from the shell.  With no  argu-
          ments, trap prints the list of commands associated with
          each signal number.  The -l option causes the shell  to



GNU              Last change: 1993 September 16                15






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          print  a  list  of signal names and their corresponding
          numbers.  An argument of --  disables  option  checking
          for  the  rest  of the arguments.  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 the trap name or number is invalid; otherwise
          trap returns true.

     type [-all] [-type | -path] _n_a_m_e [_n_a_m_e ...]
          With no options, indicate how each _n_a_m_e would be inter-
          preted if used as a command name.  If the -type flag is
          used, type prints a phrase which is 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 -path flag is used, type 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 -type would
          not return _f_i_l_e.  If a command is hashed, -path  prints
          the hashed value, not necessarily the file that appears
          first in PATH.  If the -all flag is used,  type  prints
          all  of  the  places  that  contain an executable named
          _n_a_m_e.  This includes aliases and functions, if and only
          if  the  -path  flag  is  not  also used.  The table of
          hashed commands is not consulted when using -all.  type
          accepts  -a,  -t,  and  -p in place of -all, -type, and
          -path, respectively.  An argument of -- disables option
          checking  for  the rest of the arguments.  type returns
          true if any of the arguments are found, false  if  none
          are found.

     ulimit [-SHacdfmstpnuv [_l_i_m_i_t]]
          Ulimit provides control over the resources available 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 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,  the  command
          applies  to  the  soft limit.  If _l_i_m_i_t is omitted, the
          current 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  is
          printed  before  the  value.   Other options are inter-
          preted 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



GNU              Last change: 1993 September 16                16






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



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

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

     umask [-S] [_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 symbolic  mode
          mask  similar to that accepted by _c_h_m_o_d(1).  If _m_o_d_e is
          omitted, or if the -S option is supplied,  the  current
          value of the mask is printed.  The -S option causes the
          mask to be printed in symbolic form; the default output
          is  an octal number.  An argument of -- disables option
          checking for the rest of  the  arguments.   The  return
          status  is 0 if the mode was successfully changed or if
          no _m_o_d_e argument was supplied, and false otherwise.

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

     unset [-fv] [_n_a_m_e ...]
          For each _n_a_m_e, remove the  corresponding  variable  or,
          given  the -f option, function.  An argument of -- dis-
          ables option checking for the rest  of  the  arguments.
          Note that PATH, IFS, PPID, PS1, PS2, UID, and EUID can-
          not be unset.  If any of RANDOM,  SECONDS,  LINENO,  or
          HISTCMD  are unset, they lose their special properties,



GNU              Last change: 1993 September 16                17






BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)



          even if they are subsequently reset.  The  exit  status
          is  true  unless  a  _n_a_m_e  does  not  exist  or is non-
          unsettable.

     wait [_n]
          Wait for the specified process and return its  termina-
          tion status.  _n may be a process ID or a job specifica-
          tion; if a job spec is given,  all  processes  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-
          existant 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              Last change: 1993 September 16                18