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-2016 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 can be used as options  when  the  shell  is
26       invoked.  In addition, bash interprets the following options when it is
27       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
32                 assigned  to  $0  and any remaining arguments are assigned to
33                 the positional parameters.  The assignment  to  $0  sets  the
34                 name  of  the  shell, which is used in warning and error mes‐
35                 sages.
36       -i        If the -i option is present, the shell is interactive.
37       -l        Make bash act as if it had been invoked as a login shell (see
38                 INVOCATION below).
39       -r        If  the  -r  option  is present, the shell becomes restricted
40                 (see RESTRICTED SHELL below).
41       -s        If the -s option is present, or if no arguments remain  after
42                 option  processing,  then commands are read from the standard
43                 input.  This option allows the positional  parameters  to  be
44                 set when invoking an interactive shell.
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
63       options must appear on the command  line  before  the  single-character
64       options 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
81              INVOCATION 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
95              below).
96
97       --norc Do  not  read  and  execute  the  personal  initialization  file
98              ~/.bashrc  if  the  shell  is interactive.  This option is on by
99              default 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
132       executed,  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
141       (unless -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
172       example, 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
181       behavior  of  historical  versions  of sh as closely as possible, while
182       conforming to the POSIX standard as well.  When invoked as an  interac‐
183       tive  login  shell, or a non-interactive shell with the --login option,
184       it first attempts to read and execute commands  from  /etc/profile  and
185       ~/.profile,  in  that  order.   The  --noprofile  option may be used to
186       inhibit 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
192       attempt to read any other startup files.   When  invoked  as  sh,  bash
193       enters 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
215       appear  in  the  environment, are ignored, and the effective user id is
216       set to the real user id.  If the -p option is supplied  at  invocation,
217       the  startup  behavior  is  the  same, but the effective user id is not
218       reset.
219

DEFINITIONS

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

RESERVED WORDS

239       Reserved words are words that have a special meaning to the shell.  The
240       following words are recognized as reserved when unquoted and either the
241       first word of a simple command (see SHELL GRAMMAR below) or  the  third
242       word of a case or for command:
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
253       arguments 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).
298
299   Lists
300       A  list  is a sequence of one or more pipelines separated by one of the
301       operators ;, &, &&, or ||, and optionally terminated by one of ;, &, or
302       <newline>.
303
304       Of these list operators, && and || have equal precedence, followed by ;
305       and &, which have equal precedence.
306
307       A sequence of one or more newlines may appear in a list  instead  of  a
308       semicolon to delimit commands.
309
310       If  a  command  is terminated by the control operator &, the shell exe‐
311       cutes the command in the background in a subshell.  The shell does  not
312       wait  for  the command to finish, and the return status is 0.  Commands
313       separated by a ; are executed sequentially; the shell  waits  for  each
314       command  to terminate in turn.  The return status is the exit status of
315       the last command executed.
316
317       AND and OR lists are sequences of one or more  pipelines  separated  by
318       the  &&  and  || control operators, respectively.  AND and OR lists are
319       executed with left associativity.  An AND list has the form
320
321              command1 && command2
322
323       command2 is executed if, and only if, command1 returns an  exit  status
324       of zero.
325
326       An OR list has the form
327
328              command1 || command2
329
330       command2  is  executed  if and only if command1 returns a non-zero exit
331       status.  The return status of AND and OR lists is the  exit  status  of
332       the last command executed in the list.
333
334   Compound Commands
335       A  compound command is one of the following.  In most cases a list in a
336       command's description may be separated from the rest of the command  by
337       one  or  more  newlines, and may be followed by a newline in place of a
338       semicolon.
339
340       (list) list is executed in a subshell environment (see  COMMAND  EXECU‐
341              TION  ENVIRONMENT below).  Variable assignments and builtin com‐
342              mands that affect the  shell's  environment  do  not  remain  in
343              effect  after  the  command completes.  The return status is the
344              exit status of list.
345
346       { list; }
347              list is simply executed in the current shell environment.   list
348              must  be  terminated with a newline or semicolon.  This is known
349              as a group command.  The return status is  the  exit  status  of
350              list.   Note that unlike the metacharacters ( and ), { and } are
351              reserved words and must occur where a reserved word is permitted
352              to  be  recognized.   Since they do not cause a word break, they
353              must be separated from  list  by  whitespace  or  another  shell
354              metacharacter.
355
356       ((expression))
357              The  expression  is  evaluated  according to the rules described
358              below under ARITHMETIC EVALUATION.  If the value of the  expres‐
359              sion  is  non-zero, the return status is 0; otherwise the return
360              status is 1.  This is exactly equivalent to let "expression".
361
362       [[ expression ]]
363              Return a status of 0 or 1 depending on  the  evaluation  of  the
364              conditional  expression expression.  Expressions are composed of
365              the primaries described  below  under  CONDITIONAL  EXPRESSIONS.
366              Word  splitting  and pathname expansion are not performed on the
367              words between the [[ and  ]];  tilde  expansion,  parameter  and
368              variable  expansion, arithmetic expansion, command substitution,
369              process substitution, and quote removal are  performed.   Condi‐
370              tional operators such as -f must be unquoted to be recognized as
371              primaries.
372
373              When used with [[, the < and > operators sort  lexicographically
374              using the current locale.
375
376              When  the  == and != operators are used, the string to the right
377              of the operator is considered a pattern and matched according to
378              the rules described below under Pattern Matching, as if the ext‐
379              glob shell option were enabled.  The = operator is equivalent to
380              ==.   If  the  nocasematch shell option is enabled, the match is
381              performed without regard to the case of  alphabetic  characters.
382              The  return  value  is  0 if the string matches (==) or does not
383              match (!=) the pattern, and 1 otherwise.  Any part of  the  pat‐
384              tern  may be quoted to force the quoted portion to be matched as
385              a string.
386
387              An additional binary operator, =~, is available, with  the  same
388              precedence  as  ==  and  !=.  When it is used, the string to the
389              right of the operator is considered an extended regular  expres‐
390              sion and matched accordingly (as in regex(3)).  The return value
391              is 0 if the string matches the pattern, and 1 otherwise.  If the
392              regular  expression  is syntactically incorrect, the conditional
393              expression's return value is 2.  If the nocasematch shell option
394              is enabled, the match is performed without regard to the case of
395              alphabetic characters.  Any part of the pattern may be quoted to
396              force  the  quoted  portion  to be matched as a string.  Bracket
397              expressions in regular expressions must  be  treated  carefully,
398              since  normal  quoting  characters  lose  their meanings between
399              brackets.  If the pattern is stored in a shell variable, quoting
400              the  variable  expansion forces the entire pattern to be matched
401              as a string.  Substrings matched by parenthesized subexpressions
402              within  the  regular  expression are saved in the array variable
403              BASH_REMATCH.  The element of BASH_REMATCH with index 0  is  the
404              portion  of  the  string matching the entire regular expression.
405              The element of BASH_REMATCH with index n is the portion  of  the
406              string matching the nth parenthesized subexpression.
407
408              Expressions  may  be  combined  using  the  following operators,
409              listed in decreasing order of precedence:
410
411              ( expression )
412                     Returns the value of expression.  This  may  be  used  to
413                     override the normal precedence of operators.
414              ! expression
415                     True if expression is false.
416              expression1 && expression2
417                     True if both expression1 and expression2 are true.
418              expression1 || expression2
419                     True if either expression1 or expression2 is true.
420
421              The && and || operators do not evaluate expression2 if the value
422              of expression1 is sufficient to determine the  return  value  of
423              the entire conditional expression.
424
425       for name [ [ in [ word ... ] ] ; ] do list ; done
426              The list of words following in is expanded, generating a list of
427              items.  The variable name is set to each element of this list in
428              turn,  and  list is executed each time.  If the in word is omit‐
429              ted, the for command executes  list  once  for  each  positional
430              parameter that is set (see PARAMETERS below).  The return status
431              is the exit status of the last command that  executes.   If  the
432              expansion of the items following in results in an empty list, no
433              commands are executed, and the return status is 0.
434
435       for (( expr1 ; expr2 ; expr3 )) ; do list ; done
436              First, the arithmetic expression expr1 is evaluated according to
437              the  rules  described  below  under  ARITHMETIC EVALUATION.  The
438              arithmetic expression expr2 is then evaluated  repeatedly  until
439              it  evaluates  to zero.  Each time expr2 evaluates to a non-zero
440              value, list is executed and the arithmetic expression  expr3  is
441              evaluated.   If  any  expression is omitted, it behaves as if it
442              evaluates to 1.  The return value is the exit status of the last
443              command in list that is executed, or false if any of the expres‐
444              sions is invalid.
445
446       select name [ in word ] ; do list ; done
447              The list of words following in is expanded, generating a list of
448              items.   The  set  of  expanded words is printed on the standard
449              error, each preceded by a number.  If the in  word  is  omitted,
450              the  positional  parameters  are printed (see PARAMETERS below).
451              The PS3 prompt is then displayed and a line read from the  stan‐
452              dard  input.   If the line consists of a number corresponding to
453              one of the displayed words, then the value of  name  is  set  to
454              that  word.  If the line is empty, the words and prompt are dis‐
455              played again.  If EOF is read, the command completes.  Any other
456              value  read  causes  name  to  be set to null.  The line read is
457              saved in the variable REPLY.  The list is  executed  after  each
458              selection until a break command is executed.  The exit status of
459              select is the exit status of the last command executed in  list,
460              or zero if no commands were executed.
461
462       case word in [ [(] pattern [ | pattern ] ... ) list ;; ] ... esac
463              A case command first expands word, and tries to match it against
464              each pattern in turn, using the same matching rules as for path‐
465              name  expansion  (see  Pathname  Expansion  below).  The word is
466              expanded using tilde expansion, parameter  and  variable  expan‐
467              sion,  arithmetic  expansion, command substitution, process sub‐
468              stitution and quote removal.  Each pattern examined is  expanded
469              using  tilde expansion, parameter and variable expansion, arith‐
470              metic expansion, command substitution, and process substitution.
471              If  the  nocasematch  shell option is enabled, the match is per‐
472              formed without regard to  the  case  of  alphabetic  characters.
473              When  a  match is found, the corresponding list is executed.  If
474              the ;; operator is used, no  subsequent  matches  are  attempted
475              after  the  first pattern match.  Using ;& in place of ;; causes
476              execution to continue with the list associated with the next set
477              of  patterns.  Using ;;& in place of ;; causes the shell to test
478              the next pattern list in the statement, if any, and execute  any
479              associated  list on a successful match.  The exit status is zero
480              if no pattern matches.  Otherwise, it is the exit status of  the
481              last command executed in list.
482
483       if list; then list; [ elif list; then list; ] ... [ else list; ] fi
484              The  if  list is executed.  If its exit status is zero, the then
485              list is executed.  Otherwise, each  elif  list  is  executed  in
486              turn,  and  if  its  exit status is zero, the corresponding then
487              list is executed and the command completes.  Otherwise, the else
488              list  is executed, if present.  The exit status is the exit sta‐
489              tus of the last command executed, or zero if no condition tested
490              true.
491
492       while list-1; do list-2; done
493       until list-1; do list-2; done
494              The  while command continuously executes the list list-2 as long
495              as the last command in the list list-1 returns an exit status of
496              zero.   The  until  command  is  identical to the while command,
497              except that the test is negated: list-2 is executed as  long  as
498              the  last command in list-1 returns a non-zero exit status.  The
499              exit status of the while and until commands is the  exit  status
500              of the last command executed in list-2, or zero if none was exe‐
501              cuted.
502
503   Coprocesses
504       A coprocess is a shell command preceded by the coproc reserved word.  A
505       coprocess  is  executed asynchronously in a subshell, as if the command
506       had been terminated with the & control operator, with  a  two-way  pipe
507       established between the executing shell and the coprocess.
508
509       The format for a coprocess is:
510
511              coproc [NAME] command [redirections]
512
513       This  creates  a  coprocess  named  NAME.  If NAME is not supplied, the
514       default name is COPROC.  NAME must not be supplied if command is a sim‐
515       ple command (see above); otherwise, it is interpreted as the first word
516       of the simple command.  When the coprocess is executed, the shell  cre‐
517       ates  an array variable (see Arrays below) named NAME in the context of
518       the executing shell.  The standard output of command is connected via a
519       pipe  to  a  file  descriptor  in  the  executing  shell, and that file
520       descriptor is assigned to NAME[0].  The standard input  of  command  is
521       connected  via  a pipe to a file descriptor in the executing shell, and
522       that file descriptor is assigned to NAME[1].  This pipe is  established
523       before  any  redirections  specified  by  the  command (see REDIRECTION
524       below).  The file descriptors can be utilized  as  arguments  to  shell
525       commands  and  redirections  using  standard word expansions.  The file
526       descriptors are not available in subshells.   The  process  ID  of  the
527       shell spawned to execute the coprocess is available as the value of the
528       variable NAME_PID.  The wait builtin command may be used  to  wait  for
529       the coprocess to terminate.
530
531       Since  the  coprocess is created as an asynchronous command, the coproc
532       command always returns success.  The return status of  a  coprocess  is
533       the exit status of command.
534
535   Shell Function Definitions
536       A  shell function is an object that is called like a simple command and
537       executes a compound command with a new set  of  positional  parameters.
538       Shell functions are declared as follows:
539
540       name () compound-command [redirection]
541       function name [()] compound-command [redirection]
542              This  defines a function named name.  The reserved word function
543              is optional.  If the function reserved  word  is  supplied,  the
544              parentheses  are optional.  The body of the function is the com‐
545              pound command compound-command (see  Compound  Commands  above).
546              That  command is usually a list of commands between { and }, but
547              may be any command listed under Compound  Commands  above,  with
548              one  exception:  If  the function reserved word is used, but the
549              parentheses are not supplied, the  braces  are  required.   com‐
550              pound-command is executed whenever name is specified as the name
551              of a simple command.  When in posix mode, name may  not  be  the
552              name  of  one  of  the POSIX special builtins.  Any redirections
553              (see REDIRECTION below) specified when a function is defined are
554              performed  when  the function is executed.  The exit status of a
555              function definition is zero unless a syntax error  occurs  or  a
556              readonly  function with the same name already exists.  When exe‐
557              cuted, the exit status of a function is the exit status  of  the
558              last command executed in the body.  (See FUNCTIONS below.)
559

COMMENTS

561       In a non-interactive shell, or an interactive shell in which the inter‐
562       active_comments option to the  shopt  builtin  is  enabled  (see  SHELL
563       BUILTIN  COMMANDS  below), a word beginning with # causes that word and
564       all remaining characters on that line to be  ignored.   An  interactive
565       shell  without  the  interactive_comments option enabled does not allow
566       comments.  The interactive_comments option is on by default in interac‐
567       tive shells.
568

QUOTING

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

PARAMETERS

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

EXPANSION

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

REDIRECTION

1980       Before  a  command  is executed, its input and output may be redirected
1981       using a special notation interpreted by the shell.  Redirection  allows
1982       commands'  file handles to be duplicated, opened, closed, made to refer
1983       to different files, and can change the files the command reads from and
1984       writes  to.  Redirection may also be used to modify file handles in the
1985       current shell execution environment.  The following redirection  opera‐
1986       tors may precede or appear anywhere within a simple command or may fol‐
1987       low a command.  Redirections are processed in the  order  they  appear,
1988       from left to right.
1989
1990       Each  redirection  that may be preceded by a file descriptor number may
1991       instead be preceded by a word of the form {varname}.  In this case, for
1992       each redirection operator except >&- and <&-, the shell will allocate a
1993       file descriptor greater than or equal to 10 and assign it  to  varname.
1994       If  >&-  or  <&- is preceded by {varname}, the value of varname defines
1995       the file descriptor to close.
1996
1997       In the following descriptions, if the file descriptor number  is  omit‐
1998       ted,  and the first character of the redirection operator is <, the re‐
1999       direction refers to the standard input (file  descriptor  0).   If  the
2000       first  character  of  the  redirection  operator  is >, the redirection
2001       refers to the standard output (file descriptor 1).
2002
2003       The word following the redirection operator in the  following  descrip‐
2004       tions,  unless  otherwise noted, is subjected to brace expansion, tilde
2005       expansion, parameter  and  variable  expansion,  command  substitution,
2006       arithmetic  expansion,  quote  removal,  pathname  expansion,  and word
2007       splitting.  If it expands to more than one word, bash reports an error.
2008
2009       Note that the order of redirections is significant.  For  example,  the
2010       command
2011
2012              ls > dirlist 2>&1
2013
2014       directs  both  standard  output and standard error to the file dirlist,
2015       while the command
2016
2017              ls 2>&1 > dirlist
2018
2019       directs only the standard output to file dirlist, because the  standard
2020       error  was duplicated from the standard output before the standard out‐
2021       put was redirected to dirlist.
2022
2023       Bash handles several filenames specially when they are used in redirec‐
2024       tions, as described in the following table.  If the operating system on
2025       which bash is running provides these special files, bash will use them;
2026       otherwise  it  will emulate them internally with the behavior described
2027       below.
2028
2029              /dev/fd/fd
2030                     If fd is a valid integer, file descriptor  fd  is  dupli‐
2031                     cated.
2032              /dev/stdin
2033                     File descriptor 0 is duplicated.
2034              /dev/stdout
2035                     File descriptor 1 is duplicated.
2036              /dev/stderr
2037                     File descriptor 2 is duplicated.
2038              /dev/tcp/host/port
2039                     If host is a valid hostname or Internet address, and port
2040                     is an integer port number or service name, bash  attempts
2041                     to open the corresponding TCP socket.
2042              /dev/udp/host/port
2043                     If host is a valid hostname or Internet address, and port
2044                     is an integer port number or service name, bash  attempts
2045                     to open the corresponding UDP socket.
2046
2047       A failure to open or create a file causes the redirection to fail.
2048
2049       Redirections  using file descriptors greater than 9 should be used with
2050       care, as they may conflict with file descriptors the shell uses  inter‐
2051       nally.
2052
2053   Redirecting Input
2054       Redirection of input causes the file whose name results from the expan‐
2055       sion of word to be opened for reading on  file  descriptor  n,  or  the
2056       standard input (file descriptor 0) if n is not specified.
2057
2058       The general format for redirecting input is:
2059
2060              [n]<word
2061
2062   Redirecting Output
2063       Redirection  of  output  causes  the  file  whose name results from the
2064       expansion of word to be opened for writing on file descriptor n, or the
2065       standard output (file descriptor 1) if n is not specified.  If the file
2066       does not exist it is created; if it does exist it is truncated to  zero
2067       size.
2068
2069       The general format for redirecting output is:
2070
2071              [n]>word
2072
2073       If  the  redirection operator is >, and the noclobber option to the set
2074       builtin has been enabled, the redirection will fail if the  file  whose
2075       name  results  from the expansion of word exists and is a regular file.
2076       If the redirection operator is >|, or the redirection operator is > and
2077       the noclobber option to the set builtin command is not enabled, the re‐
2078       direction is attempted even if the file named by word exists.
2079
2080   Appending Redirected Output
2081       Redirection of output in  this  fashion  causes  the  file  whose  name
2082       results  from  the expansion of word to be opened for appending on file
2083       descriptor n, or the standard output (file descriptor 1) if  n  is  not
2084       specified.  If the file does not exist it is created.
2085
2086       The general format for appending output is:
2087
2088              [n]>>word
2089
2090   Redirecting Standard Output and Standard Error
2091       This  construct allows both the standard output (file descriptor 1) and
2092       the standard error output (file descriptor 2) to be redirected  to  the
2093       file whose name is the expansion of word.
2094
2095       There  are  two  formats  for  redirecting standard output and standard
2096       error:
2097
2098              &>word
2099       and
2100              >&word
2101
2102       Of the two forms, the first is preferred.  This is semantically equiva‐
2103       lent to
2104
2105              >word 2>&1
2106
2107       When  using  the second form, word may not expand to a number or -.  If
2108       it does,  other  redirection  operators  apply  (see  Duplicating  File
2109       Descriptors below) for compatibility reasons.
2110
2111   Appending Standard Output and Standard Error
2112       This  construct allows both the standard output (file descriptor 1) and
2113       the standard error output (file descriptor 2) to  be  appended  to  the
2114       file whose name is the expansion of word.
2115
2116       The format for appending standard output and standard error is:
2117
2118              &>>word
2119
2120       This is semantically equivalent to
2121
2122              >>word 2>&1
2123
2124       (see Duplicating File Descriptors below).
2125
2126   Here Documents
2127       This  type  of  redirection  instructs the shell to read input from the
2128       current source until a line containing only delimiter (with no trailing
2129       blanks)  is seen.  All of the lines read up to that point are then used
2130       as the standard input (or file descriptor n if n is  specified)  for  a
2131       command.
2132
2133       The format of here-documents is:
2134
2135              [n]<<[-]word
2136                      here-document
2137              delimiter
2138
2139       No  parameter  and variable expansion, command substitution, arithmetic
2140       expansion, or pathname expansion is performed on word.  If any part  of
2141       word  is  quoted, the delimiter is the result of quote removal on word,
2142       and the lines in the  here-document  are  not  expanded.   If  word  is
2143       unquoted,  all  lines  of  the here-document are subjected to parameter
2144       expansion, command substitution, and arithmetic expansion, the  charac‐
2145       ter  sequence  \<newline>  is  ignored, and \ must be used to quote the
2146       characters \, $, and `.
2147
2148       If the redirection operator is <<-, then all leading tab characters are
2149       stripped  from  input  lines  and  the line containing delimiter.  This
2150       allows here-documents within shell scripts to be indented in a  natural
2151       fashion.
2152
2153   Here Strings
2154       A variant of here documents, the format is:
2155
2156              [n]<<<word
2157
2158       The  word  undergoes  brace  expansion,  tilde expansion, parameter and
2159       variable expansion, command  substitution,  arithmetic  expansion,  and
2160       quote  removal.   Pathname  expansion  and  word splitting are not per‐
2161       formed.  The result is supplied as a  single  string,  with  a  newline
2162       appended, to the command on its standard input (or file descriptor n if
2163       n is specified).
2164
2165   Duplicating File Descriptors
2166       The redirection operator
2167
2168              [n]<&word
2169
2170       is used to duplicate input file descriptors.  If word expands to one or
2171       more  digits,  the file descriptor denoted by n is made to be a copy of
2172       that file descriptor.  If the digits in word  do  not  specify  a  file
2173       descriptor  open for input, a redirection error occurs.  If word evalu‐
2174       ates to -, file descriptor n is closed.  If n  is  not  specified,  the
2175       standard input (file descriptor 0) is used.
2176
2177       The operator
2178
2179              [n]>&word
2180
2181       is  used  similarly  to duplicate output file descriptors.  If n is not
2182       specified, the standard output (file descriptor 1)  is  used.   If  the
2183       digits  in word do not specify a file descriptor open for output, a re‐
2184       direction error occurs.  If word evaluates to -, file descriptor  n  is
2185       closed.   As  a special case, if n is omitted, and word does not expand
2186       to one or more digits or -, the standard output and standard error  are
2187       redirected as described previously.
2188
2189   Moving File Descriptors
2190       The redirection operator
2191
2192              [n]<&digit-
2193
2194       moves  the  file descriptor digit to file descriptor n, or the standard
2195       input (file descriptor 0) if n is not specified.  digit is closed after
2196       being duplicated to n.
2197
2198       Similarly, the redirection operator
2199
2200              [n]>&digit-
2201
2202       moves  the  file descriptor digit to file descriptor n, or the standard
2203       output (file descriptor 1) if n is not specified.
2204
2205   Opening File Descriptors for Reading and Writing
2206       The redirection operator
2207
2208              [n]<>word
2209
2210       causes the file whose name is the expansion of word to  be  opened  for
2211       both  reading and writing on file descriptor n, or on file descriptor 0
2212       if n is not specified.  If the file does not exist, it is created.
2213

ALIASES

2215       Aliases allow a string to be substituted for a word when it is used  as
2216       the  first  word  of  a  simple command.  The shell maintains a list of
2217       aliases that may be set and unset with the alias  and  unalias  builtin
2218       commands  (see  SHELL  BUILTIN COMMANDS below).  The first word of each
2219       simple command, if unquoted, is checked to see if it has an alias.   If
2220       so,  that word is replaced by the text of the alias.  The characters /,
2221       $, `, and = and any of the shell metacharacters or  quoting  characters
2222       listed above may not appear in an alias name.  The replacement text may
2223       contain any valid shell input,  including  shell  metacharacters.   The
2224       first  word  of  the replacement text is tested for aliases, but a word
2225       that is identical to an alias being expanded is not expanded  a  second
2226       time.   This  means  that  one may alias ls to ls -F, for instance, and
2227       bash does not try to recursively expand the replacement text.   If  the
2228       last  character  of  the  alias value is a blank, then the next command
2229       word following the alias is also checked for alias expansion.
2230
2231       Aliases are created and listed with the alias command, and removed with
2232       the unalias command.
2233
2234       There  is no mechanism for using arguments in the replacement text.  If
2235       arguments are needed, a shell function should be  used  (see  FUNCTIONS
2236       below).
2237
2238       Aliases  are not expanded when the shell is not interactive, unless the
2239       expand_aliases shell option is set using shopt (see the description  of
2240       shopt under SHELL BUILTIN COMMANDS below).
2241
2242       The  rules  concerning  the  definition and use of aliases are somewhat
2243       confusing.  Bash always reads at  least  one  complete  line  of  input
2244       before  executing  any  of  the  commands  on  that  line.  Aliases are
2245       expanded when a command is read, not when it is  executed.   Therefore,
2246       an  alias definition appearing on the same line as another command does
2247       not take effect until the next line of input  is  read.   The  commands
2248       following the alias definition on that line are not affected by the new
2249       alias.  This behavior is also an issue  when  functions  are  executed.
2250       Aliases  are  expanded when a function definition is read, not when the
2251       function is executed, because a function definition is  itself  a  com‐
2252       mand.   As  a consequence, aliases defined in a function are not avail‐
2253       able until after that function is executed.  To  be  safe,  always  put
2254       alias  definitions on a separate line, and do not use alias in compound
2255       commands.
2256
2257       For almost every purpose, aliases are superseded by shell functions.
2258

FUNCTIONS

2260       A shell function, defined  as  described  above  under  SHELL  GRAMMAR,
2261       stores  a  series  of commands for later execution.  When the name of a
2262       shell function is used as a simple command name, the list  of  commands
2263       associated with that function name is executed.  Functions are executed
2264       in the context of the current shell;  no  new  process  is  created  to
2265       interpret  them  (contrast  this with the execution of a shell script).
2266       When a function is executed, the arguments to the function  become  the
2267       positional parameters during its execution.  The special parameter # is
2268       updated to reflect the change.  Special parameter 0 is unchanged.   The
2269       first  element of the FUNCNAME variable is set to the name of the func‐
2270       tion while the function is executing.
2271
2272       All other aspects of the  shell  execution  environment  are  identical
2273       between  a function and its caller with these exceptions: the DEBUG and
2274       RETURN traps (see the description  of  the  trap  builtin  under  SHELL
2275       BUILTIN  COMMANDS below) are not inherited unless the function has been
2276       given the trace attribute (see the description of the  declare  builtin
2277       below)  or  the -o functrace shell option has been enabled with the set
2278       builtin (in which case all  functions  inherit  the  DEBUG  and  RETURN
2279       traps),  and the ERR trap is not inherited unless the -o errtrace shell
2280       option has been enabled.
2281
2282       Variables local to the function may be declared with the local  builtin
2283       command.  Ordinarily, variables and their values are shared between the
2284       function and its caller.
2285
2286       The FUNCNEST variable, if set  to  a  numeric  value  greater  than  0,
2287       defines  a  maximum  function nesting level.  Function invocations that
2288       exceed the limit cause the entire command to abort.
2289
2290       If the builtin command return is executed in a function,  the  function
2291       completes  and  execution resumes with the next command after the func‐
2292       tion call.  Any command associated with the  RETURN  trap  is  executed
2293       before execution resumes.  When a function completes, the values of the
2294       positional parameters and the special parameter # are restored  to  the
2295       values they had prior to the function's execution.
2296
2297       Function  names and definitions may be listed with the -f option to the
2298       declare or typeset builtin commands.  The -F option to declare or type‐
2299       set  will  list the function names only (and optionally the source file
2300       and line number, if the extdebug shell option is  enabled).   Functions
2301       may  be exported so that subshells automatically have them defined with
2302       the -f option to the export builtin.   A  function  definition  may  be
2303       deleted  using  the  -f  option  to the unset builtin.  Note that shell
2304       functions and variables with the same name may result in multiple iden‐
2305       tically-named  entries  in  the environment passed to the shell's chil‐
2306       dren.  Care should be taken in cases where this may cause a problem.
2307
2308       Functions may be recursive.  The FUNCNEST variable may be used to limit
2309       the  depth  of the function call stack and restrict the number of func‐
2310       tion invocations.  By default, no limit is imposed  on  the  number  of
2311       recursive calls.
2312

ARITHMETIC EVALUATION

2314       The  shell allows arithmetic expressions to be evaluated, under certain
2315       circumstances (see the let and declare builtin commands,  the  ((  com‐
2316       pound command, and Arithmetic Expansion).  Evaluation is done in fixed-
2317       width integers with no check for overflow,  though  division  by  0  is
2318       trapped  and  flagged as an error.  The operators and their precedence,
2319       associativity, and values are the same as in the C language.  The  fol‐
2320       lowing  list  of  operators  is grouped into levels of equal-precedence
2321       operators.  The levels are listed in order of decreasing precedence.
2322
2323       id++ id--
2324              variable post-increment and post-decrement
2325       ++id --id
2326              variable pre-increment and pre-decrement
2327       - +    unary minus and plus
2328       ! ~    logical and bitwise negation
2329       **     exponentiation
2330       * / %  multiplication, division, remainder
2331       + -    addition, subtraction
2332       << >>  left and right bitwise shifts
2333       <= >= < >
2334              comparison
2335       == !=  equality and inequality
2336       &      bitwise AND
2337       ^      bitwise exclusive OR
2338       |      bitwise OR
2339       &&     logical AND
2340       ||     logical OR
2341       expr?expr:expr
2342              conditional operator
2343       = *= /= %= += -= <<= >>= &= ^= |=
2344              assignment
2345       expr1 , expr2
2346              comma
2347
2348       Shell variables are allowed as operands; parameter  expansion  is  per‐
2349       formed before the expression is evaluated.  Within an expression, shell
2350       variables may also be referenced by name without  using  the  parameter
2351       expansion  syntax.  A shell variable that is null or unset evaluates to
2352       0 when referenced by name without using the parameter expansion syntax.
2353       The  value  of a variable is evaluated as an arithmetic expression when
2354       it is referenced, or when a variable which has been given  the  integer
2355       attribute using declare -i is assigned a value.  A null value evaluates
2356       to 0.  A shell variable need not have its integer attribute  turned  on
2357       to be used in an expression.
2358
2359       Constants with a leading 0 are interpreted as octal numbers.  A leading
2360       0x or  0X  denotes  hexadecimal.   Otherwise,  numbers  take  the  form
2361       [base#]n,  where the optional base is a decimal number between 2 and 64
2362       representing the arithmetic base, and n is a number in that  base.   If
2363       base#  is omitted, then base 10 is used.  When specifying n, the digits
2364       greater than 9 are represented by the lowercase letters, the  uppercase
2365       letters, @, and _, in that order.  If base is less than or equal to 36,
2366       lowercase and uppercase letters may be used interchangeably  to  repre‐
2367       sent numbers between 10 and 35.
2368
2369       Operators  are  evaluated  in  order of precedence.  Sub-expressions in
2370       parentheses are evaluated first and may override the  precedence  rules
2371       above.
2372

CONDITIONAL EXPRESSIONS

2374       Conditional  expressions  are  used  by the [[ compound command and the
2375       test and [ builtin commands to test file attributes and perform  string
2376       and  arithmetic comparisons.  Expressions are formed from the following
2377       unary or binary primaries.  Bash handles  several  filenames  specially
2378       when  they  are  used in expressions.  If the operating system on which
2379       bash is running provides these special files, bash will use them;  oth‐
2380       erwise  it will emulate them internally with this behavior: If any file
2381       argument to one of the primaries is of the form  /dev/fd/n,  then  file
2382       descriptor  n is checked.  If the file argument to one of the primaries
2383       is one of /dev/stdin, /dev/stdout, or /dev/stderr, file  descriptor  0,
2384       1, or 2, respectively, is checked.
2385
2386       Unless otherwise specified, primaries that operate on files follow sym‐
2387       bolic links and operate on the target of the link, rather than the link
2388       itself.
2389
2390       When  used  with [[, the < and > operators sort lexicographically using
2391       the current locale.  The test command sorts using ASCII ordering.
2392
2393       -a file
2394              True if file exists.
2395       -b file
2396              True if file exists and is a block special file.
2397       -c file
2398              True if file exists and is a character special file.
2399       -d file
2400              True if file exists and is a directory.
2401       -e file
2402              True if file exists.
2403       -f file
2404              True if file exists and is a regular file.
2405       -g file
2406              True if file exists and is set-group-id.
2407       -h file
2408              True if file exists and is a symbolic link.
2409       -k file
2410              True if file exists and its ``sticky'' bit is set.
2411       -p file
2412              True if file exists and is a named pipe (FIFO).
2413       -r file
2414              True if file exists and is readable.
2415       -s file
2416              True if file exists and has a size greater than zero.
2417       -t fd  True if file descriptor fd is open and refers to a terminal.
2418       -u file
2419              True if file exists and its set-user-id bit is set.
2420       -w file
2421              True if file exists and is writable.
2422       -x file
2423              True if file exists and is executable.
2424       -G file
2425              True if file exists and is owned by the effective group id.
2426       -L file
2427              True if file exists and is a symbolic link.
2428       -N file
2429              True if file exists and has been  modified  since  it  was  last
2430              read.
2431       -O file
2432              True if file exists and is owned by the effective user id.
2433       -S file
2434              True if file exists and is a socket.
2435       file1 -ef file2
2436              True  if file1 and file2 refer to the same device and inode num‐
2437              bers.
2438       file1 -nt file2
2439              True if file1 is newer (according  to  modification  date)  than
2440              file2, or if file1 exists and file2 does not.
2441       file1 -ot file2
2442              True  if file1 is older than file2, or if file2 exists and file1
2443              does not.
2444       -o optname
2445              True if the shell option optname is enabled.  See  the  list  of
2446              options  under  the  description  of  the  -o  option to the set
2447              builtin below.
2448       -v varname
2449              True if the shell variable varname is set (has been  assigned  a
2450              value).
2451       -R varname
2452              True  if  the shell variable varname is set and is a name refer‐
2453              ence.
2454       -z string
2455              True if the length of string is zero.
2456       string
2457       -n string
2458              True if the length of string is non-zero.
2459
2460       string1 == string2
2461       string1 = string2
2462              True if the strings are equal.  = should be used with  the  test
2463              command  for  POSIX conformance.  When used with the [[ command,
2464              this performs pattern matching as described above (Compound Com‐
2465              mands).
2466
2467       string1 != string2
2468              True if the strings are not equal.
2469
2470       string1 < string2
2471              True if string1 sorts before string2 lexicographically.
2472
2473       string1 > string2
2474              True if string1 sorts after string2 lexicographically.
2475
2476       arg1 OP arg2
2477              OP  is one of -eq, -ne, -lt, -le, -gt, or -ge.  These arithmetic
2478              binary operators return true if arg1 is equal to, not equal  to,
2479              less  than, less than or equal to, greater than, or greater than
2480              or equal to arg2, respectively.  Arg1 and arg2 may  be  positive
2481              or negative integers.
2482

SIMPLE COMMAND EXPANSION

2484       When  a  simple  command  is executed, the shell performs the following
2485       expansions, assignments, and redirections, from left to right.
2486
2487       1.     The words that the parser has  marked  as  variable  assignments
2488              (those  preceding  the  command name) and redirections are saved
2489              for later processing.
2490
2491       2.     The words that are not variable assignments or redirections  are
2492              expanded.   If  any words remain after expansion, the first word
2493              is taken to be the name of the command and the  remaining  words
2494              are the arguments.
2495
2496       3.     Redirections are performed as described above under REDIRECTION.
2497
2498       4.     The text after the = in each variable assignment undergoes tilde
2499              expansion, parameter expansion, command substitution, arithmetic
2500              expansion,  and quote removal before being assigned to the vari‐
2501              able.
2502
2503       If no command name results, the variable assignments affect the current
2504       shell  environment.  Otherwise, the variables are added to the environ‐
2505       ment of the executed command and do not affect the current shell  envi‐
2506       ronment.   If  any  of  the assignments attempts to assign a value to a
2507       readonly variable, an error occurs, and the command exits with  a  non-
2508       zero status.
2509
2510       If  no  command  name  results,  redirections are performed, but do not
2511       affect the current shell environment.  A redirection error  causes  the
2512       command to exit with a non-zero status.
2513
2514       If  there is a command name left after expansion, execution proceeds as
2515       described below.  Otherwise, the command exits.  If one of  the  expan‐
2516       sions  contained a command substitution, the exit status of the command
2517       is the exit status of the  last  command  substitution  performed.   If
2518       there were no command substitutions, the command exits with a status of
2519       zero.
2520

COMMAND EXECUTION

2522       After a command has been split into words, if it results  in  a  simple
2523       command  and  an  optional list of arguments, the following actions are
2524       taken.
2525
2526       If the command name contains no slashes, the shell attempts  to  locate
2527       it.   If  there  exists a shell function by that name, that function is
2528       invoked as described above in FUNCTIONS.  If the name does not match  a
2529       function,  the shell searches for it in the list of shell builtins.  If
2530       a match is found, that builtin is invoked.
2531
2532       If the name is neither a shell function nor a builtin, and contains  no
2533       slashes,  bash  searches  each element of the PATH for a directory con‐
2534       taining an executable file by that name.  Bash uses  a  hash  table  to
2535       remember  the  full pathnames of executable files (see hash under SHELL
2536       BUILTIN COMMANDS below).  A full search of the directories in  PATH  is
2537       performed  only  if the command is not found in the hash table.  If the
2538       search is unsuccessful, the shell searches for a defined shell function
2539       named command_not_found_handle.  If that function exists, it is invoked
2540       with the original command and the original command's arguments  as  its
2541       arguments,  and  the  function's exit status becomes the exit status of
2542       the shell.  If that function is not defined, the shell prints an  error
2543       message and returns an exit status of 127.
2544
2545       If  the  search  is  successful, or if the command name contains one or
2546       more slashes, the shell executes the named program in a separate execu‐
2547       tion environment.  Argument 0 is set to the name given, and the remain‐
2548       ing arguments to the command are set to the arguments given, if any.
2549
2550       If this execution fails because the file is not in  executable  format,
2551       and  the file is not a directory, it is assumed to be a shell script, a
2552       file containing shell commands.  A subshell is spawned to  execute  it.
2553       This  subshell  reinitializes itself, so that the effect is as if a new
2554       shell had been invoked to handle the script, with  the  exception  that
2555       the  locations  of  commands  remembered  by the parent (see hash below
2556       under SHELL BUILTIN COMMANDS) are retained by the child.
2557
2558       If the program is a file beginning with #!, the remainder of the  first
2559       line  specifies an interpreter for the program.  The shell executes the
2560       specified interpreter on operating systems that do not handle this exe‐
2561       cutable format themselves.  The arguments to the interpreter consist of
2562       a single optional argument following the interpreter name on the  first
2563       line  of  the program, followed by the name of the program, followed by
2564       the command arguments, if any.
2565

COMMAND EXECUTION ENVIRONMENT

2567       The shell has an execution environment, which consists of  the  follow‐
2568       ing:
2569
2570       ·      open  files inherited by the shell at invocation, as modified by
2571              redirections supplied to the exec builtin
2572
2573       ·      the current working directory as set by cd, pushd, or  popd,  or
2574              inherited by the shell at invocation
2575
2576       ·      the  file  creation  mode mask as set by umask or inherited from
2577              the shell's parent
2578
2579       ·      current traps set by trap
2580
2581       ·      shell parameters that are set by variable assignment or with set
2582              or inherited from the shell's parent in the environment
2583
2584       ·      shell  functions  defined during execution or inherited from the
2585              shell's parent in the environment
2586
2587       ·      options enabled at invocation (either by default  or  with  com‐
2588              mand-line arguments) or by set
2589
2590       ·      options enabled by shopt
2591
2592       ·      shell aliases defined with alias
2593
2594       ·      various  process  IDs,  including  those of background jobs, the
2595              value of $$, and the value of PPID
2596
2597       When a simple command other than a builtin or shell function is  to  be
2598       executed,  it  is invoked in a separate execution environment that con‐
2599       sists of the following.  Unless otherwise noted, the values are  inher‐
2600       ited from the shell.
2601
2602
2603       ·      the  shell's  open  files,  plus any modifications and additions
2604              specified by redirections to the command
2605
2606       ·      the current working directory
2607
2608       ·      the file creation mode mask
2609
2610       ·      shell variables and functions  marked  for  export,  along  with
2611              variables exported for the command, passed in the environment
2612
2613       ·      traps caught by the shell are reset to the values inherited from
2614              the shell's parent, and traps ignored by the shell are ignored
2615
2616       A command invoked  in  this  separate  environment  cannot  affect  the
2617       shell's execution environment.
2618
2619       Command  substitution, commands grouped with parentheses, and asynchro‐
2620       nous commands are invoked in a subshell environment that is a duplicate
2621       of  the  shell  environment,  except that traps caught by the shell are
2622       reset to the values that the shell inherited from its parent at invoca‐
2623       tion.  Builtin commands that are invoked as part of a pipeline are also
2624       executed in a subshell environment.  Changes made to the subshell envi‐
2625       ronment cannot affect the shell's execution environment.
2626
2627       Subshells spawned to execute command substitutions inherit the value of
2628       the -e option from the parent shell.  When  not  in  posix  mode,  bash
2629       clears the -e option in such subshells.
2630
2631       If  a  command  is  followed  by a & and job control is not active, the
2632       default standard input for the command is  the  empty  file  /dev/null.
2633       Otherwise,  the  invoked  command  inherits the file descriptors of the
2634       calling shell as modified by redirections.
2635

ENVIRONMENT

2637       When a program is invoked it is given an array of  strings  called  the
2638       environment.   This  is  a  list  of  name-value  pairs,  of  the  form
2639       name=value.
2640
2641       The shell provides several ways  to  manipulate  the  environment.   On
2642       invocation, the shell scans its own environment and creates a parameter
2643       for each name found, automatically marking it for export to child  pro‐
2644       cesses.   Executed  commands  inherit  the environment.  The export and
2645       declare -x commands allow parameters and functions to be added  to  and
2646       deleted from the environment.  If the value of a parameter in the envi‐
2647       ronment is modified, the new value becomes  part  of  the  environment,
2648       replacing  the  old.  The environment inherited by any executed command
2649       consists of the shell's initial environment, whose values may be  modi‐
2650       fied  in  the  shell, less any pairs removed by the unset command, plus
2651       any additions via the export and declare -x commands.
2652
2653       The environment for any simple command or  function  may  be  augmented
2654       temporarily  by  prefixing  it with parameter assignments, as described
2655       above in PARAMETERS.  These assignment statements affect only the envi‐
2656       ronment seen by that command.
2657
2658       If  the  -k option is set (see the set builtin command below), then all
2659       parameter assignments are placed in the environment for a command,  not
2660       just those that precede the command name.
2661
2662       When  bash  invokes  an  external command, the variable _ is set to the
2663       full filename of the command and passed to that command in its environ‐
2664       ment.
2665

EXIT STATUS

2667       The  exit  status  of  an executed command is the value returned by the
2668       waitpid system call or equivalent function.  Exit statuses fall between
2669       0  and  255, though, as explained below, the shell may use values above
2670       125 specially.  Exit statuses from shell builtins and compound commands
2671       are also limited to this range.  Under certain circumstances, the shell
2672       will use special values to indicate specific failure modes.
2673
2674       For the shell's purposes, a command which exits with a zero exit status
2675       has  succeeded.   An exit status of zero indicates success.  A non-zero
2676       exit status indicates failure.  When a command terminates  on  a  fatal
2677       signal N, bash uses the value of 128+N as the exit status.
2678
2679       If  a  command  is  not  found, the child process created to execute it
2680       returns a status of 127.  If a command is found but is not  executable,
2681       the return status is 126.
2682
2683       If a command fails because of an error during expansion or redirection,
2684       the exit status is greater than zero.
2685
2686       Shell builtin commands return a status of 0 (true) if  successful,  and
2687       non-zero  (false)  if an error occurs while they execute.  All builtins
2688       return an exit status of  2  to  indicate  incorrect  usage,  generally
2689       invalid options or missing arguments.
2690
2691       Bash  itself  returns  the  exit  status  of the last command executed,
2692       unless a syntax error occurs, in which case it exits  with  a  non-zero
2693       value.  See also the exit builtin command below.
2694

SIGNALS

2696       When  bash  is  interactive,  in  the  absence of any traps, it ignores
2697       SIGTERM (so that kill 0 does not kill an interactive shell), and SIGINT
2698       is  caught and handled (so that the wait builtin is interruptible).  In
2699       all cases, bash ignores SIGQUIT.  If job control  is  in  effect,  bash
2700       ignores SIGTTIN, SIGTTOU, and SIGTSTP.
2701
2702       Non-builtin commands run by bash have signal handlers set to the values
2703       inherited by the shell from its parent.  When job  control  is  not  in
2704       effect,  asynchronous commands ignore SIGINT and SIGQUIT in addition to
2705       these inherited handlers.  Commands run as a result of command  substi‐
2706       tution ignore the keyboard-generated job control signals SIGTTIN, SIGT‐
2707       TOU, and SIGTSTP.
2708
2709       The shell exits by default upon receipt of a SIGHUP.   Before  exiting,
2710       an  interactive  shell  resends  the  SIGHUP  to  all  jobs, running or
2711       stopped.  Stopped jobs are sent SIGCONT to ensure that they receive the
2712       SIGHUP.   To  prevent the shell from sending the signal to a particular
2713       job, it should be removed from the jobs table with the  disown  builtin
2714       (see  SHELL  BUILTIN  COMMANDS  below)  or marked to not receive SIGHUP
2715       using disown -h.
2716
2717       If the huponexit shell option has been set with  shopt,  bash  sends  a
2718       SIGHUP to all jobs when an interactive login shell exits.
2719
2720       If  bash is waiting for a command to complete and receives a signal for
2721       which a trap has been set, the trap will not be executed until the com‐
2722       mand  completes.   When bash is waiting for an asynchronous command via
2723       the wait builtin, the reception of a signal for which a trap  has  been
2724       set will cause the wait builtin to return immediately with an exit sta‐
2725       tus greater than 128, immediately after which the trap is executed.
2726

JOB CONTROL

2728       Job control refers to the ability to  selectively  stop  (suspend)  the
2729       execution of processes and continue (resume) their execution at a later
2730       point.  A user typically  employs  this  facility  via  an  interactive
2731       interface  supplied  jointly  by the operating system kernel's terminal
2732       driver and bash.
2733
2734       The shell associates a job with each pipeline.  It  keeps  a  table  of
2735       currently  executing  jobs,  which may be listed with the jobs command.
2736       When bash starts a job asynchronously (in the background), it prints  a
2737       line that looks like:
2738
2739              [1] 25647
2740
2741       indicating that this job is job number 1 and that the process ID of the
2742       last process in the pipeline associated with this job is 25647.  All of
2743       the  processes  in a single pipeline are members of the same job.  Bash
2744       uses the job abstraction as the basis for job control.
2745
2746       To facilitate the implementation of the user interface to job  control,
2747       the operating system maintains the notion of a current terminal process
2748       group ID.  Members of this process group (processes whose process group
2749       ID is equal to the current terminal process group ID) receive keyboard-
2750       generated signals such as SIGINT.  These processes are said  to  be  in
2751       the  foreground.  Background processes are those whose process group ID
2752       differs from the terminal's; such processes are immune to keyboard-gen‐
2753       erated signals.  Only foreground processes are allowed to read from or,
2754       if the user so specifies with  stty  tostop,  write  to  the  terminal.
2755       Background  processes  which  attempt  to read from (write to when stty
2756       tostop is in effect) the terminal are sent a SIGTTIN  (SIGTTOU)  signal
2757       by  the  kernel's  terminal  driver, which, unless caught, suspends the
2758       process.
2759
2760       If the operating system on which bash is running supports job  control,
2761       bash contains facilities to use it.  Typing the suspend character (typ‐
2762       ically ^Z, Control-Z) while a process is running causes that process to
2763       be  stopped  and  returns  control to bash.  Typing the delayed suspend
2764       character (typically ^Y, Control-Y) causes the process  to  be  stopped
2765       when  it  attempts  to  read input from the terminal, and control to be
2766       returned to bash.  The user may then manipulate the state of this  job,
2767       using  the  bg command to continue it in the background, the fg command
2768       to continue it in the foreground, or the kill command to kill it.  A ^Z
2769       takes effect immediately, and has the additional side effect of causing
2770       pending output and typeahead to be discarded.
2771
2772       There are a number of ways to refer to a job in the shell.  The charac‐
2773       ter  %  introduces  a job specification (jobspec).  Job number n may be
2774       referred to as %n.  A job may also be referred to using a prefix of the
2775       name used to start it, or using a substring that appears in its command
2776       line.  For example, %ce refers to  a  stopped  ce  job.   If  a  prefix
2777       matches  more  than one job, bash reports an error.  Using %?ce, on the
2778       other hand, refers to any job containing the string ce in  its  command
2779       line.   If  the  substring  matches  more than one job, bash reports an
2780       error.  The symbols %% and %+ refer to the shell's notion of  the  cur‐
2781       rent  job, which is the last job stopped while it was in the foreground
2782       or started in the background.  The previous job may be referenced using
2783       %-.  If there is only a single job, %+ and %- can both be used to refer
2784       to that job.  In output pertaining to jobs (e.g.,  the  output  of  the
2785       jobs command), the current job is always flagged with a +, and the pre‐
2786       vious job with a -.  A single % (with no  accompanying  job  specifica‐
2787       tion) also refers to the current job.
2788
2789       Simply  naming a job can be used to bring it into the foreground: %1 is
2790       a synonym for ``fg %1'', bringing job 1 from the  background  into  the
2791       foreground.   Similarly,  ``%1  &''  resumes  job  1 in the background,
2792       equivalent to ``bg %1''.
2793
2794       The shell learns immediately whenever a job changes  state.   Normally,
2795       bash waits until it is about to print a prompt before reporting changes
2796       in a job's status so as to not interrupt any other output.  If  the  -b
2797       option to the set builtin command is enabled, bash reports such changes
2798       immediately.  Any trap on SIGCHLD  is  executed  for  each  child  that
2799       exits.
2800
2801       If  an  attempt to exit bash is made while jobs are stopped (or, if the
2802       checkjobs shell option has been enabled using the shopt  builtin,  run‐
2803       ning), the shell prints a warning message, and, if the checkjobs option
2804       is enabled, lists the jobs and their statuses.  The  jobs  command  may
2805       then  be  used to inspect their status.  If a second attempt to exit is
2806       made without an intervening command, the shell does not  print  another
2807       warning, and any stopped jobs are terminated.
2808

PROMPTING

2810       When executing interactively, bash displays the primary prompt PS1 when
2811       it is ready to read a command, and the secondary  prompt  PS2  when  it
2812       needs  more  input  to  complete a command.  Bash displays PS0 after it
2813       reads a command but before executing  it.   Bash  allows  these  prompt
2814       strings  to  be  customized  by inserting a number of backslash-escaped
2815       special characters that are decoded as follows:
2816              \a     an ASCII bell character (07)
2817              \d     the date in "Weekday Month Date" format (e.g.,  "Tue  May
2818                     26")
2819              \D{format}
2820                     the  format  is  passed  to strftime(3) and the result is
2821                     inserted into the prompt string; an empty format  results
2822                     in a locale-specific time representation.  The braces are
2823                     required
2824              \e     an ASCII escape character (033)
2825              \h     the hostname up to the first `.'
2826              \H     the hostname
2827              \j     the number of jobs currently managed by the shell
2828              \l     the basename of the shell's terminal device name
2829              \n     newline
2830              \r     carriage return
2831              \s     the name of the shell, the basename of  $0  (the  portion
2832                     following the final slash)
2833              \t     the current time in 24-hour HH:MM:SS format
2834              \T     the current time in 12-hour HH:MM:SS format
2835              \@     the current time in 12-hour am/pm format
2836              \A     the current time in 24-hour HH:MM format
2837              \u     the username of the current user
2838              \v     the version of bash (e.g., 2.00)
2839              \V     the release of bash, version + patch level (e.g., 2.00.0)
2840              \w     the  current  working  directory,  with $HOME abbreviated
2841                     with a tilde (uses the value of the PROMPT_DIRTRIM  vari‐
2842                     able)
2843              \W     the basename of the current working directory, with $HOME
2844                     abbreviated with a tilde
2845              \!     the history number of this command
2846              \#     the command number of this command
2847              \$     if the effective UID is 0, a #, otherwise a $
2848              \nnn   the character corresponding to the octal number nnn
2849              \\     a backslash
2850              \[     begin a sequence of non-printing characters, which  could
2851                     be  used  to  embed  a terminal control sequence into the
2852                     prompt
2853              \]     end a sequence of non-printing characters
2854
2855       The command number and the history number are  usually  different:  the
2856       history  number of a command is its position in the history list, which
2857       may include commands  restored  from  the  history  file  (see  HISTORY
2858       below),  while  the  command  number is the position in the sequence of
2859       commands executed during the current shell session.  After  the  string
2860       is  decoded,  it is expanded via parameter expansion, command substitu‐
2861       tion, arithmetic expansion, and quote removal, subject to the value  of
2862       the  promptvars  shell option (see the description of the shopt command
2863       under SHELL BUILTIN COMMANDS below).
2864

READLINE

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

HISTORY

3866       When  the  -o  history  option to the set builtin is enabled, the shell
3867       provides access to the command history, the list of commands previously
3868       typed.   The  value  of  the HISTSIZE variable is used as the number of
3869       commands to save in a history list.  The text of the last HISTSIZE com‐
3870       mands  (default  500)  is  saved.  The shell stores each command in the
3871       history list prior to parameter and variable expansion  (see  EXPANSION
3872       above)  but after history expansion is performed, subject to the values
3873       of the shell variables HISTIGNORE and HISTCONTROL.
3874
3875       On startup, the history is initialized from the file named by the vari‐
3876       able  HISTFILE  (default ~/.bash_history).  The file named by the value
3877       of HISTFILE is truncated, if necessary, to contain  no  more  than  the
3878       number  of  lines specified by the value of HISTFILESIZE.  If HISTFILE‐
3879       SIZE is unset, or set to null, a non-numeric value, or a numeric  value
3880       less  than  zero,  the history file is not truncated.  When the history
3881       file is read, lines beginning with the history comment  character  fol‐
3882       lowed immediately by a digit are interpreted as timestamps for the pre‐
3883       ceding history line.  These timestamps are optionally displayed depend‐
3884       ing  on  the  value  of the HISTTIMEFORMAT variable.  When a shell with
3885       history enabled exits, the last $HISTSIZE lines  are  copied  from  the
3886       history  list  to $HISTFILE.  If the histappend shell option is enabled
3887       (see the description of shopt under SHELL BUILTIN COMMANDS below),  the
3888       lines  are  appended to the history file, otherwise the history file is
3889       overwritten.   If  HISTFILE  is  unset,  or  if  the  history  file  is
3890       unwritable,  the  history is not saved.  If the HISTTIMEFORMAT variable
3891       is set, time stamps are written to the history file,  marked  with  the
3892       history  comment  character, so they may be preserved across shell ses‐
3893       sions.  This uses the history comment character  to  distinguish  time‐
3894       stamps from other history lines.  After saving the history, the history
3895       file is truncated to contain no more than HISTFILESIZE lines.  If HIST‐
3896       FILESIZE  is  unset,  or set to null, a non-numeric value, or a numeric
3897       value less than zero, the history file is not truncated.
3898
3899       The builtin command fc (see SHELL BUILTIN COMMANDS below) may  be  used
3900       to list or edit and re-execute a portion of the history list.  The his‐
3901       tory builtin may be used to display or  modify  the  history  list  and
3902       manipulate  the  history file.  When using command-line editing, search
3903       commands are available in each editing mode that provide access to  the
3904       history list.
3905
3906       The  shell  allows control over which commands are saved on the history
3907       list.  The HISTCONTROL and HISTIGNORE variables may be set to cause the
3908       shell to save only a subset of the commands entered.  The cmdhist shell
3909       option, if enabled, causes the shell to attempt to save each line of  a
3910       multi-line  command  in the same history entry, adding semicolons where
3911       necessary to preserve syntactic correctness.  The lithist shell  option
3912       causes  the shell to save the command with embedded newlines instead of
3913       semicolons.  See the description of the shopt builtin below under SHELL
3914       BUILTIN  COMMANDS  for  information  on  setting  and  unsetting  shell
3915       options.
3916

HISTORY EXPANSION

3918       The shell supports a history expansion feature that is similar  to  the
3919       history  expansion in csh.  This section describes what syntax features
3920       are available.  This feature is  enabled  by  default  for  interactive
3921       shells, and can be disabled using the +H option to the set builtin com‐
3922       mand (see SHELL BUILTIN COMMANDS below).  Non-interactive shells do not
3923       perform history expansion by default.
3924
3925       History expansions introduce words from the history list into the input
3926       stream, making it easy to repeat commands, insert the  arguments  to  a
3927       previous command into the current input line, or fix errors in previous
3928       commands quickly.
3929
3930       History expansion is performed immediately after  a  complete  line  is
3931       read,  before  the  shell  breaks it into words.  It takes place in two
3932       parts.  The first is to determine which line from the history  list  to
3933       use during substitution.  The second is to select portions of that line
3934       for inclusion into the current one.  The line selected from the history
3935       is  the  event,  and  the portions of that line that are acted upon are
3936       words.  Various modifiers are  available  to  manipulate  the  selected
3937       words.  The line is broken into words in the same fashion as when read‐
3938       ing input, so that several metacharacter-separated words surrounded  by
3939       quotes  are  considered one word.  History expansions are introduced by
3940       the appearance of the  history  expansion  character,  which  is  !  by
3941       default.   Only  backslash  (\) and single quotes can quote the history
3942       expansion character,  but  the  history  expansion  character  is  also
3943       treated  as  quoted if it immediately precedes the closing double quote
3944       in a double-quoted string.
3945
3946       Several characters inhibit history expansion if found immediately  fol‐
3947       lowing  the history expansion character, even if it is unquoted: space,
3948       tab, newline, carriage return, and =.  If the extglob shell  option  is
3949       enabled, ( will also inhibit expansion.
3950
3951       Several  shell  options  settable with the shopt builtin may be used to
3952       tailor the behavior of history  expansion.   If  the  histverify  shell
3953       option is enabled (see the description of the shopt builtin below), and
3954       readline is being  used,  history  substitutions  are  not  immediately
3955       passed  to  the  shell  parser.  Instead, the expanded line is reloaded
3956       into the readline editing buffer for further modification.  If readline
3957       is  being  used,  and  the histreedit shell option is enabled, a failed
3958       history substitution will be reloaded into the readline editing  buffer
3959       for  correction.   The  -p option to the history builtin command may be
3960       used to see what a history expansion will do before using it.   The  -s
3961       option to the history builtin may be used to add commands to the end of
3962       the history list without actually executing  them,  so  that  they  are
3963       available for subsequent recall.
3964
3965       The  shell allows control of the various characters used by the history
3966       expansion mechanism (see the description of histchars above under Shell
3967       Variables).   The shell uses the history comment character to mark his‐
3968       tory timestamps when writing the history file.
3969
3970   Event Designators
3971       An event designator is a reference to a command line entry in the  his‐
3972       tory  list.   Unless  the reference is absolute, events are relative to
3973       the current position in the history list.
3974
3975       !      Start a history substitution, except when followed by  a  blank,
3976              newline,  carriage return, = or ( (when the extglob shell option
3977              is enabled using the shopt builtin).
3978       !n     Refer to command line n.
3979       !-n    Refer to the current command minus n.
3980       !!     Refer to the previous command.  This is a synonym for `!-1'.
3981       !string
3982              Refer to the most recent command preceding the current  position
3983              in the history list starting with string.
3984       !?string[?]
3985              Refer  to the most recent command preceding the current position
3986              in the history list containing string.  The trailing  ?  may  be
3987              omitted if string is followed immediately by a newline.
3988       ^string1^string2^
3989              Quick  substitution.   Repeat  the  previous  command, replacing
3990              string1 with string2.  Equivalent  to  ``!!:s/string1/string2/''
3991              (see Modifiers below).
3992       !#     The entire command line typed so far.
3993
3994   Word Designators
3995       Word  designators are used to select desired words from the event.  A :
3996       separates the event specification from the word designator.  It may  be
3997       omitted  if  the word designator begins with a ^, $, *, -, or %.  Words
3998       are numbered from the beginning of the line, with the first word  being
3999       denoted  by  0  (zero).  Words are inserted into the current line sepa‐
4000       rated by single spaces.
4001
4002       0 (zero)
4003              The zeroth word.  For the shell, this is the command word.
4004       n      The nth word.
4005       ^      The first argument.  That is, word 1.
4006       $      The last word.  This is usually  the  last  argument,  but  will
4007              expand to the zeroth word if there is only one word in the line.
4008       %      The word matched by the most recent `?string?' search.
4009       x-y    A range of words; `-y' abbreviates `0-y'.
4010       *      All  of  the words but the zeroth.  This is a synonym for `1-$'.
4011              It is not an error to use * if there is just  one  word  in  the
4012              event; the empty string is returned in that case.
4013       x*     Abbreviates x-$.
4014       x-     Abbreviates x-$ like x*, but omits the last word.
4015
4016       If  a  word  designator is supplied without an event specification, the
4017       previous command is used as the event.
4018
4019   Modifiers
4020       After the optional word designator, there may appear a sequence of  one
4021       or more of the following modifiers, each preceded by a `:'.
4022
4023       h      Remove a trailing filename component, leaving only the head.
4024       t      Remove all leading filename components, leaving the tail.
4025       r      Remove a trailing suffix of the form .xxx, leaving the basename.
4026       e      Remove all but the trailing suffix.
4027       p      Print the new command but do not execute it.
4028       q      Quote the substituted words, escaping further substitutions.
4029       x      Quote  the  substituted words as with q, but break into words at
4030              blanks and newlines.
4031       s/old/new/
4032              Substitute new for the first occurrence  of  old  in  the  event
4033              line.   Any  delimiter  can  be  used  in place of /.  The final
4034              delimiter is optional if it is the last character of  the  event
4035              line.   The delimiter may be quoted in old and new with a single
4036              backslash.  If & appears in new, it is replaced by old.  A  sin‐
4037              gle  backslash  will  quote the &.  If old is null, it is set to
4038              the last old substituted, or, if no previous  history  substitu‐
4039              tions took place, the last string in a !?string[?]  search.
4040       &      Repeat the previous substitution.
4041       g      Cause changes to be applied over the entire event line.  This is
4042              used in conjunction with `:s' (e.g.,  `:gs/old/new/')  or  `:&'.
4043              If  used with `:s', any delimiter can be used in place of /, and
4044              the final delimiter is optional if it is the last  character  of
4045              the event line.  An a may be used as a synonym for g.
4046       G      Apply  the following `s' modifier once to each word in the event
4047              line.
4048

SHELL BUILTIN COMMANDS

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

RESTRICTED SHELL

5819       If bash is started with the name rbash, or the -r option is supplied at
5820       invocation, the shell becomes restricted.  A restricted shell  is  used
5821       to  set  up an environment more controlled than the standard shell.  It
5822       behaves identically to bash with the exception that the  following  are
5823       disallowed or not performed:
5824
5825       ·      changing directories with cd
5826
5827       ·      setting or unsetting the values of SHELL, PATH, ENV, or BASH_ENV
5828
5829       ·      specifying command names containing /
5830
5831       ·      specifying  a  filename  containing  a / as an argument to the .
5832              builtin command
5833
5834       ·      specifying a filename containing a slash as an argument  to  the
5835              -p option to the hash builtin command
5836
5837       ·      importing  function  definitions  from  the shell environment at
5838              startup
5839
5840       ·      parsing the value of SHELLOPTS from  the  shell  environment  at
5841              startup
5842
5843       ·      redirecting output using the >, >|, <>, >&, &>, and >> redirect‐
5844              ion operators
5845
5846       ·      using the exec builtin command to replace the shell with another
5847              command
5848
5849       ·      adding  or  deleting builtin commands with the -f and -d options
5850              to the enable builtin command
5851
5852       ·      using the  enable  builtin  command  to  enable  disabled  shell
5853              builtins
5854
5855       ·      specifying the -p option to the command builtin command
5856
5857       ·      turning off restricted mode with set +r or set +o restricted.
5858
5859       These restrictions are enforced after any startup files are read.
5860
5861       When a command that is found to be a shell script is executed (see COM‐
5862       MAND EXECUTION above), rbash turns off any restrictions  in  the  shell
5863       spawned to execute the script.
5864

SEE ALSO

5866       Bash Reference Manual, Brian Fox and Chet Ramey
5867       The Gnu Readline Library, Brian Fox and Chet Ramey
5868       The Gnu History Library, Brian Fox and Chet Ramey
5869       Portable  Operating  System  Interface (POSIX) Part 2: Shell and Utili‐
5870       ties, IEEE --
5871              http://pubs.opengroup.org/onlinepubs/9699919799/
5872       http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode
5873       sh(1), ksh(1), csh(1)
5874       emacs(1), vi(1)
5875       readline(3)
5876

FILES

5878       /bin/bash
5879              The bash executable
5880       /etc/profile
5881              The systemwide initialization file, executed for login shells
5882       /etc/bash.bash_logout
5883              The systemwide login shell cleanup file, executed when  a  login
5884              shell exits
5885       ~/.bash_profile
5886              The personal initialization file, executed for login shells
5887       ~/.bashrc
5888              The individual per-interactive-shell startup file
5889       ~/.bash_logout
5890              The  individual  login shell cleanup file, executed when a login
5891              shell exits
5892       ~/.inputrc
5893              Individual readline initialization file
5894

AUTHORS

5896       Brian Fox, Free Software Foundation
5897       bfox@gnu.org
5898
5899       Chet Ramey, Case Western Reserve University
5900       chet.ramey@case.edu
5901

BUG REPORTS

5903       If you find a bug in bash, you should report it.  But first, you should
5904       make  sure  that  it really is a bug, and that it appears in the latest
5905       version  of  bash.   The  latest  version  is  always  available   from
5906       ftp://ftp.gnu.org/pub/gnu/bash/.
5907
5908       Once  you  have  determined that a bug actually exists, use the bashbug
5909       command to submit a bug report.  If you have a fix, you are  encouraged
5910       to  mail that as well!  Suggestions and `philosophical' bug reports may
5911       be mailed  to  bug-bash@gnu.org  or  posted  to  the  Usenet  newsgroup
5912       gnu.bash.bug.
5913
5914       ALL bug reports should include:
5915
5916       The version number of bash
5917       The hardware and operating system
5918       The compiler used to compile
5919       A description of the bug behaviour
5920       A short script or `recipe' which exercises the bug
5921
5922       bashbug  inserts  the first three items automatically into the template
5923       it provides for filing a bug report.
5924
5925       Comments and bug reports concerning this manual page should be directed
5926       to chet.ramey@case.edu.
5927

BUGS

5929       It's too big and too slow.
5930
5931       There are some subtle differences between bash and traditional versions
5932       of sh, mostly because of the POSIX specification.
5933
5934       Aliases are confusing in some uses.
5935
5936       Shell builtin commands and functions are not stoppable/restartable.
5937
5938       Compound commands and command sequences of the form `a ; b ; c' are not
5939       handled  gracefully  when  process  suspension  is  attempted.   When a
5940       process is stopped, the shell immediately executes the next command  in
5941       the  sequence.   It  suffices to place the sequence of commands between
5942       parentheses to force it into a subshell, which  may  be  stopped  as  a
5943       unit.
5944
5945       Array variables may not (yet) be exported.
5946
5947       There may be only one active coprocess at a time.
5948
5949
5950
5951GNU Bash 4.4                    2016 August 26                         BASH(1)
Impressum