1BASH_BUILTINS(1)            General Commands Manual           BASH_BUILTINS(1)
2
3
4

NAME

6       bash,  :,  .,  [, alias, bg, bind, break, builtin, caller, cd, command,
7       compgen, complete, compopt,  continue,  declare,  dirs,  disown,  echo,
8       enable,  eval,  exec, exit, export, false, fc, fg, getopts, hash, help,
9       history, jobs, kill, let, local, logout, mapfile, popd, printf,  pushd,
10       pwd,  read, readonly, return, set, shift, shopt, source, suspend, test,
11       times, trap, true, type, typeset, ulimit, umask, unalias, unset, wait -
12       bash built-in commands, see bash(1)
13

BASH BUILTIN COMMANDS

15       Unless otherwise noted, each builtin command documented in this section
16       as accepting options preceded by - accepts -- to signify the end of the
17       options.  The :, true, false, and test/[ builtins do not accept options
18       and do not treat -- specially.  The exit, logout, return,  break,  con‐
19       tinue,  let,  and shift builtins accept and process arguments beginning
20       with - without requiring --.  Other builtins that accept arguments  but
21       are  not  specified  as accepting options interpret arguments beginning
22       with - as invalid options and require -- to  prevent  this  interpreta‐
23       tion.
24       : [arguments]
25              No  effect;  the command does nothing beyond expanding arguments
26              and performing any specified redirections.  The return status is
27              zero.
28
29        .  filename [arguments]
30       source filename [arguments]
31              Read  and  execute  commands  from filename in the current shell
32              environment and return the exit status of the last command  exe‐
33              cuted  from  filename.   If  filename  does not contain a slash,
34              filenames in PATH are used  to  find  the  directory  containing
35              filename.  The file searched for in PATH need not be executable.
36              When bash is  not  in  posix  mode,  the  current  directory  is
37              searched  if no file is found in PATH.  If the sourcepath option
38              to the shopt builtin command is turned  off,  the  PATH  is  not
39              searched.   If any arguments are supplied, they become the posi‐
40              tional parameters when  filename  is  executed.   Otherwise  the
41              positional  parameters  are  unchanged.   If  the  -T  option is
42              enabled, source inherits any trap on DEBUG; if it  is  not,  any
43              DEBUG  trap  string  is  saved  and  restored around the call to
44              source, and source unsets the DEBUG trap while it executes.   If
45              -T  is not set, and the sourced file changes the DEBUG trap, the
46              new value is retained when source completes.  The return  status
47              is the status of the last command exited within the script (0 if
48              no commands are executed), and false if filename is not found or
49              cannot be read.
50
51       alias [-p] [name[=value] ...]
52              Alias with no arguments or with the -p option prints the list of
53              aliases in the form alias name=value on standard  output.   When
54              arguments  are supplied, an alias is defined for each name whose
55              value is given.  A trailing space in value causes the next  word
56              to be checked for alias substitution when the alias is expanded.
57              For each name in the argument list for which no  value  is  sup‐
58              plied,  the  name  and  value  of  the  alias is printed.  Alias
59              returns true unless a name is given for which no alias has  been
60              defined.
61
62       bg [jobspec ...]
63              Resume  each  suspended  job jobspec in the background, as if it
64              had been started with &.  If jobspec is not present, the shell's
65              notion  of the current job is used.  bg jobspec returns 0 unless
66              run when job control is disabled or, when run with  job  control
67              enabled,  any  specified  jobspec  was  not found or was started
68              without job control.
69
70       bind [-m keymap] [-lpsvPSVX]
71       bind [-m keymap] [-q function] [-u function] [-r keyseq]
72       bind [-m keymap] -f filename
73       bind [-m keymap] -x keyseq:shell-command
74       bind [-m keymap] keyseq:function-name
75       bind [-m keymap] keyseq:readline-command
76              Display current readline key and function bindings, bind  a  key
77              sequence  to  a  readline  function  or macro, or set a readline
78              variable.  Each non-option argument is a  command  as  it  would
79              appear  in  .inputrc, but each binding or command must be passed
80              as a separate argument; e.g.,  '"\C-x\C-r":  re-read-init-file'.
81              Options, if supplied, have the following meanings:
82              -m keymap
83                     Use keymap as the keymap to be affected by the subsequent
84                     bindings.  Acceptable keymap names are emacs, emacs-stan‐
85                     dard,  emacs-meta,  emacs-ctlx,  vi, vi-move, vi-command,
86                     and vi-insert.  vi is equivalent to  vi-command  (vi-move
87                     is  also  a  synonym); emacs is equivalent to emacs-stan‐
88                     dard.
89              -l     List the names of all readline functions.
90              -p     Display readline function names and bindings  in  such  a
91                     way that they can be re-read.
92              -P     List current readline function names and bindings.
93              -s     Display  readline  key  sequences bound to macros and the
94                     strings they output in such a way that they  can  be  re-
95                     read.
96              -S     Display  readline  key  sequences bound to macros and the
97                     strings they output.
98              -v     Display readline variable names and values in such a  way
99                     that they can be re-read.
100              -V     List current readline variable names and values.
101              -f filename
102                     Read key bindings from filename.
103              -q function
104                     Query about which keys invoke the named function.
105              -u function
106                     Unbind all keys bound to the named function.
107              -r keyseq
108                     Remove any current binding for keyseq.
109              -x keyseq:shell-command
110                     Cause  shell-command  to  be  executed whenever keyseq is
111                     entered.  When shell-command is executed, the shell  sets
112                     the  READLINE_LINE  variable to the contents of the read‐
113                     line line buffer and the READLINE_POINT variable  to  the
114                     current location of the insertion point.  If the executed
115                     command changes  the  value  of  READLINE_LINE  or  READ‐
116                     LINE_POINT,  those  new  values  will be reflected in the
117                     editing state.
118              -X     List all key sequences bound to shell  commands  and  the
119                     associated  commands  in  a  format that can be reused as
120                     input.
121
122              The return value is 0 unless an unrecognized option is given  or
123              an error occurred.
124
125       break [n]
126              Exit  from  within a for, while, until, or select loop.  If n is
127              specified, break n levels.  n must be ≥ 1.  If n is greater than
128              the  number  of enclosing loops, all enclosing loops are exited.
129              The return value is 0 unless n is not greater than or  equal  to
130              1.
131
132       builtin shell-builtin [arguments]
133              Execute  the  specified shell builtin, passing it arguments, and
134              return its exit status.  This is useful when defining a function
135              whose  name  is the same as a shell builtin, retaining the func‐
136              tionality of the builtin within the function.  The cd builtin is
137              commonly  redefined  this  way.   The  return status is false if
138              shell-builtin is not a shell builtin command.
139
140       caller [expr]
141              Returns the context of any active subroutine call (a shell func‐
142              tion or a script executed with the . or source builtins).  With‐
143              out expr, caller displays the line number and source filename of
144              the  current subroutine call.  If a non-negative integer is sup‐
145              plied as expr, caller displays the line number, subroutine name,
146              and  source  file  corresponding to that position in the current
147              execution call stack.  This extra information may be  used,  for
148              example,  to print a stack trace.  The current frame is frame 0.
149              The return value is 0 unless the shell is not executing  a  sub‐
150              routine  call or expr does not correspond to a valid position in
151              the call stack.
152
153       cd [-L|[-P [-e]] [-@]] [dir]
154              Change the current directory to dir.  if dir  is  not  supplied,
155              the  value of the HOME shell variable is the default.  Any addi‐
156              tional arguments following dir are ignored.  The variable CDPATH
157              defines  the  search path for the directory containing dir: each
158              directory name in  CDPATH  is  searched  for  dir.   Alternative
159              directory  names in CDPATH are separated by a colon (:).  A null
160              directory name in CDPATH is the same as the  current  directory,
161              i.e., ``.''.  If dir begins with a slash (/), then CDPATH is not
162              used.  The -P option causes cd to  use  the  physical  directory
163              structure  by  resolving symbolic links while traversing dir and
164              before processing instances of .. in dir (see also the -P option
165              to the set builtin command); the -L option forces symbolic links
166              to be followed by resolving the link after processing  instances
167              of .. in dir.  If .. appears in dir, it is processed by removing
168              the immediately previous pathname component from dir, back to  a
169              slash  or  the  beginning  of dir.  If the -e option is supplied
170              with -P, and the current working directory  cannot  be  success‐
171              fully  determined  after  a successful directory change, cd will
172              return an unsuccessful status.  On systems that support it,  the
173              -@  option  presents  the  extended attributes associated with a
174              file as a directory.  An argument of - is converted  to  $OLDPWD
175              before the directory change is attempted.  If a non-empty direc‐
176              tory name from CDPATH is used, or if - is  the  first  argument,
177              and the directory change is successful, the absolute pathname of
178              the new working directory is written  to  the  standard  output.
179              The  return  value  is  true  if  the directory was successfully
180              changed; false otherwise.
181
182       command [-pVv] command [arg ...]
183              Run command with args  suppressing  the  normal  shell  function
184              lookup.  Only builtin commands or commands found in the PATH are
185              executed.  If the -p option is given, the search for command  is
186              performed  using  a default value for PATH that is guaranteed to
187              find all of the standard utilities.  If  either  the  -V  or  -v
188              option is supplied, a description of command is printed.  The -v
189              option causes a single word indicating the command  or  filename
190              used to invoke command to be displayed; the -V option produces a
191              more verbose description.  If the -V or -v option  is  supplied,
192              the  exit  status  is  0 if command was found, and 1 if not.  If
193              neither option is supplied and an error occurred or command can‐
194              not  be found, the exit status is 127.  Otherwise, the exit sta‐
195              tus of the command builtin is the exit status of command.
196
197       compgen [option] [word]
198              Generate possible completion matches for word according  to  the
199              options,  which  may  be  any  option  accepted  by the complete
200              builtin with the exception of -p and -r, and write  the  matches
201              to  the  standard  output.  When using the -F or -C options, the
202              various shell  variables  set  by  the  programmable  completion
203              facilities, while available, will not have useful values.
204
205              The matches will be generated in the same way as if the program‐
206              mable completion code had generated them directly from a comple‐
207              tion  specification  with the same flags.  If word is specified,
208              only those completions matching word will be displayed.
209
210              The return value is true unless an invalid option  is  supplied,
211              or no matches were generated.
212
213       complete  [-abcdefgjksuv] [-o comp-option] [-DEI] [-A action] [-G glob‐
214       pat] [-W wordlist] [-F function] [-C command]
215              [-X filterpat] [-P prefix] [-S suffix] name [name ...]
216       complete -pr [-DEI] [name ...]
217              Specify how arguments to each name should be completed.  If  the
218              -p  option  is supplied, or if no options are supplied, existing
219              completion specifications are printed in a way that allows  them
220              to be reused as input.  The -r option removes a completion spec‐
221              ification for each name, or, if no names are supplied, all  com‐
222              pletion specifications.  The -D option indicates that other sup‐
223              plied options and actions should apply to the  ``default''  com‐
224              mand  completion; that is, completion attempted on a command for
225              which no completion has previously been defined.  The -E  option
226              indicates  that  other supplied options and actions should apply
227              to ``empty'' command completion; that is,  completion  attempted
228              on  a  blank  line.  The -I option indicates that other supplied
229              options and actions should apply to  completion  on  the  inital
230              non-assignment  word  on  the line, or after a command delimiter
231              such as ; or |, which is usually command  name  completion.   If
232              multiple  options  are  supplied, the -D option takes precedence
233              over -E, and both take precedence over -I.  If any of -D, -E, or
234              -I  are  supplied,  any  other name arguments are ignored; these
235              completions only apply to the case specified by the option.
236
237              The process of applying  these  completion  specifications  when
238              word  completion  is attempted is described above under Program‐
239              mable Completion.
240
241              Other options, if specified, have the following  meanings.   The
242              arguments  to the -G, -W, and -X options (and, if necessary, the
243              -P and -S options) should be quoted to protect them from  expan‐
244              sion before the complete builtin is invoked.
245              -o comp-option
246                      The  comp-option  controls  several aspects of the comp‐
247                      spec's behavior beyond the simple generation of  comple‐
248                      tions.  comp-option may be one of:
249                      bashdefault
250                              Perform the rest of the default bash completions
251                              if the compspec generates no matches.
252                      default Use readline's default  filename  completion  if
253                              the compspec generates no matches.
254                      dirnames
255                              Perform  directory  name completion if the comp‐
256                              spec generates no matches.
257                      filenames
258                              Tell readline that the compspec generates  file‐
259                              names,  so  it can perform any filename-specific
260                              processing (like adding  a  slash  to  directory
261                              names,  quoting special characters, or suppress‐
262                              ing trailing spaces).  Intended to be used  with
263                              shell functions.
264                      noquote Tell  readline  not to quote the completed words
265                              if they are filenames (quoting filenames is  the
266                              default).
267                      nosort  Tell  readline  not to sort the list of possible
268                              completions alphabetically.
269                      nospace Tell  readline  not  to  append  a  space   (the
270                              default)  to  words  completed at the end of the
271                              line.
272                      plusdirs
273                              After any matches defined by  the  compspec  are
274                              generated,    directory   name   completion   is
275                              attempted and  any  matches  are  added  to  the
276                              results of the other actions.
277              -A action
278                      The  action  may  be  one of the following to generate a
279                      list of possible completions:
280                      alias   Alias names.  May also be specified as -a.
281                      arrayvar
282                              Array variable names.
283                      binding Readline key binding names.
284                      builtin Names of shell builtin commands.   May  also  be
285                              specified as -b.
286                      command Command names.  May also be specified as -c.
287                      directory
288                              Directory names.  May also be specified as -d.
289                      disabled
290                              Names of disabled shell builtins.
291                      enabled Names of enabled shell builtins.
292                      export  Names  of exported shell variables.  May also be
293                              specified as -e.
294                      file    File names.  May also be specified as -f.
295                      function
296                              Names of shell functions.
297                      group   Group names.  May also be specified as -g.
298                      helptopic
299                              Help topics as accepted by the help builtin.
300                      hostname
301                              Hostnames, as taken from the file  specified  by
302                              the HOSTFILE shell variable.
303                      job     Job  names,  if job control is active.  May also
304                              be specified as -j.
305                      keyword Shell reserved words.  May also be specified  as
306                              -k.
307                      running Names of running jobs, if job control is active.
308                      service Service names.  May also be specified as -s.
309                      setopt  Valid  arguments  for  the  -o option to the set
310                              builtin.
311                      shopt   Shell option names  as  accepted  by  the  shopt
312                              builtin.
313                      signal  Signal names.
314                      stopped Names of stopped jobs, if job control is active.
315                      user    User names.  May also be specified as -u.
316                      variable
317                              Names of all shell variables.  May also be spec‐
318                              ified as -v.
319              -C command
320                      command is executed in a subshell environment,  and  its
321                      output is used as the possible completions.
322              -F function
323                      The  shell  function function is executed in the current
324                      shell environment.  When the function is  executed,  the
325                      first  argument  ($1)  is  the name of the command whose
326                      arguments are being completed, the second argument  ($2)
327                      is the word being completed, and the third argument ($3)
328                      is the word preceding the word being  completed  on  the
329                      current  command  line.   When it finishes, the possible
330                      completions are retrieved from the value of the  COMPRE‐
331                      PLY array variable.
332              -G globpat
333                      The  pathname  expansion  pattern globpat is expanded to
334                      generate the possible completions.
335              -P prefix
336                      prefix is added at the beginning of each  possible  com‐
337                      pletion after all other options have been applied.
338              -S suffix
339                      suffix is appended to each possible completion after all
340                      other options have been applied.
341              -W wordlist
342                      The wordlist is split using the characters  in  the  IFS
343                      special  variable as delimiters, and each resultant word
344                      is expanded.  Shell quoting is honored within  wordlist,
345                      in order to provide a mechanism for the words to contain
346                      shell metacharacters or characters in the value of  IFS.
347                      The  possible  completions are the members of the resul‐
348                      tant list which match the word being completed.
349              -X filterpat
350                      filterpat is a pattern as used for  pathname  expansion.
351                      It is applied to the list of possible completions gener‐
352                      ated by the preceding options and  arguments,  and  each
353                      completion  matching filterpat is removed from the list.
354                      A leading ! in filterpat negates the  pattern;  in  this
355                      case, any completion not matching filterpat is removed.
356
357              The  return  value is true unless an invalid option is supplied,
358              an option other than -p or -r is supplied without a  name  argu‐
359              ment,  an  attempt  is made to remove a completion specification
360              for a name for which no specification exists, or an error occurs
361              adding a completion specification.
362
363       compopt [-o option] [-DEI] [+o option] [name]
364              Modify  completion  options  for  each  name  according  to  the
365              options, or for the currently-executing completion if  no  names
366              are  supplied.   If no options are given, display the completion
367              options for each name or the current completion.   The  possible
368              values  of  option  are  those  valid  for  the complete builtin
369              described above.  The -D option indicates  that  other  supplied
370              options should apply to the ``default'' command completion; that
371              is, completion attempted on a command for  which  no  completion
372              has previously been defined.  The -E option indicates that other
373              supplied options should apply to ``empty''  command  completion;
374              that  is,  completion  attempted on a blank line.  The -I option
375              indicates that other supplied options should apply to completion
376              on  the  inital non-assignment word on the line, or after a com‐
377              mand delimiter such as ; or |, which  is  usually  command  name
378              completion.
379
380              The  return  value is true unless an invalid option is supplied,
381              an attempt is made to modify the options for a name for which no
382              completion specification exists, or an output error occurs.
383
384       continue [n]
385              Resume the next iteration of the enclosing for, while, until, or
386              select loop.  If n is specified, resume  at  the  nth  enclosing
387              loop.   n  must  be  ≥  1.   If  n is greater than the number of
388              enclosing loops, the  last  enclosing  loop  (the  ``top-level''
389              loop) is resumed.  The return value is 0 unless n is not greater
390              than or equal to 1.
391
392       declare [-aAfFgilnrtux] [-p] [name[=value] ...]
393       typeset [-aAfFgilnrtux] [-p] [name[=value] ...]
394              Declare variables and/or give them attributes.  If no names  are
395              given  then display the values of variables.  The -p option will
396              display the attributes and values of each name.  When -p is used
397              with  name  arguments, additional options, other than -f and -F,
398              are ignored.  When -p is supplied  without  name  arguments,  it
399              will  display  the attributes and values of all variables having
400              the attributes specified by the additional options.  If no other
401              options   are   supplied  with  -p,  declare  will  display  the
402              attributes and values of all shell  variables.   The  -f  option
403              will  restrict  the  display  to shell functions.  The -F option
404              inhibits the display of function definitions; only the  function
405              name  and  attributes are printed.  If the extdebug shell option
406              is enabled using shopt, the source file  name  and  line  number
407              where each name is defined are displayed as well.  The -F option
408              implies -f.  The -g option forces variables  to  be  created  or
409              modified at the global scope, even when declare is executed in a
410              shell function.  It is ignored in all other cases.  The  follow‐
411              ing options can be used to restrict output to variables with the
412              specified attribute or to give variables attributes:
413              -a     Each name  is  an  indexed  array  variable  (see  Arrays
414                     above).
415              -A     Each  name  is  an associative array variable (see Arrays
416                     above).
417              -f     Use function names only.
418              -i     The variable is treated as an integer; arithmetic evalua‐
419                     tion  (see ARITHMETIC EVALUATION above) is performed when
420                     the variable is assigned a value.
421              -l     When the variable is assigned  a  value,  all  upper-case
422                     characters  are  converted to lower-case.  The upper-case
423                     attribute is disabled.
424              -n     Give each name the nameref attribute, making  it  a  name
425                     reference  to  another  variable.  That other variable is
426                     defined by the value of name.   All  references,  assign‐
427                     ments,  and attribute modifications to name, except those
428                     using or changing the -n attribute itself, are  performed
429                     on  the variable referenced by name's value.  The nameref
430                     attribute cannot be applied to array variables.
431              -r     Make names readonly.  These names cannot then be assigned
432                     values by subsequent assignment statements or unset.
433              -t     Give  each  name  the  trace attribute.  Traced functions
434                     inherit the DEBUG  and  RETURN  traps  from  the  calling
435                     shell.   The  trace  attribute has no special meaning for
436                     variables.
437              -u     When the variable is assigned  a  value,  all  lower-case
438                     characters  are  converted to upper-case.  The lower-case
439                     attribute is disabled.
440              -x     Mark names for export  to  subsequent  commands  via  the
441                     environment.
442
443              Using  `+'  instead of `-' turns off the attribute instead, with
444              the exceptions that +a and +A may not be used to  destroy  array
445              variables  and  +r will not remove the readonly attribute.  When
446              used in a function, declare and typeset make each name local, as
447              with  the local command, unless the -g option is supplied.  If a
448              variable name is followed by =value, the value of  the  variable
449              is  set  to value.  When using -a or -A and the compound assign‐
450              ment syntax to create array variables, additional attributes  do
451              not  take effect until subsequent assignments.  The return value
452              is 0 unless an invalid option is encountered, an attempt is made
453              to define a function using ``-f foo=bar'', an attempt is made to
454              assign a value to a readonly variable, an  attempt  is  made  to
455              assign  a  value to an array variable without using the compound
456              assignment syntax (see Arrays above), one of the names is not  a
457              valid  shell variable name, an attempt is made to turn off read‐
458              only status for a readonly variable, an attempt is made to  turn
459              off array status for an array variable, or an attempt is made to
460              display a non-existent function with -f.
461
462       dirs [-clpv] [+n] [-n]
463              Without options,  displays  the  list  of  currently  remembered
464              directories.   The  default  display  is  on  a single line with
465              directory names separated by spaces.  Directories are  added  to
466              the  list  with  the  pushd  command;  the  popd command removes
467              entries from the list.  The  current  directory  is  always  the
468              first directory in the stack.
469              -c     Clears  the  directory  stack  by  deleting  all  of  the
470                     entries.
471              -l     Produces a listing  using  full  pathnames;  the  default
472                     listing format uses a tilde to denote the home directory.
473              -p     Print the directory stack with one entry per line.
474              -v     Print  the  directory stack with one entry per line, pre‐
475                     fixing each entry with its index in the stack.
476              +n     Displays the nth entry counting from the left of the list
477                     shown by dirs when invoked without options, starting with
478                     zero.
479              -n     Displays the nth entry counting from  the  right  of  the
480                     list shown by dirs when invoked without options, starting
481                     with zero.
482
483              The return value is 0 unless an invalid option is supplied or  n
484              indexes beyond the end of the directory stack.
485
486       disown [-ar] [-h] [jobspec ... | pid ... ]
487              Without  options,  remove  each jobspec from the table of active
488              jobs.  If jobspec is not present, and neither the -a nor the  -r
489              option  is  supplied, the current job is used.  If the -h option
490              is given, each jobspec is not removed from  the  table,  but  is
491              marked  so  that  SIGHUP  is  not  sent  to the job if the shell
492              receives a SIGHUP.  If no jobspec is  supplied,  the  -a  option
493              means  to  remove or mark all jobs; the -r option without a job‐
494              spec argument restricts operation to running jobs.   The  return
495              value is 0 unless a jobspec does not specify a valid job.
496
497       echo [-neE] [arg ...]
498              Output  the  args,  separated  by spaces, followed by a newline.
499              The return status is 0 unless a write error occurs.   If  -n  is
500              specified, the trailing newline is suppressed.  If the -e option
501              is given,  interpretation  of  the  following  backslash-escaped
502              characters  is  enabled.  The -E option disables the interpreta‐
503              tion of these escape characters, even on systems where they  are
504              interpreted  by  default.  The xpg_echo shell option may be used
505              to dynamically determine  whether  or  not  echo  expands  these
506              escape  characters  by  default.   echo does not interpret -- to
507              mean the end of options.  echo interprets the  following  escape
508              sequences:
509              \a     alert (bell)
510              \b     backspace
511              \c     suppress further output
512              \e
513              \E     an escape character
514              \f     form feed
515              \n     new line
516              \r     carriage return
517              \t     horizontal tab
518              \v     vertical tab
519              \\     backslash
520              \0nnn  the  eight-bit  character  whose value is the octal value
521                     nnn (zero to three octal digits)
522              \xHH   the eight-bit character whose value  is  the  hexadecimal
523                     value HH (one or two hex digits)
524              \uHHHH the  Unicode (ISO/IEC 10646) character whose value is the
525                     hexadecimal value HHHH (one to four hex digits)
526              \UHHHHHHHH
527                     the Unicode (ISO/IEC 10646) character whose value is  the
528                     hexadecimal value HHHHHHHH (one to eight hex digits)
529
530       enable [-a] [-dnps] [-f filename] [name ...]
531              Enable  and disable builtin shell commands.  Disabling a builtin
532              allows a disk command which has the same name as a shell builtin
533              to  be  executed without specifying a full pathname, even though
534              the shell normally searches for builtins before  disk  commands.
535              If  -n  is  used,  each  name  is disabled; otherwise, names are
536              enabled.  For example, to use the test binary found via the PATH
537              instead  of  the  shell builtin version, run ``enable -n test''.
538              The -f option means to load the new builtin  command  name  from
539              shared object filename, on systems that support dynamic loading.
540              The -d option will delete a builtin previously loaded  with  -f.
541              If no name arguments are given, or if the -p option is supplied,
542              a list of shell builtins is printed.  With no other option argu‐
543              ments,  the  list consists of all enabled shell builtins.  If -n
544              is supplied, only disabled builtins are printed.  If -a is  sup‐
545              plied,  the  list printed includes all builtins, with an indica‐
546              tion of whether or not each is enabled.  If -s is supplied,  the
547              output  is restricted to the POSIX special builtins.  The return
548              value is 0 unless a name is not a shell builtin or there  is  an
549              error loading a new builtin from a shared object.
550
551       eval [arg ...]
552              The  args  are read and concatenated together into a single com‐
553              mand.  This command is then read and executed by the shell,  and
554              its  exit status is returned as the value of eval.  If there are
555              no args, or only null arguments, eval returns 0.
556
557       exec [-cl] [-a name] [command [arguments]]
558              If command is specified, it replaces the shell.  No new  process
559              is  created.  The arguments become the arguments to command.  If
560              the -l option is supplied, the shell places a dash at the begin‐
561              ning  of  the  zeroth  argument passed to command.  This is what
562              login(1) does.  The -c option causes command to be executed with
563              an  empty environment.  If -a is supplied, the shell passes name
564              as the zeroth argument to the executed command.  If command can‐
565              not  be executed for some reason, a non-interactive shell exits,
566              unless the execfail shell option is enabled.  In that  case,  it
567              returns  failure.   An  interactive shell returns failure if the
568              file cannot be executed.  A subshell  exits  unconditionally  if
569              exec  fails.  If command is not specified, any redirections take
570              effect in the current shell, and the return  status  is  0.   If
571              there is a redirection error, the return status is 1.
572
573       exit [n]
574              Cause  the  shell  to exit with a status of n.  If n is omitted,
575              the exit status is that of the last command executed.  A trap on
576              EXIT is executed before the shell terminates.
577
578       export [-fn] [name[=word]] ...
579       export -p
580              The  supplied names are marked for automatic export to the envi‐
581              ronment of subsequently executed commands.  If the -f option  is
582              given,  the names refer to functions.  If no names are given, or
583              if the -p option is supplied, a list of names  of  all  exported
584              variables  is printed.  The -n option causes the export property
585              to be removed from each name.  If a variable name is followed by
586              =word, the value of the variable is set to word.  export returns
587              an exit status of 0 unless an invalid option is encountered, one
588              of  the  names is not a valid shell variable name, or -f is sup‐
589              plied with a name that is not a function.
590
591       fc [-e ename] [-lnr] [first] [last]
592       fc -s [pat=rep] [cmd]
593              The first form selects a range of commands from  first  to  last
594              from  the  history  list  and  displays or edits and re-executes
595              them.  First and last may be specified as a  string  (to  locate
596              the  last command beginning with that string) or as a number (an
597              index into the history list, where a negative number is used  as
598              an  offset  from  the  current  command number).  If last is not
599              specified, it is set to the current command for listing (so that
600              ``fc  -l  -10'' prints the last 10 commands) and to first other‐
601              wise.  If first is not specified, it is set to the previous com‐
602              mand for editing and -16 for listing.
603
604              The  -n option suppresses the command numbers when listing.  The
605              -r option reverses the order of the commands.  If the -l  option
606              is  given,  the  commands are listed on standard output.  Other‐
607              wise, the editor given by ename is invoked on a file  containing
608              those  commands.  If ename is not given, the value of the FCEDIT
609              variable is used, and the value of EDITOR if FCEDIT is not  set.
610              If  neither  variable  is set, vi is used.  When editing is com‐
611              plete, the edited commands are echoed and executed.
612
613              In the second form, command is re-executed after  each  instance
614              of  pat  is replaced by rep.  Command is interpreted the same as
615              first above.  A useful alias to use with this is ``r="fc  -s"'',
616              so  that  typing  ``r  cc'' runs the last command beginning with
617              ``cc'' and typing ``r'' re-executes the last command.
618
619              If the first form is used, the  return  value  is  0  unless  an
620              invalid  option  is encountered or first or last specify history
621              lines out of range.  If the -e option is  supplied,  the  return
622              value is the value of the last command executed or failure if an
623              error occurs with the temporary file of commands.  If the second
624              form  is  used, the return status is that of the command re-exe‐
625              cuted, unless cmd does not specify  a  valid  history  line,  in
626              which case fc returns failure.
627
628       fg [jobspec]
629              Resume  jobspec  in the foreground, and make it the current job.
630              If jobspec is not present, the shell's notion of the current job
631              is  used.   The  return value is that of the command placed into
632              the foreground, or failure if run when job control  is  disabled
633              or, when run with job control enabled, if jobspec does not spec‐
634              ify a valid job or jobspec specifies  a  job  that  was  started
635              without job control.
636
637       getopts optstring name [args]
638              getopts  is used by shell procedures to parse positional parame‐
639              ters.  optstring contains the option  characters  to  be  recog‐
640              nized;  if  a  character  is  followed by a colon, the option is
641              expected to have an argument, which should be separated from  it
642              by  white space.  The colon and question mark characters may not
643              be used as option characters.  Each time it is invoked,  getopts
644              places  the next option in the shell variable name, initializing
645              name if it does not exist, and the index of the next argument to
646              be processed into the variable OPTIND.  OPTIND is initialized to
647              1 each time the shell or a shell script  is  invoked.   When  an
648              option  requires  an argument, getopts places that argument into
649              the variable OPTARG.  The shell does not reset OPTIND  automati‐
650              cally;  it  must  be  manually  reset  between multiple calls to
651              getopts within the same shell invocation if a new set of parame‐
652              ters is to be used.
653
654              When  the  end  of  options is encountered, getopts exits with a
655              return value greater than zero.  OPTIND is set to the  index  of
656              the first non-option argument, and name is set to ?.
657
658              getopts  normally  parses the positional parameters, but if more
659              arguments are given in args, getopts parses those instead.
660
661              getopts can report errors in two ways.  If the  first  character
662              of  optstring  is  a  colon, silent error reporting is used.  In
663              normal operation, diagnostic messages are printed  when  invalid
664              options  or  missing  option  arguments are encountered.  If the
665              variable OPTERR is set to 0, no  error  messages  will  be  dis‐
666              played, even if the first character of optstring is not a colon.
667
668              If an invalid option is seen, getopts places ? into name and, if
669              not silent, prints an  error  message  and  unsets  OPTARG.   If
670              getopts  is  silent,  the  option  character  found is placed in
671              OPTARG and no diagnostic message is printed.
672
673              If a required argument is not found, and getopts is not  silent,
674              a  question  mark  (?) is placed in name, OPTARG is unset, and a
675              diagnostic message is printed.  If getopts  is  silent,  then  a
676              colon  (:)  is  placed  in  name and OPTARG is set to the option
677              character found.
678
679              getopts returns true if an option, specified or unspecified,  is
680              found.  It returns false if the end of options is encountered or
681              an error occurs.
682
683       hash [-lr] [-p filename] [-dt] [name]
684              Each time hash is invoked, the full pathname of the command name
685              is  determined  by searching the directories in $PATH and remem‐
686              bered.  Any previously-remembered pathname is discarded.  If the
687              -p option is supplied, no path search is performed, and filename
688              is used as the full filename of  the  command.   The  -r  option
689              causes  the  shell  to  forget all remembered locations.  The -d
690              option causes the shell to forget  the  remembered  location  of
691              each  name.   If the -t option is supplied, the full pathname to
692              which each name corresponds is printed.  If multiple name  argu‐
693              ments  are  supplied  with  -t,  the  name is printed before the
694              hashed full pathname.  The -l option causes output  to  be  dis‐
695              played in a format that may be reused as input.  If no arguments
696              are given, or if only -l is supplied, information  about  remem‐
697              bered  commands  is printed.  The return status is true unless a
698              name is not found or an invalid option is supplied.
699
700       help [-dms] [pattern]
701              Display helpful information about builtin commands.  If  pattern
702              is  specified, help gives detailed help on all commands matching
703              pattern; otherwise help for all the builtins and  shell  control
704              structures is printed.
705              -d     Display a short description of each pattern
706              -m     Display the description of each pattern in a manpage-like
707                     format
708              -s     Display only a short usage synopsis for each pattern
709
710              The return status is 0 unless no command matches pattern.
711
712       history [n]
713       history -c
714       history -d offset
715       history -d start-end
716       history -anrw [filename]
717       history -p arg [arg ...]
718       history -s arg [arg ...]
719              With no options, display the command history list with line num‐
720              bers.  Lines listed with a * have been modified.  An argument of
721              n lists only the last n lines.  If the shell variable  HISTTIME‐
722              FORMAT  is  set  and not null, it is used as a format string for
723              strftime(3) to display the time stamp associated with each  dis‐
724              played  history  entry.  No intervening blank is printed between
725              the formatted time stamp and the history line.  If  filename  is
726              supplied,  it  is  used as the name of the history file; if not,
727              the value of HISTFILE is used.  Options, if supplied,  have  the
728              following meanings:
729              -c     Clear the history list by deleting all the entries.
730              -d offset
731                     Delete  the  history entry at position offset.  If offset
732                     is negative, it is interpreted as relative to one greater
733                     than the last history position, so negative indices count
734                     back from the end of the history,  and  an  index  of  -1
735                     refers to the current history -d command.
736              -d start-end
737                     Delete  the  history  entries between positions start and
738                     end, inclusive.  Positive and negative values  for  start
739                     and end are interpreted as described above.
740              -a     Append  the  ``new''  history  lines to the history file.
741                     These are history lines entered since  the  beginning  of
742                     the current bash session, but not already appended to the
743                     history file.
744              -n     Read the history lines not already read from the  history
745                     file  into  the  current  history  list.  These are lines
746                     appended to the history file since the beginning  of  the
747                     current bash session.
748              -r     Read  the contents of the history file and append them to
749                     the current history list.
750              -w     Write the current history list to the history file, over‐
751                     writing the history file's contents.
752              -p     Perform  history  substitution  on the following args and
753                     display the result on  the  standard  output.   Does  not
754                     store  the results in the history list.  Each arg must be
755                     quoted to disable normal history expansion.
756              -s     Store the args in the history list  as  a  single  entry.
757                     The  last  command  in the history list is removed before
758                     the args are added.
759
760              If the HISTTIMEFORMAT variable is set, the time  stamp  informa‐
761              tion  associated  with each history entry is written to the his‐
762              tory file, marked with the history comment character.  When  the
763              history  file  is read, lines beginning with the history comment
764              character followed immediately by a  digit  are  interpreted  as
765              timestamps for the following history entry.  The return value is
766              0 unless an invalid option is encountered, an error occurs while
767              reading  or  writing the history file, an invalid offset is sup‐
768              plied as an argument to -d, or the history expansion supplied as
769              an argument to -p fails.
770
771       jobs [-lnprs] [ jobspec ... ]
772       jobs -x command [ args ... ]
773              The first form lists the active jobs.  The options have the fol‐
774              lowing meanings:
775              -l     List process IDs in addition to the normal information.
776              -n     Display information only about  jobs  that  have  changed
777                     status since the user was last notified of their status.
778              -p     List  only  the  process  ID  of  the job's process group
779                     leader.
780              -r     Display only running jobs.
781              -s     Display only stopped jobs.
782
783              If jobspec is given, output is restricted to  information  about
784              that  job.   The  return status is 0 unless an invalid option is
785              encountered or an invalid jobspec is supplied.
786
787              If the -x option is supplied, jobs replaces any jobspec found in
788              command  or  args  with  the corresponding process group ID, and
789              executes command passing it args, returning its exit status.
790
791       kill [-s sigspec | -n signum | -sigspec] [pid | jobspec] ...
792       kill -l|-L [sigspec | exit_status]
793              Send the signal named by sigspec  or  signum  to  the  processes
794              named  by  pid or jobspec.  sigspec is either a case-insensitive
795              signal name such as SIGKILL (with or without the SIG prefix)  or
796              a  signal  number; signum is a signal number.  If sigspec is not
797              present, then SIGTERM is assumed.  An argument of -l  lists  the
798              signal  names.   If any arguments are supplied when -l is given,
799              the names of the signals  corresponding  to  the  arguments  are
800              listed, and the return status is 0.  The exit_status argument to
801              -l is a number specifying either a signal  number  or  the  exit
802              status  of  a  process terminated by a signal.  The -L option is
803              equivalent to -l.  kill returns true if at least one signal  was
804              successfully  sent,  or  false  if an error occurs or an invalid
805              option is encountered.
806
807       let arg [arg ...]
808              Each arg is an arithmetic expression to be evaluated (see ARITH‐
809              METIC  EVALUATION  above).   If the last arg evaluates to 0, let
810              returns 1; 0 is returned otherwise.
811
812       local [option] [name[=value] ... | - ]
813              For each argument, a local variable named name is  created,  and
814              assigned  value.   The option can be any of the options accepted
815              by declare.  When local is used within a function, it causes the
816              variable  name  to have a visible scope restricted to that func‐
817              tion and its children.  If name is -, the set of  shell  options
818              is  made  local to the function in which local is invoked: shell
819              options changed using the set builtin inside  the  function  are
820              restored  to  their  original  values when the function returns.
821              With no operands, local writes a list of local variables to  the
822              standard  output.  It is an error to use local when not within a
823              function.  The return status is 0 unless local is used outside a
824              function,  an  invalid  name  is supplied, or name is a readonly
825              variable.
826
827       logout Exit a login shell.
828
829       mapfile [-d delim] [-n count] [-O origin] [-s count] [-t] [-u  fd]  [-C
830       callback] [-c quantum] [array]
831       readarray [-d delim] [-n count] [-O origin] [-s count] [-t] [-u fd] [-C
832       callback] [-c quantum] [array]
833              Read lines from the standard input into the indexed array  vari‐
834              able  array, or from file descriptor fd if the -u option is sup‐
835              plied.  The variable MAPFILE is the default array.  Options,  if
836              supplied, have the following meanings:
837              -d     The  first  character  of delim is used to terminate each
838                     input line, rather than newline.  If delim is  the  empty
839                     string, mapfile will terminate a line when it reads a NUL
840                     character.
841              -n     Copy at most count lines.  If count is 0, all  lines  are
842                     copied.
843              -O     Begin  assigning  to  array at index origin.  The default
844                     index is 0.
845              -s     Discard the first count lines read.
846              -t     Remove a trailing delim (default newline) from each  line
847                     read.
848              -u     Read  lines  from file descriptor fd instead of the stan‐
849                     dard input.
850              -C     Evaluate callback each time quantum lines are read.   The
851                     -c option specifies quantum.
852              -c     Specify  the  number  of  lines read between each call to
853                     callback.
854
855              If -C is specified without -c,  the  default  quantum  is  5000.
856              When callback is evaluated, it is supplied the index of the next
857              array element to be assigned and the line to be assigned to that
858              element  as  additional  arguments.  callback is evaluated after
859              the line is read but before the array element is assigned.
860
861              If not supplied with an  explicit  origin,  mapfile  will  clear
862              array before assigning to it.
863
864              mapfile  returns successfully unless an invalid option or option
865              argument is supplied, array is invalid or  unassignable,  or  if
866              array is not an indexed array.
867
868       popd [-n] [+n] [-n]
869              Removes  entries  from  the directory stack.  With no arguments,
870              removes the top directory from the stack, and performs a  cd  to
871              the new top directory.  Arguments, if supplied, have the follow‐
872              ing meanings:
873              -n     Suppresses the normal change of directory  when  removing
874                     directories  from  the  stack,  so that only the stack is
875                     manipulated.
876              +n     Removes the nth entry counting from the left of the  list
877                     shown  by  dirs, starting with zero.  For example: ``popd
878                     +0'' removes the first directory, ``popd +1'' the second.
879              -n     Removes the nth entry counting from the right of the list
880                     shown  by  dirs, starting with zero.  For example: ``popd
881                     -0'' removes the last directory, ``popd -1'' the next  to
882                     last.
883
884              If  the popd command is successful, a dirs is performed as well,
885              and the return status is 0.  popd returns false  if  an  invalid
886              option is encountered, the directory stack is empty, a non-exis‐
887              tent directory stack entry is specified, or the directory change
888              fails.
889
890       printf [-v var] format [arguments]
891              Write  the  formatted arguments to the standard output under the
892              control of the format.  The -v option causes the  output  to  be
893              assigned  to  the  variable var rather than being printed to the
894              standard output.
895
896              The format is a character string which contains three  types  of
897              objects:  plain  characters, which are simply copied to standard
898              output, character escape  sequences,  which  are  converted  and
899              copied  to  the standard output, and format specifications, each
900              of which causes printing of the next  successive  argument.   In
901              addition to the standard printf(1) format specifications, printf
902              interprets the following extensions:
903              %b     causes printf to expand backslash escape sequences in the
904                     corresponding argument in the same way as echo -e.
905              %q     causes  printf  to output the corresponding argument in a
906                     format that can be reused as shell input.
907              %(datefmt)T
908                     causes printf to output the  date-time  string  resulting
909                     from  using  datefmt  as a format string for strftime(3).
910                     The corresponding argument is an integer representing the
911                     number  of seconds since the epoch.  Two special argument
912                     values may be used: -1 represents the current  time,  and
913                     -2  represents  the  time  the  shell was invoked.  If no
914                     argument is specified, conversion behaves as  if  -1  had
915                     been  given.   This  is  an exception to the usual printf
916                     behavior.
917
918              Arguments to non-string format specifiers are treated as C  con‐
919              stants, except that a leading plus or minus sign is allowed, and
920              if the leading character is a single or double quote, the  value
921              is the ASCII value of the following character.
922
923              The  format  is  reused as necessary to consume all of the argu‐
924              ments.  If the format requires more arguments than are supplied,
925              the  extra  format  specifications  behave as if a zero value or
926              null string, as appropriate,  had  been  supplied.   The  return
927              value is zero on success, non-zero on failure.
928
929       pushd [-n] [+n] [-n]
930       pushd [-n] [dir]
931              Adds  a  directory to the top of the directory stack, or rotates
932              the stack, making the new top of the stack the  current  working
933              directory.   With  no  arguments,  pushd  exchanges  the top two
934              directories and returns 0, unless the directory stack is  empty.
935              Arguments, if supplied, have the following meanings:
936              -n     Suppresses  the  normal change of directory when rotating
937                     or adding directories to the  stack,  so  that  only  the
938                     stack is manipulated.
939              +n     Rotates  the  stack  so  that the nth directory (counting
940                     from the left of the list shown by  dirs,  starting  with
941                     zero) is at the top.
942              -n     Rotates  the  stack  so  that the nth directory (counting
943                     from the right of the list shown by dirs,  starting  with
944                     zero) is at the top.
945              dir    Adds dir to the directory stack at the top, making it the
946                     new current working directory as if it had been  supplied
947                     as the argument to the cd builtin.
948
949              If the pushd command is successful, a dirs is performed as well.
950              If the first form is used, pushd returns 0 unless the cd to  dir
951              fails.   With the second form, pushd returns 0 unless the direc‐
952              tory stack is empty, a non-existent directory stack  element  is
953              specified,  or the directory change to the specified new current
954              directory fails.
955
956       pwd [-LP]
957              Print the absolute pathname of the  current  working  directory.
958              The pathname printed contains no symbolic links if the -P option
959              is supplied or the -o physical option to the set builtin command
960              is  enabled.  If the -L option is used, the pathname printed may
961              contain symbolic links.  The return status is 0 unless an  error
962              occurs  while  reading  the  name of the current directory or an
963              invalid option is supplied.
964
965       read [-ers] [-a aname] [-d delim] [-i text] [-n nchars] [-N nchars] [-p
966       prompt] [-t timeout] [-u fd] [name ...]
967              One  line  is  read  from  the  standard input, or from the file
968              descriptor fd supplied as an argument to the  -u  option,  split
969              into  words  as  described  above  under Word Splitting, and the
970              first word is assigned to the first name, the second word to the
971              second name, and so on.  If there are more words than names, the
972              remaining words and their intervening delimiters are assigned to
973              the  last  name.   If  there are fewer words read from the input
974              stream than names, the remaining names are assigned  empty  val‐
975              ues.   The  characters  in  IFS  are used to split the line into
976              words  using  the  same  rules  the  shell  uses  for  expansion
977              (described above under Word Splitting).  The backslash character
978              (\) may be used to remove any special meaning for the next char‐
979              acter  read  and  for  line continuation.  Options, if supplied,
980              have the following meanings:
981              -a aname
982                     The words are assigned to sequential indices of the array
983                     variable aname, starting at 0.  aname is unset before any
984                     new  values  are  assigned.   Other  name  arguments  are
985                     ignored.
986              -d delim
987                     The  first  character  of  delim is used to terminate the
988                     input line, rather than newline.  If delim is  the  empty
989                     string,  read  will  terminate a line when it reads a NUL
990                     character.
991              -e     If the standard input is coming from a terminal, readline
992                     (see  READLINE  above) is used to obtain the line.  Read‐
993                     line uses the current (or default, if  line  editing  was
994                     not  previously  active) editing settings, but uses Read‐
995                     line's default filename completion.
996              -i text
997                     If readline is being used  to  read  the  line,  text  is
998                     placed into the editing buffer before editing begins.
999              -n nchars
1000                     read  returns after reading nchars characters rather than
1001                     waiting for a complete line of input, but honors a delim‐
1002                     iter  if fewer than nchars characters are read before the
1003                     delimiter.
1004              -N nchars
1005                     read returns  after  reading  exactly  nchars  characters
1006                     rather  than waiting for a complete line of input, unless
1007                     EOF is encountered or read times out.  Delimiter  charac‐
1008                     ters  encountered  in the input are not treated specially
1009                     and do not cause read to return until  nchars  characters
1010                     are  read.   The result is not split on the characters in
1011                     IFS; the intent is that the variable is assigned  exactly
1012                     the characters read (with the exception of backslash; see
1013                     the -r option below).
1014              -p prompt
1015                     Display prompt on standard error, without a trailing new‐
1016                     line, before attempting to read any input.  The prompt is
1017                     displayed only if input is coming from a terminal.
1018              -r     Backslash does not act as an escape character.  The back‐
1019                     slash  is considered to be part of the line.  In particu‐
1020                     lar, a backslash-newline pair may not then be used  as  a
1021                     line continuation.
1022              -s     Silent mode.  If input is coming from a terminal, charac‐
1023                     ters are not echoed.
1024              -t timeout
1025                     Cause read to time out and return failure if  a  complete
1026                     line  of  input  (or a specified number of characters) is
1027                     not read within timeout seconds.  timeout may be a  deci‐
1028                     mal  number with a fractional portion following the deci‐
1029                     mal point.  This option is  only  effective  if  read  is
1030                     reading  input  from  a  terminal, pipe, or other special
1031                     file; it has no effect when reading from  regular  files.
1032                     If read times out, read saves any partial input read into
1033                     the specified variable  name.   If  timeout  is  0,  read
1034                     returns  immediately,  without  trying  to read any data.
1035                     The exit status is 0 if input is available on the  speci‐
1036                     fied  file descriptor, non-zero otherwise.  The exit sta‐
1037                     tus is greater than 128 if the timeout is exceeded.
1038              -u fd  Read input from file descriptor fd.
1039
1040              If no names are supplied, the line read is assigned to the vari‐
1041              able  REPLY.   The  exit  status  is zero, unless end-of-file is
1042              encountered, read times out (in which case the status is greater
1043              than  128),  a variable assignment error (such as assigning to a
1044              readonly variable) occurs, or an invalid file descriptor is sup‐
1045              plied as the argument to -u.
1046
1047       readonly [-aAf] [-p] [name[=word] ...]
1048              The  given  names are marked readonly; the values of these names
1049              may not be changed by subsequent assignment.  If the  -f  option
1050              is  supplied,  the  functions  corresponding to the names are so
1051              marked.  The  -a  option  restricts  the  variables  to  indexed
1052              arrays;  the  -A  option  restricts the variables to associative
1053              arrays.  If both options are supplied, -A takes precedence.   If
1054              no  name arguments are given, or if the -p option is supplied, a
1055              list of all readonly names is printed.  The other options may be
1056              used  to  restrict the output to a subset of the set of readonly
1057              names.  The -p option causes output to be displayed in a  format
1058              that  may be reused as input.  If a variable name is followed by
1059              =word, the value of the variable is set  to  word.   The  return
1060              status  is 0 unless an invalid option is encountered, one of the
1061              names is not a valid shell variable name, or -f is supplied with
1062              a name that is not a function.
1063
1064       return [n]
1065              Causes  a function to stop executing and return the value speci‐
1066              fied by n to its caller.  If n is omitted, the return status  is
1067              that  of  the  last  command  executed in the function body.  If
1068              return is executed by a trap handler, the last command  used  to
1069              determine  the  status  is  the last command executed before the
1070              trap handler.  If return is executed during a  DEBUG  trap,  the
1071              last  command  used  to determine the status is the last command
1072              executed by the trap handler  before  return  was  invoked.   If
1073              return  is  used  outside  a function, but during execution of a
1074              script by the .  (source) command, it causes the shell  to  stop
1075              executing  that script and return either n or the exit status of
1076              the last command executed within the script as the  exit  status
1077              of  the script.  If n is supplied, the return value is its least
1078              significant 8 bits.  The return status is non-zero if return  is
1079              supplied  a  non-numeric argument, or is used outside a function
1080              and not during execution of a script by . or source.   Any  com‐
1081              mand  associated  with the RETURN trap is executed before execu‐
1082              tion resumes after the function or script.
1083
1084       set [--abefhkmnptuvxBCEHPT] [-o option-name] [arg ...]
1085       set [+abefhkmnptuvxBCEHPT] [+o option-name] [arg ...]
1086              Without options, the name and value of each shell  variable  are
1087              displayed in a format that can be reused as input for setting or
1088              resetting the currently-set variables.  Read-only variables can‐
1089              not  be  reset.  In posix mode, only shell variables are listed.
1090              The output is sorted according  to  the  current  locale.   When
1091              options  are specified, they set or unset shell attributes.  Any
1092              arguments remaining after option processing are treated as  val‐
1093              ues for the positional parameters and are assigned, in order, to
1094              $1, $2, ...  $n.  Options,  if  specified,  have  the  following
1095              meanings:
1096              -a      Each variable or function that is created or modified is
1097                      given the export attribute and marked for export to  the
1098                      environment of subsequent commands.
1099              -b      Report  the status of terminated background jobs immedi‐
1100                      ately, rather than before the next primary prompt.  This
1101                      is effective only when job control is enabled.
1102              -e      Exit  immediately  if a pipeline (which may consist of a
1103                      single simple command), a list, or  a  compound  command
1104                      (see SHELL GRAMMAR above), exits with a non-zero status.
1105                      The shell does not exit if the  command  that  fails  is
1106                      part  of  the command list immediately following a while
1107                      or until keyword, part of the test following the  if  or
1108                      elif  reserved  words, part of any command executed in a
1109                      && or || list except the command following the final  &&
1110                      or ||, any command in a pipeline but the last, or if the
1111                      command's return value is being inverted with !.   If  a
1112                      compound  command  other  than a subshell returns a non-
1113                      zero status because a command failed while -e was  being
1114                      ignored,  the  shell  does  not exit.  A trap on ERR, if
1115                      set, is executed before the shell  exits.   This  option
1116                      applies to the shell environment and each subshell envi‐
1117                      ronment separately (see  COMMAND  EXECUTION  ENVIRONMENT
1118                      above), and may cause subshells to exit before executing
1119                      all the commands in the subshell.
1120
1121                      If a compound command or shell function  executes  in  a
1122                      context  where -e is being ignored, none of the commands
1123                      executed within the compound command  or  function  body
1124                      will  be  affected  by the -e setting, even if -e is set
1125                      and a command returns a failure status.  If  a  compound
1126                      command  or  shell function sets -e while executing in a
1127                      context where -e is ignored, that setting will not  have
1128                      any  effect  until  the  compound command or the command
1129                      containing the function call completes.
1130              -f      Disable pathname expansion.
1131              -h      Remember the location of commands as they are looked  up
1132                      for execution.  This is enabled by default.
1133              -k      All  arguments  in the form of assignment statements are
1134                      placed in the environment for a command, not just  those
1135                      that precede the command name.
1136              -m      Monitor  mode.   Job control is enabled.  This option is
1137                      on by default for interactive  shells  on  systems  that
1138                      support  it  (see JOB CONTROL above).  All processes run
1139                      in a separate process group.  When a background job com‐
1140                      pletes, the shell prints a line containing its exit sta‐
1141                      tus.
1142              -n      Read commands but do not execute them.  This may be used
1143                      to  check  a  shell  script  for syntax errors.  This is
1144                      ignored by interactive shells.
1145              -o option-name
1146                      The option-name can be one of the following:
1147                      allexport
1148                              Same as -a.
1149                      braceexpand
1150                              Same as -B.
1151                      emacs   Use an emacs-style command line  editing  inter‐
1152                              face.  This is enabled by default when the shell
1153                              is interactive, unless the shell is started with
1154                              the  --noediting  option.  This also affects the
1155                              editing interface used for read -e.
1156                      errexit Same as -e.
1157                      errtrace
1158                              Same as -E.
1159                      functrace
1160                              Same as -T.
1161                      hashall Same as -h.
1162                      histexpand
1163                              Same as -H.
1164                      history Enable command history, as described above under
1165                              HISTORY.  This option is on by default in inter‐
1166                              active shells.
1167                      ignoreeof
1168                              The  effect  is  as   if   the   shell   command
1169                              ``IGNOREEOF=10''  had  been  executed (see Shell
1170                              Variables above).
1171                      keyword Same as -k.
1172                      monitor Same as -m.
1173                      noclobber
1174                              Same as -C.
1175                      noexec  Same as -n.
1176                      noglob  Same as -f.
1177                      nolog   Currently ignored.
1178                      notify  Same as -b.
1179                      nounset Same as -u.
1180                      onecmd  Same as -t.
1181                      physical
1182                              Same as -P.
1183                      pipefail
1184                              If set, the return value of a  pipeline  is  the
1185                              value  of  the  last (rightmost) command to exit
1186                              with a non-zero status, or zero if all  commands
1187                              in  the pipeline exit successfully.  This option
1188                              is disabled by default.
1189                      posix   Change the behavior of bash  where  the  default
1190                              operation  differs  from  the  POSIX standard to
1191                              match the standard (posix mode).  See  SEE  ALSO
1192                              below for a reference to a document that details
1193                              how posix mode affects bash's behavior.
1194                      privileged
1195                              Same as -p.
1196                      verbose Same as -v.
1197                      vi      Use a vi-style command line  editing  interface.
1198                              This also affects the editing interface used for
1199                              read -e.
1200                      xtrace  Same as -x.
1201                      If -o is supplied with no option-name, the values of the
1202                      current  options are printed.  If +o is supplied with no
1203                      option-name, a series of set commands  to  recreate  the
1204                      current  option  settings  is  displayed on the standard
1205                      output.
1206              -p      Turn on privileged mode.  In this  mode,  the  $ENV  and
1207                      $BASH_ENV  files  are not processed, shell functions are
1208                      not inherited from the environment, and  the  SHELLOPTS,
1209                      BASHOPTS,  CDPATH,  and  GLOBIGNORE  variables,  if they
1210                      appear in the environment, are ignored.  If the shell is
1211                      started  with the effective user (group) id not equal to
1212                      the real user (group) id, and the -p option is not  sup‐
1213                      plied, these actions are taken and the effective user id
1214                      is set to the real user id.  If the -p  option  is  sup‐
1215                      plied  at  startup,  the effective user id is not reset.
1216                      Turning this option off causes the  effective  user  and
1217                      group ids to be set to the real user and group ids.
1218              -t      Exit after reading and executing one command.
1219              -u      Treat unset variables and parameters other than the spe‐
1220                      cial parameters "@" and "*" as an error when  performing
1221                      parameter  expansion.   If  expansion is attempted on an
1222                      unset variable or parameter, the shell prints  an  error
1223                      message,  and, if not interactive, exits with a non-zero
1224                      status.
1225              -v      Print shell input lines as they are read.
1226              -x      After expanding each simple command, for  command,  case
1227                      command, select command, or arithmetic for command, dis‐
1228                      play the expanded value of PS4, followed by the  command
1229                      and its expanded arguments or associated word list.
1230              -B      The  shell performs brace expansion (see Brace Expansion
1231                      above).  This is on by default.
1232              -C      If set, bash does not overwrite an  existing  file  with
1233                      the  >,  >&,  and <> redirection operators.  This may be
1234                      overridden when creating output files by using the redi‐
1235                      rection operator >| instead of >.
1236              -E      If set, any trap on ERR is inherited by shell functions,
1237                      command substitutions, and commands executed in  a  sub‐
1238                      shell  environment.  The ERR trap is normally not inher‐
1239                      ited in such cases.
1240              -H      Enable !  style history substitution.  This option is on
1241                      by default when the shell is interactive.
1242              -P      If  set,  the shell does not resolve symbolic links when
1243                      executing commands such as cd that  change  the  current
1244                      working  directory.   It  uses  the  physical  directory
1245                      structure instead.  By default, bash follows the logical
1246                      chain  of  directories  when  performing  commands which
1247                      change the current directory.
1248              -T      If set, any traps on DEBUG and RETURN are  inherited  by
1249                      shell  functions,  command  substitutions,  and commands
1250                      executed in  a  subshell  environment.   The  DEBUG  and
1251                      RETURN traps are normally not inherited in such cases.
1252              --      If  no arguments follow this option, then the positional
1253                      parameters are unset.  Otherwise, the positional parame‐
1254                      ters  are  set  to  the args, even if some of them begin
1255                      with a -.
1256              -       Signal the end of options, cause all remaining  args  to
1257                      be assigned to the positional parameters.  The -x and -v
1258                      options are turned off.  If there are no args, the posi‐
1259                      tional parameters remain unchanged.
1260
1261              The  options are off by default unless otherwise noted.  Using +
1262              rather than - causes  these  options  to  be  turned  off.   The
1263              options  can  also be specified as arguments to an invocation of
1264              the shell.  The current set of options may be found in $-.   The
1265              return status is always true unless an invalid option is encoun‐
1266              tered.
1267
1268       shift [n]
1269              The positional parameters from n+1 ... are renamed  to  $1  ....
1270              Parameters  represented  by  the  numbers  $# down to $#-n+1 are
1271              unset.  n must be a non-negative number less than  or  equal  to
1272              $#.   If  n is 0, no parameters are changed.  If n is not given,
1273              it is assumed to be 1.  If n is greater than $#, the  positional
1274              parameters  are  not changed.  The return status is greater than
1275              zero if n is greater than $# or less than zero; otherwise 0.
1276
1277       shopt [-pqsu] [-o] [optname ...]
1278              Toggle the values of settings controlling optional shell  behav‐
1279              ior.   The settings can be either those listed below, or, if the
1280              -o option is used, those available with the -o option to the set
1281              builtin command.  With no options, or with the -p option, a list
1282              of all settable options is  displayed,  with  an  indication  of
1283              whether or not each is set; if optnames are supplied, the output
1284              is restricted to those options.  The -p option causes output  to
1285              be  displayed  in  a  form  that  may be reused as input.  Other
1286              options have the following meanings:
1287              -s     Enable (set) each optname.
1288              -u     Disable (unset) each optname.
1289              -q     Suppresses normal output (quiet mode); the return  status
1290                     indicates whether the optname is set or unset.  If multi‐
1291                     ple optname arguments are given with -q, the return  sta‐
1292                     tus  is zero if all optnames are enabled; non-zero other‐
1293                     wise.
1294              -o     Restricts the values of optname to be those  defined  for
1295                     the -o option to the set builtin.
1296
1297              If  either  -s  or  -u  is used with no optname arguments, shopt
1298              shows only those options which are set or  unset,  respectively.
1299              Unless  otherwise  noted, the shopt options are disabled (unset)
1300              by default.
1301
1302              The return status when listing options is zero if  all  optnames
1303              are  enabled,  non-zero  otherwise.   When  setting or unsetting
1304              options, the return status is zero unless an optname  is  not  a
1305              valid shell option.
1306
1307              The list of shopt options is:
1308
1309              assoc_expand_once
1310                      If  set,  the  shell  suppresses  multiple evaluation of
1311                      associative array subscripts during  arithmetic  expres‐
1312                      sion  evaluation, while executing builtins that can per‐
1313                      form variable assignments, and while executing  builtins
1314                      that perform array dereferencing.
1315              autocd  If  set,  a command name that is the name of a directory
1316                      is executed as if it were the argument to  the  cd  com‐
1317                      mand.  This option is only used by interactive shells.
1318              cdable_vars
1319                      If  set,  an  argument to the cd builtin command that is
1320                      not a directory is assumed to be the name of a  variable
1321                      whose value is the directory to change to.
1322              cdspell If set, minor errors in the spelling of a directory com‐
1323                      ponent in a cd command will be  corrected.   The  errors
1324                      checked for are transposed characters, a missing charac‐
1325                      ter, and one character too many.   If  a  correction  is
1326                      found,  the  corrected filename is printed, and the com‐
1327                      mand proceeds.  This option is only used by  interactive
1328                      shells.
1329              checkhash
1330                      If set, bash checks that a command found in the hash ta‐
1331                      ble exists before trying to execute  it.   If  a  hashed
1332                      command  no  longer exists, a normal path search is per‐
1333                      formed.
1334              checkjobs
1335                      If set, bash lists the status of any stopped and running
1336                      jobs  before  exiting an interactive shell.  If any jobs
1337                      are running, this causes the exit to be deferred until a
1338                      second  exit is attempted without an intervening command
1339                      (see JOB CONTROL above).   The  shell  always  postpones
1340                      exiting if any jobs are stopped.
1341              checkwinsize
1342                      If  set, bash checks the window size after each external
1343                      (non-builtin) command and,  if  necessary,  updates  the
1344                      values  of LINES and COLUMNS.  This option is enabled by
1345                      default.
1346              cmdhist If set, bash attempts to save all lines of  a  multiple-
1347                      line  command  in  the  same history entry.  This allows
1348                      easy re-editing of multi-line commands.  This option  is
1349                      enabled  by  default,  but only has an effect if command
1350                      history is enabled, as described above under HISTORY.
1351              compat31
1352                      If set, bash changes its behavior to that of version 3.1
1353                      with  respect  to quoted arguments to the [[ conditional
1354                      command's =~ operator and locale-specific string compar‐
1355                      ison  when  using  the  [[ conditional command's < and >
1356                      operators.  Bash versions prior to  bash-4.1  use  ASCII
1357                      collation and strcmp(3); bash-4.1 and later use the cur‐
1358                      rent locale's collation sequence and strcoll(3).
1359              compat32
1360                      If set, bash changes its behavior to that of version 3.2
1361                      with  respect  to locale-specific string comparison when
1362                      using the [[ conditional command's  <  and  >  operators
1363                      (see  previous  item)  and  the effect of interrupting a
1364                      command list.  Bash versions 3.2  and  earlier  continue
1365                      with  the  next command in the list after one terminates
1366                      due to an interrupt.
1367              compat40
1368                      If set, bash changes its behavior to that of version 4.0
1369                      with  respect  to locale-specific string comparison when
1370                      using the [[ conditional command's  <  and  >  operators
1371                      (see  description  of compat31) and the effect of inter‐
1372                      rupting a command list.  Bash  versions  4.0  and  later
1373                      interrupt  the  list as if the shell received the inter‐
1374                      rupt; previous versions continue with the  next  command
1375                      in the list.
1376              compat41
1377                      If  set, bash, when in posix mode, treats a single quote
1378                      in a double-quoted  parameter  expansion  as  a  special
1379                      character.   The  single quotes must match (an even num‐
1380                      ber) and the characters between the  single  quotes  are
1381                      considered  quoted.   This is the behavior of posix mode
1382                      through version 4.1.  The default bash behavior  remains
1383                      as in previous versions.
1384              compat42
1385                      If  set, bash does not process the replacement string in
1386                      the pattern  substitution  word  expansion  using  quote
1387                      removal.
1388              compat43
1389                      If  set,  bash  does  not  print a warning message if an
1390                      attempt is made to use a quoted compound  array  assign‐
1391                      ment  as  an  argument  to declare, makes word expansion
1392                      errors non-fatal errors that cause the  current  command
1393                      to  fail  (the  default  behavior  is to make them fatal
1394                      errors that cause the shell to exit), and does not reset
1395                      the  loop  state when a shell function is executed (this
1396                      allows break or continue in a shell function  to  affect
1397                      loops in the caller's context).
1398              compat44
1399                      If   set,   bash  saves  the  positional  parameters  to
1400                      BASH_ARGV and BASH_ARGC before they are used, regardless
1401                      of whether or not extended debugging mode is enabled.
1402              complete_fullquote
1403                      If  set,  bash  quotes all shell metacharacters in file‐
1404                      names and directory names  when  performing  completion.
1405                      If not set, bash removes metacharacters such as the dol‐
1406                      lar sign from the set of characters that will be  quoted
1407                      in  completed filenames when these metacharacters appear
1408                      in shell variable references in words to  be  completed.
1409                      This  means  that  dollar  signs  in variable names that
1410                      expand to directories will not be quoted;  however,  any
1411                      dollar  signs appearing in filenames will not be quoted,
1412                      either.  This is active only when bash  is  using  back‐
1413                      slashes  to quote completed filenames.  This variable is
1414                      set by default, which is the default  bash  behavior  in
1415                      versions through 4.2.
1416              direxpand
1417                      If  set,  bash replaces directory names with the results
1418                      of word expansion when performing  filename  completion.
1419                      This  changes  the contents of the readline editing buf‐
1420                      fer.  If not set, bash attempts  to  preserve  what  the
1421                      user typed.
1422              dirspell
1423                      If  set,  bash attempts spelling correction on directory
1424                      names during word completion if the directory name  ini‐
1425                      tially supplied does not exist.
1426              dotglob If  set, bash includes filenames beginning with a `.' in
1427                      the results of pathname expansion.  The filenames  ``.''
1428                      and  ``..''   must always be matched explicitly, even if
1429                      dotglob is set.
1430              execfail
1431                      If set, a non-interactive shell will not exit if it can‐
1432                      not  execute  the  file  specified as an argument to the
1433                      exec builtin command.  An  interactive  shell  does  not
1434                      exit if exec fails.
1435              expand_aliases
1436                      If  set,  aliases  are expanded as described above under
1437                      ALIASES.  This option is enabled by default for interac‐
1438                      tive shells.
1439              extdebug
1440                      If  set  at  shell  invocation,  arrange  to execute the
1441                      debugger profile before the shell starts,  identical  to
1442                      the  --debugger option.  If set after invocation, behav‐
1443                      ior intended for use by debuggers is enabled:
1444                      1.     The -F option to the declare builtin displays the
1445                             source file name and line number corresponding to
1446                             each function name supplied as an argument.
1447                      2.     If the command run by the DEBUG  trap  returns  a
1448                             non-zero  value,  the next command is skipped and
1449                             not executed.
1450                      3.     If the command run by the DEBUG  trap  returns  a
1451                             value  of 2, and the shell is executing in a sub‐
1452                             routine (a shell function or a shell script  exe‐
1453                             cuted  by  the  .  or source builtins), the shell
1454                             simulates a call to return.
1455                      4.     BASH_ARGC and BASH_ARGV are updated as  described
1456                             in their descriptions above.
1457                      5.     Function  tracing  is  enabled: command substitu‐
1458                             tion, shell functions, and subshells invoked with
1459                             ( command ) inherit the DEBUG and RETURN traps.
1460                      6.     Error  tracing  is enabled: command substitution,
1461                             shell functions, and  subshells  invoked  with  (
1462                             command ) inherit the ERR trap.
1463              extglob If set, the extended pattern matching features described
1464                      above under Pathname Expansion are enabled.
1465              extquote
1466                      If set, $'string' and  $"string"  quoting  is  performed
1467                      within   ${parameter}   expansions  enclosed  in  double
1468                      quotes.  This option is enabled by default.
1469              failglob
1470                      If set, patterns which fail to  match  filenames  during
1471                      pathname expansion result in an expansion error.
1472              force_fignore
1473                      If  set,  the  suffixes  specified  by the FIGNORE shell
1474                      variable cause words to be ignored when performing  word
1475                      completion even if the ignored words are the only possi‐
1476                      ble  completions.   See  SHELL  VARIABLES  above  for  a
1477                      description  of  FIGNORE.   This  option  is  enabled by
1478                      default.
1479              globasciiranges
1480                      If set,  range  expressions  used  in  pattern  matching
1481                      bracket  expressions (see Pattern Matching above) behave
1482                      as if in the traditional C locale when  performing  com‐
1483                      parisons.   That  is,  the  current  locale's  collating
1484                      sequence is not taken into account, so b will  not  col‐
1485                      late  between  A  and  B,  and upper-case and lower-case
1486                      ASCII characters will collate together.
1487              globstar
1488                      If set, the pattern ** used in a pathname expansion con‐
1489                      text  will  match all files and zero or more directories
1490                      and subdirectories.  If the pattern is followed by a  /,
1491                      only directories and subdirectories match.
1492              gnu_errfmt
1493                      If set, shell error messages are written in the standard
1494                      GNU error message format.
1495              histappend
1496                      If set, the history list is appended to the  file  named
1497                      by  the  value  of  the HISTFILE variable when the shell
1498                      exits, rather than overwriting the file.
1499              histreedit
1500                      If set, and readline is being used, a user is given  the
1501                      opportunity to re-edit a failed history substitution.
1502              histverify
1503                      If  set, and readline is being used, the results of his‐
1504                      tory substitution are  not  immediately  passed  to  the
1505                      shell  parser.   Instead,  the  resulting line is loaded
1506                      into the readline editing buffer, allowing further modi‐
1507                      fication.
1508              hostcomplete
1509                      If set, and readline is being used, bash will attempt to
1510                      perform hostname completion when a word containing  a  @
1511                      is   being  completed  (see  Completing  under  READLINE
1512                      above).  This is enabled by default.
1513              huponexit
1514                      If set, bash will send SIGHUP to all jobs when an inter‐
1515                      active login shell exits.
1516              inherit_errexit
1517                      If  set,  command substitution inherits the value of the
1518                      errexit option, instead of unsetting it in the  subshell
1519                      environment.   This option is enabled when posix mode is
1520                      enabled.
1521              interactive_comments
1522                      If set, allow a word beginning with # to cause that word
1523                      and  all remaining characters on that line to be ignored
1524                      in an interactive  shell  (see  COMMENTS  above).   This
1525                      option is enabled by default.
1526              lastpipe
1527                      If  set,  and  job control is not active, the shell runs
1528                      the last command of a pipeline not executed in the back‐
1529                      ground in the current shell environment.
1530              lithist If  set,  and  the cmdhist option is enabled, multi-line
1531                      commands are saved to the history with embedded newlines
1532                      rather than using semicolon separators where possible.
1533              localvar_inherit
1534                      If set, local variables inherit the value and attributes
1535                      of a variable of the same name that exists at a previous
1536                      scope  before  any  new  value is assigned.  The nameref
1537                      attribute is not inherited.
1538              localvar_unset
1539                      If set, calling unset on  local  variables  in  previous
1540                      function  scopes  marks  them so subsequent lookups find
1541                      them unset until that function returns. This is  identi‐
1542                      cal  to the behavior of unsetting local variables at the
1543                      current function scope.
1544              login_shell
1545                      The shell sets this option if it is started as  a  login
1546                      shell  (see  INVOCATION  above).   The  value may not be
1547                      changed.
1548              mailwarn
1549                      If set, and a file that bash is checking  for  mail  has
1550                      been  accessed  since  the last time it was checked, the
1551                      message ``The mail in mailfile has been read''  is  dis‐
1552                      played.
1553              no_empty_cmd_completion
1554                      If  set,  and  readline  is  being  used,  bash will not
1555                      attempt to search the PATH for possible completions when
1556                      completion is attempted on an empty line.
1557              nocaseglob
1558                      If  set,  bash  matches  filenames in a case-insensitive
1559                      fashion when performing pathname expansion (see Pathname
1560                      Expansion above).
1561              nocasematch
1562                      If  set,  bash  matches  patterns  in a case-insensitive
1563                      fashion when performing matching while executing case or
1564                      [[ conditional commands, when performing pattern substi‐
1565                      tution word expansions, or when filtering possible  com‐
1566                      pletions as part of programmable completion.
1567              nullglob
1568                      If  set,  bash allows patterns which match no files (see
1569                      Pathname Expansion above) to expand to  a  null  string,
1570                      rather than themselves.
1571              progcomp
1572                      If set, the programmable completion facilities (see Pro‐
1573                      grammable Completion above) are enabled.  This option is
1574                      enabled by default.
1575              progcomp_alias
1576                      If  set,  and  programmable  completion is enabled, bash
1577                      treats a command name that doesn't have any  completions
1578                      as  a possible alias and attempts alias expansion. If it
1579                      has an  alias,  bash  attempts  programmable  completion
1580                      using  the  command  word  resulting  from  the expanded
1581                      alias.
1582              promptvars
1583                      If set, prompt strings undergo parameter expansion, com‐
1584                      mand   substitution,  arithmetic  expansion,  and  quote
1585                      removal after being expanded as described  in  PROMPTING
1586                      above.  This option is enabled by default.
1587              restricted_shell
1588                      The   shell  sets  this  option  if  it  is  started  in
1589                      restricted mode (see RESTRICTED SHELL below).  The value
1590                      may  not be changed.  This is not reset when the startup
1591                      files are executed, allowing the startup files  to  dis‐
1592                      cover whether or not a shell is restricted.
1593              shift_verbose
1594                      If  set,  the shift builtin prints an error message when
1595                      the shift count exceeds the number of positional parame‐
1596                      ters.
1597              sourcepath
1598                      If set, the source (.) builtin uses the value of PATH to
1599                      find the directory containing the file  supplied  as  an
1600                      argument.  This option is enabled by default.
1601              xpg_echo
1602                      If   set,  the  echo  builtin  expands  backslash-escape
1603                      sequences by default.
1604
1605       suspend [-f]
1606              Suspend the execution of this shell until it receives a  SIGCONT
1607              signal.  A login shell cannot be suspended; the -f option can be
1608              used to override this and force the suspension.  The return sta‐
1609              tus  is  0  unless the shell is a login shell and -f is not sup‐
1610              plied, or if job control is not enabled.
1611
1612       test expr
1613       [ expr ]
1614              Return a status of 0 (true) or 1 (false) depending on the evalu‐
1615              ation of the conditional expression expr.  Each operator and op‐
1616              erand must be a separate argument.  Expressions are composed  of
1617              the  primaries  described  above  under CONDITIONAL EXPRESSIONS.
1618              test does not accept any options, nor does it accept and  ignore
1619              an argument of -- as signifying the end of options.
1620
1621              Expressions  may  be  combined  using  the  following operators,
1622              listed  in  decreasing  order  of  precedence.   The  evaluation
1623              depends  on the number of arguments; see below.  Operator prece‐
1624              dence is used when there are five or more arguments.
1625              ! expr True if expr is false.
1626              ( expr )
1627                     Returns the value of expr.  This may be used to  override
1628                     the normal precedence of operators.
1629              expr1 -a expr2
1630                     True if both expr1 and expr2 are true.
1631              expr1 -o expr2
1632                     True if either expr1 or expr2 is true.
1633
1634              test and [ evaluate conditional expressions using a set of rules
1635              based on the number of arguments.
1636
1637              0 arguments
1638                     The expression is false.
1639              1 argument
1640                     The expression is true if and only if the argument is not
1641                     null.
1642              2 arguments
1643                     If the first argument is !, the expression is true if and
1644                     only if the second argument is null.  If the first  argu‐
1645                     ment  is  one  of  the unary conditional operators listed
1646                     above under CONDITIONAL EXPRESSIONS,  the  expression  is
1647                     true if the unary test is true.  If the first argument is
1648                     not a valid unary conditional operator, the expression is
1649                     false.
1650              3 arguments
1651                     The following conditions are applied in the order listed.
1652                     If the second argument is one of the  binary  conditional
1653                     operators listed above under CONDITIONAL EXPRESSIONS, the
1654                     result of the expression is the result of the binary test
1655                     using  the first and third arguments as operands.  The -a
1656                     and -o operators are  considered  binary  operators  when
1657                     there  are  three arguments.  If the first argument is !,
1658                     the value is the negation of the two-argument test  using
1659                     the second and third arguments.  If the first argument is
1660                     exactly ( and the third argument is exactly ), the result
1661                     is  the one-argument test of the second argument.  Other‐
1662                     wise, the expression is false.
1663              4 arguments
1664                     If the first argument is !, the result is the negation of
1665                     the  three-argument  expression composed of the remaining
1666                     arguments.  Otherwise, the expression is parsed and eval‐
1667                     uated  according  to  precedence  using  the rules listed
1668                     above.
1669              5 or more arguments
1670                     The expression  is  parsed  and  evaluated  according  to
1671                     precedence using the rules listed above.
1672
1673              When  used  with  test  or [, the < and > operators sort lexico‐
1674              graphically using ASCII ordering.
1675
1676       times  Print the accumulated user and system times for  the  shell  and
1677              for processes run from the shell.  The return status is 0.
1678
1679       trap [-lp] [[arg] sigspec ...]
1680              The  command  arg  is  to  be  read  and executed when the shell
1681              receives signal(s) sigspec.  If arg is absent (and  there  is  a
1682              single  sigspec)  or  -,  each  specified signal is reset to its
1683              original disposition (the value it  had  upon  entrance  to  the
1684              shell).   If arg is the null string the signal specified by each
1685              sigspec is ignored by the shell and by the commands it  invokes.
1686              If  arg  is  not present and -p has been supplied, then the trap
1687              commands associated with each  sigspec  are  displayed.   If  no
1688              arguments  are  supplied or if only -p is given, trap prints the
1689              list of commands associated with each  signal.   The  -l  option
1690              causes  the shell to print a list of signal names and their cor‐
1691              responding numbers.   Each  sigspec  is  either  a  signal  name
1692              defined  in  <signal.h>,  or  a signal number.  Signal names are
1693              case insensitive and the SIG prefix is optional.
1694
1695              If a sigspec is EXIT (0) the command arg  is  executed  on  exit
1696              from  the shell.  If a sigspec is DEBUG, the command arg is exe‐
1697              cuted before every simple command, for  command,  case  command,
1698              select  command,  every  arithmetic  for command, and before the
1699              first command executes in a shell function  (see  SHELL  GRAMMAR
1700              above).   Refer to the description of the extdebug option to the
1701              shopt builtin for details of its effect on the DEBUG trap.  If a
1702              sigspec is RETURN, the command arg is executed each time a shell
1703              function or a script executed with the . or source builtins fin‐
1704              ishes executing.
1705
1706              If  a  sigspec  is  ERR,  the command arg is executed whenever a
1707              pipeline (which may consist of a single simple command), a list,
1708              or a compound command returns a non-zero exit status, subject to
1709              the following conditions.  The ERR trap is not executed  if  the
1710              failed command is part of the command list immediately following
1711              a while or until keyword, part of the test in an  if  statement,
1712              part of a command executed in a && or || list except the command
1713              following the final && or ||, any command in a pipeline but  the
1714              last,  or  if the command's return value is being inverted using
1715              !.  These are the same conditions obeyed  by  the  errexit  (-e)
1716              option.
1717
1718              Signals ignored upon entry to the shell cannot be trapped, reset
1719              or listed.  Trapped signals that are not being ignored are reset
1720              to  their  original values in a subshell or subshell environment
1721              when one is created.  The return status is false if any  sigspec
1722              is invalid; otherwise trap returns true.
1723
1724       type [-aftpP] name [name ...]
1725              With  no options, indicate how each name would be interpreted if
1726              used as a command name.  If the -t option is used, type prints a
1727              string  which  is  one  of alias, keyword, function, builtin, or
1728              file if  name  is  an  alias,  shell  reserved  word,  function,
1729              builtin,  or disk file, respectively.  If the name is not found,
1730              then nothing  is  printed,  and  an  exit  status  of  false  is
1731              returned.   If  the  -p  option is used, type either returns the
1732              name of the disk file that would be executed if name were speci‐
1733              fied as a command name, or nothing if ``type -t name'' would not
1734              return file.  The -P option forces a PATH search for each  name,
1735              even if ``type -t name'' would not return file.  If a command is
1736              hashed, -p and -P print the hashed value, which is not necessar‐
1737              ily  the  file  that appears first in PATH.  If the -a option is
1738              used, type prints all of the places that contain  an  executable
1739              named name.  This includes aliases and functions, if and only if
1740              the -p option is not also used.  The table of hashed commands is
1741              not  consulted  when  using  -a.  The -f option suppresses shell
1742              function lookup, as with the command builtin.  type returns true
1743              if all of the arguments are found, false if any are not found.
1744
1745       ulimit [-HSabcdefiklmnpqrstuvxPT [limit]]
1746              Provides  control  over the resources available to the shell and
1747              to processes started by it, on systems that allow such  control.
1748              The -H and -S options specify that the hard or soft limit is set
1749              for the given resource.  A hard limit cannot be increased  by  a
1750              non-root  user  once it is set; a soft limit may be increased up
1751              to the value of the hard limit.  If neither -H nor -S is  speci‐
1752              fied, both the soft and hard limits are set.  The value of limit
1753              can be a number in the unit specified for the resource or one of
1754              the special values hard, soft, or unlimited, which stand for the
1755              current hard limit,  the  current  soft  limit,  and  no  limit,
1756              respectively.   If  limit  is  omitted, the current value of the
1757              soft limit of the resource is printed, unless the -H  option  is
1758              given.  When more than one resource is specified, the limit name
1759              and unit are printed before the value.  Other options are inter‐
1760              preted as follows:
1761              -a     All current limits are reported
1762              -b     The maximum socket buffer size
1763              -c     The maximum size of core files created
1764              -d     The maximum size of a process's data segment
1765              -e     The maximum scheduling priority ("nice")
1766              -f     The  maximum  size  of files written by the shell and its
1767                     children
1768              -i     The maximum number of pending signals
1769              -k     The maximum number of kqueues that may be allocated
1770              -l     The maximum size that may be locked into memory
1771              -m     The maximum resident set size (many systems do not  honor
1772                     this limit)
1773              -n     The maximum number of open file descriptors (most systems
1774                     do not allow this value to be set)
1775              -p     The pipe size in 512-byte blocks (this may not be set)
1776              -q     The maximum number of bytes in POSIX message queues
1777              -r     The maximum real-time scheduling priority
1778              -s     The maximum stack size
1779              -t     The maximum amount of cpu time in seconds
1780              -u     The maximum number of processes  available  to  a  single
1781                     user
1782              -v     The  maximum  amount  of  virtual memory available to the
1783                     shell and, on some systems, to its children
1784              -x     The maximum number of file locks
1785              -P     The maximum number of pseudoterminals
1786              -T     The maximum number of threads
1787
1788              If limit is given, and the -a option is not used, limit  is  the
1789              new  value  of  the  specified resource.  If no option is given,
1790              then -f is assumed.  Values are in 1024-byte increments,  except
1791              for  -t,  which is in seconds; -p, which is in units of 512-byte
1792              blocks; -P, -T, -b, -k, -n, and -u, which are  unscaled  values;
1793              and, when in posix mode, -c and -f, which are in 512-byte incre‐
1794              ments.  The return status is 0 unless an invalid option or argu‐
1795              ment  is supplied, or an error occurs while setting a new limit.
1796              In POSIX Mode 512-byte blocks are used for  the  `-c'  and  `-f'
1797              options.
1798
1799       umask [-p] [-S] [mode]
1800              The user file-creation mask is set to mode.  If mode begins with
1801              a digit, it is interpreted as an octal number; otherwise  it  is
1802              interpreted  as a symbolic mode mask similar to that accepted by
1803              chmod(1).  If mode is omitted, the current value of the mask  is
1804              printed.   The  -S  option causes the mask to be printed in sym‐
1805              bolic form; the default output is an octal number.   If  the  -p
1806              option is supplied, and mode is omitted, the output is in a form
1807              that may be reused as input.  The return status is 0 if the mode
1808              was  successfully  changed  or if no mode argument was supplied,
1809              and false otherwise.
1810
1811       unalias [-a] [name ...]
1812              Remove each name from the list of defined  aliases.   If  -a  is
1813              supplied,  all  alias definitions are removed.  The return value
1814              is true unless a supplied name is not a defined alias.
1815
1816       unset [-fv] [-n] [name ...]
1817              For each name, remove the corresponding  variable  or  function.
1818              If the -v option is given, each name refers to a shell variable,
1819              and that variable is removed.  Read-only variables  may  not  be
1820              unset.   If  -f  is specified, each name refers to a shell func‐
1821              tion, and the function definition is removed.  If the -n  option
1822              is  supplied, and name is a variable with the nameref attribute,
1823              name will be unset rather than the variable it  references.   -n
1824              has  no  effect if the -f option is supplied.  If no options are
1825              supplied, each name refers to a variable; if there is  no  vari‐
1826              able  by  that name, any function with that name is unset.  Each
1827              unset variable or  function  is  removed  from  the  environment
1828              passed  to subsequent commands.  If any of COMP_WORDBREAKS, RAN‐
1829              DOM, SECONDS, LINENO, HISTCMD, FUNCNAME, GROUPS, or DIRSTACK are
1830              unset, they lose their special properties, even if they are sub‐
1831              sequently reset.  The exit status is true unless a name is read‐
1832              only.
1833
1834       wait [-fn] [id ...]
1835              Wait for each specified child process and return its termination
1836              status.  Each id may be a process ID or a job specification;  if
1837              a  job  spec  is given, all processes in that job's pipeline are
1838              waited for.  If id is not given, all currently active child pro‐
1839              cesses are waited for, and the return status is zero.  If the -n
1840              option is supplied, wait waits for  any  job  to  terminate  and
1841              returns  its exit status.  If the -f option is supplied, and job
1842              control is enabled, wait forces id to terminate before returning
1843              its  status, instead of returning when it changes status.  If id
1844              specifies a non-existent process or job, the  return  status  is
1845              127.   Otherwise,  the  return  status is the exit status of the
1846              last process or job waited for.
1847

SEE ALSO

1849       bash(1), sh(1)
1850
1851
1852
1853GNU Bash 5.0                      2004 Apr 20                 BASH_BUILTINS(1)
Impressum