documentation/builtins.txt

   1
   2
   3
   4 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
   5
   6
   7
   8 NAME
   9      bash, :, ., alias, bg, bind, break, builtin, bye, case,  cd,
  10      command,  continue, declare, dirs, echo, enable, eval, exec,
  11      exit, export, fc, fg, for, getopts, hash, help, history, if,
  12      jobs,  kill,  let,  local,  logout,  popd, pushd, pwd, read,
  13      readonly, return, set, shift, source, suspend, test,  times,
  14      trap,  type,  typeset, ulimit, umask, unalias, unset, until,
  15      wait, while - bash built-in commands, see bash(1)
  16
  17 BASH BUILTIN COMMANDS
  18      : [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs]
  19           No effect; the command does  nothing  beyond  expanding
  20           _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs and performing any specified redirections.  A
  21           zero exit code is returned.
  22
  23       .  _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs]
  24      source _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs]
  25           Read and execute commands from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be in the  current
  26           shell  environment  and  return  the exit status of the
  27           last command executed from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be.  If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be  does
  28           not contain a slash, pathnames in PATH are used to find
  29           the directory containing _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be.  The  file  searched
  30           for in PATH need not be executable.  The current direc-
  31           tory is searched if no file is found in PATH.   If  any
  32           _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs  are  supplied,  they  become  the positional
  33           parameters when _\bf_\bi_\bl_\be is executed.  Otherwise the  posi-
  34           tional  parameters are unchanged.  The return status is
  35           the status of the last command exited within the script
  36           (0  if no commands are executed), and false if _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
  37           is not found.
  38
  39      alias [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be] ...]
  40           Alias with no arguments prints the list of  aliases  in
  41           the form _\bn_\ba_\bm_\be=_\bv_\ba_\bl_\bu_\be on standard output.  When arguments
  42           are supplied, an alias is defined for each  _\bn_\ba_\bm_\be  whose
  43           _\bv_\ba_\bl_\bu_\be  is  given.  A trailing space in _\bv_\ba_\bl_\bu_\be causes the
  44           next word to be checked for alias substitution when the
  45           alias  is expanded.  For each _\bn_\ba_\bm_\be in the argument list
  46           for which no _\bv_\ba_\bl_\bu_\be is supplied, the name and  value  of
  47           the alias is printed.  Alias returns true unless a _\bn_\ba_\bm_\be
  48           is given for which no alias has been defined.
  49
  50      bg [_\bj_\bo_\bb_\bs_\bp_\be_\bc]
  51           Place _\bj_\bo_\bb_\bs_\bp_\be_\bc in the background,  as  if  it  had  been
  52           started with &.  If _\bj_\bo_\bb_\bs_\bp_\be_\bc is not present, the shell's
  53           notion of the _\bc_\bu_\br_\br_\be_\bn_\bt _\bj_\bo_\bb is used.  bg _\bj_\bo_\bb_\bs_\bp_\be_\bc  returns
  54           0  unless run when job control is disabled or, when run
  55           with job control enabled, if _\bj_\bo_\bb_\bs_\bp_\be_\bc was not  found  or
  56           started without job control.
  57
  58      bind [-m _\bk_\be_\by_\bm_\ba_\bp] [-lvd] [-q _\bn_\ba_\bm_\be]
  59      bind [-m _\bk_\be_\by_\bm_\ba_\bp] -f _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
  60
  61
  62
  63 GNU              Last change: 1993 September 16                 1
  64
  65
  66
  67
  68
  69
  70 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
  71
  72
  73
  74      bind [-m _\bk_\be_\by_\bm_\ba_\bp] _\bk_\be_\by_\bs_\be_\bq:_\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn-_\bn_\ba_\bm_\be
  75           Display current readline key and function bindings,  or
  76           bind  a  key  sequence to a readline function or macro.
  77           The binding syntax accepted is  identical  to  that  of
  78           ._\bi_\bn_\bp_\bu_\bt_\br_\bc, but each binding must be passed as a separate
  79           argument;   e.g.,   '"\C-x\C-r":    re-read-init-file'.
  80           Options, if supplied, have the following meanings:
  81           -m _\bk_\be_\by_\bm_\ba_\bp
  82                Use _\bk_\be_\by_\bm_\ba_\bp as the keymap to  be  affected  by  the
  83                subsequent  bindings.  Acceptable _\bk_\be_\by_\bm_\ba_\bp names are
  84                _\be_\bm_\ba_\bc_\bs, _\be_\bm_\ba_\bc_\bs-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd, _\be_\bm_\ba_\bc_\bs-_\bm_\be_\bt_\ba, _\be_\bm_\ba_\bc_\bs-_\bc_\bt_\bl_\bx, _\bv_\bi,
  85                _\bv_\bi-_\bm_\bo_\bv_\be,   _\bv_\bi-_\bc_\bo_\bm_\bm_\ba_\bn_\bd,   and   _\bv_\bi-_\bi_\bn_\bs_\be_\br_\bt.   _\bv_\bi  is
  86                equivalent to _\bv_\bi-_\bc_\bo_\bm_\bm_\ba_\bn_\bd; _\be_\bm_\ba_\bc_\bs is  equivalent  to
  87                _\be_\bm_\ba_\bc_\bs-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd.
  88           -l   List the names of all readline functions
  89           -v   List current function names and bindings
  90           -d   Dump function names and bindings  in  such  a  way
  91                that they can be re-read
  92           -f _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
  93                Read key bindings from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
  94           -q _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn
  95                Query about which keys invoke the named _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn
  96
  97           The return value is 0 unless an unrecognized option  is
  98           given or an error occurred.
  99
 100      break [_\bn]
 101           Exit from within a for, while, or until loop.  If _\bn  is
 102           specified,  break  _\bn  levels.   _\bn must be >\b_ 1.  If _\bn is
 103           greater than the number of enclosing loops, all enclos-
 104           ing loops are exited.  The return value is 0 unless the
 105           shell is not executing a loop when break is executed.
 106
 107      builtin _\bs_\bh_\be_\bl_\bl-_\bb_\bu_\bi_\bl_\bt_\bi_\bn [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs]
 108           Execute the specified shell builtin, passing  it  _\ba_\br_\bg_\bu_\b-
 109           _\bm_\be_\bn_\bt_\bs, and return its exit status.  This is useful when
 110           you wish to define a function whose name is the same as
 111           a  shell  builtin,  but  need  the functionality of the
 112           builtin within the function itself.  The cd builtin  is
 113           commonly  redefined  this  way.   The  return status is
 114           false if _\bs_\bh_\be_\bl_\bl-_\bb_\bu_\bi_\bl_\bt_\bi_\bn is not a shell builtin command.
 115
 116      cd [_\bd_\bi_\br]
 117           Change the current directory to _\bd_\bi_\br.  The variable HOME
 118           is  the  default  _\bd_\bi_\br.  The variable CDPATH defines the
 119           search path for the directory containing _\bd_\bi_\br.  Alterna-
 120           tive  directory  names are separated by a colon (:).  A
 121           null directory name  in  CDPATH  is  the  same  as  the
 122           current  directory,  i.e., ``.''.  If _\bd_\bi_\br begins with a
 123           slash (/), then CDPATH is not used.  An argument  of  -
 124           is  equivalent to $OLDPWD.  The return value is true if
 125           the   directory   was   successfully   changed;   false
 126
 127
 128
 129 GNU              Last change: 1993 September 16                 2
 130
 131
 132
 133
 134
 135
 136 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 137
 138
 139
 140           otherwise.
 141
 142      command [-pVv] _\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\ba_\br_\bg ...]
 143           Run _\bc_\bo_\bm_\bm_\ba_\bn_\bd with  _\ba_\br_\bg_\bs  suppressing  the  normal  shell
 144           function  lookup.  Only  builtin  commands  or commands
 145           found in the PATH are executed.  If the  -p  option  is
 146           given,  the  search  for  _\bc_\bo_\bm_\bm_\ba_\bn_\bd  is performed using a
 147           default value for PATH that is guaranteed to  find  all
 148           of  the  standard  utilities.   If  either the -V or -v
 149           option  is  supplied,  a  description  of  _\bc_\bo_\bm_\bm_\ba_\bn_\bd   is
 150           printed.  The -v option causes a single word indicating
 151           the command or pathname used to invoke  _\bc_\bo_\bm_\bm_\ba_\bn_\bd  to  be
 152           printed; the -V option produces a more verbose descrip-
 153           tion.  An argument of -- disables option  checking  for
 154           the  rest  of the arguments.  If the -V or -v option is
 155           supplied, the exit status is 0 if  _\bc_\bo_\bm_\bm_\ba_\bn_\bd  was  found,
 156           and  1  if  not.   If neither option is supplied and an
 157           error occurred or _\bc_\bo_\bm_\bm_\ba_\bn_\bd cannot  be  found,  the  exit
 158           status  is 127.  Otherwise, the exit status of the com-
 159           mand builtin is the exit status of _\bc_\bo_\bm_\bm_\ba_\bn_\bd.
 160
 161      continue [_\bn]
 162           Resume the next iteration of the enclosing for,  while,
 163           or  until  loop.   If _\bn is specified, resume at the _\bnth
 164           enclosing loop.  _\bn must be >\b_ 1.  If _\bn is  greater  than
 165           the  number of enclosing loops, the last enclosing loop
 166           (the `top-level' loop) is resumed.  The return value is
 167           0  unless  the  shell is not executing a loop when con-
 168           tinue is executed.
 169
 170      declare [-frxi] [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be]]
 171      typeset [-frxi] [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be]]
 172           Declare variables and/or give them attributes.   If  no
 173           _\bn_\ba_\bm_\bes  are  given, then display the values of variables
 174           instead.  The options can be used to restrict output to
 175           variables with the specified attribute.
 176           -f   Use function names only
 177           -r   Make _\bn_\ba_\bm_\bes readonly.  These names cannot  then  be
 178                assigned  values  by  subsequent assignment state-
 179                ments.
 180           -x   Mark _\bn_\ba_\bm_\bes for export to subsequent  commands  via
 181                the environment.
 182           -i   The variable is treated as an integer;  arithmetic
 183                evaluation  (see  ARITHMETIC  EVALUATION ) is per-
 184                formed when the variable is assigned a value.
 185
 186           Using `+'  instead  of  `-'  turns  off  the  attribute
 187           instead.   When  used in a function, makes _\bn_\ba_\bm_\bes local,
 188           as with the local  command.   The  return  value  is  0
 189           unless  an illegal option is encountered, an attempt is
 190           made to define a function using "-f  foo=bar",  one  of
 191           the  _\bn_\ba_\bm_\be_\bs  is  not  a  legal  shell  variable name, an
 192
 193
 194
 195 GNU              Last change: 1993 September 16                 3
 196
 197
 198
 199
 200
 201
 202 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 203
 204
 205
 206           attempt is made to  turn  off  readonly  status  for  a
 207           readonly  variable,  or an attempt is made to display a
 208           non-existant function with -f.
 209
 210      dirs [-l] [+/-n]
 211           Display the list of currently  remembered  directories.
 212           Directories  are  added to the list with the pushd com-
 213           mand; the popd command moves back up through the list.
 214           +n   displays the _\bnth entry counting from the  left  of
 215                the  list  shown  by  dirs  when  invoked  without
 216                options, starting with zero.
 217           -n   displays the _\bnth entry counting from the right  of
 218                the  list  shown  by  dirs  when  invoked  without
 219                options, starting with zero.
 220           -l   produces a longer  listing;  the  default  listing
 221                format uses a tilde to denote the home directory.
 222
 223           The return value is 0 unless an illegal option is  sup-
 224           plied  or  _\bn  indexes  beyond  the end of the directory
 225           stack.
 226
 227      echo [-neE] [_\ba_\br_\bg ...]
 228           Output the  _\ba_\br_\bgs,  separated  by  spaces.   The  return
 229           status  is  always 0.  If -n is specified, the trailing
 230           newline is suppressed.  If  the  -e  option  is  given,
 231           interpretation of the following backslash-escaped char-
 232           acters  is  enabled.   The  -E  option   disables   the
 233           interpretation of these escape characters, even on sys-
 234           tems where they are interpreted by default.
 235           \a   alert (bell)
 236           \b   backspace
 237           \c   suppress trailing newline
 238           \f   form feed
 239           \n   new line
 240           \r   carriage return
 241           \t   horizontal tab
 242           \v   vertical tab
 243           \\   backslash
 244           \nnn the character whose ASCII code is _\bn_\bn_\bn (octal)
 245
 246      enable [-n] [-all] [_\bn_\ba_\bm_\be ...]
 247           Enable and disable builtin shell commands.  This allows
 248           the execution of a disk command which has the same name
 249           as a shell builtin without specifying a full  pathname.
 250           If  -n is used, each _\bn_\ba_\bm_\be is disabled; otherwise, _\bn_\ba_\bm_\be_\bs
 251           are enabled.  For example, to use the test binary found
 252           via the PATH instead of the shell builtin version, type
 253           ``enable -n test''.  If no arguments are given, a  list
 254           of  all  enabled shell builtins is printed.  If only -n
 255           is  supplied,  a  list  of  all  disabled  builtins  is
 256           printed.   If  only  -all is supplied, the list printed
 257           includes all builtins, with an indication of whether or
 258
 259
 260
 261 GNU              Last change: 1993 September 16                 4
 262
 263
 264
 265
 266
 267
 268 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 269
 270
 271
 272           not  each  is  enabled.  enable accepts -a as a synonym
 273           for -all.  The return value is 0 unless a _\bn_\ba_\bm_\be is not a
 274           shell builtin.
 275
 276      eval [_\ba_\br_\bg ...]
 277           The _\ba_\br_\bgs are read and concatenated together into a sin-
 278           gle command.  This command is then read and executed by
 279           the shell, and its exit status is returned as the value
 280           of  the  eval  command.   If there are no _\ba_\br_\bg_\bs, or only
 281           null arguments, eval returns true.
 282
 283      exec [[-] _\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs]]
 284           If _\bc_\bo_\bm_\bm_\ba_\bn_\bd is specified, it replaces the shell.  No new
 285           process is created.  The _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs become the arguments
 286           to _\bc_\bo_\bm_\bm_\ba_\bn_\bd.  If the first  argument  is  -,  the  shell
 287           places  a  dash  in  the  zeroth arg passed to _\bc_\bo_\bm_\bm_\ba_\bn_\bd.
 288           This is what login does.  If the file  cannot  be  exe-
 289           cuted  for  some reason, a non-interactive shell exits,
 290           unless  the   shell   variable   no_exit_on_failed_exec
 291           exists,  in which case it returns failure.  An interac-
 292           tive shell returns failure if the file cannot  be  exe-
 293           cuted.   If  _\bc_\bo_\bm_\bm_\ba_\bn_\bd is not specified, any redirections
 294           take effect in the current shell, and the return status
 295           is 0.
 296
 297      exit [_\bn]
 298           Cause the shell to exit with a status of _\bn.   If  _\bn  is
 299           omitted,  the  exit  status is that of the last command
 300           executed.  A trap on EXIT is executed before the  shell
 301           terminates.
 302
 303      export [-nf] [_\bn_\ba_\bm_\be[=_\bw_\bo_\br_\bd]] ...
 304      export -p
 305           The supplied _\bn_\ba_\bm_\be_\bs are marked for automatic  export  to
 306           the  environment of subsequently executed commands.  If
 307           the -f option is given, the _\bn_\ba_\bm_\be_\bs refer  to  functions.
 308           If no _\bn_\ba_\bm_\be_\bs are given, or if the -p option is supplied,
 309           a list of all names that are exported in this shell  is
 310           printed.   The  -n option causes the export property to
 311           be removed from the named variables.  An argument of --
 312           disables option checking for the rest of the arguments.
 313           export returns an exit status of 0  unless  an  illegal
 314           option  is encountered, one of the _\bn_\ba_\bm_\be_\bs is not a legal
 315           shell variable name, or -f is supplied with a _\bn_\ba_\bm_\be that
 316           is not a function.
 317
 318      fc [-e _\be_\bn_\ba_\bm_\be] [-nlr] [_\bf_\bi_\br_\bs_\bt] [_\bl_\ba_\bs_\bt]
 319      fc -s [_\bp_\ba_\bt=_\br_\be_\bp] [_\bc_\bm_\bd]
 320           Fix Command.  In the first form, a  range  of  commands
 321           from  _\bf_\bi_\br_\bs_\bt  to _\bl_\ba_\bs_\bt is selected from the history list.
 322           _\bF_\bi_\br_\bs_\bt and _\bl_\ba_\bs_\bt may be specified as a string (to  locate
 323           the  last  command  beginning with that string) or as a
 324
 325
 326
 327 GNU              Last change: 1993 September 16                 5
 328
 329
 330
 331
 332
 333
 334 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 335
 336
 337
 338           number (an index into the history list, where  a  nega-
 339           tive  number is used as an offset from the current com-
 340           mand number).  If _\bl_\ba_\bs_\bt is not specified it  is  set  to
 341           the  current  command  for  listing  (so that fc -l -10
 342           prints the last 10 commands) and  to  _\bf_\bi_\br_\bs_\bt  otherwise.
 343           If  _\bf_\bi_\br_\bs_\bt  is  not  specified it is set to the previous
 344           command for editing and -16 for listing.
 345
 346           The -n flag suppresses the command numbers  when  list-
 347           ing.   The  -r flag reverses the order of the commands.
 348           If the -l flag is given, the  commands  are  listed  on
 349           standard  output.  Otherwise, the editor given by _\be_\bn_\ba_\bm_\be
 350           is invoked on a file  containing  those  commands.   If
 351           _\be_\bn_\ba_\bm_\be is not given, the value of the FCEDIT variable is
 352           used, and the value of EDITOR if FCEDIT is not set.  If
 353           neither variable is set, is used.  When editing is com-
 354           plete, the edited commands are echoed and executed.
 355
 356           In the second form, _\bc_\bo_\bm_\bm_\ba_\bn_\bd is re-executed  after  each
 357           instance  of _\bp_\ba_\bt is replaced by _\br_\be_\bp.  A useful alias to
 358           use with this is ``r=fc -s'', so that typing  ``r  cc''
 359           runs  the last command beginning with ``cc'' and typing
 360           ``r'' re-executes the last command.
 361
 362           If the first form is used, the return value is 0 unless
 363           an  illegal  option  is  encountered  or  _\bf_\bi_\br_\bs_\bt or _\bl_\ba_\bs_\bt
 364           specify history lines out of range.  If the  -e  option
 365           is  supplied, the return value is the value of the last
 366           command executed or failure if an error occurs with the
 367           temporary  file  of  commands.   If  the second form is
 368           used, the return status is  that  of  the  command  re-
 369           executed,  unless  _\bc_\bm_\bd does not specify a valid history
 370           line, in which case fc returns failure.
 371
 372      fg [_\bj_\bo_\bb_\bs_\bp_\be_\bc]
 373           Place _\bj_\bo_\bb_\bs_\bp_\be_\bc  in  the  foreground,  and  make  it  the
 374           current  job.   If  _\bj_\bo_\bb_\bs_\bp_\be_\bc is not present, the shell's
 375           notion of the _\bc_\bu_\br_\br_\be_\bn_\bt _\bj_\bo_\bb is used.  The return value is
 376           that  of  the  command  placed  into the foreground, or
 377           failure if run when job control is  disabled  or,  when
 378           run  with  job  control  enabled,  if  _\bj_\bo_\bb_\bs_\bp_\be_\bc does not
 379           specify a valid job or _\bj_\bo_\bb_\bs_\bp_\be_\bc specifies a job that was
 380           started without job control.
 381
 382      getopts _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg _\bn_\ba_\bm_\be [_\ba_\br_\bg_\bs]
 383           getopts is used by shell procedures to parse positional
 384           parameters.   _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg  contains the option letters to
 385           be recognized; if a letter is followed by a colon,  the
 386           option is expected to have an argument, which should be
 387           separated from it by white  space.   Each  time  it  is
 388           invoked,  getopts  places  the next option in the shell
 389           variable _\bn_\ba_\bm_\be, initializing _\bn_\ba_\bm_\be if it does not  exist,
 390
 391
 392
 393 GNU              Last change: 1993 September 16                 6
 394
 395
 396
 397
 398
 399
 400 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 401
 402
 403
 404           and the index of the next argument to be processed into
 405           the variable OPTIND.  OPTIND is initialized to  1  each
 406           time  the  shell or a shell script is invoked.  When an
 407           option requires an argument, getopts places that  argu-
 408           ment  into  the  variable  OPTARG.   The shell does not
 409           reset OPTIND automatically; it must be  manually  reset
 410           between multiple calls to getopts within the same shell
 411           invocation if a new set of parameters is to be used.
 412
 413           getopts can report errors in two ways.   If  the  first
 414           character of _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg is a colon, _\bs_\bi_\bl_\be_\bn_\bt error report-
 415           ing is used.  In normal operation  diagnostic  messages
 416           are  printed  when  illegal  options  or missing option
 417           arguments are encountered.  If the variable  OPTERR  is
 418           set  to  0, no error message will be displayed, even if
 419           the first character of _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg is not a colon.
 420
 421           If an illegal option is seen,  getopts  places  ?  into
 422           _\bn_\ba_\bm_\be  and,  if  not silent, prints an error message and
 423           unsets OPTARG.  If getopts is silent, the option  char-
 424           acter  found is placed in OPTARG and no diagnostic mes-
 425           sage is printed.
 426
 427           If a required argument is not found, and getopts is not
 428           silent,  a  question mark (?) is placed in _\bn_\ba_\bm_\be, OPTARG
 429           is unset, and a  diagnostic  message  is  printed.   If
 430           getopts  is  silent, then a colon (:) is placed in _\bn_\ba_\bm_\be
 431           and OPTARG is set to the option character found.
 432
 433           getopts normally parses the positional parameters,  but
 434           if  more  arguments  are  given in _\ba_\br_\bg_\bs, getopts parses
 435           those instead.  getopts  returns  true  if  an  option,
 436           specified  or  unspecified, is found.  It returns false
 437           if the end  of  options  is  encountered  or  an  error
 438           occurs.
 439
 440      hash [-r] [_\bn_\ba_\bm_\be]
 441           For each _\bn_\ba_\bm_\be, the full  pathname  of  the  command  is
 442           determined  and  remembered.   The -r option causes the
 443           shell to forget all remembered locations.  If no  argu-
 444           ments  are given, information about remembered commands
 445           is printed.  An argument of -- disables option checking
 446           for  the  rest  of the arguments.  The return status is
 447           true unless a _\bn_\ba_\bm_\be is not found or an illegal option is
 448           supplied.
 449
 450      help [_\bp_\ba_\bt_\bt_\be_\br_\bn]
 451           Display helpful information about builtin commands.  If
 452           _\bp_\ba_\bt_\bt_\be_\br_\bn  is  specified, help gives detailed help on all
 453           commands matching _\bp_\ba_\bt_\bt_\be_\br_\bn;  otherwise  a  list  of  the
 454           builtins  is printed.  The return status is 0 unless no
 455           command matches _\bp_\ba_\bt_\bt_\be_\br_\bn.
 456
 457
 458
 459 GNU              Last change: 1993 September 16                 7
 460
 461
 462
 463
 464
 465
 466 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 467
 468
 469
 470      history [_\bn]
 471      history -rwan [_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be]
 472           With no options, display the command history list  with
 473           line  numbers.   Lines  listed with a * have been modi-
 474           fied.  An argument of _\bn lists only the  last  _\bn  lines.
 475           If a non-option argument is supplied, it is used as the
 476           name of the history file; if not, the value of HISTFILE
 477           is  used.   Options,  if  supplied,  have the following
 478           meanings:
 479           -a   Append the ``new'' history  lines  (history  lines
 480                entered  since  the  beginning of the current bash
 481                session) to the history file
 482           -n   Read the history lines not already read  from  the
 483                history file into the current history list.  These
 484                are lines appended to the history file  since  the
 485                beginning of the current bash session.
 486           -r   Read the contents of the history file and use them
 487                as the current history
 488           -w   Write the current history  to  the  history  file,
 489                overwriting the history file's contents.
 490
 491           The return value is  0  unless  an  illegal  option  is
 492           encountered or an error occurs while reading or writing
 493           the history file.
 494
 495      jobs [-lnp] [ _\bj_\bo_\bb_\bs_\bp_\be_\bc ... ]
 496      jobs -x _\bc_\bo_\bm_\bm_\ba_\bn_\bd [ _\ba_\br_\bg_\bs ... ]
 497           The first form lists the active jobs.   The  -l  option
 498           lists  process  IDs  in addition to the normal informa-
 499           tion; the -p option lists only the process  ID  of  the
 500           job's  process  group  leader.   The -n option displays
 501           only jobs that have changed status since last notified.
 502           If  _\bj_\bo_\bb_\bs_\bp_\be_\bc  is given, output is restricted to informa-
 503           tion about that job.  The return status is 0 unless  an
 504           illegal  option is encountered or an illegal _\bj_\bo_\bb_\bs_\bp_\be_\bc is
 505           supplied.
 506
 507           If the -x option is supplied, jobs replaces any _\bj_\bo_\bb_\bs_\bp_\be_\bc
 508           found in _\bc_\bo_\bm_\bm_\ba_\bn_\bd or _\ba_\br_\bg_\bs with the corresponding process
 509           group ID, and executes _\bc_\bo_\bm_\bm_\ba_\bn_\bd passing it _\ba_\br_\bg_\bs, return-
 510           ing its exit status.
 511
 512      kill [-s sigspec | -sigspec] [_\bp_\bi_\bd | _\bj_\bo_\bb_\bs_\bp_\be_\bc] ...
 513      kill -l [_\bs_\bi_\bg_\bn_\bu_\bm]
 514           Send the signal named by _\bs_\bi_\bg_\bs_\bp_\be_\bc to the processes named
 515           by  _\bp_\bi_\bd  or  _\bj_\bo_\bb_\bs_\bp_\be_\bc.   _\bs_\bi_\bg_\bs_\bp_\be_\bc is either a signal name
 516           such as SIGKILL or a signal number.  If  _\bs_\bi_\bg_\bs_\bp_\be_\bc  is  a
 517           signal  name,  the  name is case insensitive and may be
 518           given with or without the SIG prefix.   If  _\bs_\bi_\bg_\bs_\bp_\be_\bc  is
 519           not  present,  then SIGTERM is assumed.  An argument of
 520           -l lists the signal names.  If any arguments  are  sup-
 521           plied  when  -l  is  given,  the names of the specified
 522
 523
 524
 525 GNU              Last change: 1993 September 16                 8
 526
 527
 528
 529
 530
 531
 532 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 533
 534
 535
 536           signals are listed, and the return  status  is  0.   An
 537           argument of -- disables option checking for the rest of
 538           the arguments.  kill returns true if at least one  sig-
 539           nal  was successfully sent, or false if an error occurs
 540           or an illegal option is encountered.
 541
 542      let _\ba_\br_\bg [_\ba_\br_\bg ...]
 543           Each _\ba_\br_\bg is an arithmetic expression  to  be  evaluated
 544           (see ARITHMETIC EVALUATION).  If the last _\ba_\br_\bg evaluates
 545           to 0, let returns 1; 0 is returned otherwise.
 546
 547      local [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be] ...]
 548           For each argument, create a local variable named  _\bn_\ba_\bm_\be,
 549           and assign it _\bv_\ba_\bl_\bu_\be.  When local is used within a func-
 550           tion, it causes the variable _\bn_\ba_\bm_\be  to  have  a  visible
 551           scope  restricted  to  that  function and its children.
 552           With no operands, local writes a list  of  local  vari-
 553           ables  to  the  standard output.  It is an error to use
 554           local when not within a function.  The return status is
 555           0  unless local is used outside a function, or an ille-
 556           gal _\bn_\ba_\bm_\be is supplied.
 557
 558      logout
 559           Exit a login shell.
 560
 561      popd [+/-n]
 562           Removes entries from  the  directory  stack.   With  no
 563           arguments,  removes  the  top directory from the stack,
 564           and performs a cd to the new top directory.
 565           +n   removes the _\bnth entry counting from  the  left  of
 566                the  list  shown by dirs, starting with zero.  For
 567                example: ``popd +0'' removes the first  directory,
 568                ``popd +1'' the second.
 569           -n   removes the _\bnth entry counting from the  right  of
 570                the  list  shown by dirs, starting with zero.  For
 571                example: ``popd -0'' removes the  last  directory,
 572                ``popd -1'' the next to last.
 573
 574           If the popd command is successful, a dirs is  performed
 575           as  well,  and  the  return  status is 0.  popd returns
 576           false if an illegal option is encountered,  the  direc-
 577           tory  stack  is  empty,  a non-existent directory stack
 578           entry is specified, or the directory change fails.
 579
 580      pushd [_\bd_\bi_\br]
 581      pushd +/-n
 582           Adds a directory to the top of the directory stack,  or
 583           rotates  the stack, making the new top of the stack the
 584           current  working   directory.    With   no   arguments,
 585           exchanges the top two directories and returns 0, unless
 586           the directory stack is empty.
 587           +n   Rotates  the  stack  so  that  the  _\bnth  directory
 588
 589
 590
 591 GNU              Last change: 1993 September 16                 9
 592
 593
 594
 595
 596
 597
 598 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 599
 600
 601
 602                (counting from the left of the list shown by dirs)
 603                is at the top.
 604           -n   Rotates  the  stack  so  that  the  _\bnth  directory
 605                (counting from the right) is at the top.
 606           dir  adds _\bd_\bi_\br to the directory stack at the top, making
 607                it the new current working directory.
 608
 609           If the pushd command is successful, a dirs is performed
 610           as  well.   If  the first form is used, pushd returns 0
 611           unless the cd to _\bd_\bi_\br  fails.   With  the  second  form,
 612           pushd  returns 0 unless the directory stack is empty, a
 613           non-existant directory stack element is  specified,  or
 614           the  directory  change  to  the  specified  new current
 615           directory fails.
 616
 617      pwd  Print the absolute  pathname  of  the  current  working
 618           directory.  The path printed contains no symbolic links
 619           if the -P option to the set  builtin  command  is  set.
 620           See  also  the description of nolinks under Shell Vari-
 621           ables above).  The return status is 0 unless  an  error
 622           occurs while reading the pathname of the current direc-
 623           tory.
 624
 625      read [-r] [_\bn_\ba_\bm_\be ...]
 626           One line is read from the standard input, and the first
 627           word  is assigned to the first _\bn_\ba_\bm_\be, the second word to
 628           the  second  _\bn_\ba_\bm_\be,  and  so  on,  with  leftover  words
 629           assigned  to the last _\bn_\ba_\bm_\be.  Only the characters in IFS
 630           are recognized as word delimiters.   If  no  _\bn_\ba_\bm_\be_\bs  are
 631           supplied,  the  line  read  is assigned to the variable
 632           REPLY.  The return code is zero, unless end-of-file  is
 633           encountered.   If  the -r option is given, a backslash-
 634           newline pair is not ignored, and the backslash is  con-
 635           sidered to be part of the line.
 636
 637      readonly [-f] [_\bn_\ba_\bm_\be ...]
 638      readonly -p
 639           The given _\bn_\ba_\bm_\be_\bs are marked readonly and the  values  of
 640           these  _\bn_\ba_\bm_\be_\bs  may  not be changed by subsequent assign-
 641           ment.  If the -f  option  is  supplied,  the  functions
 642           corresponding  to the _\bn_\ba_\bm_\be_\bs are so marked.  If no argu-
 643           ments are given, or if the -p  option  is  supplied,  a
 644           list  of all readonly names is printed.  An argument of
 645           -- disables option checking for the rest of  the  argu-
 646           ments.  The return status is 0 unless an illegal option
 647           is encountered, one of the _\bn_\ba_\bm_\be_\bs is not a  legal  shell
 648           variable  name,  or  -f is supplied with a _\bn_\ba_\bm_\be that is
 649           not a function.
 650
 651      return [_\bn]
 652           Causes a function to exit with the return value  speci-
 653           fied  by _\bn.  If _\bn is omitted, the return status is that
 654
 655
 656
 657 GNU              Last change: 1993 September 16                10
 658
 659
 660
 661
 662
 663
 664 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 665
 666
 667
 668           of the last command executed in the function body.   If
 669           used  outside  a  function,  but  during execution of a
 670           script by the . (source) command, it causes  the  shell
 671           to  stop  executing  that script and return either _\bn or
 672           the exit status of the last command executed within the
 673           script  as the exit status of the script.  If used out-
 674           side a function and not during execution of a script by
 675           ., the return status is false.
 676
 677      set [--abefhkmnptuvxldCHP] [-o _\bo_\bp_\bt_\bi_\bo_\bn] [_\ba_\br_\bg ...]
 678           -a      Automatically mark variables which are modified
 679                   or  created  for  export  to the environment of
 680                   subsequent commands.
 681           -b      Cause the status of terminated background  jobs
 682                   to  be reported immediately, rather than before
 683                   the next  primary  prompt.   (Also  see  notify
 684                   under Shell Variables above).
 685           -e      Exit immediately if a _\bs_\bi_\bm_\bp_\bl_\be-_\bc_\bo_\bm_\bm_\ba_\bn_\bd (see SHELL
 686                   GRAMMAR  above)  exits  with a non-zero status.
 687                   The shell does not exit  if  the  command  that
 688                   fails  is  part of an _\bu_\bn_\bt_\bi_\bl or _\bw_\bh_\bi_\bl_\be loop, part
 689                   of an _\bi_\bf statement, part of a && or || list, or
 690                   if the command's return value is being inverted
 691                   via !.
 692           -f      Disable pathname expansion.
 693           -h      Locate and remember function commands as  func-
 694                   tions  are defined.  Function commands are nor-
 695                   mally looked up when the function is executed.
 696           -k      All  keyword  arguments  are  placed   in   the
 697                   environment  for a command, not just those that
 698                   precede the command name.
 699           -m      Monitor mode.  Job control  is  enabled.   This
 700                   flag is on by default for interactive shells on
 701                   systems  that  support  it  (see  JOB   CONTROL
 702                   above).  Background processes run in a separate
 703                   process group and a line containing their  exit
 704                   status is printed upon their completion.
 705           -n      Read commands but do not  execute  them.   This
 706                   may  be used to check a shell script for syntax
 707                   errors.   This  is  ignored   for   interactive
 708                   shells.
 709           -o _\bo_\bp_\bt_\bi_\bo_\bn-_\bn_\ba_\bm_\be
 710                   The _\bo_\bp_\bt_\bi_\bo_\bn-_\bn_\ba_\bm_\be can be one of the following:
 711                   allexport
 712                           Same as -a.
 713                   braceexpand
 714                           The shell performs brace expansion (see
 715                           Brace  Expansion above).  This is on by
 716                           default.
 717                   emacs   Use an emacs-style command line editing
 718                           interface.   This is enabled by default
 719                           when the shell is  interactive,  unless
 720
 721
 722
 723 GNU              Last change: 1993 September 16                11
 724
 725
 726
 727
 728
 729
 730 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 731
 732
 733
 734                           the  shell  is  started  with the -nol-
 735                           ineediting option.
 736                   errexit Same as -e.
 737                   histexpand
 738                           Same as -H.
 739                   ignoreeof
 740                           The effect is as if the  shell  command
 741                           `IGNOREEOF=10'  had  been executed (see
 742                           Shell Variables above).
 743                   interactive-comments
 744                           Allow a word beginning with # to  cause
 745                           that  word and all remaining characters
 746                           on  that  line  to  be  ignored  in  an
 747                           interactive shell (see COMMENTS above).
 748                   monitor Same as -m.
 749                   noclobber
 750                           Same as -C.
 751                   noexec  Same as -n.
 752                   noglob  Same as -f.
 753                   nohash  Same as -d.
 754                   notify  Same as -b.
 755                   nounset Same as -u.
 756                   physical
 757                           Same as -P.
 758                   posix   Change the behavior of bash  where  the
 759                           default   operation  differs  from  the
 760                           Posix  1003.2  standard  to  match  the
 761                           standard.
 762                   privileged
 763                           Same as -p.
 764                   verbose Same as -v.
 765                   vi      Use a  vi-style  command  line  editing
 766                           interface.
 767                   xtrace  Same as -x.
 768                   If no _\bo_\bp_\bt_\bi_\bo_\bn-_\bn_\ba_\bm_\be is supplied,  the  values  of
 769                   the current options are printed.
 770           -p      Turn on _\bp_\br_\bi_\bv_\bi_\bl_\be_\bg_\be_\bd mode.   In  this  mode,  the
 771                   $ENV file is not processed, and shell functions
 772                   are not inherited from the  environment.   This
 773                   is  enabled  automatically  on  startup  if the
 774                   effective user (group) id is not equal  to  the
 775                   real  user (group) id.  Turning this option off
 776                   causes the effective user and group ids  to  be
 777                   set to the real user and group ids.
 778           -t      Exit after reading and executing one command.
 779           -u      Treat unset variables as an error when perform-
 780                   ing   parameter  expansion.   If  expansion  is
 781                   attempted  on  an  unset  variable,  the  shell
 782                   prints  an  error message, and, if not interac-
 783                   tive, exits with a non-zero status.
 784           -v      Print shell input lines as they are read.
 785           -x      After  expanding  each   _\bs_\bi_\bm_\bp_\bl_\be-_\bc_\bo_\bm_\bm_\ba_\bn_\bd,   bash
 786
 787
 788
 789 GNU              Last change: 1993 September 16                12
 790
 791
 792
 793
 794
 795
 796 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 797
 798
 799
 800                   displays the expanded value of PS4, followed by
 801                   the command and its expanded arguments.
 802           -l      Save and restore the binding of _\bn_\ba_\bm_\be in  a  for
 803                   _\bn_\ba_\bm_\be  [in  word]  command  (see  SHELL  GRAMMAR
 804                   above).
 805           -d      Disable the hashing of commands that are looked
 806                   up   for  execution.   Normally,  commands  are
 807                   remembered in a hash table, and once found,  do
 808                   not have to be looked up again.
 809           -C      The  effect  is  as  if   the   shell   command
 810                   `noclobber=' had been executed (see Shell Vari-
 811                   ables above).
 812           -H      Enable ! style history substitution.  This flag
 813                   is on by default when the shell is interactive.
 814           -P      If set, do not follow symbolic links when  per-
 815                   forming  commands  such  as cd which change the
 816                   current directory.  The physical  directory  is
 817                   used instead.
 818           --      If no arguments  follow  this  flag,  then  the
 819                   positional  parameters  are  unset.  Otherwise,
 820                   the positional parameters are set to the  _\ba_\br_\bgs,
 821                   even if some of them begin with a -.
 822           -       Signal the end of options, cause all  remaining
 823                   _\ba_\br_\bgs  to  be assigned to the positional parame-
 824                   ters.  The -x and -v options  are  turned  off.
 825                   If there are no _\ba_\br_\bgs, the positional parameters
 826                   remain unchanged.
 827
 828           The flags are off by default  unless  otherwise  noted.
 829           Using  +  rather than - causes these flags to be turned
 830           off.  The flags can also be specified as options to  an
 831           invocation  of the shell.  The current set of flags may
 832           be found in $-.  After the option  arguments  are  pro-
 833           cessed,  the remaining _\bn _\ba_\br_\bgs are treated as values for
 834           the positional parameters and are assigned,  in  order,
 835           to $1, $2, ... $_\bn.  If no options or _\ba_\br_\bgs are supplied,
 836           all shell variables are printed.  The return status  is
 837           always true unless an illegal option is encountered.
 838
 839      shift [_\bn]
 840           The positional parameters from _\bn+1 ... are  renamed  to
 841           $1  ....  Parameters represented by the numbers $# down
 842           to $#-_\bn+1 are unset.  If _\bn  is  0,  no  parameters  are
 843           changed.   If _\bn is not given, it is assumed to be 1.  _\bn
 844           must be a non-negative number less than or equal to $#.
 845           If  _\bn is greater than $#, the positional parameters are
 846           not changed.  The return status is greater than 0 if  _\bn
 847           is greater than $# or less than 0; otherwise 0.
 848
 849      suspend [-f]
 850           Suspend the execution of this shell until it receives a
 851           SIGCONT  signal.  The -f option says not to complain if
 852
 853
 854
 855 GNU              Last change: 1993 September 16                13
 856
 857
 858
 859
 860
 861
 862 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 863
 864
 865
 866           this is a login shell; just suspend anyway.  The return
 867           status is 0 unless the shell is a login shell and -f is
 868           not supplied, or if job control is not enabled.
 869
 870      test _\be_\bx_\bp_\br
 871      [ _\be_\bx_\bp_\br ]
 872           Return a status of 0 (true) or 1 (false)  depending  on
 873           the  evaluation  of  the  conditional  expression _\be_\bx_\bp_\br.
 874           Expressions may be unary or binary.  Unary  expressions
 875           are  often used to examine the status of a file.  There
 876           are string operators and numeric  comparison  operators
 877           as  well.  Each operator and operand must be a separate
 878           argument.  If _\bf_\bi_\bl_\be is of the form /dev/fd/_\bn, then  file
 879           descriptor _\bn is checked.
 880           -b _\bf_\bi_\bl_\be
 881                True if _\bf_\bi_\bl_\be exists and is block special.
 882           -c _\bf_\bi_\bl_\be
 883                True if _\bf_\bi_\bl_\be exists and is character special.
 884           -d _\bf_\bi_\bl_\be
 885                True if _\bf_\bi_\bl_\be exists and is a directory.
 886           -e _\bf_\bi_\bl_\be
 887                True if _\bf_\bi_\bl_\be exists.
 888           -f _\bf_\bi_\bl_\be
 889                True if _\bf_\bi_\bl_\be exists and is a regular file.
 890           -g _\bf_\bi_\bl_\be
 891                True if _\bf_\bi_\bl_\be exists and is set-group-id.
 892           -k _\bf_\bi_\bl_\be
 893                True if _\bf_\bi_\bl_\be has its ``sticky'' bit set.
 894           -L _\bf_\bi_\bl_\be
 895                True if _\bf_\bi_\bl_\be exists and is a symbolic link.
 896           -p _\bf_\bi_\bl_\be
 897                True if _\bf_\bi_\bl_\be exists and is a named pipe.
 898           -r _\bf_\bi_\bl_\be
 899                True if _\bf_\bi_\bl_\be exists and is readable.
 900           -s _\bf_\bi_\bl_\be
 901                True if _\bf_\bi_\bl_\be exists and has a  size  greater  than
 902                zero.
 903           -S _\bf_\bi_\bl_\be
 904                True if _\bf_\bi_\bl_\be exists and is a socket.
 905           -t _\bf_\bd
 906                True if _\bf_\bd is opened on a terminal.
 907           -u _\bf_\bi_\bl_\be
 908                True if _\bf_\bi_\bl_\be exists and  its  set-user-id  bit  is
 909                set.
 910           -w _\bf_\bi_\bl_\be
 911                True if _\bf_\bi_\bl_\be exists and is writable.
 912           -x _\bf_\bi_\bl_\be
 913                True if _\bf_\bi_\bl_\be exists and is executable.
 914           -O _\bf_\bi_\bl_\be
 915                True if _\bf_\bi_\bl_\be exists and is owned by the  effective
 916                user id.
 917           -G _\bf_\bi_\bl_\be
 918
 919
 920
 921 GNU              Last change: 1993 September 16                14
 922
 923
 924
 925
 926
 927
 928 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 929
 930
 931
 932                True if _\bf_\bi_\bl_\be exists and is owned by the  effective
 933                group id.
 934           _\bf_\bi_\bl_\be_\b1 -nt _\bf_\bi_\bl_\be_\b2
 935                True if _\bf_\bi_\bl_\be_\b1 is newer (according to  modification
 936                date) than _\bf_\bi_\bl_\be_\b2.
 937           _\bf_\bi_\bl_\be_\b1 -ot _\bf_\bi_\bl_\be_\b2
 938                True if _\bf_\bi_\bl_\be_\b1 is older than file2.
 939           _\bf_\bi_\bl_\be_\b1 -ef _\bf_\bi_\bl_\be
 940                True if _\bf_\bi_\bl_\be_\b1 and _\bf_\bi_\bl_\be_\b2 have the same  device  and
 941                inode numbers.
 942           -z _\bs_\bt_\br_\bi_\bn_\bg
 943                True if the length of _\bs_\bt_\br_\bi_\bn_\bg is zero.
 944           -n _\bs_\bt_\br_\bi_\bn_\bg
 945           _\bs_\bt_\br_\bi_\bn_\bg
 946                True if the length of _\bs_\bt_\br_\bi_\bn_\bg is non-zero.
 947           _\bs_\bt_\br_\bi_\bn_\bg_\b1 = _\bs_\bt_\br_\bi_\bn_\bg_\b2
 948                True if the strings are equal.
 949           _\bs_\bt_\br_\bi_\bn_\bg_\b1 != _\bs_\bt_\br_\bi_\bn_\bg_\b2
 950                True if the strings are not equal.
 951           ! _\be_\bx_\bp_\br
 952                True if _\be_\bx_\bp_\br is false.
 953           _\be_\bx_\bp_\br_\b1 -a _\be_\bx_\bp_\br_\b2
 954                True if both _\be_\bx_\bp_\br_\b1 AND _\be_\bx_\bp_\br_\b2 are true.
 955           _\be_\bx_\bp_\br_\b1 -o _\be_\bx_\bp_\br_\b2
 956                True if either _\be_\bx_\bp_\br_\b1 OR _\be_\bx_\bp_\br_\b2 is true.
 957           _\ba_\br_\bg_\b1 OP _\ba_\br_\bg_\b2
 958                OP is one of -eq, -ne,  -lt,  -le,  -gt,  or  -ge.
 959                These  arithmetic  binary operators return true if
 960                _\ba_\br_\bg_\b1 is equal,  not-equal,  less-than,  less-than-
 961                or-equal,  greater-than,  or greater-than-or-equal
 962                than _\ba_\br_\bg_\b2, respectively.  _\bA_\br_\bg_\b1  and  _\ba_\br_\bg_\b2  may  be
 963                positive  integers, negative integers, or the spe-
 964                cial expression -l _\bs_\bt_\br_\bi_\bn_\bg, which evaluates to  the
 965                length of _\bs_\bt_\br_\bi_\bn_\bg.
 966
 967      times
 968           Print the accumulated user and  system  times  for  the
 969           shell and for processes run from the shell.  The return
 970           status is 0.
 971
 972      trap [-l] [_\ba_\br_\bg] [_\bs_\bi_\bg_\bs_\bp_\be_\bc]
 973           The command _\ba_\br_\bg is to be read  and  executed  when  the
 974           shell  receives signal(s) _\bs_\bi_\bg_\bs_\bp_\be_\bc.  If _\ba_\br_\bg is absent or
 975           -, all specified signals are reset  to  their  original
 976           values  (the  values  they  had  upon  entrance  to the
 977           shell).  If _\ba_\br_\bg is  the  null  string  this  signal  is
 978           ignored  by  the  shell and by the commands it invokes.
 979           _\bs_\bi_\bg_\bs_\bp_\be_\bc is either a signal name defined in  <_\bs_\bi_\bg_\bn_\ba_\bl._\bh>,
 980           or  a signal number. If _\bs_\bi_\bg_\bs_\bp_\be_\bc is EXIT (0) the command
 981           _\ba_\br_\bg is executed on exit from the shell.  With no  argu-
 982           ments, trap prints the list of commands associated with
 983           each signal number.  The -l option causes the shell  to
 984
 985
 986
 987 GNU              Last change: 1993 September 16                15
 988
 989
 990
 991
 992
 993
 994 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
 995
 996
 997
 998           print  a  list  of signal names and their corresponding
 999           numbers.  An argument of --  disables  option  checking
