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

NAME

6       bash - GNU Bourne-Again SHell
7

SYNOPSIS

9       bash [options] [command_string | file]
10
12       Bash is Copyright (C) 1989-2020 by the Free Software Foundation, Inc.
13

DESCRIPTION

15       Bash  is  an  sh-compatible  command language interpreter that executes
16       commands read from the standard input or from a file.  Bash also incor‐
17       porates useful features from the Korn and C shells (ksh and csh).
18
19       Bash  is  intended  to  be a conformant implementation of the Shell and
20       Utilities portion  of  the  IEEE  POSIX  specification  (IEEE  Standard
21       1003.1).  Bash can be configured to be POSIX-conformant by default.
22

OPTIONS

24       All of the single-character shell options documented in the description
25       of the set builtin command, including -o, can be used as  options  when
26       the  shell  is invoked.  In addition, bash interprets the following op‐
27       tions when it is invoked:
28
29       -c        If the -c option is present, then commands are read from  the
30                 first non-option argument command_string.  If there are argu‐
31                 ments after the command_string, the  first  argument  is  as‐
32                 signed  to $0 and any remaining arguments are assigned to the
33                 positional parameters.  The assignment to $0 sets the name of
34                 the shell, which is used in warning and error messages.
35       -i        If the -i option is present, the shell is interactive.
36       -l        Make bash act as if it had been invoked as a login shell (see
37                 INVOCATION below).
38       -r        If the -r option is present,  the  shell  becomes  restricted
39                 (see RESTRICTED SHELL below).
40       -s        If  the -s option is present, or if no arguments remain after
41                 option processing, then commands are read from  the  standard
42                 input.   This  option  allows the positional parameters to be
43                 set when invoking an interactive shell or when reading  input
44                 through a pipe.
45       -D        A  list of all double-quoted strings preceded by $ is printed
46                 on the standard output.  These are the strings that are  sub‐
47                 ject to language translation when the current locale is not C
48                 or POSIX.  This implies the -n option; no  commands  will  be
49                 executed.
50       [-+]O [shopt_option]
51                 shopt_option  is  one  of  the  shell options accepted by the
52                 shopt  builtin  (see  SHELL  BUILTIN  COMMANDS  below).    If
53                 shopt_option is present, -O sets the value of that option; +O
54                 unsets it.  If shopt_option is not supplied,  the  names  and
55                 values  of the shell options accepted by shopt are printed on
56                 the standard output.  If the invocation  option  is  +O,  the
57                 output is displayed in a format that may be reused as input.
58       --        A  --  signals the end of options and disables further option
59                 processing.  Any arguments after the -- are treated as  file‐
60                 names and arguments.  An argument of - is equivalent to --.
61
62       Bash  also  interprets  a number of multi-character options.  These op‐
63       tions must appear on the command line before the  single-character  op‐
64       tions to be recognized.
65
66       --debugger
67              Arrange for the debugger profile to be executed before the shell
68              starts.  Turns on extended debugging mode (see  the  description
69              of the extdebug option to the shopt builtin below).
70       --dump-po-strings
71              Equivalent  to -D, but the output is in the GNU gettext po (por‐
72              table object) file format.
73       --dump-strings
74              Equivalent to -D.
75       --help Display a usage message on standard  output  and  exit  success‐
76              fully.
77       --init-file file
78       --rcfile file
79              Execute commands from file instead of the standard personal ini‐
80              tialization file ~/.bashrc if the shell is interactive (see  IN‐
81              VOCATION below).
82
83       --login
84              Equivalent to -l.
85
86       --noediting
87              Do  not  use the GNU readline library to read command lines when
88              the shell is interactive.
89
90       --noprofile
91              Do not read either the system-wide startup file /etc/profile  or
92              any   of  the  personal  initialization  files  ~/.bash_profile,
93              ~/.bash_login, or ~/.profile.   By  default,  bash  reads  these
94              files  when  it  is invoked as a login shell (see INVOCATION be‐
95              low).
96
97       --norc Do  not  read  and  execute  the  personal  initialization  file
98              ~/.bashrc if the shell is interactive.  This option is on by de‐
99              fault if the shell is invoked as sh.
100
101       --posix
102              Change the behavior of bash where the default operation  differs
103              from the POSIX standard to match the standard (posix mode).  See
104              SEE ALSO below for a reference to a document  that  details  how
105              posix mode affects bash's behavior.
106
107       --restricted
108              The shell becomes restricted (see RESTRICTED SHELL below).
109
110       --rpm-requires
111              Produce the list of files that are required for the shell script
112              to run.  This implies '-n' and is subject to  the  same  limita‐
113              tions as compile time error checking checking; Command substitu‐
114              tions, Conditional expressions and eval builtin are  not  parsed
115              so some dependencies may be missed.
116
117       --verbose
118              Equivalent to -v.
119
120       --version
121              Show  version information for this instance of bash on the stan‐
122              dard output and exit successfully.
123

ARGUMENTS

125       If arguments remain after option processing, and neither the -c nor the
126       -s  option  has  been supplied, the first argument is assumed to be the
127       name of a file containing shell commands.  If bash is invoked  in  this
128       fashion,  $0 is set to the name of the file, and the positional parame‐
129       ters are set to the remaining arguments.  Bash reads and executes  com‐
130       mands  from this file, then exits.  Bash's exit status is the exit sta‐
131       tus of the last command executed in the script.  If no commands are ex‐
132       ecuted,  the  exit  status  is 0.  An attempt is first made to open the
133       file in the current directory, and, if no file is found, then the shell
134       searches the directories in PATH for the script.
135

INVOCATION

137       A  login shell is one whose first character of argument zero is a -, or
138       one started with the --login option.
139
140       An interactive shell is one started without non-option  arguments  (un‐
141       less  -s  is  specified) and without the -c option whose standard input
142       and error are both connected to terminals (as determined by isatty(3)),
143       or  one  started  with  the -i option.  PS1 is set and $- includes i if
144       bash is interactive, allowing a shell script or a startup file to  test
145       this state.
146
147       The  following paragraphs describe how bash executes its startup files.
148       If any of the files exist but cannot be read, bash  reports  an  error.
149       Tildes  are expanded in filenames as described below under Tilde Expan‐
150       sion in the EXPANSION section.
151
152       When bash is invoked as an interactive login shell, or as a  non-inter‐
153       active  shell with the --login option, it first reads and executes com‐
154       mands from the file /etc/profile, if that file exists.   After  reading
155       that file, it looks for ~/.bash_profile, ~/.bash_login, and ~/.profile,
156       in that order, and reads and executes commands from the first one  that
157       exists  and  is  readable.  The --noprofile option may be used when the
158       shell is started to inhibit this behavior.
159
160       When an interactive login shell exits, or a non-interactive login shell
161       executes  the  exit  builtin  command, bash reads and executes commands
162       from the files ~/.bash_logout and /etc/bash.bash_logout, if  the  files
163       exists.
164
165       When  an  interactive  shell that is not a login shell is started, bash
166       reads and executes commands from ~/.bashrc, if that file exists.   This
167       may  be inhibited by using the --norc option.  The --rcfile file option
168       will force bash to read and  execute  commands  from  file  instead  of
169       ~/.bashrc.
170
171       When  bash is started non-interactively, to run a shell script, for ex‐
172       ample, it looks for the variable BASH_ENV in the  environment,  expands
173       its  value if it appears there, and uses the expanded value as the name
174       of a file to read and execute.  Bash behaves as if the  following  com‐
175       mand were executed:
176              if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
177       but  the value of the PATH variable is not used to search for the file‐
178       name.
179
180       If bash is invoked with the name sh, it tries to mimic the startup  be‐
181       havior  of historical versions of sh as closely as possible, while con‐
182       forming to the POSIX standard as well.  When invoked as an  interactive
183       login  shell,  or  a  non-interactive shell with the --login option, it
184       first attempts to read  and  execute  commands  from  /etc/profile  and
185       ~/.profile,  in  that order.  The --noprofile option may be used to in‐
186       hibit this behavior.  When invoked as an  interactive  shell  with  the
187       name  sh,  bash  looks for the variable ENV, expands its value if it is
188       defined, and uses the expanded value as the name of a file to read  and
189       execute.  Since a shell invoked as sh does not attempt to read and exe‐
190       cute commands from any other startup files, the --rcfile option has  no
191       effect.   A non-interactive shell invoked with the name sh does not at‐
192       tempt to read any other startup files.  When invoked as sh, bash enters
193       posix mode after the startup files are read.
194
195       When  bash  is  started in posix mode, as with the --posix command line
196       option, it follows the POSIX standard for startup files.  In this mode,
197       interactive  shells  expand  the ENV variable and commands are read and
198       executed from the file whose name is  the  expanded  value.   No  other
199       startup files are read.
200
201       Bash attempts to determine when it is being run with its standard input
202       connected to a network connection, as when executed by the remote shell
203       daemon,  usually rshd, or the secure shell daemon sshd.  If bash deter‐
204       mines it is being run in this fashion, it reads and  executes  commands
205       from  ~/.bashrc,  if  that file exists and is readable.  It will not do
206       this if invoked as sh.  The --norc option may be used to  inhibit  this
207       behavior,  and the --rcfile option may be used to force another file to
208       be read, but neither rshd nor sshd  generally  invoke  the  shell  with
209       those options or allow them to be specified.
210
211       If the shell is started with the effective user (group) id not equal to
212       the real user (group) id, and the -p option is not supplied, no startup
213       files are read, shell functions are not inherited from the environment,
214       the SHELLOPTS, BASHOPTS, CDPATH, and GLOBIGNORE variables, if they  ap‐
215       pear  in the environment, are ignored, and the effective user id is set
216       to the real user id.  If the -p option is supplied at  invocation,  the
217       startup behavior is the same, but the effective user id is not reset.
218

DEFINITIONS

220       The  following  definitions  are used throughout the rest of this docu‐
221       ment.
222       blank  A space or tab.
223       word   A sequence of characters considered as  a  single  unit  by  the
224              shell.  Also known as a token.
225       name   A  word  consisting  only  of alphanumeric characters and under‐
226              scores, and beginning with an alphabetic character or an  under‐
227              score.  Also referred to as an identifier.
228       metacharacter
229              A  character  that,  when unquoted, separates words.  One of the
230              following:
231              |  & ; ( ) < > space tab newline
232       control operator
233              A token that performs a control function.  It is one of the fol‐
234              lowing symbols:
235              || & && ; ;; ;& ;;& ( ) | |& <newline>
236

RESERVED WORDS

238       Reserved words are words that have a special meaning to the shell.  The
239       following words are recognized as reserved when unquoted and either the
240       first  word of a command (see SHELL GRAMMAR below), the third word of a
241       case or select command (only in is valid), or the third word of  a  for
242       command (only in and do are valid):
243
244       !  case   coproc   do  done elif else esac fi for function if in select
245       then until while { } time [[ ]]
246

SHELL GRAMMAR

248   Simple Commands
249       A simple command is a sequence of optional  variable  assignments  fol‐
250       lowed  by  blank-separated  words and redirections, and terminated by a
251       control operator.  The first word specifies the command to be executed,
252       and  is passed as argument zero.  The remaining words are passed as ar‐
253       guments to the invoked command.
254
255       The return value of a simple command is its exit status,  or  128+n  if
256       the command is terminated by signal n.
257
258   Pipelines
259       A  pipeline  is  a sequence of one or more commands separated by one of
260       the control operators | or |&.  The format for a pipeline is:
261
262              [time [-p]] [ ! ] command [ [||&] command2 ... ]
263
264       The standard output of command is connected via a pipe to the  standard
265       input  of  command2.   This connection is performed before any redirec‐
266       tions specified by the command (see REDIRECTION below).  If |& is used,
267       command's  standard  error, in addition to its standard output, is con‐
268       nected to command2's standard input through the pipe; it  is  shorthand
269       for  2>&1  |.   This  implicit redirection of the standard error to the
270       standard output is performed after any redirections  specified  by  the
271       command.
272
273       The return status of a pipeline is the exit status of the last command,
274       unless the pipefail option is enabled.  If  pipefail  is  enabled,  the
275       pipeline's  return  status is the value of the last (rightmost) command
276       to exit with a non-zero status, or zero if all commands  exit  success‐
277       fully.  If the reserved word !  precedes a pipeline, the exit status of
278       that pipeline is the logical negation of the exit status  as  described
279       above.   The  shell waits for all commands in the pipeline to terminate
280       before returning a value.
281
282       If the time reserved word precedes a pipeline, the elapsed as  well  as
283       user  and  system  time consumed by its execution are reported when the
284       pipeline terminates.  The -p option changes the output format  to  that
285       specified  by POSIX.  When the shell is in posix mode, it does not rec‐
286       ognize time as a reserved word if the next token  begins  with  a  `-'.
287       The  TIMEFORMAT  variable  may be set to a format string that specifies
288       how the timing information should be displayed; see the description  of
289       TIMEFORMAT under Shell Variables below.
290
291       When the shell is in posix mode, time may be followed by a newline.  In
292       this case, the shell displays the total user and system  time  consumed
293       by  the shell and its children.  The TIMEFORMAT variable may be used to
294       specify the format of the time information.
295
296       Each command in a pipeline is executed as a separate process (i.e.,  in
297       a  subshell).  See COMMAND EXECUTION ENVIRONMENT for a description of a
298       subshell environment.  If the lastpipe  option  is  enabled  using  the
299       shopt builtin (see the description of shopt below), the last element of
300       a pipeline may be run by the shell process.
301
302   Lists
303       A list is a sequence of one or more pipelines separated by one  of  the
304       operators ;, &, &&, or ||, and optionally terminated by one of ;, &, or
305       <newline>.
306
307       Of these list operators, && and || have equal precedence, followed by ;
308       and &, which have equal precedence.
309
310       A  sequence  of  one or more newlines may appear in a list instead of a
311       semicolon to delimit commands.
312
313       If a command is terminated by the control operator &,  the  shell  exe‐
314       cutes  the command in the background in a subshell.  The shell does not
315       wait for the command to finish, and the return status is 0.  These  are
316       referred  to  as  asynchronous commands.  Commands separated by a ; are
317       executed sequentially; the shell waits for each command to terminate in
318       turn.   The  return  status is the exit status of the last command exe‐
319       cuted.
320
321       AND and OR lists are sequences of one or more  pipelines  separated  by
322       the  &&  and  || control operators, respectively.  AND and OR lists are
323       executed with left associativity.  An AND list has the form
324
325              command1 && command2
326
327       command2 is executed if, and only if, command1 returns an  exit  status
328       of zero (success).
329
330       An OR list has the form
331
332              command1 || command2
333
334       command2  is executed if, and only if, command1 returns a non-zero exit
335       status.  The return status of AND and OR lists is the  exit  status  of
336       the last command executed in the list.
337
338   Compound Commands
339       A  compound command is one of the following.  In most cases a list in a
340       command's description may be separated from the rest of the command  by
341       one  or  more  newlines, and may be followed by a newline in place of a
342       semicolon.
343
344       (list) list is executed in a subshell environment (see  COMMAND  EXECU‐
345              TION  ENVIRONMENT below).  Variable assignments and builtin com‐
346              mands that affect the shell's environment do not remain  in  ef‐
347              fect after the command completes.  The return status is the exit
348              status of list.
349
350       { list; }
351              list is simply executed in the current shell environment.   list
352              must  be  terminated with a newline or semicolon.  This is known
353              as a group command.  The return status is  the  exit  status  of
354              list.   Note that unlike the metacharacters ( and ), { and } are
355              reserved words and must occur where a reserved word is permitted
356              to  be  recognized.   Since they do not cause a word break, they
357              must be separated from  list  by  whitespace  or  another  shell
358              metacharacter.
359
360       ((expression))
361              The expression is evaluated according to the rules described be‐
362              low under ARITHMETIC EVALUATION.  If the value of the expression
363              is non-zero, the return status is 0; otherwise the return status
364              is 1.  This is exactly equivalent to let "expression".
365
366       [[ expression ]]
367              Return a status of 0 or 1 depending on  the  evaluation  of  the
368              conditional  expression expression.  Expressions are composed of
369              the primaries described  below  under  CONDITIONAL  EXPRESSIONS.
370              Word  splitting  and pathname expansion are not performed on the
371              words between the [[ and  ]];  tilde  expansion,  parameter  and
372              variable  expansion, arithmetic expansion, command substitution,
373              process substitution, and quote removal are  performed.   Condi‐
374              tional operators such as -f must be unquoted to be recognized as
375              primaries.
376
377              When used with [[, the < and > operators sort  lexicographically
378              using the current locale.
379
380              When  the  == and != operators are used, the string to the right
381              of the operator is considered a pattern and matched according to
382              the rules described below under Pattern Matching, as if the ext‐
383              glob shell option were enabled.  The = operator is equivalent to
384              ==.   If  the  nocasematch shell option is enabled, the match is
385              performed without regard to the case of  alphabetic  characters.
386              The  return  value  is  0 if the string matches (==) or does not
387              match (!=) the pattern, and 1 otherwise.  Any part of  the  pat‐
388              tern  may be quoted to force the quoted portion to be matched as
389              a string.
390
391              An additional binary operator, =~, is available, with  the  same
392              precedence  as  ==  and  !=.  When it is used, the string to the
393              right of the operator is considered a POSIX extended regular ex‐
394              pression  and  matched  accordingly (using the POSIX regcomp and
395              regexec interfaces usually described in regex(3)).   The  return
396              value  is  0 if the string matches the pattern, and 1 otherwise.
397              If the regular expression is syntactically incorrect, the condi‐
398              tional expression's return value is 2.  If the nocasematch shell
399              option is enabled, the match is performed without regard to  the
400              case  of  alphabetic characters.  Any part of the pattern may be
401              quoted to force the quoted portion to be matched  as  a  string.
402              Bracket expressions in regular expressions must be treated care‐
403              fully, since normal quoting characters lose their  meanings  be‐
404              tween  brackets.   If the pattern is stored in a shell variable,
405              quoting the variable expansion forces the entire pattern  to  be
406              matched as a string.
407
408              The  pattern  will  match  if it matches any part of the string.
409              Anchor the pattern using the ^ and $ regular  expression  opera‐
410              tors to force it to match the entire string.  The array variable
411              BASH_REMATCH records which parts of the string matched the  pat‐
412              tern.   The  element  of  BASH_REMATCH with index 0 contains the
413              portion of the string matching the  entire  regular  expression.
414              Substrings  matched  by  parenthesized subexpressions within the
415              regular expression are saved in the remaining  BASH_REMATCH  in‐
416              dices.  The  element of BASH_REMATCH with index n is the portion
417              of the string matching the nth parenthesized subexpression.
418
419              Expressions may  be  combined  using  the  following  operators,
420              listed in decreasing order of precedence:
421
422              ( expression )
423                     Returns  the  value  of  expression.  This may be used to
424                     override the normal precedence of operators.
425              ! expression
426                     True if expression is false.
427              expression1 && expression2
428                     True if both expression1 and expression2 are true.
429              expression1 || expression2
430                     True if either expression1 or expression2 is true.
431
432              The && and || operators do not evaluate expression2 if the value
433              of  expression1  is  sufficient to determine the return value of
434              the entire conditional expression.
435
436       for name [ [ in [ word ... ] ] ; ] do list ; done
437              The list of words following in is expanded, generating a list of
438              items.  The variable name is set to each element of this list in
439              turn, and list is executed each time.  If the in word  is  omit‐
440              ted,  the for command executes list once for each positional pa‐
441              rameter that is set (see PARAMETERS below).  The  return  status
442              is  the  exit  status of the last command that executes.  If the
443              expansion of the items following in results in an empty list, no
444              commands are executed, and the return status is 0.
445
446       for (( expr1 ; expr2 ; expr3 )) ; do list ; done
447              First, the arithmetic expression expr1 is evaluated according to
448              the rules described  below  under  ARITHMETIC  EVALUATION.   The
449              arithmetic  expression  expr2 is then evaluated repeatedly until
450              it evaluates to zero.  Each time expr2 evaluates to  a  non-zero
451              value,  list  is executed and the arithmetic expression expr3 is
452              evaluated.  If any expression is omitted, it behaves  as  if  it
453              evaluates to 1.  The return value is the exit status of the last
454              command in list that is executed, or false if any of the expres‐
455              sions is invalid.
456
457       select name [ in word ] ; do list ; done
458              The list of words following in is expanded, generating a list of
459              items.  The set of expanded words is printed on the standard er‐
460              ror,  each preceded by a number.  If the in word is omitted, the
461              positional parameters are printed (see PARAMETERS  below).   The
462              PS3  prompt  is then displayed and a line read from the standard
463              input.  If the line consists of a number corresponding to one of
464              the displayed words, then the value of name is set to that word.
465              If the line is empty, the words and prompt are displayed  again.
466              If  EOF  is  read,  the command completes.  Any other value read
467              causes name to be set to null.  The line read is  saved  in  the
468              variable REPLY.  The list is executed after each selection until
469              a break command is executed.  The exit status of select  is  the
470              exit  status of the last command executed in list, or zero if no
471              commands were executed.
472
473       case word in [ [(] pattern [ | pattern ] ... ) list ;; ] ... esac
474              A case command first expands word, and tries to match it against
475              each  pattern  in turn, using the matching rules described under
476              Pattern Matching below.  The word is expanded using tilde expan‐
477              sion,  parameter  and  variable expansion, arithmetic expansion,
478              command substitution, process substitution  and  quote  removal.
479              Each pattern examined is expanded using tilde expansion, parame‐
480              ter and variable expansion, arithmetic expansion,  command  sub‐
481              stitution,  and  process substitution.  If the nocasematch shell
482              option is enabled, the match is performed without regard to  the
483              case  of alphabetic characters.  When a match is found, the cor‐
484              responding list is executed.  If the ;;  operator  is  used,  no
485              subsequent  matches are attempted after the first pattern match.
486              Using ;& in place of ;; causes execution to  continue  with  the
487              list  associated  with  the  next set of patterns.  Using ;;& in
488              place of ;; causes the shell to test the next  pattern  list  in
489              the statement, if any, and execute any associated list on a suc‐
490              cessful match, continuing the case statement execution as if the
491              pattern  list  had  not  matched.  The exit status is zero if no
492              pattern matches.  Otherwise, it is the exit status of  the  last
493              command executed in list.
494
495       if list; then list; [ elif list; then list; ] ... [ else list; ] fi
496              The  if  list is executed.  If its exit status is zero, the then
497              list is executed.  Otherwise, each  elif  list  is  executed  in
498              turn,  and  if  its  exit status is zero, the corresponding then
499              list is executed and the command completes.  Otherwise, the else
500              list  is executed, if present.  The exit status is the exit sta‐
501              tus of the last command executed, or zero if no condition tested
502              true.
503
504       while list-1; do list-2; done
505       until list-1; do list-2; done
506              The  while command continuously executes the list list-2 as long
507              as the last command in the list list-1 returns an exit status of
508              zero.   The until command is identical to the while command, ex‐
509              cept that the test is negated: list-2 is executed as long as the
510              last command in list-1 returns a non-zero exit status.  The exit
511              status of the while and until commands is the exit status of the
512              last command executed in list-2, or zero if none was executed.
513
514   Coprocesses
515       A coprocess is a shell command preceded by the coproc reserved word.  A
516       coprocess is executed asynchronously in a subshell, as if  the  command
517       had  been  terminated  with the & control operator, with a two-way pipe
518       established between the executing shell and the coprocess.
519
520       The format for a coprocess is:
521
522              coproc [NAME] command [redirections]
523
524       This creates a coprocess named NAME.  If NAME is not supplied, the  de‐
525       fault name is COPROC.  NAME must not be supplied if command is a simple
526       command (see above); otherwise, it is interpreted as the first word  of
527       the  simple command.  When the coprocess is executed, the shell creates
528       an array variable (see Arrays below) named NAME in the context  of  the
529       executing  shell.   The  standard  output of command is connected via a
530       pipe to a file descriptor in the executing shell,  and  that  file  de‐
531       scriptor is assigned to NAME[0].  The standard input of command is con‐
532       nected via a pipe to a file descriptor in the executing shell, and that
533       file  descriptor  is assigned to NAME[1].  This pipe is established be‐
534       fore any redirections specified by the command (see REDIRECTION below).
535       The file descriptors can be utilized as arguments to shell commands and
536       redirections using standard word expansions.  Other than those  created
537       to  execute command and process substitutions, the file descriptors are
538       not available in subshells.  The process ID of the shell spawned to ex‐
539       ecute the coprocess is available as the value of the variable NAME_PID.
540       The wait builtin command may be used to wait for the coprocess to  ter‐
541       minate.
542
543       Since  the  coprocess is created as an asynchronous command, the coproc
544       command always returns success.  The return status of  a  coprocess  is
545       the exit status of command.
546
547   Shell Function Definitions
548       A  shell function is an object that is called like a simple command and
549       executes a compound command with a new set  of  positional  parameters.
550       Shell functions are declared as follows:
551
552       fname () compound-command [redirection]
553       function fname [()] compound-command [redirection]
554              This defines a function named fname.  The reserved word function
555              is optional.  If the function reserved  word  is  supplied,  the
556              parentheses  are optional.  The body of the function is the com‐
557              pound command compound-command (see  Compound  Commands  above).
558              That  command is usually a list of commands between { and }, but
559              may be any command listed under Compound  Commands  above,  with
560              one  exception:  If  the function reserved word is used, but the
561              parentheses are not supplied, the  braces  are  required.   com‐
562              pound-command  is  executed  whenever  fname is specified as the
563              name of a simple command.  When in posix mode, fname must  be  a
564              valid  shell  name  and  may not be the name of one of the POSIX
565              special builtins.  In default mode, a function name can  be  any
566              unquoted  shell  word that does not contain $.  Any redirections
567              (see REDIRECTION below) specified when a function is defined are
568              performed  when  the function is executed.  The exit status of a
569              function definition is zero unless a syntax error  occurs  or  a
570              readonly  function with the same name already exists.  When exe‐
571              cuted, the exit status of a function is the exit status  of  the
572              last command executed in the body.  (See FUNCTIONS below.)
573

COMMENTS

575       In a non-interactive shell, or an interactive shell in which the inter‐
576       active_comments option to the  shopt  builtin  is  enabled  (see  SHELL
577       BUILTIN  COMMANDS  below), a word beginning with # causes that word and
578       all remaining characters on that line to be  ignored.   An  interactive
579       shell  without  the  interactive_comments option enabled does not allow
580       comments.  The interactive_comments option is on by default in interac‐
581       tive shells.
582

QUOTING

584       Quoting  is used to remove the special meaning of certain characters or
585       words to the shell.  Quoting can be used to disable  special  treatment
586       for special characters, to prevent reserved words from being recognized
587       as such, and to prevent parameter expansion.
588
589       Each of the metacharacters listed above under DEFINITIONS  has  special
590       meaning to the shell and must be quoted if it is to represent itself.
591
592       When  the command history expansion facilities are being used (see HIS‐
593       TORY EXPANSION below), the history expansion character, usually !, must
594       be quoted to prevent history expansion.
595
596       There  are  three  quoting  mechanisms:  the  escape  character, single
597       quotes, and double quotes.
598
599       A non-quoted backslash (\) is the escape character.  It  preserves  the
600       literal value of the next character that follows, with the exception of
601       <newline>.  If a \<newline> pair appears, and the backslash is not  it‐
602       self quoted, the \<newline> is treated as a line continuation (that is,
603       it is removed from the input stream and effectively ignored).
604
605       Enclosing characters in single quotes preserves the  literal  value  of
606       each character within the quotes.  A single quote may not occur between
607       single quotes, even when preceded by a backslash.
608
609       Enclosing characters in double quotes preserves the  literal  value  of
610       all  characters  within the quotes, with the exception of $, `, \, and,
611       when history expansion is enabled, !.  When the shell is in posix mode,
612       the  !  has  no special meaning within double quotes, even when history
613       expansion is enabled.  The characters $  and  `  retain  their  special
614       meaning  within double quotes.  The backslash retains its special mean‐
615       ing only when followed by one of the following characters: $, `, ",  \,
616       or  <newline>.   A  double  quote may be quoted within double quotes by
617       preceding it with a backslash.  If enabled, history expansion  will  be
618       performed  unless  an  !  appearing in double quotes is escaped using a
619       backslash.  The backslash preceding the !  is not removed.
620
621       The special parameters * and @ have  special  meaning  when  in  double
622       quotes (see PARAMETERS below).
623
624       Words of the form $'string' are treated specially.  The word expands to
625       string, with backslash-escaped characters replaced as specified by  the
626       ANSI  C  standard.  Backslash escape sequences, if present, are decoded
627       as follows:
628              \a     alert (bell)
629              \b     backspace
630              \e
631              \E     an escape character
632              \f     form feed
633              \n     new line
634              \r     carriage return
635              \t     horizontal tab
636              \v     vertical tab
637              \\     backslash
638              \'     single quote
639              \"     double quote
640              \?     question mark
641              \nnn   the eight-bit character whose value is  the  octal  value
642                     nnn (one to three octal digits)
643              \xHH   the  eight-bit  character  whose value is the hexadecimal
644                     value HH (one or two hex digits)
645              \uHHHH the Unicode (ISO/IEC 10646) character whose value is  the
646                     hexadecimal value HHHH (one to four hex digits)
647              \UHHHHHHHH
648                     the  Unicode (ISO/IEC 10646) character whose value is the
649                     hexadecimal value HHHHHHHH (one to eight hex digits)
650              \cx    a control-x character
651
652       The expanded result is single-quoted, as if the  dollar  sign  had  not
653       been present.
654
655       A double-quoted string preceded by a dollar sign ($"string") will cause
656       the string to be translated according to the current locale.  The  get‐
657       text  infrastructure  performs  the message catalog lookup and transla‐
658       tion, using the LC_MESSAGES and TEXTDOMAIN  shell  variables.   If  the
659       current  locale  is  C or POSIX, or if there are no translations avail‐
660       able, the dollar sign is ignored.  If the string is translated and  re‐
661       placed, the replacement is double-quoted.
662

PARAMETERS

