source: trunk/third/bash/doc/bash.1 @ 21276

Revision 21276, 238.1 KB checked in by zacheiss, 20 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r21275, which included commits to RCS files with non-trunk default branches.
Line 
1.\"
2.\" MAN PAGE COMMENTS to
3.\"
4.\"     Chet Ramey
5.\"     Information Network Services
6.\"     Case Western Reserve University
7.\"     chet@po.CWRU.Edu
8.\"
9.\"     Last Change: Sat Jun 26 14:26:44 EDT 2004
10.\"
11.\" bash_builtins, strip all but Built-Ins section
12.if \n(zZ=1 .ig zZ
13.if \n(zY=1 .ig zY
14.TH BASH 1 "2004 June 26" "GNU Bash-3.0"
15.\"
16.\" There's some problem with having a `@'
17.\" in a tagged paragraph with the BSD man macros.
18.\" It has to do with `@' appearing in the }1 macro.
19.\" This is a problem on 4.3 BSD and Ultrix, but Sun
20.\" appears to have fixed it.
21.\" If you're seeing the characters
22.\" `@u-3p' appearing before the lines reading
23.\" `possible-hostname-completions
24.\" and `complete-hostname' down in READLINE,
25.\" then uncomment this redefinition.
26.\"
27.de }1
28.ds ]X \&\\*(]B\\
29.nr )E 0
30.if !"\\$1"" .nr )I \\$1n
31.}f
32.ll \\n(LLu
33.in \\n()Ru+\\n(INu+\\n()Iu
34.ti \\n(INu
35.ie !\\n()Iu+\\n()Ru-\w\\*(]Xu-3p \{\\*(]X
36.br\}
37.el \\*(]X\h|\\n()Iu+\\n()Ru\c
38.}f
39..
40.\"
41.\" File Name macro.  This used to be `.PN', for Path Name,
42.\" but Sun doesn't seem to like that very much.
43.\"
44.de FN
45\fI\|\\$1\|\fP
46..
47.SH NAME
48bash \- GNU Bourne-Again SHell
49.SH SYNOPSIS
50.B bash
51[options]
52[file]
53.SH COPYRIGHT
54.if n Bash is Copyright (C) 1989-2004 by the Free Software Foundation, Inc.
55.if t Bash is Copyright \(co 1989-2004 by the Free Software Foundation, Inc.
56.SH DESCRIPTION
57.B Bash
58is an \fBsh\fR-compatible command language interpreter that
59executes commands read from the standard input or from a file.
60.B Bash
61also incorporates useful features from the \fIKorn\fP and \fIC\fP
62shells (\fBksh\fP and \fBcsh\fP).
63.PP
64.B Bash
65is intended to be a conformant implementation of the IEEE
66POSIX Shell and Tools specification (IEEE Working Group 1003\.2).
67.SH OPTIONS
68In addition to the single-character shell options documented in the
69description of the \fBset\fR builtin command, \fBbash\fR
70interprets the following options when it is invoked:
71.PP
72.PD 0
73.TP 10
74.BI \-c "\| string\^"
75If the
76.B \-c
77option is present, then commands are read from
78.IR string .
79If there are arguments after the
80.IR string ,
81they are assigned to the positional parameters, starting with
82.BR $0 .
83.TP
84.B \-i
85If the
86.B \-i
87option is present, the shell is
88.IR interactive .
89.TP
90.B \-l
91Make
92.B bash
93act as if it had been invoked as a login shell (see
94.SM
95.B INVOCATION
96below).
97.TP
98.B \-r
99If the
100.B \-r
101option is present, the shell becomes
102.I restricted
103(see
104.SM
105.B "RESTRICTED SHELL"
106below).
107.TP
108.B \-s
109If the
110.B \-s
111option is present, or if no arguments remain after option
112processing, then commands are read from the standard input.
113This option allows the positional parameters to be set
114when invoking an interactive shell.
115.TP
116.B \-D
117A list of all double-quoted strings preceded by \fB$\fP
118is printed on the standard ouput.
119These are the strings that
120are subject to language translation when the current locale
121is not \fBC\fP or \fBPOSIX\fP.
122This implies the \fB\-n\fP option; no commands will be executed.
123.TP
124.B [\-+]O [\fIshopt_option\fP]
125\fIshopt_option\fP is one of the shell options accepted by the
126\fBshopt\fP builtin (see
127.SM
128.B SHELL BUILTIN COMMANDS
129below).
130If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option;
131\fB+O\fP unsets it.
132If \fIshopt_option\fP is not supplied, the names and values of the shell
133options accepted by \fBshopt\fP are printed on the standard output.
134If the invocation option is \fB+O\fP, the output is displayed in a format
135that may be reused as input.
136.TP
137.B \-\-
138A
139.B \-\-
140signals the end of options and disables further option processing.
141Any arguments after the
142.B \-\-
143are treated as filenames and arguments.  An argument of
144.B \-
145is equivalent to \fB\-\-\fP.
146.PD
147.PP
148.B Bash
149also interprets a number of multi-character options.
150These options must appear on the command line before the
151single-character options to be recognized.
152.PP
153.PD 0
154.TP
155.B \-\-debugger
156Arrange for the debugger profile to be executed before the shell
157starts.  Turns on extended debugging mode (see the description of the
158.B extdebug
159option to the
160.B shopt
161builtin below) and shell function tracing (see the description of the
162\fB\-o functrace\fP option to the
163.B set
164builtin below).
165.TP
166.B \-\-dump\-po\-strings
167Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP
168\fBpo\fP (portable object) file format.
169.TP
170.B \-\-dump\-strings
171Equivalent to \fB\-D\fP.
172.TP
173.B \-\-help
174Display a usage message on standard output and exit successfully.
175.TP
176\fB\-\-init\-file\fP \fIfile\fP
177.PD 0
178.TP
179\fB\-\-rcfile\fP \fIfile\fP
180.PD
181Execute commands from
182.I file
183instead of the standard personal initialization file
184.I ~/.bashrc
185if the shell is interactive (see
186.SM
187.B INVOCATION
188below).
189.TP
190.B \-\-login
191Equivalent to \fB\-l\fP.
192.TP
193.B \-\-noediting
194Do not use the GNU
195.B readline
196library to read command lines when the shell is interactive.
197.TP
198.B \-\-noprofile
199Do not read either the system-wide startup file
200.FN /etc/profile
201or any of the personal initialization files
202.IR ~/.bash_profile ,
203.IR ~/.bash_login ,
204or
205.IR ~/.profile .
206By default,
207.B bash
208reads these files when it is invoked as a login shell (see
209.SM
210.B INVOCATION
211below).
212.TP
213.B \-\-norc
214Do not read and execute the personal initialization file
215.I ~/.bashrc
216if the shell is interactive.
217This option is on by default if the shell is invoked as
218.BR sh .
219.TP
220.B \-\-posix
221Change the behavior of \fBbash\fP where the default operation differs
222from the POSIX 1003.2 standard to match the standard (\fIposix mode\fP).
223.TP
224.B \-\-restricted
225The shell becomes restricted (see
226.SM
227.B "RESTRICTED SHELL"
228below).
229.TP
230.B \-\-verbose
231Equivalent to  \fB\-v\fP.
232.TP
233.B \-\-version
234Show version information for this instance of
235.B bash
236on the standard output and exit successfully.
237.PD
238.SH ARGUMENTS
239If arguments remain after option processing, and neither the
240.B \-c
241nor the
242.B \-s
243option has been supplied, the first argument is assumed to
244be the name of a file containing shell commands.
245If
246.B bash
247is invoked in this fashion,
248.B $0
249is set to the name of the file, and the positional parameters
250are set to the remaining arguments.
251.B Bash
252reads and executes commands from this file, then exits.
253\fBBash\fP's exit status is the exit status of the last command
254executed in the script.
255If no commands are executed, the exit status is 0.
256An attempt is first made to open the file in the current directory, and,
257if no file is found, then the shell searches the directories in
258.SM
259.B PATH
260for the script.
261.SH INVOCATION
262A \fIlogin shell\fP is one whose first character of argument zero is a
263.BR \- ,
264or one started with the
265.B \-\-login
266option.
267.PP
268An \fIinteractive\fP shell is one started without non-option arguments
269and without the
270.B \-c
271option
272whose standard input and error are
273both connected to terminals (as determined by
274.IR isatty (3)),
275or one started with the
276.B \-i
277option.
278.SM
279.B PS1
280is set and
281.B $\-
282includes
283.B i
284if
285.B bash
286is interactive,
287allowing a shell script or a startup file to test this state.
288.PP
289The following paragraphs describe how
290.B bash
291executes its startup files.
292If any of the files exist but cannot be read,
293.B bash
294reports an error.
295Tildes are expanded in file names as described below under
296.B "Tilde Expansion"
297in the
298.SM
299.B EXPANSION
300section.
301.PP
302When
303.B bash
304is invoked as an interactive login shell, or as a non-interactive shell
305with the \fB\-\-login\fP option, it first reads and
306executes commands from the file \fI/etc/profile\fP, if that
307file exists.
308After reading that file, it looks for \fI~/.bash_profile\fP,
309\fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads
310and executes commands from the first one that exists and is readable.
311The
312.B \-\-noprofile
313option may be used when the shell is started to inhibit this behavior.
314.PP
315When a login shell exits,
316.B bash
317reads and executes commands from the file \fI~/.bash_logout\fP, if it
318exists.
319.PP
320When an interactive shell that is not a login shell is started,
321.B bash
322reads and executes commands from \fI~/.bashrc\fP, if that file exists.
323This may be inhibited by using the
324.B \-\-norc
325option.
326The \fB\-\-rcfile\fP \fIfile\fP option will force
327.B bash
328to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP.
329.PP
330When
331.B bash
332is started non-interactively, to run a shell script, for example, it
333looks for the variable
334.SM
335.B BASH_ENV
336in the environment, expands its value if it appears there, and uses the
337expanded value as the name of a file to read and execute.
338.B Bash
339behaves as if the following command were executed:
340.sp .5
341.RS
342.if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP
343.if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
344.RE
345.sp .5
346but the value of the
347.SM
348.B PATH
349variable is not used to search for the file name.
350.PP
351If
352.B bash
353is invoked with the name
354.BR sh ,
355it tries to mimic the startup behavior of historical versions of
356.B sh
357as closely as possible,
358while conforming to the POSIX standard as well.
359When invoked as an interactive login shell, or a non-interactive
360shell with the \fB\-\-login\fP option, it first attempts to
361read and execute commands from
362.I /etc/profile
363and
364.IR ~/.profile ,
365in that order.
366The
367.B \-\-noprofile
368option may be used to inhibit this behavior.
369When invoked as an interactive shell with the name
370.BR sh ,
371.B bash
372looks for the variable
373.SM
374.BR ENV ,
375expands its value if it is defined, and uses the
376expanded value as the name of a file to read and execute.
377Since a shell invoked as
378.B sh
379does not attempt to read and execute commands from any other startup
380files, the
381.B \-\-rcfile
382option has no effect.
383A non-interactive shell invoked with the name
384.B sh
385does not attempt to read any other startup files.
386When invoked as
387.BR sh ,
388.B bash
389enters
390.I posix
391mode after the startup files are read.
392.PP
393When
394.B bash
395is started in
396.I posix
397mode, as with the
398.B \-\-posix
399command line option, it follows the POSIX standard for startup files.
400In this mode, interactive shells expand the
401.SM
402.B ENV
403variable and commands are read and executed from the file
404whose name is the expanded value.
405No other startup files are read.
406.PP
407.B Bash
408attempts to determine when it is being run by the remote shell
409daemon, usually \fIrshd\fP.
410If
411.B bash
412determines it is being run by \fIrshd\fP, it reads and executes
413commands from \fI~/.bashrc\fP, if that file exists and is readable.
414It will not do this if invoked as \fBsh\fP.
415The
416.B \-\-norc
417option may be used to inhibit this behavior, and the
418.B \-\-rcfile
419option may be used to force another file to be read, but
420\fIrshd\fP does not generally invoke the shell with those options
421or allow them to be specified.
422.PP
423If the shell is started with the effective user (group) id not equal to the
424real user (group) id, and the \fB\-p\fP option is not supplied, no startup
425files are read, shell functions are not inherited from the environment, the
426.SM
427.B SHELLOPTS
428variable, if it appears in the environment, is ignored,
429and the effective user id is set to the real user id.
430If the \fB\-p\fP option is supplied at invocation, the startup behavior is
431the same, but the effective user id is not reset.
432.SH DEFINITIONS
433.PP
434The following definitions are used throughout the rest of this
435document.
436.PD 0
437.TP
438.B blank
439A space or tab.
440.TP
441.B word
442A sequence of characters considered as a single unit by the shell.
443Also known as a
444.BR token .
445.TP
446.B name
447A
448.I word
449consisting only of alphanumeric characters and underscores, and
450beginning with an alphabetic character or an underscore.  Also
451referred to as an
452.BR identifier .
453.TP
454.B metacharacter
455A character that, when unquoted, separates words.  One of the following:
456.br
457.RS
458.PP
459.if t \fB|  &  ;  (  )  <  >  space  tab\fP
460.if n \fB|  & ; ( ) < > space tab\fP
461.RE
462.PP
463.TP
464.B control operator
465A \fItoken\fP that performs a control function.  It is one of the following
466symbols:
467.RS
468.PP
469.if t \fB\(bv\(bv  &  &&  ;  ;;  (  )  |  <newline>\fP
470.if n \fB|| & && ; ;; ( ) | <newline>\fP
471.RE
472.PD
473.SH "RESERVED WORDS"
474\fIReserved words\fP are words that have a special meaning to the shell.
475The following words are recognized as reserved when unquoted and either
476the first word of a simple command (see
477.SM
478.B SHELL GRAMMAR
479below) or the third word of a
480.B case
481or
482.B for
483command:
484.if t .RS
485.PP
486.B
487.if n ! case  do done elif else esac fi for function if in select then until while { } time [[ ]]
488.if t !    case    do    done    elif    else    esac    fi    for    function    if    in    select    then    until    while    {    }    time    [[    ]]
489.if t .RE
490.SH "SHELL GRAMMAR"
491.SS Simple Commands
492.PP
493A \fIsimple command\fP is a sequence of optional variable assignments
494followed by \fBblank\fP-separated words and redirections, and
495terminated by a \fIcontrol operator\fP.  The first word
496specifies the command to be executed, and is passed as argument zero.
497The remaining words are passed as arguments to the invoked command.
498.PP
499The return value of a \fIsimple command\fP is its exit status, or
500128+\fIn\^\fP if the command is terminated by signal
501.IR n .
502.SS Pipelines
503.PP
504A \fIpipeline\fP is a sequence of one or more commands separated by
505the character
506.BR | .
507The format for a pipeline is:
508.RS
509.PP
510[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand\fP [ \fB|\fP \fIcommand2\fP ... ]
511.RE
512.PP
513The standard output of
514.I command
515is connected via a pipe to the standard input of
516.IR command2 .
517This connection is performed before any redirections specified by the
518command (see
519.SM
520.B REDIRECTION
521below).
522.PP
523The return status of a pipeline is the exit status of the last
524command, unless the \fBpipefail\fP option is enabled.
525If \fBpipefail\fP is enabled, the pipeline's return status is the
526value of the last (rightmost) command to exit with a non-zero status,
527or zero if all commands exit successfully.
528If the reserved word
529.B !
530precedes a pipeline, the exit status of that pipeline is the logical
531negation of the exit status as described above.
532The shell waits for all commands in the pipeline to
533terminate before returning a value.
534.PP
535If the
536.B time
537reserved word precedes a pipeline, the elapsed as well as user and
538system time consumed by its execution are reported when the pipeline
539terminates.
540The \fB\-p\fP option changes the output format to that specified by POSIX.
541The
542.SM
543.B TIMEFORMAT
544variable may be set to a format string that specifies how the timing
545information should be displayed; see the description of
546.SM
547.B TIMEFORMAT
548under
549.B "Shell Variables"
550below.
551.PP
552Each command in a pipeline is executed as a separate process (i.e., in a
553subshell).
554.SS Lists
555.PP
556A \fIlist\fP is a sequence of one or more pipelines separated by one
557of the operators
558.BR ; ,
559.BR & ,
560.BR && ,
561or
562.BR \(bv\(bv ,
563and optionally terminated by one of
564.BR ; ,
565.BR & ,
566or
567.BR <newline> .
568.PP
569Of these list operators,
570.B &&
571and
572.B \(bv\(bv
573have equal precedence, followed by
574.B ;
575and
576.BR &,
577which have equal precedence.
578.PP
579A sequence of one or more newlines may appear in a \fIlist\fP instead
580of a semicolon to delimit commands.
581.PP
582If a command is terminated by the control operator
583.BR & ,
584the shell executes the command in the \fIbackground\fP
585in a subshell.  The shell does not wait for the command to
586finish, and the return status is 0.  Commands separated by a
587.B ;
588are executed sequentially; the shell waits for each
589command to terminate in turn.  The return status is the
590exit status of the last command executed.
591.PP
592The control operators
593.B &&
594and
595.B \(bv\(bv
596denote AND lists and OR lists, respectively.
597An AND list has the form
598.RS
599.PP
600\fIcommand1\fP \fB&&\fP \fIcommand2\fP
601.RE
602.PP
603.I command2
604is executed if, and only if,
605.I command1
606returns an exit status of zero.
607.PP
608An OR list has the form
609.RS
610.PP
611\fIcommand1\fP \fB\(bv\(bv\fP \fIcommand2\fP
612.PP
613.RE
614.PP
615.I command2
616is executed if and only if
617.I command1
618returns a non-zero exit status.  The return status of
619AND and OR lists is the exit status of the last command
620executed in the list.
621.SS Compound Commands
622.PP
623A \fIcompound command\fP is one of the following:
624.TP
625(\fIlist\fP)
626\fIlist\fP is executed in a subshell environment (see
627.SM
628\fBCOMMAND EXECUTION ENVIRONMENT\fP
629below).
630Variable assignments and builtin
631commands that affect the shell's environment do not remain in effect
632after the command completes.  The return status is the exit status of
633\fIlist\fP.
634.TP
635{ \fIlist\fP; }
636\fIlist\fP is simply executed in the current shell environment.
637\fIlist\fP must be terminated with a newline or semicolon.
638This is known as a \fIgroup command\fP.
639The return status is the exit status of
640\fIlist\fP.
641Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and
642\fB}\fP are \fIreserved words\fP and must occur where a reserved
643word is permitted to be recognized.  Since they do not cause a word
644break, they must be separated from \fIlist\fP by whitespace.
645.TP
646((\fIexpression\fP))
647The \fIexpression\fP is evaluated according to the rules described
648below under
649.SM
650.BR "ARITHMETIC EVALUATION" .
651If the value of the expression is non-zero, the return status is 0;
652otherwise the return status is 1.  This is exactly equivalent to
653\fBlet "\fIexpression\fP"\fR.
654.TP
655\fB[[\fP \fIexpression\fP \fB]]\fP
656Return a status of 0 or 1 depending on the evaluation of
657the conditional expression \fIexpression\fP.
658Expressions are composed of the primaries described below under
659.SM
660.BR "CONDITIONAL EXPRESSIONS" .
661Word splitting and pathname expansion are not performed on the words
662between the \fB[[\fP and \fB]]\fP; tilde expansion, parameter and
663variable expansion, arithmetic expansion, command substitution, process
664substitution, and quote removal are performed.
665Conditional operators such as \fB\-f\fP must be unquoted to be recognized
666as primaries.
667.if t .sp 0.5
668.if n .sp 1
669When the \fB==\fP and \fB!=\fP operators are used, the string to the
670right of the operator is considered a pattern and matched according
671to the rules described below under \fBPattern Matching\fP.
672The return value is 0 if the string matches or does not match
673the pattern, respectively, and 1 otherwise.
674Any part of the pattern may be quoted to force it to be matched as a
675string.
676.if t .sp 0.5
677.if n .sp 1
678An additional binary operator, \fB=~\fP, is available, with the same
679precedence as \fB==\fP and \fB!=\fP.
680When it is used, the string to the right of the operator is considered
681an extended regular expression and matched accordingly (as in \fIregex\fP(3)). 
682The return value is 0 if the string matches
683the pattern, and 1 otherwise.
684If the regular expression is syntactically incorrect, the conditional
685expression's return value is 2.
686If the shell option
687.B nocaseglob
688is enabled, the match is performed without regard to the case
689of alphabetic characters.
690Substrings matched by parenthesized subexpressions within the regular
691expression are saved in the array variable \fBBASH_REMATCH\fP.
692The element of \fBBASH_REMATCH\fP with index 0 is the portion of the string
693matching the entire regular expression.
694The element of \fBBASH_REMATCH\fP with index \fIn\fP is the portion of the
695string matching the \fIn\fPth parenthesized subexpression.
696.if t .sp 0.5
697.if n .sp 1
698Expressions may be combined using the following operators, listed
699in decreasing order of precedence:
700.if t .sp 0.5
701.if n .sp 1
702.RS
703.PD 0
704.TP
705.B ( \fIexpression\fP )
706Returns the value of \fIexpression\fP.
707This may be used to override the normal precedence of operators.
708.TP
709.B ! \fIexpression\fP
710True if
711.I expression
712is false.
713.TP
714\fIexpression1\fP \fB&&\fP \fIexpression2\fP
715True if both
716.I expression1
717and
718.I expression2
719are true.
720.TP
721.if t \fIexpression1\fP \fB\(bv\(bv\fP \fIexpression2\fP
722.if n \fIexpression1\fP \fB||\fP \fIexpression2\fP
723True if either
724.I expression1
725or
726.I expression2
727is true.
728.PD
729.LP
730The \fB&&\fP and
731.if t \fB\(bv\(bv\fP
732.if n \fB||\fP
733operators do not evaluate \fIexpression2\fP if the value of
734\fIexpression1\fP is sufficient to determine the return value of
735the entire conditional expression.
736.RE
737.TP
738\fBfor\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP
739The list of words following \fBin\fP is expanded, generating a list
740of items.
741The variable \fIname\fP is set to each element of this list
742in turn, and \fIlist\fP is executed each time.
743If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes
744\fIlist\fP once for each positional parameter that is set (see
745.SM
746.B PARAMETERS
747below).
748The return status is the exit status of the last command that executes.
749If the expansion of the items following \fBin\fP results in an empty
750list, no commands are executed, and the return status is 0.
751.TP
752\fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP
753First, the arithmetic expression \fIexpr1\fP is evaluated according
754to the rules described below under
755.SM
756.BR "ARITHMETIC EVALUATION" .
757The arithmetic expression \fIexpr2\fP is then evaluated repeatedly
758until it evaluates to zero.
759Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is
760executed and the arithmetic expression \fIexpr3\fP is evaluated.
761If any expression is omitted, it behaves as if it evaluates to 1.
762The return value is the exit status of the last command in \fIlist\fP
763that is executed, or false if any of the expressions is invalid.
764.TP
765\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP
766The list of words following \fBin\fP is expanded, generating a list
767of items.  The set of expanded words is printed on the standard
768error, each preceded by a number.  If the \fBin\fP
769\fIword\fP is omitted, the positional parameters are printed (see
770.SM
771.B PARAMETERS
772below).  The
773.B PS3
774prompt is then displayed and a line read from the standard input.
775If the line consists of a number corresponding to one of
776the displayed words, then the value of
777.I name
778is set to that word.  If the line is empty, the words and prompt
779are displayed again.  If EOF is read, the command completes.  Any
780other value read causes
781.I name
782to be set to null.  The line read is saved in the variable
783.BR REPLY .
784The
785.I list
786is executed after each selection until a
787.B break
788command is executed.
789The exit status of
790.B select
791is the exit status of the last command executed in
792.IR list ,
793or zero if no commands were executed.
794.TP
795\fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
796... ) \fIlist\fP ;; ] ... \fBesac\fP
797A \fBcase\fP command first expands \fIword\fP, and tries to match
798it against each \fIpattern\fP in turn, using the same matching rules
799as for pathname expansion (see
800.B Pathname Expansion
801below).  When a match is found, the
802corresponding \fIlist\fP is executed.  After the first match, no
803subsequent matches are attempted.  The exit status is zero if no
804pattern matches.  Otherwise, it is the exit status of the
805last command executed in \fIlist\fP.
806.TP
807\fBif\fP \fIlist\fP; \fBthen\fP \fIlist;\fP \
808[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
809[ \fBelse\fP \fIlist\fP; ] \fBfi\fP
810The
811.B if
812.I list
813is executed.  If its exit status is zero, the
814\fBthen\fP \fIlist\fP is executed.  Otherwise, each \fBelif\fP
815\fIlist\fP is executed in turn, and if its exit status is zero,
816the corresponding \fBthen\fP \fIlist\fP is executed and the
817command completes.  Otherwise, the \fBelse\fP \fIlist\fP is
818executed, if present.  The exit status is the exit status of the
819last command executed, or zero if no condition tested true.
820.TP
821\fBwhile\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
822.PD 0
823.TP
824\fBuntil\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
825.PD
826The \fBwhile\fP command continuously executes the \fBdo\fP
827\fIlist\fP as long as the last command in \fIlist\fP returns
828an exit status of zero.  The \fBuntil\fP command is identical
829to the \fBwhile\fP command, except that the test is negated;
830the
831.B do
832.I list
833is executed as long as the last command in
834.I list
835returns a non-zero exit status.
836The exit status of the \fBwhile\fP and \fBuntil\fP commands
837is the exit status
838of the last \fBdo\fP \fIlist\fP command executed, or zero if
839none was executed.
840.SS Shell Function Definitions
841.PP
842A shell function is an object that is called like a simple command and
843executes a compound command with a new set of positional parameters.
844Shell functions are declared as follows:
845.TP
846[ \fBfunction\fP ] \fIname\fP () \fIcompound\-command\fP [\fIredirection\fP]
847This defines a function named \fIname\fP.
848The reserved word \fBfunction\fP is optional.
849If the \fBfunction\fP reserved word is supplied, the parentheses are optional.
850The \fIbody\fP of the function is the compound command
851.I compound\-command
852(see \fBCompound Commands\fP above).
853That command is usually a \fIlist\fP of commands between { and }, but
854may be any command listed under \fBCompound Commands\fP above.
855\fIcompound\-command\fP is executed whenever \fIname\fP is specified as the
856name of a simple command.
857Any redirections (see
858.SM
859.B REDIRECTION
860below) specified when a function is defined are performed
861when the function is executed.
862The exit status of a function definition is zero unless a syntax error
863occurs or a readonly function with the same name already exists.
864When executed, the exit status of a function is the exit status of the
865last command executed in the body.  (See
866.SM
867.B FUNCTIONS
868below.)
869.SH COMMENTS
870In a non-interactive shell, or an interactive shell in which the
871.B interactive_comments
872option to the
873.B shopt
874builtin is enabled (see
875.SM
876.B "SHELL BUILTIN COMMANDS"
877below), a word beginning with
878.B #
879causes that word and all remaining characters on that line to
880be ignored.  An interactive shell without the
881.B interactive_comments
882option enabled does not allow comments.  The
883.B interactive_comments
884option is on by default in interactive shells.
885.SH QUOTING
886\fIQuoting\fP is used to remove the special meaning of certain
887characters or words to the shell.  Quoting can be used to
888disable special treatment for special characters, to prevent
889reserved words from being recognized as such, and to prevent
890parameter expansion.
891.PP
892Each of the \fImetacharacters\fP listed above under
893.SM
894.B DEFINITIONS
895has special meaning to the shell and must be quoted if it is to
896represent itself.
897.PP
898When the command history expansion facilities are being used, the
899\fIhistory expansion\fP character, usually \fB!\fP, must be quoted
900to prevent history expansion.
901.PP
902There are three quoting mechanisms: the
903.IR "escape character" ,
904single quotes, and double quotes.
905.PP
906A non-quoted backslash (\fB\e\fP) is the
907.IR "escape character" .
908It preserves the literal value of the next character that follows,
909with the exception of <newline>.  If a \fB\e\fP<newline> pair
910appears, and the backslash is not itself quoted, the \fB\e\fP<newline>
911is treated as a line continuation (that is, it is removed from the
912input stream and effectively ignored).
913.PP
914Enclosing characters in single quotes preserves the literal value
915of each character within the quotes.  A single quote may not occur
916between single quotes, even when preceded by a backslash.
917.PP
918Enclosing characters in double quotes preserves the literal value
919of all characters within the quotes, with the exception of
920.BR $ ,
921.BR ` ,
922and
923.BR \e .
924The characters
925.B $
926and
927.B `
928retain their special meaning within double quotes.  The backslash
929retains its special meaning only when followed by one of the following
930characters:
931.BR $ ,
932.BR ` ,
933\^\fB"\fP\^,
934.BR \e ,
935or
936.BR <newline> .
937A double quote may be quoted within double quotes by preceding it with
938a backslash.
939When command history is being used, the double quote may not be used to
940quote the history expansion character.
941.PP
942The special parameters
943.B *
944and
945.B @
946have special meaning when in double
947quotes (see
948.SM
949.B PARAMETERS
950below).
951.PP
952Words of the form \fB$\fP'\fIstring\fP' are treated specially.  The
953word expands to \fIstring\fP, with backslash-escaped characters replaced
954as specifed by the ANSI C standard.  Backslash escape sequences, if
955present, are decoded as follows:
956.RS
957.PD 0
958.TP
959.B \ea
960alert (bell)
961.TP
962.B \eb
963backspace
964.TP
965.B \ee
966an escape character
967.TP   
968.B \ef
969form feed
970.TP 
971.B \en
972new line
973.TP     
974.B \er
975carriage return
976.TP
977.B \et
978horizontal tab
979.TP   
980.B \ev
981vertical tab
982.TP
983.B \e\e
984backslash
985.TP
986.B \e'
987single quote
988.TP   
989.B \e\fInnn\fP
990the eight-bit character whose value is the octal value \fInnn\fP
991(one to three digits)
992.TP
993.B \ex\fIHH\fP
994the eight-bit character whose value is the hexadecimal value \fIHH\fP
995(one or two hex digits)
996.TP
997.B \ec\fIx\fP
998a control-\fIx\fP character
999.PD
1000.RE
1001.LP
1002The expanded result is single-quoted, as if the dollar sign had
1003not been present.
1004.PP
1005A double-quoted string preceded by a dollar sign (\fB$\fP) will cause
1006the string to be translated according to the current locale.
1007If the current locale is \fBC\fP or \fBPOSIX\fP, the dollar sign
1008is ignored.
1009If the string is translated and replaced, the replacement is
1010double-quoted.
1011.SH PARAMETERS
1012A
1013.I parameter
1014is an entity that stores values.
1015It can be a
1016.IR name ,
1017a number, or one of the special characters listed below under
1018.BR "Special Parameters" .
1019A
1020.I variable
1021is a parameter denoted by a
1022.IR name .
1023A variable has a \fIvalue\fP and zero or more \fIattributes\fP.
1024Attributes are assigned using the
1025.B declare
1026builtin command (see
1027.B declare
1028below in
1029.SM
1030.BR "SHELL BUILTIN COMMANDS" ).
1031.PP
1032A parameter is set if it has been assigned a value.  The null string is
1033a valid value.  Once a variable is set, it may be unset only by using
1034the
1035.B unset
1036builtin command (see
1037.SM
1038.B SHELL BUILTIN COMMANDS
1039below).
1040.PP
1041A
1042.I variable
1043may be assigned to by a statement of the form
1044.RS
1045.PP
1046\fIname\fP=[\fIvalue\fP]
1047.RE
1048.PP
1049If
1050.I value
1051is not given, the variable is assigned the null string.  All
1052.I values
1053undergo tilde expansion, parameter and variable expansion,
1054command substitution, arithmetic expansion, and quote
1055removal (see
1056.SM
1057.B EXPANSION
1058below).  If the variable has its
1059.B integer
1060attribute set, then
1061.I value
1062is evaluated as an arithmetic expression even if the $((...)) expansion is
1063not used (see
1064.B "Arithmetic Expansion"
1065below).
1066Word splitting is not performed, with the exception
1067of \fB"$@"\fP as explained below under
1068.BR "Special Parameters" .
1069Pathname expansion is not performed.
1070Assignment statements may also appear as arguments to the
1071.BR alias ,
1072.BR declare ,
1073.BR typeset ,
1074.BR export ,
1075.BR readonly ,
1076and
1077.B local
1078builtin commands.
1079.SS Positional Parameters
1080.PP
1081A
1082.I positional parameter
1083is a parameter denoted by one or more
1084digits, other than the single digit 0.  Positional parameters are
1085assigned from the shell's arguments when it is invoked,
1086and may be reassigned using the
1087.B set
1088builtin command.  Positional parameters may not be assigned to
1089with assignment statements.  The positional parameters are
1090temporarily replaced when a shell function is executed (see
1091.SM
1092.B FUNCTIONS
1093below).
1094.PP
1095When a positional parameter consisting of more than a single
1096digit is expanded, it must be enclosed in braces (see
1097.SM
1098.B EXPANSION
1099below).
1100.SS Special Parameters
1101.PP
1102The shell treats several parameters specially.  These parameters may
1103only be referenced; assignment to them is not allowed.
1104.PD 0
1105.TP
1106.B *
1107Expands to the positional parameters, starting from one.  When the
1108expansion occurs within double quotes, it expands to a single word
1109with the value of each parameter separated by the first character
1110of the
1111.SM
1112.B IFS
1113special variable.  That is, "\fB$*\fP" is equivalent
1114to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where
1115.I c
1116is the first character of the value of the
1117.SM
1118.B IFS
1119variable.  If
1120.SM
1121.B IFS
1122is unset, the parameters are separated by spaces.
1123If
1124.SM
1125.B IFS
1126is null, the parameters are joined without intervening separators.
1127.TP
1128.B @
1129Expands to the positional parameters, starting from one.  When the
1130expansion occurs within double quotes, each parameter expands to a
1131separate word.  That is, "\fB$@\fP" is equivalent to
1132"\fB$1\fP" "\fB$2\fP" ...
1133When there are no positional parameters, "\fB$@\fP" and
1134.B $@
1135expand to nothing (i.e., they are removed).
1136.TP
1137.B #
1138Expands to the number of positional parameters in decimal.
1139.TP
1140.B ?
1141Expands to the status of the most recently executed foreground
1142pipeline.
1143.TP
1144.B \-
1145Expands to the current option flags as specified upon invocation,
1146by the
1147.B set
1148builtin command, or those set by the shell itself
1149(such as the
1150.B \-i
1151option).
1152.TP
1153.B $
1154Expands to the process ID of the shell.  In a () subshell, it
1155expands to the process ID of the current shell, not the
1156subshell.
1157.TP
1158.B !
1159Expands to the process ID of the most recently executed background
1160(asynchronous) command.
1161.TP
1162.B 0
1163Expands to the name of the shell or shell script.  This is set at
1164shell initialization.  If
1165.B bash
1166is invoked with a file of commands,
1167.B $0
1168is set to the name of that file.  If
1169.B bash
1170is started with the
1171.B \-c
1172option, then
1173.B $0
1174is set to the first argument after the string to be
1175executed, if one is present.  Otherwise, it is set
1176to the file name used to invoke
1177.BR bash ,
1178as given by argument zero.
1179.TP
1180.B _
1181At shell startup, set to the absolute file name of the shell or shell
1182script being executed as passed in the argument list.
1183Subsequently, expands to the last argument to the previous command,
1184after expansion.
1185Also set to the full file name of each command executed and placed in
1186the environment exported to that command.
1187When checking mail, this parameter holds the name of the mail file
1188currently being checked.
1189.PD
1190.SS Shell Variables
1191.PP
1192The following variables are set by the shell:
1193.PP
1194.PD 0
1195.TP
1196.B BASH
1197Expands to the full file name used to invoke this instance of
1198.BR bash .
1199.TP
1200.B BASH_ARGC
1201An array variable whose values are the number of parameters in each
1202frame of the current bash execution call stack.  The number of
1203parameters to the current subroutine (shell function or script executed
1204with \fB.\fP or \fBsource\fP) is at the top of the stack.  When a
1205subroutine is executed, the number of parameters passed is pushed onto
1206\fBBASH_ARGC\fP.
1207.TP
1208.B BASH_ARGV
1209An array variable containing all of the parameters in the current bash
1210execution call stack.  The final parameter of the last subroutine call
1211is at the top of the stack; the first parameter of the initial call is
1212at the bottom.  When a subroutine is executed, the parameters supplied
1213are pushed onto \fBBASH_ARGV\fP.
1214.TP
1215.B BASH_COMMAND
1216The command currently being executed or about to be executed, unless the
1217shell is executing a command as the result of a trap,
1218in which case it is the command executing at the time of the trap.
1219.TP
1220.B BASH_EXECUTION_STRING
1221The command argument to the \fB\-c\fP invocation option.
1222.TP
1223.B BASH_LINENO
1224An array variable whose members are the line numbers in source files
1225corresponding to each member of @var{FUNCNAME}.
1226\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source
1227file where \fB${FUNCNAME[\fP\fI$i + 1\fP\fB]}\fP was called.
1228The corresponding source file name is \fB${BASH_SOURCE[\fP\fI$i + 1\fP\fB]}\fB.
1229Use \fBLINENO\fP to obtain the current line number.
1230.TP
1231.B BASH_REMATCH
1232An array variable whose members are assigned by the \fB=~\fP binary
1233operator to the \fB[[\fP conditional command.
1234The element with index 0 is the portion of the string
1235matching the entire regular expression.
1236The element with index \fIn\fP is the portion of the
1237string matching the \fIn\fPth parenthesized subexpression.
1238This variable is read-only.
1239.TP
1240.B BASH_SOURCE
1241An array variable whose members are the source filenames corresponding
1242to the elements in the \fBFUNCNAME\fP array variable.
1243.TP
1244.B BASH_SUBSHELL
1245Incremented by one each time a subshell or subshell environment is spawned.
1246The initial value is 0.
1247.TP
1248.B BASH_VERSINFO
1249A readonly array variable whose members hold version information for
1250this instance of
1251.BR bash .
1252The values assigned to the array members are as follows:
1253.sp .5
1254.RS
1255.PD 0
1256.TP 24
1257.B BASH_VERSINFO[\fR0\fP]
1258The major version number (the \fIrelease\fP).
1259.TP
1260.B BASH_VERSINFO[\fR1\fP]
1261The minor version number (the \fIversion\fP).
1262.TP
1263.B BASH_VERSINFO[\fR2\fP]
1264The patch level.
1265.TP
1266.B BASH_VERSINFO[\fR3\fP]
1267The build version.
1268.TP
1269.B BASH_VERSINFO[\fR4\fP]
1270The release status (e.g., \fIbeta1\fP).
1271.TP
1272.B BASH_VERSINFO[\fR5\fP]
1273The value of \fBMACHTYPE\fP.
1274.PD
1275.RE
1276.TP
1277.B BASH_VERSION
1278Expands to a string describing the version of this instance of
1279.BR bash .
1280.TP
1281.B COMP_CWORD
1282An index into \fB${COMP_WORDS}\fP of the word containing the current
1283cursor position.
1284This variable is available only in shell functions invoked by the
1285programmable completion facilities (see \fBProgrammable Completion\fP
1286below).
1287.TP
1288.B COMP_LINE
1289The current command line.
1290This variable is available only in shell functions and external
1291commands invoked by the
1292programmable completion facilities (see \fBProgrammable Completion\fP
1293below).
1294.TP
1295.B COMP_POINT
1296The index of the current cursor position relative to the beginning of
1297the current command.
1298If the current cursor position is at the end of the current command,
1299the value of this variable is equal to \fB${#COMP_LINE}\fP.
1300This variable is available only in shell functions and external
1301commands invoked by the
1302programmable completion facilities (see \fBProgrammable Completion\fP
1303below).
1304.TP
1305.B COMP_WORDBREAKS
1306The set of characters that the Readline library treats as word
1307separators when performing word completion.
1308If
1309.SM
1310.B COMP_WORDBREAKS
1311is unset, it loses its special properties, even if it is
1312subsequently reset.
1313.TP
1314.B COMP_WORDS
1315An array variable (see \fBArrays\fP below) consisting of the individual
1316words in the current command line.
1317This variable is available only in shell functions invoked by the
1318programmable completion facilities (see \fBProgrammable Completion\fP
1319below).
1320.TP
1321.B DIRSTACK
1322An array variable (see
1323.B Arrays
1324below) containing the current contents of the directory stack.
1325Directories appear in the stack in the order they are displayed by the
1326.B dirs
1327builtin.
1328Assigning to members of this array variable may be used to modify
1329directories already in the stack, but the
1330.B pushd
1331and
1332.B popd
1333builtins must be used to add and remove directories.
1334Assignment to this variable will not change the current directory.
1335If
1336.SM
1337.B DIRSTACK
1338is unset, it loses its special properties, even if it is
1339subsequently reset.
1340.TP
1341.B EUID
1342Expands to the effective user ID of the current user, initialized at
1343shell startup.  This variable is readonly.
1344.TP
1345.B FUNCNAME
1346An array variable containing the names of all shell functions
1347currently in the execution call stack.
1348The element with index 0 is the name of any currently-executing
1349shell function.
1350The bottom-most element is "main".
1351This variable exists only when a shell function is executing.
1352Assignments to
1353.SM
1354.B FUNCNAME
1355have no effect and return an error status.
1356If
1357.SM
1358.B FUNCNAME
1359is unset, it loses its special properties, even if it is
1360subsequently reset.
1361.TP
1362.B GROUPS
1363An array variable containing the list of groups of which the current
1364user is a member.
1365Assignments to   
1366.SM
1367.B GROUPS
1368have no effect and return an error status.
1369If
1370.SM
1371.B GROUPS
1372is unset, it loses its special properties, even if it is
1373subsequently reset.
1374.TP
1375.B HISTCMD
1376The history number, or index in the history list, of the current
1377command.
1378If
1379.SM
1380.B HISTCMD
1381is unset, it loses its special properties, even if it is
1382subsequently reset.
1383.TP
1384.B HOSTNAME
1385Automatically set to the name of the current host.
1386.TP
1387.B HOSTTYPE
1388Automatically set to a string that uniquely
1389describes the type of machine on which
1390.B bash
1391is executing.
1392The default is system-dependent.
1393.TP
1394.B LINENO
1395Each time this parameter is referenced, the shell substitutes
1396a decimal number representing the current sequential line number
1397(starting with 1) within a script or function.  When not in a
1398script or function, the value substituted is not guaranteed to
1399be meaningful.
1400If
1401.SM
1402.B LINENO
1403is unset, it loses its special properties, even if it is
1404subsequently reset.
1405.TP
1406.B MACHTYPE
1407Automatically set to a string that fully describes the system
1408type on which
1409.B bash
1410is executing, in the standard GNU \fIcpu-company-system\fP format.
1411The default is system-dependent.
1412.TP
1413.B OLDPWD
1414The previous working directory as set by the
1415.B cd
1416command.
1417.TP
1418.B OPTARG
1419The value of the last option argument processed by the
1420.B getopts
1421builtin command (see
1422.SM
1423.B SHELL BUILTIN COMMANDS
1424below).
1425.TP
1426.B OPTIND
1427The index of the next argument to be processed by the
1428.B getopts
1429builtin command (see
1430.SM
1431.B SHELL BUILTIN COMMANDS
1432below).
1433.TP
1434.B OSTYPE
1435Automatically set to a string that
1436describes the operating system on which
1437.B bash
1438is executing.
1439The default is system-dependent.
1440.TP
1441.B PIPESTATUS
1442An array variable (see
1443.B Arrays
1444below) containing a list of exit status values from the processes
1445in the most-recently-executed foreground pipeline (which may
1446contain only a single command).
1447.TP
1448.B PPID
1449The process ID of the shell's parent.  This variable is readonly.
1450.TP
1451.B PWD
1452The current working directory as set by the
1453.B cd
1454command.
1455.TP
1456.B RANDOM
1457Each time this parameter is referenced, a random integer between
14580 and 32767 is
1459generated.  The sequence of random numbers may be initialized by assigning
1460a value to
1461.SM
1462.BR RANDOM .
1463If
1464.SM
1465.B RANDOM
1466is unset, it loses its special properties, even if it is
1467subsequently reset.
1468.TP
1469.B REPLY
1470Set to the line of input read by the
1471.B read
1472builtin command when no arguments are supplied.
1473.TP
1474.B SECONDS
1475Each time this parameter is
1476referenced, the number of seconds since shell invocation is returned.  If a
1477value is assigned to
1478.SM
1479.BR SECONDS ,
1480the value returned upon subsequent
1481references is
1482the number of seconds since the assignment plus the value assigned.
1483If
1484.SM
1485.B SECONDS
1486is unset, it loses its special properties, even if it is
1487subsequently reset.
1488.TP
1489.B SHELLOPTS
1490A colon-separated list of enabled shell options.  Each word in
1491the list is a valid argument for the
1492.B \-o
1493option to the
1494.B set
1495builtin command (see
1496.SM
1497.B "SHELL BUILTIN COMMANDS"
1498below).  The options appearing in
1499.SM
1500.B SHELLOPTS
1501are those reported as
1502.I on
1503by \fBset \-o\fP.
1504If this variable is in the environment when
1505.B bash
1506starts up, each shell option in the list will be enabled before
1507reading any startup files.
1508This variable is read-only.
1509.TP
1510.B SHLVL
1511Incremented by one each time an instance of
1512.B bash
1513is started.
1514.TP
1515.B UID
1516Expands to the user ID of the current user, initialized at shell startup.
1517This variable is readonly.
1518.PD
1519.PP
1520The following variables are used by the shell.  In some cases,
1521.B bash
1522assigns a default value to a variable; these cases are noted
1523below.
1524.PP
1525.PD 0
1526.TP
1527.B BASH_ENV
1528If this parameter is set when \fBbash\fP is executing a shell script,
1529its value is interpreted as a filename containing commands to
1530initialize the shell, as in
1531.IR ~/.bashrc .
1532The value of
1533.SM
1534.B BASH_ENV
1535is subjected to parameter expansion, command substitution, and arithmetic
1536expansion before being interpreted as a file name.
1537.SM
1538.B PATH
1539is not used to search for the resultant file name.
1540.TP
1541.B CDPATH
1542The search path for the
1543.B cd
1544command.
1545This is a colon-separated list of directories in which the shell looks
1546for destination directories specified by the
1547.B cd
1548command.
1549A sample value is
1550.if t \f(CW".:~:/usr"\fP.
1551.if n ".:~:/usr".
1552.TP
1553.B COLUMNS
1554Used by the \fBselect\fP builtin command to determine the terminal width
1555when printing selection lists.  Automatically set upon receipt of a SIGWINCH.
1556.TP
1557.B COMPREPLY
1558An array variable from which \fBbash\fP reads the possible completions
1559generated by a shell function invoked by the programmable completion
1560facility (see \fBProgrammable Completion\fP below).
1561.TP
1562.B EMACS
1563If \fBbash\fP finds this variable in the environment when the shell starts
1564with value
1565.if t \f(CWt\fP,
1566.if n "t",
1567it assumes that the shell is running in an emacs shell buffer and disables
1568line editing.
1569.TP
1570.B FCEDIT
1571The default editor for the
1572.B fc
1573builtin command.
1574.TP
1575.B FIGNORE
1576A colon-separated list of suffixes to ignore when performing
1577filename completion (see
1578.SM
1579.B READLINE
1580below).
1581A filename whose suffix matches one of the entries in
1582.SM
1583.B FIGNORE
1584is excluded from the list of matched filenames.
1585A sample value is
1586.if t \f(CW".o:~"\fP.
1587.if n ".o:~".
1588.TP
1589.B GLOBIGNORE
1590A colon-separated list of patterns defining the set of filenames to
1591be ignored by pathname expansion.
1592If a filename matched by a pathname expansion pattern also matches one
1593of the patterns in
1594.SM
1595.BR GLOBIGNORE ,
1596it is removed from the list of matches.
1597.TP
1598.B HISTCONTROL
1599A colon-separated list of values controlling how commands are saved on
1600the history list.
1601If the list of values includes
1602.IR ignorespace ,
1603lines which begin with a
1604.B space
1605character are not saved in the history list.
1606A value of
1607.I ignoredups
1608causes lines matching the previous history entry to not be saved.
1609A value of
1610.I ignoreboth
1611is shorthand for \fIignorespace\fP and \fIignoredups\fP.
1612A value of
1613.IR erasedups
1614causes all previous lines matching the current line to be removed from
1615the history list before that line is saved.
1616Any value not in the above list is ignored.
1617If \fBHISTCONTROL\fP is unset, or does not include a valid value,
1618all lines read by the shell parser are saved on the history list,
1619subject to the value of
1620.BR HISTIGNORE .
1621The second and subsequent lines of a multi-line compound command are
1622not tested, and are added to the history regardless of the value of
1623.BR HISTCONTROL .
1624.TP
1625.B HISTFILE
1626The name of the file in which command history is saved (see
1627.SM
1628.B HISTORY
1629below).  The default value is \fI~/.bash_history\fP.  If unset, the
1630command history is not saved when an interactive shell exits.
1631.TP
1632.B HISTFILESIZE
1633The maximum number of lines contained in the history file.  When this
1634variable is assigned a value, the history file is truncated, if
1635necessary, to contain no more than that number of lines.  The default
1636value is 500.  The history file is also truncated to this size after
1637writing it when an interactive shell exits.
1638.TP
1639.B HISTIGNORE
1640A colon-separated list of patterns used to decide which command lines
1641should be saved on the history list.  Each pattern is anchored at the
1642beginning of the line and must match the complete line (no implicit
1643`\fB*\fP' is appended).  Each pattern is tested against the line
1644after the checks specified by
1645.B HISTCONTROL
1646are applied.
1647In addition to the normal shell pattern matching characters, `\fB&\fP'
1648matches the previous history line.  `\fB&\fP' may be escaped using a
1649backslash; the backslash is removed before attempting a match.
1650The second and subsequent lines of a multi-line compound command are
1651not tested, and are added to the history regardless of the value of
1652.BR HISTIGNORE .
1653.TP
1654.B HISTSIZE
1655The number of commands to remember in the command history (see
1656.SM
1657.B HISTORY
1658below).  The default value is 500.
1659.TP
1660.B HISTTIMEFORMAT
1661If this variable is set and not null, its value is used as a format string
1662for \fIstrftime\fP(3) to print the time stamp associated with each history
1663entry displayed by the \fBhistory\fP builtin.
1664If this variable is set, time stamps are written to the history file so
1665they may be preserved across shell sessions.
1666.TP
1667.B HOME
1668The home directory of the current user; the default argument for the
1669\fBcd\fP builtin command.
1670The value of this variable is also used when performing tilde expansion.
1671.TP
1672.B HOSTFILE
1673Contains the name of a file in the same format as
1674.FN /etc/hosts
1675that should be read when the shell needs to complete a
1676hostname.
1677The list of possible hostname completions may be changed while the
1678shell is running;
1679the next time hostname completion is attempted after the
1680value is changed,
1681.B bash
1682adds the contents of the new file to the existing list.
1683If
1684.SM
1685.B HOSTFILE
1686is set, but has no value, \fBbash\fP attempts to read
1687.FN /etc/hosts
1688to obtain the list of possible hostname completions.
1689When
1690.SM
1691.B HOSTFILE
1692is unset, the hostname list is cleared.
1693.TP
1694.B IFS
1695The
1696.I Internal Field Separator
1697that is used
1698for word splitting after expansion and to
1699split lines into words with the
1700.B read
1701builtin command.  The default value is
1702``<space><tab><newline>''.
1703.TP
1704.B IGNOREEOF
1705Controls the
1706action of an interactive shell on receipt of an
1707.SM
1708.B EOF
1709character as the sole input.  If set, the value is the number of
1710consecutive
1711.SM
1712.B EOF
1713characters which must be
1714typed as the first characters on an input line before
1715.B bash
1716exits.  If the variable exists but does not have a numeric value, or
1717has no value, the default value is 10.  If it does not exist,
1718.SM
1719.B EOF
1720signifies the end of input to the shell.
1721.TP
1722.B INPUTRC
1723The filename for the
1724.B readline
1725startup file, overriding the default of
1726.FN ~/.inputrc
1727(see
1728.SM
1729.B READLINE
1730below).
1731.TP
1732.B LANG
1733Used to determine the locale category for any category not specifically
1734selected with a variable starting with \fBLC_\fP.
1735.TP
1736.B LC_ALL
1737This variable overrides the value of \fBLANG\fP and any other
1738\fBLC_\fP variable specifying a locale category.
1739.TP
1740.B LC_COLLATE
1741This variable determines the collation order used when sorting the
1742results of pathname expansion, and determines the behavior of range
1743expressions, equivalence classes, and collating sequences within
1744pathname expansion and pattern matching.
1745.TP
1746.B LC_CTYPE
1747This variable determines the interpretation of characters and the
1748behavior of character classes within pathname expansion and pattern
1749matching.
1750.TP
1751.B LC_MESSAGES
1752This variable determines the locale used to translate double-quoted
1753strings preceded by a \fB$\fP.
1754.TP
1755.B LC_NUMERIC
1756This variable determines the locale category used for number formatting.
1757.TP
1758.B LINES
1759Used by the \fBselect\fP builtin command to determine the column length
1760for printing selection lists.  Automatically set upon receipt of a SIGWINCH.
1761.TP
1762.B MAIL
1763If this parameter is set to a file name and the
1764.SM
1765.B MAILPATH
1766variable is not set,
1767.B bash
1768informs the user of the arrival of mail in the specified file.
1769.TP
1770.B MAILCHECK
1771Specifies how
1772often (in seconds)
1773.B bash
1774checks for mail.  The default is 60 seconds.  When it is time to check
1775for mail, the shell does so before displaying the primary prompt.
1776If this variable is unset, or set to a value that is not a number
1777greater than or equal to zero, the shell disables mail checking.
1778.TP
1779.B MAILPATH
1780A colon-separated list of file names to be checked for mail.
1781The message to be printed when mail arrives in a particular file
1782may be specified by separating the file name from the message with a `?'.
1783When used in the text of the message, \fB$_\fP expands to the name of
1784the current mailfile.
1785Example:
1786.RS
1787.PP
1788\fBMAILPATH\fP='/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"'
1789.PP
1790.B Bash
1791supplies a default value for this variable, but the location of the user
1792mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP).
1793.RE
1794.TP
1795.B OPTERR
1796If set to the value 1,
1797.B bash
1798displays error messages generated by the
1799.B getopts
1800builtin command (see
1801.SM
1802.B SHELL BUILTIN COMMANDS
1803below).
1804.SM
1805.B OPTERR
1806is initialized to 1 each time the shell is invoked or a shell
1807script is executed.
1808.TP
1809.B PATH
1810The search path for commands.  It
1811is a colon-separated list of directories in which
1812the shell looks for commands (see
1813.SM
1814.B COMMAND EXECUTION
1815below).
1816A zero-length (null) directory name in the value of \fBPATH\fP indicates the
1817current directory.
1818A null directory name may appear as two adjacent colons, or as an initial
1819or trailing colon.
1820The default path is system-dependent,
1821and is set by the administrator who installs
1822.BR bash .
1823A common value is
1824.if t \f(CW/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin\fP.
1825.if n ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin''.
1826.TP
1827.B POSIXLY_CORRECT
1828If this variable is in the environment when \fBbash\fP starts, the shell
1829enters \fIposix mode\fP before reading the startup files, as if the
1830.B \-\-posix
1831invocation option had been supplied.  If it is set while the shell is
1832running, \fBbash\fP enables \fIposix mode\fP, as if the command
1833.if t \f(CWset -o posix\fP
1834.if n \fIset -o posix\fP
1835had been executed.
1836.TP
1837.B PROMPT_COMMAND
1838If set, the value is executed as a command prior to issuing each primary
1839prompt.
1840.TP
1841.B PS1
1842The value of this parameter is expanded (see
1843.SM
1844.B PROMPTING
1845below) and used as the primary prompt string.  The default value is
1846``\fB\es\-\ev\e$ \fP''.
1847.TP
1848.B PS2
1849The value of this parameter is expanded as with
1850.B PS1
1851and used as the secondary prompt string.  The default is
1852``\fB> \fP''.
1853.TP
1854.B PS3
1855The value of this parameter is used as the prompt for the
1856.B select
1857command (see
1858.SM
1859.B SHELL GRAMMAR
1860above).
1861.TP
1862.B PS4
1863The value of this parameter is expanded as with
1864.B PS1
1865and the value is printed before each command
1866.B bash
1867displays during an execution trace.  The first character of
1868.SM
1869.B PS4
1870is replicated multiple times, as necessary, to indicate multiple
1871levels of indirection.  The default is ``\fB+ \fP''.
1872.TP
1873.B SHELL
1874The full pathname to the shell is kept in this environment variable.
1875If it is not set when the shell starts,
1876.B bash
1877assigns to it the full pathname of the current user's login shell.
1878.TP
1879.B TIMEFORMAT
1880The value of this parameter is used as a format string specifying
1881how the timing information for pipelines prefixed with the
1882.B time
1883reserved word should be displayed.
1884The \fB%\fP character introduces an escape sequence that is
1885expanded to a time value or other information.
1886The escape sequences and their meanings are as follows; the
1887braces denote optional portions.
1888.sp .5
1889.RS
1890.PD 0
1891.TP 10
1892.B %%
1893A literal \fB%\fP.
1894.TP
1895.B %[\fIp\fP][l]R
1896The elapsed time in seconds.
1897.TP
1898.B %[\fIp\fP][l]U
1899The number of CPU seconds spent in user mode.
1900.TP
1901.B %[\fIp\fP][l]S
1902The number of CPU seconds spent in system mode.
1903.TP
1904.B %P
1905The CPU percentage, computed as (%U + %S) / %R.
1906.PD
1907.RE
1908.IP
1909The optional \fIp\fP is a digit specifying the \fIprecision\fP,
1910the number of fractional digits after a decimal point.
1911A value of 0 causes no decimal point or fraction to be output.
1912At most three places after the decimal point may be specified;
1913values of \fIp\fP greater than 3 are changed to 3.
1914If \fIp\fP is not specified, the value 3 is used.
1915.IP
1916The optional \fBl\fP specifies a longer format, including
1917minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs.
1918The value of \fIp\fP determines whether or not the fraction is
1919included.
1920.IP
1921If this variable is not set, \fBbash\fP acts as if it had the
1922value \fB$'\enreal\et%3lR\enuser\et%3lU\ensys\t%3lS'\fP.
1923If the value is null, no timing information is displayed.
1924A trailing newline is added when the format string is displayed.
1925.TP
1926.B TMOUT
1927If set to a value greater than zero, \fBTMOUT\fP is treated as the
1928default timeout for the \fBread\fP builtin.
1929The \fBselect\fP command terminates if input does not arrive
1930after \fBTMOUT\fP seconds when input is coming from a terminal.
1931In an interactive shell, the value is interpreted as the
1932number of seconds to wait for input after issuing the primary prompt.
1933.B Bash
1934terminates after waiting for that number of seconds if input does
1935not arrive.
1936.TP
1937.B auto_resume
1938This variable controls how the shell interacts with the user and
1939job control.  If this variable is set, single word simple
1940commands without redirections are treated as candidates for resumption
1941of an existing stopped job.  There is no ambiguity allowed; if there is
1942more than one job beginning with the string typed, the job most recently
1943accessed is selected.  The
1944.I name
1945of a stopped job, in this context, is the command line used to
1946start it.
1947If set to the value
1948.IR exact ,
1949the string supplied must match the name of a stopped job exactly;
1950if set to
1951.IR substring ,
1952the string supplied needs to match a substring of the name of a
1953stopped job.  The
1954.I substring
1955value provides functionality analogous to the
1956.B %?
1957job identifier (see
1958.SM
1959.B JOB CONTROL
1960below).  If set to any other value, the supplied string must
1961be a prefix of a stopped job's name; this provides functionality
1962analogous to the
1963.B %
1964job identifier.
1965.TP
1966.B histchars
1967The two or three characters which control history expansion
1968and tokenization (see
1969.SM
1970.B HISTORY EXPANSION
1971below).  The first character is the \fIhistory expansion\fP character,
1972the character which signals the start of a history
1973expansion, normally `\fB!\fP'.
1974The second character is the \fIquick substitution\fP
1975character, which is used as shorthand for re-running the previous
1976command entered, substituting one string for another in the command.
1977The default is `\fB^\fP'.
1978The optional third character is the character
1979which indicates that the remainder of the line is a comment when found
1980as the first character of a word, normally `\fB#\fP'.  The history
1981comment character causes history substitution to be skipped for the
1982remaining words on the line.  It does not necessarily cause the shell
1983parser to treat the rest of the line as a comment.
1984.PD
1985.SS Arrays
1986.B Bash
1987provides one-dimensional array variables.  Any variable may be used as
1988an array; the
1989.B declare
1990builtin will explicitly declare an array.  There is no maximum
1991limit on the size of an array, nor any requirement that members
1992be indexed or assigned contiguously.  Arrays are indexed using
1993integers and are zero-based.
1994.PP
1995An array is created automatically if any variable is assigned to using
1996the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP.  The
1997.I subscript
1998is treated as an arithmetic expression that must evaluate to a number
1999greater than or equal to zero.  To explicitly declare an array, use
2000.B declare \-a \fIname\fP
2001(see
2002.SM
2003.B SHELL BUILTIN COMMANDS
2004below).
2005.B declare \-a \fIname\fP[\fIsubscript\fP]
2006is also accepted; the \fIsubscript\fP is ignored.  Attributes may be
2007specified for an array variable using the
2008.B declare
2009and
2010.B readonly
2011builtins.  Each attribute applies to all members of an array.
2012.PP
2013Arrays are assigned to using compound assignments of the form
2014\fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each
2015\fIvalue\fP is of the form [\fIsubscript\fP]=\fIstring\fP.  Only
2016\fIstring\fP is required.  If
2017the optional brackets and subscript are supplied, that index is assigned to;
2018otherwise the index of the element assigned is the last index assigned
2019to by the statement plus one.  Indexing starts at zero.
2020This syntax is also accepted by the
2021.B declare
2022builtin.  Individual array elements may be assigned to using the
2023\fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above.
2024.PP
2025Any element of an array may be referenced using
2026${\fIname\fP[\fIsubscript\fP]}.  The braces are required to avoid
2027conflicts with pathname expansion.  If
2028\fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to
2029all members of \fIname\fP.  These subscripts differ only when the
2030word appears within double quotes.  If the word is double-quoted,
2031${\fIname\fP[*]} expands to a single
2032word with the value of each array member separated by the first
2033character of the
2034.SM
2035.B IFS
2036special variable, and ${\fIname\fP[@]} expands each element of
2037\fIname\fP to a separate word.  When there are no array members,
2038${\fIname\fP[@]} expands to nothing.  This is analogous to the expansion
2039of the special parameters \fB*\fP and \fB@\fP (see
2040.B Special Parameters
2041above).  ${#\fIname\fP[\fIsubscript\fP]} expands to the length of
2042${\fIname\fP[\fIsubscript\fP]}.  If \fIsubscript\fP is \fB*\fP or
2043\fB@\fP, the expansion is the number of elements in the array.
2044Referencing an array variable without a subscript is equivalent to
2045referencing element zero.
2046.PP
2047The
2048.B unset
2049builtin is used to destroy arrays.  \fBunset\fP \fIname\fP[\fIsubscript\fP]
2050destroys the array element at index \fIsubscript\fP.
2051\fBunset\fP \fIname\fP, where \fIname\fP is an array, or
2052\fBunset\fP \fIname\fP[\fIsubscript\fP], where
2053\fIsubscript\fP is \fB*\fP or \fB@\fP, removes the entire array.
2054.PP
2055The
2056.BR declare ,
2057.BR local ,
2058and
2059.B readonly
2060builtins each accept a
2061.B \-a
2062option to specify an array.  The
2063.B read
2064builtin accepts a
2065.B \-a
2066option to assign a list of words read from the standard input
2067to an array.  The
2068.B set
2069and
2070.B declare
2071builtins display array values in a way that allows them to be
2072reused as assignments.
2073.SH EXPANSION
2074Expansion is performed on the command line after it has been split into
2075words.  There are seven kinds of expansion performed:
2076.IR "brace expansion" ,
2077.IR "tilde expansion" ,
2078.IR "parameter and variable expansion" ,
2079.IR "command substitution" ,
2080.IR "arithmetic expansion" ,
2081.IR "word splitting" ,
2082and
2083.IR "pathname expansion" .
2084.PP
2085The order of expansions is: brace expansion, tilde expansion,
2086parameter, variable and arithmetic expansion and
2087command substitution
2088(done in a left-to-right fashion), word splitting, and pathname
2089expansion.
2090.PP
2091On systems that can support it, there is an additional expansion
2092available: \fIprocess substitution\fP.
2093.PP
2094Only brace expansion, word splitting, and pathname expansion
2095can change the number of words of the expansion; other expansions
2096expand a single word to a single word.
2097The only exceptions to this are the expansions of
2098"\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP"
2099as explained above (see
2100.SM
2101.BR PARAMETERS ).
2102.SS Brace Expansion
2103.PP
2104.I "Brace expansion"
2105is a mechanism by which arbitrary strings
2106may be generated.  This mechanism is similar to
2107\fIpathname expansion\fP, but the filenames generated
2108need not exist.  Patterns to be brace expanded take
2109the form of an optional
2110.IR preamble ,
2111followed by either a series of comma-separated strings or
2112a sequence expression between a pair of braces, followed by
2113an optional
2114.IR postscript .
2115The preamble is prefixed to each string contained
2116within the braces, and the postscript is then appended
2117to each resulting string, expanding left to right.
2118.PP
2119Brace expansions may be nested.  The results of each expanded
2120string are not sorted; left to right order is preserved.
2121For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'.
2122.PP
2123A sequence expression takes the form \fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB}\fP,
2124where \fIx\fP and \fIy\fP are either integers or single characters.
2125When integers are supplied, the expression expands to each number between
2126\fIx\fP and \fIy\fP, inclusive.
2127When characters are supplied, the expression expands to each character
2128lexicographically between \fIx\fP and \fIy\fP, inclusive.  Note that
2129both \fIx\fP and \fIy\fP must be of the same type.
2130.PP
2131Brace expansion is performed before any other expansions,
2132and any characters special to other expansions are preserved
2133in the result.  It is strictly textual.
2134.B Bash
2135does not apply any syntactic interpretation to the context of the
2136expansion or the text between the braces.
2137.PP
2138A correctly-formed brace expansion must contain unquoted opening
2139and closing braces, and at least one unquoted comma or a valid
2140sequence expression.
2141Any incorrectly formed brace expansion is left unchanged.
2142A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its
2143being considered part of a brace expression.
2144To avoid conflicts with parameter expansion, the string \fB${\fP
2145is not considered eligible for brace expansion.
2146.PP
2147This construct is typically used as shorthand when the common
2148prefix of the strings to be generated is longer than in the
2149above example:
2150.RS
2151.PP
2152mkdir /usr/local/src/bash/{old,new,dist,bugs}
2153.RE
2154or
2155.RS
2156chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
2157.RE
2158.PP
2159Brace expansion introduces a slight incompatibility with
2160historical versions of
2161.BR sh .
2162.B sh
2163does not treat opening or closing braces specially when they
2164appear as part of a word, and preserves them in the output.
2165.B Bash
2166removes braces from words as a consequence of brace
2167expansion.  For example, a word entered to
2168.B sh
2169as \fIfile{1,2}\fP
2170appears identically in the output.  The same word is
2171output as
2172.I file1 file2
2173after expansion by
2174.BR bash .
2175If strict compatibility with
2176.B sh
2177is desired, start
2178.B bash
2179with the
2180.B +B
2181option or disable brace expansion with the
2182.B +B
2183option to the
2184.B set
2185command (see
2186.SM
2187.B SHELL BUILTIN COMMANDS
2188below).
2189.SS Tilde Expansion
2190.PP
2191If a word begins with an unquoted tilde character (`\fB~\fP'), all of
2192the characters preceding the first unquoted slash (or all characters,
2193if there is no unquoted slash) are considered a \fItilde-prefix\fP.
2194If none of the characters in the tilde-prefix are quoted, the
2195characters in the tilde-prefix following the tilde are treated as a
2196possible \fIlogin name\fP.
2197If this login name is the null string, the tilde is replaced with the
2198value of the shell parameter
2199.SM
2200.BR HOME .
2201If
2202.SM
2203.B HOME
2204is unset, the home directory of the user executing the shell is
2205substituted instead.
2206Otherwise, the tilde-prefix is replaced with the home directory
2207associated with the specified login name.
2208.PP
2209If the tilde-prefix is a `~+', the value of the shell variable
2210.SM
2211.B PWD
2212replaces the tilde-prefix.
2213If the tilde-prefix is a `~\-', the value of the shell variable
2214.SM
2215.BR OLDPWD ,
2216if it is set, is substituted.
2217If the characters following the tilde in the tilde-prefix consist
2218of a number \fIN\fP, optionally prefixed
2219by a `+' or a `\-', the tilde-prefix is replaced with the corresponding
2220element from the directory stack, as it would be displayed by the
2221.B dirs
2222builtin invoked with the tilde-prefix as an argument.
2223If the characters following the tilde in the tilde-prefix consist of a
2224number without a leading `+' or `\-', `+' is assumed.
2225.PP
2226If the login name is invalid, or the tilde expansion fails, the word
2227is unchanged.
2228.PP
2229Each variable assignment is checked for unquoted tilde-prefixes immediately
2230following a
2231.B :
2232or
2233.BR = .
2234In these cases, tilde expansion is also performed.
2235Consequently, one may use file names with tildes in assignments to
2236.SM
2237.BR PATH ,
2238.SM
2239.BR MAILPATH ,
2240and
2241.SM
2242.BR CDPATH ,
2243and the shell assigns the expanded value.
2244.SS Parameter Expansion
2245.PP
2246The `\fB$\fP' character introduces parameter expansion,
2247command substitution, or arithmetic expansion.  The parameter name
2248or symbol to be expanded may be enclosed in braces, which
2249are optional but serve to protect the variable to be expanded from
2250characters immediately following it which could be
2251interpreted as part of the name.
2252.PP
2253When braces are used, the matching ending brace is the first `\fB}\fP'
2254not escaped by a backslash or within a quoted string, and not within an
2255embedded arithmetic expansion, command substitution, or paramter
2256expansion.
2257.PP
2258.PD 0
2259.TP
2260${\fIparameter\fP}
2261The value of \fIparameter\fP is substituted.  The braces are required
2262when
2263.I parameter
2264is a positional parameter with more than one digit,
2265or when
2266.I parameter
2267is followed by a character which is not to be
2268interpreted as part of its name.
2269.PD
2270.PP
2271If the first character of \fIparameter\fP is an exclamation point,
2272a level of variable indirection is introduced.
2273\fBBash\fP uses the value of the variable formed from the rest of
2274\fIparameter\fP as the name of the variable; this variable is then
2275expanded and that value is used in the rest of the substitution, rather
2276than the value of \fIparameter\fP itself.
2277This is known as \fIindirect expansion\fP.
2278The exceptions to this are the expansions of ${!\fIprefix\fP*} and
2279${\fB!\fP\fIname\fP[\fI@\fP]} described below.
2280The exclamation point must immediately follow the left brace in order to
2281introduce indirection.
2282.PP
2283In each of the cases below, \fIword\fP is subject to tilde expansion,
2284parameter expansion, command substitution, and arithmetic expansion.
2285When not performing substring expansion, \fBbash\fP tests for a parameter
2286that is unset or null; omitting the colon results in a test only for a
2287parameter that is unset.
2288.PP
2289.PD 0
2290.TP
2291${\fIparameter\fP\fB:\-\fP\fIword\fP}
2292\fBUse Default Values\fP.  If
2293.I parameter
2294is unset or null, the expansion of
2295.I word
2296is substituted.  Otherwise, the value of
2297.I parameter
2298is substituted.
2299.TP
2300${\fIparameter\fP\fB:=\fP\fIword\fP}
2301\fBAssign Default Values\fP.
2302If
2303.I parameter
2304is unset or null, the expansion of
2305.I word
2306is assigned to
2307.IR parameter .
2308The value of
2309.I parameter
2310is then substituted.  Positional parameters and special parameters may
2311not be assigned to in this way.
2312.TP
2313${\fIparameter\fP\fB:?\fP\fIword\fP}
2314\fBDisplay Error if Null or Unset\fP.
2315If
2316.I parameter
2317is null or unset, the expansion of \fIword\fP (or a message to that effect
2318if
2319.I word
2320is not present) is written to the standard error and the shell, if it
2321is not interactive, exits.  Otherwise, the value of \fIparameter\fP is
2322substituted.
2323.TP
2324${\fIparameter\fP\fB:+\fP\fIword\fP}
2325\fBUse Alternate Value\fP.
2326If
2327.I parameter
2328is null or unset, nothing is substituted, otherwise the expansion of
2329.I word
2330is substituted.
2331.TP
2332${\fIparameter\fP\fB:\fP\fIoffset\fP}
2333.PD 0
2334.TP
2335${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
2336.PD
2337\fBSubstring Expansion.\fP
2338Expands to up to \fIlength\fP characters of \fIparameter\fP
2339starting at the character specified by \fIoffset\fP.
2340If \fIlength\fP is omitted, expands to the substring of
2341\fIparameter\fP starting at the character specified by \fIoffset\fP.
2342\fIlength\fP and \fIoffset\fP are arithmetic expressions (see
2343.SM
2344.B
2345ARITHMETIC EVALUATION
2346below).
2347\fIlength\fP must evaluate to a number greater than or equal to zero.
2348If \fIoffset\fP evaluates to a number less than zero, the value
2349is used as an offset from the end of the value of \fIparameter\fP.
2350If \fIparameter\fP is \fB@\fP, the result is \fIlength\fP positional
2351parameters beginning at \fIoffset\fP.
2352If \fIparameter\fP is an array name indexed by @ or *,
2353the result is the \fIlength\fP
2354members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
2355Substring indexing is zero-based unless the positional parameters
2356are used, in which case the indexing starts at 1.
2357.TP
2358${\fB!\fP\fIprefix\fP\fB*\fP}
2359.PD 0
2360.TP
2361${\fB!\fP\fIprefix\fP\fB@\fP}
2362.PD
2363Expands to the names of variables whose names begin with \fIprefix\fP,
2364separated by the first character of the
2365.SM
2366.B IFS
2367special variable.
2368.TP
2369${\fB!\fP\fIname\fP[\fI@\fP]}
2370.PD 0
2371.TP
2372${\fB!\fP\fIname\fP[\fI*\fP]}
2373.PD
2374If \fIname\fP is an array variable, expands to the list of array indices
2375(keys) assigned in \fIname\fP.
2376If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null
2377otherwise.
2378When \fI@\fP is used and the expansion appears within double quotes, each
2379key expands to a separate word.
2380.TP
2381${\fB#\fP\fIparameter\fP}
2382The length in characters of the value of \fIparameter\fP is substituted.
2383If
2384.I parameter
2385is
2386.B *
2387or
2388.BR @ ,
2389the value substituted is the number of positional parameters.
2390If
2391.I parameter
2392is an array name subscripted by
2393.B *
2394or
2395.BR @ ,
2396the value substituted is the number of elements in the array.
2397.TP
2398${\fIparameter\fP\fB#\fP\fIword\fP}
2399.PD 0
2400.TP
2401${\fIparameter\fP\fB##\fP\fIword\fP}
2402.PD
2403The
2404.I word
2405is expanded to produce a pattern just as in pathname
2406expansion.  If the pattern matches the beginning of
2407the value of
2408.IR parameter ,
2409then the result of the expansion is the expanded value of
2410.I parameter
2411with the shortest matching pattern (the ``\fB#\fP'' case) or the
2412longest matching pattern (the ``\fB##\fP'' case) deleted.
2413If
2414.I parameter
2415is
2416.B @
2417or
2418.BR * ,
2419the pattern removal operation is applied to each positional
2420parameter in turn, and the expansion is the resultant list.
2421If
2422.I parameter
2423is an array variable subscripted with
2424.B @
2425or
2426.BR * ,
2427the pattern removal operation is applied to each member of the
2428array in turn, and the expansion is the resultant list.
2429.TP
2430${\fIparameter\fP\fB%\fP\fIword\fP}
2431.PD 0
2432.TP
2433${\fIparameter\fP\fB%%\fP\fIword\fP}
2434.PD
2435The \fIword\fP is expanded to produce a pattern just as in
2436pathname expansion.
2437If the pattern matches a trailing portion of the expanded value of
2438.IR parameter ,
2439then the result of the expansion is the expanded value of
2440.I parameter
2441with the shortest matching pattern (the ``\fB%\fP'' case) or the
2442longest matching pattern (the ``\fB%%\fP'' case) deleted.
2443If
2444.I parameter
2445is
2446.B @
2447or
2448.BR * ,
2449the pattern removal operation is applied to each positional
2450parameter in turn, and the expansion is the resultant list.
2451If
2452.I parameter
2453is an array variable subscripted with
2454.B @
2455or
2456.BR * ,
2457the pattern removal operation is applied to each member of the
2458array in turn, and the expansion is the resultant list.
2459.TP
2460${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
2461.PD 0
2462.TP
2463${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP}
2464.PD
2465The \fIpattern\fP is expanded to produce a pattern just as in
2466pathname expansion.
2467\fIParameter\fP is expanded and the longest match of \fIpattern\fP
2468against its value is replaced with \fIstring\fP.
2469In the first form, only the first match is replaced.
2470The second form causes all matches of \fIpattern\fP to be
2471replaced with \fIstring\fP.
2472If \fIpattern\fP begins with \fB#\fP, it must match at the beginning
2473of the expanded value of \fIparameter\fP.
2474If \fIpattern\fP begins with \fB%\fP, it must match at the end
2475of the expanded value of \fIparameter\fP.
2476If \fIstring\fP is null, matches of \fIpattern\fP are deleted
2477and the \fB/\fP following \fIpattern\fP may be omitted.
2478If
2479.I parameter
2480is
2481.B @
2482or
2483.BR * ,
2484the substitution operation is applied to each positional
2485parameter in turn, and the expansion is the resultant list.
2486If
2487.I parameter
2488is an array variable subscripted with
2489.B @
2490or
2491.BR * ,
2492the substitution operation is applied to each member of the
2493array in turn, and the expansion is the resultant list.
2494.SS Command Substitution
2495.PP
2496\fICommand substitution\fP allows the output of a command to replace
2497the command name.  There are two forms:
2498.PP
2499.RS
2500.PP
2501\fB$(\fP\fIcommand\fP\|\fB)\fP
2502.RE
2503or
2504.RS
2505\fB`\fP\fIcommand\fP\fB`\fP
2506.RE
2507.PP
2508.B Bash
2509performs the expansion by executing \fIcommand\fP and
2510replacing the command substitution with the standard output of the
2511command, with any trailing newlines deleted.
2512Embedded newlines are not deleted, but they may be removed during
2513word splitting.
2514The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by
2515the equivalent but faster \fB$(< \fIfile\fP)\fR.
2516.PP
2517When the old-style backquote form of substitution is used,
2518backslash retains its literal meaning except when followed by
2519.BR $ ,
2520.BR ` ,
2521or
2522.BR \e .
2523The first backquote not preceded by a backslash terminates the
2524command substitution.
2525When using the $(\^\fIcommand\fP\|) form, all characters between the
2526parentheses make up the command; none are treated specially.
2527.PP
2528Command substitutions may be nested.  To nest when using the backquoted form,
2529escape the inner backquotes with backslashes.
2530.PP
2531If the substitution appears within double quotes, word splitting and
2532pathname expansion are not performed on the results.
2533.SS Arithmetic Expansion
2534.PP
2535Arithmetic expansion allows the evaluation of an arithmetic expression
2536and the substitution of the result.  The format for arithmetic expansion is:
2537.RS
2538.PP
2539\fB$((\fP\fIexpression\fP\fB))\fP
2540.RE
2541.PP
2542The
2543.I expression
2544is treated as if it were within double quotes, but a double quote
2545inside the parentheses is not treated specially.
2546All tokens in the expression undergo parameter expansion, string
2547expansion, command substitution, and quote removal.
2548Arithmetic expansions may be nested.
2549.PP
2550The evaluation is performed according to the rules listed below under
2551.SM
2552.BR "ARITHMETIC EVALUATION" .
2553If
2554.I expression
2555is invalid,
2556.B bash
2557prints a message indicating failure and no substitution occurs.
2558.SS Process Substitution
2559.PP
2560\fIProcess substitution\fP is supported on systems that support named
2561pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files.
2562It takes the form of
2563\fB<(\fP\fIlist\^\fP\fB)\fP
2564or
2565\fB>(\fP\fIlist\^\fP\fB)\fP.
2566The process \fIlist\fP is run with its input or output connected to a
2567\fIFIFO\fP or some file in \fB/dev/fd\fP.  The name of this file is
2568passed as an argument to the current command as the result of the
2569expansion.  If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
2570the file will provide input for \fIlist\fP.  If the
2571\fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an
2572argument should be read to obtain the output of \fIlist\fP.
2573.PP
2574When available, process substitution is performed
2575simultaneously with parameter and variable expansion,
2576command substitution,
2577and arithmetic expansion.
2578.SS Word Splitting
2579.PP
2580The shell scans the results of
2581parameter expansion,
2582command substitution,
2583and
2584arithmetic expansion
2585that did not occur within double quotes for
2586.IR "word splitting" .
2587.PP
2588The shell treats each character of
2589.SM
2590.B IFS
2591as a delimiter, and splits the results of the other
2592expansions into words on these characters.  If
2593.SM
2594.B IFS
2595is unset, or its
2596value is exactly
2597.BR <space><tab><newline> ,
2598the default, then
2599any sequence of
2600.SM
2601.B IFS
2602characters serves to delimit words.  If
2603.SM
2604.B IFS
2605has a value other than the default, then sequences of
2606the whitespace characters
2607.B space
2608and
2609.B tab
2610are ignored at the beginning and end of the
2611word, as long as the whitespace character is in the
2612value of
2613.SM
2614.BR IFS
2615(an
2616.SM
2617.B IFS
2618whitespace character).
2619Any character in
2620.SM
2621.B IFS
2622that is not
2623.SM
2624.B IFS
2625whitespace, along with any adjacent
2626.SM
2627.B IFS
2628whitespace characters, delimits a field.
2629A sequence of
2630.SM
2631.B IFS
2632whitespace characters is also treated as a delimiter.
2633If the value of
2634.SM
2635.B IFS
2636is null, no word splitting occurs.
2637.PP
2638Explicit null arguments (\^\f3"\^"\fP or \^\f3'\^'\fP\^) are retained.
2639Unquoted implicit null arguments, resulting from the expansion of
2640parameters that have no values, are removed.
2641If a parameter with no value is expanded within double quotes, a
2642null argument results and is retained.
2643.PP
2644Note that if no expansion occurs, no splitting
2645is performed.
2646.SS Pathname Expansion
2647.PP
2648After word splitting,
2649unless the
2650.B \-f
2651option has been set,
2652.B bash
2653scans each word for the characters
2654.BR * ,
2655.BR ? ,
2656and
2657.BR [ .
2658If one of these characters appears, then the word is
2659regarded as a
2660.IR pattern ,
2661and replaced with an alphabetically sorted list of
2662file names matching the pattern.
2663If no matching file names are found,
2664and the shell option
2665.B nullglob
2666is disabled, the word is left unchanged.
2667If the
2668.B nullglob
2669option is set, and no matches are found,
2670the word is removed.
2671If the
2672.B failglob
2673shell option is set, and no matches are found, an error message
2674is printed and the command is not executed.
2675If the shell option
2676.B nocaseglob
2677is enabled, the match is performed without regard to the case
2678of alphabetic characters.
2679When a pattern is used for pathname expansion,
2680the character
2681.B ``.''
2682at the start of a name or immediately following a slash
2683must be matched explicitly, unless the shell option
2684.B dotglob
2685is set.
2686When matching a pathname, the slash character must always be
2687matched explicitly.
2688In other cases, the
2689.B ``.''
2690character is not treated specially.
2691See the description of
2692.B shopt
2693below under
2694.SM
2695.B SHELL BUILTIN COMMANDS
2696for a description of the
2697.BR nocaseglob ,
2698.BR nullglob ,
2699.BR failglob ,
2700and
2701.B dotglob
2702shell options.
2703.PP
2704The
2705.SM
2706.B GLOBIGNORE
2707shell variable may be used to restrict the set of file names matching a
2708.IR pattern .
2709If
2710.SM
2711.B GLOBIGNORE
2712is set, each matching file name that also matches one of the patterns in
2713.SM
2714.B GLOBIGNORE
2715is removed from the list of matches.
2716The file names
2717.B ``.''
2718and
2719.B ``..''
2720are always ignored when
2721.SM
2722.B GLOBIGNORE
2723is set and not null.  However, setting
2724.SM
2725.B GLOBIGNORE
2726to a non-null value has the effect of enabling the
2727.B dotglob
2728shell option, so all other file names beginning with a
2729.B ``.''
2730will match.
2731To get the old behavior of ignoring file names beginning with a
2732.BR ``.'' ,
2733make
2734.B ``.*''
2735one of the patterns in
2736.SM
2737.BR GLOBIGNORE .
2738The
2739.B dotglob
2740option is disabled when
2741.SM
2742.B GLOBIGNORE
2743is unset.
2744.PP
2745\fBPattern Matching\fP
2746.PP
2747Any character that appears in a pattern, other than the special pattern
2748characters described below, matches itself.  The NUL character may not
2749occur in a pattern.  A backslash escapes the following character; the
2750escaping backslash is discarded when matching.
2751The special pattern characters must be quoted if
2752they are to be matched literally.
2753.PP
2754The special pattern characters have the following meanings:
2755.PP
2756.PD 0
2757.TP
2758.B *
2759Matches any string, including the null string.
2760.TP
2761.B ?
2762Matches any single character.
2763.TP
2764.B [...]
2765Matches any one of the enclosed characters.  A pair of characters
2766separated by a hyphen denotes a
2767\fIrange expression\fP;
2768any character that sorts between those two characters, inclusive,
2769using the current locale's collating sequence and character set,
2770is matched.  If the first character following the
2771.B [
2772is a
2773.B !
2774or a
2775.B ^
2776then any character not enclosed is matched.
2777The sorting order of characters in range expressions is determined by
2778the current locale and the value of the \fBLC_COLLATE\fP shell variable,
2779if set.
2780A
2781.B \-
2782may be matched by including it as the first or last character
2783in the set.
2784A
2785.B ]
2786may be matched by including it as the first character
2787in the set.
2788.br
2789.if t .sp 0.5
2790.if n .sp 1
2791Within
2792.B [
2793and
2794.BR ] ,
2795\fIcharacter classes\fP can be specified using the syntax
2796\fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the
2797following classes defined in the POSIX.2 standard:
2798.PP
2799.RS
2800.B
2801.if n alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit
2802.if t alnum   alpha   ascii   blank   cntrl   digit   graph   lower   print   punct   space   upper   word   xdigit
2803.br
2804A character class matches any character belonging to that class.
2805The \fBword\fP character class matches letters, digits, and the character _.
2806.br
2807.if t .sp 0.5
2808.if n .sp 1
2809Within
2810.B [
2811and
2812.BR ] ,
2813an \fIequivalence class\fP can be specified using the syntax
2814\fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the
2815same collation weight (as defined by the current locale) as
2816the character \fIc\fP.
2817.br
2818.if t .sp 0.5
2819.if n .sp 1
2820Within
2821.B [
2822and
2823.BR ] ,
2824the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol
2825\fIsymbol\fP.
2826.RE
2827.PD
2828.PP
2829If the \fBextglob\fP shell option is enabled using the \fBshopt\fP
2830builtin, several extended pattern matching operators are recognized.
2831In the following description, a \fIpattern-list\fP is a list of one
2832or more patterns separated by a \fB|\fP.
2833Composite patterns may be formed using one or more of the following
2834sub-patterns:
2835.sp 1
2836.PD 0
2837.RS
2838.TP
2839\fB?(\fP\^\fIpattern-list\^\fP\fB)\fP
2840Matches zero or one occurrence of the given patterns
2841.TP
2842\fB*(\fP\^\fIpattern-list\^\fP\fB)\fP
2843Matches zero or more occurrences of the given patterns
2844.TP
2845\fB+(\fP\^\fIpattern-list\^\fP\fB)\fP
2846Matches one or more occurrences of the given patterns
2847.TP
2848\fB@(\fP\^\fIpattern-list\^\fP\fB)\fP
2849Matches exactly one of the given patterns
2850.TP
2851\fB!(\fP\^\fIpattern-list\^\fP\fB)\fP
2852Matches anything except one of the given patterns
2853.RE
2854.PD
2855.SS Quote Removal
2856.PP
2857After the preceding expansions, all unquoted occurrences of the
2858characters
2859.BR \e ,
2860.BR ' ,
2861and \^\f3"\fP\^ that did not result from one of the above
2862expansions are removed.
2863.SH REDIRECTION
2864Before a command is executed, its input and output
2865may be
2866.I redirected
2867using a special notation interpreted by the shell.
2868Redirection may also be used to open and close files for the
2869current shell execution environment.  The following redirection
2870operators may precede or appear anywhere within a
2871.I simple command
2872or may follow a
2873.IR command .
2874Redirections are processed in the order they appear, from
2875left to right.
2876.PP
2877In the following descriptions, if the file descriptor number is
2878omitted, and the first character of the redirection operator is
2879.BR < ,
2880the redirection refers to the standard input (file descriptor
28810).  If the first character of the redirection operator is
2882.BR > ,
2883the redirection refers to the standard output (file descriptor
28841).
2885.PP
2886The word following the redirection operator in the following
2887descriptions, unless otherwise noted, is subjected to brace expansion,
2888tilde expansion, parameter expansion, command substitution, arithmetic
2889expansion, quote removal, pathname expansion, and word splitting.
2890If it expands to more than one word,
2891.B bash
2892reports an error.
2893.PP
2894Note that the order of redirections is significant.  For example,
2895the command
2896.RS
2897.PP
2898ls \fB>\fP dirlist 2\fB>&\fP1
2899.RE
2900.PP
2901directs both standard output and standard error to the file
2902.IR dirlist ,
2903while the command
2904.RS
2905.PP
2906ls 2\fB>&\fP1 \fB>\fP dirlist
2907.RE
2908.PP
2909directs only the standard output to file
2910.IR dirlist ,
2911because the standard error was duplicated as standard output
2912before the standard output was redirected to
2913.IR dirlist .
2914.PP
2915\fBBash\fP handles several filenames specially when they are used in
2916redirections, as described in the following table:
2917.RS
2918.PP
2919.PD 0
2920.TP
2921.B /dev/fd/\fIfd\fP
2922If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated.
2923.TP
2924.B /dev/stdin
2925File descriptor 0 is duplicated.
2926.TP
2927.B /dev/stdout
2928File descriptor 1 is duplicated.
2929.TP
2930.B /dev/stderr
2931File descriptor 2 is duplicated.
2932.TP
2933.B /dev/tcp/\fIhost\fP/\fIport\fP
2934If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
2935is an integer port number or service name, \fBbash\fP attempts to open
2936a TCP connection to the corresponding socket.
2937.TP
2938.B /dev/udp/\fIhost\fP/\fIport\fP
2939If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
2940is an integer port number or service name, \fBbash\fP attempts to open
2941a UDP connection to the corresponding socket.
2942.PD
2943.RE
2944.PP
2945A failure to open or create a file causes the redirection to fail.
2946.SS Redirecting Input
2947.PP
2948Redirection of input causes the file whose name results from
2949the expansion of
2950.I word
2951to be opened for reading on file descriptor
2952.IR n ,
2953or the standard input (file descriptor 0) if
2954.I n
2955is not specified.
2956.PP
2957The general format for redirecting input is:
2958.RS
2959.PP
2960[\fIn\fP]\fB<\fP\fIword\fP
2961.RE
2962.SS Redirecting Output
2963.PP
2964Redirection of output causes the file whose name results from
2965the expansion of
2966.I word
2967to be opened for writing on file descriptor
2968.IR n ,
2969or the standard output (file descriptor 1) if
2970.I n
2971is not specified.  If the file does not exist it is created;
2972if it does exist it is truncated to zero size.
2973.PP
2974The general format for redirecting output is:
2975.RS
2976.PP
2977[\fIn\fP]\fB>\fP\fIword\fP
2978.RE
2979.PP
2980If the redirection operator is
2981.BR > ,
2982and the
2983.B noclobber
2984option to the
2985.B set
2986builtin has been enabled, the redirection will fail if the file
2987whose name results from the expansion of \fIword\fP exists and is
2988a regular file.
2989If the redirection operator is
2990.BR >| ,
2991or the redirection operator is
2992.B >
2993and the
2994.B noclobber
2995option to the
2996.B set
2997builtin command is not enabled, the redirection is attempted even
2998if the file named by \fIword\fP exists.
2999.SS Appending Redirected Output
3000.PP
3001Redirection of output in this fashion
3002causes the file whose name results from
3003the expansion of
3004.I word
3005to be opened for appending on file descriptor
3006.IR n ,
3007or the standard output (file descriptor 1) if
3008.I n
3009is not specified.  If the file does not exist it is created.
3010.PP
3011The general format for appending output is:
3012.RS
3013.PP
3014[\fIn\fP]\fB>>\fP\fIword\fP
3015.RE
3016.PP
3017.SS Redirecting Standard Output and Standard Error
3018.PP
3019.B Bash
3020allows both the
3021standard output (file descriptor 1) and
3022the standard error output (file descriptor 2)
3023to be redirected to the file whose name is the
3024expansion of
3025.I word
3026with this construct.
3027.PP
3028There are two formats for redirecting standard output and
3029standard error:
3030.RS
3031.PP
3032\fB&>\fP\fIword\fP
3033.RE
3034and
3035.RS
3036\fB>&\fP\fIword\fP
3037.RE
3038.PP
3039Of the two forms, the first is preferred.
3040This is semantically equivalent to
3041.RS
3042.PP
3043\fB>\fP\fIword\fP 2\fB>&\fP1
3044.RE
3045.SS Here Documents
3046.PP
3047This type of redirection instructs the shell to read input from the
3048current source until a line containing only
3049.I word
3050(with no trailing blanks)
3051is seen.  All of
3052the lines read up to that point are then used as the standard
3053input for a command.
3054.PP
3055The format of here-documents is:
3056.RS
3057.PP
3058.nf
3059\fB<<\fP[\fB\-\fP]\fIword\fP
3060        \fIhere-document\fP
3061\fIdelimiter\fP
3062.fi
3063.RE
3064.PP
3065No parameter expansion, command substitution, arithmetic expansion,
3066or pathname expansion is performed on
3067.IR word .
3068If any characters in
3069.I word
3070are quoted, the
3071.I delimiter
3072is the result of quote removal on
3073.IR word ,
3074and the lines in the here-document are not expanded.
3075If \fIword\fP is unquoted,
3076all lines of the here-document are subjected to parameter expansion,
3077command substitution, and arithmetic expansion.  In the latter
3078case, the character sequence
3079.B \e<newline>
3080is ignored, and
3081.B \e
3082must be used to quote the characters
3083.BR \e ,
3084.BR $ ,
3085and
3086.BR ` .
3087.PP
3088If the redirection operator is
3089.BR <<\- ,
3090then all leading tab characters are stripped from input lines and the
3091line containing
3092.IR delimiter .
3093This allows
3094here-documents within shell scripts to be indented in a
3095natural fashion.
3096.SS "Here Strings"
3097A variant of here documents, the format is:
3098.RS
3099.PP
3100.nf
3101\fB<<<\fP\fIword\fP
3102.fi
3103.RE
3104.PP
3105The \fIword\fP is expanded and supplied to the command on its standard
3106input.
3107.SS "Duplicating File Descriptors"
3108.PP
3109The redirection operator
3110.RS
3111.PP
3112[\fIn\fP]\fB<&\fP\fIword\fP
3113.RE
3114.PP
3115is used to duplicate input file descriptors.
3116If
3117.I word
3118expands to one or more digits, the file descriptor denoted by
3119.I n
3120is made to be a copy of that file descriptor.
3121If the digits in
3122.I word
3123do not specify a file descriptor open for input, a redirection error occurs.
3124If
3125.I word
3126evaluates to
3127.BR \- ,
3128file descriptor
3129.I n
3130is closed.  If
3131.I n
3132is not specified, the standard input (file descriptor 0) is used.
3133.PP
3134The operator
3135.RS
3136.PP
3137[\fIn\fP]\fB>&\fP\fIword\fP
3138.RE
3139.PP
3140is used similarly to duplicate output file descriptors.  If
3141.I n
3142is not specified, the standard output (file descriptor 1) is used.
3143If the digits in
3144.I word
3145do not specify a file descriptor open for output, a redirection error occurs.
3146As a special case, if \fIn\fP is omitted, and \fIword\fP does not
3147expand to one or more digits, the standard output and standard
3148error are redirected as described previously.
3149.SS "Moving File Descriptors"
3150.PP
3151The redirection operator
3152.RS
3153.PP
3154[\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP
3155.RE
3156.PP
3157moves the file descriptor \fIdigit\fP to file descriptor
3158.IR n ,
3159or the standard input (file descriptor 0) if \fIn\fP is not specified.
3160\fIdigit\fP is closed after being duplicated to \fIn\fP.
3161.PP
3162Similarly, the redirection operator
3163.RS
3164.PP
3165[\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP
3166.RE
3167.PP
3168moves the file descriptor \fIdigit\fP to file descriptor
3169.IR n ,
3170or the standard output (file descriptor 1) if \fIn\fP is not specified.
3171.SS "Opening File Descriptors for Reading and Writing"
3172.PP
3173The redirection operator
3174.RS
3175.PP
3176[\fIn\fP]\fB<>\fP\fIword\fP
3177.RE
3178.PP
3179causes the file whose name is the expansion of
3180.I word
3181to be opened for both reading and writing on file descriptor
3182.IR n ,
3183or on file descriptor 0 if
3184.I n
3185is not specified.  If the file does not exist, it is created.
3186.SH ALIASES
3187\fIAliases\fP allow a string to be substituted for a word when it is used
3188as the first word of a simple command.
3189The shell maintains a list of aliases that may be set and unset with the
3190.B alias
3191and
3192.B unalias
3193builtin commands (see
3194.SM
3195.B SHELL BUILTIN COMMANDS
3196below).
3197The first word of each simple command, if unquoted,
3198is checked to see if it has an
3199alias.  If so, that word is replaced by the text of the alias.
3200The characters \fB/\fP, \fB$\fP, \fB`\fP, and \fB=\fP and
3201any of the shell \fImetacharacters\fP or quoting characters
3202listed above may not appear in an alias name.
3203The replacement text may contain any valid shell input,
3204including shell metacharacters.
3205The first word of the replacement text is tested
3206for aliases, but a word that is identical to an alias being expanded
3207is not expanded a second time.
3208This means that one may alias
3209.B ls
3210to
3211.BR "ls \-F" ,
3212for instance, and
3213.B bash
3214does not try to recursively expand the replacement text.
3215If the last character of the alias value is a
3216.IR blank ,
3217then the next command
3218word following the alias is also checked for alias expansion.
3219.PP
3220Aliases are created and listed with the
3221.B alias
3222command, and removed with the
3223.B unalias
3224command.
3225.PP
3226There is no mechanism for using arguments in the replacement text.
3227If arguments are needed, a shell function should be used (see
3228.SM
3229.B FUNCTIONS
3230below).
3231.PP
3232Aliases are not expanded when the shell is not interactive, unless
3233the
3234.B expand_aliases
3235shell option is set using
3236.B shopt
3237(see the description of
3238.B shopt
3239under
3240.SM
3241\fBSHELL BUILTIN COMMANDS\fP
3242below).
3243.PP
3244The rules concerning the definition and use of aliases are
3245somewhat confusing.
3246.B Bash
3247always reads at least one complete line
3248of input before executing any
3249of the commands on that line.  Aliases are expanded when a
3250command is read, not when it is executed.  Therefore, an
3251alias definition appearing on the same line as another
3252command does not take effect until the next line of input is read.
3253The commands following the alias definition
3254on that line are not affected by the new alias.
3255This behavior is also an issue when functions are executed.
3256Aliases are expanded when a function definition is read,
3257not when the function is executed, because a function definition
3258is itself a compound command.  As a consequence, aliases
3259defined in a function are not available until after that
3260function is executed.  To be safe, always put
3261alias definitions on a separate line, and do not use
3262.B alias
3263in compound commands.
3264.PP
3265For almost every purpose, aliases are superseded by
3266shell functions.
3267.SH FUNCTIONS
3268A shell function, defined as described above under
3269.SM
3270.BR "SHELL GRAMMAR" ,
3271stores a series of commands for later execution.
3272When the name of a shell function is used as a simple command name,
3273the list of commands associated with that function name is executed.
3274Functions are executed in the context of the
3275current shell; no new process is created to interpret
3276them (contrast this with the execution of a shell script).
3277When a function is executed, the arguments to the
3278function become the positional parameters
3279during its execution.
3280The special parameter
3281.B #
3282is updated to reflect the change.  Special parameter 0
3283is unchanged.
3284The first element of the
3285.SM
3286.B FUNCNAME
3287variable is set to the name of the function while the function
3288is executing.
3289All other aspects of the shell execution
3290environment are identical between a function and its caller
3291with the exception that the
3292.SM
3293.B DEBUG
3294trap (see the description of the
3295.B trap
3296builtin under
3297.SM
3298.B SHELL BUILTIN COMMANDS
3299below) is not inherited unless the function has been given the
3300\fBtrace\fP attribute (see the description of the
3301.SM
3302.B declare
3303builtin below) or the
3304\fB\-o functrace\fP shell option has been enabled with
3305the \fBset\fP builtin
3306(in which case all functions inherit the \fBDEBUG\fP trap).
3307.PP
3308Variables local to the function may be declared with the
3309.B local
3310builtin command.  Ordinarily, variables and their values
3311are shared between the function and its caller.
3312.PP
3313If the builtin command
3314.B return
3315is executed in a function, the function completes and
3316execution resumes with the next command after the function
3317call.
3318Any command associated with the \fBRETURN\fP trap is executed
3319before execution resumes.
3320When a function completes, the values of the
3321positional parameters and the special parameter
3322.B #
3323are restored to the values they had prior to the function's
3324execution.
3325.PP
3326Function names and definitions may be listed with the
3327.B \-f
3328option to the
3329.B declare
3330or
3331.B typeset
3332builtin commands.  The
3333.B \-F
3334option to
3335.B declare
3336or
3337.B typeset
3338will list the function names only
3339(and optionally the source file and line number, if the \fBextdebug\fP
3340shell option is enabled).
3341Functions may be exported so that subshells
3342automatically have them defined with the
3343.B \-f
3344option to the
3345.B export
3346builtin.
3347Note that shell functions and variables with the same name may result
3348in multiple identically-named entries in the environment passed to the
3349shell's children.
3350Care should be taken in cases where this may cause a problem.
3351.PP
3352Functions may be recursive.  No limit is imposed on the number
3353of recursive calls.
3354.SH "ARITHMETIC EVALUATION"
3355The shell allows arithmetic expressions to be evaluated, under
3356certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin
3357commands and \fBArithmetic Expansion\fP).
3358Evaluation is done in fixed-width integers with no check for overflow,
3359though division by 0 is trapped and flagged as an error.
3360The operators and their precedence, associativity, and values
3361are the same as in the C language.
3362The following list of operators is grouped into levels of
3363equal-precedence operators.
3364The levels are listed in order of decreasing precedence.
3365.PP
3366.PD 0
3367.TP
3368.B \fIid\fP++ \fIid\fP\-\-
3369variable post-increment and post-decrement
3370.TP
3371.B ++\fIid\fP \-\-\fIid\fP
3372variable pre-increment and pre-decrement
3373.TP
3374.B \- +
3375unary minus and plus
3376.TP
3377.B ! ~
3378logical and bitwise negation
3379.TP
3380.B **
3381exponentiation
3382.TP
3383.B * / %
3384multiplication, division, remainder
3385.TP
3386.B + \-
3387addition, subtraction
3388.TP
3389.B << >>
3390left and right bitwise shifts
3391.TP
3392.B <= >= < >
3393comparison
3394.TP
3395.B == !=
3396equality and inequality
3397.TP
3398.B &
3399bitwise AND
3400.TP
3401.B ^
3402bitwise exclusive OR
3403.TP
3404.B |
3405bitwise OR
3406.TP
3407.B &&
3408logical AND
3409.TP
3410.B ||
3411logical OR
3412.TP
3413.B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
3414conditional operator
3415.TP
3416.B = *= /= %= += \-= <<= >>= &= ^= |=
3417assignment
3418.TP
3419.B \fIexpr1\fP , \fIexpr2\fP
3420comma
3421.PD
3422.PP
3423Shell variables are allowed as operands; parameter expansion is
3424performed before the expression is evaluated.
3425Within an expression, shell variables may also be referenced by name
3426without using the parameter expansion syntax.
3427A shell variable that is null or unset evaluates to 0 when referenced
3428by name without using the parameter expansion syntax.
3429The value of a variable is evaluated as an arithmetic expression
3430when it is referenced, or when a variable which has been given the
3431\fIinteger\fP attribute using \fBdeclare -i\fP is assigned a value.
3432A null value evaluates to 0.
3433A shell variable need not have its integer attribute
3434turned on to be used in an expression.
3435.PP
3436Constants with a leading 0 are interpreted as octal numbers.
3437A leading 0x or 0X denotes hexadecimal.
3438Otherwise, numbers take the form [\fIbase#\fP]n, where \fIbase\fP
3439is a decimal number between 2 and 64 representing the arithmetic
3440base, and \fIn\fP is a number in that base.
3441If \fIbase#\fP is omitted, then base 10 is used.
3442The digits greater than 9 are represented by the lowercase letters,
3443the uppercase letters, @, and _, in that order.
3444If \fIbase\fP is less than or equal to 36, lowercase and uppercase
3445letters may be used interchangably to represent numbers between 10
3446and 35.
3447.PP
3448Operators are evaluated in order of precedence.  Sub-expressions in
3449parentheses are evaluated first and may override the precedence
3450rules above.
3451.SH "CONDITIONAL EXPRESSIONS"
3452Conditional expressions are used by the \fB[[\fP compound command and
3453the \fBtest\fP and \fB[\fP builtin commands to test file attributes
3454and perform string and arithmetic comparisons.
3455Expressions are formed from the following unary or binary primaries.
3456If any \fIfile\fP argument to one of the primaries is of the form
3457\fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked.
3458If the \fIfile\fP argument to one of the primaries is one of
3459\fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file
3460descriptor 0, 1, or 2, respectively, is checked.
3461.sp 1
3462.PD 0
3463.TP
3464.B \-a \fIfile\fP
3465True if \fIfile\fP exists.
3466.TP
3467.B \-b \fIfile\fP
3468True if \fIfile\fP exists and is a block special file.
3469.TP
3470.B \-c \fIfile\fP
3471True if \fIfile\fP exists and is a character special file.
3472.TP
3473.B \-d \fIfile\fP
3474True if \fIfile\fP exists and is a directory.
3475.TP
3476.B \-e \fIfile\fP
3477True if \fIfile\fP exists.
3478.TP
3479.B \-f \fIfile\fP
3480True if \fIfile\fP exists and is a regular file.
3481.TP
3482.B \-g \fIfile\fP
3483True if \fIfile\fP exists and is set-group-id.
3484.TP
3485.B \-h \fIfile\fP
3486True if \fIfile\fP exists and is a symbolic link.
3487.TP
3488.B \-k \fIfile\fP
3489True if \fIfile\fP exists and its ``sticky'' bit is set.
3490.TP
3491.B \-p \fIfile\fP
3492True if \fIfile\fP exists and is a named pipe (FIFO).
3493.TP
3494.B \-r \fIfile\fP
3495True if \fIfile\fP exists and is readable.
3496.TP
3497.B \-s \fIfile\fP
3498True if \fIfile\fP exists and has a size greater than zero.
3499.TP
3500.B \-t \fIfd\fP
3501True if file descriptor
3502.I fd
3503is open and refers to a terminal.
3504.TP
3505.B \-u \fIfile\fP
3506True if \fIfile\fP exists and its set-user-id bit is set.
3507.TP
3508.B \-w \fIfile\fP
3509True if \fIfile\fP exists and is writable.
3510.TP
3511.B \-x \fIfile\fP
3512True if \fIfile\fP exists and is executable.
3513.TP
3514.B \-O \fIfile\fP
3515True if \fIfile\fP exists and is owned by the effective user id.
3516.TP
3517.B \-G \fIfile\fP
3518True if \fIfile\fP exists and is owned by the effective group id.
3519.TP
3520.B \-L \fIfile\fP
3521True if \fIfile\fP exists and is a symbolic link.
3522.TP
3523.B \-S \fIfile\fP
3524True if \fIfile\fP exists and is a socket.
3525.TP
3526.B \-N \fIfile\fP
3527True if \fIfile\fP exists and has been modified since it was last read.
3528.TP
3529\fIfile1\fP \-\fBnt\fP \fIfile2\fP
3530True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP,
3531or if \fIfile1\fP exists and \fPfile2\fP does not.
3532.TP
3533\fIfile1\fP \-\fBot\fP \fIfile2\fP
3534True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists
3535and \fIfile1\fP does not.
3536.TP
3537\fIfile1\fP \fB\-ef\fP \fIfile2\fP
3538True if \fIfile1\fP and \fIfile2\fP refer to the same device and
3539inode numbers.
3540.TP
3541.B \-o \fIoptname\fP
3542True if shell option
3543.I optname
3544is enabled.
3545See the list of options under the description of the
3546.B \-o
3547option to the
3548.B set
3549builtin below.
3550.TP
3551.B \-z \fIstring\fP
3552True if the length of \fIstring\fP is zero.
3553.TP
3554\fIstring\fP
3555.PD 0
3556.TP
3557.B \-n \fIstring\fP
3558.PD
3559True if the length of
3560.I string
3561is non-zero.
3562.TP
3563\fIstring1\fP \fB==\fP \fIstring2\fP
3564True if the strings are equal.  \fB=\fP may be used in place of
3565\fB==\fP for strict POSIX compliance.
3566.TP
3567\fIstring1\fP \fB!=\fP \fIstring2\fP
3568True if the strings are not equal.
3569.TP
3570\fIstring1\fP \fB<\fP \fIstring2\fP
3571True if \fIstring1\fP sorts before \fIstring2\fP lexicographically
3572in the current locale.
3573.TP
3574\fIstring1\fP \fB>\fP \fIstring2\fP
3575True if \fIstring1\fP sorts after \fIstring2\fP lexicographically
3576in the current locale.
3577.TP
3578.I \fIarg1\fP \fBOP\fP \fIarg2\fP
3579.SM
3580.B OP
3581is one of
3582.BR \-eq ,
3583.BR \-ne ,
3584.BR \-lt ,
3585.BR \-le ,
3586.BR \-gt ,
3587or
3588.BR \-ge .
3589These arithmetic binary operators return true if \fIarg1\fP
3590is equal to, not equal to, less than, less than or equal to,
3591greater than, or greater than or equal to \fIarg2\fP, respectively.
3592.I Arg1
3593and
3594.I arg2
3595may be positive or negative integers.
3596.PD
3597.SH "SIMPLE COMMAND EXPANSION"
3598When a simple command is executed, the shell performs the following
3599expansions, assignments, and redirections, from left to right.
3600.IP 1.
3601The words that the parser has marked as variable assignments (those
3602preceding the command name) and redirections are saved for later
3603processing.
3604.IP 2.
3605The words that are not variable assignments or redirections are
3606expanded.  If any words remain after expansion, the first word
3607is taken to be the name of the command and the remaining words are
3608the arguments.
3609.IP 3.
3610Redirections are performed as described above under
3611.SM
3612.BR REDIRECTION .
3613.IP 4.
3614The text after the \fB=\fP in each variable assignment undergoes tilde
3615expansion, parameter expansion, command substitution, arithmetic expansion,
3616and quote removal before being assigned to the variable.
3617.PP
3618If no command name results, the variable assignments affect the current
3619shell environment.  Otherwise, the variables are added to the environment
3620of the executed command and do not affect the current shell environment.
3621If any of the assignments attempts to assign a value to a readonly variable,
3622an error occurs, and the command exits with a non-zero status.
3623.PP
3624If no command name results, redirections are performed, but do not
3625affect the current shell environment.  A redirection error causes the
3626command to exit with a non-zero status.
3627.PP
3628If there is a command name left after expansion, execution proceeds as
3629described below.  Otherwise, the command exits.  If one of the expansions
3630contained a command substitution, the exit status of the command is
3631the exit status of the last command substitution performed.  If there
3632were no command substitutions, the command exits with a status of zero.
3633.SH "COMMAND EXECUTION"
3634After a command has been split into words, if it results in a
3635simple command and an optional list of arguments, the following
3636actions are taken.
3637.PP
3638If the command name contains no slashes, the shell attempts to
3639locate it.  If there exists a shell function by that name, that
3640function is invoked as described above in
3641.SM
3642.BR FUNCTIONS .
3643If the name does not match a function, the shell searches for
3644it in the list of shell builtins.  If a match is found, that
3645builtin is invoked.
3646.PP
3647If the name is neither a shell function nor a builtin,
3648and contains no slashes,
3649.B bash
3650searches each element of the
3651.SM
3652.B PATH
3653for a directory containing an executable file by that name.
3654.B Bash
3655uses a hash table to remember the full pathnames of executable
3656files (see
3657.B hash
3658under
3659.SM
3660.B "SHELL BUILTIN COMMANDS"
3661below).
3662A full search of the directories in
3663.SM
3664.B PATH
3665is performed only if the command is not found in the hash table.
3666If the search is unsuccessful, the shell prints an error
3667message and returns an exit status of 127.
3668.PP
3669If the search is successful, or if the command name contains
3670one or more slashes, the shell executes the named program in a
3671separate execution environment.
3672Argument 0 is set to the name given, and the remaining arguments
3673to the command are set to the arguments given, if any.
3674.PP
3675If this execution fails because the file is not in executable
3676format, and the file is not a directory, it is assumed to be
3677a \fIshell script\fP, a file
3678containing shell commands.  A subshell is spawned to execute
3679it.  This subshell reinitializes itself, so
3680that the effect is as if a new shell had been invoked
3681to handle the script, with the exception that the locations of
3682commands remembered by the parent (see
3683.B hash
3684below under
3685.SM
3686\fBSHELL BUILTIN COMMANDS\fP)
3687are retained by the child.
3688.PP
3689If the program is a file beginning with
3690.BR #! ,
3691the remainder of the first line specifies an interpreter
3692for the program.  The shell executes the
3693specified interpreter on operating systems that do not
3694handle this executable format themselves.  The arguments to the
3695interpreter consist of a single optional argument following the
3696interpreter name on the first line of the program, followed
3697by the name of the program, followed by the command
3698arguments, if any.
3699.SH COMMAND EXECUTION ENVIRONMENT
3700The shell has an \fIexecution environment\fP, which consists of the
3701following:
3702.sp 1
3703.IP \(bu
3704open files inherited by the shell at invocation, as modified by
3705redirections supplied to the \fBexec\fP builtin
3706.IP \(bu
3707the current working directory as set by \fBcd\fP, \fBpushd\fP, or
3708\fBpopd\fP, or inherited by the shell at invocation
3709.IP \(bu
3710the file creation mode mask as set by \fBumask\fP or inherited from
3711the shell's parent
3712.IP \(bu
3713current traps set by \fBtrap\fP
3714.IP \(bu
3715shell parameters that are set by variable assignment or with \fBset\fP
3716or inherited from the shell's parent in the environment
3717.IP \(bu
3718shell functions defined during execution or inherited from the shell's
3719parent in the environment
3720.IP \(bu
3721options enabled at invocation (either by default or with command-line
3722arguments) or by \fBset\fP
3723.IP \(bu
3724options enabled by \fBshopt\fP
3725.IP \(bu
3726shell aliases defined with \fBalias\fP
3727.IP \(bu
3728various process IDs, including those of background jobs, the value
3729of \fB$$\fP, and the value of \fB$PPID\fP
3730.PP
3731When a simple command other than a builtin or shell function
3732is to be executed, it
3733is invoked in a separate execution environment that consists of
3734the following.  Unless otherwise noted, the values are inherited
3735from the shell.
3736.sp 1
3737.IP \(bu
3738the shell's open files, plus any modifications and additions specified
3739by redirections to the command
3740.IP \(bu
3741the current working directory
3742.IP \(bu
3743the file creation mode mask
3744.IP \(bu
3745shell variables and functions marked for export, along with variables
3746exported for the command, passed in the environment
3747.IP \(bu
3748traps caught by the shell are reset to the values inherited from the
3749shell's parent, and traps ignored by the shell are ignored
3750.PP
3751A command invoked in this separate environment cannot affect the
3752shell's execution environment.
3753.PP
3754Command substitution, commands grouped with parentheses,
3755and asynchronous commands are invoked in a
3756subshell environment that is a duplicate of the shell environment,
3757except that traps caught by the shell are reset to the values
3758that the shell inherited from its parent at invocation.  Builtin
3759commands that are invoked as part of a pipeline are also executed in a
3760subshell environment.  Changes made to the subshell environment
3761cannot affect the shell's execution environment.
3762.PP
3763If a command is followed by a \fB&\fP and job control is not active, the
3764default standard input for the command is the empty file \fI/dev/null\fP.
3765Otherwise, the invoked command inherits the file descriptors of the calling
3766shell as modified by redirections.
3767.SH ENVIRONMENT
3768When a program is invoked it is given an array of strings
3769called the
3770.IR environment .
3771This is a list of
3772\fIname\fP\-\fIvalue\fP pairs, of the form
3773.IR "name\fR=\fPvalue" .
3774.PP
3775The shell provides several ways to manipulate the environment.
3776On invocation, the shell scans its own environment and
3777creates a parameter for each name found, automatically marking
3778it for
3779.I export
3780to child processes.  Executed commands inherit the environment.
3781The
3782.B export
3783and
3784.B declare \-x
3785commands allow parameters and functions to be added to and
3786deleted from the environment.  If the value of a parameter
3787in the environment is modified, the new value becomes part
3788of the environment, replacing the old.  The environment
3789inherited by any executed command consists of the shell's
3790initial environment, whose values may be modified in the shell,
3791less any pairs removed by the
3792.B unset
3793command, plus any additions via the
3794.B export
3795and
3796.B declare \-x
3797commands.
3798.PP
3799The environment for any
3800.I simple command
3801or function may be augmented temporarily by prefixing it with
3802parameter assignments, as described above in
3803.SM
3804.BR PARAMETERS .
3805These assignment statements affect only the environment seen
3806by that command.
3807.PP
3808If the
3809.B \-k
3810option is set (see the
3811.B set
3812builtin command below), then
3813.I all
3814parameter assignments are placed in the environment for a command,
3815not just those that precede the command name.
3816.PP
3817When
3818.B bash
3819invokes an external command, the variable
3820.B _
3821is set to the full file name of the command and passed to that
3822command in its environment.
3823.SH "EXIT STATUS"
3824For the shell's purposes, a command which exits with a
3825zero exit status has succeeded.  An exit status of zero
3826indicates success.  A non-zero exit status indicates failure.
3827When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses
3828the value of 128+\fIN\fP as the exit status.
3829.PP
3830If a command is not found, the child process created to
3831execute it returns a status of 127.  If a command is found
3832but is not executable, the return status is 126.
3833.PP
3834If a command fails because of an error during expansion or redirection,
3835the exit status is greater than zero.
3836.PP
3837Shell builtin commands return a status of 0 (\fItrue\fP) if
3838successful, and non-zero (\fIfalse\fP) if an error occurs
3839while they execute.
3840All builtins return an exit status of 2 to indicate incorrect usage.
3841.PP
3842\fBBash\fP itself returns the exit status of the last command
3843executed, unless a syntax error occurs, in which case it exits
3844with a non-zero value.  See also the \fBexit\fP builtin
3845command below.
3846.SH SIGNALS
3847When \fBbash\fP is interactive, in the absence of any traps, it ignores
3848.SM
3849.B SIGTERM
3850(so that \fBkill 0\fP does not kill an interactive shell),
3851and
3852.SM
3853.B SIGINT
3854is caught and handled (so that the \fBwait\fP builtin is interruptible).
3855In all cases, \fBbash\fP ignores
3856.SM
3857.BR SIGQUIT .
3858If job control is in effect,
3859.B bash
3860ignores
3861.SM
3862.BR SIGTTIN ,
3863.SM
3864.BR SIGTTOU ,
3865and
3866.SM
3867.BR SIGTSTP .
3868.PP
3869Non-builtin commands run by \fBbash\fP have signal handlers
3870set to the values inherited by the shell from its parent.
3871When job control is not in effect, asynchronous commands
3872ignore
3873.SM
3874.B SIGINT
3875and
3876.SM
3877.B SIGQUIT
3878in addition to these inherited handlers.
3879Commands run as a result of command substitution ignore the
3880keyboard-generated job control signals
3881.SM
3882.BR SIGTTIN ,
3883.SM
3884.BR SIGTTOU ,
3885and
3886.SM
3887.BR SIGTSTP .
3888.PP
3889The shell exits by default upon receipt of a
3890.SM
3891.BR SIGHUP .
3892Before exiting, an interactive shell resends the
3893.SM
3894.B SIGHUP
3895to all jobs, running or stopped.
3896Stopped jobs are sent
3897.SM
3898.B SIGCONT
3899to ensure that they receive the
3900.SM
3901.BR SIGHUP .
3902To prevent the shell from
3903sending the signal to a particular job, it should be removed from the
3904jobs table with the
3905.B disown
3906builtin (see
3907.SM
3908.B "SHELL BUILTIN COMMANDS"
3909below) or marked
3910to not receive
3911.SM
3912.B SIGHUP
3913using
3914.BR "disown \-h" .
3915.PP
3916If the
3917.B huponexit
3918shell option has been set with
3919.BR shopt ,
3920.B bash
3921sends a
3922.SM
3923.B SIGHUP
3924to all jobs when an interactive login shell exits.
3925.PP
3926If \Bbash\fP is waiting for a command to complete and receives a signal
3927for which a trap has been set, the trap will not be executed until
3928the command completes.
3929When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP
3930builtin, the reception of a signal for which a trap has been set will
3931cause the \fBwait\fP builtin to return immediately with an exit status
3932greater than 128, immediately after which the trap is executed.
3933.SH "JOB CONTROL"
3934.I Job control
3935refers to the ability to selectively stop (\fIsuspend\fP)
3936the execution of processes and continue (\fIresume\fP)
3937their execution at a later point.  A user typically employs
3938this facility via an interactive interface supplied jointly
3939by the system's terminal driver and
3940.BR bash .
3941.PP
3942The shell associates a
3943.I job
3944with each pipeline.  It keeps a table of currently executing
3945jobs, which may be listed with the
3946.B jobs
3947command.  When
3948.B bash
3949starts a job asynchronously (in the
3950.IR background ),
3951it prints a line that looks like:
3952.RS
3953.PP
3954[1] 25647
3955.RE
3956.PP
3957indicating that this job is job number 1 and that the process ID
3958of the last process in the pipeline associated with this job is 25647.
3959All of the processes in a single pipeline are members of the same job.
3960.B Bash
3961uses the
3962.I job
3963abstraction as the basis for job control.
3964.PP
3965To facilitate the implementation of the user interface to job
3966control, the operating system maintains the notion of a \fIcurrent terminal
3967process group ID\fP.  Members of this process group (processes whose
3968process group ID is equal to the current terminal process group ID)
3969receive keyboard-generated signals such as
3970.SM
3971.BR SIGINT .
3972These processes are said to be in the
3973.IR foreground .
3974.I Background
3975processes are those whose process group ID differs from the terminal's;
3976such processes are immune to keyboard-generated signals.
3977Only foreground processes are allowed to read from or write to the
3978terminal.  Background processes which attempt to read from (write to) the
3979terminal are sent a
3980.SM
3981.B SIGTTIN (SIGTTOU)
3982signal by the terminal driver,
3983which, unless caught, suspends the process.
3984.PP
3985If the operating system on which
3986.B bash
3987is running supports
3988job control,
3989.B bash
3990contains facilities to use it.
3991Typing the
3992.I suspend
3993character (typically
3994.BR ^Z ,
3995Control-Z) while a process is running
3996causes that process to be stopped and returns control to
3997.BR bash .
3998Typing the
3999.I "delayed suspend"
4000character (typically
4001.BR ^Y ,
4002Control-Y) causes the process to be stopped when it
4003attempts to read input from the terminal, and control to
4004be returned to
4005.BR bash .
4006The user may then manipulate the state of this job, using the
4007.B bg
4008command to continue it in the background, the
4009.B fg
4010command to continue it in the foreground, or
4011the
4012.B kill
4013command to kill it.  A \fB^Z\fP takes effect immediately,
4014and has the additional side effect of causing pending output
4015and typeahead to be discarded.
4016.PP
4017There are a number of ways to refer to a job in the shell.
4018The character
4019.B %
4020introduces a job name.  Job number
4021.I n
4022may be referred to as
4023.BR %n .
4024A job may also be referred to using a prefix of the name used to
4025start it, or using a substring that appears in its command line.
4026For example,
4027.B %ce
4028refers to a stopped
4029.B ce
4030job.  If a prefix matches more than one job,
4031.B bash
4032reports an error.  Using
4033.BR %?ce ,
4034on the other hand, refers to any job containing the string
4035.B ce
4036in its command line.  If the substring matches more than one job,
4037.B bash
4038reports an error.  The symbols
4039.B %%
4040and
4041.B %+
4042refer to the shell's notion of the
4043.IR "current job" ,
4044which is the last job stopped while it was in
4045the foreground or started in the background.
4046The
4047.I "previous job"
4048may be referenced using
4049.BR %\- .
4050In output pertaining to jobs (e.g., the output of the
4051.B jobs
4052command), the current job is always flagged with a
4053.BR + ,
4054and the previous job with a
4055.BR \- .
4056.PP
4057Simply naming a job can be used to bring it into the
4058foreground:
4059.B %1
4060is a synonym for
4061\fB``fg %1''\fP,
4062bringing job 1 from the background into the foreground.
4063Similarly,
4064.B ``%1 &''
4065resumes job 1 in the background, equivalent to
4066\fB``bg %1''\fP.
4067.PP
4068The shell learns immediately whenever a job changes state.
4069Normally,
4070.B bash
4071waits until it is about to print a prompt before reporting
4072changes in a job's status so as to not interrupt
4073any other output.  If the
4074.B \-b
4075option to the
4076.B set
4077builtin command
4078is enabled,
4079.B bash
4080reports such changes immediately.
4081Any trap on
4082.SM
4083.B SIGCHLD
4084is executed for each child that exits.
4085.PP
4086If an attempt to exit
4087.B bash
4088is made while jobs are stopped, the shell prints a warning message.  The
4089.B jobs
4090command may then be used to inspect their status.
4091If a second attempt to exit is made without an intervening command,
4092the shell does not print another warning, and the stopped
4093jobs are terminated.
4094.SH PROMPTING
4095When executing interactively,
4096.B bash
4097displays the primary prompt
4098.SM
4099.B PS1
4100when it is ready to read a command, and the secondary prompt
4101.SM
4102.B PS2
4103when it needs more input to complete a command.
4104.B Bash
4105allows these prompt strings to be customized by inserting a number of
4106backslash-escaped special characters that are decoded as follows:
4107.RS
4108.PD 0
4109.TP
4110.B \ea
4111an ASCII bell character (07)
4112.TP
4113.B \ed
4114the date in "Weekday Month Date" format (e.g., "Tue May 26")
4115.TP
4116.B \eD{\fIformat\fP}
4117the \fIformat\fP is passed to \fIstrftime\fP(3) and the result is inserted
4118into the prompt string; an empty \fIformat\fP results in a locale-specific
4119time representation.  The braces are required
4120.TP
4121.B \ee
4122an ASCII escape character (033)
4123.TP
4124.B \eh
4125the hostname up to the first `.'
4126.TP
4127.B \eH
4128the hostname
4129.TP
4130.B \ej
4131the number of jobs currently managed by the shell
4132.TP
4133.B \el
4134the basename of the shell's terminal device name
4135.TP
4136.B \en
4137newline
4138.TP
4139.B \er
4140carriage return
4141.TP
4142.B \es
4143the name of the shell, the basename of
4144.B $0
4145(the portion following the final slash)
4146.TP
4147.B \et
4148the current time in 24-hour HH:MM:SS format
4149.TP
4150.B \eT
4151the current time in 12-hour HH:MM:SS format
4152.TP
4153.B \e@
4154the current time in 12-hour am/pm format
4155.TP
4156.B \eA
4157the current time in 24-hour HH:MM format
4158.TP
4159.B \eu
4160the username of the current user
4161.TP
4162.B \ev
4163the version of \fBbash\fP (e.g., 2.00)
4164.TP
4165.B \eV
4166the release of \fBbash\fP, version + patch level (e.g., 2.00.0)
4167.TP
4168.B \ew
4169the current working directory, with \fB$HOME\fP abbreviated with a tilde
4170.TP
4171.B \eW
4172the basename of the current working directory, with \fB$HOME\fP
4173abbreviated with a tilde
4174.TP
4175.B \e!
4176the history number of this command
4177.TP
4178.B \e#
4179the command number of this command
4180.TP
4181.B \e$
4182if the effective UID is 0, a
4183.BR # ,
4184otherwise a
4185.B $
4186.TP
4187.B \e\fInnn\fP
4188the character corresponding to the octal number \fInnn\fP
4189.TP
4190.B \e\e
4191a backslash
4192.TP
4193.B \e[
4194begin a sequence of non-printing characters, which could be used to
4195embed a terminal control sequence into the prompt
4196.TP
4197.B \e]
4198end a sequence of non-printing characters
4199.PD
4200.RE
4201.PP
4202The command number and the history number are usually different:
4203the history number of a command is its position in the history
4204list, which may include commands restored from the history file
4205(see
4206.SM
4207.B HISTORY
4208below), while the command number is the position in the sequence
4209of commands executed during the current shell session.
4210After the string is decoded, it is expanded via
4211parameter expansion, command substitution, arithmetic
4212expansion, and quote removal, subject to the value of the
4213.B promptvars
4214shell option (see the description of the
4215.B shopt
4216command under
4217.SM
4218.B "SHELL BUILTIN COMMANDS"
4219below).
4220.SH READLINE
4221This is the library that handles reading input when using an interactive
4222shell, unless the
4223.B \-\-noediting
4224option is given at shell invocation.
4225By default, the line editing commands are similar to those of emacs.
4226A vi-style line editing interface is also available.
4227To turn off line editing after the shell is running, use the
4228.B +o emacs
4229or
4230.B +o vi
4231options to the
4232.B set
4233builtin (see
4234.SM
4235.B SHELL BUILTIN COMMANDS
4236below).
4237.SS "Readline Notation"
4238.PP
4239In this section, the emacs-style notation is used to denote
4240keystrokes.  Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
4241means Control\-N.  Similarly,
4242.I meta
4243keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X.  (On keyboards
4244without a
4245.I meta
4246key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
4247then the
4248.I x
4249key.  This makes ESC the \fImeta prefix\fP.
4250The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
4251or press the Escape key
4252then hold the Control key while pressing the
4253.I x
4254key.)
4255.PP
4256Readline commands may be given numeric
4257.IR arguments ,
4258which normally act as a repeat count.
4259Sometimes, however, it is the sign of the argument that is significant.
4260Passing a negative argument to a command that acts in the forward
4261direction (e.g., \fBkill\-line\fP) causes that command to act in a
4262backward direction.
4263Commands whose behavior with arguments deviates from this are noted
4264below.
4265.PP
4266When a command is described as \fIkilling\fP text, the text
4267deleted is saved for possible future retrieval
4268(\fIyanking\fP).  The killed text is saved in a
4269\fIkill ring\fP.  Consecutive kills cause the text to be
4270accumulated into one unit, which can be yanked all at once.
4271Commands which do not kill text separate the chunks of text
4272on the kill ring.
4273.SS "Readline Initialization"
4274.PP
4275Readline is customized by putting commands in an initialization
4276file (the \fIinputrc\fP file).
4277The name of this file is taken from the value of the
4278.SM
4279.B INPUTRC
4280variable.  If that variable is unset, the default is
4281.IR ~/.inputrc .
4282When a program which uses the readline library starts up, the
4283initialization file is read, and the key bindings and variables
4284are set.
4285There are only a few basic constructs allowed in the
4286readline initialization file.
4287Blank lines are ignored.
4288Lines beginning with a \fB#\fP are comments.
4289Lines beginning with a \fB$\fP indicate conditional constructs.
4290Other lines denote key bindings and variable settings.
4291.PP
4292The default key-bindings may be changed with an
4293.I inputrc
4294file.
4295Other programs that use this library may add their own commands
4296and bindings.
4297.PP
4298For example, placing
4299.RS
4300.PP
4301M\-Control\-u: universal\-argument
4302.RE
4303or
4304.RS
4305C\-Meta\-u: universal\-argument
4306.RE
4307into the
4308.I inputrc
4309would make M\-C\-u execute the readline command
4310.IR universal\-argument .
4311.PP
4312The following symbolic character names are recognized:
4313.IR RUBOUT ,
4314.IR DEL ,
4315.IR ESC ,
4316.IR LFD ,
4317.IR NEWLINE ,
4318.IR RET ,
4319.IR RETURN ,
4320.IR SPC ,
4321.IR SPACE ,
4322and
4323.IR TAB .
4324.PP
4325In addition to command names, readline allows keys to be bound
4326to a string that is inserted when the key is pressed (a \fImacro\fP).
4327.SS "Readline Key Bindings"
4328.PP
4329The syntax for controlling key bindings in the
4330.I inputrc
4331file is simple.  All that is required is the name of the
4332command or the text of a macro and a key sequence to which
4333it should be bound. The name may be specified in one of two ways:
4334as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
4335prefixes, or as a key sequence.
4336.PP
4337When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP,
4338.I keyname
4339is the name of a key spelled out in English.  For example:
4340.sp
4341.RS
4342Control-u: universal\-argument
4343.br
4344Meta-Rubout: backward-kill-word
4345.br
4346Control-o: "> output"
4347.RE
4348.LP
4349In the above example,
4350.I C\-u
4351is bound to the function
4352.BR universal\-argument ,
4353.I M\-DEL
4354is bound to the function
4355.BR backward\-kill\-word ,
4356and
4357.I C\-o
4358is bound to run the macro
4359expressed on the right hand side (that is, to insert the text
4360.if t \f(CW> output\fP
4361.if n ``> output''
4362into the line).
4363.PP
4364In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
4365.B keyseq
4366differs from
4367.B keyname
4368above in that strings denoting
4369an entire key sequence may be specified by placing the sequence
4370within double quotes.  Some GNU Emacs style key escapes can be
4371used, as in the following example, but the symbolic character names
4372are not recognized.
4373.sp
4374.RS
4375"\eC\-u": universal\-argument
4376.br
4377"\eC\-x\eC\-r": re\-read\-init\-file
4378.br
4379"\ee[11~": "Function Key 1"
4380.RE
4381.PP
4382In this example,
4383.I C\-u
4384is again bound to the function
4385.BR universal\-argument .
4386.I "C\-x C\-r"
4387is bound to the function
4388.BR re\-read\-init\-file ,
4389and
4390.I "ESC [ 1 1 ~"
4391is bound to insert the text
4392.if t \f(CWFunction Key 1\fP.
4393.if n ``Function Key 1''.
4394.PP
4395The full set of GNU Emacs style escape sequences is
4396.RS
4397.PD 0
4398.TP
4399.B \eC\-
4400control prefix
4401.TP
4402.B \eM\-
4403meta prefix
4404.TP
4405.B \ee
4406an escape character
4407.TP
4408.B \e\e
4409backslash
4410.TP
4411.B \e"
4412literal "
4413.TP
4414.B \e'
4415literal '
4416.RE
4417.PD
4418.PP
4419In addition to the GNU Emacs style escape sequences, a second
4420set of backslash escapes is available:
4421.RS
4422.PD 0
4423.TP
4424.B \ea
4425alert (bell)
4426.TP
4427.B \eb
4428backspace
4429.TP
4430.B \ed
4431delete
4432.TP
4433.B \ef
4434form feed
4435.TP
4436.B \en
4437newline
4438.TP
4439.B \er
4440carriage return
4441.TP
4442.B \et
4443horizontal tab
4444.TP
4445.B \ev
4446vertical tab
4447.TP
4448.B \e\fInnn\fP
4449the eight-bit character whose value is the octal value \fInnn\fP
4450(one to three digits)
4451.TP
4452.B \ex\fIHH\fP
4453the eight-bit character whose value is the hexadecimal value \fIHH\fP
4454(one or two hex digits)
4455.RE
4456.PD
4457.PP
4458When entering the text of a macro, single or double quotes must
4459be used to indicate a macro definition.
4460Unquoted text is assumed to be a function name.
4461In the macro body, the backslash escapes described above are expanded.
4462Backslash will quote any other character in the macro text,
4463including " and '.
4464.PP
4465.B Bash
4466allows the current readline key bindings to be displayed or modified
4467with the
4468.B bind
4469builtin command.  The editing mode may be switched during interactive
4470use by using the
4471.B \-o
4472option to the
4473.B set
4474builtin command (see
4475.SM
4476.B SHELL BUILTIN COMMANDS
4477below).
4478.SS "Readline Variables"
4479.PP
4480Readline has variables that can be used to further customize its
4481behavior.  A variable may be set in the
4482.I inputrc
4483file with a statement of the form
4484.RS
4485.PP
4486\fBset\fP \fIvariable\-name\fP \fIvalue\fP
4487.RE
4488.PP
4489Except where noted, readline variables can take the values
4490.B On
4491or
4492.BR Off .
4493The variables and their default values are:
4494.PP
4495.PD 0
4496.TP
4497.B bell\-style (audible)
4498Controls what happens when readline wants to ring the terminal bell.
4499If set to \fBnone\fP, readline never rings the bell.  If set to
4500\fBvisible\fP, readline uses a visible bell if one is available.
4501If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
4502.TP
4503.B comment\-begin (``#'')
4504The string that is inserted when the readline
4505.B insert\-comment
4506command is executed.
4507This command is bound to
4508.B M\-#
4509in emacs mode and to
4510.B #
4511in vi command mode.
4512.TP
4513.B completion\-ignore\-case (Off)
4514If set to \fBOn\fP, readline performs filename matching and completion
4515in a case\-insensitive fashion.
4516.TP
4517.B completion\-query\-items (100)
4518This determines when the user is queried about viewing
4519the number of possible completions
4520generated by the \fBpossible\-completions\fP command.
4521It may be set to any integer value greater than or equal to
4522zero.  If the number of possible completions is greater than
4523or equal to the value of this variable, the user is asked whether
4524or not he wishes to view them; otherwise they are simply listed
4525on the terminal.
4526.TP
4527.B convert\-meta (On)
4528If set to \fBOn\fP, readline will convert characters with the
4529eighth bit set to an ASCII key sequence
4530by stripping the eighth bit and prefixing an
4531escape character (in effect, using escape as the \fImeta prefix\fP).
4532.TP
4533.B disable\-completion (Off)
4534If set to \fBOn\fP, readline will inhibit word completion.  Completion
4535characters will be inserted into the line as if they had been
4536mapped to \fBself-insert\fP.
4537.TP
4538.B editing\-mode (emacs)
4539Controls whether readline begins with a set of key bindings similar
4540to \fIemacs\fP or \fIvi\fP.
4541.B editing\-mode
4542can be set to either
4543.B emacs
4544or
4545.BR vi .
4546.TP
4547.B enable\-keypad (Off)
4548When set to \fBOn\fP, readline will try to enable the application
4549keypad when it is called.  Some systems need this to enable the
4550arrow keys.
4551.TP
4552.B expand\-tilde (Off)
4553If set to \fBon\fP, tilde expansion is performed when readline
4554attempts word completion.
4555.TP
4556.B history-preserve-point
4557If set to \fBon\fP, the history code attempts to place point at the
4558same location on each history line retrived with \fBprevious-history\fP
4559or \fBnext-history\fP.
4560.TP
4561.B horizontal\-scroll\-mode (Off)
4562When set to \fBOn\fP, makes readline use a single line for display,
4563scrolling the input horizontally on a single screen line when it
4564becomes longer than the screen width rather than wrapping to a new line.
4565.TP
4566.B input\-meta (Off)
4567If set to \fBOn\fP, readline will enable eight-bit input (that is,
4568it will not strip the high bit from the characters it reads),
4569regardless of what the terminal claims it can support.  The name
4570.B meta\-flag
4571is a synonym for this variable.
4572.TP
4573.B isearch\-terminators (``C\-[C\-J'')
4574The string of characters that should terminate an incremental
4575search without subsequently executing the character as a command.
4576If this variable has not been given a value, the characters
4577\fIESC\fP and \fIC\-J\fP will terminate an incremental search.
4578.TP
4579.B keymap (emacs)
4580Set the current readline keymap.  The set of valid keymap names is
4581\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
4582vi\-command\fP, and
4583.IR vi\-insert .
4584\fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is
4585equivalent to \fIemacs\-standard\fP.  The default value is
4586.IR emacs ;
4587the value of
4588.B editing\-mode
4589also affects the default keymap.
4590.TP
4591.B mark\-directories (On)
4592If set to \fBOn\fP, completed directory names have a slash
4593appended.
4594.TP
4595.B mark\-modified\-lines (Off)
4596If set to \fBOn\fP, history lines that have been modified are displayed
4597with a preceding asterisk (\fB*\fP).
4598.TP
4599.B mark\-symlinked\-directories (Off)
4600If set to \fBOn\fP, completed names which are symbolic links to directories
4601have a slash appended (subject to the value of
4602\fBmark\-directories\fP).
4603.TP
4604.B match\-hidden\-files (On)
4605This variable, when set to \fBOn\fP, causes readline to match files whose
4606names begin with a `.' (hidden files) when performing filename
4607completion, unless the leading `.' is
4608supplied by the user in the filename to be completed.
4609.TP
4610.B output\-meta (Off)
4611If set to \fBOn\fP, readline will display characters with the
4612eighth bit set directly rather than as a meta-prefixed escape
4613sequence.
4614.TP
4615.B page\-completions (On)
4616If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager
4617to display a screenful of possible completions at a time.
4618.TP
4619.B print\-completions\-horizontally (Off)
4620If set to \fBOn\fP, readline will display completions with matches
4621sorted horizontally in alphabetical order, rather than down the screen.
4622.TP
4623.B show\-all\-if\-ambiguous (Off)
4624This alters the default behavior of the completion functions.  If
4625set to
4626.BR on ,
4627words which have more than one possible completion cause the
4628matches to be listed immediately instead of ringing the bell.
4629.TP
4630.B show\-all\-if\-unmodified (Off)
4631This alters the default behavior of the completion functions in
4632a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
4633If set to
4634.BR on ,
4635words which have more than one possible completion without any
4636possible partial completion (the possible completions don't share
4637a common prefix) cause the matches to be listed immediately instead
4638of ringing the bell.
4639.TP
4640.B visible\-stats (Off)
4641If set to \fBOn\fP, a character denoting a file's type as reported
4642by \fIstat\fP(2) is appended to the filename when listing possible
4643completions.
4644.PD
4645.SS "Readline Conditional Constructs"
4646.PP
4647Readline implements a facility similar in spirit to the conditional
4648compilation features of the C preprocessor which allows key
4649bindings and variable settings to be performed as the result
4650of tests.  There are four parser directives used.
4651.IP \fB$if\fP
4652The
4653.B $if
4654construct allows bindings to be made based on the
4655editing mode, the terminal being used, or the application using
4656readline.  The text of the test extends to the end of the line;
4657no characters are required to isolate it.
4658.RS
4659.IP \fBmode\fP
4660The \fBmode=\fP form of the \fB$if\fP directive is used to test
4661whether readline is in emacs or vi mode.
4662This may be used in conjunction
4663with the \fBset keymap\fP command, for instance, to set bindings in
4664the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if
4665readline is starting out in emacs mode.
4666.IP \fBterm\fP
4667The \fBterm=\fP form may be used to include terminal-specific
4668key bindings, perhaps to bind the key sequences output by the
4669terminal's function keys.  The word on the right side of the
4670.B =
4671is tested against the both full name of the terminal and the portion
4672of the terminal name before the first \fB\-\fP.  This allows
4673.I sun
4674to match both
4675.I sun
4676and
4677.IR sun\-cmd ,
4678for instance.
4679.IP \fBapplication\fP
4680The \fBapplication\fP construct is used to include
4681application-specific settings.  Each program using the readline
4682library sets the \fIapplication name\fP, and an initialization
4683file can test for a particular value.
4684This could be used to bind key sequences to functions useful for
4685a specific program.  For instance, the following command adds a
4686key sequence that quotes the current or previous word in Bash:
4687.sp 1
4688.RS
4689.nf
4690\fB$if\fP Bash
4691# Quote the current or previous word
4692"\eC\-xq": "\eeb\e"\eef\e""
4693\fB$endif\fP
4694.fi
4695.RE
4696.RE
4697.IP \fB$endif\fP
4698This command, as seen in the previous example, terminates an
4699\fB$if\fP command.
4700.IP \fB$else\fP
4701Commands in this branch of the \fB$if\fP directive are executed if
4702the test fails.
4703.IP \fB$include\fP
4704This directive takes a single filename as an argument and reads commands
4705and bindings from that file.  For example, the following directive
4706would read \fI/etc/inputrc\fP:
4707.sp 1
4708.RS
4709.nf
4710\fB$include\fP \^ \fI/etc/inputrc\fP
4711.fi
4712.RE
4713.SS Searching
4714.PP
4715Readline provides commands for searching through the command history
4716(see
4717.SM
4718.B HISTORY
4719below) for lines containing a specified string.
4720There are two search modes:
4721.I incremental
4722and
4723.IR non-incremental .
4724.PP
4725Incremental searches begin before the user has finished typing the
4726search string.
4727As each character of the search string is typed, readline displays
4728the next entry from the history matching the string typed so far.
4729An incremental search requires only as many characters as needed to
4730find the desired history entry.
4731The characters present in the value of the \fBisearch-terminators\fP
4732variable are used to terminate an incremental search.
4733If that variable has not been assigned a value the Escape and
4734Control-J characters will terminate an incremental search.
4735Control-G will abort an incremental search and restore the original
4736line.
4737When the search is terminated, the history entry containing the
4738search string becomes the current line.
4739.PP
4740To find other matching entries in the history list, type Control-S or
4741Control-R as appropriate.
4742This will search backward or forward in the history for the next
4743entry matching the search string typed so far.
4744Any other key sequence bound to a readline command will terminate
4745the search and execute that command.
4746For instance, a \fInewline\fP will terminate the search and accept
4747the line, thereby executing the command from the history list.
4748.PP
4749Readline remembers the last incremental search string.  If two
4750Control-Rs are typed without any intervening characters defining a
4751new search string, any remembered search string is used.
4752.PP
4753Non-incremental searches read the entire search string before starting
4754to search for matching history lines.  The search string may be
4755typed by the user or be part of the contents of the current line.
4756.SS "Readline Command Names"
4757.PP
4758The following is a list of the names of the commands and the default
4759key sequences to which they are bound.
4760Command names without an accompanying key sequence are unbound by default.
4761In the following descriptions, \fIpoint\fP refers to the current cursor
4762position, and \fImark\fP refers to a cursor position saved by the
4763\fBset\-mark\fP command.
4764The text between the point and mark is referred to as the \fIregion\fP.
4765.SS Commands for Moving
4766.PP
4767.PD 0
4768.TP
4769.B beginning\-of\-line (C\-a)
4770Move to the start of the current line.
4771.TP
4772.B end\-of\-line (C\-e)
4773Move to the end of the line.
4774.TP
4775.B forward\-char (C\-f)
4776Move forward a character.
4777.TP
4778.B backward\-char (C\-b)
4779Move back a character.
4780.TP
4781.B forward\-word (M\-f)
4782Move forward to the end of the next word.  Words are composed of
4783alphanumeric characters (letters and digits).
4784.TP
4785.B backward\-word (M\-b)
4786Move back to the start of the current or previous word.  Words are
4787composed of alphanumeric characters (letters and digits).
4788.TP
4789.B clear\-screen (C\-l)
4790Clear the screen leaving the current line at the top of the screen.
4791With an argument, refresh the current line without clearing the
4792screen.
4793.TP
4794.B redraw\-current\-line
4795Refresh the current line.
4796.PD
4797.SS Commands for Manipulating the History
4798.PP
4799.PD 0
4800.TP
4801.B accept\-line (Newline, Return)
4802Accept the line regardless of where the cursor is.  If this line is
4803non-empty, add it to the history list according to the state of the
4804.SM
4805.B HISTCONTROL
4806variable.  If the line is a modified history
4807line, then restore the history line to its original state.
4808.TP
4809.B previous\-history (C\-p)
4810Fetch the previous command from the history list, moving back in
4811the list.
4812.TP
4813.B next\-history (C\-n)
4814Fetch the next command from the history list, moving forward in the
4815list.
4816.TP
4817.B beginning\-of\-history (M\-<)
4818Move to the first line in the history.
4819.TP
4820.B end\-of\-history (M\->)
4821Move to the end of the input history, i.e., the line currently being
4822entered.
4823.TP
4824.B reverse\-search\-history (C\-r)
4825Search backward starting at the current line and moving `up' through
4826the history as necessary.  This is an incremental search.
4827.TP
4828.B forward\-search\-history (C\-s)
4829Search forward starting at the current line and moving `down' through
4830the history as necessary.  This is an incremental search.
4831.TP
4832.B non\-incremental\-reverse\-search\-history (M\-p)
4833Search backward through the history starting at the current line
4834using a non-incremental search for a string supplied by the user.
4835.TP
4836.B non\-incremental\-forward\-search\-history (M\-n)
4837Search forward through the history using a non-incremental search for
4838a string supplied by the user.
4839.TP
4840.B history\-search\-forward
4841Search forward through the history for the string of characters
4842between the start of the current line and the point.
4843This is a non-incremental search.
4844.TP
4845.B history\-search\-backward
4846Search backward through the history for the string of characters
4847between the start of the current line and the point.
4848This is a non-incremental search.
4849.TP
4850.B yank\-nth\-arg (M\-C\-y)
4851Insert the first argument to the previous command (usually
4852the second word on the previous line) at point.
4853With an argument
4854.IR n ,
4855insert the \fIn\fPth word from the previous command (the words
4856in the previous command begin with word 0).  A negative argument
4857inserts the \fIn\fPth word from the end of the previous command.
4858.TP
4859.B
4860yank\-last\-arg (M\-.\^, M\-_\^)
4861Insert the last argument to the previous command (the last word of
4862the previous history entry).  With an argument,
4863behave exactly like \fByank\-nth\-arg\fP.
4864Successive calls to \fByank\-last\-arg\fP move back through the history
4865list, inserting the last argument of each line in turn.
4866.TP
4867.B shell\-expand\-line (M\-C\-e)
4868Expand the line as the shell does.  This
4869performs alias and history expansion as well as all of the shell
4870word expansions.  See
4871.SM
4872.B HISTORY EXPANSION
4873below for a description of history expansion.
4874.TP
4875.B history\-expand\-line (M\-^)
4876Perform history expansion on the current line.
4877See
4878.SM
4879.B HISTORY EXPANSION
4880below for a description of history expansion.
4881.TP
4882.B magic\-space
4883Perform history expansion on the current line and insert a space.
4884See
4885.SM
4886.B HISTORY EXPANSION
4887below for a description of history expansion.
4888.TP
4889.B alias\-expand\-line
4890Perform alias expansion on the current line.
4891See
4892.SM
4893.B ALIASES
4894above for a description of alias expansion.
4895.TP
4896.B history\-and\-alias\-expand\-line
4897Perform history and alias expansion on the current line.
4898.TP
4899.B insert\-last\-argument (M\-.\^, M\-_\^)
4900A synonym for \fByank\-last\-arg\fP.
4901.TP
4902.B operate\-and\-get\-next (C\-o)
4903Accept the current line for execution and fetch the next line
4904relative to the current line from the history for editing.  Any
4905argument is ignored.
4906.TP
4907.B edit\-and\-execute\-command (C\-xC\-e)
4908Invoke an editor on the current command line, and execute the result as shell
4909commands.
4910\fBBash\fP attempts to invoke
4911.SM
4912.BR $FCEDIT ,
4913.SM
4914.BR $EDITOR ,
4915and \fIemacs\fP as the editor, in that order.
4916.PD
4917.SS Commands for Changing Text
4918.PP
4919.PD 0
4920.TP
4921.B delete\-char (C\-d)
4922Delete the character at point.  If point is at the
4923beginning of the line, there are no characters in the line, and
4924the last character typed was not bound to \fBdelete\-char\fP,
4925then return
4926.SM
4927.BR EOF .
4928.TP
4929.B backward\-delete\-char (Rubout)
4930Delete the character behind the cursor.  When given a numeric argument,
4931save the deleted text on the kill ring.
4932.TP
4933.B forward\-backward\-delete\-char
4934Delete the character under the cursor, unless the cursor is at the
4935end of the line, in which case the character behind the cursor is
4936deleted.
4937.TP
4938.B quoted\-insert (C\-q, C\-v)
4939Add the next character typed to the line verbatim.  This is
4940how to insert characters like \fBC\-q\fP, for example.
4941.TP
4942.B tab\-insert (C\-v TAB)
4943Insert a tab character.
4944.TP
4945.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
4946Insert the character typed.
4947.TP
4948.B transpose\-chars (C\-t)
4949Drag the character before point forward over the character at point,
4950moving point forward as well.
4951If point is at the end of the line, then this transposes
4952the two characters before point.
4953Negative arguments have no effect.
4954.TP
4955.B transpose\-words (M\-t)
4956Drag the word before point past the word after point,
4957moving point over that word as well.
4958If point is at the end of the line, this transposes
4959the last two words on the line.   
4960.TP
4961.B upcase\-word (M\-u)
4962Uppercase the current (or following) word.  With a negative argument,
4963uppercase the previous word, but do not move point.
4964.TP
4965.B downcase\-word (M\-l)
4966Lowercase the current (or following) word.  With a negative argument,
4967lowercase the previous word, but do not move point.
4968.TP
4969.B capitalize\-word (M\-c)
4970Capitalize the current (or following) word.  With a negative argument,
4971capitalize the previous word, but do not move point.
4972.TP
4973.B overwrite\-mode
4974Toggle overwrite mode.  With an explicit positive numeric argument,
4975switches to overwrite mode.  With an explicit non-positive numeric
4976argument, switches to insert mode.  This command affects only
4977\fBemacs\fP mode; \fBvi\fP mode does overwrite differently.
4978Each call to \fIreadline()\fP starts in insert mode.
4979In overwrite mode, characters bound to \fBself\-insert\fP replace   
4980the text at point rather than pushing the text to the right.
4981Characters bound to \fBbackward\-delete\-char\fP replace the character
4982before point with a space.  By default, this command is unbound.
4983.PD
4984.SS Killing and Yanking
4985.PP
4986.PD 0
4987.TP
4988.B kill\-line (C\-k)
4989Kill the text from point to the end of the line.
4990.TP
4991.B backward\-kill\-line (C\-x Rubout)
4992Kill backward to the beginning of the line.
4993.TP
4994.B unix\-line\-discard (C\-u)
4995Kill backward from point to the beginning of the line.
4996The killed text is saved on the kill-ring.
4997.\" There is no real difference between this and backward-kill-line
4998.TP
4999.B kill\-whole\-line
5000Kill all characters on the current line, no matter where point is.
5001.TP
5002.B kill\-word  (M\-d)
5003Kill from point to the end of the current word, or if between
5004words, to the end of the next word.
5005Word boundaries are the same as those used by \fBforward\-word\fP.
5006.TP
5007.B backward\-kill\-word (M\-Rubout)
5008Kill the word behind point.
5009Word boundaries are the same as those used by \fBbackward\-word\fP.
5010.TP
5011.B unix\-word\-rubout (C\-w)
5012Kill the word behind point, using white space as a word boundary.
5013The killed text is saved on the kill-ring.
5014.TP
5015.B unix\-filename\-rubout
5016Kill the word behind point, using white space and the slash character
5017as the word boundaries.
5018The killed text is saved on the kill-ring.
5019.TP
5020.B delete\-horizontal\-space (M\-\e)
5021Delete all spaces and tabs around point.
5022.TP
5023.B kill\-region
5024Kill the text in the current region.
5025.TP
5026.B copy\-region\-as\-kill
5027Copy the text in the region to the kill buffer.
5028.TP
5029.B copy\-backward\-word
5030Copy the word before point to the kill buffer.
5031The word boundaries are the same as \fBbackward\-word\fP.
5032.TP
5033.B copy\-forward\-word
5034Copy the word following point to the kill buffer.
5035The word boundaries are the same as \fBforward\-word\fP.
5036.TP
5037.B yank (C\-y)
5038Yank the top of the kill ring into the buffer at point.
5039.TP
5040.B yank\-pop (M\-y)
5041Rotate the kill ring, and yank the new top.  Only works following
5042.B yank
5043or
5044.BR yank\-pop .
5045.PD
5046.SS Numeric Arguments
5047.PP
5048.PD 0
5049.TP
5050.B digit\-argument (M\-0, M\-1, ..., M\-\-)
5051Add this digit to the argument already accumulating, or start a new
5052argument.  M\-\- starts a negative argument.
5053.TP
5054.B universal\-argument
5055This is another way to specify an argument.
5056If this command is followed by one or more digits, optionally with a
5057leading minus sign, those digits define the argument.
5058If the command is followed by digits, executing
5059.B universal\-argument
5060again ends the numeric argument, but is otherwise ignored.
5061As a special case, if this command is immediately followed by a
5062character that is neither a digit or minus sign, the argument count
5063for the next command is multiplied by four.
5064The argument count is initially one, so executing this function the
5065first time makes the argument count four, a second time makes the
5066argument count sixteen, and so on.
5067.PD
5068.SS Completing
5069.PP
5070.PD 0
5071.TP
5072.B complete (TAB)
5073Attempt to perform completion on the text before point.
5074.B Bash
5075attempts completion treating the text as a variable (if the
5076text begins with \fB$\fP), username (if the text begins with
5077\fB~\fP), hostname (if the text begins with \fB@\fP), or
5078command (including aliases and functions) in turn.  If none
5079of these produces a match, filename completion is attempted.
5080.TP
5081.B possible\-completions (M\-?)
5082List the possible completions of the text before point.
5083.TP
5084.B insert\-completions (M\-*)
5085Insert all completions of the text before point
5086that would have been generated by
5087\fBpossible\-completions\fP.
5088.TP
5089.B menu\-complete
5090Similar to \fBcomplete\fP, but replaces the word to be completed
5091with a single match from the list of possible completions.
5092Repeated execution of \fBmenu\-complete\fP steps through the list
5093of possible completions, inserting each match in turn.
5094At the end of the list of completions, the bell is rung
5095(subject to the setting of \fBbell\-style\fP)
5096and the original text is restored.
5097An argument of \fIn\fP moves \fIn\fP positions forward in the list
5098of matches; a negative argument may be used to move backward
5099through the list.
5100This command is intended to be bound to \fBTAB\fP, but is unbound
5101by default.
5102.TP
5103.B delete\-char\-or\-list
5104Deletes the character under the cursor if not at the beginning or
5105end of the line (like \fBdelete\-char\fP).
5106If at the end of the line, behaves identically to
5107\fBpossible\-completions\fP.
5108This command is unbound by default.
5109.TP
5110.B complete\-filename (M\-/)
5111Attempt filename completion on the text before point.
5112.TP
5113.B possible\-filename\-completions (C\-x /)
5114List the possible completions of the text before point,
5115treating it as a filename.
5116.TP
5117.B complete\-username (M\-~)
5118Attempt completion on the text before point, treating
5119it as a username.
5120.TP
5121.B possible\-username\-completions (C\-x ~)
5122List the possible completions of the text before point,
5123treating it as a username.
5124.TP
5125.B complete\-variable (M\-$)
5126Attempt completion on the text before point, treating
5127it as a shell variable.
5128.TP
5129.B possible\-variable\-completions (C\-x $)
5130List the possible completions of the text before point,
5131treating it as a shell variable.
5132.TP
5133.B complete\-hostname (M\-@)
5134Attempt completion on the text before point, treating
5135it as a hostname.
5136.TP
5137.B possible\-hostname\-completions (C\-x @)
5138List the possible completions of the text before point,
5139treating it as a hostname.
5140.TP
5141.B complete\-command (M\-!)
5142Attempt completion on the text before point, treating
5143it as a command name.  Command completion attempts to
5144match the text against aliases, reserved words, shell
5145functions, shell builtins, and finally executable filenames,
5146in that order.
5147.TP
5148.B possible\-command\-completions (C\-x !)
5149List the possible completions of the text before point,
5150treating it as a command name.
5151.TP
5152.B dynamic\-complete\-history (M\-TAB)
5153Attempt completion on the text before point, comparing
5154the text against lines from the history list for possible
5155completion matches.
5156.TP
5157.B complete\-into\-braces (M\-{)
5158Perform filename completion and insert the list of possible completions
5159enclosed within braces so the list is available to the shell (see
5160.B Brace Expansion
5161above).
5162.PD
5163.SS Keyboard Macros
5164.PP
5165.PD 0
5166.TP
5167.B start\-kbd\-macro (C\-x (\^)
5168Begin saving the characters typed into the current keyboard macro.
5169.TP
5170.B end\-kbd\-macro (C\-x )\^)
5171Stop saving the characters typed into the current keyboard macro
5172and store the definition.
5173.TP
5174.B call\-last\-kbd\-macro (C\-x e)
5175Re-execute the last keyboard macro defined, by making the characters
5176in the macro appear as if typed at the keyboard.
5177.PD
5178.SS Miscellaneous
5179.PP
5180.PD 0
5181.TP
5182.B re\-read\-init\-file (C\-x C\-r)
5183Read in the contents of the \fIinputrc\fP file, and incorporate
5184any bindings or variable assignments found there.
5185.TP
5186.B abort (C\-g)
5187Abort the current editing command and
5188ring the terminal's bell (subject to the setting of
5189.BR bell\-style ).
5190.TP
5191.B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...)
5192If the metafied character \fIx\fP is lowercase, run the command
5193that is bound to the corresponding uppercase character.
5194.TP
5195.B prefix\-meta (ESC)
5196Metafy the next character typed.
5197.SM
5198.B ESC
5199.B f
5200is equivalent to
5201.BR Meta\-f .
5202.TP
5203.B undo (C\-_, C\-x C\-u)
5204Incremental undo, separately remembered for each line.
5205.TP
5206.B revert\-line (M\-r)
5207Undo all changes made to this line.  This is like executing the
5208.B undo
5209command enough times to return the line to its initial state.
5210.TP
5211.B tilde\-expand (M\-&)
5212Perform tilde expansion on the current word.
5213.TP
5214.B set\-mark (C\-@, M\-<space>)
5215Set the mark to the point.  If a
5216numeric argument is supplied, the mark is set to that position.
5217.TP
5218.B exchange\-point\-and\-mark (C\-x C\-x)
5219Swap the point with the mark.  The current cursor position is set to
5220the saved position, and the old cursor position is saved as the mark.
5221.TP
5222.B character\-search (C\-])
5223A character is read and point is moved to the next occurrence of that
5224character.  A negative count searches for previous occurrences.
5225.TP
5226.B character\-search\-backward (M\-C\-])
5227A character is read and point is moved to the previous occurrence of that
5228character.  A negative count searches for subsequent occurrences.
5229.TP
5230.B insert\-comment (M\-#)
5231Without a numeric argument, the value of the readline
5232.B comment\-begin
5233variable is inserted at the beginning of the current line.
5234If a numeric argument is supplied, this command acts as a toggle:  if
5235the characters at the beginning of the line do not match the value
5236of \fBcomment\-begin\fP, the value is inserted, otherwise
5237the characters in \fBcomment-begin\fP are deleted from the beginning of
5238the line.
5239In either case, the line is accepted as if a newline had been typed.
5240The default value of
5241\fBcomment\-begin\fP causes this command to make the current line
5242a shell comment.
5243If a numeric argument causes the comment character to be removed, the line
5244will be executed by the shell.
5245.TP
5246.B glob\-complete\-word (M\-g)
5247The word before point is treated as a pattern for pathname expansion,
5248with an asterisk implicitly appended.  This pattern is used to
5249generate a list of matching file names for possible completions.
5250.TP
5251.B glob\-expand\-word (C\-x *)
5252The word before point is treated as a pattern for pathname expansion,
5253and the list of matching file names is inserted, replacing the word.
5254If a numeric argument is supplied, an asterisk is appended before
5255pathname expansion.
5256.TP
5257.B glob\-list\-expansions (C\-x g)
5258The list of expansions that would have been generated by
5259.B glob\-expand\-word
5260is displayed, and the line is redrawn.
5261If a numeric argument is supplied, an asterisk is appended before
5262pathname expansion.
5263.TP
5264.B dump\-functions
5265Print all of the functions and their key bindings to the
5266readline output stream.  If a numeric argument is supplied,
5267the output is formatted in such a way that it can be made part
5268of an \fIinputrc\fP file.
5269.TP
5270.B dump\-variables
5271Print all of the settable readline variables and their values to the
5272readline output stream.  If a numeric argument is supplied,
5273the output is formatted in such a way that it can be made part
5274of an \fIinputrc\fP file.
5275.TP
5276.B dump\-macros
5277Print all of the readline key sequences bound to macros and the
5278strings they ouput.  If a numeric argument is supplied,
5279the output is formatted in such a way that it can be made part
5280of an \fIinputrc\fP file.
5281.TP
5282.B display\-shell\-version (C\-x C\-v)
5283Display version information about the current instance of
5284.BR bash .
5285.PD
5286.SS Programmable Completion
5287.PP
5288When word completion is attempted for an argument to a command for
5289which a completion specification (a \fIcompspec\fP) has been defined
5290using the \fBcomplete\fP builtin (see
5291.SM
5292.B "SHELL BUILTIN COMMANDS"
5293below), the programmable completion facilities are invoked.
5294.PP
5295First, the command name is identified.
5296If a compspec has been defined for that command, the
5297compspec is used to generate the list of possible completions for the word.
5298If the command word is a full pathname, a compspec for the full
5299pathname is searched for first.
5300If no compspec is found for the full pathname, an attempt is made to
5301find a compspec for the portion following the final slash.
5302.PP
5303Once a compspec has been found, it is used to generate the list of
5304matching words.
5305If a compspec is not found, the default \fBbash\fP completion as
5306described above under \fBCompleting\fP is performed.
5307.PP
5308First, the actions specified by the compspec are used.
5309Only matches which are prefixed by the word being completed are
5310returned.
5311When the
5312.B \-f
5313or
5314.B \-d
5315option is used for filename or directory name completion, the shell
5316variable
5317.SM
5318.B FIGNORE
5319is used to filter the matches.
5320.PP
5321Any completions specified by a filename expansion pattern to the
5322\fB\-G\fP option are generated next.
5323The words generated by the pattern need not match the word
5324being completed.
5325The
5326.SM
5327.B GLOBIGNORE
5328shell variable is not used to filter the matches, but the
5329.SM
5330.B FIGNORE
5331variable is used.
5332.PP
5333Next, the string specified as the argument to the \fB\-W\fP option
5334is considered.
5335The string is first split using the characters in the
5336.SM
5337.B IFS
5338special variable as delimiters.
5339Shell quoting is honored.
5340Each word is then expanded using
5341brace expansion, tilde expansion, parameter and variable expansion,
5342command substitution, arithmetic expansion, and pathname expansion,
5343as described above under
5344.SM
5345.BR EXPANSION .
5346The results are split using the rules described above under
5347\fBWord Splitting\fP.
5348The results of the expansion are prefix-matched against the word being
5349completed, and the matching words become the possible completions.
5350.PP
5351After these matches have been generated, any shell function or command
5352specified with the \fB\-F\fP and \fB\-C\fP options is invoked.
5353When the command or function is invoked, the
5354.SM
5355.B COMP_LINE
5356and
5357.SM
5358.B COMP_POINT
5359variables are assigned values as described above under
5360\fBShell Variables\fP.
5361If a shell function is being invoked, the
5362.SM
5363.B COMP_WORDS
5364and
5365.SM
5366.B COMP_CWORD
5367variables are also set.
5368When the function or command is invoked, the first argument is the
5369name of the command whose arguments are being completed, the
5370second argument is the word being completed, and the third argument
5371is the word preceding the word being completed on the current command line.
5372No filtering of the generated completions against the word being completed
5373is performed; the function or command has complete freedom in generating
5374the matches.
5375.PP
5376Any function specified with \fB\-F\fP is invoked first.
5377The function may use any of the shell facilities, including the
5378\fBcompgen\fP builtin described below, to generate the matches.
5379It must put the possible completions in the
5380.SM
5381.B COMPREPLY
5382array variable.
5383.PP
5384Next, any command specified with the \fB\-C\fP option is invoked
5385in an environment equivalent to command substitution.
5386It should print a list of completions, one per line, to the
5387standard output.
5388Backslash may be used to escape a newline, if necessary.
5389.PP
5390After all of the possible completions are generated, any filter
5391specified with the \fB\-X\fP option is applied to the list.
5392The filter is a pattern as used for pathname expansion; a \fB&\fP
5393in the pattern is replaced with the text of the word being completed.
5394A literal \fB&\fP may be escaped with a backslash; the backslash
5395is removed before attempting a match.
5396Any completion that matches the pattern will be removed from the list.
5397A leading \fB!\fP negates the pattern; in this case any completion
5398not matching the pattern will be removed.
5399.PP
5400Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP
5401options are added to each member of the completion list, and the result is
5402returned to the readline completion code as the list of possible
5403completions.
5404.PP
5405If the previously-applied actions do not generate any matches, and the
5406\fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the
5407compspec was defined, directory name completion is attempted.
5408.PP
5409If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the
5410compspec was defined, directory name completion is attempted and any
5411matches are added to the results of the other actions.
5412.PP
5413By default, if a compspec is found, whatever it generates is returned
5414to the completion code as the full set of possible completions.
5415The default \fBbash\fP completions are not attempted, and the readline
5416default of filename completion is disabled.
5417If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when
5418the compspec was defined, the \fBbash\fP default completions are attempted
5419if the compspec generates no matches.
5420If the \fB\-o default\fP option was supplied to \fBcomplete\fP when the
5421compspec was defined, readline's default completion will be performed
5422if the compspec (and, if attempted, the default \fBbash\fP completions)
5423generate no matches.
5424.PP
5425When a compspec indicates that directory name completion is desired,
5426the programmable completion functions force readline to append a slash
5427to completed names which are symbolic links to directories, subject to 
5428the value of the \fBmark\-directories\fP readline variable, regardless
5429of the setting of the \fBmark-symlinked\-directories\fP readline variable.
5430.SH HISTORY
5431When the
5432.B \-o history
5433option to the
5434.B set
5435builtin is enabled, the shell provides access to the
5436\fIcommand history\fP,
5437the list of commands previously typed.
5438The value of the \fBHISTSIZE\fP variable is used as the
5439number of commands to save in a history list.
5440The text of the last
5441.SM
5442.B HISTSIZE
5443commands (default 500) is saved.  The shell
5444stores each command in the history list prior to parameter and
5445variable expansion (see
5446.SM
5447.B EXPANSION
5448above) but after history expansion is performed, subject to the
5449values of the shell variables
5450.SM
5451.B HISTIGNORE
5452and
5453.SM
5454.BR HISTCONTROL .
5455.PP
5456On startup, the history is initialized from the file named by
5457the variable
5458.SM
5459.B HISTFILE
5460(default \fI~/.bash_history\fP).
5461The file named by the value of
5462.SM
5463.B HISTFILE
5464is truncated, if necessary, to contain no more than
5465the number of lines specified by the value of
5466.SM
5467.BR HISTFILESIZE .
5468When an interactive shell exits, the last
5469.SM
5470.B $HISTSIZE
5471lines are copied from the history list to
5472.SM
5473.BR $HISTFILE .
5474If the
5475.B histappend
5476shell option is enabled
5477(see the description of
5478.B shopt
5479under
5480.SM
5481.B "SHELL BUILTIN COMMANDS"
5482below), the lines are appended to the history file,
5483otherwise the history file is overwritten.
5484If
5485.SM
5486.B HISTFILE
5487is unset, or if the history file is unwritable, the history is
5488not saved.  After saving the history, the history file is truncated
5489to contain no more than
5490.SM
5491.B HISTFILESIZE
5492lines.  If
5493.SM
5494.B HISTFILESIZE
5495is not set, no truncation is performed.
5496.PP
5497The builtin command
5498.B fc
5499(see
5500.SM
5501.B SHELL BUILTIN COMMANDS
5502below) may be used to list or edit and re-execute a portion of
5503the history list.
5504The
5505.B history
5506builtin may be used to display or modify the history list and
5507manipulate the history file.
5508When using command-line editing, search commands
5509are available in each editing mode that provide access to the
5510history list.
5511.PP
5512The shell allows control over which commands are saved on the history
5513list.  The
5514.SM
5515.B HISTCONTROL
5516and
5517.SM
5518.B HISTIGNORE
5519variables may be set to cause the shell to save only a subset of the
5520commands entered.
5521The
5522.B cmdhist
5523shell option, if enabled, causes the shell to attempt to save each
5524line of a multi-line command in the same history entry, adding
5525semicolons where necessary to preserve syntactic correctness.
5526The
5527.B lithist
5528shell option causes the shell to save the command with embedded newlines
5529instead of semicolons.  See the description of the
5530.B shopt
5531builtin below under
5532.SM
5533.B "SHELL BUILTIN COMMANDS"
5534for information on setting and unsetting shell options.
5535.SH "HISTORY EXPANSION"
5536.PP
5537The shell supports a history expansion feature that
5538is similar to the history expansion in
5539.BR csh.
5540This section describes what syntax features are available.  This
5541feature is enabled by default for interactive shells, and can be
5542disabled using the
5543.B \+H
5544option to the
5545.B set
5546builtin command (see
5547.SM
5548.B SHELL BUILTIN COMMANDS
5549below).  Non-interactive shells do not perform history expansion
5550by default.
5551.PP
5552History expansions introduce words from the history list into
5553the input stream, making it easy to repeat commands, insert the
5554arguments to a previous command into the current input line, or
5555fix errors in previous commands quickly.
5556.PP
5557History expansion is performed immediately after a complete line
5558is read, before the shell breaks it into words.
5559It takes place in two parts.
5560The first is to determine which line from the history list
5561to use during substitution.
5562The second is to select portions of that line for inclusion into
5563the current one.
5564The line selected from the history is the \fIevent\fP,
5565and the portions of that line that are acted upon are \fIwords\fP.
5566Various \fImodifiers\fP are available to manipulate the selected words.
5567The line is broken into words in the same fashion as when reading input,
5568so that several \fImetacharacter\fP-separated words surrounded by
5569quotes are considered one word.
5570History expansions are introduced by the appearance of the
5571history expansion character, which is \^\fB!\fP\^ by default.
5572Only backslash (\^\fB\e\fP\^) and single quotes can quote
5573the history expansion character.
5574.PP
5575Several characters inhibit history expansion if found immediately
5576following the history expansion character, even if it is unquoted:
5577space, tab, newline, carriage return, and \fB=\fP.
5578If the \fBextglob\fP shell option is enabled, \fB(\fP will also
5579inhibit expansion.
5580.PP
5581Several shell options settable with the
5582.B shopt
5583builtin may be used to tailor the behavior of history expansion.
5584If the
5585.B histverify
5586shell option is enabled (see the description of the
5587.B shopt
5588builtin), and
5589.B readline
5590is being used, history substitutions are not immediately passed to
5591the shell parser.
5592Instead, the expanded line is reloaded into the
5593.B readline
5594editing buffer for further modification.
5595If
5596.B readline
5597is being used, and the
5598.B histreedit
5599shell option is enabled, a failed history substitution will be reloaded
5600into the
5601.B readline
5602editing buffer for correction.
5603The
5604.B \-p
5605option to the
5606.B history
5607builtin command may be used to see what a history expansion will
5608do before using it.
5609The
5610.B \-s
5611option to the
5612.B history
5613builtin may be used to add commands to the end of the history list
5614without actually executing them, so that they are available for
5615subsequent recall.
5616.PP
5617The shell allows control of the various characters used by the
5618history expansion mechanism (see the description of
5619.B histchars
5620above under
5621.BR "Shell Variables" ).
5622.SS Event Designators
5623.PP
5624An event designator is a reference to a command line entry in the
5625history list.
5626.PP
5627.PD 0
5628.TP
5629.B !
5630Start a history substitution, except when followed by a
5631.BR blank ,
5632newline, carriage return, =
5633or ( (when the \fBextglob\fP shell option is enabled using
5634the \fBshopt\fP builtin).
5635.TP
5636.B !\fIn\fR
5637Refer to command line
5638.IR n .
5639.TP
5640.B !\-\fIn\fR
5641Refer to the current command line minus
5642.IR n .
5643.TP
5644.B !!
5645Refer to the previous command.  This is a synonym for `!\-1'.
5646.TP
5647.B !\fIstring\fR
5648Refer to the most recent command starting with
5649.IR string .
5650.TP
5651.B !?\fIstring\fR\fB[?]\fR
5652Refer to the most recent command containing
5653.IR string .
5654The trailing \fB?\fP may be omitted if
5655.I string
5656is followed immediately by a newline.
5657.TP
5658.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
5659Quick substitution.  Repeat the last command, replacing
5660.I string1
5661with
5662.IR string2 .
5663Equivalent to
5664``!!:s/\fIstring1\fP/\fIstring2\fP/''
5665(see \fBModifiers\fP below).
5666.TP
5667.B !#
5668The entire command line typed so far.
5669.PD
5670.SS Word Designators
5671.PP
5672Word designators are used to select desired words from the event.
5673A
5674.B :
5675separates the event specification from the word designator.
5676It may be omitted if the word designator begins with a
5677.BR ^ ,
5678.BR $ ,
5679.BR * ,
5680.BR \- ,
5681or
5682.BR % .
5683Words are numbered from the beginning of the line,
5684with the first word being denoted by 0 (zero).
5685Words are inserted into the current line separated by single spaces.
5686.PP
5687.PD 0
5688.TP
5689.B 0 (zero)
5690The zeroth word.  For the shell, this is the command
5691word.
5692.TP
5693.I n
5694The \fIn\fRth word.
5695.TP
5696.B ^
5697The first argument.  That is, word 1.
5698.TP
5699.B $
5700The last argument.
5701.TP
5702.B %
5703The word matched by the most recent `?\fIstring\fR?' search.
5704.TP
5705.I x\fB\-\fPy
5706A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
5707.TP
5708.B *
5709All of the words but the zeroth.  This is a synonym
5710for `\fI1\-$\fP'.  It is not an error to use
5711.B *
5712if there is just one
5713word in the event; the empty string is returned in that case.
5714.TP
5715.B x*
5716Abbreviates \fIx\-$\fP.
5717.TP
5718.B x\-
5719Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
5720.PD
5721.PP
5722If a word designator is supplied without an event specification, the
5723previous command is used as the event.
5724.SS Modifiers
5725.PP
5726After the optional word designator, there may appear a sequence of
5727one or more of the following modifiers, each preceded by a `:'.
5728.PP
5729.PD 0
5730.PP
5731.TP
5732.B h
5733Remove a trailing file name component, leaving only the head.
5734.TP
5735.B t
5736Remove all leading file name components, leaving the tail.
5737.TP
5738.B r
5739Remove a trailing suffix of the form \fI.xxx\fP, leaving the
5740basename.
5741.TP
5742.B e
5743Remove all but the trailing suffix.
5744.TP
5745.B p
5746Print the new command but do not execute it.
5747.TP
5748.B q
5749Quote the substituted words, escaping further substitutions.
5750.TP
5751.B x
5752Quote the substituted words as with
5753.BR q ,
5754but break into words at
5755.B blanks
5756and newlines.
5757.TP
5758.B s/\fIold\fP/\fInew\fP/
5759Substitute
5760.I new
5761for the first occurrence of
5762.I old
5763in the event line.  Any delimiter can be used in place of /.  The
5764final delimiter is optional if it is the last character of the
5765event line.  The delimiter may be quoted in
5766.I old
5767and
5768.I new
5769with a single backslash.  If & appears in
5770.IR new ,
5771it is replaced by
5772.IR old .
5773A single backslash will quote the &.  If
5774.I old
5775is null, it is set to the last
5776.I old
5777substituted, or, if no previous history substitutions took place,
5778the last
5779.I string
5780in a
5781.B !?\fIstring\fR\fB[?]\fR
5782search.
5783.TP
5784.B &
5785Repeat the previous substitution.
5786.TP
5787.B g
5788Cause changes to be applied over the entire event line.  This is
5789used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
5790or `\fB:&\fP'.  If used with
5791`\fB:s\fP', any delimiter can be used
5792in place of /, and the final delimiter is optional
5793if it is the last character of the event line.
5794An \fBa\fP may be used as a synonym for \fBg\fP.
5795.TP
5796.B G
5797Apply the following `\fBs\fP' modifier once to each word in the event line.
5798.PD
5799.SH "SHELL BUILTIN COMMANDS"
5800.\" start of bash_builtins
5801.zZ
5802.PP
5803Unless otherwise noted, each builtin command documented in this
5804section as accepting options preceded by
5805.B \-
5806accepts
5807.B \-\-
5808to signify the end of the options.
5809.sp .5
5810.PD 0
5811.TP
5812\fB:\fP [\fIarguments\fP]
5813.PD
5814No effect; the command does nothing beyond expanding
5815.I arguments
5816and performing any specified
5817redirections.  A zero exit code is returned.
5818.TP
5819\fB .\| \fP \fIfilename\fP [\fIarguments\fP]
5820.PD 0
5821.TP
5822\fBsource\fP \fIfilename\fP [\fIarguments\fP]
5823.PD
5824Read and execute commands from
5825.I filename
5826in the current
5827shell environment and return the exit status of the last command
5828executed from
5829.IR filename .
5830If
5831.I filename
5832does not contain a slash, file names in
5833.SM
5834.B PATH
5835are used to find the directory containing
5836.IR filename .
5837The file searched for in
5838.SM
5839.B PATH
5840need not be executable.
5841When \fBbash\fP is not in \fIposix mode\fP, the current directory is
5842searched if no file is found in
5843.SM
5844.BR PATH .
5845If the
5846.B sourcepath
5847option to the
5848.B shopt
5849builtin command is turned off, the
5850.SM
5851.B PATH
5852is not searched.
5853If any \fIarguments\fP are supplied, they become the positional
5854parameters when \fIfilename\fP is executed.  Otherwise the positional
5855parameters are unchanged.
5856The return status is the status of the last command exited within
5857the script (0 if no commands are executed), and false if
5858.I filename
5859is not found or cannot be read.
5860.TP
5861\fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
5862\fBAlias\fP with no arguments or with the
5863.B \-p
5864option prints the list of aliases in the form
5865\fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
5866When arguments are supplied, an alias is defined for
5867each \fIname\fP whose \fIvalue\fP is given.
5868A trailing space in  \fIvalue\fP causes the next word to be
5869checked for alias substitution when the alias is expanded.
5870For each \fIname\fP in the argument list for which no \fIvalue\fP
5871is supplied, the name and value of the alias is printed.
5872\fBAlias\fP returns true unless a \fIname\fP is given for which
5873no alias has been defined.
5874.TP
5875\fBbg\fP [\fIjobspec\fP]
5876Resume the suspended job \fIjobspec\fP in the background, as if it
5877had been started with
5878.BR & .
5879If \fIjobspec\fP is not present, the shell's notion of the
5880\fIcurrent job\fP is used.
5881.B bg
5882.I jobspec
5883returns 0 unless run when job control is disabled or, when run with
5884job control enabled, if \fIjobspec\fP was not found or started without
5885job control.
5886.TP
5887\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSV\fP]
5888.PD 0
5889.TP
5890\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
5891.TP
5892\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
5893.TP
5894\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP
5895.TP
5896\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
5897.TP
5898\fBbind\fP \fIreadline\-command\fP
5899.PD
5900Display current
5901.B readline
5902key and function bindings, bind a key sequence to a
5903.B readline
5904function or macro, or set a
5905.B readline
5906variable.
5907Each non-option argument is a command as it would appear in
5908.IR .inputrc ,
5909but each binding or command must be passed as a separate argument;
5910e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'.
5911Options, if supplied, have the following meanings:
5912.RS
5913.PD 0
5914.TP
5915.B \-m \fIkeymap\fP
5916Use
5917.I keymap
5918as the keymap to be affected by the subsequent bindings.
5919Acceptable
5920.I keymap
5921names are
5922\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
5923vi\-move, vi\-command\fP, and
5924.IR vi\-insert .
5925\fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is
5926equivalent to \fIemacs\-standard\fP.
5927.TP
5928.B \-l
5929List the names of all \fBreadline\fP functions.
5930.TP
5931.B \-p
5932Display \fBreadline\fP function names and bindings in such a way
5933that they can be re-read.
5934.TP
5935.B \-P
5936List current \fBreadline\fP function names and bindings.
5937.TP
5938.B \-v
5939Display \fBreadline\fP variable names and values in such a way that they
5940can be re-read.
5941.TP
5942.B \-V
5943List current \fBreadline\fP variable names and values.
5944.TP
5945.B \-s
5946Display \fBreadline\fP key sequences bound to macros and the strings
5947they output in such a way that they can be re-read.
5948.TP
5949.B \-S
5950Display \fBreadline\fP key sequences bound to macros and the strings
5951they output.
5952.TP
5953.B \-f \fIfilename\fP
5954Read key bindings from \fIfilename\fP.
5955.TP
5956.B \-q \fIfunction\fP
5957Query about which keys invoke the named \fIfunction\fP.
5958.TP
5959.B \-u \fIfunction\fP
5960Unbind all keys bound to the named \fIfunction\fP.
5961.TP
5962.B \-r \fIkeyseq\fP
5963Remove any current binding for \fIkeyseq\fP.
5964.TP
5965.B \-x \fIkeyseq\fP:\fIshell\-command\fP
5966Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
5967entered.
5968.PD
5969.PP
5970The return value is 0 unless an unrecognized option is given or an
5971error occurred.
5972.RE
5973.TP
5974\fBbreak\fP [\fIn\fP]
5975Exit from within a
5976.BR for ,
5977.BR while ,
5978.BR until ,
5979or
5980.B select
5981loop.  If \fIn\fP is specified, break \fIn\fP levels.
5982.I n
5983must be \(>= 1.  If
5984.I n
5985is greater than the number of enclosing loops, all enclosing loops
5986are exited.  The return value is 0 unless the shell is not executing
5987a loop when
5988.B break
5989is executed.
5990.TP
5991\fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
5992Execute the specified shell builtin, passing it
5993.IR arguments ,
5994and return its exit status.
5995This is useful when defining a
5996function whose name is the same as a shell builtin,
5997retaining the functionality of the builtin within the function.
5998The \fBcd\fP builtin is commonly redefined this way.
5999The return status is false if
6000.I shell\-builtin
6001is not a shell builtin command.
6002.TP
6003\fBcd\fP [\fB\-L|-P\fP] [\fIdir\fP]
6004Change the current directory to \fIdir\fP.  The variable
6005.SM
6006.B HOME
6007is the
6008default
6009.IR dir .
6010The variable
6011.SM
6012.B CDPATH
6013defines the search path for the directory containing
6014.IR dir .
6015Alternative directory names in
6016.SM
6017.B CDPATH
6018are separated by a colon (:).  A null directory name in
6019.SM
6020.B CDPATH
6021is the same as the current directory, i.e., ``\fB.\fP''.  If
6022.I dir
6023begins with a slash (/),
6024then
6025.SM
6026.B CDPATH
6027is not used. The
6028.B \-P
6029option says to use the physical directory structure instead of
6030following symbolic links (see also the
6031.B \-P
6032option to the
6033.B set
6034builtin command); the
6035.B \-L
6036option forces symbolic links to be followed.  An argument of
6037.B \-
6038is equivalent to
6039.SM
6040.BR $OLDPWD .
6041If a non-empty directory name from \fBCDPATH\fP is used, or if
6042\fB\-\fP is the first argument, and the directory change is
6043successful, the absolute pathname of the new working directory is
6044written to the standard output.
6045The return value is true if the directory was successfully changed;
6046false otherwise.
6047.TP
6048\fBcaller\fP [\fIexpr\fP]
6049Returns the context of any active subroutine call (a shell function or
6050a script executed with the \fB.\fP or \fBsource\fP builtins.
6051Without \fIexpr\fP, \fBcaller\fP displays the line number and source
6052filename of the current subroutine call.
6053If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
6054displays the line number, subroutine name, and source file corresponding
6055to that position in the current execution call stack.  This extra
6056information may be used, for example, to print a stack trace.  The
6057current frame is frame 0.
6058The return value is 0 unless the shell is not executing a subroutine
6059call or \fIexpr\fP does not correspond to a valid position in the
6060call stack.
6061.TP
6062\fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...]
6063Run
6064.I command
6065with
6066.I args
6067suppressing the normal shell function lookup. Only builtin
6068commands or commands found in the
6069.SM
6070.B PATH
6071are executed.  If the
6072.B \-p
6073option is given, the search for
6074.I command
6075is performed using a default value for
6076.B PATH
6077that is guaranteed to find all of the standard utilities.
6078If either the
6079.B \-V
6080or
6081.B \-v
6082option is supplied, a description of
6083.I command
6084is printed.  The
6085.B \-v
6086option causes a single word indicating the command or file name
6087used to invoke
6088.I command
6089to be displayed; the
6090.B \-V
6091option produces a more verbose description.
6092If the
6093.B \-V
6094or
6095.B \-v
6096option is supplied, the exit status is 0 if
6097.I command
6098was found, and 1 if not.  If neither option is supplied and
6099an error occurred or
6100.I command
6101cannot be found, the exit status is 127.  Otherwise, the exit status of the
6102.B command
6103builtin is the exit status of
6104.IR command .
6105.TP
6106\fBcompgen\fP [\fIoption\fP] [\fIword\fP]
6107Generate possible completion matches for \fIword\fP according to
6108the \fIoption\fPs, which may be any option accepted by the
6109.B complete
6110builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write
6111the matches to the standard output.
6112When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables
6113set by the programmable completion facilities, while available, will not
6114have useful values.
6115.sp 1
6116The matches will be generated in the same way as if the programmable
6117completion code had generated them directly from a completion specification
6118with the same flags.
6119If \fIword\fP is specified, only those completions matching \fIword\fP
6120will be displayed.
6121.sp 1
6122The return value is true unless an invalid option is supplied, or no
6123matches were generated.
6124.TP
6125\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP]
6126.br
6127[\fB\-X\fP \fIfilterpat\fP] [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] \fIname\fP [\fIname ...\fP]
6128.PD 0
6129.TP
6130\fBcomplete\fP \fB\-pr\fP [\fIname\fP ...]
6131.PD
6132Specify how arguments to each \fIname\fP should be completed.
6133If the \fB\-p\fP option is supplied, or if no options are supplied,
6134existing completion specifications are printed in a way that allows
6135them to be reused as input.
6136The \fB\-r\fP option removes a completion specification for
6137each \fIname\fP, or, if no \fIname\fPs are supplied, all
6138completion specifications.
6139.sp 1
6140The process of applying these completion specifications when word completion
6141is attempted is described above under \fBProgrammable Completion\fP.
6142.sp 1
6143Other options, if specified, have the following meanings.
6144The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options
6145(and, if necessary, the \fB\-P\fP and \fB\-S\fP options)
6146should be quoted to protect them from expansion before the
6147.B complete
6148builtin is invoked.
6149.RS
6150.PD 0
6151.TP 8
6152\fB\-o\fP \fIcomp-option\fP
6153The \fIcomp-option\fP controls several aspects of the compspec's behavior
6154beyond the simple generation of completions.
6155\fIcomp-option\fP may be one of:
6156.RS
6157.TP 8
6158.B bashdefault
6159Perform the rest of the default \fBbash\fP completions if the compspec
6160generates no matches.
6161.TP 8
6162.B default
6163Use readline's default filename completion if the compspec generates
6164no matches.
6165.TP 8
6166.B dirnames
6167Perform directory name completion if the compspec generates no matches.
6168.TP 8
6169.B filenames
6170Tell readline that the compspec generates filenames, so it can perform any
6171filename\-specific processing (like adding a slash to directory names or
6172suppressing trailing spaces).  Intended to be used with shell functions.
6173.TP 8
6174.B nospace
6175Tell readline not to append a space (the default) to words completed at
6176the end of the line.
6177.RE
6178.TP 8
6179\fB\-A\fP \fIaction\fP
6180The \fIaction\fP may be one of the following to generate a list of possible
6181completions:
6182.RS
6183.TP 8
6184.B alias
6185Alias names.  May also be specified as \fB\-a\fP.
6186.TP 8
6187.B arrayvar
6188Array variable names.
6189.TP 8
6190.B binding
6191\fBReadline\fP key binding names.
6192.TP 8
6193.B builtin
6194Names of shell builtin commands.  May also be specified as \fB\-b\fP.
6195.TP 8
6196.B command
6197Command names.  May also be specified as \fB\-c\fP.
6198.TP 8
6199.B directory
6200Directory names.  May also be specified as \fB\-d\fP.
6201.TP 8
6202.B disabled
6203Names of disabled shell builtins.
6204.TP 8
6205.B enabled
6206Names of enabled shell builtins.
6207.TP 8
6208.B export
6209Names of exported shell variables.  May also be specified as \fB\-e\fP.
6210.TP 8
6211.B file
6212File names.  May also be specified as \fB\-f\fP.
6213.TP 8
6214.B function
6215Names of shell functions.
6216.TP 8
6217.B group
6218Group names.  May also be specified as \fB\-g\fP.
6219.TP 8
6220.B helptopic
6221Help topics as accepted by the \fBhelp\fP builtin.
6222.TP 8
6223.B hostname
6224Hostnames, as taken from the file specified by the
6225.SM
6226.B HOSTFILE
6227shell variable.
6228.TP 8
6229.B job
6230Job names, if job control is active.  May also be specified as \fB\-j\fP.
6231.TP 8
6232.B keyword
6233Shell reserved words.  May also be specified as \fB\-k\fP.
6234.TP 8
6235.B running
6236Names of running jobs, if job control is active.
6237.TP 8
6238.B service
6239Service names.  May also be specified as \fB\-s\fP.
6240.TP 8
6241.B setopt
6242Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin.
6243.TP 8
6244.B shopt
6245Shell option names as accepted by the \fBshopt\fP builtin.
6246.TP 8
6247.B signal
6248Signal names.
6249.TP 8
6250.B stopped
6251Names of stopped jobs, if job control is active.
6252.TP 8
6253.B user
6254User names.  May also be specified as \fB\-u\fP.
6255.TP 8
6256.B variable
6257Names of all shell variables.  May also be specified as \fB\-v\fP.
6258.RE
6259.TP 8
6260\fB\-G\fP \fIglobpat\fP
6261The filename expansion pattern \fIglobpat\fP is expanded to generate
6262the possible completions.
6263.TP 8
6264\fB\-W\fP \fIwordlist\fP
6265The \fIwordlist\fP is split using the characters in the
6266.SM
6267.B IFS
6268special variable as delimiters, and each resultant word is expanded.
6269The possible completions are the members of the resultant list which
6270match the word being completed.
6271.TP 8
6272\fB\-C\fP \fIcommand\fP
6273\fIcommand\fP is executed in a subshell environment, and its output is
6274used as the possible completions.
6275.TP 8
6276\fB\-F\fP \fIfunction\fP
6277The shell function \fIfunction\fP is executed in the current shell
6278environment.
6279When it finishes, the possible completions are retrieved from the value
6280of the
6281.SM
6282.B COMPREPLY
6283array variable.
6284.TP 8
6285\fB\-X\fP \fIfilterpat\fP
6286\fIfilterpat\fP is a pattern as used for filename expansion.
6287It is applied to the list of possible completions generated by the
6288preceding options and arguments, and each completion matching
6289\fIfilterpat\fP is removed from the list.
6290A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
6291case, any completion not matching \fIfilterpat\fP is removed.
6292.TP 8
6293\fB\-P\fP \fIprefix\fP
6294\fIprefix\fP is added at the beginning of each possible completion
6295after all other options have been applied.
6296.TP 8
6297\fB\-S\fP \fIsuffix\fP
6298\fIsuffix\fP is appended to each possible completion
6299after all other options have been applied.
6300.PD
6301.PP
6302The return value is true unless an invalid option is supplied, an option
6303other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP
6304argument, an attempt is made to remove a completion specification for
6305a \fIname\fP for which no specification exists, or
6306an error occurs adding a completion specification.
6307.RE
6308.TP
6309\fBcontinue\fP [\fIn\fP]
6310Resume the next iteration of the enclosing
6311.BR for ,
6312.BR while ,
6313.BR until ,
6314or
6315.B select
6316loop.
6317If
6318.I n
6319is specified, resume at the \fIn\fPth enclosing loop.
6320.I n
6321must be \(>= 1.  If
6322.I n
6323is greater than the number of enclosing loops, the last enclosing loop
6324(the ``top-level'' loop) is resumed.  The return value is 0 unless the
6325shell is not executing a loop when
6326.B continue
6327is executed.
6328.TP
6329\fBdeclare\fP [\fB\-afFirtx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
6330.PD 0
6331.TP
6332\fBtypeset\fP [\fB\-afFirtx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
6333.PD
6334Declare variables and/or give them attributes.
6335If no \fIname\fPs are given then display the values of variables.
6336The
6337.B \-p
6338option will display the attributes and values of each
6339.IR name .
6340When
6341.B \-p
6342is used, additional options are ignored.
6343The
6344.B \-F
6345option inhibits the display of function definitions; only the
6346function name and attributes are printed.
6347If the \fBextdebug\fP shell option is enabled using \fBshopt\fP,
6348the source file name and line number where the function is defined
6349are displayed as well.  The
6350.B \-F
6351option implies
6352.BR \-f .
6353The following options can
6354be used to restrict output to variables with the specified attribute or
6355to give variables attributes:
6356.RS
6357.PD 0
6358.TP
6359.B \-a
6360Each \fIname\fP is an array variable (see
6361.B Arrays
6362above).
6363.TP
6364.B \-f
6365Use function names only.
6366.TP
6367.B \-i
6368The variable is treated as an integer; arithmetic evaluation (see
6369.SM
6370.B "ARITHMETIC EVALUATION" ") "
6371is performed when the variable is assigned a value.
6372.TP
6373.B \-r
6374Make \fIname\fPs readonly.  These names cannot then be assigned values
6375by subsequent assignment statements or unset.
6376.TP
6377.B \-t
6378Give each \fIname\fP the \fItrace\fP attribute.
6379Traced functions inherit the \fBDEBUG\fP trap from the calling shell.
6380The trace attribute has no special meaning for variables.
6381.TP
6382.B \-x
6383Mark \fIname\fPs for export to subsequent commands via the environment.
6384.PD
6385.PP
6386Using `+' instead of `\-'
6387turns off the attribute instead, with the exception that \fB+a\fP
6388may not be used to destroy an array variable.  When used in a function,
6389makes each
6390\fIname\fP local, as with the
6391.B local
6392command.
6393If a variable name is followed by =\fIvalue\fP, the value of
6394the variable is set to \fIvalue\fP.
6395The return value is 0 unless an invalid option is encountered,
6396an attempt is made to define a function using
6397.if n ``\-f foo=bar'',
6398.if t \f(CW\-f foo=bar\fP,
6399an attempt is made to assign a value to a readonly variable,
6400an attempt is made to assign a value to an array variable without
6401using the compound assignment syntax (see
6402.B Arrays
6403above), one of the \fInames\fP is not a valid shell variable name,
6404an attempt is made to turn off readonly status for a readonly variable,
6405an attempt is made to turn off array status for an array variable,
6406or an attempt is made to display a non-existent function with \fB\-f\fP.
6407.RE
6408.TP
6409.B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
6410Without options, displays the list of currently remembered directories.
6411The default display is on a single line with directory names separated
6412by spaces.
6413Directories are added to the list with the
6414.B pushd
6415command; the
6416.B popd
6417command removes entries from the list.
6418.RS
6419.PD 0
6420.TP
6421\fB+\fP\fIn\fP
6422Displays the \fIn\fPth entry counting from the left of the list
6423shown by
6424.B dirs
6425when invoked without options, starting with zero.
6426.TP
6427\fB\-\fP\fIn\fP
6428Displays the \fIn\fPth entry counting from the right of the list
6429shown by
6430.B dirs
6431when invoked without options, starting with zero.
6432.TP
6433.B \-c
6434Clears the directory stack by deleting all of the entries.
6435.TP
6436.B \-l
6437Produces a longer listing; the default listing format uses a
6438tilde to denote the home directory.
6439.TP
6440.B \-p
6441Print the directory stack with one entry per line.
6442.TP
6443.B \-v
6444Print the directory stack with one entry per line,
6445prefixing each entry with its index in the stack.
6446.PD
6447.PP
6448The return value is 0 unless an
6449invalid option is supplied or \fIn\fP indexes beyond the end
6450of the directory stack.
6451.RE
6452.TP
6453\fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ...]
6454Without options, each
6455.I jobspec
6456is removed from the table of active jobs.
6457If the \fB\-h\fP option is given, each
6458.I jobspec
6459is not removed from the table, but is marked so that
6460.SM
6461.B SIGHUP
6462is not sent to the job if the shell receives a
6463.SM
6464.BR SIGHUP .
6465If no
6466.I jobspec
6467is present, and neither the
6468.B \-a
6469nor the
6470.B \-r
6471option is supplied, the \fIcurrent job\fP is used.
6472If no
6473.I jobspec
6474is supplied, the
6475.B \-a
6476option means to remove or mark all jobs; the
6477.B \-r
6478option without a
6479.I jobspec
6480argument restricts operation to running jobs.
6481The return value is 0 unless a
6482.I jobspec
6483does not specify a valid job.
6484.TP
6485\fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...]
6486Output the \fIarg\fPs, separated by spaces, followed by a newline.
6487The return status is always 0.
6488If \fB\-n\fP is specified, the trailing newline is
6489suppressed.  If the \fB\-e\fP option is given, interpretation of
6490the following backslash-escaped characters is enabled.  The
6491.B \-E
6492option disables the interpretation of these escape characters,
6493even on systems where they are interpreted by default.
6494The \fBxpg_echo\fP shell option may be used to
6495dynamically determine whether or not \fBecho\fP expands these
6496escape characters by default.
6497.B echo
6498does not interpret
6499.B \-\-
6500to mean the end of options.
6501.B echo
6502interprets the following escape sequences:
6503.RS
6504.PD 0
6505.TP
6506.B \ea
6507alert (bell)
6508.TP
6509.B \eb
6510backspace
6511.TP
6512.B \ec
6513suppress trailing newline
6514.TP
6515.B \ee
6516an escape character
6517.TP
6518.B \ef
6519form feed
6520.TP
6521.B \en
6522new line
6523.TP
6524.B \er
6525carriage return
6526.TP
6527.B \et
6528horizontal tab
6529.TP
6530.B \ev
6531vertical tab
6532.TP
6533.B \e\e
6534backslash
6535.TP
6536.B \e0\fInnn\fP
6537the eight-bit character whose value is the octal value \fInnn\fP
6538(zero to three octal digits)
6539.TP
6540.B \e\fInnn\fP
6541the eight-bit character whose value is the octal value \fInnn\fP
6542(one to three octal digits)
6543.TP
6544.B \ex\fIHH\fP
6545the eight-bit character whose value is the hexadecimal value \fIHH\fP
6546(one or two hex digits)
6547.PD
6548.RE
6549.TP
6550\fBenable\fP [\fB\-adnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...]
6551Enable and disable builtin shell commands.
6552Disabling a builtin allows a disk command which has the same name
6553as a shell builtin to be executed without specifying a full pathname,
6554even though the shell normally searches for builtins before disk commands.
6555If \fB\-n\fP is used, each \fIname\fP
6556is disabled; otherwise,
6557\fInames\fP are enabled.  For example, to use the
6558.B test
6559binary found via the
6560.SM
6561.B PATH
6562instead of the shell builtin version, run
6563.if t \f(CWenable -n test\fP.
6564.if n ``enable -n test''.
6565The
6566.B \-f
6567option means to load the new builtin command
6568.I name
6569from shared object
6570.IR filename ,
6571on systems that support dynamic loading.  The
6572.B \-d
6573option will delete a builtin previously loaded with
6574.BR \-f .
6575If no \fIname\fP arguments are given, or if the
6576.B \-p
6577option is supplied, a list of shell builtins is printed.
6578With no other option arguments, the list consists of all enabled
6579shell builtins.
6580If \fB\-n\fP is supplied, only disabled builtins are printed.
6581If \fB\-a\fP is supplied, the list printed includes all builtins, with an
6582indication of whether or not each is enabled.
6583If \fB\-s\fP is supplied, the output is restricted to the POSIX
6584\fIspecial\fP builtins.
6585The return value is 0 unless a
6586.I name
6587is not a shell builtin or there is an error loading a new builtin
6588from a shared object.
6589.TP
6590\fBeval\fP [\fIarg\fP ...]
6591The \fIarg\fPs are read and concatenated together into a single
6592command.  This command is then read and executed by the shell, and
6593its exit status is returned as the value of
6594.BR eval .
6595If there are no
6596.IR args ,
6597or only null arguments,
6598.B eval
6599returns 0.
6600.TP
6601\fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]]
6602If
6603.I command
6604is specified, it replaces the shell.
6605No new process is created.  The
6606.I arguments
6607become the arguments to \fIcommand\fP.
6608If the
6609.B \-l
6610option is supplied,
6611the shell places a dash at the beginning of the zeroth arg passed to
6612.IR command .
6613This is what
6614.IR login (1)
6615does.  The
6616.B \-c
6617option causes
6618.I command
6619to be executed with an empty environment.  If
6620.B \-a
6621is supplied, the shell passes
6622.I name
6623as the zeroth argument to the executed command.  If
6624.I command
6625cannot be executed for some reason, a non-interactive shell exits,
6626unless the shell option
6627.B execfail
6628is enabled, in which case it returns failure.
6629An interactive shell returns failure if the file cannot be executed.
6630If
6631.I command
6632is not specified, any redirections take effect in the current shell,
6633and the return status is 0.  If there is a redirection error, the
6634return status is 1.
6635.TP
6636\fBexit\fP [\fIn\fP]
6637Cause the shell to exit
6638with a status of \fIn\fP.  If
6639.I n
6640is omitted, the exit status
6641is that of the last command executed.
6642A trap on
6643.SM
6644.B EXIT
6645is executed before the shell terminates.
6646.TP
6647\fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ...
6648.PD 0
6649.TP
6650.B export \-p
6651.PD
6652The supplied
6653.I names
6654are marked for automatic export to the environment of
6655subsequently executed commands.  If the
6656.B \-f
6657option is given,
6658the
6659.I names
6660refer to functions.
6661If no
6662.I names
6663are given, or if the
6664.B \-p
6665option is supplied, a list
6666of all names that are exported in this shell is printed.
6667The
6668.B \-n
6669option causes the export property to be removed from each
6670\fIname\fP.
6671If a variable name is followed by =\fIword\fP, the value of
6672the variable is set to \fIword\fP.
6673.B export
6674returns an exit status of 0 unless an invalid option is
6675encountered,
6676one of the \fInames\fP is not a valid shell variable name, or
6677.B \-f
6678is supplied with a
6679.I name
6680that is not a function.
6681.TP
6682\fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-nlr\fP] [\fIfirst\fP] [\fIlast\fP]
6683.PD 0
6684.TP
6685\fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
6686.PD
6687Fix Command.  In the first form, a range of commands from
6688.I first
6689to
6690.I last
6691is selected from the history list.
6692.I First
6693and
6694.I last
6695may be specified as a string (to locate the last command beginning
6696with that string) or as a number (an index into the history list,
6697where a negative number is used as an offset from the current
6698command number).  If
6699.I last
6700is not specified it is set to
6701the current command for listing (so that
6702.if n ``fc \-l \-10''
6703.if t \f(CWfc \-l \-10\fP
6704prints the last 10 commands) and to
6705.I first
6706otherwise.
6707If
6708.I first
6709is not specified it is set to the previous
6710command for editing and \-16 for listing.
6711.sp 1
6712The
6713.B \-n
6714option suppresses
6715the command numbers when listing.  The
6716.B \-r
6717option reverses the order of
6718the commands.  If the
6719.B \-l
6720option is given,
6721the commands are listed on
6722standard output.  Otherwise, the editor given by
6723.I ename
6724is invoked
6725on a file containing those commands.  If
6726.I ename
6727is not given, the
6728value of the
6729.SM
6730.B FCEDIT
6731variable is used, and
6732the value of
6733.SM
6734.B EDITOR
6735if
6736.SM
6737.B FCEDIT
6738is not set.  If neither variable is set,
6739.FN vi
6740is used.  When editing is complete, the edited commands are
6741echoed and executed.
6742.sp 1
6743In the second form, \fIcommand\fP is re-executed after each instance
6744of \fIpat\fP is replaced by \fIrep\fP.
6745A useful alias to use with this is
6746.if n ``r="fc -s"'',
6747.if t \f(CWr='fc \-s'\fP,
6748so that typing
6749.if n ``r cc''
6750.if t \f(CWr cc\fP
6751runs the last command beginning with
6752.if n ``cc''
6753.if t \f(CWcc\fP
6754and typing
6755.if n ``r''
6756.if t \f(CWr\fP
6757re-executes the last command.
6758.sp 1
6759If the first form is used, the return value is 0 unless an invalid
6760option is encountered or
6761.I first
6762or
6763.I last
6764specify history lines out of range.
6765If the
6766.B \-e
6767option is supplied, the return value is the value of the last
6768command executed or failure if an error occurs with the temporary
6769file of commands.  If the second form is used, the return status
6770is that of the command re-executed, unless
6771.I cmd
6772does not specify a valid history line, in which case
6773.B fc
6774returns failure.
6775.TP
6776\fBfg\fP [\fIjobspec\fP]
6777Resume
6778.I jobspec
6779in the foreground, and make it the current job.
6780If
6781.I jobspec
6782is not present, the shell's notion of the \fIcurrent job\fP is used.
6783The return value is that of the command placed into the foreground,
6784or failure if run when job control is disabled or, when run with
6785job control enabled, if
6786.I jobspec
6787does not specify a valid job or
6788.I jobspec
6789specifies a job that was started without job control.
6790.TP
6791\fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIargs\fP]
6792.B getopts
6793is used by shell procedures to parse positional parameters.
6794.I optstring
6795contains the option characters to be recognized; if a character
6796is followed by a colon, the option is expected to have an
6797argument, which should be separated from it by white space.
6798The colon and question mark characters may not be used as
6799option characters.
6800Each time it is invoked,
6801.B getopts
6802places the next option in the shell variable
6803.IR name ,
6804initializing
6805.I name
6806if it does not exist,
6807and the index of the next argument to be processed into the
6808variable
6809.SM
6810.BR OPTIND .
6811.SM
6812.B OPTIND
6813is initialized to 1 each time the shell or a shell script
6814is invoked.  When an option requires an argument,
6815.B getopts
6816places that argument into the variable
6817.SM
6818.BR OPTARG .
6819The shell does not reset
6820.SM
6821.B OPTIND
6822automatically; it must be manually reset between multiple
6823calls to
6824.B getopts
6825within the same shell invocation if a new set of parameters
6826is to be used.
6827.sp 1
6828When the end of options is encountered, \fBgetopts\fP exits with a
6829return value greater than zero.
6830\fBOPTIND\fP is set to the index of the first non-option argument,
6831and \fBname\fP is set to ?.
6832.sp 1
6833.B getopts
6834normally parses the positional parameters, but if more arguments are
6835given in
6836.IR args ,
6837.B getopts
6838parses those instead.
6839.sp 1
6840.B getopts
6841can report errors in two ways.  If the first character of
6842.I optstring
6843is a colon,
6844.I silent
6845error reporting is used.  In normal operation diagnostic messages
6846are printed when invalid options or missing option arguments are
6847encountered.
6848If the variable
6849.SM
6850.B OPTERR
6851is set to 0, no error messages will be displayed, even if the first
6852character of
6853.I optstring
6854is not a colon.
6855.sp 1
6856If an invalid option is seen,
6857.B getopts
6858places ? into
6859.I name
6860and, if not silent,
6861prints an error message and unsets
6862.SM
6863.BR OPTARG .
6864If
6865.B getopts
6866is silent,
6867the option character found is placed in
6868.SM
6869.B OPTARG
6870and no diagnostic message is printed.
6871.sp 1
6872If a required argument is not found, and
6873.B getopts
6874is not silent,
6875a question mark (\^\fB?\fP\^) is placed in
6876.IR name ,
6877.SM
6878.B OPTARG
6879is unset, and a diagnostic message is printed.
6880If
6881.B getopts
6882is silent, then a colon (\^\fB:\fP\^) is placed in
6883.I name
6884and
6885.SM
6886.B OPTARG
6887is set to the option character found.
6888.sp 1
6889.B getopts
6890returns true if an option, specified or unspecified, is found.
6891It returns false if the end of options is encountered or an
6892error occurs.
6893.TP
6894\fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
6895For each
6896.IR name ,
6897the full file name of the command is determined by searching
6898the directories in
6899.B $PATH
6900and remembered.
6901If the
6902.B \-p
6903option is supplied, no path search is performed, and
6904.I filename
6905is used as the full file name of the command.
6906The
6907.B \-r
6908option causes the shell to forget all
6909remembered locations.
6910The
6911.B \-d
6912option causes the shell to forget the remembered location of each \fIname\fP.
6913If the
6914.B \-t
6915option is supplied, the full pathname to which each \fIname\fP corresponds
6916is printed.  If multiple \fIname\fP arguments are supplied with \fB\-t\fP,
6917the \fIname\fP is printed before the hashed full pathname.
6918The
6919.B \-l
6920option causes output to be displayed in a format that may be reused as input.
6921If no arguments are given, or if only \fB\-l\fP is supplied,
6922information about remembered commands is printed.
6923The return status is true unless a
6924.I name
6925is not found or an invalid option is supplied.
6926.TP
6927\fBhelp\fP [\fB\-s\fP] [\fIpattern\fP]
6928Display helpful information about builtin commands.  If
6929.I pattern
6930is specified,
6931.B help
6932gives detailed help on all commands matching
6933.IR pattern ;
6934otherwise help for all the builtins and shell control structures
6935is printed.
6936The \fB\-s\fP option restricts the information displayed to a short
6937usage synopsis.
6938The return status is 0 unless no command matches
6939.IR pattern .
6940.TP
6941\fBhistory [\fIn\fP]
6942.PD 0
6943.TP
6944\fBhistory\fP \fB\-c\fP
6945.TP
6946\fBhistory \-d\fP \fIoffset\fP
6947.TP
6948\fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
6949.TP
6950\fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP]
6951.TP
6952\fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP]
6953.PD
6954With no options, display the command
6955history list with line numbers.  Lines listed
6956with a
6957.B *
6958have been modified.  An argument of
6959.I n
6960lists only the last
6961.I n
6962lines.
6963If the shell variable \fBHISTTIMEFORMAT\fP is set and not null,
6964it is used as a format string for \fIstrftime\fP(3) to display
6965the time stamp associated with each displayed history entry.
6966No intervening blank is printed between the formatted time stamp
6967and the history line.
6968If \fIfilename\fP is supplied, it is used as the
6969name of the history file; if not, the value of
6970.SM
6971.B HISTFILE
6972is used.  Options, if supplied, have the following meanings:
6973.RS
6974.PD 0
6975.TP
6976.B \-c
6977Clear the history list by deleting all the entries.
6978.TP
6979\fB\-d\fP \fIoffset\fP
6980Delete the history entry at position \fIoffset\fP.
6981.TP
6982.B \-a
6983Append the ``new'' history lines (history lines entered since the
6984beginning of the current \fBbash\fP session) to the history file.
6985.TP
6986.B \-n
6987Read the history lines not already read from the history
6988file into the current history list.  These are lines
6989appended to the history file since the beginning of the
6990current \fBbash\fP session.
6991.TP
6992.B \-r
6993Read the contents of the history file
6994and use them as the current history.
6995.TP
6996.B \-w
6997Write the current history to the history file, overwriting the
6998history file's contents.
6999.TP
7000.B \-p
7001Perform history substitution on the following \fIargs\fP and display
7002the result on the standard output.
7003Does not store the results in the history list.
7004Each \fIarg\fP must be quoted to disable normal history expansion.
7005.TP
7006.B \-s
7007Store the
7008.I args
7009in the history list as a single entry.  The last command in the
7010history list is removed before the
7011.I args
7012are added.
7013.PD
7014.PP
7015If the \fBHISTTIMEFORMAT\fP is set, the time stamp information
7016associated with each history entry is written to the history file.
7017The return value is 0 unless an invalid option is encountered, an
7018error occurs while reading or writing the history file, an invalid
7019\fIoffset\fP is supplied as an argument to \fB\-d\fP, or the
7020history expansion supplied as an argument to \fB\-p\fP fails.
7021.RE
7022.TP
7023\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ]
7024.PD 0
7025.TP
7026\fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ]
7027.PD
7028The first form lists the active jobs.  The options have the following
7029meanings:
7030.RS
7031.PD 0
7032.TP
7033.B \-l
7034List process IDs
7035in addition to the normal information.
7036.TP
7037.B \-p
7038List only the process ID of the job's process group
7039leader.
7040.TP
7041.B \-n
7042Display information only about jobs that have changed status since
7043the user was last notified of their status.
7044.TP
7045.B \-r
7046Restrict output to running jobs.
7047.TP
7048.B \-s
7049Restrict output to stopped jobs.
7050.PD
7051.PP
7052If
7053.I jobspec
7054is given, output is restricted to information about that job.
7055The return status is 0 unless an invalid option is encountered
7056or an invalid
7057.I jobspec
7058is supplied.
7059.PP
7060If the
7061.B \-x
7062option is supplied,
7063.B jobs
7064replaces any
7065.I jobspec
7066found in
7067.I command
7068or
7069.I args
7070with the corresponding process group ID, and executes
7071.I command
7072passing it
7073.IR args ,
7074returning its exit status.
7075.RE
7076.TP
7077\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ...
7078.PD 0
7079.TP
7080\fBkill\fP \fB\-l\fP [\fIsigspec\fP | \fIexit_status\fP]
7081.PD
7082Send the signal named by
7083.I sigspec
7084or
7085.I signum
7086to the processes named by
7087.I pid
7088or
7089.IR jobspec .
7090.I sigspec
7091is either a case-insensitive signal name such as
7092.SM
7093.B SIGKILL
7094(with or without the
7095.SM
7096.B SIG
7097prefix) or a signal number;
7098.I signum
7099is a signal number.
7100If
7101.I sigspec
7102is not present, then
7103.SM
7104.B SIGTERM
7105is assumed.
7106An argument of
7107.B \-l
7108lists the signal names.
7109If any arguments are supplied when
7110.B \-l
7111is given, the names of the signals corresponding to the arguments are
7112listed, and the return status is 0.
7113The \fIexit_status\fP argument to
7114.B \-l
7115is a number specifying either a signal number or the exit status of
7116a process terminated by a signal.
7117.B kill
7118returns true if at least one signal was successfully sent, or false
7119if an error occurs or an invalid option is encountered.
7120.TP
7121\fBlet\fP \fIarg\fP [\fIarg\fP ...]
7122Each
7123.I arg
7124is an arithmetic expression to be evaluated (see
7125.SM
7126.BR "ARITHMETIC EVALUATION" ).
7127If the last
7128.I arg
7129evaluates to 0,
7130.B let
7131returns 1; 0 is returned otherwise.
7132.TP
7133\fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ...]
7134For each argument, a local variable named
7135.I name
7136is created, and assigned
7137.IR value .
7138The \fIoption\fP can be any of the options accepted by \fBdeclare\fP.
7139When
7140.B local
7141is used within a function, it causes the variable
7142.I name
7143to have a visible scope restricted to that function and its children.
7144With no operands,
7145.B local
7146writes a list of local variables to the standard output.  It is
7147an error to use
7148.B local
7149when not within a function.  The return status is 0 unless
7150.B local
7151is used outside a function, an invalid
7152.I name
7153is supplied, or
7154\fIname\fP is a readonly variable.
7155.TP
7156.B logout
7157Exit a login shell.
7158.TP
7159\fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
7160Removes entries from the directory stack.  With no arguments,
7161removes the top directory from the stack, and performs a
7162.B cd
7163to the new top directory.
7164Arguments, if supplied, have the following meanings:
7165.RS
7166.PD 0
7167.TP
7168\fB+\fP\fIn\fP
7169Removes the \fIn\fPth entry counting from the left of the list
7170shown by
7171.BR dirs ,
7172starting with zero.  For example:
7173.if n ``popd +0''
7174.if t \f(CWpopd +0\fP
7175removes the first directory,
7176.if n ``popd +1''
7177.if t \f(CWpopd +1\fP
7178the second.
7179.TP
7180\fB\-\fP\fIn\fP
7181Removes the \fIn\fPth entry counting from the right of the list
7182shown by
7183.BR dirs ,
7184starting with zero.  For example:
7185.if n ``popd -0''
7186.if t \f(CWpopd -0\fP
7187removes the last directory,
7188.if n ``popd -1''
7189.if t \f(CWpopd -1\fP
7190the next to last.
7191.TP
7192.B \-n
7193Suppresses the normal change of directory when removing directories
7194from the stack, so that only the stack is manipulated.
7195.PD
7196.PP
7197If the
7198.B popd
7199command is successful, a
7200.B dirs
7201is performed as well, and the return status is 0.
7202.B popd
7203returns false if an invalid option is encountered, the directory stack
7204is empty, a non-existent directory stack entry is specified, or the
7205directory change fails.
7206.RE
7207.TP
7208\fBprintf\fP \fIformat\fP [\fIarguments\fP]
7209Write the formatted \fIarguments\fP to the standard output under the
7210control of the \fIformat\fP.
7211The \fIformat\fP is a character string which contains three types of objects:
7212plain characters, which are simply copied to standard output, character
7213escape sequences, which are converted and copied to the standard output, and
7214format specifications, each of which causes printing of the next successive
7215\fIargument\fP.
7216In addition to the standard \fIprintf\fP(1) formats, \fB%b\fP causes
7217\fBprintf\fP to expand backslash escape sequences in the corresponding
7218\fIargument\fP (except that \fB\ec\fP terminates output, backslashes in
7219\fB\e'\fP, \fB\e"\fP, and \fB\e?\fP are not removed, and octal escapes
7220beginning with \fB\e0\fP may contain up to four digits),
7221and \fB%q\fP causes \fBprintf\fP to output the corresponding
7222\fIargument\fP in a format that can be reused as shell input.
7223.sp 1
7224The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
7225If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
7226extra format specifications behave as if a zero value or null string, as
7227appropriate, had been supplied.  The return value is zero on success,
7228non-zero on failure.
7229.TP
7230\fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
7231.PD 0
7232.TP
7233\fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
7234.PD
7235Adds a directory to the top of the directory stack, or rotates
7236the stack, making the new top of the stack the current working
7237directory.  With no arguments, exchanges the top two directories
7238and returns 0, unless the directory stack is empty.
7239Arguments, if supplied, have the following meanings:
7240.RS
7241.PD 0
7242.TP
7243\fB+\fP\fIn\fP
7244Rotates the stack so that the \fIn\fPth directory
7245(counting from the left of the list shown by
7246.BR dirs ,
7247starting with zero)
7248is at the top.
7249.TP
7250\fB\-\fP\fIn\fP
7251Rotates the stack so that the \fIn\fPth directory
7252(counting from the right of the list shown by
7253.BR dirs ,
7254starting with zero) is at the top.
7255.TP
7256.B \-n
7257Suppresses the normal change of directory when adding directories
7258to the stack, so that only the stack is manipulated.
7259.TP
7260.I dir
7261Adds
7262.I dir
7263to the directory stack at the top, making it the
7264new current working directory.
7265.PD
7266.PP
7267If the
7268.B pushd
7269command is successful, a
7270.B dirs
7271is performed as well.
7272If the first form is used,
7273.B pushd
7274returns 0 unless the cd to
7275.I dir
7276fails.  With the second form,
7277.B pushd
7278returns 0 unless the directory stack is empty,
7279a non-existent directory stack element is specified,
7280or the directory change to the specified new current directory
7281fails.
7282.RE
7283.TP
7284\fBpwd\fP [\fB\-LP\fP]
7285Print the absolute pathname of the current working directory.
7286The pathname printed contains no symbolic links if the
7287.B \-P
7288option is supplied or the
7289.B \-o physical
7290option to the
7291.B set
7292builtin command is enabled.
7293If the
7294.B \-L
7295option is used, the pathname printed may contain symbolic links.
7296The return status is 0 unless an error occurs while
7297reading the name of the current directory or an
7298invalid option is supplied.
7299.TP
7300\fBread\fP [\fB\-ers\fP] [\fB\-u\fP \fIfd\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-a\fP \fIaname\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-n\fP \fInchars\fP] [\fB\-d\fP \fIdelim\fP] [\fIname\fP ...]
7301One line is read from the standard input, or from the file descriptor
7302\fIfd\fP supplied as an argument to the \fB\-u\fP option, and the first word
7303is assigned to the first
7304.IR name ,
7305the second word to the second
7306.IR name ,
7307and so on, with leftover words and their intervening separators assigned
7308to the last
7309.IR name .
7310If there are fewer words read from the input stream than names,
7311the remaining names are assigned empty values.
7312The characters in
7313.SM
7314.B IFS
7315are used to split the line into words.
7316The backslash character (\fB\e\fP) may be used to remove any special
7317meaning for the next character read and for line continuation.
7318Options, if supplied, have the following meanings:
7319.RS
7320.PD 0
7321.TP
7322.B \-a \fIaname\fP
7323The words are assigned to sequential indices
7324of the array variable
7325.IR aname ,
7326starting at 0.
7327.I aname
7328is unset before any new values are assigned.
7329Other \fIname\fP arguments are ignored.
7330.TP
7331.B \-d \fIdelim\fP
7332The first character of \fIdelim\fP is used to terminate the input line,
7333rather than newline.
7334.TP
7335.B \-e
7336If the standard input
7337is coming from a terminal,
7338.B readline
7339(see
7340.SM
7341.B READLINE
7342above) is used to obtain the line.
7343.TP
7344.B \-n \fInchars\fP
7345\fBread\fP returns after reading \fInchars\fP characters rather than
7346waiting for a complete line of input.
7347.TP
7348.B \-p \fIprompt\fP
7349Display \fIprompt\fP on standard error, without a
7350trailing newline, before attempting to read any input.  The prompt
7351is displayed only if input is coming from a terminal.
7352.TP
7353.B \-r
7354Backslash does not act as an escape character.
7355The backslash is considered to be part of the line.
7356In particular, a backslash-newline pair may not be used as a line
7357continuation.
7358.TP
7359.B \-s
7360Silent mode.  If input is coming from a terminal, characters are
7361not echoed.
7362.TP
7363.B \-t \fItimeout\fP
7364Cause \fBread\fP to time out and return failure if a complete line of
7365input is not read within \fItimeout\fP seconds.
7366This option has no effect if \fBread\fP is not reading input from the
7367terminal or a pipe.
7368.TP
7369.B \-u \fIfd\FP
7370Read input from file descriptor \fIfd\fP.
7371.PD
7372.PP
7373If no
7374.I names
7375are supplied, the line read is assigned to the variable
7376.SM
7377.BR REPLY .
7378The return code is zero, unless end-of-file is encountered, \fBread\fP
7379times out, or an invalid file descriptor is supplied as the argument to
7380\fB\-u\fP.
7381.RE
7382.TP
7383\fBreadonly\fP [\fB\-apf\fP] [\fIname\fP[=\fIword\fP] ...]
7384.PD
7385The given
7386\fInames\fP are marked readonly; the values of these
7387.I names
7388may not be changed by subsequent assignment.
7389If the
7390.B \-f
7391option is supplied, the functions corresponding to the
7392\fInames\fP are so
7393marked.
7394The
7395.B \-a
7396option restricts the variables to arrays.
7397If no
7398.I name
7399arguments are given, or if the
7400.B \-p
7401option is supplied, a list of all readonly names is printed.
7402The
7403.B \-p
7404option causes output to be displayed in a format that
7405may be reused as input.
7406If a variable name is followed by =\fIword\fP, the value of
7407the variable is set to \fIword\fP.
7408The return status is 0 unless an invalid option is encountered,
7409one of the
7410.I names
7411is not a valid shell variable name, or
7412.B \-f
7413is supplied with a
7414.I name
7415that is not a function.
7416.TP
7417\fBreturn\fP [\fIn\fP]
7418Causes a function to exit with the return value specified by
7419.IR n .
7420If
7421.I n
7422is omitted, the return status is that of the last command
7423executed in the function body.  If used outside a function,
7424but during execution of a script by the
7425.B .
7426(\fBsource\fP) command, it causes the shell to stop executing
7427that script and return either
7428.I n
7429or the exit status of the last command executed within the
7430script as the exit status of the script.  If used outside a
7431function and not during execution of a script by \fB.\fP\^,
7432the return status is false.
7433Any command associated with the \fBRETURN\fP trap is executed
7434before execution resumes after the function or script.
7435.TP
7436\fBset\fP [\fB\-\-abefhkmnptuvxBCHP\fP] [\fB\-o\fP \fIoption\fP] [\fIarg\fP ...]
7437Without options, the name and value of each shell variable are displayed
7438in a format that can be reused as input.
7439The output is sorted according to the current locale.
7440When options are specified, they set or unset shell attributes.
7441Any arguments remaining after the options are processed are treated
7442as values for the positional parameters and are assigned, in order, to
7443.BR $1 ,
7444.BR $2 ,
7445.B ...
7446.BR $\fIn\fP .
7447Options, if specified, have the following meanings:
7448.RS
7449.PD 0
7450.TP 8
7451.B \-a
7452Automatically mark variables and functions which are modified or
7453created for export to the environment of subsequent commands.
7454.TP 8
7455.B \-b
7456Report the status of terminated background jobs
7457immediately, rather than before the next primary prompt.  This is
7458effective only when job control is enabled.
7459.TP 8
7460.B \-e
7461Exit immediately if a \fIsimple command\fP (see
7462.SM
7463.B SHELL GRAMMAR
7464above) exits with a non-zero status.
7465The shell does not exit if the
7466command that fails is part of the command list immediately following a
7467.B while
7468or
7469.B until
7470keyword,
7471part of the test in an
7472.I if
7473statement, part of a
7474.B &&
7475or
7476.B \(bv\(bv
7477list, or if the command's return value is
7478being inverted via
7479.BR ! .
7480A trap on \fBERR\fP, if set, is executed before the shell exits.
7481.TP 8
7482.B \-f
7483Disable pathname expansion.
7484.TP 8
7485.B \-h
7486Remember the location of commands as they are looked up for execution.
7487This is enabled by default.
7488.TP 8
7489.B \-k
7490All arguments in the form of assignment statements
7491are placed in the environment for a command, not just
7492those that precede the command name.
7493.TP 8
7494.B \-m
7495Monitor mode.  Job control is enabled.  This option is on
7496by default for interactive shells on systems that support
7497it (see
7498.SM
7499.B JOB CONTROL
7500above).  Background processes run in a separate process
7501group and a line containing their exit status is printed
7502upon their completion.
7503.TP 8
7504.B \-n
7505Read commands but do not execute them.  This may be used to
7506check a shell script for syntax errors.  This is ignored by
7507interactive shells.
7508.TP 8
7509.B \-o \fIoption\-name\fP
7510The \fIoption\-name\fP can be one of the following:
7511.RS
7512.TP 8
7513.B allexport
7514Same as
7515.BR \-a .
7516.TP 8
7517.B braceexpand
7518Same as
7519.BR \-B .
7520.TP 8
7521.B emacs
7522Use an emacs-style command line editing interface.  This is enabled
7523by default when the shell is interactive, unless the shell is started
7524with the
7525.B \-\-noediting
7526option.
7527.TP 8
7528.B errtrace
7529Same as
7530.BR \-E .
7531.TP 8
7532.B functrace
7533Same as
7534.BR \-T .
7535.TP 8
7536.B errexit
7537Same as
7538.BR \-e .
7539.TP 8
7540.B hashall
7541Same as
7542.BR \-h .
7543.TP 8
7544.B histexpand
7545Same as
7546.BR \-H .
7547.TP 8
7548.B history
7549Enable command history, as described above under
7550.SM
7551.BR HISTORY .
7552This option is on by default in interactive shells.
7553.TP 8
7554.B ignoreeof
7555The effect is as if the shell command
7556.if t \f(CWIGNOREEOF=10\fP
7557.if n ``IGNOREEOF=10''
7558had been executed
7559(see
7560.B Shell Variables
7561above).
7562.TP 8
7563.B keyword
7564Same as
7565.BR \-k .
7566.TP 8
7567.B monitor
7568Same as
7569.BR \-m .
7570.TP 8
7571.B noclobber
7572Same as
7573.BR \-C .
7574.TP 8
7575.B noexec
7576Same as
7577.BR \-n .
7578.TP 8
7579.B noglob
7580Same as
7581.BR \-f .
7582.B nolog
7583Currently ignored.
7584.TP 8
7585.B notify
7586Same as
7587.BR \-b .
7588.TP 8
7589.B nounset
7590Same as
7591.BR \-u .
7592.TP 8
7593.B onecmd
7594Same as
7595.BR \-t .
7596.TP 8
7597.B physical
7598Same as
7599.BR \-P .
7600.TP 8
7601.B pipefail
7602If set, the return value of a pipeline is the value of the last
7603(rightmost) command to exit with a non-zero status, or zero if all
7604commands in the pipeline exit successfully.
7605This option is disabled by default.
7606.TP 8
7607.B posix
7608Change the behavior of
7609.B bash
7610where the default operation differs
7611from the POSIX 1003.2 standard to match the standard (\fI`posix mode\fP).
7612.TP 8
7613.B privileged
7614Same as
7615.BR \-p .
7616.TP 8
7617.B verbose
7618Same as
7619.BR \-v .
7620.TP 8
7621.B vi
7622Use a vi-style command line editing interface.
7623.TP 8
7624.B xtrace
7625Same as
7626.BR \-x .
7627.sp .5
7628.PP
7629If
7630.B \-o
7631is supplied with no \fIoption\-name\fP, the values of the current options are
7632printed.
7633If
7634.B +o
7635is supplied with no \fIoption\-name\fP, a series of
7636.B set
7637commands to recreate the current option settings is displayed on
7638the standard output.
7639.RE
7640.TP 8
7641.B \-p
7642Turn on
7643.I privileged
7644mode.  In this mode, the
7645.SM
7646.B $ENV
7647and
7648.SM
7649.B $BASH_ENV
7650files are not processed, shell functions are not inherited from the
7651environment, and the
7652.SM
7653.B SHELLOPTS
7654variable, if it appears in the environment, is ignored.
7655If the shell is started with the effective user (group) id not equal to the
7656real user (group) id, and the \fB\-p\fP option is not supplied, these actions
7657are taken and the effective user id is set to the real user id.
7658If the \fB\-p\fP option is supplied at startup, the effective user id is
7659not reset.
7660Turning this option off causes the effective user
7661and group ids to be set to the real user and group ids.
7662.TP 8
7663.B \-t
7664Exit after reading and executing one command.
7665.TP 8
7666.B \-u
7667Treat unset variables as an error when performing
7668parameter expansion.  If expansion is attempted on an
7669unset variable, the shell prints an error message, and,
7670if not interactive, exits with a non-zero status.
7671.TP 8
7672.B \-v
7673Print shell input lines as they are read.
7674.TP 8
7675.B \-x
7676After expanding each \fIsimple command\fP,
7677\fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or
7678arithmetic \fBfor\fP command, display the expanded value of
7679.SM
7680.BR PS4 ,
7681followed by the command and its expanded arguments
7682or associated word list.
7683.TP 8
7684.B \-B
7685The shell performs brace expansion (see
7686.B Brace Expansion
7687above).  This is on by default.
7688.TP 8
7689.B \-C
7690If set,
7691.B bash
7692does not overwrite an existing file with the
7693.BR > ,
7694.BR >& ,
7695and
7696.B <>
7697redirection operators.  This may be overridden when
7698creating output files by using the redirection operator
7699.B >|
7700instead of
7701.BR > .
7702.TP 8
7703.B \-E
7704If set, any trap on \fBERR\fP is inherited by shell functions, command
7705substitutions, and commands executed in a subshell environment.
7706The \fBERR\fP trap is normally not inherited in such cases.
7707.TP 8
7708.B \-H
7709Enable
7710.B !
7711style history substitution.  This option is on by
7712default when the shell is interactive.
7713.TP 8
7714.B \-P
7715If set, the shell does not follow symbolic links when executing
7716commands such as
7717.B cd
7718that change the current working directory.  It uses the
7719physical directory structure instead.  By default,
7720.B bash
7721follows the logical chain of directories when performing commands
7722which change the current directory.
7723.TP 8
7724.B \-T
7725If set, any trap on \fBDEBUG\fP is inherited by shell functions, command
7726substitutions, and commands executed in a subshell environment.
7727The \fBDEBUG\fP trap is normally not inherited in such cases.
7728.TP 8
7729.B \-\-
7730If no arguments follow this option, then the positional parameters are
7731unset.  Otherwise, the positional parameters are set to the
7732\fIarg\fPs, even if some of them begin with a
7733.BR \- .
7734.TP 8
7735.B \-
7736Signal the end of options, cause all remaining \fIarg\fPs to be
7737assigned to the positional parameters.  The
7738.B \-x
7739and
7740.B \-v
7741options are turned off.
7742If there are no \fIarg\fPs,
7743the positional parameters remain unchanged.
7744.PD
7745.PP
7746The options are off by default unless otherwise noted.
7747Using + rather than \- causes these options to be turned off.
7748The options can also be specified as arguments to an invocation of
7749the shell.
7750The current set of options may be found in
7751.BR $\- .
7752The return status is always true unless an invalid option is encountered.
7753.RE
7754.TP
7755\fBshift\fP [\fIn\fP]
7756The positional parameters from \fIn\fP+1 ... are renamed to
7757.B $1
7758.B ....
7759Parameters represented by the numbers \fB$#\fP
7760down to \fB$#\fP\-\fIn\fP+1 are unset.
7761.I n
7762must be a non-negative number less than or equal to \fB$#\fP.
7763If
7764.I n
7765is 0, no parameters are changed.
7766If
7767.I n
7768is not given, it is assumed to be 1.
7769If
7770.I n
7771is greater than \fB$#\fP, the positional parameters are not changed.
7772The return status is greater than zero if
7773.I n
7774is greater than
7775.B $#
7776or less than zero; otherwise 0.
7777.TP
7778\fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...]
7779Toggle the values of variables controlling optional shell behavior.
7780With no options, or with the
7781.B \-p
7782option, a list of all settable options is displayed, with
7783an indication of whether or not each is set.
7784The \fB\-p\fP option causes output to be displayed in a form that
7785may be reused as input.
7786Other options have the following meanings:
7787.RS
7788.PD 0
7789.TP
7790.B \-s
7791Enable (set) each \fIoptname\fP.
7792.TP
7793.B \-u
7794Disable (unset) each \fIoptname\fP.
7795.TP
7796.B \-q
7797Suppresses normal output (quiet mode); the return status indicates
7798whether the \fIoptname\fP is set or unset.
7799If multiple \fIoptname\fP arguments are given with
7800.BR \-q ,
7801the return status is zero if all \fIoptnames\fP are enabled; non-zero
7802otherwise.
7803.TP
7804.B \-o
7805Restricts the values of \fIoptname\fP to be those defined for the
7806.B \-o
7807option to the
7808.B set
7809builtin.
7810.PD
7811.PP
7812If either
7813.B \-s
7814or
7815.B \-u
7816is used with no \fIoptname\fP arguments, the display is limited to
7817those options which are set or unset, respectively.
7818Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
7819by default.
7820.PP
7821The return status when listing options is zero if all \fIoptnames\fP
7822are enabled, non-zero otherwise.  When setting or unsetting options,
7823the return status is zero unless an \fIoptname\fP is not a valid shell
7824option.
7825.PP
7826The list of \fBshopt\fP options is:
7827.if t .sp .5v
7828.if n .sp 1v
7829.PD 0
7830.TP 8
7831.B cdable_vars
7832If set, an argument to the
7833.B cd
7834builtin command that
7835is not a directory is assumed to be the name of a variable whose
7836value is the directory to change to.
7837.TP 8
7838.B cdspell
7839If set, minor errors in the spelling of a directory component in a
7840.B cd
7841command will be corrected.
7842The errors checked for are transposed characters,
7843a missing character, and one character too many.
7844If a correction is found, the corrected file name is printed,
7845and the command proceeds.
7846This option is only used by interactive shells.
7847.TP 8
7848.B checkhash
7849If set, \fBbash\fP checks that a command found in the hash
7850table exists before trying to execute it.  If a hashed command no
7851longer exists, a normal path search is performed.
7852.TP 8
7853.B checkwinsize
7854If set, \fBbash\fP checks the window size after each command
7855and, if necessary, updates the values of
7856.SM
7857.B LINES
7858and
7859.SM
7860.BR COLUMNS .
7861.TP 8
7862.B cmdhist
7863If set,
7864.B bash
7865attempts to save all lines of a multiple-line
7866command in the same history entry.  This allows
7867easy re-editing of multi-line commands.
7868.TP 8
7869.B dotglob
7870If set,
7871.B bash
7872includes filenames beginning with a `.' in the results of pathname
7873expansion.
7874.TP 8
7875.B execfail
7876If set, a non-interactive shell will not exit if
7877it cannot execute the file specified as an argument to the
7878.B exec
7879builtin command.  An interactive shell does not exit if
7880.B exec
7881fails.
7882.TP 8
7883.B expand_aliases
7884If set, aliases are expanded as described above under
7885.SM
7886.BR ALIASES .
7887This option is enabled by default for interactive shells.
7888.TP 8
7889.B extdebug
7890If set, behavior intended for use by debuggers is enabled:
7891.RS
7892.TP
7893.B 1.
7894The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source
7895file name and line number corresponding to each function name supplied
7896as an argument.
7897.TP
7898.B 2.
7899If the command run by the \fBDEBUG\fP trap returns a non-zero value, the
7900next command is skipped and not executed.
7901.TP
7902.B 3.
7903If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
7904shell is executing in a subroutine (a shell function or a shell script
7905executed by the \fB.\fP or \fBsource\fP builtins), a call to
7906\fBreturn\fP is simulated.
7907.RE
7908.TP 8
7909.B extglob
7910If set, the extended pattern matching features described above under
7911\fBPathname Expansion\fP are enabled.
7912.TP 8
7913.B extquote
7914If set, \fB$\fP'\fIstring\fP' and \fB$\fP"\fIstring\fP" quoting is
7915performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
7916enclosed in double quotes.  This option is enabled by default.
7917.TP 8
7918.B failglob
7919If set, patterns which fail to match filenames during pathname expansion
7920result in an expansion error.
7921.TP 8
7922.B force_fignore
7923If set, the suffixes specified by the \fBFIGNORE\fP shell variable
7924cause words to be ignored when performing word completion even if
7925the ignored words are the only possible completions.
7926See
7927.SM
7928\fBSHELL VARIABLES\fP
7929above for a description of \fBFIGNORE\fP.
7930This option is enabled by default.
7931.TP 8
7932.B gnu_errfmt
7933If set, shell error messages are written in the standard GNU error
7934message format.
7935.TP 8
7936.B histappend
7937If set, the history list is appended to the file named by the value
7938of the
7939.B HISTFILE
7940variable when the shell exits, rather than overwriting the file.
7941.TP 8
7942.B histreedit
7943If set, and
7944.B readline
7945is being used, a user is given the opportunity to re-edit a
7946failed history substitution.
7947.TP 8
7948.B histverify
7949If set, and
7950.B readline
7951is being used, the results of history substitution are not immediately
7952passed to the shell parser.  Instead, the resulting line is loaded into
7953the \fBreadline\fP editing buffer, allowing further modification.
7954.TP 8
7955.B hostcomplete
7956If set, and
7957.B readline
7958is being used, \fBbash\fP will attempt to perform hostname completion when a
7959word containing a \fB@\fP is being completed (see
7960.B Completing
7961under
7962.SM
7963.B READLINE
7964above).
7965This is enabled by default.
7966.TP 8
7967.B huponexit
7968If set, \fBbash\fP will send
7969.SM
7970.B SIGHUP
7971to all jobs when an interactive login shell exits.
7972.TP 8
7973.B interactive_comments
7974If set, allow a word beginning with
7975.B #
7976to cause that word and all remaining characters on that
7977line to be ignored in an interactive shell (see
7978.SM
7979.B COMMENTS
7980above).  This option is enabled by default.
7981.TP 8
7982.B lithist
7983If set, and the
7984.B cmdhist
7985option is enabled, multi-line commands are saved to the history with
7986embedded newlines rather than using semicolon separators where possible.
7987.TP 8
7988.B login_shell
7989The shell sets this option if it is started as a login shell (see
7990.SM
7991.B "INVOCATION"
7992above).
7993The value may not be changed.
7994.TP 8
7995.B mailwarn
7996If set, and a file that \fBbash\fP is checking for mail has been 
7997accessed since the last time it was checked, the message ``The mail in
7998\fImailfile\fP has been read'' is displayed.
7999.TP 8
8000.B no_empty_cmd_completion
8001If set, and
8002.B readline
8003is being used,
8004.B bash
8005will not attempt to search the \fBPATH\fP for possible completions when
8006completion is attempted on an empty line.
8007.TP 8
8008.B nocaseglob
8009If set,
8010.B bash
8011matches filenames in a case\-insensitive fashion when performing pathname
8012expansion (see
8013.B Pathname Expansion
8014above).
8015.TP 8
8016.B nullglob
8017If set,
8018.B bash
8019allows patterns which match no
8020files (see
8021.B Pathname Expansion
8022above)
8023to expand to a null string, rather than themselves.
8024.TP 8
8025.B progcomp
8026If set, the programmable completion facilities (see
8027\fBProgrammable Completion\fP above) are enabled.
8028This option is enabled by default.
8029.TP 8
8030.B promptvars
8031If set, prompt strings undergo
8032parameter expansion, command substitution, arithmetic
8033expansion, and quote removal after being expanded as described in
8034.SM
8035.B PROMPTING
8036above.  This option is enabled by default.
8037.TP 8
8038.B restricted_shell
8039The shell sets this option if it is started in restricted mode (see
8040.SM
8041.B "RESTRICTED SHELL"
8042below).
8043The value may not be changed.
8044This is not reset when the startup files are executed, allowing
8045the startup files to discover whether or not a shell is restricted.
8046.TP 8
8047.B shift_verbose
8048If set, the
8049.B shift
8050builtin prints an error message when the shift count exceeds the
8051number of positional parameters.
8052.TP 8
8053.B sourcepath
8054If set, the
8055\fBsource\fP (\fB.\fP) builtin uses the value of
8056.SM
8057.B PATH
8058to find the directory containing the file supplied as an argument.
8059This option is enabled by default.
8060.TP 8
8061.B xpg_echo
8062If set, the \fBecho\fP builtin expands backslash-escape sequences
8063by default.
8064.RE
8065.TP
8066\fBsuspend\fP [\fB\-f\fP]
8067Suspend the execution of this shell until it receives a
8068.SM
8069.B SIGCONT
8070signal.  The
8071.B \-f
8072option says not to complain if this is
8073a login shell; just suspend anyway.  The return status is 0 unless
8074the shell is a login shell and
8075.B \-f
8076is not supplied, or if job control is not enabled.
8077.TP
8078\fBtest\fP \fIexpr\fP
8079.PD 0
8080.TP
8081\fB[\fP \fIexpr\fP \fB]\fP
8082Return a status of 0 or 1 depending on
8083the evaluation of the conditional expression
8084.IR expr .
8085Each operator and operand must be a separate argument.
8086Expressions are composed of the primaries described above under
8087.SM
8088.BR "CONDITIONAL EXPRESSIONS" .
8089.if t .sp 0.5
8090.if n .sp 1
8091Expressions may be combined using the following operators, listed
8092in decreasing order of precedence.
8093.RS
8094.PD 0
8095.TP
8096.B ! \fIexpr\fP
8097True if
8098.I expr
8099is false.
8100.TP
8101.B ( \fIexpr\fP )
8102Returns the value of \fIexpr\fP.
8103This may be used to override the normal precedence of operators.
8104.TP
8105\fIexpr1\fP \-\fBa\fP \fIexpr2\fP
8106True if both
8107.I expr1
8108and
8109.I expr2
8110are true.
8111.TP
8112\fIexpr1\fP \-\fBo\fP \fIexpr2\fP
8113True if either
8114.I expr1
8115or
8116.I expr2
8117is true.
8118.PD
8119.PP
8120\fBtest\fP and \fB[\fP evaluate conditional
8121expressions using a set of rules based on the number of arguments.
8122.if t .sp 0.5
8123.if n .sp 1
8124.PD 0
8125.TP
81260 arguments
8127The expression is false.
8128.TP
81291 argument
8130The expression is true if and only if the argument is not null.
8131.TP
81322 arguments
8133If the first argument is \fB!\fP, the expression is true if and
8134only if the second argument is null.
8135If the first argument is one of the unary conditional operators listed above
8136under
8137.SM
8138.BR "CONDITIONAL EXPRESSIONS" ,
8139the expression is true if the unary test is true.
8140If the first argument is not a valid unary conditional operator, the expression
8141is false.
8142.TP
81433 arguments
8144If the second argument is one of the binary conditional operators listed above
8145under
8146.SM
8147.BR "CONDITIONAL EXPRESSIONS" ,
8148the result of the expression is the result of the binary test using
8149the first and third arguments as operands.
8150If the first argument is \fB!\fP, the value is the negation of
8151the two-argument test using the second and third arguments.
8152If the first argument is exactly \fB(\fP and the third argument is
8153exactly \fB)\fP, the result is the one-argument test of the second
8154argument.
8155Otherwise, the expression is false.
8156The \fB\-a\fP and \fB\-o\fP operators are considered binary operators
8157in this case. 
8158.TP
81594 arguments
8160If the first argument is \fB!\fP, the result is the negation of
8161the three-argument expression composed of the remaining arguments.
8162Otherwise, the expression is parsed and evaluated according to
8163precedence using the rules listed above.
8164.TP
81655 or more arguments
8166The expression is parsed and evaluated according to precedence
8167using the rules listed above.
8168.RE
8169.PD
8170.TP
8171.B times
8172Print the accumulated user and system times for the shell and
8173for processes run from the shell.  The return status is 0.
8174.TP
8175\fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...]
8176The command
8177.I arg
8178is to be read and executed when the shell receives
8179signal(s)
8180.IR sigspec .
8181If
8182.I arg
8183is absent (and there is a single \fIsigspec\fP) or
8184.BR \- ,
8185each specified signal is
8186reset to its original disposition (the value it had
8187upon entrance to the shell).
8188If
8189.I arg
8190is the null string the signal specified by each
8191.I sigspec
8192is ignored by the shell and by the commands it invokes.
8193If
8194.I arg
8195is not present and
8196.B \-p
8197has been supplied, then the trap commands associated with each
8198.I sigspec
8199are displayed.
8200If no arguments are supplied or if only
8201.B \-p
8202is given,
8203.B trap
8204prints the list of commands associated with each signal.
8205The
8206.B \-l
8207option causes the shell to print a list of signal names and
8208their corresponding numbers.
8209Each
8210.I sigspec
8211is either
8212a signal name defined in <\fIsignal.h\fP>, or a signal number.
8213Signal names are case insensitive and the SIG prefix is optional.
8214If a
8215.I sigspec
8216is
8217.SM
8218.B EXIT
8219(0) the command
8220.I arg
8221is executed on exit from the shell.
8222If a
8223.I sigspec
8224is
8225.SM
8226.BR DEBUG ,
8227the command
8228.I arg
8229is executed before every \fIsimple command\fP, \fIfor\fP command,
8230\fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP
8231command, and before the first command executes in a shell function (see
8232.SM
8233.B SHELL GRAMMAR
8234above).
8235Refer to the description of the \fBextglob\fP option to the
8236\fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap.
8237If a
8238.I sigspec
8239is
8240.SM
8241.BR ERR ,
8242the command
8243.I arg
8244is executed whenever a simple command has a non\-zero exit status,
8245subject to the following conditions.
8246The
8247.SM
8248.B ERR
8249trap is not executed if the failed
8250command is part of the command list immediately following a
8251.B while
8252or
8253.B until
8254keyword,
8255part of the test in an
8256.I if
8257statement, part of a
8258.B &&
8259or
8260.B \(bv\(bv
8261list, or if the command's return value is
8262being inverted via
8263.BR ! .
8264These are the same conditions obeyed by the \fBerrexit\fP option.
8265If a
8266.I sigspec
8267is
8268.SM
8269.BR RETURN ,
8270the command
8271.I arg
8272is executed each time a shell function or a script executed with the
8273\fB.\fP or \fBsource\fP builtins finishes executing.
8274Signals ignored upon entry to the shell cannot be trapped or reset.
8275Trapped signals are reset to their original values in a child
8276process when it is created.
8277The return status is false if any
8278.I sigspec
8279is invalid; otherwise
8280.B trap
8281returns true.
8282.TP
8283\fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...]
8284With no options,
8285indicate how each
8286.I name
8287would be interpreted if used as a command name.
8288If the
8289.B \-t
8290option is used,
8291.B type
8292prints a string which is one of
8293.IR alias ,
8294.IR keyword ,
8295.IR function ,
8296.IR builtin ,
8297or
8298.I file
8299if
8300.I name
8301is an alias, shell reserved word, function, builtin, or disk file,
8302respectively.
8303If the
8304.I name
8305is not found, then nothing is printed, and an exit status of false
8306is returned.
8307If the
8308.B \-p
8309option is used,
8310.B type
8311either returns the name of the disk file
8312that would be executed if
8313.I name
8314were specified as a command name,
8315or nothing if
8316.if t \f(CWtype -t name\fP
8317.if n ``type -t name''
8318would not return
8319.IR file .
8320The
8321.B \-P
8322option forces a
8323.SM
8324.B PATH
8325search for each \fIname\fP, even if
8326.if t \f(CWtype -t name\fP
8327.if n ``type -t name''
8328would not return
8329.IR file .
8330If a command is hashed,
8331.B \-p
8332and
8333.B \-P
8334print the hashed value, not necessarily the file that appears
8335first in
8336.SM
8337.BR PATH .
8338If the
8339.B \-a
8340option is used,
8341.B type
8342prints all of the places that contain
8343an executable named
8344.IR name .
8345This includes aliases and functions,
8346if and only if the
8347.B \-p
8348option is not also used.
8349The table of hashed commands is not consulted
8350when using
8351.BR \-a .
8352The
8353.B \-f
8354option suppresses shell function lookup, as with the \fBcommand\fP builtin.
8355.B type
8356returns true if any of the arguments are found, false if
8357none are found.
8358.TP
8359\fBulimit\fP [\fB\-SHacdflmnpstuv\fP [\fIlimit\fP]]
8360Provides control over the resources available to the shell and to
8361processes started by it, on systems that allow such control.
8362The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is
8363set for the given resource.  A hard limit cannot be increased once it
8364is set; a soft limit may be increased up to the value of the hard limit.
8365If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard
8366limits are set.
8367The value of
8368.I limit
8369can be a number in the unit specified for the resource
8370or one of the special values
8371.BR hard ,
8372.BR soft ,
8373or
8374.BR unlimited ,
8375which stand for the current hard limit, the current soft limit, and
8376no limit, respectively.
8377If
8378.I limit
8379is omitted, the current value of the soft limit of the resource is
8380printed, unless the \fB\-H\fP option is given.  When more than one
8381resource is specified, the limit name and unit are printed before the value.
8382Other options are interpreted as follows:
8383.RS
8384.PD 0
8385.TP
8386.B \-a
8387All current limits are reported
8388.TP
8389.B \-c
8390The maximum size of core files created
8391.TP
8392.B \-d
8393The maximum size of a process's data segment
8394.TP
8395.B \-f
8396The maximum size of files created by the shell
8397.TP
8398.B \-l
8399The maximum size that may be locked into memory
8400.TP
8401.B \-m
8402The maximum resident set size
8403.TP
8404.B \-n
8405The maximum number of open file descriptors (most systems do not
8406allow this value to be set)
8407.TP
8408.B \-p
8409The pipe size in 512-byte blocks (this may not be set)
8410.TP
8411.B \-s
8412The maximum stack size
8413.TP
8414.B \-t
8415The maximum amount of cpu time in seconds
8416.TP
8417.B \-u
8418The maximum number of processes available to a single user
8419.TP
8420.B \-v
8421The maximum amount of virtual memory available to the shell
8422.PD
8423.PP
8424If
8425.I limit
8426is given, it is the new value of the specified resource (the
8427.B \-a
8428option is display only).
8429If no option is given, then
8430.B \-f
8431is assumed.  Values are in 1024-byte increments, except for
8432.BR \-t ,
8433which is in seconds,
8434.BR \-p ,
8435which is in units of 512-byte blocks,
8436and
8437.B \-n
8438and
8439.BR \-u ,
8440which are unscaled values.
8441The return status is 0 unless an invalid option or argument is supplied,
8442or an error occurs while setting a new limit.
8443.RE
8444.TP
8445\fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP]
8446The user file-creation mask is set to
8447.IR mode .
8448If
8449.I mode
8450begins with a digit, it
8451is interpreted as an octal number; otherwise
8452it is interpreted as a symbolic mode mask similar
8453to that accepted by
8454.IR chmod (1).
8455If
8456.I mode
8457is omitted, the current value of the mask is printed.
8458The
8459.B \-S
8460option causes the mask to be printed in symbolic form; the
8461default output is an octal number.
8462If the
8463.B \-p
8464option is supplied, and
8465.I mode
8466is omitted, the output is in a form that may be reused as input.
8467The return status is 0 if the mode was successfully changed or if
8468no \fImode\fP argument was supplied, and false otherwise.
8469.TP
8470\fBunalias\fP [\-\fBa\fP] [\fIname\fP ...]
8471Remove each \fIname\fP from the list of defined aliases.  If
8472.B \-a
8473is supplied, all alias definitions are removed.  The return
8474value is true unless a supplied
8475.I name
8476is not a defined alias.
8477.TP
8478\fBunset\fP [\-\fBfv\fP] [\fIname\fP ...]
8479For each
8480.IR name ,
8481remove the corresponding variable or function.
8482If no options are supplied, or the
8483.B \-v
8484option is given, each
8485.I name
8486refers to a shell variable.
8487Read-only variables may not be unset.
8488If
8489.B \-f
8490is specifed,
8491each
8492.I name
8493refers to a shell function, and the function definition
8494is removed.
8495Each unset variable or function is removed from the environment
8496passed to subsequent commands.
8497If any of
8498.SM
8499.BR RANDOM ,
8500.SM
8501.BR SECONDS ,
8502.SM
8503.BR LINENO ,
8504.SM
8505.BR HISTCMD ,
8506.SM
8507.BR FUNCNAME ,
8508.SM
8509.BR GROUPS ,
8510or
8511.SM
8512.B DIRSTACK
8513are unset, they lose their special properties, even if they are
8514subsequently reset.  The exit status is true unless a
8515.I name
8516is readonly.
8517.TP
8518\fBwait\fP [\fIn\fP]
8519Wait for the specified process and return its termination
8520status.
8521.I n
8522may be a process
8523ID or a job specification; if a job spec is given, all processes
8524in that job's pipeline are waited for.  If
8525.I n
8526is not given, all currently active child processes
8527are waited for, and the return status is zero.  If
8528.I n
8529specifies a non-existent process or job, the return status is
8530127.  Otherwise, the return status is the exit status of the last
8531process or job waited for.
8532.\" bash_builtins
8533.if \n(zZ=1 .ig zZ
8534.SH "RESTRICTED SHELL"
8535.\" rbash.1
8536.zY
8537.PP
8538If
8539.B bash
8540is started with the name
8541.BR rbash ,
8542or the
8543.B \-r
8544option is supplied at invocation,
8545the shell becomes restricted.
8546A restricted shell is used to
8547set up an environment more controlled than the standard shell.
8548It behaves identically to
8549.B bash
8550with the exception that the following are disallowed or not performed:
8551.IP \(bu
8552changing directories with \fBcd\fP
8553.IP \(bu
8554setting or unsetting the values of
8555.BR SHELL ,
8556.BR PATH ,
8557.BR ENV ,
8558or
8559.B BASH_ENV
8560.IP \(bu
8561specifying command names containing
8562.B /
8563.IP \(bu
8564specifying a file name containing a
8565.B /
8566as an argument to the
8567.B .
8568builtin command
8569.IP \(bu
8570Specifying a filename containing a slash as an argument to the
8571.B \-p
8572option to the
8573.B hash
8574builtin command
8575.IP \(bu
8576importing function definitions from the shell environment at startup
8577.IP \(bu
8578parsing the value of \fBSHELLOPTS\fP from the shell environment at startup
8579.IP \(bu
8580redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
8581.IP \(bu
8582using the
8583.B exec
8584builtin command to replace the shell with another command
8585.IP \(bu
8586adding or deleting builtin commands with the
8587.B \-f
8588and
8589.B \-d
8590options to the
8591.B enable
8592builtin command
8593.IP \(bu
8594Using the \fBenable\fP builtin command to enable disabled shell builtins
8595.IP \(bu
8596specifying the
8597.B \-p
8598option to the
8599.B command
8600builtin command
8601.IP \(bu
8602turning off restricted mode with
8603\fBset +r\fP or \fBset +o restricted\fP.
8604.PP
8605These restrictions are enforced after any startup files are read.
8606.PP
8607.ie \n(zY=1 When a command that is found to be a shell script is executed,
8608.el \{ When a command that is found to be a shell script is executed
8609(see
8610.SM
8611.B "COMMAND EXECUTION"
8612above),
8613\}
8614.B rbash
8615turns off any restrictions in the shell spawned to execute the
8616script.
8617.\" end of rbash.1
8618.if \n(zY=1 .ig zY
8619.SH "SEE ALSO"
8620.PD 0
8621.TP
8622\fIBash Reference Manual\fP, Brian Fox and Chet Ramey
8623.TP
8624\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
8625.TP
8626\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
8627.TP
8628\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE
8629.TP
8630\fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
8631.TP
8632\fIemacs\fP(1), \fIvi\fP(1)
8633.TP
8634\fIreadline\fP(3)
8635.PD
8636.SH FILES
8637.PD 0
8638.TP
8639.FN /bin/bash
8640The \fBbash\fP executable
8641.TP
8642.FN /etc/profile
8643The systemwide initialization file, executed for login shells
8644.TP
8645.FN ~/.bash_profile
8646The personal initialization file, executed for login shells
8647.TP
8648.FN ~/.bashrc
8649The individual per-interactive-shell startup file
8650.TP
8651.FN ~/.bash_logout
8652The individual login shell cleanup file, executed when a login shell exits
8653.TP
8654.FN ~/.inputrc
8655Individual \fIreadline\fP initialization file
8656.PD
8657.SH AUTHORS
8658Brian Fox, Free Software Foundation
8659.br
8660bfox@gnu.org
8661.PP
8662Chet Ramey, Case Western Reserve University
8663.br
8664chet@po.CWRU.Edu
8665.SH BUG REPORTS
8666If you find a bug in
8667.B bash,
8668you should report it.  But first, you should
8669make sure that it really is a bug, and that it appears in the latest
8670version of
8671.BR bash .
8672The latest version is always available from
8673\fIftp://ftp.gnu.org/pub/bash/\fP.
8674.PP
8675Once you have determined that a bug actually exists, use the
8676.I bashbug
8677command to submit a bug report.
8678If you have a fix, you are encouraged to mail that as well!
8679Suggestions and `philosophical' bug reports may be mailed
8680to \fIbug-bash@gnu.org\fP or posted to the Usenet
8681newsgroup
8682.BR gnu.bash.bug .
8683.PP
8684ALL bug reports should include:
8685.PP
8686.PD 0
8687.TP 20
8688The version number of \fBbash\fR
8689.TP
8690The hardware and operating system
8691.TP
8692The compiler used to compile
8693.TP
8694A description of the bug behaviour
8695.TP
8696A short script or `recipe' which exercises the bug
8697.PD
8698.PP
8699.I bashbug
8700inserts the first three items automatically into the template
8701it provides for filing a bug report.
8702.PP
8703Comments and bug reports concerning
8704this manual page should be directed to
8705.IR chet@po.CWRU.Edu .
8706.SH BUGS
8707.PP
8708It's too big and too slow.
8709.PP
8710There are some subtle differences between
8711.B bash
8712and traditional versions of
8713.BR sh ,
8714mostly because of the
8715.SM
8716.B POSIX
8717specification.
8718.PP
8719Aliases are confusing in some uses.
8720.PP
8721Shell builtin commands and functions are not stoppable/restartable.
8722.PP
8723Compound commands and command sequences of the form `a ; b ; c'
8724are not handled gracefully when process suspension is attempted.
8725When a process is stopped, the shell immediately executes the next
8726command in the sequence.
8727It suffices to place the sequence of commands between
8728parentheses to force it into a subshell, which may be stopped as
8729a unit.
8730.PP
8731Commands inside of \fB$(\fP...\fB)\fP command substitution are not
8732parsed until substitution is attempted.  This will delay error
8733reporting until some time after the command is entered.  For example,
8734unmatched parentheses, even inside shell comments, will result in
8735error messages while the construct is being read.
8736.PP
8737Array variables may not (yet) be exported.
8738.zZ
8739.zY
Note: See TracBrowser for help on using the repository browser.