1000           for  the  rest  of the arguments.  Signals ignored upon
1001           entry to the shell cannot be trapped or reset.  Trapped
1002           signals  are  reset to their original values in a child
1003           process when it is created.  The return status is false
1004           if either the trap name or number is invalid; otherwise
1005           trap returns true.
1006
1007      type [-all] [-type | -path] _\bn_\ba_\bm_\be [_\bn_\ba_\bm_\be ...]
1008           With no options, indicate how each _\bn_\ba_\bm_\be would be inter-
1009           preted if used as a command name.  If the -type flag is
1010           used, type prints a phrase which is one of _\ba_\bl_\bi_\ba_\bs,  _\bk_\be_\by_\b-
1011           _\bw_\bo_\br_\bd,  _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn,  _\bb_\bu_\bi_\bl_\bt_\bi_\bn, or _\bf_\bi_\bl_\be if _\bn_\ba_\bm_\be is an alias,
1012           shell reserved word, function, builtin, or  disk  file,
1013           respectively. If the name is not found, then nothing is
1014           printed, and an exit status of false is  returned.   If
1015           the -path flag is used, type either returns the name of
1016           the disk file that  would  be  executed  if  _\bn_\ba_\bm_\be  were
1017           specified  as a command name, or nothing if -type would
1018           not return _\bf_\bi_\bl_\be.  If a command is hashed, -path  prints
1019           the hashed value, not necessarily the file that appears
1020           first in PATH.  If the -all flag is used,  type  prints
1021           all  of  the  places  that  contain an executable named
1022           _\bn_\ba_\bm_\be.  This includes aliases and functions, if and only
1023           if  the  -path  flag  is  not  also used.  The table of
1024           hashed commands is not consulted when using -all.  type
1025           accepts  -a,  -t,  and  -p in place of -all, -type, and
1026           -path, respectively.  An argument of -- disables option
1027           checking  for  the rest of the arguments.  type returns
1028           true if any of the arguments are found, false  if  none
1029           are found.
1030
1031      ulimit [-SHacdfmstpnuv [_\bl_\bi_\bm_\bi_\bt]]
1032           Ulimit provides control over the resources available to
1033           the  shell  and  to processes started by it, on systems
1034           that allow such control.  The value of _\bl_\bi_\bm_\bi_\bt can  be  a
1035           number  in  the unit specified for the resource, or the
1036           value unlimited.  The H and S options specify that  the
1037           hard  or  soft  limit is set for the given resource.  A
1038           hard limit cannot be increased once it is set;  a  soft
1039           limit  may  be  increased  up  to the value of the hard
1040           limit.  If neither H nor S is  specified,  the  command
1041           applies  to  the  soft limit.  If _\bl_\bi_\bm_\bi_\bt is omitted, the
1042           current value of the soft  limit  of  the  resource  is
1043           printed,  unless the H option is given.  When more than
1044           one resource is specified, the limit name and  unit  is
1045           printed  before  the  value.   Other options are inter-
1046           preted as follows:
1047           -a   all current limits are reported
1048           -c   the maximum size of core files created
1049           -d   the maximum size of a process's data segment
1050
1051
1052
1053 GNU              Last change: 1993 September 16                16
1054
1055
1056
1057
1058
1059
1060 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
1061
1062
1063
1064           -f   the maximum size of files created by the shell
1065           -m   the maximum resident set size
1066           -s   the maximum stack size
1067           -t   the maximum amount of cpu time in seconds
1068           -p   the pipe size in 512-byte blocks (this may not  be
1069                set)
1070           -n   the maximum number of open file descriptors  (most
1071                systems  do  not  allow this value to be set, only
1072                displayed)
1073           -u   the maximum number of  processes  available  to  a
1074                single user
1075           -v   The maximum amount of virtual memory available  to
1076                the shell
1077
1078           An argument of -- disables option checking for the rest
1079           of  the  arguments.   If  _\bl_\bi_\bm_\bi_\bt is given, it is the new
1080           value of the  specified  resource  (the  -a  option  is
1081           display  only).   If  no  option  is  given, then -f is
1082           assumed.  Values are in  1024-byte  increments,  except
1083           for  -t,  which is in seconds, -p, which is in units of
1084           512-byte blocks, and -n  and  -u,  which  are  unscaled
1085           values.   The  return  status  is  0  unless an illegal
1086           option is encountered,  a  non-numeric  argument  other
1087           than unlimited is supplied as _\bl_\bi_\bm_\bi_\bt, or an error occurs
1088           while setting a new limit.
1089
1090      umask [-S] [_\bm_\bo_\bd_\be]
1091           The user file-creation mask is set to  _\bm_\bo_\bd_\be.   If  _\bm_\bo_\bd_\be
1092           begins  with  a  digit,  it  is interpreted as an octal
1093           number; otherwise it is interpreted as a symbolic  mode
1094           mask  similar to that accepted by _\bc_\bh_\bm_\bo_\bd(1).  If _\bm_\bo_\bd_\be is
1095           omitted, or if the -S option is supplied,  the  current
1096           value of the mask is printed.  The -S option causes the
1097           mask to be printed in symbolic form; the default output
1098           is  an octal number.  An argument of -- disables option
1099           checking for the rest of  the  arguments.   The  return
1100           status  is 0 if the mode was successfully changed or if
1101           no _\bm_\bo_\bd_\be argument was supplied, and false otherwise.
1102
1103      unalias [-a] [_\bn_\ba_\bm_\be ...]
1104           Remove _\bn_\ba_\bm_\bes from the list of defined aliases.   If  -a
1105           is  supplied,  all  alias definitions are removed.  The
1106           return value is true unless a supplied _\bn_\ba_\bm_\be  is  not  a
1107           defined alias.
1108
1109      unset [-fv] [_\bn_\ba_\bm_\be ...]
1110           For each _\bn_\ba_\bm_\be, remove the  corresponding  variable  or,
1111           given  the -f option, function.  An argument of -- dis-
1112           ables option checking for the rest  of  the  arguments.
1113           Note that PATH, IFS, PPID, PS1, PS2, UID, and EUID can-
1114           not be unset.  If any of RANDOM,  SECONDS,  LINENO,  or
1115           HISTCMD  are unset, they lose their special properties,
1116
1117
1118
1119 GNU              Last change: 1993 September 16                17
1120
1121
1122
1123
1124
1125
1126 BASH_BUILTINS(1)         USER COMMANDS           BASH_BUILTINS(1)
1127
1128
1129
1130           even if they are subsequently reset.  The  exit  status
1131           is  true  unless  a  _\bn_\ba_\bm_\be  does  not  exist  or is non-
1132           unsettable.
1133
1134      wait [_\bn]
1135           Wait for the specified process and return its  termina-
1136           tion status.  _\bn may be a process ID or a job specifica-
1137           tion; if a job spec is given,  all  processes  in  that
1138           job's  pipeline are waited for.  If _\bn is not given, all
1139           currently active child processes are  waited  for,  and
1140           the  return  status  is  zero.   If  _\bn specifies a non-
1141           existant process or job,  the  return  status  is  127.
1142           Otherwise,  the return status is the exit status of the
1143           last process or job waited for.
1144
1145 SEE ALSO
1146      bash(1), sh(1)
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185 GNU              Last change: 1993 September 16                18
1186
1187
1188