664       A  parameter is an entity that stores values.  It can be a name, a num‐
665       ber, or one of the special characters listed below under Special Param‐
666       eters.   A variable is a parameter denoted by a name.  A variable has a
667       value and zero or more attributes.  Attributes are assigned  using  the
668       declare builtin command (see declare below in SHELL BUILTIN COMMANDS).
669
670       A parameter is set if it has been assigned a value.  The null string is
671       a valid value.  Once a variable is set, it may be unset only  by  using
672       the unset builtin command (see SHELL BUILTIN COMMANDS below).
673
674       A variable may be assigned to by a statement of the form
675
676              name=[value]
677
678       If  value  is not given, the variable is assigned the null string.  All
679       values undergo tilde expansion, parameter and variable expansion,  com‐
680       mand  substitution, arithmetic expansion, and quote removal (see EXPAN‐
681       SION below).  If the variable has its integer attribute set, then value
682       is evaluated as an arithmetic expression even if the $((...)) expansion
683       is not used (see Arithmetic Expansion below).  Word  splitting  is  not
684       performed,  with the exception of "$@" as explained below under Special
685       Parameters.  Pathname expansion is not  performed.   Assignment  state‐
686       ments  may also appear as arguments to the alias, declare, typeset, ex‐
687       port, readonly, and  local  builtin  commands  (declaration  commands).
688       When in posix mode, these builtins may appear in a command after one or
689       more instances of the  command  builtin  and  retain  these  assignment
690       statement properties.
691
692       In  the context where an assignment statement is assigning a value to a
693       shell variable or array index, the += operator can be used to append to
694       or  add  to  the variable's previous value.  This includes arguments to
695       builtin commands such as  declare  that  accept  assignment  statements
696       (declaration commands).  When += is applied to a variable for which the
697       integer attribute has been set, value is evaluated as an arithmetic ex‐
698       pression and added to the variable's current value, which is also eval‐
699       uated.  When += is applied to an array variable using compound  assign‐
700       ment  (see  Arrays  below), the variable's value is not unset (as it is
701       when using =), and new values are appended to the  array  beginning  at
702       one  greater  than  the  array's  maximum index (for indexed arrays) or
703       added as additional key-value pairs in an associative array.  When  ap‐
704       plied  to  a  string-valued variable, value is expanded and appended to
705       the variable's value.
706
707       A variable can be assigned the nameref attribute using the -n option to
708       the  declare or local builtin commands (see the descriptions of declare
709       and local below) to create a nameref, or a reference to  another  vari‐
710       able.   This  allows  variables to be manipulated indirectly.  Whenever
711       the nameref variable is referenced, assigned to, unset, or has its  at‐
712       tributes  modified  (other than using or changing the nameref attribute
713       itself), the operation is actually performed on the variable  specified
714       by  the  nameref  variable's  value.  A nameref is commonly used within
715       shell functions to refer to a variable whose name is passed as an argu‐
716       ment  to the function.  For instance, if a variable name is passed to a
717       shell function as its first argument, running
718              declare -n ref=$1
719       inside the function creates a nameref variable ref whose value  is  the
720       variable name passed as the first argument.  References and assignments
721       to ref, and changes to its attributes, are treated as  references,  as‐
722       signments,  and  attribute modifications to the variable whose name was
723       passed as $1.  If the control variable in a for loop  has  the  nameref
724       attribute,  the  list  of words can be a list of shell variables, and a
725       name reference will be established for each word in the list, in  turn,
726       when the loop is executed.  Array variables cannot be given the nameref
727       attribute.  However, nameref variables can  reference  array  variables
728       and  subscripted  array  variables.  Namerefs can be unset using the -n
729       option to the unset builtin.  Otherwise, if unset is executed with  the
730       name  of  a nameref variable as an argument, the variable referenced by
731       the nameref variable will be unset.
732
733   Positional Parameters
734       A positional parameter is a parameter denoted by one  or  more  digits,
735       other than the single digit 0.  Positional parameters are assigned from
736       the shell's arguments when it is invoked, and may be  reassigned  using
737       the  set builtin command.  Positional parameters may not be assigned to
738       with assignment statements.  The positional parameters are  temporarily
739       replaced when a shell function is executed (see FUNCTIONS below).
740
741       When  a  positional parameter consisting of more than a single digit is
742       expanded, it must be enclosed in braces (see EXPANSION below).
743
744   Special Parameters
745       The shell treats several parameters specially.   These  parameters  may
746       only be referenced; assignment to them is not allowed.
747       *      Expands  to  the positional parameters, starting from one.  When
748              the expansion is not within double quotes, each  positional  pa‐
749              rameter  expands  to  a  separate word.  In contexts where it is
750              performed, those words are subject to further word splitting and
751              pathname  expansion.   When  the  expansion occurs within double
752              quotes, it expands to a single word with the value of  each  pa‐
753              rameter  separated  by  the  first  character of the IFS special
754              variable.  That is, "$*" is equivalent to "$1c$2c...",  where  c
755              is the first character of the value of the IFS variable.  If IFS
756              is unset, the parameters are separated by  spaces.   If  IFS  is
757              null, the parameters are joined without intervening separators.
758       @      Expands  to  the  positional  parameters, starting from one.  In
759              contexts where word splitting is performed,  this  expands  each
760              positional  parameter  to  a separate word; if not within double
761              quotes, these words are subject to word splitting.  In  contexts
762              where  word splitting is not performed, this expands to a single
763              word with each positional parameter separated by a space.   When
764              the  expansion  occurs  within double quotes, each parameter ex‐
765              pands to a separate word.  That is, "$@" is equivalent  to  "$1"
766              "$2"  ...   If the double-quoted expansion occurs within a word,
767              the expansion of the first parameter is joined with  the  begin‐
768              ning  part  of  the original word, and the expansion of the last
769              parameter is joined with the last part  of  the  original  word.
770              When  there  are no positional parameters, "$@" and $@ expand to
771              nothing (i.e., they are removed).
772       #      Expands to the number of positional parameters in decimal.
773       ?      Expands to the exit status of the most recently  executed  fore‐
774              ground pipeline.
775       -      Expands  to  the  current option flags as specified upon invoca‐
776              tion, by the set builtin command, or those set by the shell  it‐
777              self (such as the -i option).
778       $      Expands  to  the  process ID of the shell.  In a () subshell, it
779              expands to the process ID of the current  shell,  not  the  sub‐
780              shell.
781       !      Expands  to  the process ID of the job most recently placed into
782              the background, whether executed as an asynchronous  command  or
783              using the bg builtin (see JOB CONTROL below).
784       0      Expands  to  the name of the shell or shell script.  This is set
785              at shell initialization.  If bash is invoked with a file of com‐
786              mands,  $0  is set to the name of that file.  If bash is started
787              with the -c option, then $0 is set to the first  argument  after
788              the  string to be executed, if one is present.  Otherwise, it is
789              set to the filename used to invoke bash, as  given  by  argument
790              zero.
791
792   Shell Variables
793       The following variables are set by the shell:
794
795       _      At  shell  startup, set to the pathname used to invoke the shell
796              or shell script being executed as passed in the  environment  or
797              argument  list.   Subsequently,  expands to the last argument to
798              the previous simple command executed in  the  foreground,  after
799              expansion.   Also  set  to the full pathname used to invoke each
800              command executed and placed in the environment exported to  that
801              command.   When  checking mail, this parameter holds the name of
802              the mail file currently being checked.
803       BASH   Expands to the full filename used to  invoke  this  instance  of
804              bash.
805       BASHOPTS
806              A  colon-separated  list of enabled shell options.  Each word in
807              the list is a valid argument for the  -s  option  to  the  shopt
808              builtin command (see SHELL BUILTIN COMMANDS below).  The options
809              appearing in BASHOPTS are those reported as  on  by  shopt.   If
810              this  variable  is  in the environment when bash starts up, each
811              shell option in the list will  be  enabled  before  reading  any
812              startup files.  This variable is read-only.
813       BASHPID
814              Expands  to  the  process  ID of the current bash process.  This
815              differs from $$ under certain circumstances, such  as  subshells
816              that  do  not require bash to be re-initialized.  Assignments to
817              BASHPID have no effect.  If BASHPID is unset, it loses its  spe‐
818              cial properties, even if it is subsequently reset.
819       BASH_ALIASES
820              An  associative  array  variable whose members correspond to the
821              internal list of aliases as maintained  by  the  alias  builtin.
822              Elements  added to this array appear in the alias list; however,
823              unsetting array elements currently does not cause aliases to  be
824              removed from the alias list.  If BASH_ALIASES is unset, it loses
825              its special properties, even if it is subsequently reset.
826       BASH_ARGC
827              An array variable whose values are the number of  parameters  in
828              each frame of the current bash execution call stack.  The number
829              of parameters to  the  current  subroutine  (shell  function  or
830              script  executed  with  . or source) is at the top of the stack.
831              When a subroutine is executed, the number of  parameters  passed
832              is pushed onto BASH_ARGC.  The shell sets BASH_ARGC only when in
833              extended debugging mode (see the description of the extdebug op‐
834              tion  to  the  shopt builtin below).  Setting extdebug after the
835              shell has started to execute a script, or referencing this vari‐
836              able  when  extdebug is not set, may result in inconsistent val‐
837              ues.
838       BASH_ARGV
839              An array variable containing all of the parameters in  the  cur‐
840              rent bash execution call stack.  The final parameter of the last
841              subroutine call is at the top of the stack; the first  parameter
842              of the initial call is at the bottom.  When a subroutine is exe‐
843              cuted, the parameters supplied are pushed onto  BASH_ARGV.   The
844              shell  sets  BASH_ARGV only when in extended debugging mode (see
845              the description of the extdebug option to the shopt builtin  be‐
846              low).  Setting extdebug after the shell has started to execute a
847              script, or referencing this variable when extdebug is  not  set,
848              may result in inconsistent values.
849       BASH_ARGV0
850              When  referenced, this variable expands to the name of the shell
851              or shell script (identical to $0; see the description of special
852              parameter  0  above).  Assignment to BASH_ARGV0 causes the value
853              assigned to also be assigned to $0.  If BASH_ARGV0 is unset,  it
854              loses its special properties, even if it is subsequently reset.
855       BASH_CMDS
856              An  associative  array  variable whose members correspond to the
857              internal hash table  of  commands  as  maintained  by  the  hash
858              builtin.  Elements added to this array appear in the hash table;
859              however, unsetting array elements currently does not cause  com‐
860              mand  names  to be removed from the hash table.  If BASH_CMDS is
861              unset, it loses its special properties, even  if  it  is  subse‐
862              quently reset.
863       BASH_COMMAND
864              The  command  currently  being executed or about to be executed,
865              unless the shell is executing a command as the result of a trap,
866              in  which  case  it  is the command executing at the time of the
867              trap.  If BASH_COMMAND is unset, it loses  its  special  proper‐
868              ties, even if it is subsequently reset.
869       BASH_EXECUTION_STRING
870              The command argument to the -c invocation option.
871       BASH_LINENO
872              An  array  variable whose members are the line numbers in source
873              files where each corresponding member of FUNCNAME  was  invoked.
874              ${BASH_LINENO[$i]}  is  the  line  number  in  the  source  file
875              (${BASH_SOURCE[$i+1]})  where  ${FUNCNAME[$i]}  was  called  (or
876              ${BASH_LINENO[$i-1]}  if  referenced  within another shell func‐
877              tion).  Use LINENO to obtain the current line number.
878       BASH_LOADABLES_PATH
879              A colon-separated list of directories in which the  shell  looks
880              for  dynamically  loadable builtins specified by the enable com‐
881              mand.
882       BASH_REMATCH
883              An array variable whose members are assigned by  the  =~  binary
884              operator  to the [[ conditional command.  The element with index
885              0 is the portion of the string matching the entire  regular  ex‐
886              pression.  The element with index n is the portion of the string
887              matching the nth parenthesized subexpression.
888       BASH_SOURCE
889              An array variable whose members are the source  filenames  where
890              the  corresponding  shell  function  names in the FUNCNAME array
891              variable are defined.  The shell function ${FUNCNAME[$i]} is de‐
892              fined   in   the   file   ${BASH_SOURCE[$i]}   and  called  from
893              ${BASH_SOURCE[$i+1]}.
894       BASH_SUBSHELL
895              Incremented by one within each subshell or subshell  environment
896              when  the  shell begins executing in that environment.  The ini‐
897              tial value is 0.  If BASH_SUBSHELL is unset, it loses  its  spe‐
898              cial properties, even if it is subsequently reset.
899       BASH_VERSINFO
900              A readonly array variable whose members hold version information
901              for this instance of bash.  The values  assigned  to  the  array
902              members are as follows:
903              BASH_VERSINFO[0]        The major version number (the release).
904              BASH_VERSINFO[1]        The minor version number (the version).
905              BASH_VERSINFO[2]        The patch level.
906              BASH_VERSINFO[3]        The build version.
907              BASH_VERSINFO[4]        The release status (e.g., beta1).
908              BASH_VERSINFO[5]        The value of MACHTYPE.
909       BASH_VERSION
910              Expands  to  a string describing the version of this instance of
911              bash.
912       COMP_CWORD
913              An index into ${COMP_WORDS} of the word containing  the  current
914              cursor position.  This variable is available only in shell func‐
915              tions invoked by the  programmable  completion  facilities  (see
916              Programmable Completion below).
917       COMP_KEY
918              The key (or final key of a key sequence) used to invoke the cur‐
919              rent completion function.
920       COMP_LINE
921              The current command line.  This variable is  available  only  in
922              shell  functions  and  external commands invoked by the program‐
923              mable completion facilities (see Programmable Completion below).
924       COMP_POINT
925              The index of the current cursor position relative to the  begin‐
926              ning  of the current command.  If the current cursor position is
927              at the end of the current command, the value of this variable is
928              equal  to  ${#COMP_LINE}.   This  variable  is available only in
929              shell functions and external commands invoked  by  the  program‐
930              mable completion facilities (see Programmable Completion below).
931       COMP_TYPE
932              Set  to an integer value corresponding to the type of completion
933              attempted that caused a completion function to be  called:  TAB,
934              for  normal completion, ?, for listing completions after succes‐
935              sive tabs, !, for listing alternatives on partial  word  comple‐
936              tion,  @,  to list completions if the word is not unmodified, or
937              %, for menu completion.  This  variable  is  available  only  in
938              shell  functions  and  external commands invoked by the program‐
939              mable completion facilities (see Programmable Completion below).
940       COMP_WORDBREAKS
941              The set of characters that the readline library treats  as  word
942              separators  when performing word completion.  If COMP_WORDBREAKS
943              is unset, it loses its special properties, even if it is  subse‐
944              quently reset.
945       COMP_WORDS
946              An  array variable (see Arrays below) consisting of the individ‐
947              ual words in the current command line.  The line is  split  into
948              words  as  readline would split it, using COMP_WORDBREAKS as de‐
949              scribed above.  This variable is available only in  shell  func‐
950              tions  invoked  by  the  programmable completion facilities (see
951              Programmable Completion below).
952       COPROC An array variable (see Arrays below) created to  hold  the  file
953              descriptors  for  output  from and input to an unnamed coprocess
954              (see Coprocesses above).
955       DIRSTACK
956              An array variable (see Arrays below) containing the current con‐
957              tents  of  the directory stack.  Directories appear in the stack
958              in the order they are displayed by the dirs builtin.   Assigning
959              to members of this array variable may be used to modify directo‐
960              ries already in the stack, but the pushd and popd builtins  must
961              be used to add and remove directories.  Assignment to this vari‐
962              able will not change the current directory.  If DIRSTACK is  un‐
963              set, it loses its special properties, even if it is subsequently
964              reset.
965       EPOCHREALTIME
966              Each time this parameter is referenced, it expands to the number
967              of  seconds  since  the  Unix  Epoch (see time(3)) as a floating
968              point  value  with  micro-second  granularity.   Assignments  to
969              EPOCHREALTIME  are ignored.  If EPOCHREALTIME is unset, it loses
970              its special properties, even if it is subsequently reset.
971       EPOCHSECONDS
972              Each time this parameter is referenced, it expands to the number
973              of  seconds  since the Unix Epoch (see time(3)).  Assignments to
974              EPOCHSECONDS are ignored.  If EPOCHSECONDS is  unset,  it  loses
975              its special properties, even if it is subsequently reset.
976       EUID   Expands  to  the effective user ID of the current user, initial‐
977              ized at shell startup.  This variable is readonly.
978       FUNCNAME
979              An array variable containing the names of  all  shell  functions
980              currently in the execution call stack.  The element with index 0
981              is the name of any currently-executing shell function.  The bot‐
982              tom-most  element  (the  one  with the highest index) is "main".
983              This variable exists only when a shell  function  is  executing.
984              Assignments  to  FUNCNAME have no effect.  If FUNCNAME is unset,
985              it loses its special properties, even if it is subsequently  re‐
986              set.
987
988              This  variable  can  be  used  with BASH_LINENO and BASH_SOURCE.
989              Each  element  of  FUNCNAME  has   corresponding   elements   in
990              BASH_LINENO and BASH_SOURCE to describe the call stack.  For in‐
991              stance,   ${FUNCNAME[$i]}   was    called    from    the    file
992              ${BASH_SOURCE[$i+1]}  at  line  number  ${BASH_LINENO[$i]}.  The
993              caller builtin displays the current call stack using this infor‐
994              mation.
995       GROUPS An  array  variable  containing  the list of groups of which the
996              current user is a member.  Assignments to GROUPS have no effect.
997              If  GROUPS is unset, it loses its special properties, even if it
998              is subsequently reset.
999       HISTCMD
1000              The history number, or index in the history list, of the current
1001              command.  Assignments to HISTCMD are ignored.  If HISTCMD is un‐
1002              set, it loses its special properties, even if it is subsequently
1003              reset.
1004       HOSTNAME
1005              Automatically set to the name of the current host.
1006       HOSTTYPE
1007              Automatically  set  to a string that uniquely describes the type
1008              of machine on which bash is executing.  The default  is  system-
1009              dependent.
1010       LINENO Each  time this parameter is referenced, the shell substitutes a
1011              decimal number representing the current sequential  line  number
1012              (starting  with  1)  within a script or function.  When not in a
1013              script or function, the value substituted is not  guaranteed  to
1014              be meaningful.  If LINENO is unset, it loses its special proper‐
1015              ties, even if it is subsequently reset.
1016       MACHTYPE
1017              Automatically set to a string that fully  describes  the  system
1018              type  on  which  bash is executing, in the standard GNU cpu-com‐
1019              pany-system format.  The default is system-dependent.
1020       MAPFILE
1021              An array variable (see Arrays below) created to  hold  the  text
1022              read by the mapfile builtin when no variable name is supplied.
1023       OLDPWD The previous working directory as set by the cd command.
1024       OPTARG The  value  of the last option argument processed by the getopts
1025              builtin command (see SHELL BUILTIN COMMANDS below).
1026       OPTIND The index of the next argument to be processed  by  the  getopts
1027              builtin command (see SHELL BUILTIN COMMANDS below).
1028       OSTYPE Automatically  set to a string that describes the operating sys‐
1029              tem on which bash is executing.  The  default  is  system-depen‐
1030              dent.
1031       PIPESTATUS
1032              An  array  variable (see Arrays below) containing a list of exit
1033              status values from the processes in  the  most-recently-executed
1034              foreground pipeline (which may contain only a single command).
1035       PPID   The  process  ID  of the shell's parent.  This variable is read‐
1036              only.
1037       PWD    The current working directory as set by the cd command.
1038       RANDOM Each time this parameter is referenced, it expands to  a  random
1039              integer  between  0 and 32767.  Assigning a value to RANDOM ini‐
1040              tializes (seeds) the sequence of random numbers.  If  RANDOM  is
1041              unset,  it  loses  its  special properties, even if it is subse‐
1042              quently reset.
1043       READLINE_LINE
1044              The contents of the readline line buffer, for use with "bind -x"
1045              (see SHELL BUILTIN COMMANDS below).
1046       READLINE_MARK
1047              The position of the mark (saved insertion point) in the readline
1048              line buffer, for use with "bind -x" (see SHELL BUILTIN  COMMANDS
1049              below).  The characters between the insertion point and the mark
1050              are often called the region.
1051       READLINE_POINT
1052              The position of the insertion point in the readline line buffer,
1053              for use with "bind -x" (see SHELL BUILTIN COMMANDS below).
1054       REPLY  Set  to  the line of input read by the read builtin command when
1055              no arguments are supplied.
1056       SECONDS
1057              Each time this parameter is referenced, the  number  of  seconds
1058              since  shell  invocation is returned.  If a value is assigned to
1059              SECONDS, the value returned upon subsequent  references  is  the
1060              number  of seconds since the assignment plus the value assigned.
1061              The number of seconds at shell invocation and the  current  time
1062              is  always  determined by querying the system clock.  If SECONDS
1063              is unset, it loses its special properties, even if it is  subse‐
1064              quently reset.
1065       SHELLOPTS
1066              A  colon-separated  list of enabled shell options.  Each word in
1067              the list is a valid argument  for  the  -o  option  to  the  set
1068              builtin command (see SHELL BUILTIN COMMANDS below).  The options
1069              appearing in SHELLOPTS are those reported as on by set  -o.   If
1070              this  variable  is  in the environment when bash starts up, each
1071              shell option in the list will  be  enabled  before  reading  any
1072              startup files.  This variable is read-only.
1073       SHLVL  Incremented by one each time an instance of bash is started.
1074       SRANDOM
1075              This variable expands to a 32-bit pseudo-random number each time
1076              it is referenced. The random number generator is not  linear  on
1077              systems  that  support  /dev/urandom  or arc4random, so each re‐
1078              turned number has no relationship to the numbers  preceding  it.
1079              The  random number generator cannot be seeded, so assignments to
1080              this variable have no effect.  If SRANDOM is unset, it loses its
1081              special properties, even if it is subsequently reset.
1082       UID    Expands to the user ID of the current user, initialized at shell
1083              startup.  This variable is readonly.
1084
1085       The following variables are used by the shell.  In some cases, bash as‐
1086       signs a default value to a variable; these cases are noted below.
1087
1088       BASH_COMPAT
1089              The  value  is used to set the shell's compatibility level.  See
1090              SHELL COMPATIBILITY MODE below for a description of the  various
1091              compatibility levels and their effects.  The value may be a dec‐
1092              imal number (e.g., 4.2) or an integer (e.g.,  42)  corresponding
1093              to  the desired compatibility level.  If BASH_COMPAT is unset or
1094              set to the empty string, the compatibility level is set  to  the
1095              default  for  the  current  version.  If BASH_COMPAT is set to a
1096              value that is not one of the  valid  compatibility  levels,  the
1097              shell  prints  an error message and sets the compatibility level
1098              to the default for the current version.  The valid values corre‐
1099              spond  to the compatibility levels described below under BSHELL‐
1100              COMPATIBILITYMODE.  For example, 4.2 and  42  are  valid  values
1101              that correspond to the compat42 shopt option and set the compat‐
1102              ibility level to 42.  The current version is also a valid value.
1103       BASH_ENV
1104              If this parameter is set when bash is executing a shell  script,
1105              its  value  is  interpreted as a filename containing commands to
1106              initialize the shell, as in ~/.bashrc.  The value of BASH_ENV is
1107              subjected  to  parameter  expansion,  command  substitution, and
1108              arithmetic expansion before being  interpreted  as  a  filename.
1109              PATH is not used to search for the resultant filename.
1110       BASH_XTRACEFD
1111              If  set  to an integer corresponding to a valid file descriptor,
1112              bash will write the trace output generated when set  -x  is  en‐
1113              abled  to  that  file descriptor.  The file descriptor is closed
1114              when BASH_XTRACEFD is unset or assigned a new value.   Unsetting
1115              BASH_XTRACEFD  or assigning it the empty string causes the trace
1116              output to be sent to the  standard  error.   Note  that  setting
1117              BASH_XTRACEFD to 2 (the standard error file descriptor) and then
1118              unsetting it will result in the standard error being closed.
1119       CDPATH The search path for the cd command.  This is  a  colon-separated
1120              list of directories in which the shell looks for destination di‐
1121              rectories specified by  the  cd  command.   A  sample  value  is
1122              ".:~:/usr".
1123       CHILD_MAX
1124              Set  the  number  of exited child status values for the shell to
1125              remember.  Bash will not allow this value to be decreased  below
1126              a  POSIX-mandated  minimum,  and  there is a maximum value (cur‐
1127              rently 8192) that this may not exceed.   The  minimum  value  is
1128              system-dependent.
1129       COLUMNS
1130              Used  by  the  select compound command to determine the terminal
1131              width when printing selection lists.  Automatically set  if  the
1132              checkwinsize  option  is enabled or in an interactive shell upon
1133              receipt of a SIGWINCH.
1134       COMPREPLY
1135              An array variable from which bash reads the possible completions
1136              generated  by  a shell function invoked by the programmable com‐
1137              pletion facility (see Programmable Completion below).  Each  ar‐
1138              ray element contains one possible completion.
1139       EMACS  If  bash  finds  this variable in the environment when the shell
1140              starts with value "t", it assumes that the shell is  running  in
1141              an Emacs shell buffer and disables line editing.
1142       ENV    Expanded  and  executed  similarly  to  BASH_ENV (see INVOCATION
1143              above) when an interactive shell is invoked in posix mode.
1144       EXECIGNORE
1145              A colon-separated list of shell patterns (see Pattern  Matching)
1146              defining  the  list of filenames to be ignored by command search
1147              using PATH.  Files whose full pathnames match one of these  pat‐
1148              terns  are  not  considered executable files for the purposes of
1149              completion and command execution via PATH lookup.  This does not
1150              affect the behavior of the [, test, and [[ commands.  Full path‐
1151              names in the command hash table are not subject  to  EXECIGNORE.
1152              Use  this  variable to ignore shared library files that have the
1153              executable bit set, but are not executable files.   The  pattern
1154              matching honors the setting of the extglob shell option.
1155       FCEDIT The default editor for the fc builtin command.
1156       FIGNORE
1157              A  colon-separated  list  of  suffixes to ignore when performing
1158              filename completion (see READLINE below).  A filename whose suf‐
1159              fix  matches  one of the entries in FIGNORE is excluded from the
1160              list of matched filenames.  A sample value is ".o:~".
1161       FUNCNEST
1162              If set to a numeric value greater  than  0,  defines  a  maximum
1163              function  nesting  level.  Function invocations that exceed this
1164              nesting level will cause the current command to abort.
1165       GLOBIGNORE
1166              A colon-separated list of patterns  defining  the  set  of  file
1167              names  to  be  ignored  by  pathname  expansion.  If a file name
1168              matched by a pathname expansion pattern also matches one of  the
1169              patterns in GLOBIGNORE, it is removed from the list of matches.
1170       HISTCONTROL
1171              A  colon-separated  list  of values controlling how commands are
1172              saved on the history list.  If the list of values  includes  ig‐
1173              norespace,  lines  which  begin  with  a space character are not
1174              saved in the history list.  A value of ignoredups  causes  lines
1175              matching the previous history entry to not be saved.  A value of
1176              ignoreboth is shorthand for ignorespace and ignoredups.  A value
1177              of erasedups causes all previous lines matching the current line
1178              to be removed from the history list before that line  is  saved.
1179              Any  value  not in the above list is ignored.  If HISTCONTROL is
1180              unset, or does not include a valid value, all lines read by  the
1181              shell parser are saved on the history list, subject to the value
1182              of HISTIGNORE.  The second and subsequent lines of a  multi-line
1183              compound  command  are  not tested, and are added to the history
1184              regardless of the value of HISTCONTROL.
1185       HISTFILE
1186              The name of the file in which command history is saved (see HIS‐
1187              TORY  below).   The default value is ~/.bash_history.  If unset,
1188              the command history is not saved when a shell exits.
1189       HISTFILESIZE
1190              The maximum number of lines contained in the history file.  When
1191              this  variable  is  assigned  a value, the history file is trun‐
1192              cated, if necessary, to contain no  more  than  that  number  of
1193              lines  by removing the oldest entries.  The history file is also
1194              truncated to this size after writing it when a shell exits.   If
1195              the  value  is  0,  the  history file is truncated to zero size.
1196              Non-numeric values and numeric values  less  than  zero  inhibit
1197              truncation.   The  shell  sets the default value to the value of
1198              HISTSIZE after reading any startup files.
1199       HISTIGNORE
1200              A colon-separated list of patterns used to decide which  command
1201              lines  should be saved on the history list.  Each pattern is an‐
1202              chored at the beginning of the line and must match the  complete
1203              line  (no  implicit  `*'  is  appended).  Each pattern is tested
1204              against the line after the checks specified by  HISTCONTROL  are
1205              applied.  In addition to the normal shell pattern matching char‐
1206              acters, `&' matches the previous history line.  `&' may  be  es‐
1207              caped  using  a  backslash;  the backslash is removed before at‐
1208              tempting a match.  The second and subsequent lines of  a  multi-
1209              line  compound command are not tested, and are added to the his‐
1210              tory regardless of the value of HISTIGNORE.  The pattern  match‐
1211              ing honors the setting of the extglob shell option.
1212       HISTSIZE
1213              The  number  of commands to remember in the command history (see
1214              HISTORY below).  If the value is 0, commands are  not  saved  in
1215              the history list.  Numeric values less than zero result in every
1216              command being saved on the history list  (there  is  no  limit).
1217              The  shell  sets  the  default  value  to  500 after reading any
1218              startup files.
1219       HISTTIMEFORMAT
1220              If this variable is set and not null, its value  is  used  as  a
1221              format string for strftime(3) to print the time stamp associated
1222              with each history entry displayed by the  history  builtin.   If
1223              this  variable  is  set,  time stamps are written to the history
1224              file so they may be preserved across shell sessions.  This  uses
1225              the  history  comment  character  to distinguish timestamps from
1226              other history lines.
1227       HOME   The home directory of the current user; the default argument for
1228              the cd builtin command.  The value of this variable is also used
1229              when performing tilde expansion.
1230       HOSTFILE
1231              Contains the name of a file in the  same  format  as  /etc/hosts
1232              that should be read when the shell needs to complete a hostname.
1233              The list of possible hostname completions may be  changed  while
1234              the  shell  is running; the next time hostname completion is at‐
1235              tempted after the value is changed, bash adds  the  contents  of
1236              the  new file to the existing list.  If HOSTFILE is set, but has
1237              no value, or does not name a readable  file,  bash  attempts  to
1238              read  /etc/hosts to obtain the list of possible hostname comple‐
1239              tions.  When HOSTFILE is unset, the hostname list is cleared.
1240       IFS    The Internal Field Separator that is used for word splitting af‐
1241              ter  expansion  and  to  split  lines  into  words with the read
1242              builtin  command.   The  default  value  is  ``<space><tab><new‐
1243              line>''.
1244       IGNOREEOF
1245              Controls the action of an interactive shell on receipt of an EOF
1246              character as the sole input.  If set, the value is the number of
1247              consecutive  EOF  characters  which  must  be typed as the first
1248              characters on an input line before bash exits.  If the  variable
1249              exists  but  does not have a numeric value, or has no value, the
1250              default value is 10.  If it does not exist,  EOF  signifies  the
1251              end of input to the shell.
1252       INPUTRC
1253              The  filename  for the readline startup file, overriding the de‐
1254              fault of ~/.inputrc (see READLINE below).
1255       INSIDE_EMACS
1256              If this variable appears  in  the  environment  when  the  shell
1257              starts,  bash  assumes  that it is running inside an Emacs shell
1258              buffer and may disable line editing, depending on the  value  of
1259              TERM.
1260       LANG   Used  to  determine  the  locale  category  for any category not
1261              specifically selected with a variable starting with LC_.
1262       LC_ALL This variable overrides the value of  LANG  and  any  other  LC_
1263              variable specifying a locale category.
1264       LC_COLLATE
1265              This  variable  determines the collation order used when sorting
1266              the results of pathname expansion, and determines  the  behavior
1267              of  range  expressions,  equivalence  classes, and collating se‐
1268              quences within pathname expansion and pattern matching.
1269       LC_CTYPE
1270              This variable determines the interpretation  of  characters  and
1271              the  behavior of character classes within pathname expansion and
1272              pattern matching.
1273       LC_MESSAGES
1274              This variable determines the locale used  to  translate  double-
1275              quoted strings preceded by a $.
1276       LC_NUMERIC
1277              This  variable  determines  the  locale category used for number
1278              formatting.
1279       LC_TIME
1280              This variable determines the locale category used for  data  and
1281              time formatting.
1282       LINES  Used  by  the  select  compound  command to determine the column
1283              length for printing selection lists.  Automatically set  if  the
1284              checkwinsize  option  is enabled or in an interactive shell upon
1285              receipt of a SIGWINCH.
1286       MAIL   If this parameter is set to a file or  directory  name  and  the
1287              MAILPATH  variable  is not set, bash informs the user of the ar‐
1288              rival of mail in the specified file or Maildir-format directory.
1289       MAILCHECK
1290              Specifies how often (in seconds) bash checks for mail.  The  de‐
1291              fault  is  60  seconds.   When it is time to check for mail, the
1292              shell does so before displaying the  primary  prompt.   If  this
1293              variable  is  unset,  or  set  to  a  value that is not a number
1294              greater than or equal to zero, the shell disables mail checking.
1295       MAILPATH
1296              A colon-separated list of filenames to be checked for mail.  The
1297              message to be printed when mail arrives in a particular file may
1298              be specified by separating the filename from the message with  a
1299              `?'.   When  used  in the text of the message, $_ expands to the
1300              name of the current mailfile.  Example:
1301              MAILPATH='/var/mail/bfox?"You  have  mail":~/shell-mail?"$_  has
1302              mail!"'
1303              Bash  can be configured to supply a default value for this vari‐
1304              able (there is no value by default), but  the  location  of  the
1305              user  mail  files  that  it  uses  is  system  dependent  (e.g.,
1306              /var/mail/$USER).
1307       OPTERR If set to the value 1, bash displays error messages generated by
1308              the  getopts builtin command (see SHELL BUILTIN COMMANDS below).
1309              OPTERR is initialized to 1 each time the shell is invoked  or  a
1310              shell script is executed.
1311       PATH   The  search  path for commands.  It is a colon-separated list of
1312              directories in which the shell looks for commands  (see  COMMAND
1313              EXECUTION  below).   A  zero-length (null) directory name in the
1314              value of PATH indicates the current directory.  A null directory
1315              name  may  appear  as  two  adjacent colons, or as an initial or
1316              trailing colon.  The default path is  system-dependent,  and  is
1317              set by the administrator who installs bash.  A common value is
1318              ``/usr/local/bin:/usr/lo‐
1319              cal/sbin:/usr/bin:/usr/sbin:/bin:/sbin''.
1320       POSIXLY_CORRECT
1321              If  this  variable  is  in the environment when bash starts, the
1322              shell enters posix mode before reading the startup files, as  if
1323              the  --posix  invocation option had been supplied.  If it is set
1324              while the shell is running, bash enables posix mode, as  if  the
1325              command  set  -o posix had been executed.  When the shell enters
1326              posix mode, it sets this variable if it was not already set.
1327       PROMPT_COMMAND
1328              If this variable is set, and is an array, the value of each  set
1329              element  is  executed as a command prior to issuing each primary
1330              prompt.  If this is set but not an array variable, its value  is
1331              used as a command to execute instead.
1332       PROMPT_DIRTRIM
1333              If  set  to a number greater than zero, the value is used as the
1334              number of trailing directory components to retain when expanding
1335              the  \w  and  \W  prompt  string  escapes (see PROMPTING below).
1336              Characters removed are replaced with an ellipsis.
1337       PS0    The value of this parameter is expanded  (see  PROMPTING  below)
1338              and  displayed by interactive shells after reading a command and
1339              before the command is executed.
1340       PS1    The value of this parameter is expanded  (see  PROMPTING  below)
1341              and  used  as  the  primary prompt string.  The default value is
1342              ``\s-\v\$ ''.
1343       PS2    The value of this parameter is expanded as with PS1 and used  as
1344              the secondary prompt string.  The default is ``> ''.
1345       PS3    The value of this parameter is used as the prompt for the select
1346              command (see SHELL GRAMMAR above).
1347       PS4    The value of this parameter is expanded  as  with  PS1  and  the
1348              value is printed before each command bash displays during an ex‐
1349              ecution trace.  The first character of the expanded value of PS4
1350              is replicated multiple times, as necessary, to indicate multiple
1351              levels of indirection.  The default is ``+ ''.
1352       SHELL  This variable expands to the full pathname to the shell.  If  it
1353              is  not  set  when the shell starts, bash assigns to it the full
1354              pathname of the current user's login shell.
1355       TIMEFORMAT
1356              The value of this parameter is used as a format string  specify‐
1357              ing  how  the timing information for pipelines prefixed with the
1358              time reserved word should be displayed.  The % character  intro‐
1359              duces  an  escape  sequence  that is expanded to a time value or
1360              other information.  The escape sequences and their meanings  are
1361              as follows; the braces denote optional portions.
1362              %%        A literal %.
1363              %[p][l]R  The elapsed time in seconds.
1364              %[p][l]U  The number of CPU seconds spent in user mode.
1365              %[p][l]S  The number of CPU seconds spent in system mode.
1366              %P        The CPU percentage, computed as (%U + %S) / %R.
1367
1368              The  optional  p is a digit specifying the precision, the number
1369              of fractional digits after a decimal point.  A value of 0 causes
1370              no decimal point or fraction to be output.  At most three places
1371              after the decimal point may be specified; values  of  p  greater
1372              than  3 are changed to 3.  If p is not specified, the value 3 is
1373              used.
1374
1375              The optional l specifies a longer format, including minutes,  of
1376              the  form  MMmSS.FFs.   The value of p determines whether or not
1377              the fraction is included.
1378
1379              If this variable is not set, bash acts as if it  had  the  value
1380              $'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'.   If  the value is null,
1381              no timing information is displayed.  A trailing newline is added
1382              when the format string is displayed.
1383       TMOUT  If set to a value greater than zero, TMOUT is treated as the de‐
1384              fault timeout for the read builtin.  The select  command  termi‐
1385              nates if input does not arrive after TMOUT seconds when input is
1386              coming from a terminal.  In an interactive shell, the  value  is
1387              interpreted as the number of seconds to wait for a line of input
1388              after issuing the primary prompt.  Bash terminates after waiting
1389              for  that number of seconds if a complete line of input does not
1390              arrive.
1391       TMPDIR If set, bash uses its value as the name of a directory in  which
1392              bash creates temporary files for the shell's use.
1393       auto_resume
1394              This variable controls how the shell interacts with the user and
1395              job control.  If this variable is set, single word  simple  com‐
1396              mands without redirections are treated as candidates for resump‐
1397              tion of an existing stopped job.  There is no ambiguity allowed;
1398              if  there  is more than one job beginning with the string typed,
1399              the job most recently accessed  is  selected.   The  name  of  a
1400              stopped  job, in this context, is the command line used to start
1401              it.  If set to the value exact, the string supplied  must  match
1402              the  name  of  a  stopped  job exactly; if set to substring, the
1403              string supplied needs to match a substring  of  the  name  of  a
1404              stopped  job.  The substring value provides functionality analo‐
1405              gous to the %?  job identifier (see JOB CONTROL below).  If  set
1406              to  any  other  value, the supplied string must be a prefix of a
1407              stopped job's name; this provides functionality analogous to the
1408              %string job identifier.
1409       histchars
1410              The  two or three characters which control history expansion and
1411              tokenization (see HISTORY EXPANSION below).  The first character
1412              is  the history expansion character, the character which signals
1413              the start of a history  expansion,  normally  `!'.   The  second
1414              character  is the quick substitution character, which is used as
1415              shorthand for re-running the previous command  entered,  substi‐
1416              tuting  one  string  for another in the command.  The default is
1417              `^'.  The optional third character is the character which  indi‐
1418              cates  that the remainder of the line is a comment when found as
1419              the first character of a word, normally `#'.  The  history  com‐
1420              ment character causes history substitution to be skipped for the
1421              remaining words on the line.  It does not necessarily cause  the
1422              shell parser to treat the rest of the line as a comment.
1423
1424   Arrays
1425       Bash  provides one-dimensional indexed and associative array variables.
1426       Any variable may be used as an indexed array; the declare builtin  will
1427       explicitly  declare an array.  There is no maximum limit on the size of
1428       an array, nor any requirement that members be indexed or assigned  con‐
1429       tiguously.   Indexed  arrays  are  referenced using integers (including
1430       arithmetic expressions) and are zero-based; associative arrays are ref‐
1431       erenced using arbitrary strings.  Unless otherwise noted, indexed array
1432       indices must be non-negative integers.
1433
1434       An indexed array is created automatically if any variable  is  assigned
1435       to using the syntax name[subscript]=value.  The subscript is treated as
1436       an arithmetic expression that must evaluate to a number.  To explicitly
1437       declare  an  indexed array, use declare -a name (see SHELL BUILTIN COM‐
1438       MANDS below).  declare -a name[subscript] is also  accepted;  the  sub‐
1439       script is ignored.
1440
1441       Associative arrays are created using declare -A name.
1442
1443       Attributes may be specified for an array variable using the declare and
1444       readonly builtins.  Each attribute applies to all members of an array.
1445
1446       Arrays  are  assigned  to  using  compound  assignments  of  the   form
1447       name=(value1  ...  valuen),  where  each value may be of the form [sub‐
1448       script]=string.  Indexed array assignments do not require anything  but
1449       string.   Each value in the list is expanded using all the shell expan‐
1450       sions described below under EXPANSION.  When assigning to  indexed  ar‐
1451       rays,  if  the optional brackets and subscript are supplied, that index
1452       is assigned to; otherwise the index of the element assigned is the last
1453       index assigned to by the statement plus one.  Indexing starts at zero.
1454
1455       When assigning to an associative array, the words in a compound assign‐
1456       ment may be either assignment statements, for which  the  subscript  is
1457       required,  or  a list of words that is interpreted as a sequence of al‐
1458       ternating keys and values: name=( key1 value1 key2 value2 ...).   These
1459       are  treated  identically  to  name=( [key1]=value1 [key2]=value2 ...).
1460       The first word in the list determines how the remaining words  are  in‐
1461       terpreted;  all  assignments  in a list must be of the same type.  When
1462       using key/value pairs, the keys may not be missing or  empty;  a  final
1463       missing value is treated like the empty string.
1464
1465       This  syntax is also accepted by the declare builtin.  Individual array
1466       elements may be assigned to using the name[subscript]=value syntax  in‐
1467       troduced  above.   When  assigning to an indexed array, if name is sub‐
1468       scripted by a negative number, that number is interpreted  as  relative
1469       to  one  greater  than  the  maximum index of name, so negative indices
1470       count back from the end of the array, and an index of -1 references the
1471       last element.
1472
1473       Any  element  of  an  array may be referenced using ${name[subscript]}.
1474       The braces are required to avoid conflicts with pathname expansion.  If
1475       subscript  is  @  or *, the word expands to all members of name.  These
1476       subscripts differ only when the word appears within double quotes.   If
1477       the word is double-quoted, ${name[*]} expands to a single word with the
1478       value of each array member separated by the first character of the  IFS
1479       special variable, and ${name[@]} expands each element of name to a sep‐
1480       arate word.  When there are no array  members,  ${name[@]}  expands  to
1481       nothing.   If the double-quoted expansion occurs within a word, the ex‐
1482       pansion of the first parameter is joined with the beginning part of the
1483       original  word,  and the expansion of the last parameter is joined with
1484       the last part of the original word.  This is analogous to the expansion
1485       of  the  special  parameters  *  and  @ (see Special Parameters above).
1486       ${#name[subscript]} expands to the length  of  ${name[subscript]}.   If
1487       subscript is * or @, the expansion is the number of elements in the ar‐
1488       ray.  If the subscript used to reference an element of an indexed array
1489       evaluates  to a number less than zero, it is interpreted as relative to
1490       one greater than the maximum index of the array,  so  negative  indices
1491       count back from the end of the array, and an index of -1 references the
1492       last element.
1493
1494       Referencing an array variable without a subscript is equivalent to ref‐
1495       erencing  the array with a subscript of 0.  Any reference to a variable
1496       using a valid subscript is legal, and bash will create an array if nec‐
1497       essary.
1498
1499       An  array variable is considered set if a subscript has been assigned a
1500       value.  The null string is a valid value.
1501
1502       It is possible to obtain the keys (indices) of an array as well as  the
1503       values.   ${!name[@]} and ${!name[*]} expand to the indices assigned in
1504       array variable name.  The treatment when in double quotes is similar to
1505       the expansion of the special parameters @ and * within double quotes.
1506
1507       The unset builtin is used to destroy arrays.  unset name[subscript] de‐
1508       stroys the array element at index subscript, for both indexed and asso‐
1509       ciative  arrays.  Negative subscripts to indexed arrays are interpreted
1510       as described above.  Unsetting the last element of  an  array  variable
1511       does  not  unset  the variable.  unset name, where name is an array, or
1512       unset name[subscript], where subscript is * or @,  removes  the  entire
1513       array.
1514
1515       When  using  a  variable name with a subscript as an argument to a com‐
1516       mand, such as with unset, without using the word expansion  syntax  de‐
1517       scribed above, the argument is subject to pathname expansion.  If path‐
1518       name expansion is not desired, the argument should be quoted.
1519
1520       The declare, local, and readonly builtins each accept a  -a  option  to
1521       specify  an indexed array and a -A option to specify an associative ar‐
1522       ray.  If both options are supplied,  -A  takes  precedence.   The  read
1523       builtin  accepts  a  -a  option to assign a list of words read from the
1524       standard input to an array.  The set and declare builtins display array
1525       values in a way that allows them to be reused as assignments.
1526

EXPANSION

1528       Expansion is performed on the command line after it has been split into
1529       words.  There are seven kinds of expansion performed: brace  expansion,
1530       tilde  expansion,  parameter  and variable expansion, command substitu‐
1531       tion, arithmetic expansion, word splitting, and pathname expansion.
1532
1533       The order of expansions is: brace expansion; tilde expansion, parameter
1534       and  variable expansion, arithmetic expansion, and command substitution
1535       (done in a left-to-right fashion); word splitting; and pathname  expan‐
1536       sion.
1537
1538       On systems that can support it, there is an additional expansion avail‐
1539       able: process substitution.  This is performed  at  the  same  time  as
1540       tilde,  parameter,  variable, and arithmetic expansion and command sub‐
1541       stitution.
1542
1543       After these expansions are performed, quote characters present  in  the
1544       original  word  are  removed  unless  they  have been quoted themselves
1545       (quote removal).
1546
1547       Only brace expansion, word splitting, and pathname  expansion  can  in‐
1548       crease  the number of words of the expansion; other expansions expand a
1549       single word to a single word.  The only exceptions to this are the  ex‐
1550       pansions  of  "$@"  and  "${name[@]}",  and,  in  most  cases,  $*  and
1551       ${name[*]} as explained above (see PARAMETERS).
1552
1553   Brace Expansion
1554       Brace expansion is a mechanism by which arbitrary strings may be gener‐
1555       ated.   This  mechanism is similar to pathname expansion, but the file‐
1556       names generated need not exist.  Patterns to be brace expanded take the
1557       form of an optional preamble, followed by either a series of comma-sep‐
1558       arated strings or a sequence expression between a pair of braces,  fol‐
1559       lowed  by  an  optional  postscript.   The preamble is prefixed to each
1560       string contained within the braces, and the postscript is then appended
1561       to each resulting string, expanding left to right.
1562
1563       Brace  expansions  may  be nested.  The results of each expanded string
1564       are not sorted;  left  to  right  order  is  preserved.   For  example,
1565       a{d,c,b}e expands into `ade ace abe'.
1566
1567       A  sequence expression takes the form {x..y[..incr]}, where x and y are
1568       either integers or single characters, and incr, an optional  increment,
1569       is  an  integer.  When integers are supplied, the expression expands to
1570       each number between x and y, inclusive.  Supplied integers may be  pre‐
1571       fixed  with 0 to force each term to have the same width.  When either x
1572       or y begins with a zero, the shell  attempts  to  force  all  generated
1573       terms  to  contain the same number of digits, zero-padding where neces‐
1574       sary.  When characters are supplied, the  expression  expands  to  each
1575       character  lexicographically  between x and y, inclusive, using the de‐
1576       fault C locale.  Note that both x and y must be of the same type.  When
1577       the  increment  is  supplied, it is used as the difference between each
1578       term.  The default increment is 1 or -1 as appropriate.
1579
1580       Brace expansion is performed before any other expansions, and any char‐
1581       acters  special to other expansions are preserved in the result.  It is
1582       strictly textual.  Bash does not apply any syntactic interpretation  to
1583       the context of the expansion or the text between the braces.
1584
1585       A  correctly-formed  brace  expansion must contain unquoted opening and
1586       closing braces, and at least one unquoted comma or a valid sequence ex‐
1587       pression.  Any incorrectly formed brace expansion is left unchanged.  A
1588       { or , may be quoted with a backslash to prevent its  being  considered
1589       part  of  a brace expression.  To avoid conflicts with parameter expan‐
1590       sion, the string ${ is not considered eligible for brace expansion, and
1591       inhibits brace expansion until the closing }.
1592
1593       This construct is typically used as shorthand when the common prefix of
1594       the strings to be generated is longer than in the above example:
1595
1596              mkdir /usr/local/src/bash/{old,new,dist,bugs}
1597       or
1598              chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
1599
1600       Brace expansion introduces a  slight  incompatibility  with  historical
1601       versions  of sh.  sh does not treat opening or closing braces specially
1602       when they appear as part of a word, and preserves them in  the  output.
1603       Bash  removes  braces  from  words as a consequence of brace expansion.
1604       For example, a word entered to sh as file{1,2} appears  identically  in
1605       the  output.  The same word is output as file1 file2 after expansion by
1606       bash.  If strict compatibility with sh is desired, start bash with  the
1607       +B option or disable brace expansion with the +B option to the set com‐
1608       mand (see SHELL BUILTIN COMMANDS below).
1609
1610   Tilde Expansion
1611       If a word begins with an unquoted tilde character  (`~'),  all  of  the
1612       characters  preceding  the  first unquoted slash (or all characters, if
1613       there is no unquoted slash) are considered a tilde-prefix.  If none  of
1614       the  characters  in  the tilde-prefix are quoted, the characters in the
1615       tilde-prefix following the tilde are treated as a possible login  name.
1616       If  this  login name is the null string, the tilde is replaced with the
1617       value of the shell parameter HOME.  If HOME is unset, the  home  direc‐
1618       tory  of  the  user executing the shell is substituted instead.  Other‐
1619       wise, the tilde-prefix is replaced with the home  directory  associated
1620       with the specified login name.
1621
1622       If  the tilde-prefix is a `~+', the value of the shell variable PWD re‐
1623       places the tilde-prefix.  If the tilde-prefix is a `~-', the  value  of
1624       the  shell variable OLDPWD, if it is set, is substituted.  If the char‐
1625       acters following the tilde in the tilde-prefix consist of a  number  N,
1626       optionally  prefixed  by  a  `+' or a `-', the tilde-prefix is replaced
1627       with the corresponding element from the directory stack, as it would be
1628       displayed by the dirs builtin invoked with the tilde-prefix as an argu‐
1629       ment.  If the characters following the tilde in the  tilde-prefix  con‐
1630       sist of a number without a leading `+' or `-', `+' is assumed.
1631
1632       If the login name is invalid, or the tilde expansion fails, the word is
1633       unchanged.
1634
1635       Each variable assignment is checked for unquoted tilde-prefixes immedi‐
1636       ately following a : or the first =.  In these cases, tilde expansion is
1637       also performed.  Consequently, one may use filenames with tildes in as‐
1638       signments  to PATH, MAILPATH, and CDPATH, and the shell assigns the ex‐
1639       panded value.
1640
1641       Bash also performs tilde expansion on words satisfying  the  conditions
1642       of variable assignments (as described above under PARAMETERS) when they
1643       appear as arguments to simple commands.  Bash does not do this,  except
1644       for the declaration commands listed above, when in posix mode.
1645
1646   Parameter Expansion
1647       The `$' character introduces parameter expansion, command substitution,
1648       or arithmetic expansion.  The parameter name or symbol to  be  expanded
1649       may  be enclosed in braces, which are optional but serve to protect the
1650       variable to be expanded from characters immediately following it  which
1651       could be interpreted as part of the name.
1652
1653       When  braces  are  used, the matching ending brace is the first `}' not
1654       escaped by a backslash or within a quoted string, and not within an em‐
1655       bedded  arithmetic expansion, command substitution, or parameter expan‐
1656       sion.
1657
1658       ${parameter}
1659              The value of parameter is substituted.  The braces are  required
1660              when  parameter  is  a  positional  parameter with more than one
1661              digit, or when parameter is followed by a character which is not
1662              to be interpreted as part of its name.  The parameter is a shell
1663              parameter as described above PARAMETERS) or an  array  reference
1664              (Arrays).
1665
1666       If  the  first  character of parameter is an exclamation point (!), and
1667       parameter is not a nameref, it introduces a level of indirection.  Bash
1668       uses the value formed by expanding the rest of parameter as the new pa‐
1669       rameter; this is then expanded and that value is used in  the  rest  of
1670       the  expansion,  rather  than  the expansion of the original parameter.
1671       This is known as indirect expansion.  The value is subject to tilde ex‐
1672       pansion,  parameter expansion, command substitution, and arithmetic ex‐
1673       pansion.  If parameter is a nameref, this expands to the  name  of  the
1674       parameter  referenced  by  parameter instead of performing the complete
1675       indirect expansion.  The exceptions  to  this  are  the  expansions  of
1676       ${!prefix*}  and  ${!name[@]}  described  below.  The exclamation point
1677       must immediately follow the left brace in order to  introduce  indirec‐
1678       tion.
1679
1680       In each of the cases below, word is subject to tilde expansion, parame‐
1681       ter expansion, command substitution, and arithmetic expansion.
1682
1683       When not performing substring expansion, using the forms documented be‐
1684       low  (e.g.,  :-),  bash  tests  for  a parameter that is unset or null.
1685       Omitting the colon results in a test only for a parameter that  is  un‐
1686       set.
1687
1688       ${parameter:-word}
1689              Use  Default  Values.  If parameter is unset or null, the expan‐
1690              sion of word is substituted.  Otherwise, the value of  parameter
1691              is substituted.
1692       ${parameter:=word}
1693              Assign  Default  Values.  If parameter is unset or null, the ex‐
1694              pansion of word is assigned to parameter.  The value of  parame‐
1695              ter  is then substituted.  Positional parameters and special pa‐
1696              rameters may not be assigned to in this way.
1697       ${parameter:?word}
1698              Display Error if Null or Unset.  If parameter is null or  unset,
1699              the  expansion  of  word (or a message to that effect if word is
1700              not present) is written to the standard error and the shell,  if
1701              it is not interactive, exits.  Otherwise, the value of parameter
1702              is substituted.
1703       ${parameter:+word}
1704              Use Alternate Value.  If parameter is null or unset, nothing  is
1705              substituted, otherwise the expansion of word is substituted.
1706       ${parameter:offset}
1707       ${parameter:offset:length}
1708              Substring  Expansion.  Expands to up to length characters of the
1709              value of parameter starting at the character specified  by  off‐
1710              set.  If parameter is @, an indexed array subscripted by @ or *,
1711              or an associative array name, the results  differ  as  described
1712              below.   If  length  is omitted, expands to the substring of the
1713              value of parameter starting at the character specified by offset
1714              and  extending  to  the end of the value.  length and offset are
1715              arithmetic expressions (see ARITHMETIC EVALUATION below).
1716
1717              If offset evaluates to a number less than  zero,  the  value  is
1718              used as an offset in characters from the end of the value of pa‐
1719              rameter.  If length evaluates to a number less than zero, it  is
1720              interpreted as an offset in characters from the end of the value
1721              of parameter rather than a number of characters, and the  expan‐
1722              sion  is  the  characters  between offset and that result.  Note
1723              that a negative offset must be separated from the  colon  by  at
1724              least one space to avoid being confused with the :- expansion.
1725
1726              If  parameter  is  @, the result is length positional parameters
1727              beginning at offset.  A negative offset is taken relative to one
1728              greater  than the greatest positional parameter, so an offset of
1729              -1 evaluates to the last positional parameter.  It is an  expan‐
1730              sion error if length evaluates to a number less than zero.
1731
1732              If parameter is an indexed array name subscripted by @ or *, the
1733              result is the length members of the array beginning  with  ${pa‐
1734              rameter[offset]}.   A  negative  offset is taken relative to one
1735              greater than the maximum index of the specified array.  It is an
1736              expansion error if length evaluates to a number less than zero.
1737
1738              Substring expansion applied to an associative array produces un‐
1739              defined results.
1740
1741              Substring indexing is zero-based unless the  positional  parame‐
1742              ters  are  used,  in  which case the indexing starts at 1 by de‐
1743              fault.  If offset is 0, and the positional parameters are  used,
1744              $0 is prefixed to the list.
1745
1746       ${!prefix*}
1747       ${!prefix@}
1748              Names  matching prefix.  Expands to the names of variables whose
1749              names begin with prefix, separated by the first character of the
1750              IFS  special variable.  When @ is used and the expansion appears
1751              within double quotes, each variable name expands to  a  separate
1752              word.
1753
1754       ${!name[@]}
1755       ${!name[*]}
1756              List  of  array  keys.  If name is an array variable, expands to
1757              the list of array indices (keys) assigned in name.  If  name  is
1758              not  an  array,  expands to 0 if name is set and null otherwise.
1759              When @ is used and the expansion appears within  double  quotes,
1760              each key expands to a separate word.
1761
1762       ${#parameter}
1763              Parameter  length.  The length in characters of the value of pa‐
1764              rameter is substituted.  If parameter is * or @, the value  sub‐
1765              stituted  is  the number of positional parameters.  If parameter
1766              is an array name subscripted by * or @, the value substituted is
1767              the number of elements in the array.  If parameter is an indexed
1768              array name subscripted by a negative number, that number is  in‐
1769              terpreted  as  relative to one greater than the maximum index of
1770              parameter, so negative indices count back from the  end  of  the
1771              array, and an index of -1 references the last element.
1772
1773       ${parameter#word}
1774       ${parameter##word}
1775              Remove matching prefix pattern.  The word is expanded to produce
1776              a pattern just as in pathname expansion, and matched against the
1777              expanded value of parameter using the rules described under Pat‐
1778              tern Matching below.  If the pattern matches  the  beginning  of
1779              the  value of parameter, then the result of the expansion is the
1780              expanded value of parameter with the shortest  matching  pattern
1781              (the  ``#''  case)  or  the longest matching pattern (the ``##''
1782              case) deleted.  If parameter is @ or *, the pattern removal  op‐
1783              eration is applied to each positional parameter in turn, and the
1784              expansion is the resultant list.  If parameter is an array vari‐
1785              able  subscripted  with @ or *, the pattern removal operation is
1786              applied to each member of the array in turn, and  the  expansion
1787              is the resultant list.
1788
1789       ${parameter%word}
1790       ${parameter%%word}
1791              Remove matching suffix pattern.  The word is expanded to produce
1792              a pattern just as in pathname expansion, and matched against the
1793              expanded value of parameter using the rules described under Pat‐
1794              tern Matching below.  If the pattern matches a trailing  portion
1795              of  the  expanded value of parameter, then the result of the ex‐
1796              pansion is the expanded value of  parameter  with  the  shortest
1797              matching  pattern  (the ``%'' case) or the longest matching pat‐
1798              tern (the ``%%'' case) deleted.  If parameter is  @  or  *,  the
1799              pattern  removal operation is applied to each positional parame‐
1800              ter in turn, and the expansion is the resultant list.  If param‐
1801              eter  is  an array variable subscripted with @ or *, the pattern
1802              removal operation is applied to each  member  of  the  array  in
1803              turn, and the expansion is the resultant list.
1804
1805       ${parameter/pattern/string}
1806              Pattern substitution.  The pattern is expanded to produce a pat‐
1807              tern just as in pathname expansion, Parameter  is  expanded  and
1808              the  longest match of pattern against its value is replaced with
1809              string.  The match is performed using the rules described  under
1810              Pattern  Matching  below.  If pattern begins with /, all matches
1811              of pattern are replaced with string.  Normally  only  the  first
1812              match  is  replaced.  If pattern begins with #, it must match at
1813              the beginning of the expanded value of  parameter.   If  pattern
1814              begins with %, it must match at the end of the expanded value of
1815              parameter.  If string is null, matches of  pattern  are  deleted
1816              and  the / following pattern may be omitted.  If the nocasematch
1817              shell option is enabled, the match is performed  without  regard
1818              to  the  case of alphabetic characters.  If parameter is @ or *,
1819              the substitution operation is applied to each positional parame‐
1820              ter in turn, and the expansion is the resultant list.  If param‐
1821              eter is an array variable subscripted with @ or *, the substitu‐
1822              tion  operation  is applied to each member of the array in turn,
1823              and the expansion is the resultant list.
1824
1825       ${parameter^pattern}
1826       ${parameter^^pattern}
1827       ${parameter,pattern}
1828       ${parameter,,pattern}
1829              Case modification.  This expansion modifies the case  of  alpha‐
1830              betic  characters in parameter.  The pattern is expanded to pro‐
1831              duce a pattern just as in pathname expansion.  Each character in
1832              the  expanded value of parameter is tested against pattern, and,
1833              if it matches the pattern, its case is converted.   The  pattern
1834              should  not attempt to match more than one character.  The ^ op‐
1835              erator converts lowercase letters matching pattern to uppercase;
1836              the , operator converts matching uppercase letters to lowercase.
1837              The ^^ and ,, expansions convert each matched character  in  the
1838              expanded  value;  the  ^ and , expansions match and convert only
1839              the first character in the expanded value.  If pattern is  omit‐
1840              ted,  it is treated like a ?, which matches every character.  If
1841              parameter is @ or *, the case modification operation is  applied
1842              to  each  positional parameter in turn, and the expansion is the
1843              resultant list.  If parameter is an array  variable  subscripted
1844              with  @ or *, the case modification operation is applied to each
1845              member of the array in turn, and the expansion is the  resultant
1846              list.
1847
1848       ${parameter@operator}
1849              Parameter transformation.  The expansion is either a transforma‐
1850              tion of the value of parameter or  information  about  parameter
1851              itself,  depending on the value of operator.  Each operator is a
1852              single letter:
1853
1854              U      The expansion is a string that is the value of  parameter
1855                     with  lowercase alphabetic characters converted to upper‐
1856                     case.
1857              u      The expansion is a string that is the value of  parameter
1858                     with the first character converted to uppercase, if it is
1859                     alphabetic.
1860              L      The expansion is a string that is the value of  parameter
1861                     with  uppercase alphabetic characters converted to lower‐
1862                     case.
1863              Q      The expansion is a string that is the value of  parameter
1864                     quoted in a format that can be reused as input.
1865              E      The  expansion is a string that is the value of parameter
1866                     with backslash escape  sequences  expanded  as  with  the
1867                     $'...' quoting mechanism.
1868              P      The expansion is a string that is the result of expanding
1869                     the value of parameter as if it were a prompt string (see
1870                     PROMPTING below).
1871              A      The  expansion  is  a string in the form of an assignment
1872                     statement or declare command  that,  if  evaluated,  will
1873                     recreate parameter with its attributes and value.
1874              K      Produces a possibly-quoted version of the value of param‐
1875                     eter, except that it prints the values of indexed and as‐
1876                     sociative  arrays as a sequence of quoted key-value pairs
1877                     (see Arrays above).
1878              a      The expansion is a string consisting of flag values  rep‐
1879                     resenting parameter's attributes.
1880
1881              If  parameter  is @ or *, the operation is applied to each posi‐
1882              tional parameter in turn, and the  expansion  is  the  resultant
1883              list.   If  parameter is an array variable subscripted with @ or
1884              *, the operation is applied to each member of the array in turn,
1885              and the expansion is the resultant list.
1886
1887              The  result  of  the  expansion is subject to word splitting and
1888              pathname expansion as described below.
1889
1890   Command Substitution
1891       Command substitution allows the output of a command to replace the com‐
1892       mand name.  There are two forms:
1893
1894              $(command)
1895       or
1896              `command`
1897
1898       Bash performs the expansion by executing command in a subshell environ‐
1899       ment and replacing the command substitution with the standard output of
1900       the command, with any trailing newlines deleted.  Embedded newlines are
1901       not deleted, but they may be removed during word splitting.   The  com‐
1902       mand  substitution  $(cat  file)  can be replaced by the equivalent but
1903       faster $(< file).
1904
1905       When the old-style backquote form of substitution  is  used,  backslash
1906       retains  its  literal  meaning except when followed by $, `, or \.  The
1907       first backquote not preceded by a backslash terminates the command sub‐
1908       stitution.   When using the $(command) form, all characters between the
1909       parentheses make up the command; none are treated specially.
1910
1911       Command substitutions may be nested.  To nest when using the backquoted
1912       form, escape the inner backquotes with backslashes.
1913
1914       If  the  substitution  appears within double quotes, word splitting and
1915       pathname expansion are not performed on the results.
1916
1917   Arithmetic Expansion
1918       Arithmetic expansion allows the evaluation of an arithmetic  expression
1919       and  the  substitution of the result.  The format for arithmetic expan‐
1920       sion is:
1921
1922              $((expression))
1923
1924       The expression is treated as if it were within  double  quotes,  but  a
1925       double  quote inside the parentheses is not treated specially.  All to‐
1926       kens in the expression undergo parameter and variable  expansion,  com‐
1927       mand  substitution,  and  quote  removal.  The result is treated as the
1928       arithmetic expression to be evaluated.  Arithmetic  expansions  may  be
1929       nested.
1930
1931       The  evaluation  is performed according to the rules listed below under
1932       ARITHMETIC EVALUATION.  If expression is invalid, bash prints a message
1933       indicating failure and no substitution occurs.
1934
1935   Process Substitution
1936       Process  substitution allows a process's input or output to be referred
1937       to using a filename.  It takes the form of  <(list)  or  >(list).   The
1938       process  list is run asynchronously, and its input or output appears as
1939       a filename.  This filename is passed as an argument to the current com‐
1940       mand  as  the  result  of  the expansion.  If the >(list) form is used,
1941       writing to the file will provide input for list.  If the  <(list)  form
1942       is  used,  the  file passed as an argument should be read to obtain the
1943       output of list.  Process substitution is supported on systems that sup‐
1944       port named pipes (FIFOs) or the /dev/fd method of naming open files.
1945
1946       When  available,  process substitution is performed simultaneously with
1947       parameter and variable expansion, command substitution, and  arithmetic
1948       expansion.
1949
1950   Word Splitting
1951       The  shell  scans the results of parameter expansion, command substitu‐
1952       tion, and arithmetic expansion that did not occur within double  quotes
1953       for word splitting.
1954
1955       The  shell  treats each character of IFS as a delimiter, and splits the
1956       results of the other expansions into words using  these  characters  as
1957       field   terminators.   If  IFS  is  unset,  or  its  value  is  exactly
1958       <space><tab><newline>, the default, then sequences of  <space>,  <tab>,
1959       and  <newline>  at the beginning and end of the results of the previous
1960       expansions are ignored, and any sequence of IFS characters not  at  the
1961       beginning  or  end  serves  to delimit words.  If IFS has a value other
1962       than the default, then sequences of the  whitespace  characters  space,
1963       tab,  and  newline are ignored at the beginning and end of the word, as
1964       long as the whitespace character is in the value of IFS (an IFS  white‐
1965       space  character).   Any  character  in IFS that is not IFS whitespace,
1966       along with any adjacent IFS whitespace characters, delimits a field.  A
1967       sequence  of  IFS whitespace characters is also treated as a delimiter.
1968       If the value of IFS is null, no word splitting occurs.
1969
1970       Explicit null arguments ("" or '') are retained and passed to  commands
1971       as empty strings.  Unquoted implicit null arguments, resulting from the
1972       expansion of parameters that have no values, are removed.  If a parame‐
1973       ter with no value is expanded within double quotes, a null argument re‐
1974       sults and is retained and passed to a command as an empty string.  When
1975       a  quoted  null  argument  appears as part of a word whose expansion is
1976       non-null, the null argument is removed.  That is, the word -d'' becomes
1977       -d after word splitting and null argument removal.
1978
1979       Note that if no expansion occurs, no splitting is performed.
1980
1981   Pathname Expansion
1982       After  word  splitting,  unless  the -f option has been set, bash scans
1983       each word for the characters *, ?, and [.  If one of  these  characters
1984       appears, and is not quoted, then the word is regarded as a pattern, and
1985       replaced with an alphabetically sorted list of filenames  matching  the
1986       pattern  (see  Pattern  Matching  below).  If no matching filenames are
1987       found, and the shell option nullglob is not enabled, the word  is  left
1988       unchanged.   If  the  nullglob option is set, and no matches are found,
1989       the word is removed.  If the failglob  shell  option  is  set,  and  no
1990       matches  are  found, an error message is printed and the command is not
1991       executed.  If the shell option nocaseglob is enabled, the match is per‐
1992       formed  without  regard  to  the case of alphabetic characters.  When a
1993       pattern is used for pathname expansion, the  character  ``.''   at  the
1994       start  of  a  name or immediately following a slash must be matched ex‐
1995       plicitly, unless the shell option dotglob is set.  The filenames  ``.''
1996       and  ``..''  must always be matched explicitly, even if dotglob is set.
1997       In other cases, the ``.''  character is not  treated  specially.   When
1998       matching a pathname, the slash character must always be matched explic‐
1999       itly by a slash in the pattern, but in other matching contexts  it  can
2000       be matched by a special pattern character as described below under Pat‐
2001       tern Matching.  See the description of shopt below under SHELL  BUILTIN
2002       COMMANDS  for  a description of the nocaseglob, nullglob, failglob, and
2003       dotglob shell options.
2004
2005       The GLOBIGNORE shell variable may be used to restrict the set  of  file
2006       names  matching  a  pattern.   If GLOBIGNORE is set, each matching file
2007       name that also matches one of the patterns  in  GLOBIGNORE  is  removed
2008       from  the list of matches.  If the nocaseglob option is set, the match‐
2009       ing against the patterns in GLOBIGNORE is performed without  regard  to
2010       case.  The filenames ``.''  and ``..''  are always ignored when GLOBIG‐
2011       NORE is set and not null.  However, setting GLOBIGNORE  to  a  non-null
2012       value has the effect of enabling the dotglob shell option, so all other
2013       filenames beginning with a ``.''  will match.  To get the old  behavior
2014       of  ignoring  filenames beginning with a ``.'', make ``.*''  one of the
2015       patterns in GLOBIGNORE.  The dotglob option is disabled when GLOBIGNORE
2016       is unset.  The pattern matching honors the setting of the extglob shell
2017       option.
2018
2019       Pattern Matching
2020
2021       Any character that appears in a pattern, other than the special pattern
2022       characters  described below, matches itself.  The NUL character may not
2023       occur in a pattern.  A backslash escapes the following  character;  the
2024       escaping  backslash  is  discarded  when matching.  The special pattern
2025       characters must be quoted if they are to be matched literally.
2026
2027       The special pattern characters have the following meanings:
2028
2029              *      Matches any string, including the null string.  When  the
2030                     globstar  shell  option  is  enabled,  and * is used in a
2031                     pathname expansion context, two adjacent  *s  used  as  a
2032                     single  pattern will match all files and zero or more di‐
2033                     rectories and subdirectories.  If followed by  a  /,  two
2034                     adjacent  *s  will match only directories and subdirecto‐
2035                     ries.
2036              ?      Matches any single character.
2037              [...]  Matches any one of the enclosed characters.   A  pair  of
2038                     characters  separated by a hyphen denotes a range expres‐
2039                     sion; any character that falls between those two  charac‐
2040                     ters, inclusive, using the current locale's collating se‐
2041                     quence and character set, is matched.  If the first char‐
2042                     acter  following  the [ is a !  or a ^ then any character
2043                     not enclosed is matched.  The sorting order of characters
2044                     in  range expressions is determined by the current locale
2045                     and the values of the LC_COLLATE or  LC_ALL  shell  vari‐
2046                     ables,  if set.  To obtain the traditional interpretation
2047                     of  range  expressions,  where  [a-d]  is  equivalent  to
2048                     [abcd],  set  value of the LC_ALL shell variable to C, or
2049                     enable the globasciiranges shell  option.   A  -  may  be
2050                     matched by including it as the first or last character in
2051                     the set.  A ] may be matched by including it as the first
2052                     character in the set.
2053
2054                     Within  [ and ], character classes can be specified using
2055                     the syntax [:class:], where class is one of the following
2056                     classes defined in the POSIX standard:
2057                     alnum  alpha  ascii  blank  cntrl digit graph lower print
2058                     punct space upper word xdigit
2059                     A character class matches any character belonging to that
2060                     class.  The word character class matches letters, digits,
2061                     and the character _.
2062
2063                     Within [ and ], an equivalence class can be specified us‐
2064                     ing  the  syntax [=c=], which matches all characters with
2065                     the same collation weight (as defined by the current  lo‐
2066                     cale) as the character c.
2067
2068                     Within [ and ], the syntax [.symbol.] matches the collat‐
2069                     ing symbol symbol.
2070
2071       If the extglob shell option is enabled using the shopt builtin, several
2072       extended  pattern  matching operators are recognized.  In the following
2073       description, a pattern-list is a list of one or more patterns separated
2074       by a |.  Composite patterns may be formed using one or more of the fol‐
2075       lowing sub-patterns:
2076
2077              ?(pattern-list)
2078                     Matches zero or one occurrence of the given patterns
2079              *(pattern-list)
2080                     Matches zero or more occurrences of the given patterns
2081              +(pattern-list)
2082                     Matches one or more occurrences of the given patterns
2083              @(pattern-list)
2084                     Matches one of the given patterns
2085              !(pattern-list)
2086                     Matches anything except one of the given patterns
2087
2088       Complicated extended pattern matching against long strings is slow, es‐
2089       pecially when the patterns contain alternations and the strings contain
2090       multiple matches.  Using separate matches against shorter  strings,  or
2091       using arrays of strings instead of a single long string, may be faster.
2092
2093   Quote Removal
2094       After the preceding expansions, all unquoted occurrences of the charac‐
2095       ters \, ', and " that did not result from one of the  above  expansions
2096       are removed.
2097

REDIRECTION

2099       Before  a  command  is executed, its input and output may be redirected
2100       using a special notation interpreted by the shell.  Redirection  allows
2101       commands'  file handles to be duplicated, opened, closed, made to refer
2102       to different files, and can change the files the command reads from and
2103       writes  to.  Redirection may also be used to modify file handles in the
2104       current shell execution environment.  The following redirection  opera‐
2105       tors may precede or appear anywhere within a simple command or may fol‐
2106       low a command.  Redirections are processed in the  order  they  appear,
2107       from left to right.
2108
2109       Each  redirection  that may be preceded by a file descriptor number may
2110       instead be preceded by a word of the form {varname}.  In this case, for
2111       each redirection operator except >&- and <&-, the shell will allocate a
2112       file descriptor greater than or equal to 10 and assign it  to  varname.
2113       If  >&-  or  <&- is preceded by {varname}, the value of varname defines
2114       the file descriptor to close.  If {varname} is supplied, the  redirect‐
2115       ion  persists  beyond the scope of the command, allowing the shell pro‐
2116       grammer to manage the file descriptor himself.
2117
2118       In the following descriptions, if the file descriptor number  is  omit‐
2119       ted,  and the first character of the redirection operator is <, the re‐
2120       direction refers to the standard input (file  descriptor  0).   If  the
2121       first  character  of  the  redirection  operator  is >, the redirection
2122       refers to the standard output (file descriptor 1).
2123
2124       The word following the redirection operator in the  following  descrip‐
2125       tions,  unless  otherwise noted, is subjected to brace expansion, tilde
2126       expansion, parameter  and  variable  expansion,  command  substitution,
2127       arithmetic  expansion,  quote  removal,  pathname  expansion,  and word
2128       splitting.  If it expands to more than one word, bash reports an error.
2129
2130       Note that the order of redirections is significant.  For  example,  the
2131       command
2132
2133              ls > dirlist 2>&1
2134
2135       directs  both  standard  output and standard error to the file dirlist,
2136       while the command
2137
2138              ls 2>&1 > dirlist
2139
2140       directs only the standard output to file dirlist, because the  standard
2141       error  was duplicated from the standard output before the standard out‐
2142       put was redirected to dirlist.
2143
2144       Bash handles several filenames specially when they are used in redirec‐
2145       tions, as described in the following table.  If the operating system on
2146       which bash is running provides these special files, bash will use them;
2147       otherwise  it  will emulate them internally with the behavior described
2148       below.
2149
2150              /dev/fd/fd
2151                     If fd is a valid integer, file descriptor  fd  is  dupli‐
2152                     cated.
2153              /dev/stdin
2154                     File descriptor 0 is duplicated.
2155              /dev/stdout
2156                     File descriptor 1 is duplicated.
2157              /dev/stderr
2158                     File descriptor 2 is duplicated.
2159              /dev/tcp/host/port
2160                     If host is a valid hostname or Internet address, and port
2161                     is an integer port number or service name, bash  attempts
2162                     to open the corresponding TCP socket.
2163              /dev/udp/host/port
2164                     If host is a valid hostname or Internet address, and port
2165                     is an integer port number or service name, bash  attempts
2166                     to open the corresponding UDP socket.
2167
2168       A failure to open or create a file causes the redirection to fail.
2169
2170       Redirections  using file descriptors greater than 9 should be used with
2171       care, as they may conflict with file descriptors the shell uses  inter‐
2172       nally.
2173
2174   Redirecting Input
2175       Redirection of input causes the file whose name results from the expan‐
2176       sion of word to be opened for reading on  file  descriptor  n,  or  the
2177       standard input (file descriptor 0) if n is not specified.
2178
2179       The general format for redirecting input is:
2180
2181              [n]<word
2182
2183   Redirecting Output
2184       Redirection  of  output causes the file whose name results from the ex‐
2185       pansion of word to be opened for writing on file descriptor n,  or  the
2186       standard output (file descriptor 1) if n is not specified.  If the file
2187       does not exist it is created; if it does exist it is truncated to  zero
2188       size.
2189
2190       The general format for redirecting output is:
2191
2192              [n]>word
2193
2194       If  the  redirection operator is >, and the noclobber option to the set
2195       builtin has been enabled, the redirection will fail if the  file  whose
2196       name  results  from the expansion of word exists and is a regular file.
2197       If the redirection operator is >|, or the redirection operator is > and
2198       the noclobber option to the set builtin command is not enabled, the re‐
2199       direction is attempted even if the file named by word exists.
2200
2201   Appending Redirected Output
2202       Redirection of output in this fashion causes the file  whose  name  re‐
2203       sults from the expansion of word to be opened for appending on file de‐
2204       scriptor n, or the standard output (file descriptor  1)  if  n  is  not
2205       specified.  If the file does not exist it is created.
2206
2207       The general format for appending output is:
2208
2209              [n]>>word
2210
2211   Redirecting Standard Output and Standard Error
2212       This  construct allows both the standard output (file descriptor 1) and
2213       the standard error output (file descriptor 2) to be redirected  to  the
2214       file whose name is the expansion of word.
2215
2216       There  are two formats for redirecting standard output and standard er‐
2217       ror:
2218
2219              &>word
2220       and
2221              >&word
2222
2223       Of the two forms, the first is preferred.  This is semantically equiva‐
2224       lent to
2225
2226              >word 2>&1
2227
2228       When  using  the second form, word may not expand to a number or -.  If
2229       it does, other redirection operators apply (see  Duplicating  File  De‐
2230       scriptors below) for compatibility reasons.
2231
2232   Appending Standard Output and Standard Error
2233       This  construct allows both the standard output (file descriptor 1) and
2234       the standard error output (file descriptor 2) to  be  appended  to  the
2235       file whose name is the expansion of word.
2236
2237       The format for appending standard output and standard error is:
2238
2239              &>>word
2240
2241       This is semantically equivalent to
2242
2243              >>word 2>&1
2244
2245       (see Duplicating File Descriptors below).
2246
2247   Here Documents
2248       This  type  of  redirection  instructs the shell to read input from the
2249       current source until a line containing only delimiter (with no trailing
2250       blanks)  is seen.  All of the lines read up to that point are then used
2251       as the standard input (or file descriptor n if n is  specified)  for  a
2252       command.
2253
2254       The format of here-documents is:
2255
2256              [n]<<[-]word
2257                      here-document
2258              delimiter
2259
2260       No  parameter  and variable expansion, command substitution, arithmetic
2261       expansion, or pathname expansion is performed on word.  If any part  of
2262       word  is  quoted, the delimiter is the result of quote removal on word,
2263       and the lines in the here-document are not expanded.  If  word  is  un‐
2264       quoted,  all  lines of the here-document are subjected to parameter ex‐
2265       pansion, command substitution, and arithmetic expansion, the  character
2266       sequence \<newline> is ignored, and \ must be used to quote the charac‐
2267       ters \, $, and `.
2268
2269       If the redirection operator is <<-, then all leading tab characters are
2270       stripped  from input lines and the line containing delimiter.  This al‐
2271       lows here-documents within shell scripts to be indented  in  a  natural
2272       fashion.
2273
2274   Here Strings
2275       A variant of here documents, the format is:
2276
2277              [n]<<<word
2278
2279       The  word  undergoes tilde expansion, parameter and variable expansion,
2280       command substitution, arithmetic expansion, and quote  removal.   Path‐
2281       name  expansion  and  word  splitting are not performed.  The result is
2282       supplied as a single string, with a newline appended, to the command on
2283       its standard input (or file descriptor n if n is specified).
2284
2285   Duplicating File Descriptors
2286       The redirection operator
2287
2288              [n]<&word
2289
2290       is used to duplicate input file descriptors.  If word expands to one or
2291       more digits, the file descriptor denoted by n is made to be a  copy  of
2292       that  file descriptor.  If the digits in word do not specify a file de‐
2293       scriptor open for input, a redirection error occurs.  If word evaluates
2294       to -, file descriptor n is closed.  If n is not specified, the standard
2295       input (file descriptor 0) is used.
2296
2297       The operator
2298
2299              [n]>&word
2300
2301       is used similarly to duplicate output file descriptors.  If  n  is  not
2302       specified,  the  standard  output  (file descriptor 1) is used.  If the
2303       digits in word do not specify a file descriptor open for output, a  re‐
2304       direction  error  occurs.  If word evaluates to -, file descriptor n is
2305       closed.  As a special case, if n is omitted, and word does  not  expand
2306       to  one or more digits or -, the standard output and standard error are
2307       redirected as described previously.
2308
2309   Moving File Descriptors
2310       The redirection operator
2311
2312              [n]<&digit-
2313
2314       moves the file descriptor digit to file descriptor n, or  the  standard
2315       input (file descriptor 0) if n is not specified.  digit is closed after
2316       being duplicated to n.
2317
2318       Similarly, the redirection operator
2319
2320              [n]>&digit-
2321
2322       moves the file descriptor digit to file descriptor n, or  the  standard
2323       output (file descriptor 1) if n is not specified.
2324
2325   Opening File Descriptors for Reading and Writing
2326       The redirection operator
2327
2328              [n]<>word
2329
2330       causes  the  file  whose name is the expansion of word to be opened for
2331       both reading and writing on file descriptor n, or on file descriptor  0
2332       if n is not specified.  If the file does not exist, it is created.
2333

ALIASES

2335       Aliases  allow a string to be substituted for a word when it is used as
2336       the first word of a simple command.  The  shell  maintains  a  list  of
2337       aliases  that  may  be set and unset with the alias and unalias builtin
2338       commands (see SHELL BUILTIN COMMANDS below).  The first  word  of  each
2339       simple  command, if unquoted, is checked to see if it has an alias.  If
2340       so, that word is replaced by the text of the alias.  The characters  /,
2341       $,  `,  and = and any of the shell metacharacters or quoting characters
2342       listed above may not appear in an alias name.  The replacement text may
2343       contain  any  valid  shell  input, including shell metacharacters.  The
2344       first word of the replacement text is tested for aliases,  but  a  word
2345       that  is  identical to an alias being expanded is not expanded a second
2346       time.  This means that one may alias ls to ls  -F,  for  instance,  and
2347       bash  does  not try to recursively expand the replacement text.  If the
2348       last character of the alias value is a blank,  then  the  next  command
2349       word following the alias is also checked for alias expansion.
2350
2351       Aliases are created and listed with the alias command, and removed with
2352       the unalias command.
2353
2354       There is no mechanism for using arguments in the replacement text.   If
2355       arguments  are  needed,  a shell function should be used (see FUNCTIONS
2356       below).
2357
2358       Aliases are not expanded when the shell is not interactive, unless  the
2359       expand_aliases  shell option is set using shopt (see the description of
2360       shopt under SHELL BUILTIN COMMANDS below).
2361
2362       The rules concerning the definition and use  of  aliases  are  somewhat
2363       confusing.   Bash always reads at least one complete line of input, and
2364       all lines that make up a compound command, before executing any of  the
2365       commands  on  that  line or the compound command.  Aliases are expanded
2366       when a command is read, not when it is executed.  Therefore,  an  alias
2367       definition  appearing on the same line as another command does not take
2368       effect until the next line of input is read.   The  commands  following
2369       the  alias  definition  on that line are not affected by the new alias.
2370       This behavior is also an issue when functions  are  executed.   Aliases
2371       are  expanded when a function definition is read, not when the function
2372       is executed, because a function definition is itself a command.   As  a
2373       consequence,  aliases defined in a function are not available until af‐
2374       ter that function is executed.  To be safe, always  put  alias  defini‐
2375       tions on a separate line, and do not use alias in compound commands.
2376
2377       For almost every purpose, aliases are superseded by shell functions.
2378

FUNCTIONS

2380       A  shell  function,  defined  as  described  above under SHELL GRAMMAR,
2381       stores a series of commands for later execution.  When the  name  of  a
2382       shell  function  is used as a simple command name, the list of commands
2383       associated with that function name is executed.  Functions are executed
2384       in  the  context of the current shell; no new process is created to in‐
2385       terpret them (contrast this with the  execution  of  a  shell  script).
2386       When  a  function is executed, the arguments to the function become the
2387       positional parameters during its execution.  The special parameter # is
2388       updated  to reflect the change.  Special parameter 0 is unchanged.  The
2389       first element of the FUNCNAME variable is set to the name of the  func‐
2390       tion while the function is executing.
2391
2392       All  other aspects of the shell execution environment are identical be‐
2393       tween a function and its caller with these exceptions:  the  DEBUG  and
2394       RETURN  traps  (see  the  description  of  the trap builtin under SHELL
2395       BUILTIN COMMANDS below) are not inherited unless the function has  been
2396       given  the  trace attribute (see the description of the declare builtin
2397       below) or the -o functrace shell option has been enabled with  the  set
2398       builtin  (in  which  case  all  functions  inherit the DEBUG and RETURN
2399       traps), and the ERR trap is not inherited unless the -o errtrace  shell
2400       option has been enabled.
2401
2402       Variables  local to the function may be declared with the local builtin
2403       command.  Ordinarily, variables and their values are shared between the
2404       function  and  its  caller.  If a variable is declared local, the vari‐
2405       able's visible scope is restricted to that function  and  its  children
2406       (including the functions it calls).  Local variables "shadow" variables
2407       with the same name declared at previous scopes.  For instance, a  local
2408       variable  declared  in  a  function hides a global variable of the same
2409       name: references and assignments refer to the local  variable,  leaving
2410       the  global variable unmodified.  When the function returns, the global
2411       variable is once again visible.
2412
2413       The shell uses dynamic  scoping  to  control  a  variable's  visibility
2414       within  functions.   With  dynamic scoping, visible variables and their
2415       values are a result of the sequence of function calls that caused  exe‐
2416       cution  to  reach the current function.  The value of a variable that a
2417       function sees depends on its value within its caller, if  any,  whether
2418       that  caller  is the "global" scope or another shell function.  This is
2419       also the value that a local variable  declaration  "shadows",  and  the
2420       value that is restored when the function returns.
2421
2422       For  example, if a variable var is declared as local in function func1,
2423       and func1 calls another function func2, references  to  var  made  from
2424       within func2 will resolve to the local variable var from func1, shadow‐
2425       ing any global variable named var.
2426
2427       The unset builtin also acts using the same dynamic scope: if a variable
2428       is local to the current scope, unset will unset it; otherwise the unset
2429       will refer to the variable found in  any  calling  scope  as  described
2430       above.   If a variable at the current local scope is unset, it will re‐
2431       main so until it is reset in that scope or until the function  returns.
2432       Once  the  function returns, any instance of the variable at a previous
2433       scope will become visible.  If the unset acts on a variable at a previ‐
2434       ous  scope,  any  instance  of  a variable with that name that had been
2435       shadowed will become visible.
2436
2437       The FUNCNEST variable, if set to a numeric value greater  than  0,  de‐
2438       fines  a maximum function nesting level.  Function invocations that ex‐
2439       ceed the limit cause the entire command to abort.
2440
2441       If the builtin command return is executed in a function,  the  function
2442       completes  and  execution resumes with the next command after the func‐
2443       tion call.  Any command associated with the RETURN trap is executed be‐
2444       fore  execution  resumes.  When a function completes, the values of the
2445       positional parameters and the special parameter # are restored  to  the
2446       values they had prior to the function's execution.
2447
2448       Function  names and definitions may be listed with the -f option to the
2449       declare or typeset builtin commands.  The -F option to declare or type‐
2450       set  will  list the function names only (and optionally the source file
2451       and line number, if the extdebug shell option is  enabled).   Functions
2452       may  be exported so that subshells automatically have them defined with
2453       the -f option to the export builtin.   A  function  definition  may  be
2454       deleted using the -f option to the unset builtin.
2455
2456       Functions may be recursive.  The FUNCNEST variable may be used to limit
2457       the depth of the function call stack and restrict the number  of  func‐
2458       tion invocations.  By default, no limit is imposed on the number of re‐
2459       cursive calls.
2460

ARITHMETIC EVALUATION

2462       The shell allows arithmetic expressions to be evaluated, under  certain
2463       circumstances  (see  the  let and declare builtin commands, the (( com‐
2464       pound command, and Arithmetic Expansion).  Evaluation is done in fixed-
2465       width  integers  with  no  check  for overflow, though division by 0 is
2466       trapped and flagged as an error.  The operators and  their  precedence,
2467       associativity,  and values are the same as in the C language.  The fol‐
2468       lowing list of operators is grouped into levels of equal-precedence op‐
2469       erators.  The levels are listed in order of decreasing precedence.
2470
2471       id++ id--
2472              variable post-increment and post-decrement
2473       - +    unary minus and plus
2474       ++id --id
2475              variable pre-increment and pre-decrement
2476       ! ~    logical and bitwise negation
2477       **     exponentiation
2478       * / %  multiplication, division, remainder
2479       + -    addition, subtraction
2480       << >>  left and right bitwise shifts
2481       <= >= < >
2482              comparison
2483       == !=  equality and inequality
2484       &      bitwise AND
2485       ^      bitwise exclusive OR
2486       |      bitwise OR
2487       &&     logical AND
2488       ||     logical OR
2489       expr?expr:expr
2490              conditional operator
2491       = *= /= %= += -= <<= >>= &= ^= |=
2492              assignment
2493       expr1 , expr2
2494              comma
2495
2496       Shell  variables  are  allowed as operands; parameter expansion is per‐
2497       formed before the expression is evaluated.  Within an expression, shell
2498       variables  may  also  be referenced by name without using the parameter
2499       expansion syntax.  A shell variable that is null or unset evaluates  to
2500       0 when referenced by name without using the parameter expansion syntax.
2501       The value of a variable is evaluated as an arithmetic  expression  when
2502       it  is  referenced, or when a variable which has been given the integer
2503       attribute using declare -i is assigned a value.  A null value evaluates
2504       to  0.   A shell variable need not have its integer attribute turned on
2505       to be used in an expression.
2506
2507       Integer constants follow the C language definition, without suffixes or
2508       character constants.  Constants with a leading 0 are interpreted as oc‐
2509       tal numbers.  A leading 0x or 0X denotes hexadecimal.  Otherwise,  num‐
2510       bers  take the form [base#]n, where the optional base is a decimal num‐
2511       ber between 2 and 64 representing the arithmetic base, and n is a  num‐
2512       ber  in  that  base.   If base# is omitted, then base 10 is used.  When
2513       specifying n, if a non-digit is required, the digits greater than 9 are
2514       represented  by the lowercase letters, the uppercase letters, @, and _,
2515       in that order.  If base is less than or equal to 36, lowercase and  up‐
2516       percase  letters  may  be used interchangeably to represent numbers be‐
2517       tween 10 and 35.
2518
2519       Operators are evaluated in order  of  precedence.   Sub-expressions  in
2520       parentheses  are  evaluated first and may override the precedence rules
2521       above.
2522

CONDITIONAL EXPRESSIONS

2524       Conditional expressions are used by the [[  compound  command  and  the
2525       test  and [ builtin commands to test file attributes and perform string
2526       and arithmetic comparisons.  The test and [  commands  determine  their
2527       behavior  based  on  the  number  of arguments; see the descriptions of
2528       those commands for any other command-specific actions.
2529
2530       Expressions are formed from the following unary  or  binary  primaries.
2531       Bash  handles several filenames specially when they are used in expres‐
2532       sions.  If the operating system on which bash is running provides these
2533       special  files,  bash will use them; otherwise it will emulate them in‐
2534       ternally with this behavior: If any file argument to one  of  the  pri‐
2535       maries is of the form /dev/fd/n, then file descriptor n is checked.  If
2536       the file argument to  one  of  the  primaries  is  one  of  /dev/stdin,
2537       /dev/stdout,  or /dev/stderr, file descriptor 0, 1, or 2, respectively,
2538       is checked.
2539
2540       Unless otherwise specified, primaries that operate on files follow sym‐
2541       bolic links and operate on the target of the link, rather than the link
2542       itself.
2543
2544       When used with [[, the < and > operators sort  lexicographically  using
2545       the current locale.  The test command sorts using ASCII ordering.
2546
2547       -a file
2548              True if file exists.
2549       -b file
2550              True if file exists and is a block special file.
2551       -c file
2552              True if file exists and is a character special file.
2553       -d file
2554              True if file exists and is a directory.
2555       -e file
2556              True if file exists.
2557       -f file
2558              True if file exists and is a regular file.
2559       -g file
2560              True if file exists and is set-group-id.
2561       -h file
2562              True if file exists and is a symbolic link.
2563       -k file
2564              True if file exists and its ``sticky'' bit is set.
2565       -p file
2566              True if file exists and is a named pipe (FIFO).
2567       -r file
2568              True if file exists and is readable.
2569       -s file
2570              True if file exists and has a size greater than zero.
2571       -t fd  True if file descriptor fd is open and refers to a terminal.
2572       -u file
2573              True if file exists and its set-user-id bit is set.
2574       -w file
2575              True if file exists and is writable.
2576       -x file
2577              True if file exists and is executable.
2578       -G file
2579              True if file exists and is owned by the effective group id.
2580       -L file
2581              True if file exists and is a symbolic link.
2582       -N file
2583              True  if  file  exists  and  has been modified since it was last
2584              read.
2585       -O file
2586              True if file exists and is owned by the effective user id.
2587       -S file
2588              True if file exists and is a socket.
2589       file1 -ef file2
2590              True if file1 and file2 refer to the same device and inode  num‐
2591              bers.
2592       file1 -nt file2
2593              True  if  file1  is  newer (according to modification date) than
2594              file2, or if file1 exists and file2 does not.
2595       file1 -ot file2
2596              True if file1 is older than file2, or if file2 exists and  file1
2597              does not.
2598       -o optname
2599              True  if  the  shell option optname is enabled.  See the list of
2600              options under the description  of  the  -o  option  to  the  set
2601              builtin below.
2602       -v varname
2603              True  if  the shell variable varname is set (has been assigned a
2604              value).
2605       -R varname
2606              True if the shell variable varname is set and is a  name  refer‐
2607              ence.
2608       -z string
2609              True if the length of string is zero.
2610       string
2611       -n string
2612              True if the length of string is non-zero.
2613
2614       string1 == string2
2615       string1 = string2
2616              True  if  the strings are equal.  = should be used with the test
2617              command for POSIX conformance.  When used with the  [[  command,
2618              this performs pattern matching as described above (Compound Com‐
2619              mands).
2620
2621       string1 != string2
2622              True if the strings are not equal.
2623
2624       string1 < string2
2625              True if string1 sorts before string2 lexicographically.
2626
2627       string1 > string2
2628              True if string1 sorts after string2 lexicographically.
2629
2630       arg1 OP arg2
2631              OP is one of -eq, -ne, -lt, -le, -gt, or -ge.  These  arithmetic
2632              binary  operators return true if arg1 is equal to, not equal to,
2633              less than, less than or equal to, greater than, or greater  than
2634              or  equal  to arg2, respectively.  Arg1 and arg2 may be positive
2635              or negative integers.  When used with the [[ command,  Arg1  and
2636              Arg2  are  evaluated  as  arithmetic expressions (see ARITHMETIC
2637              EVALUATION above).
2638

SIMPLE COMMAND EXPANSION

2640       When a simple command is executed, the shell performs the following ex‐
2641       pansions,  assignments,  and  redirections,  from left to right, in the
2642       following order.
2643
2644       1.     The words that the parser has  marked  as  variable  assignments
2645              (those  preceding  the  command name) and redirections are saved
2646              for later processing.
2647
2648       2.     The words that are not variable assignments or redirections  are
2649              expanded.   If  any words remain after expansion, the first word
2650              is taken to be the name of the command and the  remaining  words
2651              are the arguments.
2652
2653       3.     Redirections are performed as described above under REDIRECTION.
2654
2655       4.     The text after the = in each variable assignment undergoes tilde
2656              expansion, parameter expansion, command substitution, arithmetic
2657              expansion,  and quote removal before being assigned to the vari‐
2658              able.
2659
2660       If no command name results, the variable assignments affect the current
2661       shell  environment.  Otherwise, the variables are added to the environ‐
2662       ment of the executed command and do not affect the current shell  envi‐
2663       ronment.   If  any  of  the assignments attempts to assign a value to a
2664       readonly variable, an error occurs, and the command exits with  a  non-
2665       zero status.
2666
2667       If  no command name results, redirections are performed, but do not af‐
2668       fect the current shell environment.  A  redirection  error  causes  the
2669       command to exit with a non-zero status.
2670
2671       If  there is a command name left after expansion, execution proceeds as
2672       described below.  Otherwise, the command exits.  If one of  the  expan‐
2673       sions  contained a command substitution, the exit status of the command
2674       is the exit status of the  last  command  substitution  performed.   If
2675       there were no command substitutions, the command exits with a status of
2676       zero.
2677

COMMAND EXECUTION

2679       After a command has been split into words, if it results  in  a  simple
2680       command  and  an  optional list of arguments, the following actions are
2681       taken.
2682
2683       If the command name contains no slashes, the shell attempts  to  locate
2684       it.   If  there  exists a shell function by that name, that function is
2685       invoked as described above in FUNCTIONS.  If the name does not match  a
2686       function,  the shell searches for it in the list of shell builtins.  If
2687       a match is found, that builtin is invoked.
2688
2689       If the name is neither a shell function nor a builtin, and contains  no
2690       slashes,  bash  searches  each element of the PATH for a directory con‐
2691       taining an executable file by that name.  Bash uses a hash table to re‐
2692       member  the  full  pathnames  of executable files (see hash under SHELL
2693       BUILTIN COMMANDS below).  A full search of the directories in  PATH  is
2694       performed  only  if the command is not found in the hash table.  If the
2695       search is unsuccessful, the shell searches for a defined shell function
2696       named command_not_found_handle.  If that function exists, it is invoked
2697       in a separate execution environment with the original command  and  the
2698       original  command's arguments as its arguments, and the function's exit
2699       status becomes the exit status of that subshell.  If that  function  is
2700       not defined, the shell prints an error message and returns an exit sta‐
2701       tus of 127.
2702
2703       If the search is successful, or if the command  name  contains  one  or
2704       more slashes, the shell executes the named program in a separate execu‐
2705       tion environment.  Argument 0 is set to the name given, and the remain‐
2706       ing arguments to the command are set to the arguments given, if any.
2707
2708       If  this  execution fails because the file is not in executable format,
2709       and the file is not a directory, it is assumed to be a shell script,  a
2710       file  containing  shell commands.  A subshell is spawned to execute it.
2711       This subshell reinitializes itself, so that the effect is as if  a  new
2712       shell  had  been  invoked to handle the script, with the exception that
2713       the locations of commands remembered by the parent (see hash below  un‐
2714       der SHELL BUILTIN COMMANDS) are retained by the child.
2715
2716       If  the program is a file beginning with #!, the remainder of the first
2717       line specifies an interpreter for the program.  The shell executes  the
2718       specified interpreter on operating systems that do not handle this exe‐
2719       cutable format themselves.  The arguments to the interpreter consist of
2720       a  single optional argument following the interpreter name on the first
2721       line of the program, followed by the name of the program,  followed  by
2722       the command arguments, if any.
2723

COMMAND EXECUTION ENVIRONMENT

2725       The  shell  has an execution environment, which consists of the follow‐
2726       ing:
2727
2728       •      open files inherited by the shell at invocation, as modified  by
2729              redirections supplied to the exec builtin
2730
2731       •      the  current  working directory as set by cd, pushd, or popd, or
2732              inherited by the shell at invocation
2733
2734       •      the file creation mode mask as set by umask  or  inherited  from
2735              the shell's parent
2736
2737       •      current traps set by trap
2738
2739       •      shell parameters that are set by variable assignment or with set
2740              or inherited from the shell's parent in the environment
2741
2742       •      shell functions defined during execution or inherited  from  the
2743              shell's parent in the environment
2744
2745       •      options  enabled  at  invocation (either by default or with com‐
2746              mand-line arguments) or by set
2747
2748       •      options enabled by shopt
2749
2750       •      shell aliases defined with alias
2751
2752       •      various process IDs, including those  of  background  jobs,  the
2753              value of $$, and the value of PPID
2754
2755       When  a  simple command other than a builtin or shell function is to be
2756       executed, it is invoked in a separate execution environment  that  con‐
2757       sists  of the following.  Unless otherwise noted, the values are inher‐
2758       ited from the shell.
2759
2760
2761       •      the shell's open files, plus  any  modifications  and  additions
2762              specified by redirections to the command
2763
2764       •      the current working directory
2765
2766       •      the file creation mode mask
2767
2768       •      shell  variables  and  functions  marked  for export, along with
2769              variables exported for the command, passed in the environment
2770
2771       •      traps caught by the shell are reset to the values inherited from
2772              the shell's parent, and traps ignored by the shell are ignored
2773
2774       A  command  invoked  in  this  separate  environment  cannot affect the
2775       shell's execution environment.
2776
2777       Command substitution, commands grouped with parentheses, and  asynchro‐
2778       nous commands are invoked in a subshell environment that is a duplicate
2779       of the shell environment, except that traps caught by the shell are re‐
2780       set  to  the values that the shell inherited from its parent at invoca‐
2781       tion.  Builtin commands that are invoked as part of a pipeline are also
2782       executed in a subshell environment.  Changes made to the subshell envi‐
2783       ronment cannot affect the shell's execution environment.
2784
2785       Subshells spawned to execute command substitutions inherit the value of
2786       the  -e  option  from  the  parent shell.  When not in posix mode, bash
2787       clears the -e option in such subshells.
2788
2789       If a command is followed by a & and job control is not active, the  de‐
2790       fault standard input for the command is the empty file /dev/null.  Oth‐
2791       erwise, the invoked command inherits the file descriptors of the  call‐
2792       ing shell as modified by redirections.
2793

ENVIRONMENT

2795       When  a  program  is invoked it is given an array of strings called the
2796       environment.   This  is  a  list  of  name-value  pairs,  of  the  form
2797       name=value.
2798
2799       The  shell provides several ways to manipulate the environment.  On in‐
2800       vocation, the shell scans its own environment and creates  a  parameter
2801       for  each name found, automatically marking it for export to child pro‐
2802       cesses.  Executed commands inherit the environment.  The export and de‐
2803       clare  -x  commands  allow  parameters and functions to be added to and
2804       deleted from the environment.  If the value of a parameter in the envi‐
2805       ronment is modified, the new value becomes part of the environment, re‐
2806       placing the old.  The environment inherited  by  any  executed  command
2807       consists  of the shell's initial environment, whose values may be modi‐
2808       fied in the shell, less any pairs removed by the  unset  command,  plus
2809       any additions via the export and declare -x commands.
2810
2811       The  environment  for  any  simple command or function may be augmented
2812       temporarily by prefixing it with parameter  assignments,  as  described
2813       above in PARAMETERS.  These assignment statements affect only the envi‐
2814       ronment seen by that command.
2815
2816       If the -k option is set (see the set builtin command below),  then  all
2817       parameter  assignments are placed in the environment for a command, not
2818       just those that precede the command name.
2819
2820       When bash invokes an external command, the variable _  is  set  to  the
2821       full filename of the command and passed to that command in its environ‐
2822       ment.
2823

EXIT STATUS

2825       The exit status of an executed command is the  value  returned  by  the
2826       waitpid system call or equivalent function.  Exit statuses fall between
2827       0 and 255, though, as explained below, the shell may use  values  above
2828       125 specially.  Exit statuses from shell builtins and compound commands
2829       are also limited to this range.  Under certain circumstances, the shell
2830       will use special values to indicate specific failure modes.
2831
2832       For the shell's purposes, a command which exits with a zero exit status
2833       has succeeded.  An exit status of zero indicates success.   A  non-zero
2834       exit  status  indicates  failure.  When a command terminates on a fatal
2835       signal N, bash uses the value of 128+N as the exit status.
2836
2837       If a command is not found, the child process created to execute it  re‐
2838       turns  a  status  of 127.  If a command is found but is not executable,
2839       the return status is 126.
2840
2841       If a command fails because of an error during expansion or redirection,
2842       the exit status is greater than zero.
2843
2844       Shell  builtin  commands return a status of 0 (true) if successful, and
2845       non-zero (false) if an error occurs while they execute.   All  builtins
2846       return  an  exit status of 2 to indicate incorrect usage, generally in‐
2847       valid options or missing arguments.
2848
2849       Bash itself returns the exit status of the last command  executed,  un‐
2850       less  a  syntax  error  occurs,  in which case it exits with a non-zero
2851       value.  See also the exit builtin command below.
2852

SIGNALS

2854       When bash is interactive, in the  absence  of  any  traps,  it  ignores
2855       SIGTERM (so that kill 0 does not kill an interactive shell), and SIGINT
2856       is caught and handled (so that the wait builtin is interruptible).   In
2857       all cases, bash ignores SIGQUIT.  If job control is in effect, bash ig‐
2858       nores SIGTTIN, SIGTTOU, and SIGTSTP.
2859
2860       Non-builtin commands run by bash have signal handlers set to the values
2861       inherited by the shell from its parent.  When job control is not in ef‐
2862       fect, asynchronous commands ignore SIGINT and SIGQUIT  in  addition  to
2863       these  inherited handlers.  Commands run as a result of command substi‐
2864       tution ignore the keyboard-generated job control signals SIGTTIN, SIGT‐
2865       TOU, and SIGTSTP.
2866
2867       The  shell  exits by default upon receipt of a SIGHUP.  Before exiting,
2868       an interactive shell  resends  the  SIGHUP  to  all  jobs,  running  or
2869       stopped.  Stopped jobs are sent SIGCONT to ensure that they receive the
2870       SIGHUP.  To prevent the shell from sending the signal to  a  particular
2871       job,  it  should be removed from the jobs table with the disown builtin
2872       (see SHELL BUILTIN COMMANDS below) or marked to not receive SIGHUP  us‐
2873       ing disown -h.
2874
2875       If  the  huponexit  shell  option has been set with shopt, bash sends a
2876       SIGHUP to all jobs when an interactive login shell exits.
2877
2878       If bash is waiting for a command to complete and receives a signal  for
2879       which a trap has been set, the trap will not be executed until the com‐
2880       mand completes.  When bash is waiting for an asynchronous  command  via
2881       the  wait  builtin, the reception of a signal for which a trap has been
2882       set will cause the wait builtin to return immediately with an exit sta‐
2883       tus greater than 128, immediately after which the trap is executed.
2884

JOB CONTROL

2886       Job control refers to the ability to selectively stop (suspend) the ex‐
2887       ecution of processes and continue (resume) their execution at  a  later
2888       point.   A  user typically employs this facility via an interactive in‐
2889       terface supplied jointly by  the  operating  system  kernel's  terminal
2890       driver and bash.
2891
2892       The  shell  associates  a  job with each pipeline.  It keeps a table of
2893       currently executing jobs, which may be listed with  the  jobs  command.
2894       When  bash starts a job asynchronously (in the background), it prints a
2895       line that looks like:
2896
2897              [1] 25647
2898
2899       indicating that this job is job number 1 and that the process ID of the
2900       last process in the pipeline associated with this job is 25647.  All of
2901       the processes in a single pipeline are members of the same  job.   Bash
2902       uses the job abstraction as the basis for job control.
2903
2904       To  facilitate the implementation of the user interface to job control,
2905       the operating system maintains the notion of a current terminal process
2906       group ID.  Members of this process group (processes whose process group
2907       ID is equal to the current terminal process group ID) receive keyboard-
2908       generated  signals  such  as SIGINT.  These processes are said to be in
2909       the foreground.  Background processes are those whose process group  ID
2910       differs from the terminal's; such processes are immune to keyboard-gen‐
2911       erated signals.  Only foreground processes are allowed to read from or,
2912       if  the  user  so  specifies  with  stty tostop, write to the terminal.
2913       Background processes which attempt to read from  (write  to  when  stty
2914       tostop  is  in effect) the terminal are sent a SIGTTIN (SIGTTOU) signal
2915       by the kernel's terminal driver, which,  unless  caught,  suspends  the
2916       process.
2917
2918       If  the operating system on which bash is running supports job control,
2919       bash contains facilities to use it.  Typing the suspend character (typ‐
2920       ically ^Z, Control-Z) while a process is running causes that process to
2921       be stopped and returns control to bash.   Typing  the  delayed  suspend
2922       character  (typically  ^Y,  Control-Y) causes the process to be stopped
2923       when it attempts to read input from the terminal, and control to be re‐
2924       turned  to  bash.   The user may then manipulate the state of this job,
2925       using the bg command to continue it in the background, the  fg  command
2926       to continue it in the foreground, or the kill command to kill it.  A ^Z
2927       takes effect immediately, and has the additional side effect of causing
2928       pending output and typeahead to be discarded.
2929
2930       There are a number of ways to refer to a job in the shell.  The charac‐
2931       ter % introduces a job specification (jobspec).  Job number  n  may  be
2932       referred to as %n.  A job may also be referred to using a prefix of the
2933       name used to start it, or using a substring that appears in its command
2934       line.   For example, %ce refers to a stopped job whose command name be‐
2935       gins with ce.  If a prefix matches more than one job, bash  reports  an
2936       error.  Using %?ce, on the other hand, refers to any job containing the
2937       string ce in its command line.  If the substring matches more than  one
2938       job, bash reports an error.  The symbols %% and %+ refer to the shell's
2939       notion of the current job, which is the last job stopped while  it  was
2940       in  the  foreground or started in the background.  The previous job may
2941       be referenced using %-.  If there is only a single job, %+ and  %-  can
2942       both be used to refer to that job.  In output pertaining to jobs (e.g.,
2943       the output of the jobs command), the current job is always flagged with
2944       a  +,  and the previous job with a -.  A single % (with no accompanying
2945       job specification) also refers to the current job.
2946
2947       Simply naming a job can be used to bring it into the foreground: %1  is
2948       a  synonym  for  ``fg %1'', bringing job 1 from the background into the
2949       foreground.  Similarly, ``%1 &''  resumes  job  1  in  the  background,
2950       equivalent to ``bg %1''.
2951
2952       The  shell  learns immediately whenever a job changes state.  Normally,
2953       bash waits until it is about to print a prompt before reporting changes
2954       in  a  job's status so as to not interrupt any other output.  If the -b
2955       option to the set builtin command is enabled, bash reports such changes
2956       immediately.   Any  trap on SIGCHLD is executed for each child that ex‐
2957       its.
2958
2959       If an attempt to exit bash is made while jobs are stopped (or,  if  the
2960       checkjobs  shell  option has been enabled using the shopt builtin, run‐
2961       ning), the shell prints a warning message, and, if the checkjobs option
2962       is  enabled,  lists  the jobs and their statuses.  The jobs command may
2963       then be used to inspect their status.  If a second attempt to  exit  is
2964       made  without  an intervening command, the shell does not print another
2965       warning, and any stopped jobs are terminated.
2966
2967       When the shell is waiting for a job or process using the wait  builtin,
2968       and  job  control  is  enabled,  wait  will return when the job changes
2969       state. The -f option causes wait to wait until the job or process  ter‐
2970       minates before returning.
2971

PROMPTING

2973       When executing interactively, bash displays the primary prompt PS1 when
2974       it is ready to read a command, and the secondary  prompt  PS2  when  it
2975       needs  more  input  to  complete a command.  Bash displays PS0 after it
2976       reads a command but before executing it.   Bash  displays  PS4  as  de‐
2977       scribed  above  before  tracing  each command when the -x option is en‐
2978       abled.  Bash allows these prompt strings to be customized by  inserting
2979       a  number  of  backslash-escaped special characters that are decoded as
2980       follows:
2981              \a     an ASCII bell character (07)
2982              \d     the date in "Weekday Month Date" format (e.g.,  "Tue  May
2983                     26")
2984              \D{format}
2985                     the format is passed to strftime(3) and the result is in‐
2986                     serted into the prompt string; an empty format results in
2987                     a  locale-specific  time  representation.  The braces are
2988                     required
2989              \e     an ASCII escape character (033)
2990              \h     the hostname up to the first `.'
2991              \H     the hostname
2992              \j     the number of jobs currently managed by the shell
2993              \l     the basename of the shell's terminal device name
2994              \n     newline
2995              \r     carriage return
2996              \s     the name of the shell, the basename of  $0  (the  portion
2997                     following the final slash)
2998              \t     the current time in 24-hour HH:MM:SS format
2999              \T     the current time in 12-hour HH:MM:SS format
3000              \@     the current time in 12-hour am/pm format
3001              \A     the current time in 24-hour HH:MM format
3002              \u     the username of the current user
3003              \v     the version of bash (e.g., 2.00)
3004              \V     the release of bash, version + patch level (e.g., 2.00.0)
3005              \w     the  current  working  directory,  with $HOME abbreviated
3006                     with a tilde (uses the value of the PROMPT_DIRTRIM  vari‐
3007                     able)
3008              \W     the basename of the current working directory, with $HOME
3009                     abbreviated with a tilde
3010              \!     the history number of this command
3011              \#     the command number of this command
3012              \$     if the effective UID is 0, a #, otherwise a $
3013              \nnn   the character corresponding to the octal number nnn
3014              \\     a backslash
3015              \[     begin a sequence of non-printing characters, which  could
3016                     be  used  to  embed  a terminal control sequence into the
3017                     prompt
3018              \]     end a sequence of non-printing characters
3019
3020       The command number and the history number are  usually  different:  the
3021       history  number of a command is its position in the history list, which
3022       may include commands restored from the history file  (see  HISTORY  be‐
3023       low),  while the command number is the position in the sequence of com‐
3024       mands executed during the current shell session.  After the  string  is
3025       decoded,  it is expanded via parameter expansion, command substitution,
3026       arithmetic expansion, and quote removal, subject to the  value  of  the
3027       promptvars shell option (see the description of the shopt command under
3028       SHELL BUILTIN COMMANDS below).  This can have unwanted side effects  if
3029       escaped  portions  of  the string appear within command substitution or
3030       contain characters special to word expansion.
3031

READLINE

3033       This is the library that handles reading input when using  an  interac‐
3034       tive shell, unless the --noediting option is given at shell invocation.
3035       Line editing is also used when using the -e option to the read builtin.
3036       By default, the line editing commands are similar to those of Emacs.  A
3037       vi-style line editing interface is also available.  Line editing can be
3038       enabled  at  any  time  using  the -o emacs or -o vi options to the set
3039       builtin (see SHELL BUILTIN COMMANDS below).  To turn off  line  editing
3040       after  the  shell  is running, use the +o emacs or +o vi options to the
3041       set builtin.
3042
3043   Readline Notation
3044       In this section, the Emacs-style notation is used to denote keystrokes.
3045       Control  keys  are  denoted by C-key, e.g., C-n means Control-N.  Simi‐
3046       larly, meta keys are denoted by M-key, so M-x means Meta-X.   (On  key‐
3047       boards  without a meta key, M-x means ESC x, i.e., press the Escape key
3048       then the x key.  This makes ESC the meta prefix.  The combination M-C-x
3049       means  ESC-Control-x, or press the Escape key then hold the Control key
3050       while pressing the x key.)
3051
3052       Readline commands may be given numeric arguments, which normally act as
3053       a  repeat  count.   Sometimes,  however, it is the sign of the argument
3054       that is significant.  Passing a negative argument  to  a  command  that
3055       acts  in the forward direction (e.g., kill-line) causes that command to
3056       act in a backward direction.  Commands whose  behavior  with  arguments
3057       deviates from this are noted below.
3058
3059       When  a command is described as killing text, the text deleted is saved
3060       for possible future retrieval (yanking).  The killed text is saved in a
3061       kill ring.  Consecutive kills cause the text to be accumulated into one
3062       unit, which can be yanked all at once.  Commands which do not kill text
3063       separate the chunks of text on the kill ring.
3064
3065   Readline Initialization
3066       Readline  is  customized  by putting commands in an initialization file
3067       (the inputrc file).  The name of this file is taken from the  value  of
3068       the INPUTRC variable.  If that variable is unset, the default is ~/.in‐
3069       putrc.  If that file  does not exist or cannot be  read,  the  ultimate
3070       default  is  /etc/inputrc.   When a program which uses the readline li‐
3071       brary starts up, the initialization file is read, and the key  bindings
3072       and  variables  are set.  There are only a few basic constructs allowed
3073       in the readline initialization file.  Blank lines are  ignored.   Lines
3074       beginning  with  a  #  are comments.  Lines beginning with a $ indicate
3075       conditional constructs.  Other lines denote key bindings  and  variable
3076       settings.
3077
3078       The  default  key-bindings  may be changed with an inputrc file.  Other
3079       programs that use this library may add their own commands and bindings.
3080
3081       For example, placing
3082
3083              M-Control-u: universal-argument
3084       or
3085              C-Meta-u: universal-argument
3086       into the inputrc would make M-C-u execute the readline command  univer‐
3087       sal-argument.
3088
3089       The  following  symbolic  character  names are recognized: RUBOUT, DEL,
3090       ESC, LFD, NEWLINE, RET, RETURN, SPC, SPACE, and TAB.
3091
3092       In addition to command names, readline allows keys to  be  bound  to  a
3093       string that is inserted when the key is pressed (a macro).
3094
3095   Readline Key Bindings
3096       The  syntax for controlling key bindings in the inputrc file is simple.
3097       All that is required is the name of the command or the text of a  macro
3098       and a key sequence to which it should be bound.  The name may be speci‐
3099       fied in one of two ways: as a symbolic key name, possibly with Meta- or
3100       Control- prefixes, or as a key sequence.
3101
3102       When using the form keyname:function-name or macro, keyname is the name
3103       of a key spelled out in English.  For example:
3104
3105              Control-u: universal-argument
3106              Meta-Rubout: backward-kill-word
3107              Control-o: "> output"
3108
3109       In the above example, C-u is bound to the function  universal-argument,
3110       M-DEL  is bound to the function backward-kill-word, and C-o is bound to
3111       run the macro expressed on the right hand side (that is, to insert  the
3112       text ``> output'' into the line).
3113
3114       In  the  second  form,  "keyseq":function-name or macro, keyseq differs
3115       from keyname above in that strings denoting an entire key sequence  may
3116       be  specified  by  placing the sequence within double quotes.  Some GNU
3117       Emacs style key escapes can be used, as in the following  example,  but
3118       the symbolic character names are not recognized.
3119
3120              "\C-u": universal-argument
3121              "\C-x\C-r": re-read-init-file
3122              "\e[11~": "Function Key 1"
3123
3124       In this example, C-u is again bound to the function universal-argument.
3125       C-x C-r is bound to the function re-read-init-file, and ESC [ 1 1 ~  is
3126       bound to insert the text ``Function Key 1''.
3127
3128       The full set of GNU Emacs style escape sequences is
3129              \C-    control prefix
3130              \M-    meta prefix
3131              \e     an escape character
3132              \\     backslash
3133              \"     literal "
3134              \'     literal '
3135
3136       In  addition  to  the GNU Emacs style escape sequences, a second set of
3137       backslash escapes is available:
3138              \a     alert (bell)
3139              \b     backspace
3140              \d     delete
3141              \f     form feed
3142              \n     newline
3143              \r     carriage return
3144              \t     horizontal tab
3145              \v     vertical tab
3146              \nnn   the eight-bit character whose value is  the  octal  value
3147                     nnn (one to three digits)
3148              \xHH   the  eight-bit  character  whose value is the hexadecimal
3149                     value HH (one or two hex digits)
3150
3151       When entering the text of a macro, single or double quotes must be used
3152       to indicate a macro definition.  Unquoted text is assumed to be a func‐
3153       tion name.  In the macro body, the backslash  escapes  described  above
3154       are  expanded.   Backslash  will quote any other character in the macro
3155       text, including " and '.
3156
3157       Bash allows the current readline key bindings to be displayed or  modi‐
3158       fied  with  the bind builtin command.  The editing mode may be switched
3159       during interactive use by using the -o option to the set  builtin  com‐
3160       mand (see SHELL BUILTIN COMMANDS below).
3161
3162   Readline Variables
3163       Readline has variables that can be used to further customize its behav‐
3164       ior.  A variable may be set in the inputrc file with a statement of the
3165       form
3166
3167              set variable-name value
3168       or using the bind builtin command (see SHELL BUILTIN COMMANDS below).
3169
3170       Except  where  noted,  readline variables can take the values On or Off
3171       (without regard to case).  Unrecognized  variable  names  are  ignored.
3172       When  a variable value is read, empty or null values, "on" (case-insen‐
3173       sitive), and "1" are equivalent to On.  All other values are equivalent
3174       to Off.  The variables and their default values are:
3175
3176       bell-style (audible)
3177              Controls  what  happens when readline wants to ring the terminal
3178              bell.  If set to none, readline never rings the bell.  If set to
3179              visible,  readline  uses a visible bell if one is available.  If
3180              set to audible, readline attempts to ring the terminal's bell.
3181       bind-tty-special-chars (On)
3182              If set to On, readline attempts to bind the  control  characters
3183              treated specially by the kernel's terminal driver to their read‐
3184              line equivalents.
3185       blink-matching-paren (Off)
3186              If set to On, readline attempts to briefly move the cursor to an
3187              opening parenthesis when a closing parenthesis is inserted.
3188       colored-completion-prefix (Off)
3189              If  set  to  On, when listing completions, readline displays the
3190              common prefix of the set of possible completions using a differ‐
3191              ent  color.   The  color definitions are taken from the value of
3192              the LS_COLORS environment variable.
3193       colored-stats (Off)
3194              If set to On, readline displays possible completions using  dif‐
3195              ferent  colors  to  indicate their file type.  The color defini‐
3196              tions are taken from the  value  of  the  LS_COLORS  environment
3197              variable.
3198       comment-begin (``#'')
3199              The  string  that  is  inserted when the readline insert-comment
3200              command is executed.  This command is bound to M-# in emacs mode
3201              and to # in vi command mode.
3202       completion-display-width (-1)
3203              The  number  of  screen columns used to display possible matches
3204              when performing completion.  The value is ignored if it is  less
3205              than  0 or greater than the terminal screen width.  A value of 0
3206              will cause matches to be displayed one per  line.   The  default
3207              value is -1.
3208       completion-ignore-case (Off)
3209              If set to On, readline performs filename matching and completion
3210              in a case-insensitive fashion.
3211       completion-map-case (Off)
3212              If set to On, and completion-ignore-case  is  enabled,  readline
3213              treats  hyphens  (-) and underscores (_) as equivalent when per‐
3214              forming case-insensitive filename matching and completion.
3215       completion-prefix-display-length (0)
3216              The length in characters of the common prefix of a list of  pos‐
3217              sible  completions that is displayed without modification.  When
3218              set to a value greater than zero, common  prefixes  longer  than
3219              this  value are replaced with an ellipsis when displaying possi‐
3220              ble completions.
3221       completion-query-items (100)
3222              This determines when the user is queried about viewing the  num‐
3223              ber  of  possible  completions generated by the possible-comple‐
3224              tions command.  It may be set to any integer value greater  than
3225              or  equal  to  zero.   If  the number of possible completions is
3226              greater than or equal to the value of  this  variable,  readline
3227              will  ask whether or not the user wishes to view them; otherwise
3228              they are simply listed on the terminal.
3229       convert-meta (On)
3230              If set to On, readline will convert characters with  the  eighth
3231              bit set to an ASCII key sequence by stripping the eighth bit and
3232              prefixing an escape character (in effect, using  escape  as  the
3233              meta  prefix).   The  default is On, but readline will set it to
3234              Off if the locale contains eight-bit characters.
3235       disable-completion (Off)
3236              If set to On, readline will inhibit word completion.  Completion
3237              characters  will  be  inserted into the line as if they had been
3238              mapped to self-insert.
3239       echo-control-characters (On)
3240              When set to On, on operating systems that indicate they  support
3241              it, readline echoes a character corresponding to a signal gener‐
3242              ated from the keyboard.
3243       editing-mode (emacs)
3244              Controls whether readline begins with a set of key bindings sim‐
3245              ilar to Emacs or vi.  editing-mode can be set to either emacs or
3246              vi.
3247       emacs-mode-string (@)
3248              If the show-mode-in-prompt variable is enabled, this  string  is
3249              displayed immediately before the last line of the primary prompt
3250              when emacs editing mode is active.  The value is expanded like a
3251              key  binding,  so the standard set of meta- and control prefixes
3252              and backslash escape sequences is available.  Use the \1 and  \2
3253              escapes  to  begin and end sequences of non-printing characters,
3254              which can be used to embed a terminal control sequence into  the
3255              mode string.
3256       enable-bracketed-paste (On)
3257              When  set  to  On, readline will configure the terminal in a way
3258              that will enable it to insert each paste into the editing buffer
3259              as a single string of characters, instead of treating each char‐
3260              acter as if it had been read from the keyboard.  This  can  pre‐
3261              vent  pasted  characters  from being interpreted as editing com‐
3262              mands.
3263       enable-keypad (Off)
3264              When set to On, readline will try to enable the application key‐
3265              pad when it is called.  Some systems need this to enable the ar‐
3266              row keys.
3267       enable-meta-key (On)
3268              When set to On, readline will try to enable  any  meta  modifier
3269              key  the  terminal claims to support when it is called.  On many
3270              terminals, the meta key is used to send eight-bit characters.
3271       expand-tilde (Off)
3272              If set to On, tilde expansion is  performed  when  readline  at‐
3273              tempts word completion.
3274       history-preserve-point (Off)
3275              If  set  to  On, the history code attempts to place point at the
3276              same location on each history line retrieved with  previous-his‐
3277              tory or next-history.
3278       history-size (unset)
3279              Set  the  maximum number of history entries saved in the history
3280              list.  If set to zero, any existing history entries are  deleted
3281              and no new entries are saved.  If set to a value less than zero,
3282              the number of history entries is not limited.  By  default,  the
3283              number  of  history  entries is set to the value of the HISTSIZE
3284              shell variable.  If an attempt is made to set history-size to  a
3285              non-numeric value, the maximum number of history entries will be
3286              set to 500.
3287       horizontal-scroll-mode (Off)
3288              When set to On, makes readline use a single  line  for  display,
3289              scrolling the input horizontally on a single screen line when it
3290              becomes longer than the screen width rather than wrapping  to  a
3291              new  line.   This setting is automatically enabled for terminals
3292              of height 1.
3293       input-meta (Off)
3294              If set to On, readline will enable eight-bit input (that is,  it
3295              will not strip the eighth bit from the characters it reads), re‐
3296              gardless of what the terminal claims it can support.   The  name
3297              meta-flag  is  a synonym for this variable.  The default is Off,
3298              but readline will set it to On if the locale contains  eight-bit
3299              characters.
3300       isearch-terminators (``C-[C-J'')
3301              The  string  of  characters that should terminate an incremental
3302              search without subsequently executing the character  as  a  com‐
3303              mand.   If this variable has not been given a value, the charac‐
3304              ters ESC and C-J will terminate an incremental search.
3305       keymap (emacs)
3306              Set the current readline keymap.  The set of valid keymap  names
3307              is  emacs,  emacs-standard,  emacs-meta, emacs-ctlx, vi, vi-com‐
3308              mand, and vi-insert.  vi is equivalent to vi-command;  emacs  is
3309              equivalent  to  emacs-standard.  The default value is emacs; the
3310              value of editing-mode also affects the default keymap.
3311       keyseq-timeout (500)
3312              Specifies the duration readline will wait for a  character  when
3313              reading  an ambiguous key sequence (one that can form a complete
3314              key sequence using the input read so far, or can take additional
3315              input  to  complete  a longer key sequence).  If no input is re‐
3316              ceived within the timeout, readline will  use  the  shorter  but
3317              complete  key sequence.  The value is specified in milliseconds,
3318              so a value of 1000 means that readline will wait one second  for
3319              additional  input.  If this variable is set to a value less than
3320              or equal to zero, or to a non-numeric value, readline will  wait
3321              until  another  key  is  pressed to decide which key sequence to
3322              complete.
3323       mark-directories (On)
3324              If set to On, completed directory names have a slash appended.
3325       mark-modified-lines (Off)
3326              If set to On, history lines that have  been  modified  are  dis‐
3327              played with a preceding asterisk (*).
3328       mark-symlinked-directories (Off)
3329              If set to On, completed names which are symbolic links to direc‐
3330              tories have a slash appended (subject to the value  of  mark-di‐
3331              rectories).
3332       match-hidden-files (On)
3333              This  variable,  when  set to On, causes readline to match files
3334              whose names begin with a  `.'  (hidden  files)  when  performing
3335              filename  completion.   If  set  to Off, the leading `.' must be
3336              supplied by the user in the filename to be completed.
3337       menu-complete-display-prefix (Off)
3338              If set to On, menu completion displays the common prefix of  the
3339              list of possible completions (which may be empty) before cycling
3340              through the list.
3341       output-meta (Off)
3342              If set to On, readline will display characters with  the  eighth
3343              bit set directly rather than as a meta-prefixed escape sequence.
3344              The default is Off, but readline will set it to On if the locale
3345              contains eight-bit characters.
3346       page-completions (On)
3347              If  set to On, readline uses an internal more-like pager to dis‐
3348              play a screenful of possible completions at a time.
3349       print-completions-horizontally (Off)
3350              If set to On, readline will  display  completions  with  matches
3351              sorted  horizontally in alphabetical order, rather than down the
3352              screen.
3353       revert-all-at-newline (Off)
3354              If set to On, readline will undo all changes  to  history  lines
3355              before returning when accept-line is executed.  By default, his‐
3356              tory lines may be modified  and  retain  individual  undo  lists
3357              across calls to readline.
3358       show-all-if-ambiguous (Off)
3359              This  alters  the  default behavior of the completion functions.
3360              If set to On, words which have more than one possible completion
3361              cause  the  matches  to be listed immediately instead of ringing
3362              the bell.
3363       show-all-if-unmodified (Off)
3364              This alters the default behavior of the completion functions  in
3365              a fashion similar to show-all-if-ambiguous.  If set to On, words
3366              which have more than one possible completion without any  possi‐
3367              ble  partial  completion (the possible completions don't share a
3368              common prefix) cause the matches to be  listed  immediately  in‐
3369              stead of ringing the bell.
3370       show-mode-in-prompt (Off)
3371              If  set to On, add a string to the beginning of the prompt indi‐
3372              cating the editing mode: emacs, vi  command,  or  vi  insertion.
3373              The mode strings are user-settable (e.g., emacs-mode-string).
3374       skip-completed-text (Off)
3375              If  set  to On, this alters the default completion behavior when
3376              inserting a single match into the line.  It's only  active  when
3377              performing  completion  in  the  middle  of a word.  If enabled,
3378              readline does not insert characters  from  the  completion  that
3379              match  characters  after  point  in the word being completed, so
3380              portions of the word following the cursor are not duplicated.
3381       vi-cmd-mode-string ((cmd))
3382              If the show-mode-in-prompt variable is enabled, this  string  is
3383              displayed immediately before the last line of the primary prompt
3384              when vi editing mode is active and in command mode.   The  value
3385              is expanded like a key binding, so the standard set of meta- and
3386              control prefixes and backslash escape  sequences  is  available.
3387              Use  the  \1  and  \2 escapes to begin and end sequences of non-
3388              printing characters, which can be used to embed a terminal  con‐
3389              trol sequence into the mode string.
3390       vi-ins-mode-string ((ins))
3391              If  the  show-mode-in-prompt variable is enabled, this string is
3392              displayed immediately before the last line of the primary prompt
3393              when vi editing mode is active and in insertion mode.  The value
3394              is expanded like a key binding, so the standard set of meta- and
3395              control  prefixes  and  backslash escape sequences is available.
3396              Use the \1 and \2 escapes to begin and  end  sequences  of  non-
3397              printing  characters, which can be used to embed a terminal con‐
3398              trol sequence into the mode string.
3399       visible-stats (Off)
3400              If set to On, a character denoting a file's type as reported  by
3401              stat(2)  is  appended to the filename when listing possible com‐
3402              pletions.
3403
3404   Readline Conditional Constructs
3405       Readline implements a facility similar in  spirit  to  the  conditional
3406       compilation  features  of  the C preprocessor which allows key bindings
3407       and variable settings to be performed as the result  of  tests.   There
3408       are four parser directives used.
3409
3410       $if    The  $if construct allows bindings to be made based on the edit‐
3411              ing mode, the terminal being  used,  or  the  application  using
3412              readline.  The text of the test, after any comparison operator,
3413               extends  to  the  end  of  the line; unless otherwise noted, no
3414              characters are required to isolate it.
3415
3416              mode   The mode= form of the  $if  directive  is  used  to  test
3417                     whether  readline  is  in  emacs or vi mode.  This may be
3418                     used in conjunction with the set keymap command, for  in‐
3419                     stance,   to  set  bindings  in  the  emacs-standard  and
3420                     emacs-ctlx keymaps only if readline is  starting  out  in
3421                     emacs mode.
3422
3423              term   The  term=  form may be used to include terminal-specific
3424                     key bindings, perhaps to bind the key sequences output by
3425                     the terminal's function keys.  The word on the right side
3426                     of the = is tested against both the full name of the ter‐
3427                     minal  and  the  portion  of the terminal name before the
3428                     first -.  This allows sun to match both sun and  sun-cmd,
3429                     for instance.
3430
3431              version
3432                     The  version  test  may  be  used  to perform comparisons
3433                     against specific readline versions.  The version  expands
3434                     to  the  current readline version.  The set of comparison
3435                     operators includes =, (and ==), !=, <=,  >=,  <,  and  >.
3436                     The  version number supplied on the right side of the op‐
3437                     erator consists of a major version  number,  an  optional
3438                     decimal point, and an optional minor version (e.g., 7.1).
3439                     If the minor version is omitted, it is assumed to  be  0.
3440                     The operator may be separated from the string version and
3441                     from the version number argument by whitespace.
3442
3443              application
3444                     The application construct is used to include application-
3445                     specific  settings.   Each program using the readline li‐
3446                     brary sets the application name,  and  an  initialization
3447                     file can test for a particular value.  This could be used
3448                     to bind key sequences to functions useful for a  specific
3449                     program.   For instance, the following command adds a key
3450                     sequence that quotes the  current  or  previous  word  in
3451                     bash:
3452
3453                     $if Bash
3454                     # Quote the current or previous word
3455                     "\C-xq": "\eb\"\ef\""
3456                     $endif
3457
3458              variable
3459                     The variable construct provides simple equality tests for
3460                     readline variables and values.  The permitted  comparison
3461                     operators  are  =, ==, and !=.  The variable name must be
3462                     separated from the comparison operator by whitespace; the
3463                     operator  may  be  separated  from the value on the right
3464                     hand side by whitespace.  Both string and  boolean  vari‐
3465                     ables  may  be  tested.  Boolean variables must be tested
3466                     against the values on and off.
3467
3468       $endif This command, as seen in the previous example, terminates an $if
3469              command.
3470
3471       $else  Commands in this branch of the $if directive are executed if the
3472              test fails.
3473
3474       $include
3475              This directive takes a single filename as an argument and  reads
3476              commands  and bindings from that file.  For example, the follow‐
3477              ing directive would read /etc/inputrc:
3478
3479              $include  /etc/inputrc
3480
3481   Searching
3482       Readline provides commands for searching through  the  command  history
3483       (see HISTORY below) for lines containing a specified string.  There are
3484       two search modes: incremental and non-incremental.
3485
3486       Incremental searches begin before the  user  has  finished  typing  the
3487       search  string.  As each character of the search string is typed, read‐
3488       line displays the next entry from the history matching the string typed
3489       so  far.   An  incremental  search  requires only as many characters as
3490       needed to find the desired history entry.  The  characters  present  in
3491       the  value of the isearch-terminators variable are used to terminate an
3492       incremental search.  If that variable has not been assigned a value the
3493       Escape  and  Control-J characters will terminate an incremental search.
3494       Control-G will abort an incremental search  and  restore  the  original
3495       line.   When the search is terminated, the history entry containing the
3496       search string becomes the current line.
3497
3498       To find other matching entries in the history list, type  Control-S  or
3499       Control-R  as appropriate.  This will search backward or forward in the
3500       history for the next entry matching the search  string  typed  so  far.
3501       Any  other  key sequence bound to a readline command will terminate the
3502       search and execute that command.  For instance, a newline  will  termi‐
3503       nate the search and accept the line, thereby executing the command from
3504       the history list.
3505
3506       Readline remembers the last incremental search string.  If two Control-
3507       Rs  are  typed without any intervening characters defining a new search
3508       string, any remembered search string is used.
3509
3510       Non-incremental searches read the entire search string before  starting
3511       to  search  for matching history lines.  The search string may be typed
3512       by the user or be part of the contents of the current line.
3513
3514   Readline Command Names
3515       The following is a list of the names of the commands  and  the  default
3516       key sequences to which they are bound.  Command names without an accom‐
3517       panying key sequence are unbound by default.  In the following descrip‐
3518       tions,  point refers to the current cursor position, and mark refers to
3519       a cursor position saved by the set-mark command.  The text between  the
3520       point and mark is referred to as the region.
3521
3522   Commands for Moving
3523       beginning-of-line (C-a)
3524              Move to the start of the current line.
3525       end-of-line (C-e)
3526              Move to the end of the line.
3527       forward-char (C-f)
3528              Move forward a character.
3529       backward-char (C-b)
3530              Move back a character.
3531       forward-word (M-f)
3532              Move forward to the end of the next word.  Words are composed of
3533              alphanumeric characters (letters and digits).
3534       backward-word (M-b)
3535              Move back to the start of the current or previous  word.   Words
3536              are composed of alphanumeric characters (letters and digits).
3537       shell-forward-word
3538              Move  forward  to the end of the next word.  Words are delimited
3539              by non-quoted shell metacharacters.
3540       shell-backward-word
3541              Move back to the start of the current or previous  word.   Words
3542              are delimited by non-quoted shell metacharacters.
3543       previous-screen-line
3544              Attempt  to move point to the same physical screen column on the
3545              previous physical screen line. This will not  have  the  desired
3546              effect  if  the current Readline line does not take up more than
3547              one physical line or if point is not greater than the length  of
3548              the prompt plus the screen width.
3549       next-screen-line
3550              Attempt  to move point to the same physical screen column on the
3551              next physical screen line. This will not have the desired effect
3552              if  the  current  Readline  line  does not take up more than one
3553              physical line or if the length of the current Readline  line  is
3554              not greater than the length of the prompt plus the screen width.
3555       clear-display (M-C-l)
3556              Clear  the  screen  and,  if possible, the terminal's scrollback
3557              buffer, then redraw the current line, leaving the  current  line
3558              at the top of the screen.
3559       clear-screen (C-l)
3560              Clear the screen, then redraw the current line, leaving the cur‐
3561              rent line at the top of the screen.  With an  argument,  refresh
3562              the current line without clearing the screen.
3563       redraw-current-line
3564              Refresh the current line.
3565
3566   Commands for Manipulating the History
3567       accept-line (Newline, Return)
3568              Accept the line regardless of where the cursor is.  If this line
3569              is non-empty, add it to the history list according to the  state
3570              of  the HISTCONTROL variable.  If the line is a modified history
3571              line, then restore the history line to its original state.
3572       previous-history (C-p)
3573              Fetch the previous command from the history list, moving back in
3574              the list.
3575       next-history (C-n)
3576              Fetch  the next command from the history list, moving forward in
3577              the list.
3578       beginning-of-history (M-<)
3579              Move to the first line in the history.
3580       end-of-history (M->)
3581              Move to the end of the input history, i.e., the  line  currently
3582              being entered.
3583       reverse-search-history (C-r)
3584              Search  backward  starting  at  the current line and moving `up'
3585              through the  history  as  necessary.   This  is  an  incremental
3586              search.
3587       forward-search-history (C-s)
3588              Search  forward  starting  at the current line and moving `down'
3589              through the  history  as  necessary.   This  is  an  incremental
3590              search.
3591       non-incremental-reverse-search-history (M-p)
3592              Search backward through the history starting at the current line
3593              using a non-incremental search for  a  string  supplied  by  the
3594              user.
3595       non-incremental-forward-search-history (M-n)
3596              Search  forward  through  the  history  using  a non-incremental
3597              search for a string supplied by the user.
3598       history-search-forward
3599              Search forward through the history for the string of  characters
3600              between  the start of the current line and the point.  This is a
3601              non-incremental search.
3602       history-search-backward
3603              Search backward through the history for the string of characters
3604              between  the start of the current line and the point.  This is a
3605              non-incremental search.
3606       history-substring-search-backward
3607              Search backward through the history for the string of characters
3608              between the start of the current line and the current cursor po‐
3609              sition (the point).  The search string may match anywhere  in  a
3610              history line.  This is a non-incremental search.
3611       history-substring-search-forward
3612              Search  forward through the history for the string of characters
3613              between the start of the current line and the point.  The search
3614              string  may match anywhere in a history line.  This is a non-in‐
3615              cremental search.
3616       yank-nth-arg (M-C-y)
3617              Insert the first argument to the previous command  (usually  the
3618              second word on the previous line) at point.  With an argument n,
3619              insert the nth word from the previous command (the words in  the
3620              previous  command  begin  with word 0).  A negative argument in‐
3621              serts the nth word from the end of the previous  command.   Once
3622              the  argument n is computed, the argument is extracted as if the
3623              "!n" history expansion had been specified.
3624       yank-last-arg (M-., M-_)
3625              Insert the last argument to the previous command (the last  word
3626              of the previous history entry).  With a numeric argument, behave
3627              exactly like yank-nth-arg.  Successive  calls  to  yank-last-arg
3628              move  back through the history list, inserting the last word (or
3629              the word specified by the argument to the first  call)  of  each
3630              line in turn.  Any numeric argument supplied to these successive
3631              calls determines the direction to move through the  history.   A
3632              negative  argument  switches  the  direction through the history
3633              (back or forward).  The history expansion facilities are used to
3634              extract the last word, as if the "!$" history expansion had been
3635              specified.
3636       shell-expand-line (M-C-e)
3637              Expand the line as the shell does.  This performs alias and his‐
3638              tory expansion as well as all of the shell word expansions.  See
3639              HISTORY EXPANSION below for a description of history expansion.
3640       history-expand-line (M-^)
3641              Perform history expansion on the current line.  See HISTORY  EX‐
3642              PANSION below for a description of history expansion.
3643       magic-space
3644              Perform  history  expansion  on  the  current  line and insert a
3645              space.  See HISTORY EXPANSION below for a description of history
3646              expansion.
3647       alias-expand-line
3648              Perform  alias expansion on the current line.  See ALIASES above
3649              for a description of alias expansion.
3650       history-and-alias-expand-line
3651              Perform history and alias expansion on the current line.
3652       insert-last-argument (M-., M-_)
3653              A synonym for yank-last-arg.
3654       operate-and-get-next (C-o)
3655              Accept the current line for execution and fetch  the  next  line
3656              relative  to  the  current line from the history for editing.  A
3657              numeric argument, if supplied, specifies the  history  entry  to
3658              use instead of the current line.
3659       edit-and-execute-command (C-x C-e)
3660              Invoke  an  editor  on the current command line, and execute the
3661              result as shell commands.  Bash attempts to invoke $VISUAL, $ED‐
3662              ITOR, and emacs as the editor, in that order.
3663
3664   Commands for Changing Text
3665       end-of-file (usually C-d)
3666              The  character  indicating  end-of-file  as set, for example, by
3667              ``stty''.  If this character is read when there are  no  charac‐
3668              ters  on  the  line,  and point is at the beginning of the line,
3669              Readline interprets it as the end of input and returns EOF.
3670       delete-char (C-d)
3671              Delete the character at point.  If this function is bound to the
3672              same character as the tty EOF character, as C-d commonly is, see
3673              above for the effects.
3674       backward-delete-char (Rubout)
3675              Delete the character behind the cursor.  When  given  a  numeric
3676              argument, save the deleted text on the kill ring.
3677       forward-backward-delete-char
3678              Delete  the  character under the cursor, unless the cursor is at
3679              the end of the line, in which case the character behind the cur‐
3680              sor is deleted.
3681       quoted-insert (C-q, C-v)
3682              Add  the next character typed to the line verbatim.  This is how
3683              to insert characters like C-q, for example.
3684       tab-insert (C-v TAB)
3685              Insert a tab character.
3686       self-insert (a, b, A, 1, !, ...)
3687              Insert the character typed.
3688       transpose-chars (C-t)
3689              Drag the character before point forward over  the  character  at
3690              point,  moving point forward as well.  If point is at the end of
3691              the line, then this transposes the two characters before  point.
3692              Negative arguments have no effect.
3693       transpose-words (M-t)
3694              Drag  the  word  before  point past the word after point, moving
3695              point over that word as well.  If point is at  the  end  of  the
3696              line, this transposes the last two words on the line.
3697       upcase-word (M-u)
3698              Uppercase  the current (or following) word.  With a negative ar‐
3699              gument, uppercase the previous word, but do not move point.
3700       downcase-word (M-l)
3701              Lowercase the current (or following) word.  With a negative  ar‐
3702              gument, lowercase the previous word, but do not move point.
3703       capitalize-word (M-c)
3704              Capitalize the current (or following) word.  With a negative ar‐
3705              gument, capitalize the previous word, but do not move point.
3706       overwrite-mode
3707              Toggle overwrite mode.  With an explicit positive numeric  argu‐
3708              ment, switches to overwrite mode.  With an explicit non-positive
3709              numeric argument, switches to insert mode.  This command affects
3710              only  emacs mode; vi mode does overwrite differently.  Each call
3711              to readline() starts in insert mode.  In overwrite mode, charac‐
3712              ters  bound to self-insert replace the text at point rather than
3713              pushing the text  to  the  right.   Characters  bound  to  back‐
3714              ward-delete-char  replace  the  character  before  point  with a
3715              space.  By default, this command is unbound.
3716
3717   Killing and Yanking
3718       kill-line (C-k)
3719              Kill the text from point to the end of the line.
3720       backward-kill-line (C-x Rubout)
3721              Kill backward to the beginning of the line.
3722       unix-line-discard (C-u)
3723              Kill backward from point to the  beginning  of  the  line.   The
3724              killed text is saved on the kill-ring.
3725       kill-whole-line
3726              Kill  all  characters on the current line, no matter where point
3727              is.
3728       kill-word (M-d)
3729              Kill from point to the end of the current word,  or  if  between
3730              words,  to  the  end  of the next word.  Word boundaries are the
3731              same as those used by forward-word.
3732       backward-kill-word (M-Rubout)
3733              Kill the word behind point.  Word boundaries  are  the  same  as
3734              those used by backward-word.
3735       shell-kill-word
3736              Kill  from  point  to the end of the current word, or if between
3737              words, to the end of the next word.   Word  boundaries  are  the
3738              same as those used by shell-forward-word.
3739       shell-backward-kill-word
3740              Kill  the  word  behind  point.  Word boundaries are the same as
3741              those used by shell-backward-word.
3742       unix-word-rubout (C-w)
3743              Kill the word behind point, using white space as a  word  bound‐
3744              ary.  The killed text is saved on the kill-ring.
3745       unix-filename-rubout
3746              Kill  the  word  behind  point,  using white space and the slash
3747              character as the word boundaries.  The killed text is  saved  on
3748              the kill-ring.
3749       delete-horizontal-space (M-\)
3750              Delete all spaces and tabs around point.
3751       kill-region
3752              Kill the text in the current region.
3753       copy-region-as-kill
3754              Copy the text in the region to the kill buffer.
3755       copy-backward-word
3756              Copy  the word before point to the kill buffer.  The word bound‐
3757              aries are the same as backward-word.
3758       copy-forward-word
3759              Copy the word following point to  the  kill  buffer.   The  word
3760              boundaries are the same as forward-word.
3761       yank (C-y)
3762              Yank the top of the kill ring into the buffer at point.
3763       yank-pop (M-y)
3764              Rotate  the kill ring, and yank the new top.  Only works follow‐
3765              ing yank or yank-pop.
3766
3767   Numeric Arguments
3768       digit-argument (M-0, M-1, ..., M--)
3769              Add this digit to the argument already accumulating, or start  a
3770              new argument.  M-- starts a negative argument.
3771       universal-argument
3772              This  is another way to specify an argument.  If this command is
3773              followed by one or more digits, optionally with a leading  minus
3774              sign,  those digits define the argument.  If the command is fol‐
3775              lowed by digits, executing universal-argument again ends the nu‐
3776              meric argument, but is otherwise ignored.  As a special case, if
3777              this command is immediately followed by a character that is nei‐
3778              ther  a  digit  nor  minus sign, the argument count for the next
3779              command is multiplied by four.  The argument count is  initially
3780              one,  so  executing this function the first time makes the argu‐
3781              ment count four, a second time makes the argument count sixteen,
3782              and so on.
3783
3784   Completing
3785       complete (TAB)
3786              Attempt  to  perform  completion on the text before point.  Bash
3787              attempts completion treating the text as a variable (if the text
3788              begins  with  $), username (if the text begins with ~), hostname
3789              (if the text begins with @), or command (including  aliases  and
3790              functions) in turn.  If none of these produces a match, filename
3791              completion is attempted.
3792       possible-completions (M-?)
3793              List the possible completions of the text before point.
3794       insert-completions (M-*)
3795              Insert all completions of the text before point that would  have
3796              been generated by possible-completions.
3797       menu-complete
3798              Similar  to complete, but replaces the word to be completed with
3799              a single match from the list of possible completions.   Repeated
3800              execution  of  menu-complete  steps through the list of possible
3801              completions, inserting each match in turn.  At the  end  of  the
3802              list of completions, the bell is rung (subject to the setting of
3803              bell-style) and the original text is restored.  An argument of n
3804              moves n positions forward in the list of matches; a negative ar‐
3805              gument may be used to move backward through the list.  This com‐
3806              mand is intended to be bound to TAB, but is unbound by default.
3807       menu-complete-backward
3808              Identical  to menu-complete, but moves backward through the list
3809              of possible completions, as if menu-complete had  been  given  a
3810              negative argument.  This command is unbound by default.
3811       delete-char-or-list
3812              Deletes  the  character under the cursor if not at the beginning
3813              or end of the line (like delete-char).  If at  the  end  of  the
3814              line, behaves identically to possible-completions.  This command
3815              is unbound by default.
3816       complete-filename (M-/)
3817              Attempt filename completion on the text before point.
3818       possible-filename-completions (C-x /)
3819              List the possible completions of the text before point, treating
3820              it as a filename.
3821       complete-username (M-~)
3822              Attempt  completion  on  the text before point, treating it as a
3823              username.
3824       possible-username-completions (C-x ~)
3825              List the possible completions of the text before point, treating
3826              it as a username.
3827       complete-variable (M-$)
3828              Attempt  completion  on  the text before point, treating it as a
3829              shell variable.
3830       possible-variable-completions (C-x $)
3831              List the possible completions of the text before point, treating
3832              it as a shell variable.
3833       complete-hostname (M-@)
3834              Attempt  completion  on  the text before point, treating it as a
3835              hostname.
3836       possible-hostname-completions (C-x @)
3837              List the possible completions of the text before point, treating
3838              it as a hostname.
3839       complete-command (M-!)
3840              Attempt  completion  on  the text before point, treating it as a
3841              command name.  Command completion attempts  to  match  the  text
3842              against   aliases,   reserved   words,  shell  functions,  shell
3843              builtins, and finally executable filenames, in that order.
3844       possible-command-completions (C-x !)
3845              List the possible completions of the text before point, treating
3846              it as a command name.
3847       dynamic-complete-history (M-TAB)
3848              Attempt  completion on the text before point, comparing the text
3849              against lines from the  history  list  for  possible  completion
3850              matches.
3851       dabbrev-expand
3852              Attempt  menu completion on the text before point, comparing the
3853              text against lines from the history list for possible completion
3854              matches.
3855       complete-into-braces (M-{)
3856              Perform filename completion and insert the list of possible com‐
3857              pletions enclosed within braces so the list is available to  the
3858              shell (see Brace Expansion above).
3859
3860   Keyboard Macros
3861       start-kbd-macro (C-x ()
3862              Begin  saving  the  characters  typed  into the current keyboard
3863              macro.
3864       end-kbd-macro (C-x ))
3865              Stop saving the characters typed into the current keyboard macro
3866              and store the definition.
3867       call-last-kbd-macro (C-x e)
3868              Re-execute  the last keyboard macro defined, by making the char‐
3869              acters in the macro appear as if typed at the keyboard.
3870       print-last-kbd-macro ()
3871              Print the last keyboard macro defined in a format  suitable  for
3872              the inputrc file.
3873
3874   Miscellaneous
3875       re-read-init-file (C-x C-r)
3876              Read  in  the  contents of the inputrc file, and incorporate any
3877              bindings or variable assignments found there.
3878       abort (C-g)
3879              Abort the current editing command and ring the  terminal's  bell
3880              (subject to the setting of bell-style).
3881       do-lowercase-version (M-A, M-B, M-x, ...)
3882              If  the  metafied character x is uppercase, run the command that
3883              is bound to the corresponding metafied lowercase character.  The
3884              behavior is undefined if x is already lowercase.
3885       prefix-meta (ESC)
3886              Metafy the next character typed.  ESC f is equivalent to Meta-f.
3887       undo (C-_, C-x C-u)
3888              Incremental undo, separately remembered for each line.
3889       revert-line (M-r)
3890              Undo  all changes made to this line.  This is like executing the
3891              undo command enough times to return  the  line  to  its  initial
3892              state.
3893       tilde-expand (M-&)
3894              Perform tilde expansion on the current word.
3895       set-mark (C-@, M-<space>)
3896              Set  the  mark to the point.  If a numeric argument is supplied,
3897              the mark is set to that position.
3898       exchange-point-and-mark (C-x C-x)
3899              Swap the point with the mark.  The current  cursor  position  is
3900              set  to the saved position, and the old cursor position is saved
3901              as the mark.
3902       character-search (C-])
3903              A character is read and point is moved to the next occurrence of
3904              that  character.   A negative count searches for previous occur‐
3905              rences.
3906       character-search-backward (M-C-])
3907              A character is read and point is moved to  the  previous  occur‐
3908              rence  of  that character.  A negative count searches for subse‐
3909              quent occurrences.
3910       skip-csi-sequence
3911              Read enough characters to consume a multi-key sequence  such  as
3912              those  defined for keys like Home and End.  Such sequences begin
3913              with a Control Sequence Indicator (CSI), usually ESC-[.  If this
3914              sequence  is  bound  to "\[", keys producing such sequences will
3915              have no effect unless explicitly bound to  a  readline  command,
3916              instead  of  inserting stray characters into the editing buffer.
3917              This is unbound by default, but usually bound to ESC-[.
3918       insert-comment (M-#)
3919              Without a numeric argument,  the  value  of  the  readline  com‐
3920              ment-begin  variable is inserted at the beginning of the current
3921              line.  If a numeric argument is supplied, this command acts as a
3922              toggle:  if  the  characters at the beginning of the line do not
3923              match the value of comment-begin, the value is inserted,  other‐
3924              wise the characters in comment-begin are deleted from the begin‐
3925              ning of the line.  In either case, the line is accepted as if  a
3926              newline  had  been  typed.   The  default value of comment-begin
3927              causes this command to make the current line  a  shell  comment.
3928              If  a  numeric  argument  causes the comment character to be re‐
3929              moved, the line will be executed by the shell.
3930       glob-complete-word (M-g)
3931              The word before point is treated as a pattern for  pathname  ex‐
3932              pansion,  with an asterisk implicitly appended.  This pattern is
3933              used to generate a list of matching filenames for possible  com‐
3934              pletions.
3935       glob-expand-word (C-x *)
3936              The  word  before point is treated as a pattern for pathname ex‐
3937              pansion, and the list of matching filenames is inserted, replac‐
3938              ing the word.  If a numeric argument is supplied, an asterisk is
3939              appended before pathname expansion.
3940       glob-list-expansions (C-x g)
3941              The list  of  expansions  that  would  have  been  generated  by
3942              glob-expand-word  is  displayed,  and the line is redrawn.  If a
3943              numeric argument is supplied, an  asterisk  is  appended  before
3944              pathname expansion.
3945       dump-functions
3946              Print  all  of the functions and their key bindings to the read‐
3947              line output stream.  If a numeric argument is supplied, the out‐
3948              put  is  formatted  in such a way that it can be made part of an
3949              inputrc file.
3950       dump-variables
3951              Print all of the settable readline variables and their values to
3952              the  readline output stream.  If a numeric argument is supplied,
3953              the output is formatted in such a way that it can be  made  part
3954              of an inputrc file.
3955       dump-macros
3956              Print  all of the readline key sequences bound to macros and the
3957              strings they output.  If a numeric  argument  is  supplied,  the
3958              output is formatted in such a way that it can be made part of an
3959              inputrc file.
3960       display-shell-version (C-x C-v)
3961              Display version information about the current instance of bash.
3962
3963   Programmable Completion
3964       When word completion is attempted for an  argument  to  a  command  for
3965       which  a  completion  specification (a compspec) has been defined using
3966       the complete builtin (see SHELL BUILTIN COMMANDS below),  the  program‐
3967       mable completion facilities are invoked.
3968
3969       First,  the  command  name  is  identified.  If the command word is the
3970       empty string (completion attempted at the beginning of an empty  line),
3971       any  compspec  defined  with  the  -E option to complete is used.  If a
3972       compspec has been defined for that command, the  compspec  is  used  to
3973       generate the list of possible completions for the word.  If the command
3974       word is a full pathname, a compspec for the full pathname  is  searched
3975       for  first.   If no compspec is found for the full pathname, an attempt
3976       is made to find a compspec for the portion following the  final  slash.
3977       If  those  searches  do  not result in a compspec, any compspec defined
3978       with the -D option to complete is used as the default.  If there is  no
3979       default  compspec, bash attempts alias expansion on the command word as
3980       a final resort, and attempts to find a compspec for  the  command  word
3981       from any successful expansion.
3982
3983       Once  a  compspec  has  been  found, it is used to generate the list of
3984       matching words.  If a compspec is not found, the default  bash  comple‐
3985       tion as described above under Completing is performed.
3986
3987       First,  the  actions  specified by the compspec are used.  Only matches
3988       which are prefixed by the word being completed are returned.  When  the
3989       -f  or -d option is used for filename or directory name completion, the
3990       shell variable FIGNORE is used to filter the matches.
3991
3992       Any completions specified by a pathname expansion pattern to the -G op‐
3993       tion  are  generated next.  The words generated by the pattern need not
3994       match the word being completed.  The GLOBIGNORE shell variable  is  not
3995       used to filter the matches, but the FIGNORE variable is used.
3996
3997       Next,  the string specified as the argument to the -W option is consid‐
3998       ered.  The string is first split using the characters in the  IFS  spe‐
3999       cial  variable  as delimiters.  Shell quoting is honored.  Each word is
4000       then expanded using brace expansion,  tilde  expansion,  parameter  and
4001       variable  expansion, command substitution, and arithmetic expansion, as
4002       described above under EXPANSION.  The results are split using the rules
4003       described above under Word Splitting.  The results of the expansion are
4004       prefix-matched against the word being completed, and the matching words
4005       become the possible completions.
4006
4007       After  these matches have been generated, any shell function or command
4008       specified with the -F and -C options is invoked.  When the  command  or
4009       function is invoked, the COMP_LINE, COMP_POINT, COMP_KEY, and COMP_TYPE
4010       variables are assigned values as described above under Shell Variables.
4011       If  a  shell  function  is being invoked, the COMP_WORDS and COMP_CWORD
4012       variables are also set.  When the function or command is  invoked,  the
4013       first  argument ($1) is the name of the command whose arguments are be‐
4014       ing completed, the second argument ($2) is the  word  being  completed,
4015       and  the  third argument ($3) is the word preceding the word being com‐
4016       pleted on the current command line.  No filtering of the generated com‐
4017       pletions against the word being completed is performed; the function or
4018       command has complete freedom in generating the matches.
4019
4020       Any function specified with -F is invoked first.  The function may  use
4021       any  of  the  shell facilities, including the compgen builtin described
4022       below, to generate the matches.  It must put the  possible  completions
4023       in the COMPREPLY array variable, one per array element.
4024
4025       Next,  any  command specified with the -C option is invoked in an envi‐
4026       ronment equivalent to command substitution.  It should print a list  of
4027       completions,  one  per  line, to the standard output.  Backslash may be
4028       used to escape a newline, if necessary.
4029
4030       After all of the possible completions are generated, any filter  speci‐
4031       fied  with  the -X option is applied to the list.  The filter is a pat‐
4032       tern as used for pathname expansion; a & in  the  pattern  is  replaced
4033       with  the text of the word being completed.  A literal & may be escaped
4034       with a backslash; the backslash is removed before attempting  a  match.
4035       Any  completion that matches the pattern will be removed from the list.
4036       A leading ! negates the pattern; in this case any completion not match‐
4037       ing  the  pattern  will be removed.  If the nocasematch shell option is
4038       enabled, the match is performed without regard to the  case  of  alpha‐
4039       betic characters.
4040
4041       Finally, any prefix and suffix specified with the -P and -S options are
4042       added to each member of the completion list, and the result is returned
4043       to the readline completion code as the list of possible completions.
4044
4045       If  the previously-applied actions do not generate any matches, and the
4046       -o dirnames option was supplied to complete when the compspec  was  de‐
4047       fined, directory name completion is attempted.
4048
4049       If  the  -o  plusdirs option was supplied to complete when the compspec
4050       was defined, directory name completion is attempted and any matches are
4051       added to the results of the other actions.
4052
4053       By  default,  if a compspec is found, whatever it generates is returned
4054       to the completion code as the full set of  possible  completions.   The
4055       default bash completions are not attempted, and the readline default of
4056       filename completion is disabled.  If the -o bashdefault option was sup‐
4057       plied  to complete when the compspec was defined, the bash default com‐
4058       pletions are attempted if the compspec generates no matches.  If the -o
4059       default  option was supplied to complete when the compspec was defined,
4060       readline's default completion will be performed if the  compspec  (and,
4061       if attempted, the default bash completions) generate no matches.
4062
4063       When  a  compspec  indicates that directory name completion is desired,
4064       the programmable completion functions force readline to append a  slash
4065       to  completed names which are symbolic links to directories, subject to
4066       the value of the mark-directories readline variable, regardless of  the
4067       setting of the mark-symlinked-directories readline variable.
4068
4069       There  is  some support for dynamically modifying completions.  This is
4070       most useful when used in combination with a default  completion  speci‐
4071       fied  with  complete -D.  It's possible for shell functions executed as
4072       completion handlers to indicate that completion should  be  retried  by
4073       returning  an exit status of 124.  If a shell function returns 124, and
4074       changes the compspec associated with the command on which completion is
4075       being  attempted  (supplied  as the first argument when the function is
4076       executed), programmable completion restarts from the beginning, with an
4077       attempt  to find a new compspec for that command.  This allows a set of
4078       completions to be built dynamically as completion is attempted,  rather
4079       than being loaded all at once.
4080
4081       For  instance, assuming that there is a library of compspecs, each kept
4082       in a file corresponding to the name of the command, the  following  de‐
4083       fault completion function would load completions dynamically:
4084
4085       _completion_loader()
4086       {
4087            . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
4088       }
4089       complete -D -F _completion_loader -o bashdefault -o default
4090
4091

HISTORY

4093       When  the  -o  history  option to the set builtin is enabled, the shell
4094       provides access to the command history, the list of commands previously
4095       typed.   The  value  of  the HISTSIZE variable is used as the number of
4096       commands to save in a history list.  The text of the last HISTSIZE com‐
4097       mands  (default  500)  is  saved.  The shell stores each command in the
4098       history list prior to parameter and variable expansion  (see  EXPANSION
4099       above)  but after history expansion is performed, subject to the values
4100       of the shell variables HISTIGNORE and HISTCONTROL.
4101
4102       On startup, the history is initialized from the file named by the vari‐
4103       able  HISTFILE  (default ~/.bash_history).  The file named by the value
4104       of HISTFILE is truncated, if necessary, to contain  no  more  than  the
4105       number  of  lines specified by the value of HISTFILESIZE.  If HISTFILE‐
4106       SIZE is unset, or set to null, a non-numeric value, or a numeric  value
4107       less  than  zero,  the history file is not truncated.  When the history
4108       file is read, lines beginning with the history comment  character  fol‐
4109       lowed immediately by a digit are interpreted as timestamps for the fol‐
4110       lowing history line.  These timestamps are optionally displayed depend‐
4111       ing  on  the  value  of the HISTTIMEFORMAT variable.  When a shell with
4112       history enabled exits, the last $HISTSIZE lines  are  copied  from  the
4113       history  list  to $HISTFILE.  If the histappend shell option is enabled
4114       (see the description of shopt under SHELL BUILTIN COMMANDS below),  the
4115       lines  are  appended to the history file, otherwise the history file is
4116       overwritten.  If HISTFILE is unset, or  if  the  history  file  is  un‐
4117       writable,  the history is not saved.  If the HISTTIMEFORMAT variable is
4118       set, time stamps are written to the history file, marked with the  his‐
4119       tory comment character, so they may be preserved across shell sessions.
4120       This uses the history comment character to distinguish timestamps  from
4121       other  history  lines.   After  saving the history, the history file is
4122       truncated to contain no more than HISTFILESIZE lines.  If  HISTFILESIZE
4123       is  unset, or set to null, a non-numeric value, or a numeric value less
4124       than zero, the history file is not truncated.
4125
4126       The builtin command fc (see SHELL BUILTIN COMMANDS below) may  be  used
4127       to list or edit and re-execute a portion of the history list.  The his‐
4128       tory builtin may be used to display or modify the history list and  ma‐
4129       nipulate  the  history  file.   When using command-line editing, search
4130       commands are available in each editing mode that provide access to  the
4131       history list.
4132
4133       The  shell  allows control over which commands are saved on the history
4134       list.  The HISTCONTROL and HISTIGNORE variables may be set to cause the
4135       shell to save only a subset of the commands entered.  The cmdhist shell
4136       option, if enabled, causes the shell to attempt to save each line of  a
4137       multi-line  command  in the same history entry, adding semicolons where
4138       necessary to preserve syntactic correctness.  The lithist shell  option
4139       causes  the shell to save the command with embedded newlines instead of
4140       semicolons.  See the description of the shopt builtin below under SHELL
4141       BUILTIN  COMMANDS  for  information  on setting and unsetting shell op‐
4142       tions.
4143

HISTORY EXPANSION

4145       The shell supports a history expansion feature that is similar  to  the
4146       history  expansion in csh.  This section describes what syntax features
4147       are available.  This feature is  enabled  by  default  for  interactive
4148       shells, and can be disabled using the +H option to the set builtin com‐
4149       mand (see SHELL BUILTIN COMMANDS below).  Non-interactive shells do not
4150       perform history expansion by default.
4151
4152       History expansions introduce words from the history list into the input
4153       stream, making it easy to repeat commands, insert the  arguments  to  a
4154       previous command into the current input line, or fix errors in previous
4155       commands quickly.
4156
4157       History expansion is performed immediately after  a  complete  line  is
4158       read,  before  the shell breaks it into words, and is performed on each
4159       line individually without taking quoting on  previous  lines  into  ac‐
4160       count.   It  takes place in two parts.  The first is to determine which
4161       line from the history list to use during substitution.  The  second  is
4162       to  select  portions  of  that line for inclusion into the current one.
4163       The line selected from the history is the event, and  the  portions  of
4164       that  line that are acted upon are words.  Various modifiers are avail‐
4165       able to manipulate the selected words.  The line is broken  into  words
4166       in  the same fashion as when reading input, so that several metacharac‐
4167       ter-separated words surrounded by quotes are considered one word.  His‐
4168       tory  expansions are introduced by the appearance of the history expan‐
4169       sion character, which is ! by default.  Only backslash (\)  and  single
4170       quotes  can  quote the history expansion character, but the history ex‐
4171       pansion character is also treated as quoted if it immediately  precedes
4172       the closing double quote in a double-quoted string.
4173
4174       Several  characters inhibit history expansion if found immediately fol‐
4175       lowing the history expansion character, even if it is unquoted:  space,
4176       tab,  newline,  carriage return, and =.  If the extglob shell option is
4177       enabled, ( will also inhibit expansion.
4178
4179       Several shell options settable with the shopt builtin may  be  used  to
4180       tailor  the behavior of history expansion.  If the histverify shell op‐
4181       tion is enabled (see the description of the shopt builtin  below),  and
4182       readline  is  being  used,  history  substitutions  are not immediately
4183       passed to the shell parser.  Instead, the  expanded  line  is  reloaded
4184       into the readline editing buffer for further modification.  If readline
4185       is being used, and the histreedit shell option  is  enabled,  a  failed
4186       history  substitution will be reloaded into the readline editing buffer
4187       for correction.  The -p option to the history builtin  command  may  be
4188       used  to  see what a history expansion will do before using it.  The -s
4189       option to the history builtin may be used to add commands to the end of
4190       the  history  list  without  actually  executing them, so that they are
4191       available for subsequent recall.
4192
4193       The shell allows control of the various characters used by the  history
4194       expansion mechanism (see the description of histchars above under Shell
4195       Variables).  The shell uses the history comment character to mark  his‐
4196       tory timestamps when writing the history file.
4197
4198   Event Designators
4199       An  event designator is a reference to a command line entry in the his‐
4200       tory list.  Unless the reference is absolute, events  are  relative  to
4201       the current position in the history list.
4202
4203       !      Start  a  history substitution, except when followed by a blank,
4204              newline, carriage return, = or ( (when the extglob shell  option
4205              is enabled using the shopt builtin).
4206       !n     Refer to command line n.
4207       !-n    Refer to the current command minus n.
4208       !!     Refer to the previous command.  This is a synonym for `!-1'.
4209       !string
4210              Refer  to the most recent command preceding the current position
4211              in the history list starting with string.
4212       !?string[?]
4213              Refer to the most recent command preceding the current  position
4214              in  the  history  list containing string.  The trailing ? may be
4215              omitted if string is followed  immediately  by  a  newline.   If
4216              string  is  missing,  the  string from the most recent search is
4217              used; it is an error if there is no previous search string.
4218       ^string1^string2^
4219              Quick substitution.   Repeat  the  previous  command,  replacing
4220              string1  with  string2.  Equivalent to ``!!:s^string1^string2^''
4221              (see Modifiers below).
4222       !#     The entire command line typed so far.
4223
4224   Word Designators
4225       Word designators are used to select desired words from the event.  A  :
4226       separates  the event specification from the word designator.  It may be
4227       omitted if the word designator begins with a ^, $, *, -, or  %.   Words
4228       are  numbered from the beginning of the line, with the first word being
4229       denoted by 0 (zero).  Words are inserted into the  current  line  sepa‐
4230       rated by single spaces.
4231
4232       0 (zero)
4233              The zeroth word.  For the shell, this is the command word.
4234       n      The nth word.
4235       ^      The first argument.  That is, word 1.
4236       $      The  last word.  This is usually the last argument, but will ex‐
4237              pand to the zeroth word if there is only one word in the line.
4238       %      The first word matched by the most recent `?string?' search,  if
4239              the  search  string  begins  with  a character that is part of a
4240              word.
4241       x-y    A range of words; `-y' abbreviates `0-y'.
4242       *      All of the words but the zeroth.  This is a synonym  for  `1-$'.
4243              It  is  not  an  error to use * if there is just one word in the
4244              event; the empty string is returned in that case.
4245       x*     Abbreviates x-$.
4246       x-     Abbreviates x-$ like x*, but omits the last word.  If x is miss‐
4247              ing, it defaults to 0.
4248
4249       If  a  word  designator is supplied without an event specification, the
4250       previous command is used as the event.
4251
4252   Modifiers
4253       After the optional word designator, there may appear a sequence of  one
4254       or more of the following modifiers, each preceded by a `:'.  These mod‐
4255       ify, or edit, the word or words selected from the history event.
4256
4257       h      Remove a trailing filename component, leaving only the head.
4258       t      Remove all leading filename components, leaving the tail.
4259       r      Remove a trailing suffix of the form .xxx, leaving the basename.
4260       e      Remove all but the trailing suffix.
4261       p      Print the new command but do not execute it.
4262       q      Quote the substituted words, escaping further substitutions.
4263       x      Quote the substituted words as with q, but break into  words  at
4264              blanks  and newlines.  The q and x modifiers are mutually exclu‐
4265              sive; the last one supplied is used.
4266       s/old/new/
4267              Substitute new for the first occurrence  of  old  in  the  event
4268              line.  Any character may be used as the delimiter in place of /.
4269              The final delimiter is optional if it is the last  character  of
4270              the event line.  The delimiter may be quoted in old and new with
4271              a single backslash.  If & appears in new, it is replaced by old.
4272              A  single backslash will quote the &.  If old is null, it is set
4273              to the last old substituted, or, if no previous history  substi‐
4274              tutions  took  place,  the last string in a !?string[?]  search.
4275              If new is null, each matching old is deleted.
4276       &      Repeat the previous substitution.
4277       g      Cause changes to be applied over the entire event line.  This is
4278              used  in  conjunction  with `:s' (e.g., `:gs/old/new/') or `:&'.
4279              If used with `:s', any delimiter can be used in place of /,  and
4280              the  final  delimiter is optional if it is the last character of
4281              the event line.  An a may be used as a synonym for g.
4282       G      Apply the following `s' or `&' modifier once to each word in the
4283              event line.
4284

SHELL BUILTIN COMMANDS

4286       Unless otherwise noted, each builtin command documented in this section
4287       as accepting options preceded by - accepts -- to signify the end of the
4288       options.  The :, true, false, and test/[ builtins do not accept options
4289       and do not treat -- specially.  The exit, logout, return,  break,  con‐
4290       tinue,  let,  and shift builtins accept and process arguments beginning
4291       with - without requiring --.  Other builtins that accept arguments  but
4292       are  not  specified  as accepting options interpret arguments beginning
4293       with - as invalid options and require -- to  prevent  this  interpreta‐
4294       tion.
4295       : [arguments]
4296              No  effect;  the command does nothing beyond expanding arguments
4297              and performing any specified redirections.  The return status is
4298              zero.
4299
4300        .  filename [arguments]
4301       source filename [arguments]
4302              Read and execute commands from filename in the current shell en‐
4303              vironment and return the exit status of the  last  command  exe‐
4304              cuted  from  filename.   If  filename  does not contain a slash,
4305              filenames in PATH are used  to  find  the  directory  containing
4306              filename.  The file searched for in PATH need not be executable.
4307              When bash is  not  in  posix  mode,  the  current  directory  is
4308              searched  if no file is found in PATH.  If the sourcepath option
4309              to the shopt builtin command is turned  off,  the  PATH  is  not
4310              searched.   If any arguments are supplied, they become the posi‐
4311              tional parameters when filename is executed.  Otherwise the  po‐
4312              sitional parameters are unchanged.  If the -T option is enabled,
4313              source inherits any trap on DEBUG; if it is not, any DEBUG  trap
4314              string  is  saved  and  restored  around the call to source, and
4315              source unsets the DEBUG trap while it executes.  If  -T  is  not
4316              set,  and the sourced file changes the DEBUG trap, the new value
4317              is retained when source completes.  The  return  status  is  the
4318              status  of  the  last  command exited within the script (0 if no
4319              commands are executed), and false if filename is  not  found  or
4320              cannot be read.
4321
4322       alias [-p] [name[=value] ...]
4323              Alias with no arguments or with the -p option prints the list of
4324              aliases in the form alias name=value on standard  output.   When
4325              arguments  are supplied, an alias is defined for each name whose
4326              value is given.  A trailing space in value causes the next  word
4327              to be checked for alias substitution when the alias is expanded.
4328              For each name in the argument list for which no  value  is  sup‐
4329              plied,  the  name  and value of the alias is printed.  Alias re‐
4330              turns true unless a name is given for which no  alias  has  been
4331              defined.
4332
4333       bg [jobspec ...]
4334              Resume  each  suspended  job jobspec in the background, as if it
4335              had been started with &.  If jobspec is not present, the shell's
4336              notion  of the current job is used.  bg jobspec returns 0 unless
4337              run when job control is disabled or, when run with  job  control
4338              enabled,  any  specified  jobspec  was  not found or was started
4339              without job control.
4340
4341       bind [-m keymap] [-lpsvPSVX]
4342       bind [-m keymap] [-q function] [-u function] [-r keyseq]
4343       bind [-m keymap] -f filename
4344       bind [-m keymap] -x keyseq:shell-command
4345       bind [-m keymap] keyseq:function-name
4346       bind [-m keymap] keyseq:readline-command
4347              Display current readline key and function bindings, bind  a  key
4348              sequence  to  a  readline  function  or macro, or set a readline
4349              variable.  Each non-option argument is a command as it would ap‐
4350              pear  in .inputrc, but each binding or command must be passed as
4351              a separate argument; e.g., '"\C-x\C-r": re-read-init-file'.  Op‐
4352              tions, if supplied, have the following meanings:
4353              -m keymap
4354                     Use keymap as the keymap to be affected by the subsequent
4355                     bindings.  Acceptable keymap names are emacs, emacs-stan‐
4356                     dard,  emacs-meta,  emacs-ctlx,  vi, vi-move, vi-command,
4357                     and vi-insert.  vi is equivalent to  vi-command  (vi-move
4358                     is  also  a  synonym); emacs is equivalent to emacs-stan‐
4359                     dard.
4360              -l     List the names of all readline functions.
4361              -p     Display readline function names and bindings  in  such  a
4362                     way that they can be re-read.
4363              -P     List current readline function names and bindings.
4364              -s     Display  readline  key  sequences bound to macros and the
4365                     strings they output in such a way that they  can  be  re-
4366                     read.
4367              -S     Display  readline  key  sequences bound to macros and the
4368                     strings they output.
4369              -v     Display readline variable names and values in such a  way
4370                     that they can be re-read.
4371              -V     List current readline variable names and values.
4372              -f filename
4373                     Read key bindings from filename.
4374              -q function
4375                     Query about which keys invoke the named function.
4376              -u function
4377                     Unbind all keys bound to the named function.
4378              -r keyseq
4379                     Remove any current binding for keyseq.
4380              -x keyseq:shell-command
4381                     Cause shell-command to be executed whenever keyseq is en‐
4382                     tered.  When shell-command is executed,  the  shell  sets
4383                     the  READLINE_LINE  variable to the contents of the read‐
4384                     line line buffer and the READLINE_POINT and READLINE_MARK
4385                     variables  to the current location of the insertion point
4386                     and the saved insertion point (the  mark),  respectively.
4387                     If the executed command changes the value of any of READ‐
4388                     LINE_LINE, READLINE_POINT, or  READLINE_MARK,  those  new
4389                     values will be reflected in the editing state.
4390              -X     List  all  key  sequences bound to shell commands and the
4391                     associated commands in a format that can be reused as in‐
4392                     put.
4393
4394              The  return value is 0 unless an unrecognized option is given or
4395              an error occurred.
4396
4397       break [n]
4398              Exit from within a for, while, until, or select loop.  If  n  is
4399              specified, break n levels.  n must be ≥ 1.  If n is greater than
4400              the number of enclosing loops, all enclosing loops  are  exited.
4401              The  return  value is 0 unless n is not greater than or equal to
4402              1.
4403
4404       builtin shell-builtin [arguments]
4405              Execute the specified shell builtin, passing it  arguments,  and
4406              return its exit status.  This is useful when defining a function
4407              whose name is the same as a shell builtin, retaining  the  func‐
4408              tionality of the builtin within the function.  The cd builtin is
4409              commonly redefined this way.  The  return  status  is  false  if
4410              shell-builtin is not a shell builtin command.
4411
4412       caller [expr]
4413              Returns the context of any active subroutine call (a shell func‐
4414              tion or a script executed with the . or source builtins).  With‐
4415              out expr, caller displays the line number and source filename of
4416              the current subroutine call.  If a non-negative integer is  sup‐
4417              plied as expr, caller displays the line number, subroutine name,
4418              and source file corresponding to that position  in  the  current
4419              execution  call  stack.  This extra information may be used, for
4420              example, to print a stack trace.  The current frame is frame  0.
4421              The  return  value is 0 unless the shell is not executing a sub‐
4422              routine call or expr does not correspond to a valid position  in
4423              the call stack.
4424
4425       cd [-L|[-P [-e]] [-@]] [dir]
4426              Change  the  current  directory to dir.  if dir is not supplied,
4427              the value of the HOME shell variable is the default.  Any  addi‐
4428              tional arguments following dir are ignored.  The variable CDPATH
4429              defines the search path for the directory containing  dir:  each
4430              directory  name  in CDPATH is searched for dir.  Alternative di‐
4431              rectory names in CDPATH are separated by a colon  (:).   A  null
4432              directory  name  in CDPATH is the same as the current directory,
4433              i.e., ``.''.  If dir begins with a slash (/), then CDPATH is not
4434              used.   The  -P  option  causes cd to use the physical directory
4435              structure by resolving symbolic links while traversing  dir  and
4436              before processing instances of .. in dir (see also the -P option
4437              to the set builtin command); the -L option forces symbolic links
4438              to  be followed by resolving the link after processing instances
4439              of .. in dir.  If .. appears in dir, it is processed by removing
4440              the  immediately previous pathname component from dir, back to a
4441              slash or the beginning of dir.  If the  -e  option  is  supplied
4442              with  -P,  and  the current working directory cannot be success‐
4443              fully determined after a successful directory  change,  cd  will
4444              return  an unsuccessful status.  On systems that support it, the
4445              -@ option presents the extended  attributes  associated  with  a
4446              file  as  a directory.  An argument of - is converted to $OLDPWD
4447              before the directory change is attempted.  If a non-empty direc‐
4448              tory  name  from  CDPATH is used, or if - is the first argument,
4449              and the directory change is successful, the absolute pathname of
4450              the  new  working  directory  is written to the standard output.
4451              The return value is  true  if  the  directory  was  successfully
4452              changed; false otherwise.
4453
4454       command [-pVv] command [arg ...]
4455              Run  command  with  args  suppressing  the normal shell function
4456              lookup.  Only builtin commands or commands found in the PATH are
4457              executed.   If the -p option is given, the search for command is
4458              performed using a default value for PATH that is  guaranteed  to
4459              find  all of the standard utilities.  If either the -V or -v op‐
4460              tion is supplied, a description of command is printed.   The  -v
4461              option  causes  a single word indicating the command or filename
4462              used to invoke command to be displayed; the -V option produces a
4463              more  verbose  description.  If the -V or -v option is supplied,
4464              the exit status is 0 if command was found, and  1  if  not.   If
4465              neither option is supplied and an error occurred or command can‐
4466              not be found, the exit status is 127.  Otherwise, the exit  sta‐
4467              tus of the command builtin is the exit status of command.
4468
4469       compgen [option] [word]
4470              Generate  possible  completion matches for word according to the
4471              options, which may  be  any  option  accepted  by  the  complete
4472              builtin  with  the exception of -p and -r, and write the matches
4473              to the standard output.  When using the -F or  -C  options,  the
4474              various  shell  variables set by the programmable completion fa‐
4475              cilities, while available, will not have useful values.
4476
4477              The matches will be generated in the same way as if the program‐
4478              mable completion code had generated them directly from a comple‐
4479              tion specification with the same flags.  If word  is  specified,
4480              only those completions matching word will be displayed.
4481
4482              The  return  value is true unless an invalid option is supplied,
4483              or no matches were generated.
4484
4485       complete [-abcdefgjksuv] [-o comp-option] [-DEI] [-A action] [-G  glob‐
4486       pat] [-W wordlist]
4487              [-F  function]  [-C command] [-X filterpat] [-P prefix] [-S suf‐
4488              fix] name [name ...]
4489       complete -pr [-DEI] [name ...]
4490              Specify how arguments to each name should be completed.  If  the
4491              -p  option  is supplied, or if no options are supplied, existing
4492              completion specifications are printed in a way that allows  them
4493              to be reused as input.  The -r option removes a completion spec‐
4494              ification for each name, or, if no names are supplied, all  com‐
4495              pletion specifications.  The -D option indicates that other sup‐
4496              plied options and actions should apply to the  ``default''  com‐
4497              mand  completion; that is, completion attempted on a command for
4498              which no completion has previously been defined.  The -E  option
4499              indicates  that  other supplied options and actions should apply
4500              to ``empty'' command completion; that is,  completion  attempted
4501              on  a  blank  line.  The -I option indicates that other supplied
4502              options and actions should apply to completion  on  the  initial
4503              non-assignment  word  on  the line, or after a command delimiter
4504              such as ; or |, which is usually command  name  completion.   If
4505              multiple  options  are  supplied, the -D option takes precedence
4506              over -E, and both take precedence over -I.  If any of -D, -E, or
4507              -I  are  supplied,  any  other name arguments are ignored; these
4508              completions only apply to the case specified by the option.
4509
4510              The process of applying  these  completion  specifications  when
4511              word  completion  is attempted is described above under Program‐
4512              mable Completion.
4513
4514              Other options, if specified, have the following  meanings.   The
4515              arguments  to the -G, -W, and -X options (and, if necessary, the
4516              -P and -S options) should be quoted to protect them from  expan‐
4517              sion before the complete builtin is invoked.
4518              -o comp-option
4519                      The  comp-option  controls  several aspects of the comp‐
4520                      spec's behavior beyond the simple generation of  comple‐
4521                      tions.  comp-option may be one of:
4522                      bashdefault
4523                              Perform the rest of the default bash completions
4524                              if the compspec generates no matches.
4525                      default Use readline's default  filename  completion  if
4526                              the compspec generates no matches.
4527                      dirnames
4528                              Perform  directory  name completion if the comp‐
4529                              spec generates no matches.
4530                      filenames
4531                              Tell readline that the compspec generates  file‐
4532                              names,  so  it can perform any filename-specific
4533                              processing (like adding  a  slash  to  directory
4534                              names,  quoting special characters, or suppress‐
4535                              ing trailing spaces).  Intended to be used  with
4536                              shell functions.
4537                      noquote Tell  readline  not to quote the completed words
4538                              if they are filenames (quoting filenames is  the
4539                              default).
4540                      nosort  Tell  readline  not to sort the list of possible
4541                              completions alphabetically.
4542                      nospace Tell readline not to append  a  space  (the  de‐
4543                              fault)  to  words  completed  at  the end of the
4544                              line.
4545                      plusdirs
4546                              After any matches defined by  the  compspec  are
4547                              generated,  directory  name  completion  is  at‐
4548                              tempted and any matches are added to the results
4549                              of the other actions.
4550              -A action
4551                      The  action  may  be  one of the following to generate a
4552                      list of possible completions:
4553                      alias   Alias names.  May also be specified as -a.
4554                      arrayvar
4555                              Array variable names.
4556                      binding Readline key binding names.
4557                      builtin Names of shell builtin commands.   May  also  be
4558                              specified as -b.
4559                      command Command names.  May also be specified as -c.
4560                      directory
4561                              Directory names.  May also be specified as -d.
4562                      disabled
4563                              Names of disabled shell builtins.
4564                      enabled Names of enabled shell builtins.
4565                      export  Names  of exported shell variables.  May also be
4566                              specified as -e.
4567                      file    File names.  May also be specified as -f.
4568                      function
4569                              Names of shell functions.
4570                      group   Group names.  May also be specified as -g.
4571                      helptopic
4572                              Help topics as accepted by the help builtin.
4573                      hostname
4574                              Hostnames, as taken from the file  specified  by
4575                              the HOSTFILE shell variable.
4576                      job     Job  names,  if job control is active.  May also
4577                              be specified as -j.
4578                      keyword Shell reserved words.  May also be specified  as
4579                              -k.
4580                      running Names of running jobs, if job control is active.
4581                      service Service names.  May also be specified as -s.
4582                      setopt  Valid  arguments  for  the  -o option to the set
4583                              builtin.
4584                      shopt   Shell option names  as  accepted  by  the  shopt
4585                              builtin.
4586                      signal  Signal names.
4587                      stopped Names of stopped jobs, if job control is active.
4588                      user    User names.  May also be specified as -u.
4589                      variable
4590                              Names of all shell variables.  May also be spec‐
4591                              ified as -v.
4592              -C command
4593                      command is executed in a subshell environment,  and  its
4594                      output is used as the possible completions.
4595              -F function
4596                      The  shell  function function is executed in the current
4597                      shell environment.  When the function is  executed,  the
4598                      first argument ($1) is the name of the command whose ar‐
4599                      guments are being completed, the second argument ($2) is
4600                      the word being completed, and the third argument ($3) is
4601                      the word preceding the word being completed on the  cur‐
4602                      rent  command line.  When it finishes, the possible com‐
4603                      pletions are retrieved from the value of  the  COMPREPLY
4604                      array variable.
4605              -G globpat
4606                      The  pathname  expansion  pattern globpat is expanded to
4607                      generate the possible completions.
4608              -P prefix
4609                      prefix is added at the beginning of each  possible  com‐
4610                      pletion after all other options have been applied.
4611              -S suffix
4612                      suffix is appended to each possible completion after all
4613                      other options have been applied.
4614              -W wordlist
4615                      The wordlist is split using the characters  in  the  IFS
4616                      special  variable as delimiters, and each resultant word
4617                      is expanded.  Shell quoting is honored within  wordlist,
4618                      in order to provide a mechanism for the words to contain
4619                      shell metacharacters or characters in the value of  IFS.
4620                      The  possible  completions are the members of the resul‐
4621                      tant list which match the word being completed.
4622              -X filterpat
4623                      filterpat is a pattern as used for  pathname  expansion.
4624                      It is applied to the list of possible completions gener‐
4625                      ated by the preceding options and  arguments,  and  each
4626                      completion  matching filterpat is removed from the list.
4627                      A leading ! in filterpat negates the  pattern;  in  this
4628                      case, any completion not matching filterpat is removed.
4629
4630              The  return  value is true unless an invalid option is supplied,
4631              an option other than -p or -r is supplied without a  name  argu‐
4632              ment,  an  attempt  is made to remove a completion specification
4633              for a name for which no specification exists, or an error occurs
4634              adding a completion specification.
4635
4636       compopt [-o option] [-DEI] [+o option] [name]
4637              Modify  completion  options  for  each name according to the op‐
4638              tions, or for the currently-executing completion if no names are
4639              supplied.   If  no options are given, display the completion op‐
4640              tions for each name or the  current  completion.   The  possible
4641              values  of  option  are those valid for the complete builtin de‐
4642              scribed above.  The -D option indicates that other supplied  op‐
4643              tions  should  apply to the ``default'' command completion; that
4644              is, completion attempted on a command for  which  no  completion
4645              has previously been defined.  The -E option indicates that other
4646              supplied options should apply to ``empty''  command  completion;
4647              that  is,  completion  attempted on a blank line.  The -I option
4648              indicates that other supplied options should apply to completion
4649              on  the initial non-assignment word on the line, or after a com‐
4650              mand delimiter such as ; or |, which  is  usually  command  name
4651              completion.
4652
4653              The  return  value is true unless an invalid option is supplied,
4654              an attempt is made to modify the options for a name for which no
4655              completion specification exists, or an output error occurs.
4656
4657       continue [n]
4658              Resume the next iteration of the enclosing for, while, until, or
4659              select loop.  If n is specified, resume  at  the  nth  enclosing
4660              loop.   n  must  be ≥ 1.  If n is greater than the number of en‐
4661              closing loops, the last enclosing loop (the ``top-level''  loop)
4662              is  resumed.  The return value is 0 unless n is not greater than
4663              or equal to 1.
4664
4665       declare [-aAfFgiIlnrtux] [-p] [name[=value] ...]
4666       typeset [-aAfFgiIlnrtux] [-p] [name[=value] ...]
4667              Declare variables and/or give them attributes.  If no names  are
4668              given  then display the values of variables.  The -p option will
4669              display the attributes and values of each name.  When -p is used
4670              with  name  arguments, additional options, other than -f and -F,
4671              are ignored.  When -p is supplied  without  name  arguments,  it
4672              will  display  the attributes and values of all variables having
4673              the attributes specified by the additional options.  If no other
4674              options  are  supplied  with  -p,  declare  will display the at‐
4675              tributes and values of all shell variables.  The -f option  will
4676              restrict the display to shell functions.  The -F option inhibits
4677              the display of function definitions; only the function name  and
4678              attributes are printed.  If the extdebug shell option is enabled
4679              using shopt, the source file name and  line  number  where  each
4680              name  is  defined  are displayed as well.  The -F option implies
4681              -f.  The -g option forces variables to be created or modified at
4682              the global scope, even when declare is executed in a shell func‐
4683              tion.  It is ignored in all other cases.  The -I  option  causes
4684              local  variables  to  inherit the attributes (except the nameref
4685              attribute) and value of any existing variable with the same name
4686              at  a  surrounding scope.  If there is no existing variable, the
4687              local variable is initially unset.  The following options can be
4688              used  to  restrict output to variables with the specified attri‐
4689              bute or to give variables attributes:
4690              -a     Each name  is  an  indexed  array  variable  (see  Arrays
4691                     above).
4692              -A     Each  name  is  an associative array variable (see Arrays
4693                     above).
4694              -f     Use function names only.
4695              -i     The variable is treated as an integer; arithmetic evalua‐
4696                     tion  (see ARITHMETIC EVALUATION above) is performed when
4697                     the variable is assigned a value.
4698              -l     When the variable is assigned  a  value,  all  upper-case
4699                     characters  are  converted to lower-case.  The upper-case
4700                     attribute is disabled.
4701              -n     Give each name the nameref attribute, making  it  a  name
4702                     reference  to  another  variable.  That other variable is
4703                     defined by the value of name.   All  references,  assign‐
4704                     ments,  and attribute modifications to name, except those
4705                     using or changing the -n attribute itself, are  performed
4706                     on  the variable referenced by name's value.  The nameref
4707                     attribute cannot be applied to array variables.
4708              -r     Make names readonly.  These names cannot then be assigned
4709                     values by subsequent assignment statements or unset.
4710              -t     Give each name the trace attribute.  Traced functions in‐
4711                     herit the DEBUG and RETURN traps from the calling  shell.
4712                     The trace attribute has no special meaning for variables.
4713              -u     When  the  variable  is  assigned a value, all lower-case
4714                     characters are converted to upper-case.   The  lower-case
4715                     attribute is disabled.
4716              -x     Mark  names for export to subsequent commands via the en‐
4717                     vironment.
4718
4719              Using `+' instead of `-' turns off the attribute  instead,  with
4720              the  exceptions  that +a and +A may not be used to destroy array
4721              variables and +r will not remove the readonly  attribute.   When
4722              used in a function, declare and typeset make each name local, as
4723              with the local command, unless the -g option is supplied.  If  a
4724              variable  name  is followed by =value, the value of the variable
4725              is set to value.  When using -a or -A and the  compound  assign‐
4726              ment  syntax to create array variables, additional attributes do
4727              not take effect until subsequent assignments.  The return  value
4728              is 0 unless an invalid option is encountered, an attempt is made
4729              to define a function using ``-f foo=bar'', an attempt is made to
4730              assign a value to a readonly variable, an attempt is made to as‐
4731              sign a value to an array variable without using the compound as‐
4732              signment  syntax  (see  Arrays above), one of the names is not a
4733              valid shell variable name, an attempt is made to turn off  read‐
4734              only  status for a readonly variable, an attempt is made to turn
4735              off array status for an array variable, or an attempt is made to
4736              display a non-existent function with -f.
4737
4738       dirs [-clpv] [+n] [-n]
4739              Without  options,  displays the list of currently remembered di‐
4740              rectories.  The default display is on a single line with  direc‐
4741              tory  names  separated  by spaces.  Directories are added to the
4742              list with the pushd command; the popd  command  removes  entries
4743              from the list.  The current directory is always the first direc‐
4744              tory in the stack.
4745              -c     Clears the directory stack by deleting  all  of  the  en‐
4746                     tries.
4747              -l     Produces  a  listing  using  full  pathnames; the default
4748                     listing format uses a tilde to denote the home directory.
4749              -p     Print the directory stack with one entry per line.
4750              -v     Print the directory stack with one entry per  line,  pre‐
4751                     fixing each entry with its index in the stack.
4752              +n     Displays the nth entry counting from the left of the list
4753                     shown by dirs when invoked without options, starting with
4754                     zero.
4755              -n     Displays  the  nth  entry  counting from the right of the
4756                     list shown by dirs when invoked without options, starting
4757                     with zero.
4758
4759              The  return value is 0 unless an invalid option is supplied or n
4760              indexes beyond the end of the directory stack.
4761
4762       disown [-ar] [-h] [jobspec ... | pid ... ]
4763              Without options, remove each jobspec from the  table  of  active
4764              jobs.   If jobspec is not present, and neither the -a nor the -r
4765              option is supplied, the current job is used.  If the  -h  option
4766              is  given,  each  jobspec  is not removed from the table, but is
4767              marked so that SIGHUP is not sent to the job if  the  shell  re‐
4768              ceives a SIGHUP.  If no jobspec is supplied, the -a option means
4769              to remove or mark all jobs; the -r option without a jobspec  ar‐
4770              gument restricts operation to running jobs.  The return value is
4771              0 unless a jobspec does not specify a valid job.
4772
4773       echo [-neE] [arg ...]
4774              Output the args, separated by spaces,  followed  by  a  newline.
4775              The  return  status  is 0 unless a write error occurs.  If -n is
4776              specified, the trailing newline is suppressed.  If the -e option
4777              is  given,  interpretation  of  the  following backslash-escaped
4778              characters is enabled.  The -E option disables  the  interpreta‐
4779              tion  of these escape characters, even on systems where they are
4780              interpreted by default.  The xpg_echo shell option may  be  used
4781              to  dynamically  determine whether or not echo expands these es‐
4782              cape characters by default.  echo does not interpret -- to  mean
4783              the  end  of  options.  echo interprets the following escape se‐
4784              quences:
4785              \a     alert (bell)
4786              \b     backspace
4787              \c     suppress further output
4788              \e
4789              \E     an escape character
4790              \f     form feed
4791              \n     new line
4792              \r     carriage return
4793              \t     horizontal tab
4794              \v     vertical tab
4795              \\     backslash
4796              \0nnn  the eight-bit character whose value is  the  octal  value
4797                     nnn (zero to three octal digits)
4798              \xHH   the  eight-bit  character  whose value is the hexadecimal
4799                     value HH (one or two hex digits)
4800              \uHHHH the Unicode (ISO/IEC 10646) character whose value is  the
4801                     hexadecimal value HHHH (one to four hex digits)
4802              \UHHHHHHHH
4803                     the  Unicode (ISO/IEC 10646) character whose value is the
4804                     hexadecimal value HHHHHHHH (one to eight hex digits)
4805
4806       enable [-a] [-dnps] [-f filename] [name ...]
4807              Enable and disable builtin shell commands.  Disabling a  builtin
4808              allows a disk command which has the same name as a shell builtin
4809              to be executed without specifying a full pathname,  even  though
4810              the  shell  normally searches for builtins before disk commands.
4811              If -n is used, each name is disabled; otherwise, names  are  en‐
4812              abled.   For  example, to use the test binary found via the PATH
4813              instead of the shell builtin version, run  ``enable  -n  test''.
4814              The  -f  option  means to load the new builtin command name from
4815              shared object filename, on systems that support dynamic loading.
4816              The  -d  option will delete a builtin previously loaded with -f.
4817              If no name arguments are given, or if the -p option is supplied,
4818              a list of shell builtins is printed.  With no other option argu‐
4819              ments, the list consists of all enabled shell builtins.   If  -n
4820              is  supplied, only disabled builtins are printed.  If -a is sup‐
4821              plied, the list printed includes all builtins, with  an  indica‐
4822              tion  of whether or not each is enabled.  If -s is supplied, the
4823              output is restricted to the POSIX special builtins.  The  return
4824              value  is  0 unless a name is not a shell builtin or there is an
4825              error loading a new builtin from a shared object.
4826
4827       eval [arg ...]
4828              The args are read and concatenated together into a  single  com‐
4829              mand.   This command is then read and executed by the shell, and
4830              its exit status is returned as the value of eval.  If there  are
4831              no args, or only null arguments, eval returns 0.
4832
4833       exec [-cl] [-a name] [command [arguments]]
4834              If  command is specified, it replaces the shell.  No new process
4835              is created.  The arguments become the arguments to command.   If
4836              the -l option is supplied, the shell places a dash at the begin‐
4837              ning of the zeroth argument passed to command.  This is what lo‐
4838              gin(1)  does.   The -c option causes command to be executed with
4839              an empty environment.  If -a is supplied, the shell passes  name
4840              as the zeroth argument to the executed command.  If command can‐
4841              not be executed for some reason, a non-interactive shell  exits,
4842              unless  the  execfail shell option is enabled.  In that case, it
4843              returns failure.  An interactive shell returns  failure  if  the
4844              file  cannot  be  executed.  A subshell exits unconditionally if
4845              exec fails.  If command is not specified, any redirections  take
4846              effect  in  the  current  shell, and the return status is 0.  If
4847              there is a redirection error, the return status is 1.
4848
4849       exit [n]
4850              Cause the shell to exit with a status of n.  If  n  is  omitted,
4851              the exit status is that of the last command executed.  A trap on
4852              EXIT is executed before the shell terminates.
4853
4854       export [-fn] [name[=word]] ...
4855       export -p
4856              The supplied names are marked for automatic export to the  envi‐
4857              ronment  of subsequently executed commands.  If the -f option is
4858              given, the names refer to functions.  If no names are given,  or
4859              if  the  -p  option is supplied, a list of names of all exported
4860              variables is printed.  The -n option causes the export  property
4861              to be removed from each name.  If a variable name is followed by
4862              =word, the value of the variable is set to word.  export returns
4863              an exit status of 0 unless an invalid option is encountered, one
4864              of the names is not a valid shell variable name, or -f  is  sup‐
4865              plied with a name that is not a function.
4866
4867       fc [-e ename] [-lnr] [first] [last]
4868       fc -s [pat=rep] [cmd]
4869              The  first  form  selects a range of commands from first to last
4870              from the history list and  displays  or  edits  and  re-executes
4871              them.   First  and  last may be specified as a string (to locate
4872              the last command beginning with that string) or as a number  (an
4873              index  into the history list, where a negative number is used as
4874              an offset from the current command  number).   When  listing,  a
4875              first  or  last of 0 is equivalent to -1 and -0 is equivalent to
4876              the current command (usually the fc  command);  otherwise  0  is
4877              equivalent  to  -1 and -0 is invalid.  If last is not specified,
4878              it is set to the current command for listing (so  that  ``fc  -l
4879              -10''  prints  the last 10 commands) and to first otherwise.  If
4880              first is not specified, it is set to the  previous  command  for
4881              editing and -16 for listing.
4882
4883              The  -n option suppresses the command numbers when listing.  The
4884              -r option reverses the order of the commands.  If the -l  option
4885              is  given,  the  commands are listed on standard output.  Other‐
4886              wise, the editor given by ename is invoked on a file  containing
4887              those  commands.  If ename is not given, the value of the FCEDIT
4888              variable is used, and the value of EDITOR if FCEDIT is not  set.
4889              If  neither  variable  is set, vi is used.  When editing is com‐
4890              plete, the edited commands are echoed and executed.
4891
4892              In the second form, command is re-executed after  each  instance
4893              of  pat  is replaced by rep.  Command is interpreted the same as
4894              first above.  A useful alias to use with this is ``r="fc  -s"'',
4895              so  that  typing  ``r  cc'' runs the last command beginning with
4896              ``cc'' and typing ``r'' re-executes the last command.
4897
4898              If the first form is used, the return value is 0 unless  an  in‐
4899              valid  option  is  encountered  or first or last specify history
4900              lines out of range.  If the -e option is  supplied,  the  return
4901              value is the value of the last command executed or failure if an
4902              error occurs with the temporary file of commands.  If the second
4903              form  is  used, the return status is that of the command re-exe‐
4904              cuted, unless cmd does not specify  a  valid  history  line,  in
4905              which case fc returns failure.
4906
4907       fg [jobspec]
4908              Resume  jobspec  in the foreground, and make it the current job.
4909              If jobspec is not present, the shell's notion of the current job
4910              is  used.   The  return value is that of the command placed into
4911              the foreground, or failure if run when job control  is  disabled
4912              or, when run with job control enabled, if jobspec does not spec‐
4913              ify a valid job or jobspec specifies  a  job  that  was  started
4914              without job control.
4915
4916       getopts optstring name [arg ...]
4917              getopts  is used by shell procedures to parse positional parame‐
4918              ters.  optstring contains the option  characters  to  be  recog‐
4919              nized;  if a character is followed by a colon, the option is ex‐
4920              pected to have an argument, which should be separated from it by
4921              white  space.  The colon and question mark characters may not be
4922              used as option characters.  Each time  it  is  invoked,  getopts
4923              places  the next option in the shell variable name, initializing
4924              name if it does not exist, and the index of the next argument to
4925              be processed into the variable OPTIND.  OPTIND is initialized to
4926              1 each time the shell or a shell script is invoked.  When an op‐
4927              tion requires an argument, getopts places that argument into the
4928              variable OPTARG.  The shell does not reset OPTIND automatically;
4929              it  must  be  manually  reset  between multiple calls to getopts
4930              within the same shell invocation if a new set of  parameters  is
4931              to be used.
4932
4933              When the end of options is encountered, getopts exits with a re‐
4934              turn value greater than zero.  OPTIND is set to the index of the
4935              first non-option argument, and name is set to ?.
4936
4937              getopts  normally  parses the positional parameters, but if more
4938              arguments are supplied as arg values, getopts parses  those  in‐
4939              stead.
4940
4941              getopts  can  report errors in two ways.  If the first character
4942              of optstring is a colon, silent error  reporting  is  used.   In
4943              normal  operation,  diagnostic messages are printed when invalid
4944              options or missing option arguments  are  encountered.   If  the
4945              variable  OPTERR  is  set  to  0, no error messages will be dis‐
4946              played, even if the first character of optstring is not a colon.
4947
4948              If an invalid option is seen, getopts places ? into name and, if
4949              not  silent,  prints  an  error  message  and unsets OPTARG.  If
4950              getopts is silent, the option character found is placed  in  OP‐
4951              TARG and no diagnostic message is printed.
4952
4953              If  a required argument is not found, and getopts is not silent,
4954              a question mark (?) is placed in name, OPTARG is  unset,  and  a
4955              diagnostic  message  is  printed.   If getopts is silent, then a
4956              colon (:) is placed in name and OPTARG  is  set  to  the  option
4957              character found.
4958
4959              getopts  returns true if an option, specified or unspecified, is
4960              found.  It returns false if the end of options is encountered or
4961              an error occurs.
4962
4963       hash [-lr] [-p filename] [-dt] [name]
4964              Each time hash is invoked, the full pathname of the command name
4965              is determined by searching the directories in $PATH  and  remem‐
4966              bered.  Any previously-remembered pathname is discarded.  If the
4967              -p option is supplied, no path search is performed, and filename
4968              is  used  as  the  full  filename of the command.  The -r option
4969              causes the shell to forget all remembered locations.  The -d op‐
4970              tion  causes the shell to forget the remembered location of each
4971              name.  If the -t option is supplied, the full pathname to  which
4972              each  name  corresponds  is printed.  If multiple name arguments
4973              are supplied with -t, the name is printed before the hashed full
4974              pathname.  The -l option causes output to be displayed in a for‐
4975              mat that may be reused as input.  If no arguments are given,  or
4976              if only -l is supplied, information about remembered commands is
4977              printed.  The return status is true unless a name is  not  found
4978              or an invalid option is supplied.
4979
4980       help [-dms] [pattern]
4981              Display  helpful information about builtin commands.  If pattern
4982              is specified, help gives detailed help on all commands  matching
4983              pattern;  otherwise  help for all the builtins and shell control
4984              structures is printed.
4985              -d     Display a short description of each pattern
4986              -m     Display the description of each pattern in a manpage-like
4987                     format
4988              -s     Display only a short usage synopsis for each pattern
4989
4990              The return status is 0 unless no command matches pattern.
4991
4992       history [n]
4993       history -c
4994       history -d offset
4995       history -d start-end
4996       history -anrw [filename]
4997       history -p arg [arg ...]
4998       history -s arg [arg ...]
4999              With no options, display the command history list with line num‐
5000              bers.  Lines listed with a * have been modified.  An argument of
5001              n  lists only the last n lines.  If the shell variable HISTTIME‐
5002              FORMAT is set and not null, it is used as a  format  string  for
5003              strftime(3)  to display the time stamp associated with each dis‐
5004              played history entry.  No intervening blank is  printed  between
5005              the  formatted  time stamp and the history line.  If filename is
5006              supplied, it is used as the name of the history  file;  if  not,
5007              the  value  of HISTFILE is used.  Options, if supplied, have the
5008              following meanings:
5009              -c     Clear the history list by deleting all the entries.
5010              -d offset
5011                     Delete the history entry at position offset.   If  offset
5012                     is negative, it is interpreted as relative to one greater
5013                     than the last history position, so negative indices count
5014                     back  from  the  end  of  the history, and an index of -1
5015                     refers to the current history -d command.
5016              -d start-end
5017                     Delete the history entries between  positions  start  and
5018                     end,  inclusive.   Positive and negative values for start
5019                     and end are interpreted as described above.
5020              -a     Append the ``new'' history lines  to  the  history  file.
5021                     These  are  history  lines entered since the beginning of
5022                     the current bash session, but not already appended to the
5023                     history file.
5024              -n     Read  the history lines not already read from the history
5025                     file into the current history list.  These are lines  ap‐
5026                     pended  to  the  history  file since the beginning of the
5027                     current bash session.
5028              -r     Read the contents of the history file and append them  to
5029                     the current history list.
5030              -w     Write the current history list to the history file, over‐
5031                     writing the history file's contents.
5032              -p     Perform history substitution on the  following  args  and
5033                     display  the  result  on  the  standard output.  Does not
5034                     store the results in the history list.  Each arg must  be
5035                     quoted to disable normal history expansion.
5036              -s     Store  the  args  in  the history list as a single entry.
5037                     The last command in the history list  is  removed  before
5038                     the args are added.
5039
5040              If  the  HISTTIMEFORMAT variable is set, the time stamp informa‐
5041              tion associated with each history entry is written to  the  his‐
5042              tory  file, marked with the history comment character.  When the
5043              history file is read, lines beginning with the  history  comment
5044              character  followed  immediately  by  a digit are interpreted as
5045              timestamps for the following history entry.  The return value is
5046              0 unless an invalid option is encountered, an error occurs while
5047              reading or writing the history file, an invalid offset  is  sup‐
5048              plied as an argument to -d, or the history expansion supplied as
5049              an argument to -p fails.
5050
5051       jobs [-lnprs] [ jobspec ... ]
5052       jobs -x command [ args ... ]
5053              The first form lists the active jobs.  The options have the fol‐
5054              lowing meanings:
5055              -l     List process IDs in addition to the normal information.
5056              -n     Display  information  only  about  jobs that have changed
5057                     status since the user was last notified of their status.
5058              -p     List only the process  ID  of  the  job's  process  group
5059                     leader.
5060              -r     Display only running jobs.
5061              -s     Display only stopped jobs.
5062
5063              If  jobspec  is given, output is restricted to information about
5064              that job.  The return status is 0 unless an  invalid  option  is
5065              encountered or an invalid jobspec is supplied.
5066
5067              If the -x option is supplied, jobs replaces any jobspec found in
5068              command or args with the corresponding process group ID, and ex‐
5069              ecutes command passing it args, returning its exit status.
5070
5071       kill [-s sigspec | -n signum | -sigspec] [pid | jobspec] ...
5072       kill -l|-L [sigspec | exit_status]
5073              Send  the  signal  named  by  sigspec or signum to the processes
5074              named by pid or jobspec.  sigspec is either  a  case-insensitive
5075              signal  name such as SIGKILL (with or without the SIG prefix) or
5076              a signal number; signum is a signal number.  If sigspec  is  not
5077              present,  then  SIGTERM is assumed.  An argument of -l lists the
5078              signal names.  If any arguments are supplied when -l  is  given,
5079              the  names  of  the  signals  corresponding to the arguments are
5080              listed, and the return status is 0.  The exit_status argument to
5081              -l  is  a  number  specifying either a signal number or the exit
5082              status of a process terminated by a signal.  The  -L  option  is
5083              equivalent  to -l.  kill returns true if at least one signal was
5084              successfully sent, or false if an error occurs or an invalid op‐
5085              tion is encountered.
5086
5087       let arg [arg ...]
5088              Each arg is an arithmetic expression to be evaluated (see ARITH‐
5089              METIC EVALUATION above).  If the last arg evaluates  to  0,  let
5090              returns 1; 0 is returned otherwise.
5091
5092       local [option] [name[=value] ... | - ]
5093              For  each  argument, a local variable named name is created, and
5094              assigned value.  The option can be any of the  options  accepted
5095              by declare.  When local is used within a function, it causes the
5096              variable name to have a visible scope restricted to  that  func‐
5097              tion  and  its children.  If name is -, the set of shell options
5098              is made local to the function in which local is  invoked:  shell
5099              options  changed  using  the set builtin inside the function are
5100              restored to their original values  when  the  function  returns.
5101              The restore is effected as if a series of set commands were exe‐
5102              cuted to restore the values that were in place before the  func‐
5103              tion.   With no operands, local writes a list of local variables
5104              to the standard output.  It is an error to use  local  when  not
5105              within  a function.  The return status is 0 unless local is used
5106              outside a function, an invalid name is supplied, or  name  is  a
5107              readonly variable.
5108
5109       logout Exit a login shell.
5110
5111       mapfile  [-d  delim] [-n count] [-O origin] [-s count] [-t] [-u fd] [-C
5112       callback] [-c quantum] [array]
5113       readarray [-d delim] [-n count] [-O origin] [-s count] [-t] [-u fd] [-C
5114       callback] [-c quantum] [array]
5115              Read  lines from the standard input into the indexed array vari‐
5116              able array, or from file descriptor fd if the -u option is  sup‐
5117              plied.   The variable MAPFILE is the default array.  Options, if
5118              supplied, have the following meanings:
5119              -d     The first character of delim is used  to  terminate  each
5120                     input  line,  rather than newline.  If delim is the empty
5121                     string, mapfile will terminate a line when it reads a NUL
5122                     character.
5123              -n     Copy  at  most count lines.  If count is 0, all lines are
5124                     copied.
5125              -O     Begin assigning to array at index  origin.   The  default
5126                     index is 0.
5127              -s     Discard the first count lines read.
5128              -t     Remove  a trailing delim (default newline) from each line
5129                     read.
5130              -u     Read lines from file descriptor fd instead of  the  stan‐
5131                     dard input.
5132              -C     Evaluate  callback each time quantum lines are read.  The
5133                     -c option specifies quantum.
5134              -c     Specify the number of lines read  between  each  call  to
5135                     callback.
5136
5137              If  -C  is  specified  without  -c, the default quantum is 5000.
5138              When callback is evaluated, it is supplied the index of the next
5139              array element to be assigned and the line to be assigned to that
5140              element as additional arguments.  callback  is  evaluated  after
5141              the line is read but before the array element is assigned.
5142
5143              If  not supplied with an explicit origin, mapfile will clear ar‐
5144              ray before assigning to it.
5145
5146              mapfile returns successfully unless an invalid option or  option
5147              argument  is  supplied,  array is invalid or unassignable, or if
5148              array is not an indexed array.
5149
5150       popd [-n] [+n] [-n]
5151              Removes entries from the directory stack.   With  no  arguments,
5152              removes  the  top directory from the stack, and performs a cd to
5153              the new top directory.  Arguments, if supplied, have the follow‐
5154              ing meanings:
5155              -n     Suppresses  the  normal change of directory when removing
5156                     directories from the stack, so that only the stack is ma‐
5157                     nipulated.
5158              +n     Removes  the nth entry counting from the left of the list
5159                     shown by dirs, starting with zero.  For  example:  ``popd
5160                     +0'' removes the first directory, ``popd +1'' the second.
5161              -n     Removes the nth entry counting from the right of the list
5162                     shown by dirs, starting with zero.  For  example:  ``popd
5163                     -0''  removes the last directory, ``popd -1'' the next to
5164                     last.
5165
5166              If the popd command is successful, a dirs is performed as  well,
5167              and  the  return  status is 0.  popd returns false if an invalid
5168              option is encountered, the directory stack is empty, a non-exis‐
5169              tent directory stack entry is specified, or the directory change
5170              fails.
5171
5172       printf [-v var] format [arguments]
5173              Write the formatted arguments to the standard output  under  the
5174              control  of  the  format.  The -v option causes the output to be
5175              assigned to the variable var rather than being  printed  to  the
5176              standard output.
5177
5178              The  format  is a character string which contains three types of
5179              objects: plain characters, which are simply copied  to  standard
5180              output,  character  escape  sequences,  which  are converted and
5181              copied to the standard output, and format  specifications,  each
5182              of  which  causes  printing of the next successive argument.  In
5183              addition to the standard printf(1) format specifications, printf
5184              interprets the following extensions:
5185              %b     causes printf to expand backslash escape sequences in the
5186                     corresponding argument in the same way as echo -e.
5187              %q     causes printf to output the corresponding argument  in  a
5188                     format that can be reused as shell input.
5189              %(datefmt)T
5190                     causes  printf  to  output the date-time string resulting
5191                     from using datefmt as a format  string  for  strftime(3).
5192                     The corresponding argument is an integer representing the
5193                     number of seconds since the epoch.  Two special  argument
5194                     values  may  be used: -1 represents the current time, and
5195                     -2 represents the time the shell was invoked.  If no  ar‐
5196                     gument is specified, conversion behaves as if -1 had been
5197                     given.  This is an exception to the usual  printf  behav‐
5198                     ior.
5199
5200              The %b, %q, and %T directives all use the field width and preci‐
5201              sion arguments from the format specification and write that many
5202              bytes from (or use that wide a field for) the expanded argument,
5203              which usually contains more characters than the original.
5204
5205              Arguments to non-string format specifiers are treated as C  con‐
5206              stants, except that a leading plus or minus sign is allowed, and
5207              if the leading character is a single or double quote, the  value
5208              is the ASCII value of the following character.
5209
5210              The  format  is  reused as necessary to consume all of the argu‐
5211              ments.  If the format requires more arguments than are supplied,
5212              the  extra  format  specifications  behave as if a zero value or
5213              null string, as appropriate,  had  been  supplied.   The  return
5214              value is zero on success, non-zero on failure.
5215
5216       pushd [-n] [+n] [-n]
5217       pushd [-n] [dir]
5218              Adds  a  directory to the top of the directory stack, or rotates
5219              the stack, making the new top of the stack the  current  working
5220              directory.   With  no arguments, pushd exchanges the top two di‐
5221              rectories and returns 0, unless the directory  stack  is  empty.
5222              Arguments, if supplied, have the following meanings:
5223              -n     Suppresses  the  normal change of directory when rotating
5224                     or adding directories to the  stack,  so  that  only  the
5225                     stack is manipulated.
5226              +n     Rotates  the  stack  so  that the nth directory (counting
5227                     from the left of the list shown by  dirs,  starting  with
5228                     zero) is at the top.
5229              -n     Rotates  the  stack  so  that the nth directory (counting
5230                     from the right of the list shown by dirs,  starting  with
5231                     zero) is at the top.
5232              dir    Adds dir to the directory stack at the top, making it the
5233                     new current working directory as if it had been  supplied
5234                     as the argument to the cd builtin.
5235
5236              If the pushd command is successful, a dirs is performed as well.
5237              If the first form is used, pushd returns 0 unless the cd to  dir
5238              fails.   With the second form, pushd returns 0 unless the direc‐
5239              tory stack is empty, a non-existent directory stack  element  is
5240              specified,  or the directory change to the specified new current
5241              directory fails.
5242
5243       pwd [-LP]
5244              Print the absolute pathname of the  current  working  directory.
5245              The pathname printed contains no symbolic links if the -P option
5246              is supplied or the -o physical option to the set builtin command
5247              is  enabled.  If the -L option is used, the pathname printed may
5248              contain symbolic links.  The return status is 0 unless an  error
5249              occurs while reading the name of the current directory or an in‐
5250              valid option is supplied.
5251
5252       read [-ers] [-a aname] [-d delim] [-i text] [-n nchars] [-N nchars] [-p
5253       prompt] [-t timeout] [-u fd] [name ...]
5254              One  line  is read from the standard input, or from the file de‐
5255              scriptor fd supplied as an argument to the -u option, split into
5256              words  as  described  above  under Word Splitting, and the first
5257              word is assigned to the first name, the second word to the  sec‐
5258              ond  name,  and  so on.  If there are more words than names, the
5259              remaining words and their intervening delimiters are assigned to
5260              the  last  name.   If  there are fewer words read from the input
5261              stream than names, the remaining names are assigned  empty  val‐
5262              ues.   The  characters  in  IFS  are used to split the line into
5263              words using the same rules the shell  uses  for  expansion  (de‐
5264              scribed  above  under  Word Splitting).  The backslash character
5265              (\) may be used to remove any special meaning for the next char‐
5266              acter  read  and  for  line continuation.  Options, if supplied,
5267              have the following meanings:
5268              -a aname
5269                     The words are assigned to sequential indices of the array
5270                     variable aname, starting at 0.  aname is unset before any
5271                     new values are assigned.  Other name  arguments  are  ig‐
5272                     nored.
5273              -d delim
5274                     The first character of delim is used to terminate the in‐
5275                     put line, rather than newline.  If  delim  is  the  empty
5276                     string,  read  will  terminate a line when it reads a NUL
5277                     character.
5278              -e     If the standard input is coming from a terminal, readline
5279                     (see  READLINE  above) is used to obtain the line.  Read‐
5280                     line uses the current (or default, if  line  editing  was
5281                     not  previously  active) editing settings, but uses Read‐
5282                     line's default filename completion.
5283              -i text
5284                     If readline is being used  to  read  the  line,  text  is
5285                     placed into the editing buffer before editing begins.
5286              -n nchars
5287                     read  returns after reading nchars characters rather than
5288                     waiting for a complete line of input, but honors a delim‐
5289                     iter  if fewer than nchars characters are read before the
5290                     delimiter.
5291              -N nchars
5292                     read returns  after  reading  exactly  nchars  characters
5293                     rather  than waiting for a complete line of input, unless
5294                     EOF is encountered or read times out.  Delimiter  charac‐
5295                     ters  encountered  in the input are not treated specially
5296                     and do not cause read to return until  nchars  characters
5297                     are  read.   The result is not split on the characters in
5298                     IFS; the intent is that the variable is assigned  exactly
5299                     the characters read (with the exception of backslash; see
5300                     the -r option below).
5301              -p prompt
5302                     Display prompt on standard error, without a trailing new‐
5303                     line, before attempting to read any input.  The prompt is
5304                     displayed only if input is coming from a terminal.
5305              -r     Backslash does not act as an escape character.  The back‐
5306                     slash  is considered to be part of the line.  In particu‐
5307                     lar, a backslash-newline pair may not then be used  as  a
5308                     line continuation.
5309              -s     Silent mode.  If input is coming from a terminal, charac‐
5310                     ters are not echoed.
5311              -t timeout
5312                     Cause read to time out and return failure if  a  complete
5313                     line  of  input  (or a specified number of characters) is
5314                     not read within timeout seconds.  timeout may be a  deci‐
5315                     mal  number with a fractional portion following the deci‐
5316                     mal point.  This option is  only  effective  if  read  is
5317                     reading  input  from  a  terminal, pipe, or other special
5318                     file; it has no effect when reading from  regular  files.
5319                     If read times out, read saves any partial input read into
5320                     the specified variable name.  If timeout is 0,  read  re‐
5321                     turns  immediately, without trying to read any data.  The
5322                     exit status is 0 if input is available on  the  specified
5323                     file  descriptor, non-zero otherwise.  The exit status is
5324                     greater than 128 if the timeout is exceeded.
5325              -u fd  Read input from file descriptor fd.
5326
5327              If no names are supplied, the line read, without the ending  de‐
5328              limiter  but  otherwise  unmodified, is assigned to the variable
5329              REPLY.  The exit status is zero, unless end-of-file  is  encoun‐
5330              tered,  read times out (in which case the status is greater than
5331              128), a variable assignment error (such as assigning to a  read‐
5332              only variable) occurs, or an invalid file descriptor is supplied
5333              as the argument to -u.
5334
5335       readonly [-aAf] [-p] [name[=word] ...]
5336              The given names are marked readonly; the values of  these  names
5337              may  not  be changed by subsequent assignment.  If the -f option
5338              is supplied, the functions corresponding to  the  names  are  so
5339              marked.   The  -a  option restricts the variables to indexed ar‐
5340              rays; the -A option restricts the variables to  associative  ar‐
5341              rays.  If both options are supplied, -A takes precedence.  If no
5342              name arguments are given, or if the -p  option  is  supplied,  a
5343              list of all readonly names is printed.  The other options may be
5344              used to restrict the output to a subset of the set  of  readonly
5345              names.   The -p option causes output to be displayed in a format
5346              that may be reused as input.  If a variable name is followed  by
5347              =word,  the  value  of  the variable is set to word.  The return
5348              status is 0 unless an invalid option is encountered, one of  the
5349              names is not a valid shell variable name, or -f is supplied with
5350              a name that is not a function.
5351
5352       return [n]
5353              Causes a function to stop executing and return the value  speci‐
5354              fied  by n to its caller.  If n is omitted, the return status is
5355              that of the last command executed in the function body.  If  re‐
5356              turn is executed by a trap handler, the last command used to de‐
5357              termine the status is the last command executed before the  trap
5358              handler.   If  return  is executed during a DEBUG trap, the last
5359              command used to determine the status is the  last  command  exe‐
5360              cuted  by the trap handler before return was invoked.  If return
5361              is used outside a function, but during execution of a script  by
5362              the  .   (source) command, it causes the shell to stop executing
5363              that script and return either n or the exit status of  the  last
5364              command  executed  within  the  script as the exit status of the
5365              script.  If n is supplied, the return value is its least signif‐
5366              icant  8  bits.  The return status is non-zero if return is sup‐
5367              plied a non-numeric argument, or is used outside a function  and
5368              not  during  execution  of a script by . or source.  Any command
5369              associated with the RETURN trap is executed before execution re‐
5370              sumes after the function or script.
5371
5372       set [--abefhkmnptuvxBCEHPT] [-o option-name] [arg ...]
5373       set [+abefhkmnptuvxBCEHPT] [+o option-name] [arg ...]
5374              Without  options,  the name and value of each shell variable are
5375              displayed in a format that can be reused as input for setting or
5376              resetting the currently-set variables.  Read-only variables can‐
5377              not be reset.  In posix mode, only shell variables  are  listed.
5378              The  output is sorted according to the current locale.  When op‐
5379              tions are specified, they set or unset  shell  attributes.   Any
5380              arguments  remaining after option processing are treated as val‐
5381              ues for the positional parameters and are assigned, in order, to
5382              $1,  $2,  ...   $n.   Options,  if specified, have the following
5383              meanings:
5384              -a      Each variable or function that is created or modified is
5385                      given  the export attribute and marked for export to the
5386                      environment of subsequent commands.
5387              -b      Report the status of terminated background jobs  immedi‐
5388                      ately, rather than before the next primary prompt.  This
5389                      is effective only when job control is enabled.
5390              -e      Exit immediately if a pipeline (which may consist  of  a
5391                      single  simple  command),  a list, or a compound command
5392                      (see SHELL GRAMMAR above), exits with a non-zero status.
5393                      The  shell  does  not  exit if the command that fails is
5394                      part of the command list immediately following  a  while
5395                      or  until  keyword, part of the test following the if or
5396                      elif reserved words, part of any command executed  in  a
5397                      &&  or || list except the command following the final &&
5398                      or ||, any command in a pipeline but the last, or if the
5399                      command's  return  value is being inverted with !.  If a
5400                      compound command other than a subshell  returns  a  non-
5401                      zero  status because a command failed while -e was being
5402                      ignored, the shell does not exit.  A  trap  on  ERR,  if
5403                      set,  is  executed  before the shell exits.  This option
5404                      applies to the shell environment and each subshell envi‐
5405                      ronment  separately  (see  COMMAND EXECUTION ENVIRONMENT
5406                      above), and may cause subshells to exit before executing
5407                      all the commands in the subshell.
5408
5409                      If  a  compound  command or shell function executes in a
5410                      context where -e is being ignored, none of the  commands
5411                      executed  within  the  compound command or function body
5412                      will be affected by the -e setting, even if  -e  is  set
5413                      and  a  command returns a failure status.  If a compound
5414                      command or shell function sets -e while executing  in  a
5415                      context  where -e is ignored, that setting will not have
5416                      any effect until the compound  command  or  the  command
5417                      containing the function call completes.
5418              -f      Disable pathname expansion.
5419              -h      Remember  the location of commands as they are looked up
5420                      for execution.  This is enabled by default.
5421              -k      All arguments in the form of assignment  statements  are
5422                      placed  in the environment for a command, not just those
5423                      that precede the command name.
5424              -m      Monitor mode.  Job control is enabled.  This  option  is
5425                      on  by  default  for  interactive shells on systems that
5426                      support it (see JOB CONTROL above).  All  processes  run
5427                      in a separate process group.  When a background job com‐
5428                      pletes, the shell prints a line containing its exit sta‐
5429                      tus.
5430              -n      Read commands but do not execute them.  This may be used
5431                      to check a shell script for syntax errors.  This is  ig‐
5432                      nored by interactive shells.
5433              -o option-name
5434                      The option-name can be one of the following:
5435                      allexport
5436                              Same as -a.
5437                      braceexpand
5438                              Same as -B.
5439                      emacs   Use  an  emacs-style command line editing inter‐
5440                              face.  This is enabled by default when the shell
5441                              is interactive, unless the shell is started with
5442                              the --noediting option.  This also  affects  the
5443                              editing interface used for read -e.
5444                      errexit Same as -e.
5445                      errtrace
5446                              Same as -E.
5447                      functrace
5448                              Same as -T.
5449                      hashall Same as -h.
5450                      histexpand
5451                              Same as -H.
5452                      history Enable command history, as described above under
5453                              HISTORY.  This option is on by default in inter‐
5454                              active shells.
5455                      ignoreeof
5456                              The  effect  is  as  if  the shell command ``IG‐
5457                              NOREEOF=10'' had been executed (see Shell  Vari‐
5458                              ables above).
5459                      keyword Same as -k.
5460                      monitor Same as -m.
5461                      noclobber
5462                              Same as -C.
5463                      noexec  Same as -n.
5464                      noglob  Same as -f.
5465                      nolog   Currently ignored.
5466                      notify  Same as -b.
5467                      nounset Same as -u.
5468                      onecmd  Same as -t.
5469                      physical
5470                              Same as -P.
5471                      pipefail
5472                              If  set,  the  return value of a pipeline is the
5473                              value of the last (rightmost)  command  to  exit
5474                              with  a non-zero status, or zero if all commands
5475                              in the pipeline exit successfully.  This  option
5476                              is disabled by default.
5477                      posix   Change  the  behavior  of bash where the default
5478                              operation differs from  the  POSIX  standard  to
5479                              match  the  standard (posix mode).  See SEE ALSO
5480                              below for a reference to a document that details
5481                              how posix mode affects bash's behavior.
5482                      privileged
5483                              Same as -p.
5484                      verbose Same as -v.
5485                      vi      Use  a  vi-style command line editing interface.
5486                              This also affects the editing interface used for
5487                              read -e.
5488                      xtrace  Same as -x.
5489                      If -o is supplied with no option-name, the values of the
5490                      current options are printed.  If +o is supplied with  no
5491                      option-name,  a  series  of set commands to recreate the
5492                      current option settings is  displayed  on  the  standard
5493                      output.
5494              -p      Turn  on  privileged  mode.   In this mode, the $ENV and
5495                      $BASH_ENV files are not processed, shell  functions  are
5496                      not  inherited  from the environment, and the SHELLOPTS,
5497                      BASHOPTS, CDPATH, and GLOBIGNORE variables, if they  ap‐
5498                      pear  in  the environment, are ignored.  If the shell is
5499                      started with the effective user (group) id not equal  to
5500                      the  real user (group) id, and the -p option is not sup‐
5501                      plied, these actions are taken and the effective user id
5502                      is  set  to  the real user id.  If the -p option is sup‐
5503                      plied at startup, the effective user id  is  not  reset.
5504                      Turning  this  option  off causes the effective user and
5505                      group ids to be set to the real user and group ids.
5506              -t      Exit after reading and executing one command.
5507              -u      Treat unset variables and parameters other than the spe‐
5508                      cial  parameters "@" and "*" as an error when performing
5509                      parameter expansion.  If expansion is  attempted  on  an
5510                      unset  variable  or parameter, the shell prints an error
5511                      message, and, if not interactive, exits with a  non-zero
5512                      status.
5513              -v      Print shell input lines as they are read.
5514              -x      After  expanding  each simple command, for command, case
5515                      command, select command, or arithmetic for command, dis‐
5516                      play  the expanded value of PS4, followed by the command
5517                      and its expanded arguments or associated word list.
5518              -B      The shell performs brace expansion (see Brace  Expansion
5519                      above).  This is on by default.
5520              -C      If  set,  bash  does not overwrite an existing file with
5521                      the >, >&, and <> redirection operators.   This  may  be
5522                      overridden when creating output files by using the redi‐
5523                      rection operator >| instead of >.
5524              -E      If set, any trap on ERR is inherited by shell functions,
5525                      command  substitutions,  and commands executed in a sub‐
5526                      shell environment.  The ERR trap is normally not  inher‐
5527                      ited in such cases.
5528              -H      Enable !  style history substitution.  This option is on
5529                      by default when the shell is interactive.
5530              -P      If set, the shell does not resolve symbolic  links  when
5531                      executing  commands  such  as cd that change the current
5532                      working  directory.   It  uses  the  physical  directory
5533                      structure instead.  By default, bash follows the logical
5534                      chain of  directories  when  performing  commands  which
5535                      change the current directory.
5536              -T      If  set,  any traps on DEBUG and RETURN are inherited by
5537                      shell functions, command substitutions, and commands ex‐
5538                      ecuted  in a subshell environment.  The DEBUG and RETURN
5539                      traps are normally not inherited in such cases.
5540              --      If no arguments follow this option, then the  positional
5541                      parameters are unset.  Otherwise, the positional parame‐
5542                      ters are set to the args, even if  some  of  them  begin
5543                      with a -.
5544              -       Signal  the  end of options, cause all remaining args to
5545                      be assigned to the positional parameters.  The -x and -v
5546                      options are turned off.  If there are no args, the posi‐
5547                      tional parameters remain unchanged.
5548
5549              The options are off by default unless otherwise noted.  Using  +
5550              rather  than  -  causes these options to be turned off.  The op‐
5551              tions can also be specified as arguments to an invocation of the
5552              shell.   The current set of options may be found in $-.  The re‐
5553              turn status is always true unless an invalid option  is  encoun‐
5554              tered.
5555
5556       shift [n]
5557              The  positional  parameters  from n+1 ... are renamed to $1 ....
5558              Parameters represented by the numbers $# down to $#-n+1 are  un‐
5559              set.   n must be a non-negative number less than or equal to $#.
5560              If n is 0, no parameters are changed.  If n is not given, it  is
5561              assumed to be 1.  If n is greater than $#, the positional param‐
5562              eters are not changed.  The return status is greater  than  zero
5563              if n is greater than $# or less than zero; otherwise 0.
5564
5565       shopt [-pqsu] [-o] [optname ...]
5566              Toggle  the values of settings controlling optional shell behav‐
5567              ior.  The settings can be either those listed below, or, if  the
5568              -o option is used, those available with the -o option to the set
5569              builtin command.  With no options, or with the -p option, a list
5570              of  all  settable  options  is  displayed, with an indication of
5571              whether or not each is set; if optnames are supplied, the output
5572              is  restricted to those options.  The -p option causes output to
5573              be displayed in a form that may be reused as input.   Other  op‐
5574              tions have the following meanings:
5575              -s     Enable (set) each optname.
5576              -u     Disable (unset) each optname.
5577              -q     Suppresses  normal output (quiet mode); the return status
5578                     indicates whether the optname is set or unset.  If multi‐
5579                     ple  optname arguments are given with -q, the return sta‐
5580                     tus is zero if all optnames are enabled; non-zero  other‐
5581                     wise.
5582              -o     Restricts  the  values of optname to be those defined for
5583                     the -o option to the set builtin.
5584
5585              If either -s or -u is used  with  no  optname  arguments,  shopt
5586              shows  only  those options which are set or unset, respectively.
5587              Unless otherwise noted, the shopt options are  disabled  (unset)
5588              by default.
5589
5590              The  return  status when listing options is zero if all optnames
5591              are enabled, non-zero otherwise.  When setting or unsetting  op‐
5592              tions,  the  return  status  is  zero unless an optname is not a
5593              valid shell option.
5594
5595              The list of shopt options is:
5596
5597              assoc_expand_once
5598                      If set, the shell suppresses multiple evaluation of  as‐
5599                      sociative  array subscripts during arithmetic expression
5600                      evaluation, while executing builtins  that  can  perform
5601                      variable  assignments, and while executing builtins that
5602                      perform array dereferencing.
5603              autocd  If set, a command name that is the name of  a  directory
5604                      is  executed  as  if it were the argument to the cd com‐
5605                      mand.  This option is only used by interactive shells.
5606              cdable_vars
5607                      If set, an argument to the cd builtin  command  that  is
5608                      not  a directory is assumed to be the name of a variable
5609                      whose value is the directory to change to.
5610              cdspell If set, minor errors in the spelling of a directory com‐
5611                      ponent  in  a  cd command will be corrected.  The errors
5612                      checked for are transposed characters, a missing charac‐
5613                      ter,  and  one  character  too many.  If a correction is
5614                      found, the corrected filename is printed, and  the  com‐
5615                      mand  proceeds.  This option is only used by interactive
5616                      shells.
5617              checkhash
5618                      If set, bash checks that a command found in the hash ta‐
5619                      ble  exists  before  trying  to execute it.  If a hashed
5620                      command no longer exists, a normal path search  is  per‐
5621                      formed.
5622              checkjobs
5623                      If set, bash lists the status of any stopped and running
5624                      jobs before exiting an interactive shell.  If  any  jobs
5625                      are running, this causes the exit to be deferred until a
5626                      second exit is attempted without an intervening  command
5627                      (see JOB CONTROL above).  The shell always postpones ex‐
5628                      iting if any jobs are stopped.
5629              checkwinsize
5630                      If set, bash checks the window size after each  external
5631                      (non-builtin)  command  and,  if  necessary, updates the
5632                      values of LINES and COLUMNS.  This option is enabled  by
5633                      default.
5634              cmdhist If  set,  bash attempts to save all lines of a multiple-
5635                      line command in the same  history  entry.   This  allows
5636                      easy  re-editing of multi-line commands.  This option is
5637                      enabled by default, but only has an  effect  if  command
5638                      history is enabled, as described above under HISTORY.
5639              compat31
5640              compat32
5641              compat40
5642              compat41
5643              compat42
5644              compat43
5645              compat44
5646                      These  control aspects of the shell's compatibility mode
5647                      (see SHELL COMPATIBILITY MODE below).
5648
5649              complete_fullquote
5650                      If set, bash quotes all shell  metacharacters  in  file‐
5651                      names  and  directory  names when performing completion.
5652                      If not set, bash removes metacharacters such as the dol‐
5653                      lar  sign from the set of characters that will be quoted
5654                      in completed filenames when these metacharacters  appear
5655                      in  shell  variable references in words to be completed.
5656                      This means that dollar signs in variable names that  ex‐
5657                      pand  to  directories  will  not be quoted; however, any
5658                      dollar signs appearing in filenames will not be  quoted,
5659                      either.   This  is  active only when bash is using back‐
5660                      slashes to quote completed filenames.  This variable  is
5661                      set  by  default,  which is the default bash behavior in
5662                      versions through 4.2.
5663
5664              direxpand
5665                      If set, bash replaces directory names with  the  results
5666                      of  word  expansion when performing filename completion.
5667                      This changes the contents of the readline  editing  buf‐
5668                      fer.   If  not  set,  bash attempts to preserve what the
5669                      user typed.
5670
5671              dirspell
5672                      If set, bash attempts spelling correction  on  directory
5673                      names  during word completion if the directory name ini‐
5674                      tially supplied does not exist.
5675
5676              dotglob If set, bash includes filenames beginning with a `.'  in
5677                      the  results of pathname expansion.  The filenames ``.''
5678                      and ``..''  must always be matched explicitly,  even  if
5679                      dotglob is set.
5680
5681              execfail
5682                      If set, a non-interactive shell will not exit if it can‐
5683                      not execute the file specified as  an  argument  to  the
5684                      exec  builtin  command.   An  interactive shell does not
5685                      exit if exec fails.
5686
5687              expand_aliases
5688                      If set, aliases are expanded as  described  above  under
5689                      ALIASES.  This option is enabled by default for interac‐
5690                      tive shells.
5691
5692              extdebug
5693                      If set at shell invocation, or in a shell startup  file,
5694                      arrange to execute the debugger profile before the shell
5695                      starts, identical to the --debugger option.  If set  af‐
5696                      ter  invocation,  behavior intended for use by debuggers
5697                      is enabled:
5698
5699                      1.     The -F option to the declare builtin displays the
5700                             source file name and line number corresponding to
5701                             each function name supplied as an argument.
5702
5703                      2.     If the command run by the DEBUG  trap  returns  a
5704                             non-zero  value,  the next command is skipped and
5705                             not executed.
5706
5707                      3.     If the command run by the DEBUG  trap  returns  a
5708                             value  of 2, and the shell is executing in a sub‐
5709                             routine (a shell function or a shell script  exe‐
5710                             cuted  by  the  .  or source builtins), the shell
5711                             simulates a call to return.
5712
5713                      4.     BASH_ARGC and BASH_ARGV are updated as  described
5714                             in their descriptions above.
5715
5716                      5.     Function  tracing  is  enabled: command substitu‐
5717                             tion, shell functions, and subshells invoked with
5718                             ( command ) inherit the DEBUG and RETURN traps.
5719
5720                      6.     Error  tracing  is enabled: command substitution,
5721                             shell functions, and  subshells  invoked  with  (
5722                             command ) inherit the ERR trap.
5723
5724              extglob If set, the extended pattern matching features described
5725                      above under Pathname Expansion are enabled.
5726
5727              extquote
5728                      If set, $'string' and  $"string"  quoting  is  performed
5729                      within   ${parameter}   expansions  enclosed  in  double
5730                      quotes.  This option is enabled by default.
5731
5732              failglob
5733                      If set, patterns which fail to  match  filenames  during
5734                      pathname expansion result in an expansion error.
5735
5736              force_fignore
5737                      If  set,  the  suffixes  specified  by the FIGNORE shell
5738                      variable cause words to be ignored when performing  word
5739                      completion even if the ignored words are the only possi‐
5740                      ble completions.  See SHELL VARIABLES above  for  a  de‐
5741                      scription  of  FIGNORE.   This  option is enabled by de‐
5742                      fault.
5743
5744              globasciiranges
5745                      If set,  range  expressions  used  in  pattern  matching
5746                      bracket  expressions (see Pattern Matching above) behave
5747                      as if in the traditional C locale when  performing  com‐
5748                      parisons.   That  is, the current locale's collating se‐
5749                      quence is not taken into account, so b will not  collate
5750                      between  A  and  B,  and upper-case and lower-case ASCII
5751                      characters will collate together.
5752
5753              globstar
5754                      If set, the pattern ** used in a pathname expansion con‐
5755                      text  will  match all files and zero or more directories
5756                      and subdirectories.  If the pattern is followed by a  /,
5757                      only directories and subdirectories match.
5758
5759              gnu_errfmt
5760                      If set, shell error messages are written in the standard
5761                      GNU error message format.
5762
5763              histappend
5764                      If set, the history list is appended to the  file  named
5765                      by the value of the HISTFILE variable when the shell ex‐
5766                      its, rather than overwriting the file.
5767
5768              histreedit
5769                      If set, and readline is being used, a user is given  the
5770                      opportunity to re-edit a failed history substitution.
5771
5772              histverify
5773                      If  set, and readline is being used, the results of his‐
5774                      tory substitution are  not  immediately  passed  to  the
5775                      shell  parser.   Instead,  the  resulting line is loaded
5776                      into the readline editing buffer, allowing further modi‐
5777                      fication.
5778
5779              hostcomplete
5780                      If set, and readline is being used, bash will attempt to
5781                      perform hostname completion when a word containing  a  @
5782                      is   being  completed  (see  Completing  under  READLINE
5783                      above).  This is enabled by default.
5784
5785              huponexit
5786                      If set, bash will send SIGHUP to all jobs when an inter‐
5787                      active login shell exits.
5788
5789              inherit_errexit
5790                      If  set,  command substitution inherits the value of the
5791                      errexit option, instead of unsetting it in the  subshell
5792                      environment.   This option is enabled when posix mode is
5793                      enabled.
5794
5795              interactive_comments
5796                      If set, allow a word beginning with # to cause that word
5797                      and  all remaining characters on that line to be ignored
5798                      in an interactive shell (see COMMENTS above).  This  op‐
5799                      tion is enabled by default.
5800
5801              lastpipe
5802                      If  set,  and  job control is not active, the shell runs
5803                      the last command of a pipeline not executed in the back‐
5804                      ground in the current shell environment.
5805
5806              lithist If  set,  and  the cmdhist option is enabled, multi-line
5807                      commands are saved to the history with embedded newlines
5808                      rather than using semicolon separators where possible.
5809
5810              localvar_inherit
5811                      If set, local variables inherit the value and attributes
5812                      of a variable of the same name that exists at a previous
5813                      scope before any new value is assigned.  The nameref at‐
5814                      tribute is not inherited.
5815
5816              localvar_unset
5817                      If set, calling unset on  local  variables  in  previous
5818                      function  scopes  marks  them so subsequent lookups find
5819                      them unset until that function returns. This is  identi‐
5820                      cal  to the behavior of unsetting local variables at the
5821                      current function scope.
5822
5823              login_shell
5824                      The shell sets this option if it is started as  a  login
5825                      shell  (see  INVOCATION  above).   The  value may not be
5826                      changed.
5827
5828              mailwarn
5829                      If set, and a file that bash is checking  for  mail  has
5830                      been  accessed  since  the last time it was checked, the
5831                      message ``The mail in mailfile has been read''  is  dis‐
5832                      played.
5833
5834              no_empty_cmd_completion
5835                      If  set,  and  readline is being used, bash will not at‐
5836                      tempt to search the PATH for possible  completions  when
5837                      completion is attempted on an empty line.
5838
5839              nocaseglob
5840                      If  set,  bash  matches  filenames in a case-insensitive
5841                      fashion when performing pathname expansion (see Pathname
5842                      Expansion above).
5843
5844              nocasematch
5845                      If  set,  bash  matches  patterns  in a case-insensitive
5846                      fashion when performing matching while executing case or
5847                      [[ conditional commands, when performing pattern substi‐
5848                      tution word expansions, or when filtering possible  com‐
5849                      pletions as part of programmable completion.
5850
5851              nullglob
5852                      If  set,  bash allows patterns which match no files (see
5853                      Pathname Expansion above) to expand to  a  null  string,
5854                      rather than themselves.
5855
5856              progcomp
5857                      If set, the programmable completion facilities (see Pro‐
5858                      grammable Completion above) are enabled.  This option is
5859                      enabled by default.
5860
5861              progcomp_alias
5862                      If  set,  and  programmable  completion is enabled, bash
5863                      treats a command name that doesn't have any  completions
5864                      as  a possible alias and attempts alias expansion. If it
5865                      has an alias, bash attempts programmable completion  us‐
5866                      ing the command word resulting from the expanded alias.
5867
5868              promptvars
5869                      If set, prompt strings undergo parameter expansion, com‐
5870                      mand substitution, arithmetic expansion, and  quote  re‐
5871                      moval  after  being  expanded  as described in PROMPTING
5872                      above.  This option is enabled by default.
5873
5874              restricted_shell
5875                      The shell sets this option  if  it  is  started  in  re‐
5876                      stricted  mode  (see RESTRICTED SHELL below).  The value
5877                      may not be changed.  This is not reset when the  startup
5878                      files  are  executed, allowing the startup files to dis‐
5879                      cover whether or not a shell is restricted.
5880
5881              shift_verbose
5882                      If set, the shift builtin prints an error  message  when
5883                      the shift count exceeds the number of positional parame‐
5884                      ters.
5885
5886              sourcepath
5887                      If set, the source (.) builtin uses the value of PATH to
5888                      find  the  directory  containing the file supplied as an
5889                      argument.  This option is enabled by default.
5890
5891              xpg_echo
5892                      If set, the echo builtin  expands  backslash-escape  se‐
5893                      quences by default.
5894
5895       suspend [-f]
5896              Suspend  the execution of this shell until it receives a SIGCONT
5897              signal.  A login shell cannot be suspended; the -f option can be
5898              used to override this and force the suspension.  The return sta‐
5899              tus is 0 unless the shell is a login shell and -f  is  not  sup‐
5900              plied, or if job control is not enabled.
5901
5902       test expr
5903       [ expr ]
5904              Return a status of 0 (true) or 1 (false) depending on the evalu‐
5905              ation of the conditional expression expr.  Each operator and op‐
5906              erand  must be a separate argument.  Expressions are composed of
5907              the primaries described  above  under  CONDITIONAL  EXPRESSIONS.
5908              test  does not accept any options, nor does it accept and ignore
5909              an argument of -- as signifying the end of options.
5910
5911              Expressions may  be  combined  using  the  following  operators,
5912              listed  in  decreasing  order of precedence.  The evaluation de‐
5913              pends on the number of arguments; see  below.   Operator  prece‐
5914              dence is used when there are five or more arguments.
5915              ! expr True if expr is false.
5916              ( expr )
5917                     Returns  the value of expr.  This may be used to override
5918                     the normal precedence of operators.
5919              expr1 -a expr2
5920                     True if both expr1 and expr2 are true.
5921              expr1 -o expr2
5922                     True if either expr1 or expr2 is true.
5923
5924              test and [ evaluate conditional expressions using a set of rules
5925              based on the number of arguments.
5926
5927              0 arguments
5928                     The expression is false.
5929              1 argument
5930                     The expression is true if and only if the argument is not
5931                     null.
5932              2 arguments
5933                     If the first argument is !, the expression is true if and
5934                     only  if the second argument is null.  If the first argu‐
5935                     ment is one of the  unary  conditional  operators  listed
5936                     above  under  CONDITIONAL  EXPRESSIONS, the expression is
5937                     true if the unary test is true.  If the first argument is
5938                     not a valid unary conditional operator, the expression is
5939                     false.
5940              3 arguments
5941                     The following conditions are applied in the order listed.
5942                     If  the  second argument is one of the binary conditional
5943                     operators listed above under CONDITIONAL EXPRESSIONS, the
5944                     result of the expression is the result of the binary test
5945                     using the first and third arguments as operands.  The  -a
5946                     and  -o  operators  are  considered binary operators when
5947                     there are three arguments.  If the first argument  is  !,
5948                     the  value is the negation of the two-argument test using
5949                     the second and third arguments.  If the first argument is
5950                     exactly ( and the third argument is exactly ), the result
5951                     is the one-argument test of the second argument.   Other‐
5952                     wise, the expression is false.
5953              4 arguments
5954                     If the first argument is !, the result is the negation of
5955                     the three-argument expression composed of  the  remaining
5956                     arguments.  Otherwise, the expression is parsed and eval‐
5957                     uated according to  precedence  using  the  rules  listed
5958                     above.
5959              5 or more arguments
5960                     The  expression  is  parsed  and  evaluated  according to
5961                     precedence using the rules listed above.
5962
5963              When used with test or [, the < and  >  operators  sort  lexico‐
5964              graphically using ASCII ordering.
5965
5966       times  Print  the  accumulated  user and system times for the shell and
5967              for processes run from the shell.  The return status is 0.
5968
5969       trap [-lp] [[arg] sigspec ...]
5970              The command arg is to be read and executed when  the  shell  re‐
5971              ceives signal(s) sigspec.  If arg is absent (and there is a sin‐
5972              gle sigspec) or -, each specified signal is reset to its  origi‐
5973              nal  disposition  (the value it had upon entrance to the shell).
5974              If arg is the null string the signal specified by  each  sigspec
5975              is  ignored by the shell and by the commands it invokes.  If arg
5976              is not present and -p has been supplied, then the trap  commands
5977              associated with each sigspec are displayed.  If no arguments are
5978              supplied or if only -p is given, trap prints the  list  of  com‐
5979              mands  associated  with  each  signal.  The -l option causes the
5980              shell to print a list of signal names  and  their  corresponding
5981              numbers.   Each sigspec is either a signal name defined in <sig‐
5982              nal.h>, or a signal number.  Signal names are  case  insensitive
5983              and the SIG prefix is optional.
5984
5985              If  a  sigspec  is  EXIT (0) the command arg is executed on exit
5986              from the shell.  If a sigspec is DEBUG, the command arg is  exe‐
5987              cuted  before  every  simple command, for command, case command,
5988              select command, every arithmetic for  command,  and  before  the
5989              first  command  executes  in a shell function (see SHELL GRAMMAR
5990              above).  Refer to the description of the extdebug option to  the
5991              shopt builtin for details of its effect on the DEBUG trap.  If a
5992              sigspec is RETURN, the command arg is executed each time a shell
5993              function or a script executed with the . or source builtins fin‐
5994              ishes executing.
5995
5996              If a sigspec is ERR, the command  arg  is  executed  whenever  a
5997              pipeline (which may consist of a single simple command), a list,
5998              or a compound command returns a non-zero exit status, subject to
5999              the  following  conditions.  The ERR trap is not executed if the
6000              failed command is part of the command list immediately following
6001              a  while  or until keyword, part of the test in an if statement,
6002              part of a command executed in a && or || list except the command
6003              following  the final && or ||, any command in a pipeline but the
6004              last, or if the command's return value is being  inverted  using
6005              !.  These are the same conditions obeyed by the errexit (-e) op‐
6006              tion.
6007
6008              Signals ignored upon entry to the shell cannot be trapped, reset
6009              or listed.  Trapped signals that are not being ignored are reset
6010              to their original values in a subshell or  subshell  environment
6011              when  one is created.  The return status is false if any sigspec
6012              is invalid; otherwise trap returns true.
6013
6014       type [-aftpP] name [name ...]
6015              With no options, indicate how each name would be interpreted  if
6016              used as a command name.  If the -t option is used, type prints a
6017              string which is one of alias,  keyword,  function,  builtin,  or
6018              file  if  name  is  an  alias,  shell  reserved  word, function,
6019              builtin, or disk file, respectively.  If the name is not  found,
6020              then  nothing  is  printed,  and  an exit status of false is re‐
6021              turned.  If the -p option is used, type either returns the  name
6022              of  the  disk file that would be executed if name were specified
6023              as a command name, or nothing if ``type -t name'' would not  re‐
6024              turn  file.   The  -P option forces a PATH search for each name,
6025              even if ``type -t name'' would not return file.  If a command is
6026              hashed, -p and -P print the hashed value, which is not necessar‐
6027              ily the file that appears first in PATH.  If the  -a  option  is
6028              used,  type  prints all of the places that contain an executable
6029              named name.  This includes aliases and functions, if and only if
6030              the -p option is not also used.  The table of hashed commands is
6031              not consulted when using -a.  The  -f  option  suppresses  shell
6032              function lookup, as with the command builtin.  type returns true
6033              if all of the arguments are found, false if any are not found.
6034
6035       ulimit [-HS] -a
6036       ulimit [-HS] [-bcdefiklmnpqrstuvxPRT [limit]]
6037              Provides control over the resources available to the  shell  and
6038              to  processes started by it, on systems that allow such control.
6039              The -H and -S options specify that the hard or soft limit is set
6040              for  the  given resource.  A hard limit cannot be increased by a
6041              non-root user once it is set; a soft limit may be  increased  up
6042              to  the value of the hard limit.  If neither -H nor -S is speci‐
6043              fied, both the soft and hard limits are set.  The value of limit
6044              can be a number in the unit specified for the resource or one of
6045              the special values hard, soft, or unlimited, which stand for the
6046              current  hard  limit,  the current soft limit, and no limit, re‐
6047              spectively.  If limit is omitted, the current value of the  soft
6048              limit of the resource is printed, unless the -H option is given.
6049              When more than one resource is specified,  the  limit  name  and
6050              unit,  if  appropriate, are printed before the value.  Other op‐
6051              tions are interpreted as follows:
6052              -a     All current limits are reported; no limits are set
6053              -b     The maximum socket buffer size
6054              -c     The maximum size of core files created
6055              -d     The maximum size of a process's data segment
6056              -e     The maximum scheduling priority ("nice")
6057              -f     The maximum size of files written by the  shell  and  its
6058                     children
6059              -i     The maximum number of pending signals
6060              -k     The maximum number of kqueues that may be allocated
6061              -l     The maximum size that may be locked into memory
6062              -m     The  maximum resident set size (many systems do not honor
6063                     this limit)
6064              -n     The maximum number of open file descriptors (most systems
6065                     do not allow this value to be set)
6066              -p     The pipe size in 512-byte blocks (this may not be set)
6067              -q     The maximum number of bytes in POSIX message queues
6068              -r     The maximum real-time scheduling priority
6069              -s     The maximum stack size
6070              -t     The maximum amount of cpu time in seconds
6071              -u     The  maximum  number  of  processes available to a single
6072                     user
6073              -v     The maximum amount of virtual  memory  available  to  the
6074                     shell and, on some systems, to its children
6075              -x     The maximum number of file locks
6076              -P     The maximum number of pseudoterminals
6077              -R     The  maximum  time  a  real-time  process  can run before
6078                     blocking, in microseconds
6079              -T     The maximum number of threads
6080
6081              If limit is given, and the -a option is not used, limit  is  the
6082              new  value  of  the  specified resource.  If no option is given,
6083              then -f is assumed.  Values are in 1024-byte increments,  except
6084              for  -t,  which is in seconds; -R, which is in microseconds; -p,
6085              which is in units of 512-byte blocks; -P, -T, -b,  -k,  -n,  and
6086              -u,  which  are unscaled values; and, when in posix mode, -c and
6087              -f, which are in 512-byte increments.  The return  status  is  0
6088              unless  an  invalid  option or argument is supplied, or an error
6089              occurs while setting a new limit.  In POSIX Mode 512-byte blocks
6090              are used for the `-c' and `-f' options.
6091
6092       umask [-p] [-S] [mode]
6093              The user file-creation mask is set to mode.  If mode begins with
6094              a digit, it is interpreted as an octal number; otherwise  it  is
6095              interpreted  as a symbolic mode mask similar to that accepted by
6096              chmod(1).  If mode is omitted, the current value of the mask  is
6097              printed.   The  -S  option causes the mask to be printed in sym‐
6098              bolic form; the default output is an octal number.   If  the  -p
6099              option is supplied, and mode is omitted, the output is in a form
6100              that may be reused as input.  The return status is 0 if the mode
6101              was  successfully  changed  or if no mode argument was supplied,
6102              and false otherwise.
6103
6104       unalias [-a] [name ...]
6105              Remove each name from the list of defined  aliases.   If  -a  is
6106              supplied,  all  alias definitions are removed.  The return value
6107              is true unless a supplied name is not a defined alias.
6108
6109       unset [-fv] [-n] [name ...]
6110              For each name, remove the corresponding  variable  or  function.
6111              If the -v option is given, each name refers to a shell variable,
6112              and that variable is removed.  Read-only variables  may  not  be
6113              unset.   If  -f  is specified, each name refers to a shell func‐
6114              tion, and the function definition is removed.  If the -n  option
6115              is  supplied, and name is a variable with the nameref attribute,
6116              name will be unset rather than the variable it  references.   -n
6117              has  no  effect if the -f option is supplied.  If no options are
6118              supplied, each name refers to a variable; if there is  no  vari‐
6119              able  by that name, a function with that name, if any, is unset.
6120              Each unset variable or function is removed from the  environment
6121              passed   to   subsequent  commands.   If  any  of  BASH_ALIASES,
6122              BASH_ARGV0,  BASH_CMDS,  BASH_COMMAND,  BASH_SUBSHELL,  BASHPID,
6123              COMP_WORDBREAKS,  DIRSTACK,  EPOCHREALTIME,  EPOCHSECONDS, FUNC‐
6124              NAME, GROUPS, HISTCMD, LINENO, RANDOM, SECONDS, or  SRANDOM  are
6125              unset, they lose their special properties, even if they are sub‐
6126              sequently reset.  The exit status is true unless a name is read‐
6127              only.
6128
6129       wait [-fn] [-p varname] [id ...]
6130              Wait for each specified child process and return its termination
6131              status.  Each id may be a process ID or a job specification;  if
6132              a  job  spec  is given, all processes in that job's pipeline are
6133              waited for.  If id is not given,  wait  waits  for  all  running
6134              background  jobs  and the last-executed process substitution, if
6135              its process id is the same as $!, and the return status is zero.
6136              If  the  -n option is supplied, wait waits for a single job from
6137              the list of ids or, if no ids are supplied, any job, to complete
6138              and  returns its exit status.  If none of the supplied arguments
6139              is a child of the shell, or if no arguments are supplied and the
6140              shell  has no unwaited-for children, the exit status is 127.  If
6141              the -p option is supplied, the process or job identifier of  the
6142              job  for  which  the  exit status is returned is assigned to the
6143              variable varname named by the  option  argument.   The  variable
6144              will  be unset initially, before any assignment.  This is useful
6145              only when the -n option is supplied.  Supplying the  -f  option,
6146              when  job control is enabled, forces wait to wait for id to ter‐
6147              minate before returning its status, instead of returning when it
6148              changes  status.  If id specifies a non-existent process or job,
6149              the return status is 127.  Otherwise, the return status  is  the
6150              exit status of the last process or job waited for.
6151

SHELL COMPATIBILITY MODE

6153       Bash-4.0 introduced the concept of a `shell compatibility level', spec‐
6154       ified as a set of options to the shopt builtin compat31, compat32, com‐
6155       pat40,  compat41,  and so on).  There is only one current compatibility
6156       level -- each option is mutually exclusive.  The compatibility level is
6157       intended  to allow users to select behavior from previous versions that
6158       is incompatible with newer versions while they migrate scripts  to  use
6159       current  features  and  behavior. It's intended to be a temporary solu‐
6160       tion.
6161
6162       This section does not mention behavior that is standard for a  particu‐
6163       lar  version  (e.g., setting compat32 means that quoting the rhs of the
6164       regexp matching operator quotes special regexp characters in the  word,
6165       which is default behavior in bash-3.2 and above).
6166
6167       If  a  user enables, say, compat32, it may affect the behavior of other
6168       compatibility levels up to  and  including  the  current  compatibility
6169       level.   The  idea  is  that each compatibility level controls behavior
6170       that changed in that version of bash, but that behavior may  have  been
6171       present  in  earlier versions.  For instance, the change to use locale-
6172       based comparisons with the [[ command came  in  bash-4.1,  and  earlier
6173       versions used ASCII-based comparisons, so enabling compat32 will enable
6174       ASCII-based comparisons as well.  That granularity may  not  be  suffi‐
6175       cient  for  all uses, and as a result users should employ compatibility
6176       levels carefully.  Read the documentation for a particular  feature  to
6177       find out the current behavior.
6178
6179       Bash-4.3  introduced  a new shell variable: BASH_COMPAT.  The value as‐
6180       signed to this variable (a decimal version number like 4.2, or an inte‐
6181       ger  corresponding to the compatNN option, like 42) determines the com‐
6182       patibility level.
6183
6184       Starting with bash-4.4, Bash has begun deprecating older  compatibility
6185       levels.   Eventually, the options will be removed in favor of BASH_COM‐
6186       PAT.
6187
6188       Bash-5.0 is the final version for which there  will  be  an  individual
6189       shopt  option for the previous version. Users should use BASH_COMPAT on
6190       bash-5.0 and later versions.
6191
6192       The following table describes the behavior changes controlled  by  each
6193       compatibility level setting.  The compatNN tag is used as shorthand for
6194       setting the compatibility level to NN using one of the following mecha‐
6195       nisms.   For versions prior to bash-5.0, the compatibility level may be
6196       set using the corresponding compatNN shopt option.   For  bash-4.3  and
6197       later  versions,  the  BASH_COMPAT variable is preferred, and it is re‐
6198       quired for bash-5.1 and later versions.
6199
6200       compat31
6201              •      quoting the rhs of the [[ command's regexp matching oper‐
6202                     ator (=~) has no special effect
6203
6204       compat32
6205              •      interrupting  a  command  list such as "a ; b ; c" causes
6206                     the execution  of  the  next  command  in  the  list  (in
6207                     bash-4.0  and later versions, the shell acts as if it re‐
6208                     ceived the interrupt, so interrupting one  command  in  a
6209                     list aborts the execution of the entire list)
6210
6211       compat40
6212              •      the  <  and > operators to the [[ command do not consider
6213                     the current locale when comparing strings; they use ASCII
6214                     ordering.  Bash versions prior to bash-4.1 use ASCII col‐
6215                     lation and strcmp(3); bash-4.1 and later use the  current
6216                     locale's collation sequence and strcoll(3).
6217
6218       compat41
6219              •      in  posix mode, time may be followed by options and still
6220                     be recognized as a reserved word (this is POSIX interpre‐
6221                     tation 267)
6222              •      in posix mode, the parser requires that an even number of
6223                     single quotes occur in the  word  portion  of  a  double-
6224                     quoted  parameter expansion and treats them specially, so
6225                     that characters within the single quotes  are  considered
6226                     quoted (this is POSIX interpretation 221)
6227
6228       compat42
6229              •      the replacement string in double-quoted pattern substitu‐
6230                     tion does not undergo quote removal, as it does  in  ver‐
6231                     sions after bash-4.2
6232              •      in  posix mode, single quotes are considered special when
6233                     expanding the word portion of a  double-quoted  parameter
6234                     expansion  and  can  be  used to quote a closing brace or
6235                     other special character (this is part of POSIX  interpre‐
6236                     tation  221);  in  later  versions, single quotes are not
6237                     special within double-quoted word expansions
6238
6239       compat43
6240              •      the shell does not print a warning message if an  attempt
6241                     is  made  to use a quoted compound assignment as an argu‐
6242                     ment to declare (declare -a foo='(1 2)'). Later  versions
6243                     warn that this usage is deprecated
6244              •      word  expansion  errors  are  considered non-fatal errors
6245                     that cause the current command to  fail,  even  in  posix
6246                     mode  (the  default behavior is to make them fatal errors
6247                     that cause the shell to exit)
6248              •      when  executing  a  shell  function,   the   loop   state
6249                     (while/until/etc.)  is not reset, so break or continue in
6250                     that function will break or continue loops in the calling
6251                     context.  Bash-4.4 and later reset the loop state to pre‐
6252                     vent this
6253
6254       compat44
6255              •      the shell sets  up  the  values  used  by  BASH_ARGV  and
6256                     BASH_ARGC  so  they  can expand to the shell's positional
6257                     parameters even if extended debugging mode is not enabled
6258              •      a subshell inherits loops from  its  parent  context,  so
6259                     break  or  continue  will  cause  the  subshell  to exit.
6260                     Bash-5.0 and later reset the loop state  to  prevent  the
6261                     exit
6262              •      variable  assignments  preceding builtins like export and
6263                     readonly that set attributes continue to affect variables
6264                     with the same name in the calling environment even if the
6265                     shell is not in posix mode
6266
6267       compat50
6268              •      Bash-5.1 changed the way $RANDOM is generated  to  intro‐
6269                     duce slightly more randomness. If the shell compatibility
6270                     level is set to 50 or lower, it  reverts  to  the  method
6271                     from  bash-5.0 and previous versions, so seeding the ran‐
6272                     dom number generator by assigning a value to RANDOM  will
6273                     produce the same sequence as in bash-5.0
6274              •      If  the  command hash table is empty, bash versions prior
6275                     to bash-5.1 printed an informational message to that  ef‐
6276                     fect,  even  when  producing output that can be reused as
6277                     input. Bash-5.1 suppresses that message when the  -l  op‐
6278                     tion is supplied.
6279

RESTRICTED SHELL

6281       If bash is started with the name rbash, or the -r option is supplied at
6282       invocation, the shell becomes restricted.  A restricted shell  is  used
6283       to  set  up an environment more controlled than the standard shell.  It
6284       behaves identically to bash with the exception that the  following  are
6285       disallowed or not performed:
6286
6287       •      changing directories with cd
6288
6289       •      setting  or  unsetting the values of SHELL, PATH, HISTFILE, ENV,
6290              or BASH_ENV
6291
6292       •      specifying command names containing /
6293
6294       •      specifying a filename containing a / as an  argument  to  the  .
6295              builtin command
6296
6297       •      specifying  a  filename containing a slash as an argument to the
6298              history builtin command
6299
6300       •      specifying a filename containing a slash as an argument  to  the
6301              -p option to the hash builtin command
6302
6303       •      importing  function  definitions  from  the shell environment at
6304              startup
6305
6306       •      parsing the value of SHELLOPTS from  the  shell  environment  at
6307              startup
6308
6309       •      redirecting output using the >, >|, <>, >&, &>, and >> redirect‐
6310              ion operators
6311
6312       •      using the exec builtin command to replace the shell with another
6313              command
6314
6315       •      adding  or  deleting builtin commands with the -f and -d options
6316              to the enable builtin command
6317
6318       •      using the  enable  builtin  command  to  enable  disabled  shell
6319              builtins
6320
6321       •      specifying the -p option to the command builtin command
6322
6323       •      turning off restricted mode with set +r or set +o restricted.
6324
6325       These restrictions are enforced after any startup files are read.
6326
6327       When a command that is found to be a shell script is executed (see COM‐
6328       MAND EXECUTION above), rbash turns off any restrictions  in  the  shell
6329       spawned to execute the script.
6330

SEE ALSO

6332       Bash Reference Manual, Brian Fox and Chet Ramey
6333       The Gnu Readline Library, Brian Fox and Chet Ramey
6334       The Gnu History Library, Brian Fox and Chet Ramey
6335       Portable  Operating  System  Interface (POSIX) Part 2: Shell and Utili‐
6336       ties, IEEE --
6337              http://pubs.opengroup.org/onlinepubs/9699919799/
6338       http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode
6339       sh(1), ksh(1), csh(1)
6340       emacs(1), vi(1)
6341       readline(3)
6342

FILES

6344       /bin/bash
6345              The bash executable
6346       /etc/profile
6347              The systemwide initialization file, executed for login shells
6348       /etc/bash.bash_logout
6349              The systemwide login shell cleanup file, executed when  a  login
6350              shell exits
6351       ~/.bash_profile
6352              The personal initialization file, executed for login shells
6353       ~/.bashrc
6354              The individual per-interactive-shell startup file
6355       ~/.bash_logout
6356              The  individual  login shell cleanup file, executed when a login
6357              shell exits
6358       ~/.inputrc
6359              Individual readline initialization file
6360

AUTHORS

6362       Brian Fox, Free Software Foundation
6363       bfox@gnu.org
6364
6365       Chet Ramey, Case Western Reserve University
6366       chet.ramey@case.edu
6367

BUG REPORTS

6369       If you find a bug in bash, you should report it.  But first, you should
6370       make  sure  that  it really is a bug, and that it appears in the latest
6371       version  of  bash.   The  latest  version  is  always  available   from
6372       ftp://ftp.gnu.org/pub/gnu/bash/.
6373
6374       Once  you  have  determined that a bug actually exists, use the bashbug
6375       command to submit a bug report.  If you have a fix, you are  encouraged
6376       to  mail that as well!  Suggestions and `philosophical' bug reports may
6377       be mailed  to  bug-bash@gnu.org  or  posted  to  the  Usenet  newsgroup
6378       gnu.bash.bug.
6379
6380       ALL bug reports should include:
6381
6382       The version number of bash
6383       The hardware and operating system
6384       The compiler used to compile
6385       A description of the bug behaviour
6386       A short script or `recipe' which exercises the bug
6387
6388       bashbug  inserts  the first three items automatically into the template
6389       it provides for filing a bug report.
6390
6391       Comments and bug reports concerning this manual page should be directed
6392       to chet.ramey@case.edu.
6393

BUGS

6395       It's too big and too slow.
6396
6397       There are some subtle differences between bash and traditional versions
6398       of sh, mostly because of the POSIX specification.
6399
6400       Aliases are confusing in some uses.
6401
6402       Shell builtin commands and functions are not stoppable/restartable.
6403
6404       Compound commands and command sequences of the form `a ; b ; c' are not
6405       handled  gracefully  when  process  suspension  is  attempted.   When a
6406       process is stopped, the shell immediately executes the next command  in
6407       the  sequence.   It  suffices to place the sequence of commands between
6408       parentheses to force it into a subshell, which  may  be  stopped  as  a
6409       unit.
6410
6411       Array variables may not (yet) be exported.
6412
6413       There may be only one active coprocess at a time.
6414
6415
6416
6417GNU Bash 5.1                    2020 October 29                        BASH(1)
Impressum