· 2 years ago · Oct 13, 2022, 03:10 PM
1BASH(1) General Commands Manual BASH(1)
2
3NAME
4 bash - GNU Bourne-Again SHell
5
6SYNOPSIS
7 bash [options] [file]
8
9COPYRIGHT
10 Bash is Copyright (C) 1989-2005 by the Free Software Foundation, Inc.
11
12DESCRIPTION
13 Bash is an sh-compatible command language interpreter that executes
14 commands read from the standard input or from a file. Bash also
15 incorporates useful features from the Korn and C shells (ksh and csh).
16
17 Bash is intended to be a conformant implementation of the Shell and
18 Utilities portion of the IEEE POSIX specification (IEEE Standard
19 1003.1). Bash can be configured to be POSIX-conformant by default.
20
21OPTIONS
22 In addition to the single-character shell options documented in the
23 description of the set builtin command, bash interprets the following
24 options when it is invoked:
25
26 -c string If the -c option is present, then commands are read from
27 string. If there are arguments after the string, they are
28 assigned to the positional parameters, starting with $0.
29 -i If the -i option is present, the shell is interactive.
30 -l Make bash act as if it had been invoked as a login shell (see
31 INVOCATION below).
32 -r If the -r option is present, the shell becomes restricted
33 (see RESTRICTED SHELL below).
34 -s If the -s option is present, or if no arguments remain after
35 option processing, then commands are read from the standard
36 input. This option allows the positional parameters to be
37 set when invoking an interactive shell.
38 -D A list of all double-quoted strings preceded by $ is printed
39 on the standard output. These are the strings that are
40 subject to language translation when the current locale is
41 not C or POSIX. This implies the -n option; no commands will
42 be executed.
43 [-+]O [shopt_option]
44 shopt_option is one of the shell options accepted by the
45 shopt builtin (see SHELL BUILTIN COMMANDS below). If
46 shopt_option is present, -O sets the value of that option; +O
47 unsets it. If shopt_option is not supplied, the names and
48 values of the shell options accepted by shopt are printed on
49 the standard output. If the invocation option is +O, the
50 output is displayed in a format that may be reused as input.
51 -- A -- signals the end of options and disables further option
52 processing. Any arguments after the -- are treated as
53 filenames and arguments. An argument of - is equivalent to
54 --.
55
56 Bash also interprets a number of multi-character options. These
57 options must appear on the command line before the single-character
58 options to be recognized.
59
60 --debugger
61 Arrange for the debugger profile to be executed before the shell
62 starts. Turns on extended debugging mode (see the description
63 of the extdebug option to the shopt builtin below) and shell
64 function tracing (see the description of the -o functrace option
65 to the set builtin below).
66 --dump-po-strings
67 Equivalent to -D, but the output is in the GNU gettext po
68 (portable object) file format.
69 --dump-strings
70 Equivalent to -D.
71 --help Display a usage message on standard output and exit
72 successfully.
73 --init-file file
74 --rcfile file
75 Execute commands from file instead of the standard personal
76 initialization file ~/.bashrc if the shell is interactive (see
77 INVOCATION below).
78
79 --login
80 Equivalent to -l.
81
82 --noediting
83 Do not use the GNU readline library to read command lines when
84 the shell is interactive.
85
86 --noprofile
87 Do not read either the system-wide startup file /etc/profile or
88 any of the personal initialization files ~/.bash_profile,
89 ~/.bash_login, or ~/.profile. By default, bash reads these
90 files when it is invoked as a login shell (see INVOCATION
91 below).
92
93 --norc Do not read and execute the personal initialization file
94 ~/.bashrc if the shell is interactive. This option is on by
95 default if the shell is invoked as sh.
96
97 --posix
98 Change the behavior of bash where the default operation differs
99 from the POSIX standard to match the standard (posix mode).
100
101 --restricted
102 The shell becomes restricted (see RESTRICTED SHELL below).
103
104 --verbose
105 Equivalent to -v.
106
107 --version
108 Show version information for this instance of bash on the
109 standard output and exit successfully.
110
111ARGUMENTS
112 If arguments remain after option processing, and neither the -c nor the
113 -s option has been supplied, the first argument is assumed to be the
114 name of a file containing shell commands. If bash is invoked in this
115 fashion, $0 is set to the name of the file, and the positional
116 parameters are set to the remaining arguments. Bash reads and executes
117 commands from this file, then exits. Bash's exit status is the exit
118 status of the last command executed in the script. If no commands are
119 executed, the exit status is 0. An attempt is first made to open the
120 file in the current directory, and, if no file is found, then the shell
121 searches the directories in PATH for the script.
122
123INVOCATION
124 A login shell is one whose first character of argument zero is a -, or
125 one started with the --login option.
126
127 An interactive shell is one started without non-option arguments and
128 without the -c option whose standard input and error are both connected
129 to terminals (as determined by isatty(3)), or one started with the -i
130 option. PS1 is set and $- includes i if bash is interactive, allowing
131 a shell script or a startup file to test this state.
132
133 The following paragraphs describe how bash executes its startup files.
134 If any of the files exist but cannot be read, bash reports an error.
135 Tildes are expanded in file names as described below under Tilde
136 Expansion in the EXPANSION section.
137
138 When bash is invoked as an interactive login shell, or as a non-
139 interactive shell with the --login option, it first reads and executes
140 commands from the file /etc/profile, if that file exists. After
141 reading that file, it looks for ~/.bash_profile, ~/.bash_login, and
142 ~/.profile, in that order, and reads and executes commands from the
143 first one that exists and is readable. The --noprofile option may be
144 used when the shell is started to inhibit this behavior.
145
146 When a login shell exits, bash reads and executes commands from the
147 file ~/.bash_logout, if it exists.
148
149 When an interactive shell that is not a login shell is started, bash
150 reads and executes commands from ~/.bashrc, if that file exists. This
151 may be inhibited by using the --norc option. The --rcfile file option
152 will force bash to read and execute commands from file instead of
153 ~/.bashrc.
154
155 When bash is started non-interactively, to run a shell script, for
156 example, it looks for the variable BASH_ENV in the environment, expands
157 its value if it appears there, and uses the expanded value as the name
158 of a file to read and execute. Bash behaves as if the following
159 command were executed:
160 if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
161 but the value of the PATH variable is not used to search for the file
162 name.
163
164 If bash is invoked with the name sh, it tries to mimic the startup
165 behavior of historical versions of sh as closely as possible, while
166 conforming to the POSIX standard as well. When invoked as an
167 interactive login shell, or a non-interactive shell with the --login
168 option, it first attempts to read and execute commands from
169 /etc/profile and ~/.profile, in that order. The --noprofile option may
170 be used to inhibit this behavior. When invoked as an interactive shell
171 with the name sh, bash looks for the variable ENV, expands its value if
172 it is defined, and uses the expanded value as the name of a file to
173 read and execute. Since a shell invoked as sh does not attempt to read
174 and execute commands from any other startup files, the --rcfile option
175 has no effect. A non-interactive shell invoked with the name sh does
176 not attempt to read any other startup files. When invoked as sh, bash
177 enters posix mode after the startup files are read.
178
179 When bash is started in posix mode, as with the --posix command line
180 option, it follows the POSIX standard for startup files. In this mode,
181 interactive shells expand the ENV variable and commands are read and
182 executed from the file whose name is the expanded value. No other
183 startup files are read.
184
185 Bash attempts to determine when it is being run by the remote shell
186 daemon, usually rshd. If bash determines it is being run by rshd, it
187 reads and executes commands from ~/.bashrc, if that file exists and is
188 readable. It will not do this if invoked as sh. The --norc option may
189 be used to inhibit this behavior, and the --rcfile option may be used
190 to force another file to be read, but rshd does not generally invoke
191 the shell with those options or allow them to be specified.
192
193 If the shell is started with the effective user (group) id not equal to
194 the real user (group) id, and the -p option is not supplied, no startup
195 files are read, shell functions are not inherited from the environment,
196 the SHELLOPTS variable, if it appears in the environment, is ignored,
197 and the effective user id is set to the real user id. If the -p option
198 is supplied at invocation, the startup behavior is the same, but the
199 effective user id is not reset.
200
201DEFINITIONS
202 The following definitions are used throughout the rest of this
203 document.
204 blank A space or tab.
205 word A sequence of characters considered as a single unit by the
206 shell. Also known as a token.
207 name A word consisting only of alphanumeric characters and
208 underscores, and beginning with an alphabetic character or an
209 underscore. Also referred to as an identifier.
210 metacharacter
211 A character that, when unquoted, separates words. One of the
212 following:
213 | & ; ( ) < > space tab
214 control operator
215 A token that performs a control function. It is one of the
216 following symbols:
217 || & && ; ;; ( ) | <newline>
218
219RESERVED WORDS
220 Reserved words are words that have a special meaning to the shell. The
221 following words are recognized as reserved when unquoted and either the
222 first word of a simple command (see SHELL GRAMMAR below) or the third
223 word of a case or for command:
224
225 ! case do done elif else esac fi for function if in select then until
226 while { } time [[ ]]
227
228SHELL GRAMMAR
229 Simple Commands
230 A simple command is a sequence of optional variable assignments
231 followed by blank-separated words and redirections, and terminated by a
232 control operator. The first word specifies the command to be executed,
233 and is passed as argument zero. The remaining words are passed as
234 arguments to the invoked command.
235
236 The return value of a simple command is its exit status, or 128+n if
237 the command is terminated by signal n.
238
239 Pipelines
240 A pipeline is a sequence of one or more commands separated by the
241 character |. The format for a pipeline is:
242
243 [time [-p]] [ ! ] command [ | command2 ... ]
244
245 The standard output of command is connected via a pipe to the standard
246 input of command2. This connection is performed before any
247 redirections specified by the command (see REDIRECTION below).
248
249 The return status of a pipeline is the exit status of the last command,
250 unless the pipefail option is enabled. If pipefail is enabled, the
251 pipeline's return status is the value of the last (rightmost) command
252 to exit with a non-zero status, or zero if all commands exit
253 successfully. If the reserved word ! precedes a pipeline, the exit
254 status of that pipeline is the logical negation of the exit status as
255 described above. The shell waits for all commands in the pipeline to
256 terminate before returning a value.
257
258 If the time reserved word precedes a pipeline, the elapsed as well as
259 user and system time consumed by its execution are reported when the
260 pipeline terminates. The -p option changes the output format to that
261 specified by POSIX. The TIMEFORMAT variable may be set to a format
262 string that specifies how the timing information should be displayed;
263 see the description of TIMEFORMAT under Shell Variables below.
264
265 Each command in a pipeline is executed as a separate process (i.e., in
266 a subshell).
267
268 Lists
269 A list is a sequence of one or more pipelines separated by one of the
270 operators ;, &, &&, or ⎪⎪, and optionally terminated by one of ;, &, or
271 <newline>.
272
273 Of these list operators, && and ⎪⎪ have equal precedence, followed by ;
274 and &, which have equal precedence.
275
276 A sequence of one or more newlines may appear in a list instead of a
277 semicolon to delimit commands.
278
279 If a command is terminated by the control operator &, the shell
280 executes the command in the background in a subshell. The shell does
281 not wait for the command to finish, and the return status is 0.
282 Commands separated by a ; are executed sequentially; the shell waits
283 for each command to terminate in turn. The return status is the exit
284 status of the last command executed.
285
286 The control operators && and ⎪⎪ denote AND lists and OR lists,
287 respectively. An AND list has the form
288
289 command1 && command2
290
291 command2 is executed if, and only if, command1 returns an exit status
292 of zero.
293
294 An OR list has the form
295
296 command1 ⎪⎪ command2
297
298 command2 is executed if and only if command1 returns a non-zero exit
299 status. The return status of AND and OR lists is the exit status of
300 the last command executed in the list.
301
302 Compound Commands
303 A compound command is one of the following:
304
305 (list) list is executed in a subshell environment (see COMMAND
306 EXECUTION ENVIRONMENT below). Variable assignments and builtin
307 commands that affect the shell's environment do not remain in
308 effect after the command completes. The return status is the
309 exit status of list.
310
311 { list; }
312 list is simply executed in the current shell environment. list
313 must be terminated with a newline or semicolon. This is known
314 as a group command. The return status is the exit status of
315 list. Note that unlike the metacharacters ( and ), { and } are
316 reserved words and must occur where a reserved word is permitted
317 to be recognized. Since they do not cause a word break, they
318 must be separated from list by whitespace.
319
320 ((expression))
321 The expression is evaluated according to the rules described
322 below under ARITHMETIC EVALUATION. If the value of the
323 expression is non-zero, the return status is 0; otherwise the
324 return status is 1. This is exactly equivalent to let
325 "expression".
326
327 [[ expression ]]
328 Return a status of 0 or 1 depending on the evaluation of the
329 conditional expression expression. Expressions are composed of
330 the primaries described below under CONDITIONAL EXPRESSIONS.
331 Word splitting and pathname expansion are not performed on the
332 words between the [[ and ]]; tilde expansion, parameter and
333 variable expansion, arithmetic expansion, command substitution,
334 process substitution, and quote removal are performed.
335 Conditional operators such as -f must be unquoted to be
336 recognized as primaries.
337
338 When the == and != operators are used, the string to the right
339 of the operator is considered a pattern and matched according to
340 the rules described below under Pattern Matching. If the shell
341 option nocasematch is enabled, the match is performed without
342 regard to the case of alphabetic characters. The return value
343 is 0 if the string matches (==) or does not match (!=) the
344 pattern, and 1 otherwise. Any part of the pattern may be quoted
345 to force it to be matched as a string.
346
347 An additional binary operator, =~, is available, with the same
348 precedence as == and !=. When it is used, the string to the
349 right of the operator is considered an extended regular
350 expression and matched accordingly (as in regex(3)). The return
351 value is 0 if the string matches the pattern, and 1 otherwise.
352 If the regular expression is syntactically incorrect, the
353 conditional expression's return value is 2. If the shell option
354 nocasematch is enabled, the match is performed without regard to
355 the case of alphabetic characters. Substrings matched by
356 parenthesized subexpressions within the regular expression are
357 saved in the array variable BASH_REMATCH. The element of
358 BASH_REMATCH with index 0 is the portion of the string matching
359 the entire regular expression. The element of BASH_REMATCH with
360 index n is the portion of the string matching the nth
361 parenthesized subexpression.
362
363 Expressions may be combined using the following operators,
364 listed in decreasing order of precedence:
365
366 ( expression )
367 Returns the value of expression. This may be used to
368 override the normal precedence of operators.
369 ! expression
370 True if expression is false.
371 expression1 && expression2
372 True if both expression1 and expression2 are true.
373 expression1 || expression2
374 True if either expression1 or expression2 is true.
375
376 The && and || operators do not evaluate expression2 if the value
377 of expression1 is sufficient to determine the return value of
378 the entire conditional expression.
379
380 for name [ in word ] ; do list ; done
381 The list of words following in is expanded, generating a list of
382 items. The variable name is set to each element of this list in
383 turn, and list is executed each time. If the in word is
384 omitted, the for command executes list once for each positional
385 parameter that is set (see PARAMETERS below). The return status
386 is the exit status of the last command that executes. If the
387 expansion of the items following in results in an empty list, no
388 commands are executed, and the return status is 0.
389
390 for (( expr1 ; expr2 ; expr3 )) ; do list ; done
391 First, the arithmetic expression expr1 is evaluated according to
392 the rules described below under ARITHMETIC EVALUATION. The
393 arithmetic expression expr2 is then evaluated repeatedly until
394 it evaluates to zero. Each time expr2 evaluates to a non-zero
395 value, list is executed and the arithmetic expression expr3 is
396 evaluated. If any expression is omitted, it behaves as if it
397 evaluates to 1. The return value is the exit status of the last
398 command in list that is executed, or false if any of the
399 expressions is invalid.
400
401 select name [ in word ] ; do list ; done
402 The list of words following in is expanded, generating a list of
403 items. The set of expanded words is printed on the standard
404 error, each preceded by a number. If the in word is omitted,
405 the positional parameters are printed (see PARAMETERS below).
406 The PS3 prompt is then displayed and a line read from the
407 standard input. If the line consists of a number corresponding
408 to one of the displayed words, then the value of name is set to
409 that word. If the line is empty, the words and prompt are
410 displayed again. If EOF is read, the command completes. Any
411 other value read causes name to be set to null. The line read
412 is saved in the variable REPLY. The list is executed after each
413 selection until a break command is executed. The exit status of
414 select is the exit status of the last command executed in list,
415 or zero if no commands were executed.
416
417 case word in [ [(] pattern [ | pattern ] ... ) list ;; ] ... esac
418 A case command first expands word, and tries to match it against
419 each pattern in turn, using the same matching rules as for
420 pathname expansion (see Pathname Expansion below). The word is
421 expanded using tilde expansion, parameter and variable
422 expansion, arithmetic substitution, command substitution,
423 process substitution and quote removal. Each pattern examined
424 is expanded using tilde expansion, parameter and variable
425 expansion, arithmetic substitution, command substitution, and
426 process substitution. If the shell option nocasematch is
427 enabled, the match is performed without regard to the case of
428 alphabetic characters. When a match is found, the corresponding
429 list is executed. After the first match, no subsequent matches
430 are attempted. The exit status is zero if no pattern matches.
431 Otherwise, it is the exit status of the last command executed in
432 list.
433
434 if list; then list; [ elif list; then list; ] ... [ else list; ] fi
435 The if list is executed. If its exit status is zero, the then
436 list is executed. Otherwise, each elif list is executed in
437 turn, and if its exit status is zero, the corresponding then
438 list is executed and the command completes. Otherwise, the else
439 list is executed, if present. The exit status is the exit
440 status of the last command executed, or zero if no condition
441 tested true.
442
443 while list; do list; done
444 until list; do list; done
445 The while command continuously executes the do list as long as
446 the last command in list returns an exit status of zero. The
447 until command is identical to the while command, except that the
448 test is negated; the do list is executed as long as the last
449 command in list returns a non-zero exit status. The exit status
450 of the while and until commands is the exit status of the last
451 do list command executed, or zero if none was executed.
452
453 Shell Function Definitions
454 A shell function is an object that is called like a simple command and
455 executes a compound command with a new set of positional parameters.
456 Shell functions are declared as follows:
457
458 [ function ] name () compound-command [redirection]
459 This defines a function named name. The reserved word function
460 is optional. If the function reserved word is supplied, the
461 parentheses are optional. The body of the function is the
462 compound command compound-command (see Compound Commands above).
463 That command is usually a list of commands between { and }, but
464 may be any command listed under Compound Commands above.
465 compound-command is executed whenever name is specified as the
466 name of a simple command. Any redirections (see REDIRECTION
467 below) specified when a function is defined are performed when
468 the function is executed. The exit status of a function
469 definition is zero unless a syntax error occurs or a readonly
470 function with the same name already exists. When executed, the
471 exit status of a function is the exit status of the last command
472 executed in the body. (See FUNCTIONS below.)
473
474COMMENTS
475 In a non-interactive shell, or an interactive shell in which the
476 interactive_comments option to the shopt builtin is enabled (see SHELL
477 BUILTIN COMMANDS below), a word beginning with # causes that word and
478 all remaining characters on that line to be ignored. An interactive
479 shell without the interactive_comments option enabled does not allow
480 comments. The interactive_comments option is on by default in
481 interactive shells.
482
483QUOTING
484 Quoting is used to remove the special meaning of certain characters or
485 words to the shell. Quoting can be used to disable special treatment
486 for special characters, to prevent reserved words from being recognized
487 as such, and to prevent parameter expansion.
488
489 Each of the metacharacters listed above under DEFINITIONS has special
490 meaning to the shell and must be quoted if it is to represent itself.
491
492 When the command history expansion facilities are being used (see
493 HISTORY EXPANSION below), the history expansion character, usually !,
494 must be quoted to prevent history expansion.
495
496 There are three quoting mechanisms: the escape character, single
497 quotes, and double quotes.
498
499 A non-quoted backslash (\) is the escape character. It preserves the
500 literal value of the next character that follows, with the exception of
501 <newline>. If a \<newline> pair appears, and the backslash is not
502 itself quoted, the \<newline> is treated as a line continuation (that
503 is, it is removed from the input stream and effectively ignored).
504
505 Enclosing characters in single quotes preserves the literal value of
506 each character within the quotes. A single quote may not occur between
507 single quotes, even when preceded by a backslash.
508
509 Enclosing characters in double quotes preserves the literal value of
510 all characters within the quotes, with the exception of $, `, \, and,
511 when history expansion is enabled, !. The characters $ and ` retain
512 their special meaning within double quotes. The backslash retains its
513 special meaning only when followed by one of the following characters:
514 $, `, ", \, or <newline>. A double quote may be quoted within double
515 quotes by preceding it with a backslash. If enabled, history expansion
516 will be performed unless an ! appearing in double quotes is escaped
517 using a backslash. The backslash preceding the ! is not removed.
518
519 The special parameters * and @ have special meaning when in double
520 quotes (see PARAMETERS below).
521
522 Words of the form $'string' are treated specially. The word expands to
523 string, with backslash-escaped characters replaced as specified by the
524 ANSI C standard. Backslash escape sequences, if present, are decoded
525 as follows:
526 \a alert (bell)
527 \b backspace
528 \e an escape character
529 \f form feed
530 \n new line
531 \r carriage return
532 \t horizontal tab
533 \v vertical tab
534 \\ backslash
535 \' single quote
536 \nnn the eight-bit character whose value is the octal value
537 nnn (one to three digits)
538 \xHH the eight-bit character whose value is the hexadecimal
539 value HH (one or two hex digits)
540 \cx a control-x character
541
542 The expanded result is single-quoted, as if the dollar sign had not
543 been present.
544
545 A double-quoted string preceded by a dollar sign ($) will cause the
546 string to be translated according to the current locale. If the
547 current locale is C or POSIX, the dollar sign is ignored. If the
548 string is translated and replaced, the replacement is double-quoted.
549
550PARAMETERS
551 A parameter is an entity that stores values. It can be a name, a
552 number, or one of the special characters listed below under Special
553 Parameters. A variable is a parameter denoted by a name. A variable
554 has a value and zero or more attributes. Attributes are assigned using
555 the declare builtin command (see declare below in SHELL BUILTIN
556 COMMANDS).
557
558 A parameter is set if it has been assigned a value. The null string is
559 a valid value. Once a variable is set, it may be unset only by using
560 the unset builtin command (see SHELL BUILTIN COMMANDS below).
561
562 A variable may be assigned to by a statement of the form
563
564 name=[value]
565
566 If value is not given, the variable is assigned the null string. All
567 values undergo tilde expansion, parameter and variable expansion,
568 command substitution, arithmetic expansion, and quote removal (see
569 EXPANSION below). If the variable has its integer attribute set, then
570 value is evaluated as an arithmetic expression even if the $((...))
571 expansion is not used (see Arithmetic Expansion below). Word splitting
572 is not performed, with the exception of "$@" as explained below under
573 Special Parameters. Pathname expansion is not performed. Assignment
574 statements may also appear as arguments to the alias, declare, typeset,
575 export, readonly, and local builtin commands.
576
577 In the context where an assignment statement is assigning a value to a
578 shell variable or array index, the += operator can be used to append to
579 or add to the variable's previous value. When += is applied to a
580 variable for which the integer attribute has been set, value is
581 evaluated as an arithmetic expression and added to the variable's
582 current value, which is also evaluated. When += is applied to an array
583 variable using compound assignment (see Arrays below), the variable's
584 value is not unset (as it is when using =), and new values are appended
585 to the array beginning at one greater than the array's maximum index.
586 When applied to a string-valued variable, value is expanded and
587 appended to the variable's value.
588
589 Positional Parameters
590 A positional parameter is a parameter denoted by one or more digits,
591 other than the single digit 0. Positional parameters are assigned from
592 the shell's arguments when it is invoked, and may be reassigned using
593 the set builtin command. Positional parameters may not be assigned to
594 with assignment statements. The positional parameters are temporarily
595 replaced when a shell function is executed (see FUNCTIONS below).
596
597 When a positional parameter consisting of more than a single digit is
598 expanded, it must be enclosed in braces (see EXPANSION below).
599
600 Special Parameters
601 The shell treats several parameters specially. These parameters may
602 only be referenced; assignment to them is not allowed.
603 * Expands to the positional parameters, starting from one. When
604 the expansion occurs within double quotes, it expands to a
605 single word with the value of each parameter separated by the
606 first character of the IFS special variable. That is, "$*" is
607 equivalent to "$1c$2c...", where c is the first character of the
608 value of the IFS variable. If IFS is unset, the parameters are
609 separated by spaces. If IFS is null, the parameters are joined
610 without intervening separators.
611 @ Expands to the positional parameters, starting from one. When
612 the expansion occurs within double quotes, each parameter
613 expands to a separate word. That is, "$@" is equivalent to "$1"
614 "$2" ... If the double-quoted expansion occurs within a word,
615 the expansion of the first parameter is joined with the
616 beginning part of the original word, and the expansion of the
617 last parameter is joined with the last part of the original
618 word. When there are no positional parameters, "$@" and $@
619 expand to nothing (i.e., they are removed).
620 # Expands to the number of positional parameters in decimal.
621 ? Expands to the status of the most recently executed foreground
622 pipeline.
623 - Expands to the current option flags as specified upon
624 invocation, by the set builtin command, or those set by the
625 shell itself (such as the -i option).
626 $ Expands to the process ID of the shell. In a () subshell, it
627 expands to the process ID of the current shell, not the
628 subshell.
629 ! Expands to the process ID of the most recently executed
630 background (asynchronous) command.
631 0 Expands to the name of the shell or shell script. This is set
632 at shell initialization. If bash is invoked with a file of
633 commands, $0 is set to the name of that file. If bash is
634 started with the -c option, then $0 is set to the first argument
635 after the string to be executed, if one is present. Otherwise,
636 it is set to the file name used to invoke bash, as given by
637 argument zero.
638 _ At shell startup, set to the absolute pathname used to invoke
639 the shell or shell script being executed as passed in the
640 environment or argument list. Subsequently, expands to the last
641 argument to the previous command, after expansion. Also set to
642 the full pathname used to invoke each command executed and
643 placed in the environment exported to that command. When
644 checking mail, this parameter holds the name of the mail file
645 currently being checked.
646
647 Shell Variables
648 The following variables are set by the shell:
649
650 BASH Expands to the full file name used to invoke this instance of
651 bash.
652 BASH_ARGC
653 An array variable whose values are the number of parameters in
654 each frame of the current bash execution call stack. The number
655 of parameters to the current subroutine (shell function or
656 script executed with . or source) is at the top of the stack.
657 When a subroutine is executed, the number of parameters passed
658 is pushed onto BASH_ARGC. The shell sets BASH_ARGC only when in
659 extended debugging mode (see the description of the extdebug
660 option to the shopt builtin below)
661 BASH_ARGV
662 An array variable containing all of the parameters in the
663 current bash execution call stack. The final parameter of the
664 last subroutine call is at the top of the stack; the first
665 parameter of the initial call is at the bottom. When a
666 subroutine is executed, the parameters supplied are pushed onto
667 BASH_ARGV. The shell sets BASH_ARGV only when in extended
668 debugging mode (see the description of the extdebug option to
669 the shopt builtin below)
670 BASH_COMMAND
671 The command currently being executed or about to be executed,
672 unless the shell is executing a command as the result of a trap,
673 in which case it is the command executing at the time of the
674 trap.
675 BASH_EXECUTION_STRING
676 The command argument to the -c invocation option.
677 BASH_LINENO
678 An array variable whose members are the line numbers in source
679 files corresponding to each member of FUNCNAME.
680 ${BASH_LINENO[$i]} is the line number in the source file where
681 ${FUNCNAME[$ifP]} was called. The corresponding source file
682 name is ${BASH_SOURCE[$i]}. Use LINENO to obtain the current
683 line number.
684 BASH_REMATCH
685 An array variable whose members are assigned by the =~ binary
686 operator to the [[ conditional command. The element with index
687 0 is the portion of the string matching the entire regular
688 expression. The element with index n is the portion of the
689 string matching the nth parenthesized subexpression. This
690 variable is read-only.
691 BASH_SOURCE
692 An array variable whose members are the source filenames
693 corresponding to the elements in the FUNCNAME array variable.
694 BASH_SUBSHELL
695 Incremented by one each time a subshell or subshell environment
696 is spawned. The initial value is 0.
697 BASH_VERSINFO
698 A readonly array variable whose members hold version information
699 for this instance of bash. The values assigned to the array
700 members are as follows:
701 BASH_VERSINFO[0] The major version number (the release).
702 BASH_VERSINFO[1] The minor version number (the version).
703 BASH_VERSINFO[2] The patch level.
704 BASH_VERSINFO[3] The build version.
705 BASH_VERSINFO[4] The release status (e.g., beta1).
706 BASH_VERSINFO[5] The value of MACHTYPE.
707
708 BASH_VERSION
709 Expands to a string describing the version of this instance of
710 bash.
711
712 COMP_CWORD
713 An index into ${COMP_WORDS} of the word containing the current
714 cursor position. This variable is available only in shell
715 functions invoked by the programmable completion facilities (see
716 Programmable Completion below).
717
718 COMP_LINE
719 The current command line. This variable is available only in
720 shell functions and external commands invoked by the
721 programmable completion facilities (see Programmable Completion
722 below).
723
724 COMP_POINT
725 The index of the current cursor position relative to the
726 beginning of the current command. If the current cursor
727 position is at the end of the current command, the value of this
728 variable is equal to ${#COMP_LINE}. This variable is available
729 only in shell functions and external commands invoked by the
730 programmable completion facilities (see Programmable Completion
731 below).
732
733 COMP_WORDBREAKS
734 The set of characters that the Readline library treats as word
735 separators when performing word completion. If COMP_WORDBREAKS
736 is unset, it loses its special properties, even if it is
737 subsequently reset.
738
739 COMP_WORDS
740 An array variable (see Arrays below) consisting of the
741 individual words in the current command line. The words are
742 split on shell metacharacters as the shell parser would separate
743 them. This variable is available only in shell functions
744 invoked by the programmable completion facilities (see
745 Programmable Completion below).
746
747 DIRSTACK
748 An array variable (see Arrays below) containing the current
749 contents of the directory stack. Directories appear in the
750 stack in the order they are displayed by the dirs builtin.
751 Assigning to members of this array variable may be used to
752 modify directories already in the stack, but the pushd and popd
753 builtins must be used to add and remove directories. Assignment
754 to this variable will not change the current directory. If
755 DIRSTACK is unset, it loses its special properties, even if it
756 is subsequently reset.
757
758 EUID Expands to the effective user ID of the current user,
759 initialized at shell startup. This variable is readonly.
760
761 FUNCNAME
762 An array variable containing the names of all shell functions
763 currently in the execution call stack. The element with index 0
764 is the name of any currently-executing shell function. The
765 bottom-most element is "main". This variable exists only when a
766 shell function is executing. Assignments to FUNCNAME have no
767 effect and return an error status. If FUNCNAME is unset, it
768 loses its special properties, even if it is subsequently reset.
769
770 GROUPS An array variable containing the list of groups of which the
771 current user is a member. Assignments to GROUPS have no effect
772 and return an error status. If GROUPS is unset, it loses its
773 special properties, even if it is subsequently reset.
774
775 HISTCMD
776 The history number, or index in the history list, of the current
777 command. If HISTCMD is unset, it loses its special properties,
778 even if it is subsequently reset.
779
780 HOSTNAME
781 Automatically set to the name of the current host.
782
783 HOSTTYPE
784 Automatically set to a string that uniquely describes the type
785 of machine on which bash is executing. The default is system-
786 dependent.
787
788 LINENO Each time this parameter is referenced, the shell substitutes a
789 decimal number representing the current sequential line number
790 (starting with 1) within a script or function. When not in a
791 script or function, the value substituted is not guaranteed to
792 be meaningful. If LINENO is unset, it loses its special
793 properties, even if it is subsequently reset.
794
795 MACHTYPE
796 Automatically set to a string that fully describes the system
797 type on which bash is executing, in the standard GNU cpu-
798 company-system format. The default is system-dependent.
799
800 OLDPWD The previous working directory as set by the cd command.
801
802 OPTARG The value of the last option argument processed by the getopts
803 builtin command (see SHELL BUILTIN COMMANDS below).
804
805 OPTIND The index of the next argument to be processed by the getopts
806 builtin command (see SHELL BUILTIN COMMANDS below).
807
808 OSTYPE Automatically set to a string that describes the operating
809 system on which bash is executing. The default is system-
810 dependent.
811
812 PIPESTATUS
813 An array variable (see Arrays below) containing a list of exit
814 status values from the processes in the most-recently-executed
815 foreground pipeline (which may contain only a single command).
816
817 PPID The process ID of the shell's parent. This variable is
818 readonly.
819
820 PWD The current working directory as set by the cd command.
821
822 RANDOM Each time this parameter is referenced, a random integer between
823 0 and 32767 is generated. The sequence of random numbers may be
824 initialized by assigning a value to RANDOM. If RANDOM is unset,
825 it loses its special properties, even if it is subsequently
826 reset.
827
828 REPLY Set to the line of input read by the read builtin command when
829 no arguments are supplied.
830
831 SECONDS
832 Each time this parameter is referenced, the number of seconds
833 since shell invocation is returned. If a value is assigned to
834 SECONDS, the value returned upon subsequent references is the
835 number of seconds since the assignment plus the value assigned.
836 If SECONDS is unset, it loses its special properties, even if it
837 is subsequently reset.
838
839 SHELLOPTS
840 A colon-separated list of enabled shell options. Each word in
841 the list is a valid argument for the -o option to the set
842 builtin command (see SHELL BUILTIN COMMANDS below). The options
843 appearing in SHELLOPTS are those reported as on by set -o. If
844 this variable is in the environment when bash starts up, each
845 shell option in the list will be enabled before reading any
846 startup files. This variable is read-only.
847
848 SHLVL Incremented by one each time an instance of bash is started.
849
850 UID Expands to the user ID of the current user, initialized at shell
851 startup. This variable is readonly.
852
853 The following variables are used by the shell. In some cases, bash
854 assigns a default value to a variable; these cases are noted below.
855
856 BASH_ENV
857 If this parameter is set when bash is executing a shell script,
858 its value is interpreted as a filename containing commands to
859 initialize the shell, as in ~/.bashrc. The value of BASH_ENV is
860 subjected to parameter expansion, command substitution, and
861 arithmetic expansion before being interpreted as a file name.
862 PATH is not used to search for the resultant file name.
863 CDPATH The search path for the cd command. This is a colon-separated
864 list of directories in which the shell looks for destination
865 directories specified by the cd command. A sample value is
866 ".:~:/usr".
867 COLUMNS
868 Used by the select builtin command to determine the terminal
869 width when printing selection lists. Automatically set upon
870 receipt of a SIGWINCH.
871 COMPREPLY
872 An array variable from which bash reads the possible completions
873 generated by a shell function invoked by the programmable
874 completion facility (see Programmable Completion below).
875 EMACS If bash finds this variable in the environment when the shell
876 starts with value "t", it assumes that the shell is running in
877 an emacs shell buffer and disables line editing.
878 FCEDIT The default editor for the fc builtin command.
879 FIGNORE
880 A colon-separated list of suffixes to ignore when performing
881 filename completion (see READLINE below). A filename whose
882 suffix matches one of the entries in FIGNORE is excluded from
883 the list of matched filenames. A sample value is ".o:~".
884 GLOBIGNORE
885 A colon-separated list of patterns defining the set of filenames
886 to be ignored by pathname expansion. If a filename matched by a
887 pathname expansion pattern also matches one of the patterns in
888 GLOBIGNORE, it is removed from the list of matches.
889 HISTCONTROL
890 A colon-separated list of values controlling how commands are
891 saved on the history list. If the list of values includes
892 ignorespace, lines which begin with a space character are not
893 saved in the history list. A value of ignoredups causes lines
894 matching the previous history entry to not be saved. A value of
895 ignoreboth is shorthand for ignorespace and ignoredups. A value
896 of erasedups causes all previous lines matching the current line
897 to be removed from the history list before that line is saved.
898 Any value not in the above list is ignored. If HISTCONTROL is
899 unset, or does not include a valid value, all lines read by the
900 shell parser are saved on the history list, subject to the value
901 of HISTIGNORE. The second and subsequent lines of a multi-line
902 compound command are not tested, and are added to the history
903 regardless of the value of HISTCONTROL.
904 HISTFILE
905 The name of the file in which command history is saved (see
906 HISTORY below). The default value is ~/.bash_history. If
907 unset, the command history is not saved when an interactive
908 shell exits.
909 HISTFILESIZE
910 The maximum number of lines contained in the history file. When
911 this variable is assigned a value, the history file is
912 truncated, if necessary, by removing the oldest entries, to
913 contain no more than that number of lines. The default value is
914 500. The history file is also truncated to this size after
915 writing it when an interactive shell exits.
916 HISTIGNORE
917 A colon-separated list of patterns used to decide which command
918 lines should be saved on the history list. Each pattern is
919 anchored at the beginning of the line and must match the
920 complete line (no implicit `*' is appended). Each pattern is
921 tested against the line after the checks specified by
922 HISTCONTROL are applied. In addition to the normal shell
923 pattern matching characters, `&' matches the previous history
924 line. `&' may be escaped using a backslash; the backslash is
925 removed before attempting a match. The second and subsequent
926 lines of a multi-line compound command are not tested, and are
927 added to the history regardless of the value of HISTIGNORE.
928 HISTSIZE
929 The number of commands to remember in the command history (see
930 HISTORY below). The default value is 500.
931 HISTTIMEFORMAT
932 If this variable is set and not null, its value is used as a
933 format string for strftime(3) to print the time stamp associated
934 with each history entry displayed by the history builtin. If
935 this variable is set, time stamps are written to the history
936 file so they may be preserved across shell sessions.
937 HOME The home directory of the current user; the default argument for
938 the cd builtin command. The value of this variable is also used
939 when performing tilde expansion.
940 HOSTFILE
941 Contains the name of a file in the same format as /etc/hosts
942 that should be read when the shell needs to complete a hostname.
943 The list of possible hostname completions may be changed while
944 the shell is running; the next time hostname completion is
945 attempted after the value is changed, bash adds the contents of
946 the new file to the existing list. If HOSTFILE is set, but has
947 no value, bash attempts to read /etc/hosts to obtain the list of
948 possible hostname completions. When HOSTFILE is unset, the
949 hostname list is cleared.
950 IFS The Internal Field Separator that is used for word splitting
951 after expansion and to split lines into words with the read
952 builtin command. The default value is
953 ``<space><tab><newline>''.
954 IGNOREEOF
955 Controls the action of an interactive shell on receipt of an EOF
956 character as the sole input. If set, the value is the number of
957 consecutive EOF characters which must be typed as the first
958 characters on an input line before bash exits. If the variable
959 exists but does not have a numeric value, or has no value, the
960 default value is 10. If it does not exist, EOF signifies the
961 end of input to the shell.
962 INPUTRC
963 The filename for the readline startup file, overriding the
964 default of ~/.inputrc (see READLINE below).
965 LANG Used to determine the locale category for any category not
966 specifically selected with a variable starting with LC_.
967 LC_ALL This variable overrides the value of LANG and any other LC_
968 variable specifying a locale category.
969 LC_COLLATE
970 This variable determines the collation order used when sorting
971 the results of pathname expansion, and determines the behavior
972 of range expressions, equivalence classes, and collating
973 sequences within pathname expansion and pattern matching.
974 LC_CTYPE
975 This variable determines the interpretation of characters and
976 the behavior of character classes within pathname expansion and
977 pattern matching.
978 LC_MESSAGES
979 This variable determines the locale used to translate double-
980 quoted strings preceded by a $.
981 LC_NUMERIC
982 This variable determines the locale category used for number
983 formatting.
984 LINES Used by the select builtin command to determine the column
985 length for printing selection lists. Automatically set upon
986 receipt of a SIGWINCH.
987 MAIL If this parameter is set to a file name and the MAILPATH
988 variable is not set, bash informs the user of the arrival of
989 mail in the specified file.
990 MAILCHECK
991 Specifies how often (in seconds) bash checks for mail. The
992 default is 60 seconds. When it is time to check for mail, the
993 shell does so before displaying the primary prompt. If this
994 variable is unset, or set to a value that is not a number
995 greater than or equal to zero, the shell disables mail checking.
996 MAILPATH
997 A colon-separated list of file names to be checked for mail.
998 The message to be printed when mail arrives in a particular file
999 may be specified by separating the file name from the message
1000 with a `?'. When used in the text of the message, $_ expands to
1001 the name of the current mailfile. Example:
1002 MAILPATH='/var/mail/bfox?"You have mail":~/shell-mail?"$_ has
1003 mail!"'
1004 Bash supplies a default value for this variable, but the
1005 location of the user mail files that it uses is system dependent
1006 (e.g., /var/mail/$USER).
1007 OPTERR If set to the value 1, bash displays error messages generated by
1008 the getopts builtin command (see SHELL BUILTIN COMMANDS below).
1009 OPTERR is initialized to 1 each time the shell is invoked or a
1010 shell script is executed.
1011 PATH The search path for commands. It is a colon-separated list of
1012 directories in which the shell looks for commands (see COMMAND
1013 EXECUTION below). A zero-length (null) directory name in the
1014 value of PATH indicates the current directory. A null directory
1015 name may appear as two adjacent colons, or as an initial or
1016 trailing colon. The default path is system-dependent, and is
1017 set by the administrator who installs bash. A common value is
1018 ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin''.
1019 POSIXLY_CORRECT
1020 If this variable is in the environment when bash starts, the
1021 shell enters posix mode before reading the startup files, as if
1022 the --posix invocation option had been supplied. If it is set
1023 while the shell is running, bash enables posix mode, as if the
1024 command set -o posix had been executed.
1025 PROMPT_COMMAND
1026 If set, the value is executed as a command prior to issuing each
1027 primary prompt.
1028 PS1 The value of this parameter is expanded (see PROMPTING below)
1029 and used as the primary prompt string. The default value is
1030 ``\s-\v\$ ''.
1031 PS2 The value of this parameter is expanded as with PS1 and used as
1032 the secondary prompt string. The default is ``> ''.
1033 PS3 The value of this parameter is used as the prompt for the select
1034 command (see SHELL GRAMMAR above).
1035 PS4 The value of this parameter is expanded as with PS1 and the
1036 value is printed before each command bash displays during an
1037 execution trace. The first character of PS4 is replicated
1038 multiple times, as necessary, to indicate multiple levels of
1039 indirection. The default is ``+ ''.
1040 SHELL The full pathname to the shell is kept in this environment
1041 variable. If it is not set when the shell starts, bash assigns
1042 to it the full pathname of the current user's login shell.
1043 TIMEFORMAT
1044 The value of this parameter is used as a format string
1045 specifying how the timing information for pipelines prefixed
1046 with the time reserved word should be displayed. The %
1047 character introduces an escape sequence that is expanded to a
1048 time value or other information. The escape sequences and their
1049 meanings are as follows; the braces denote optional portions.
1050 %% A literal %.
1051 %[p][l]R The elapsed time in seconds.
1052 %[p][l]U The number of CPU seconds spent in user mode.
1053 %[p][l]S The number of CPU seconds spent in system mode.
1054 %P The CPU percentage, computed as (%U + %S) / %R.
1055
1056 The optional p is a digit specifying the precision, the number
1057 of fractional digits after a decimal point. A value of 0 causes
1058 no decimal point or fraction to be output. At most three places
1059 after the decimal point may be specified; values of p greater
1060 than 3 are changed to 3. If p is not specified, the value 3 is
1061 used.
1062
1063 The optional l specifies a longer format, including minutes, of
1064 the form MMmSS.FFs. The value of p determines whether or not
1065 the fraction is included.
1066
1067 If this variable is not set, bash acts as if it had the value
1068 $'\nreal\t%3lR\nuser\t%3lU\nsys%3lS'. If the value is null, no
1069 timing information is displayed. A trailing newline is added
1070 when the format string is displayed.
1071
1072 TMOUT If set to a value greater than zero, TMOUT is treated as the
1073 default timeout for the read builtin. The select command
1074 terminates if input does not arrive after TMOUT seconds when
1075 input is coming from a terminal. In an interactive shell, the
1076 value is interpreted as the number of seconds to wait for input
1077 after issuing the primary prompt. Bash terminates after waiting
1078 for that number of seconds if input does not arrive.
1079
1080 TMPDIR If set, Bash uses its value as the name of a directory in which
1081 Bash creates temporary files for the shell's use.
1082
1083 auto_resume
1084 This variable controls how the shell interacts with the user and
1085 job control. If this variable is set, single word simple
1086 commands without redirections are treated as candidates for
1087 resumption of an existing stopped job. There is no ambiguity
1088 allowed; if there is more than one job beginning with the string
1089 typed, the job most recently accessed is selected. The name of
1090 a stopped job, in this context, is the command line used to
1091 start it. If set to the value exact, the string supplied must
1092 match the name of a stopped job exactly; if set to substring,
1093 the string supplied needs to match a substring of the name of a
1094 stopped job. The substring value provides functionality
1095 analogous to the %? job identifier (see JOB CONTROL below). If
1096 set to any other value, the supplied string must be a prefix of
1097 a stopped job's name; this provides functionality analogous to
1098 the %string job identifier.
1099
1100 histchars
1101 The two or three characters which control history expansion and
1102 tokenization (see HISTORY EXPANSION below). The first character
1103 is the history expansion character, the character which signals
1104 the start of a history expansion, normally `!'. The second
1105 character is the quick substitution character, which is used as
1106 shorthand for re-running the previous command entered,
1107 substituting one string for another in the command. The default
1108 is `^'. The optional third character is the character which
1109 indicates that the remainder of the line is a comment when found
1110 as the first character of a word, normally `#'. The history
1111 comment character causes history substitution to be skipped for
1112 the remaining words on the line. It does not necessarily cause
1113 the shell parser to treat the rest of the line as a comment.
1114
1115 Arrays
1116 Bash provides one-dimensional array variables. Any variable may be
1117 used as an array; the declare builtin will explicitly declare an array.
1118 There is no maximum limit on the size of an array, nor any requirement
1119 that members be indexed or assigned contiguously. Arrays are indexed
1120 using integers and are zero-based.
1121
1122 An array is created automatically if any variable is assigned to using
1123 the syntax name[subscript]=value. The subscript is treated as an
1124 arithmetic expression that must evaluate to a number greater than or
1125 equal to zero. To explicitly declare an array, use declare -a name
1126 (see SHELL BUILTIN COMMANDS below). declare -a name[subscript] is also
1127 accepted; the subscript is ignored. Attributes may be specified for an
1128 array variable using the declare and readonly builtins. Each attribute
1129 applies to all members of an array.
1130
1131 Arrays are assigned to using compound assignments of the form
1132 name=(value1 ... valuen), where each value is of the form
1133 [subscript]=string. Only string is required. If the optional brackets
1134 and subscript are supplied, that index is assigned to; otherwise the
1135 index of the element assigned is the last index assigned to by the
1136 statement plus one. Indexing starts at zero. This syntax is also
1137 accepted by the declare builtin. Individual array elements may be
1138 assigned to using the name[subscript]=value syntax introduced above.
1139
1140 Any element of an array may be referenced using ${name[subscript]}.
1141 The braces are required to avoid conflicts with pathname expansion. If
1142 subscript is @ or *, the word expands to all members of name. These
1143 subscripts differ only when the word appears within double quotes. If
1144 the word is double-quoted, ${name[*]} expands to a single word with the
1145 value of each array member separated by the first character of the IFS
1146 special variable, and ${name[@]} expands each element of name to a
1147 separate word. When there are no array members, ${name[@]} expands to
1148 nothing. If the double-quoted expansion occurs within a word, the
1149 expansion of the first parameter is joined with the beginning part of
1150 the original word, and the expansion of the last parameter is joined
1151 with the last part of the original word. This is analogous to the
1152 expansion of the special parameters * and @ (see Special Parameters
1153 above). ${#name[subscript]} expands to the length of
1154 ${name[subscript]}. If subscript is * or @, the expansion is the
1155 number of elements in the array. Referencing an array variable without
1156 a subscript is equivalent to referencing element zero.
1157
1158 The unset builtin is used to destroy arrays. unset name[subscript]
1159 destroys the array element at index subscript. Care must be taken to
1160 avoid unwanted side effects caused by filename generation. unset name,
1161 where name is an array, or unset name[subscript], where subscript is *
1162 or @, removes the entire array.
1163
1164 The declare, local, and readonly builtins each accept a -a option to
1165 specify an array. The read builtin accepts a -a option to assign a
1166 list of words read from the standard input to an array. The set and
1167 declare builtins display array values in a way that allows them to be
1168 reused as assignments.
1169
1170EXPANSION
1171 Expansion is performed on the command line after it has been split into
1172 words. There are seven kinds of expansion performed: brace expansion,
1173 tilde expansion, parameter and variable expansion, command
1174 substitution, arithmetic expansion, word splitting, and pathname
1175 expansion.
1176
1177 The order of expansions is: brace expansion, tilde expansion,
1178 parameter, variable and arithmetic expansion and command substitution
1179 (done in a left-to-right fashion), word splitting, and pathname
1180 expansion.
1181
1182 On systems that can support it, there is an additional expansion
1183 available: process substitution.
1184
1185 Only brace expansion, word splitting, and pathname expansion can change
1186 the number of words of the expansion; other expansions expand a single
1187 word to a single word. The only exceptions to this are the expansions
1188 of "$@" and "${name[@]}" as explained above (see PARAMETERS).
1189
1190 Brace Expansion
1191 Brace expansion is a mechanism by which arbitrary strings may be
1192 generated. This mechanism is similar to pathname expansion, but the
1193 filenames generated need not exist. Patterns to be brace expanded take
1194 the form of an optional preamble, followed by either a series of comma-
1195 separated strings or a sequence expression between a pair of braces,
1196 followed by an optional postscript. The preamble is prefixed to each
1197 string contained within the braces, and the postscript is then appended
1198 to each resulting string, expanding left to right.
1199
1200 Brace expansions may be nested. The results of each expanded string
1201 are not sorted; left to right order is preserved. For example,
1202 a{d,c,b}e expands into `ade ace abe'.
1203
1204 A sequence expression takes the form {x..y}, where x and y are either
1205 integers or single characters. When integers are supplied, the
1206 expression expands to each number between x and y, inclusive. When
1207 characters are supplied, the expression expands to each character
1208 lexicographically between x and y, inclusive. Note that both x and y
1209 must be of the same type.
1210
1211 Brace expansion is performed before any other expansions, and any
1212 characters special to other expansions are preserved in the result. It
1213 is strictly textual. Bash does not apply any syntactic interpretation
1214 to the context of the expansion or the text between the braces.
1215
1216 A correctly-formed brace expansion must contain unquoted opening and
1217 closing braces, and at least one unquoted comma or a valid sequence
1218 expression. Any incorrectly formed brace expansion is left unchanged.
1219 A { or , may be quoted with a backslash to prevent its being considered
1220 part of a brace expression. To avoid conflicts with parameter
1221 expansion, the string ${ is not considered eligible for brace
1222 expansion.
1223
1224 This construct is typically used as shorthand when the common prefix of
1225 the strings to be generated is longer than in the above example:
1226
1227 mkdir /usr/local/src/bash/{old,new,dist,bugs}
1228 or
1229 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
1230
1231 Brace expansion introduces a slight incompatibility with historical
1232 versions of sh. sh does not treat opening or closing braces specially
1233 when they appear as part of a word, and preserves them in the output.
1234 Bash removes braces from words as a consequence of brace expansion.
1235 For example, a word entered to sh as file{1,2} appears identically in
1236 the output. The same word is output as file1 file2 after expansion by
1237 bash. If strict compatibility with sh is desired, start bash with the
1238 +B option or disable brace expansion with the +B option to the set
1239 command (see SHELL BUILTIN COMMANDS below).
1240
1241 Tilde Expansion
1242 If a word begins with an unquoted tilde character (`~'), all of the
1243 characters preceding the first unquoted slash (or all characters, if
1244 there is no unquoted slash) are considered a tilde-prefix. If none of
1245 the characters in the tilde-prefix are quoted, the characters in the
1246 tilde-prefix following the tilde are treated as a possible login name.
1247 If this login name is the null string, the tilde is replaced with the
1248 value of the shell parameter HOME. If HOME is unset, the home
1249 directory of the user executing the shell is substituted instead.
1250 Otherwise, the tilde-prefix is replaced with the home directory
1251 associated with the specified login name.
1252
1253 If the tilde-prefix is a `~+', the value of the shell variable PWD
1254 replaces the tilde-prefix. If the tilde-prefix is a `~-', the value of
1255 the shell variable OLDPWD, if it is set, is substituted. If the
1256 characters following the tilde in the tilde-prefix consist of a number
1257 N, optionally prefixed by a `+' or a `-', the tilde-prefix is replaced
1258 with the corresponding element from the directory stack, as it would be
1259 displayed by the dirs builtin invoked with the tilde-prefix as an
1260 argument. If the characters following the tilde in the tilde-prefix
1261 consist of a number without a leading `+' or `-', `+' is assumed.
1262
1263 If the login name is invalid, or the tilde expansion fails, the word is
1264 unchanged.
1265
1266 Each variable assignment is checked for unquoted tilde-prefixes
1267 immediately following a : or the first =. In these cases, tilde
1268 expansion is also performed. Consequently, one may use file names with
1269 tildes in assignments to PATH, MAILPATH, and CDPATH, and the shell
1270 assigns the expanded value.
1271
1272 Parameter Expansion
1273 The `$' character introduces parameter expansion, command substitution,
1274 or arithmetic expansion. The parameter name or symbol to be expanded
1275 may be enclosed in braces, which are optional but serve to protect the
1276 variable to be expanded from characters immediately following it which
1277 could be interpreted as part of the name.
1278
1279 When braces are used, the matching ending brace is the first `}' not
1280 escaped by a backslash or within a quoted string, and not within an
1281 embedded arithmetic expansion, command substitution, or parameter
1282 expansion.
1283
1284 ${parameter}
1285 The value of parameter is substituted. The braces are required
1286 when parameter is a positional parameter with more than one
1287 digit, or when parameter is followed by a character which is not
1288 to be interpreted as part of its name.
1289
1290 If the first character of parameter is an exclamation point, a level of
1291 variable indirection is introduced. Bash uses the value of the
1292 variable formed from the rest of parameter as the name of the variable;
1293 this variable is then expanded and that value is used in the rest of
1294 the substitution, rather than the value of parameter itself. This is
1295 known as indirect expansion. The exceptions to this are the expansions
1296 of ${!prefix*} and ${!name[@]} described below. The exclamation point
1297 must immediately follow the left brace in order to introduce
1298 indirection.
1299
1300 In each of the cases below, word is subject to tilde expansion,
1301 parameter expansion, command substitution, and arithmetic expansion.
1302 When not performing substring expansion, bash tests for a parameter
1303 that is unset or null; omitting the colon results in a test only for a
1304 parameter that is unset.
1305
1306 ${parameter:-word}
1307 Use Default Values. If parameter is unset or null, the
1308 expansion of word is substituted. Otherwise, the value of
1309 parameter is substituted.
1310 ${parameter:=word}
1311 Assign Default Values. If parameter is unset or null, the
1312 expansion of word is assigned to parameter. The value of
1313 parameter is then substituted. Positional parameters and
1314 special parameters may not be assigned to in this way.
1315 ${parameter:?word}
1316 Display Error if Null or Unset. If parameter is null or unset,
1317 the expansion of word (or a message to that effect if word is
1318 not present) is written to the standard error and the shell, if
1319 it is not interactive, exits. Otherwise, the value of parameter
1320 is substituted.
1321 ${parameter:+word}
1322 Use Alternate Value. If parameter is null or unset, nothing is
1323 substituted, otherwise the expansion of word is substituted.
1324 ${parameter:offset}
1325 ${parameter:offset:length}
1326 Substring Expansion. Expands to up to length characters of
1327 parameter starting at the character specified by offset. If
1328 length is omitted, expands to the substring of parameter
1329 starting at the character specified by offset. length and
1330 offset are arithmetic expressions (see ARITHMETIC EVALUATION
1331 below). length must evaluate to a number greater than or equal
1332 to zero. If offset evaluates to a number less than zero, the
1333 value is used as an offset from the end of the value of
1334 parameter. If parameter is @, the result is length positional
1335 parameters beginning at offset. If parameter is an array name
1336 indexed by @ or *, the result is the length members of the array
1337 beginning with ${parameter[offset]}. A negative offset is taken
1338 relative to one greater than the maximum index of the specified
1339 array. Note that a negative offset must be separated from the
1340 colon by at least one space to avoid being confused with the :-
1341 expansion. Substring indexing is zero-based unless the
1342 positional parameters are used, in which case the indexing
1343 starts at 1.
1344
1345 ${!prefix*}
1346 ${!prefix@}
1347 Expands to the names of variables whose names begin with prefix,
1348 separated by the first character of the IFS special variable.
1349
1350 ${!name[@]}
1351 ${!name[*]}
1352 If name is an array variable, expands to the list of array
1353 indices (keys) assigned in name. If name is not an array,
1354 expands to 0 if name is set and null otherwise. When @ is used
1355 and the expansion appears within double quotes, each key expands
1356 to a separate word.
1357
1358 ${#parameter}
1359 The length in characters of the value of parameter is
1360 substituted. If parameter is * or @, the value substituted is
1361 the number of positional parameters. If parameter is an array
1362 name subscripted by * or @, the value substituted is the number
1363 of elements in the array.
1364
1365 ${parameter#word}
1366 ${parameter##word}
1367 The word is expanded to produce a pattern just as in pathname
1368 expansion. If the pattern matches the beginning of the value of
1369 parameter, then the result of the expansion is the expanded
1370 value of parameter with the shortest matching pattern (the ``#''
1371 case) or the longest matching pattern (the ``##'' case) deleted.
1372 If parameter is @ or *, the pattern removal operation is applied
1373 to each positional parameter in turn, and the expansion is the
1374 resultant list. If parameter is an array variable subscripted
1375 with @ or *, the pattern removal operation is applied to each
1376 member of the array in turn, and the expansion is the resultant
1377 list.
1378
1379 ${parameter%word}
1380 ${parameter%%word}
1381 The word is expanded to produce a pattern just as in pathname
1382 expansion. If the pattern matches a trailing portion of the
1383 expanded value of parameter, then the result of the expansion is
1384 the expanded value of parameter with the shortest matching
1385 pattern (the ``%'' case) or the longest matching pattern (the
1386 ``%%'' case) deleted. If parameter is @ or *, the pattern
1387 removal operation is applied to each positional parameter in
1388 turn, and the expansion is the resultant list. If parameter is
1389 an array variable subscripted with @ or *, the pattern removal
1390 operation is applied to each member of the array in turn, and
1391 the expansion is the resultant list.
1392
1393 ${parameter/pattern/string}
1394 The pattern is expanded to produce a pattern just as in pathname
1395 expansion. Parameter is expanded and the longest match of
1396 pattern against its value is replaced with string. If Ipattern
1397 begins with /, all matches of pattern are replaced with string.
1398 Normally only the first match is replaced. If pattern begins
1399 with #, it must match at the beginning of the expanded value of
1400 parameter. If pattern begins with %, it must match at the end
1401 of the expanded value of parameter. If string is null, matches
1402 of pattern are deleted and the / following pattern may be
1403 omitted. If parameter is @ or *, the substitution operation is
1404 applied to each positional parameter in turn, and the expansion
1405 is the resultant list. If parameter is an array variable
1406 subscripted with @ or *, the substitution operation is applied
1407 to each member of the array in turn, and the expansion is the
1408 resultant list.
1409
1410 Command Substitution
1411 Command substitution allows the output of a command to replace the
1412 command name. There are two forms:
1413
1414
1415 $(command)
1416 or
1417 `command`
1418
1419 Bash performs the expansion by executing command and replacing the
1420 command substitution with the standard output of the command, with any
1421 trailing newlines deleted. Embedded newlines are not deleted, but they
1422 may be removed during word splitting. The command substitution $(cat
1423 file) can be replaced by the equivalent but faster $(< file).
1424
1425 When the old-style backquote form of substitution is used, backslash
1426 retains its literal meaning except when followed by $, `, or \. The
1427 first backquote not preceded by a backslash terminates the command
1428 substitution. When using the $(command) form, all characters between
1429 the parentheses make up the command; none are treated specially.
1430
1431 Command substitutions may be nested. To nest when using the backquoted
1432 form, escape the inner backquotes with backslashes.
1433
1434 If the substitution appears within double quotes, word splitting and
1435 pathname expansion are not performed on the results.
1436
1437 Arithmetic Expansion
1438 Arithmetic expansion allows the evaluation of an arithmetic expression
1439 and the substitution of the result. The format for arithmetic
1440 expansion is:
1441
1442 $((expression))
1443
1444 The expression is treated as if it were within double quotes, but a
1445 double quote inside the parentheses is not treated specially. All
1446 tokens in the expression undergo parameter expansion, string expansion,
1447 command substitution, and quote removal. Arithmetic expansions may be
1448 nested.
1449
1450 The evaluation is performed according to the rules listed below under
1451 ARITHMETIC EVALUATION. If expression is invalid, bash prints a message
1452 indicating failure and no substitution occurs.
1453
1454 Process Substitution
1455 Process substitution is supported on systems that support named pipes
1456 (FIFOs) or the /dev/fd method of naming open files. It takes the form
1457 of <(list) or >(list). The process list is run with its input or
1458 output connected to a FIFO or some file in /dev/fd. The name of this
1459 file is passed as an argument to the current command as the result of
1460 the expansion. If the >(list) form is used, writing to the file will
1461 provide input for list. If the <(list) form is used, the file passed
1462 as an argument should be read to obtain the output of list.
1463
1464 When available, process substitution is performed simultaneously with
1465 parameter and variable expansion, command substitution, and arithmetic
1466 expansion.
1467
1468 Word Splitting
1469 The shell scans the results of parameter expansion, command
1470 substitution, and arithmetic expansion that did not occur within double
1471 quotes for word splitting.
1472
1473 The shell treats each character of IFS as a delimiter, and splits the
1474 results of the other expansions into words on these characters. If IFS
1475 is unset, or its value is exactly <space><tab><newline>, the default,
1476 then any sequence of IFS characters serves to delimit words. If IFS
1477 has a value other than the default, then sequences of the whitespace
1478 characters space and tab are ignored at the beginning and end of the
1479 word, as long as the whitespace character is in the value of IFS (an
1480 IFS whitespace character). Any character in IFS that is not IFS
1481 whitespace, along with any adjacent IFS whitespace characters, delimits
1482 a field. A sequence of IFS whitespace characters is also treated as a
1483 delimiter. If the value of IFS is null, no word splitting occurs.
1484
1485 Explicit null arguments ("" or '') are retained. Unquoted implicit
1486 null arguments, resulting from the expansion of parameters that have no
1487 values, are removed. If a parameter with no value is expanded within
1488 double quotes, a null argument results and is retained.
1489
1490 Note that if no expansion occurs, no splitting is performed.
1491
1492 Pathname Expansion
1493 After word splitting, unless the -f option has been set, bash scans
1494 each word for the characters *, ?, and [. If one of these characters
1495 appears, then the word is regarded as a pattern, and replaced with an
1496 alphabetically sorted list of file names matching the pattern. If no
1497 matching file names are found, and the shell option nullglob is
1498 disabled, the word is left unchanged. If the nullglob option is set,
1499 and no matches are found, the word is removed. If the failglob shell
1500 option is set, and no matches are found, an error message is printed
1501 and the command is not executed. If the shell option nocaseglob is
1502 enabled, the match is performed without regard to the case of
1503 alphabetic characters. When a pattern is used for pathname expansion,
1504 the character ``.'' at the start of a name or immediately following a
1505 slash must be matched explicitly, unless the shell option dotglob is
1506 set. When matching a pathname, the slash character must always be
1507 matched explicitly. In other cases, the ``.'' character is not treated
1508 specially. See the description of shopt below under SHELL BUILTIN
1509 COMMANDS for a description of the nocaseglob, nullglob, failglob, and
1510 dotglob shell options.
1511
1512 The GLOBIGNORE shell variable may be used to restrict the set of file
1513 names matching a pattern. If GLOBIGNORE is set, each matching file
1514 name that also matches one of the patterns in GLOBIGNORE is removed
1515 from the list of matches. The file names ``.'' and ``..'' are always
1516 ignored when GLOBIGNORE is set and not null. However, setting
1517 GLOBIGNORE to a non-null value has the effect of enabling the dotglob
1518 shell option, so all other file names beginning with a ``.'' will
1519 match. To get the old behavior of ignoring file names beginning with a
1520 ``.'', make ``.*'' one of the patterns in GLOBIGNORE. The dotglob
1521 option is disabled when GLOBIGNORE is unset.
1522
1523 Pattern Matching
1524
1525 Any character that appears in a pattern, other than the special pattern
1526 characters described below, matches itself. The NUL character may not
1527 occur in a pattern. A backslash escapes the following character; the
1528 escaping backslash is discarded when matching. The special pattern
1529 characters must be quoted if they are to be matched literally.
1530
1531 The special pattern characters have the following meanings:
1532
1533 * Matches any string, including the null string.
1534 ? Matches any single character.
1535 [...] Matches any one of the enclosed characters. A pair of
1536 characters separated by a hyphen denotes a range expression; any
1537 character that sorts between those two characters, inclusive,
1538 using the current locale's collating sequence and character set,
1539 is matched. If the first character following the [ is a ! or a
1540 ^ then any character not enclosed is matched. The sorting order
1541 of characters in range expressions is determined by the current
1542 locale and the value of the LC_COLLATE shell variable, if set.
1543 A - may be matched by including it as the first or last
1544 character in the set. A ] may be matched by including it as the
1545 first character in the set.
1546
1547 Within [ and ], character classes can be specified using the
1548 syntax [:class:], where class is one of the following classes
1549 defined in the POSIX standard:
1550 alnum alpha ascii blank cntrl digit graph lower print punct
1551 space upper word xdigit
1552 A character class matches any character belonging to that class.
1553 The word character class matches letters, digits, and the
1554 character _.
1555
1556 Within [ and ], an equivalence class can be specified using the
1557 syntax [=c=], which matches all characters with the same
1558 collation weight (as defined by the current locale) as the
1559 character c.
1560
1561 Within [ and ], the syntax [.symbol.] matches the collating
1562 symbol symbol.
1563
1564 If the extglob shell option is enabled using the shopt builtin, several
1565 extended pattern matching operators are recognized. In the following
1566 description, a pattern-list is a list of one or more patterns separated
1567 by a |. Composite patterns may be formed using one or more of the
1568 following sub-patterns:
1569
1570 ?(pattern-list)
1571 Matches zero or one occurrence of the given patterns
1572 *(pattern-list)
1573 Matches zero or more occurrences of the given patterns
1574 +(pattern-list)
1575 Matches one or more occurrences of the given patterns
1576 @(pattern-list)
1577 Matches one of the given patterns
1578 !(pattern-list)
1579 Matches anything except one of the given patterns
1580
1581 Quote Removal
1582 After the preceding expansions, all unquoted occurrences of the
1583 characters \, ', and " that did not result from one of the above
1584 expansions are removed.
1585
1586REDIRECTION
1587 Before a command is executed, its input and output may be redirected
1588 using a special notation interpreted by the shell. Redirection may
1589 also be used to open and close files for the current shell execution
1590 environment. The following redirection operators may precede or appear
1591 anywhere within a simple command or may follow a command. Redirections
1592 are processed in the order they appear, from left to right.
1593
1594 In the following descriptions, if the file descriptor number is
1595 omitted, and the first character of the redirection operator is <, the
1596 redirection refers to the standard input (file descriptor 0). If the
1597 first character of the redirection operator is >, the redirection
1598 refers to the standard output (file descriptor 1).
1599
1600 The word following the redirection operator in the following
1601 descriptions, unless otherwise noted, is subjected to brace expansion,
1602 tilde expansion, parameter expansion, command substitution, arithmetic
1603 expansion, quote removal, pathname expansion, and word splitting. If
1604 it expands to more than one word, bash reports an error.
1605
1606 Note that the order of redirections is significant. For example, the
1607 command
1608
1609 ls > dirlist 2>&1
1610
1611 directs both standard output and standard error to the file dirlist,
1612 while the command
1613
1614 ls 2>&1 > dirlist
1615
1616 directs only the standard output to file dirlist, because the standard
1617 error was duplicated as standard output before the standard output was
1618 redirected to dirlist.
1619
1620 Bash handles several filenames specially when they are used in
1621 redirections, as described in the following table:
1622
1623 /dev/fd/fd
1624 If fd is a valid integer, file descriptor fd is
1625 duplicated.
1626 /dev/stdin
1627 File descriptor 0 is duplicated.
1628 /dev/stdout
1629 File descriptor 1 is duplicated.
1630 /dev/stderr
1631 File descriptor 2 is duplicated.
1632 /dev/tcp/host/port
1633 If host is a valid hostname or Internet address, and port
1634 is an integer port number or service name, bash attempts
1635 to open a TCP connection to the corresponding socket.
1636 /dev/udp/host/port
1637 If host is a valid hostname or Internet address, and port
1638 is an integer port number or service name, bash attempts
1639 to open a UDP connection to the corresponding socket.
1640
1641 A failure to open or create a file causes the redirection to fail.
1642
1643 Redirections using file descriptors greater than 9 should be used with
1644 care, as they may conflict with file descriptors the shell uses
1645 internally.
1646
1647 Redirecting Input
1648 Redirection of input causes the file whose name results from the
1649 expansion of word to be opened for reading on file descriptor n, or the
1650 standard input (file descriptor 0) if n is not specified.
1651
1652 The general format for redirecting input is:
1653
1654 [n]<word
1655
1656 Redirecting Output
1657 Redirection of output causes the file whose name results from the
1658 expansion of word to be opened for writing on file descriptor n, or the
1659 standard output (file descriptor 1) if n is not specified. If the file
1660 does not exist it is created; if it does exist it is truncated to zero
1661 size.
1662
1663 The general format for redirecting output is:
1664
1665 [n]>word
1666
1667 If the redirection operator is >, and the noclobber option to the set
1668 builtin has been enabled, the redirection will fail if the file whose
1669 name results from the expansion of word exists and is a regular file.
1670 If the redirection operator is >|, or the redirection operator is > and
1671 the noclobber option to the set builtin command is not enabled, the
1672 redirection is attempted even if the file named by word exists.
1673
1674 Appending Redirected Output
1675 Redirection of output in this fashion causes the file whose name
1676 results from the expansion of word to be opened for appending on file
1677 descriptor n, or the standard output (file descriptor 1) if n is not
1678 specified. If the file does not exist it is created.
1679
1680 The general format for appending output is:
1681
1682 [n]>>word
1683
1684 Redirecting Standard Output and Standard Error
1685 Bash allows both the standard output (file descriptor 1) and the
1686 standard error output (file descriptor 2) to be redirected to the file
1687 whose name is the expansion of word with this construct.
1688
1689 There are two formats for redirecting standard output and standard
1690 error:
1691
1692 &>word
1693 and
1694 >&word
1695
1696 Of the two forms, the first is preferred. This is semantically
1697 equivalent to
1698
1699 >word 2>&1
1700
1701 Here Documents
1702 This type of redirection instructs the shell to read input from the
1703 current source until a line containing only word (with no trailing
1704 blanks) is seen. All of the lines read up to that point are then used
1705 as the standard input for a command.
1706
1707 The format of here-documents is:
1708
1709 <<[-]word
1710 here-document
1711 delimiter
1712
1713 No parameter expansion, command substitution, arithmetic expansion, or
1714 pathname expansion is performed on word. If any characters in word are
1715 quoted, the delimiter is the result of quote removal on word, and the
1716 lines in the here-document are not expanded. If word is unquoted, all
1717 lines of the here-document are subjected to parameter expansion,
1718 command substitution, and arithmetic expansion. In the latter case,
1719 the character sequence \<newline> is ignored, and \ must be used to
1720 quote the characters \, $, and `.
1721
1722 If the redirection operator is <<-, then all leading tab characters are
1723 stripped from input lines and the line containing delimiter. This
1724 allows here-documents within shell scripts to be indented in a natural
1725 fashion.
1726
1727 Here Strings
1728 A variant of here documents, the format is:
1729
1730 <<<word
1731
1732 The word is expanded and supplied to the command on its standard input.
1733
1734 Duplicating File Descriptors
1735 The redirection operator
1736
1737 [n]<&word
1738
1739 is used to duplicate input file descriptors. If word expands to one or
1740 more digits, the file descriptor denoted by n is made to be a copy of
1741 that file descriptor. If the digits in word do not specify a file
1742 descriptor open for input, a redirection error occurs. If word
1743 evaluates to -, file descriptor n is closed. If n is not specified,
1744 the standard input (file descriptor 0) is used.
1745
1746 The operator
1747
1748 [n]>&word
1749
1750 is used similarly to duplicate output file descriptors. If n is not
1751 specified, the standard output (file descriptor 1) is used. If the
1752 digits in word do not specify a file descriptor open for output, a
1753 redirection error occurs. As a special case, if n is omitted, and word
1754 does not expand to one or more digits, the standard output and standard
1755 error are redirected as described previously.
1756
1757 Moving File Descriptors
1758 The redirection operator
1759
1760 [n]<&digit-
1761
1762 moves the file descriptor digit to file descriptor n, or the standard
1763 input (file descriptor 0) if n is not specified. digit is closed after
1764 being duplicated to n.
1765
1766 Similarly, the redirection operator
1767
1768 [n]>&digit-
1769
1770 moves the file descriptor digit to file descriptor n, or the standard
1771 output (file descriptor 1) if n is not specified.
1772
1773 Opening File Descriptors for Reading and Writing
1774 The redirection operator
1775
1776 [n]<>word
1777
1778 causes the file whose name is the expansion of word to be opened for
1779 both reading and writing on file descriptor n, or on file descriptor 0
1780 if n is not specified. If the file does not exist, it is created.
1781
1782ALIASES
1783 Aliases allow a string to be substituted for a word when it is used as
1784 the first word of a simple command. The shell maintains a list of
1785 aliases that may be set and unset with the alias and unalias builtin
1786 commands (see SHELL BUILTIN COMMANDS below). The first word of each
1787 simple command, if unquoted, is checked to see if it has an alias. If
1788 so, that word is replaced by the text of the alias. The characters /,
1789 $, `, and = and any of the shell metacharacters or quoting characters
1790 listed above may not appear in an alias name. The replacement text may
1791 contain any valid shell input, including shell metacharacters. The
1792 first word of the replacement text is tested for aliases, but a word
1793 that is identical to an alias being expanded is not expanded a second
1794 time. This means that one may alias ls to ls -F, for instance, and
1795 bash does not try to recursively expand the replacement text. If the
1796 last character of the alias value is a blank, then the next command
1797 word following the alias is also checked for alias expansion.
1798
1799 Aliases are created and listed with the alias command, and removed with
1800 the unalias command.
1801
1802 There is no mechanism for using arguments in the replacement text. If
1803 arguments are needed, a shell function should be used (see FUNCTIONS
1804 below).
1805
1806 Aliases are not expanded when the shell is not interactive, unless the
1807 expand_aliases shell option is set using shopt (see the description of
1808 shopt under SHELL BUILTIN COMMANDS below).
1809
1810 The rules concerning the definition and use of aliases are somewhat
1811 confusing. Bash always reads at least one complete line of input
1812 before executing any of the commands on that line. Aliases are
1813 expanded when a command is read, not when it is executed. Therefore,
1814 an alias definition appearing on the same line as another command does
1815 not take effect until the next line of input is read. The commands
1816 following the alias definition on that line are not affected by the new
1817 alias. This behavior is also an issue when functions are executed.
1818 Aliases are expanded when a function definition is read, not when the
1819 function is executed, because a function definition is itself a
1820 compound command. As a consequence, aliases defined in a function are
1821 not available until after that function is executed. To be safe,
1822 always put alias definitions on a separate line, and do not use alias
1823 in compound commands.
1824
1825 For almost every purpose, aliases are superseded by shell functions.
1826
1827FUNCTIONS
1828 A shell function, defined as described above under SHELL GRAMMAR,
1829 stores a series of commands for later execution. When the name of a
1830 shell function is used as a simple command name, the list of commands
1831 associated with that function name is executed. Functions are executed
1832 in the context of the current shell; no new process is created to
1833 interpret them (contrast this with the execution of a shell script).
1834 When a function is executed, the arguments to the function become the
1835 positional parameters during its execution. The special parameter # is
1836 updated to reflect the change. Special parameter 0 is unchanged. The
1837 first element of the FUNCNAME variable is set to the name of the
1838 function while the function is executing. All other aspects of the
1839 shell execution environment are identical between a function and its
1840 caller with the exception that the DEBUG and RETURN traps (see the
1841 description of the trap builtin under SHELL BUILTIN COMMANDS below) are
1842 not inherited unless the function has been given the trace attribute
1843 (see the description of the declare builtin below) or the -o functrace
1844 shell option has been enabled with the set builtin (in which case all
1845 functions inherit the DEBUG and RETURN traps).
1846
1847 Variables local to the function may be declared with the local builtin
1848 command. Ordinarily, variables and their values are shared between the
1849 function and its caller.
1850
1851 If the builtin command return is executed in a function, the function
1852 completes and execution resumes with the next command after the
1853 function call. Any command associated with the RETURN trap is executed
1854 before execution resumes. When a function completes, the values of the
1855 positional parameters and the special parameter # are restored to the
1856 values they had prior to the function's execution.
1857
1858 Function names and definitions may be listed with the -f option to the
1859 declare or typeset builtin commands. The -F option to declare or
1860 typeset will list the function names only (and optionally the source
1861 file and line number, if the extdebug shell option is enabled).
1862 Functions may be exported so that subshells automatically have them
1863 defined with the -f option to the export builtin. A function
1864 definition may be deleted using the -f option to the unset builtin.
1865 Note that shell functions and variables with the same name may result
1866 in multiple identically-named entries in the environment passed to the
1867 shell's children. Care should be taken in cases where this may cause a
1868 problem.
1869
1870 Functions may be recursive. No limit is imposed on the number of
1871 recursive calls.
1872
1873ARITHMETIC EVALUATION
1874 The shell allows arithmetic expressions to be evaluated, under certain
1875 circumstances (see the let and declare builtin commands and Arithmetic
1876 Expansion). Evaluation is done in fixed-width integers with no check
1877 for overflow, though division by 0 is trapped and flagged as an error.
1878 The operators and their precedence, associativity, and values are the
1879 same as in the C language. The following list of operators is grouped
1880 into levels of equal-precedence operators. The levels are listed in
1881 order of decreasing precedence.
1882
1883 id++ id--
1884 variable post-increment and post-decrement
1885 ++id --id
1886 variable pre-increment and pre-decrement
1887 - + unary minus and plus
1888 ! ~ logical and bitwise negation
1889 ** exponentiation
1890 * / % multiplication, division, remainder
1891 + - addition, subtraction
1892 << >> left and right bitwise shifts
1893 <= >= < >
1894 comparison
1895 == != equality and inequality
1896 & bitwise AND
1897 ^ bitwise exclusive OR
1898 | bitwise OR
1899 && logical AND
1900 || logical OR
1901 expr?expr:expr
1902 conditional operator
1903 = *= /= %= += -= <<= >>= &= ^= |=
1904 assignment
1905 expr1 , expr2
1906 comma
1907
1908 Shell variables are allowed as operands; parameter expansion is
1909 performed before the expression is evaluated. Within an expression,
1910 shell variables may also be referenced by name without using the
1911 parameter expansion syntax. A shell variable that is null or unset
1912 evaluates to 0 when referenced by name without using the parameter
1913 expansion syntax. The value of a variable is evaluated as an
1914 arithmetic expression when it is referenced, or when a variable which
1915 has been given the integer attribute using declare -i is assigned a
1916 value. A null value evaluates to 0. A shell variable need not have
1917 its integer attribute turned on to be used in an expression.
1918
1919 Constants with a leading 0 are interpreted as octal numbers. A leading
1920 0x or 0X denotes hexadecimal. Otherwise, numbers take the form
1921 [base#]n, where base is a decimal number between 2 and 64 representing
1922 the arithmetic base, and n is a number in that base. If base# is
1923 omitted, then base 10 is used. The digits greater than 9 are
1924 represented by the lowercase letters, the uppercase letters, @, and _,
1925 in that order. If base is less than or equal to 36, lowercase and
1926 uppercase letters may be used interchangeably to represent numbers
1927 between 10 and 35.
1928
1929 Operators are evaluated in order of precedence. Sub-expressions in
1930 parentheses are evaluated first and may override the precedence rules
1931 above.
1932
1933CONDITIONAL EXPRESSIONS
1934 Conditional expressions are used by the [[ compound command and the
1935 test and [ builtin commands to test file attributes and perform string
1936 and arithmetic comparisons. Expressions are formed from the following
1937 unary or binary primaries. If any file argument to one of the
1938 primaries is of the form /dev/fd/n, then file descriptor n is checked.
1939 If the file argument to one of the primaries is one of /dev/stdin,
1940 /dev/stdout, or /dev/stderr, file descriptor 0, 1, or 2, respectively,
1941 is checked.
1942
1943 Unless otherwise specified, primaries that operate on files follow
1944 symbolic links and operate on the target of the link, rather than the
1945 link itself.
1946
1947 -a file
1948 True if file exists.
1949 -b file
1950 True if file exists and is a block special file.
1951 -c file
1952 True if file exists and is a character special file.
1953 -d file
1954 True if file exists and is a directory.
1955 -e file
1956 True if file exists.
1957 -f file
1958 True if file exists and is a regular file.
1959 -g file
1960 True if file exists and is set-group-id.
1961 -h file
1962 True if file exists and is a symbolic link.
1963 -k file
1964 True if file exists and its ``sticky'' bit is set.
1965 -p file
1966 True if file exists and is a named pipe (FIFO).
1967 -r file
1968 True if file exists and is readable.
1969 -s file
1970 True if file exists and has a size greater than zero.
1971 -t fd True if file descriptor fd is open and refers to a terminal.
1972 -u file
1973 True if file exists and its set-user-id bit is set.
1974 -w file
1975 True if file exists and is writable.
1976 -x file
1977 True if file exists and is executable.
1978 -O file
1979 True if file exists and is owned by the effective user id.
1980 -G file
1981 True if file exists and is owned by the effective group id.
1982 -L file
1983 True if file exists and is a symbolic link.
1984 -S file
1985 True if file exists and is a socket.
1986 -N file
1987 True if file exists and has been modified since it was last
1988 read.
1989 file1 -nt file2
1990 True if file1 is newer (according to modification date) than
1991 file2, or if file1 exists and file2 does not.
1992 file1 -ot file2
1993 True if file1 is older than file2, or if file2 exists and file1
1994 does not.
1995 file1 -ef file2
1996 True if file1 and file2 refer to the same device and inode
1997 numbers.
1998 -o optname
1999 True if shell option optname is enabled. See the list of
2000 options under the description of the -o option to the set
2001 builtin below.
2002 -z string
2003 True if the length of string is zero.
2004 string
2005 -n string
2006 True if the length of string is non-zero.
2007
2008 string1 == string2
2009 True if the strings are equal. = may be used in place of == for
2010 strict POSIX compliance.
2011
2012 string1 != string2
2013 True if the strings are not equal.
2014
2015 string1 < string2
2016 True if string1 sorts before string2 lexicographically in the
2017 current locale.
2018
2019 string1 > string2
2020 True if string1 sorts after string2 lexicographically in the
2021 current locale.
2022
2023 arg1 OP arg2
2024 OP is one of -eq, -ne, -lt, -le, -gt, or -ge. These arithmetic
2025 binary operators return true if arg1 is equal to, not equal to,
2026 less than, less than or equal to, greater than, or greater than
2027 or equal to arg2, respectively. Arg1 and arg2 may be positive
2028 or negative integers.
2029
2030SIMPLE COMMAND EXPANSION
2031 When a simple command is executed, the shell performs the following
2032 expansions, assignments, and redirections, from left to right.
2033
2034 1. The words that the parser has marked as variable assignments
2035 (those preceding the command name) and redirections are saved
2036 for later processing.
2037
2038 2. The words that are not variable assignments or redirections are
2039 expanded. If any words remain after expansion, the first word
2040 is taken to be the name of the command and the remaining words
2041 are the arguments.
2042
2043 3. Redirections are performed as described above under REDIRECTION.
2044
2045 4. The text after the = in each variable assignment undergoes tilde
2046 expansion, parameter expansion, command substitution, arithmetic
2047 expansion, and quote removal before being assigned to the
2048 variable.
2049
2050 If no command name results, the variable assignments affect the current
2051 shell environment. Otherwise, the variables are added to the
2052 environment of the executed command and do not affect the current shell
2053 environment. If any of the assignments attempts to assign a value to a
2054 readonly variable, an error occurs, and the command exits with a non-
2055 zero status.
2056
2057 If no command name results, redirections are performed, but do not
2058 affect the current shell environment. A redirection error causes the
2059 command to exit with a non-zero status.
2060
2061 If there is a command name left after expansion, execution proceeds as
2062 described below. Otherwise, the command exits. If one of the
2063 expansions contained a command substitution, the exit status of the
2064 command is the exit status of the last command substitution performed.
2065 If there were no command substitutions, the command exits with a status
2066 of zero.
2067
2068COMMAND EXECUTION
2069 After a command has been split into words, if it results in a simple
2070 command and an optional list of arguments, the following actions are
2071 taken.
2072
2073 If the command name contains no slashes, the shell attempts to locate
2074 it. If there exists a shell function by that name, that function is
2075 invoked as described above in FUNCTIONS. If the name does not match a
2076 function, the shell searches for it in the list of shell builtins. If
2077 a match is found, that builtin is invoked.
2078
2079 If the name is neither a shell function nor a builtin, and contains no
2080 slashes, bash searches each element of the PATH for a directory
2081 containing an executable file by that name. Bash uses a hash table to
2082 remember the full pathnames of executable files (see hash under SHELL
2083 BUILTIN COMMANDS below). A full search of the directories in PATH is
2084 performed only if the command is not found in the hash table. If the
2085 search is unsuccessful, the shell prints an error message and returns
2086 an exit status of 127.
2087
2088 If the search is successful, or if the command name contains one or
2089 more slashes, the shell executes the named program in a separate
2090 execution environment. Argument 0 is set to the name given, and the
2091 remaining arguments to the command are set to the arguments given, if
2092 any.
2093
2094 If this execution fails because the file is not in executable format,
2095 and the file is not a directory, it is assumed to be a shell script, a
2096 file containing shell commands. A subshell is spawned to execute it.
2097 This subshell reinitializes itself, so that the effect is as if a new
2098 shell had been invoked to handle the script, with the exception that
2099 the locations of commands remembered by the parent (see hash below
2100 under SHELL BUILTIN COMMANDS) are retained by the child.
2101
2102 If the program is a file beginning with #!, the remainder of the first
2103 line specifies an interpreter for the program. The shell executes the
2104 specified interpreter on operating systems that do not handle this
2105 executable format themselves. The arguments to the interpreter consist
2106 of a single optional argument following the interpreter name on the
2107 first line of the program, followed by the name of the program,
2108 followed by the command arguments, if any.
2109
2110COMMAND EXECUTION ENVIRONMENT
2111 The shell has an execution environment, which consists of the
2112 following:
2113
2114
2115 • open files inherited by the shell at invocation, as modified by
2116 redirections supplied to the exec builtin
2117
2118 • the current working directory as set by cd, pushd, or popd, or
2119 inherited by the shell at invocation
2120
2121 • the file creation mode mask as set by umask or inherited from
2122 the shell's parent
2123
2124 • current traps set by trap
2125
2126 • shell parameters that are set by variable assignment or with set
2127 or inherited from the shell's parent in the environment
2128
2129 • shell functions defined during execution or inherited from the
2130 shell's parent in the environment
2131
2132 • options enabled at invocation (either by default or with
2133 command-line arguments) or by set
2134
2135 • options enabled by shopt
2136
2137 • shell aliases defined with alias
2138
2139 • various process IDs, including those of background jobs, the
2140 value of $$, and the value of $PPID
2141
2142 When a simple command other than a builtin or shell function is to be
2143 executed, it is invoked in a separate execution environment that
2144 consists of the following. Unless otherwise noted, the values are
2145 inherited from the shell.
2146
2147
2148 • the shell's open files, plus any modifications and additions
2149 specified by redirections to the command
2150
2151 • the current working directory
2152
2153 • the file creation mode mask
2154
2155 • shell variables and functions marked for export, along with
2156 variables exported for the command, passed in the environment
2157
2158 • traps caught by the shell are reset to the values inherited from
2159 the shell's parent, and traps ignored by the shell are ignored
2160
2161 A command invoked in this separate environment cannot affect the
2162 shell's execution environment.
2163
2164 Command substitution, commands grouped with parentheses, and
2165 asynchronous commands are invoked in a subshell environment that is a
2166 duplicate of the shell environment, except that traps caught by the
2167 shell are reset to the values that the shell inherited from its parent
2168 at invocation. Builtin commands that are invoked as part of a pipeline
2169 are also executed in a subshell environment. Changes made to the
2170 subshell environment cannot affect the shell's execution environment.
2171
2172 If a command is followed by a & and job control is not active, the
2173 default standard input for the command is the empty file /dev/null.
2174 Otherwise, the invoked command inherits the file descriptors of the
2175 calling shell as modified by redirections.
2176
2177ENVIRONMENT
2178 When a program is invoked it is given an array of strings called the
2179 environment. This is a list of name-value pairs, of the form
2180 name=value.
2181
2182 The shell provides several ways to manipulate the environment. On
2183 invocation, the shell scans its own environment and creates a parameter
2184 for each name found, automatically marking it for export to child
2185 processes. Executed commands inherit the environment. The export and
2186 declare -x commands allow parameters and functions to be added to and
2187 deleted from the environment. If the value of a parameter in the
2188 environment is modified, the new value becomes part of the environment,
2189 replacing the old. The environment inherited by any executed command
2190 consists of the shell's initial environment, whose values may be
2191 modified in the shell, less any pairs removed by the unset command,
2192 plus any additions via the export and declare -x commands.
2193
2194 The environment for any simple command or function may be augmented
2195 temporarily by prefixing it with parameter assignments, as described
2196 above in PARAMETERS. These assignment statements affect only the
2197 environment seen by that command.
2198
2199 If the -k option is set (see the set builtin command below), then all
2200 parameter assignments are placed in the environment for a command, not
2201 just those that precede the command name.
2202
2203 When bash invokes an external command, the variable _ is set to the
2204 full file name of the command and passed to that command in its
2205 environment.
2206
2207EXIT STATUS
2208 For the shell's purposes, a command which exits with a zero exit status
2209 has succeeded. An exit status of zero indicates success. A non-zero
2210 exit status indicates failure. When a command terminates on a fatal
2211 signal N, bash uses the value of 128+N as the exit status.
2212
2213 If a command is not found, the child process created to execute it
2214 returns a status of 127. If a command is found but is not executable,
2215 the return status is 126.
2216
2217 If a command fails because of an error during expansion or redirection,
2218 the exit status is greater than zero.
2219
2220 Shell builtin commands return a status of 0 (true) if successful, and
2221 non-zero (false) if an error occurs while they execute. All builtins
2222 return an exit status of 2 to indicate incorrect usage.
2223
2224 Bash itself returns the exit status of the last command executed,
2225 unless a syntax error occurs, in which case it exits with a non-zero
2226 value. See also the exit builtin command below.
2227
2228SIGNALS
2229 When bash is interactive, in the absence of any traps, it ignores
2230 SIGTERM (so that kill 0 does not kill an interactive shell), and SIGINT
2231 is caught and handled (so that the wait builtin is interruptible). In
2232 all cases, bash ignores SIGQUIT. If job control is in effect, bash
2233 ignores SIGTTIN, SIGTTOU, and SIGTSTP.
2234
2235 Non-builtin commands run by bash have signal handlers set to the values
2236 inherited by the shell from its parent. When job control is not in
2237 effect, asynchronous commands ignore SIGINT and SIGQUIT in addition to
2238 these inherited handlers. Commands run as a result of command
2239 substitution ignore the keyboard-generated job control signals SIGTTIN,
2240 SIGTTOU, and SIGTSTP.
2241
2242 The shell exits by default upon receipt of a SIGHUP. Before exiting,
2243 an interactive shell resends the SIGHUP to all jobs, running or
2244 stopped. Stopped jobs are sent SIGCONT to ensure that they receive the
2245 SIGHUP. To prevent the shell from sending the signal to a particular
2246 job, it should be removed from the jobs table with the disown builtin
2247 (see SHELL BUILTIN COMMANDS below) or marked to not receive SIGHUP
2248 using disown -h.
2249
2250 If the huponexit shell option has been set with shopt, bash sends a
2251 SIGHUP to all jobs when an interactive login shell exits.
2252
2253 If bash is waiting for a command to complete and receives a signal for
2254 which a trap has been set, the trap will not be executed until the
2255 command completes. When bash is waiting for an asynchronous command
2256 via the wait builtin, the reception of a signal for which a trap has
2257 been set will cause the wait builtin to return immediately with an exit
2258 status greater than 128, immediately after which the trap is executed.
2259
2260JOB CONTROL
2261 Job control refers to the ability to selectively stop (suspend) the
2262 execution of processes and continue (resume) their execution at a later
2263 point. A user typically employs this facility via an interactive
2264 interface supplied jointly by the system's terminal driver and bash.
2265
2266 The shell associates a job with each pipeline. It keeps a table of
2267 currently executing jobs, which may be listed with the jobs command.
2268 When bash starts a job asynchronously (in the background), it prints a
2269 line that looks like:
2270
2271 [1] 25647
2272
2273 indicating that this job is job number 1 and that the process ID of the
2274 last process in the pipeline associated with this job is 25647. All of
2275 the processes in a single pipeline are members of the same job. Bash
2276 uses the job abstraction as the basis for job control.
2277
2278 To facilitate the implementation of the user interface to job control,
2279 the operating system maintains the notion of a current terminal process
2280 group ID. Members of this process group (processes whose process group
2281 ID is equal to the current terminal process group ID) receive keyboard-
2282 generated signals such as SIGINT. These processes are said to be in
2283 the foreground. Background processes are those whose process group ID
2284 differs from the terminal's; such processes are immune to keyboard-
2285 generated signals. Only foreground processes are allowed to read from
2286 or write to the terminal. Background processes which attempt to read
2287 from (write to) the terminal are sent a SIGTTIN (SIGTTOU) signal by the
2288 terminal driver, which, unless caught, suspends the process.
2289
2290 If the operating system on which bash is running supports job control,
2291 bash contains facilities to use it. Typing the suspend character
2292 (typically ^Z, Control-Z) while a process is running causes that
2293 process to be stopped and returns control to bash. Typing the delayed
2294 suspend character (typically ^Y, Control-Y) causes the process to be
2295 stopped when it attempts to read input from the terminal, and control
2296 to be returned to bash. The user may then manipulate the state of this
2297 job, using the bg command to continue it in the background, the fg
2298 command to continue it in the foreground, or the kill command to kill
2299 it. A ^Z takes effect immediately, and has the additional side effect
2300 of causing pending output and typeahead to be discarded.
2301
2302 There are a number of ways to refer to a job in the shell. The
2303 character % introduces a job name. Job number n may be referred to as
2304 %n. A job may also be referred to using a prefix of the name used to
2305 start it, or using a substring that appears in its command line. For
2306 example, %ce refers to a stopped ce job. If a prefix matches more than
2307 one job, bash reports an error. Using %?ce, on the other hand, refers
2308 to any job containing the string ce in its command line. If the
2309 substring matches more than one job, bash reports an error. The
2310 symbols %% and %+ refer to the shell's notion of the current job, which
2311 is the last job stopped while it was in the foreground or started in
2312 the background. The previous job may be referenced using %-. In
2313 output pertaining to jobs (e.g., the output of the jobs command), the
2314 current job is always flagged with a +, and the previous job with a -.
2315 A single % (with no accompanying job specification) also refers to the
2316 current job.
2317
2318 Simply naming a job can be used to bring it into the foreground: %1 is
2319 a synonym for ``fg %1'', bringing job 1 from the background into the
2320 foreground. Similarly, ``%1 &'' resumes job 1 in the background,
2321 equivalent to ``bg %1''.
2322
2323 The shell learns immediately whenever a job changes state. Normally,
2324 bash waits until it is about to print a prompt before reporting changes
2325 in a job's status so as to not interrupt any other output. If the -b
2326 option to the set builtin command is enabled, bash reports such changes
2327 immediately. Any trap on SIGCHLD is executed for each child that
2328 exits.
2329
2330 If an attempt to exit bash is made while jobs are stopped, the shell
2331 prints a warning message. The jobs command may then be used to inspect
2332 their status. If a second attempt to exit is made without an
2333 intervening command, the shell does not print another warning, and the
2334 stopped jobs are terminated.
2335
2336PROMPTING
2337 When executing interactively, bash displays the primary prompt PS1 when
2338 it is ready to read a command, and the secondary prompt PS2 when it
2339 needs more input to complete a command. Bash allows these prompt
2340 strings to be customized by inserting a number of backslash-escaped
2341 special characters that are decoded as follows:
2342 \a an ASCII bell character (07)
2343 \d the date in "Weekday Month Date" format (e.g., "Tue May
2344 26")
2345 \D{format}
2346 the format is passed to strftime(3) and the result is
2347 inserted into the prompt string; an empty format results
2348 in a locale-specific time representation. The braces are
2349 required
2350 \e an ASCII escape character (033)
2351 \h the hostname up to the first `.'
2352 \H the hostname
2353 \j the number of jobs currently managed by the shell
2354 \l the basename of the shell's terminal device name
2355 \n newline
2356 \r carriage return
2357 \s the name of the shell, the basename of $0 (the portion
2358 following the final slash)
2359 \t the current time in 24-hour HH:MM:SS format
2360 \T the current time in 12-hour HH:MM:SS format
2361 \@ the current time in 12-hour am/pm format
2362 \A the current time in 24-hour HH:MM format
2363 \u the username of the current user
2364 \v the version of bash (e.g., 2.00)
2365 \V the release of bash, version + patch level (e.g., 2.00.0)
2366 \w the current working directory, with $HOME abbreviated
2367 with a tilde
2368 \W the basename of the current working directory, with $HOME
2369 abbreviated with a tilde
2370 \! the history number of this command
2371 \# the command number of this command
2372 \$ if the effective UID is 0, a #, otherwise a $
2373 \nnn the character corresponding to the octal number nnn
2374 \\ a backslash
2375 \[ begin a sequence of non-printing characters, which could
2376 be used to embed a terminal control sequence into the
2377 prompt
2378 \] end a sequence of non-printing characters
2379
2380 The command number and the history number are usually different: the
2381 history number of a command is its position in the history list, which
2382 may include commands restored from the history file (see HISTORY
2383 below), while the command number is the position in the sequence of
2384 commands executed during the current shell session. After the string
2385 is decoded, it is expanded via parameter expansion, command
2386 substitution, arithmetic expansion, and quote removal, subject to the
2387 value of the promptvars shell option (see the description of the shopt
2388 command under SHELL BUILTIN COMMANDS below).
2389
2390READLINE
2391 This is the library that handles reading input when using an
2392 interactive shell, unless the --noediting option is given at shell
2393 invocation. By default, the line editing commands are similar to those
2394 of emacs. A vi-style line editing interface is also available. To
2395 turn off line editing after the shell is running, use the +o emacs or
2396 +o vi options to the set builtin (see SHELL BUILTIN COMMANDS below).
2397
2398 Readline Notation
2399 In this section, the emacs-style notation is used to denote keystrokes.
2400 Control keys are denoted by C-key, e.g., C-n means Control-N.
2401 Similarly, meta keys are denoted by M-key, so M-x means Meta-X. (On
2402 keyboards without a meta key, M-x means ESC x, i.e., press the Escape
2403 key then the x key. This makes ESC the meta prefix. The combination
2404 M-C-x means ESC-Control-x, or press the Escape key then hold the
2405 Control key while pressing the x key.)
2406
2407 Readline commands may be given numeric arguments, which normally act as
2408 a repeat count. Sometimes, however, it is the sign of the argument
2409 that is significant. Passing a negative argument to a command that
2410 acts in the forward direction (e.g., kill-line) causes that command to
2411 act in a backward direction. Commands whose behavior with arguments
2412 deviates from this are noted below.
2413
2414 When a command is described as killing text, the text deleted is saved
2415 for possible future retrieval (yanking). The killed text is saved in a
2416 kill ring. Consecutive kills cause the text to be accumulated into one
2417 unit, which can be yanked all at once. Commands which do not kill text
2418 separate the chunks of text on the kill ring.
2419
2420 Readline Initialization
2421 Readline is customized by putting commands in an initialization file
2422 (the inputrc file). The name of this file is taken from the value of
2423 the INPUTRC variable. If that variable is unset, the default is
2424 ~/.inputrc. When a program which uses the readline library starts up,
2425 the initialization file is read, and the key bindings and variables are
2426 set. There are only a few basic constructs allowed in the readline
2427 initialization file. Blank lines are ignored. Lines beginning with a
2428 # are comments. Lines beginning with a $ indicate conditional
2429 constructs. Other lines denote key bindings and variable settings.
2430
2431 The default key-bindings may be changed with an inputrc file. Other
2432 programs that use this library may add their own commands and bindings.
2433
2434 For example, placing
2435
2436 M-Control-u: universal-argument
2437 or
2438 C-Meta-u: universal-argument
2439 into the inputrc would make M-C-u execute the readline command
2440 universal-argument.
2441
2442 The following symbolic character names are recognized: RUBOUT, DEL,
2443 ESC, LFD, NEWLINE, RET, RETURN, SPC, SPACE, and TAB.
2444
2445 In addition to command names, readline allows keys to be bound to a
2446 string that is inserted when the key is pressed (a macro).
2447
2448 Readline Key Bindings
2449 The syntax for controlling key bindings in the inputrc file is simple.
2450 All that is required is the name of the command or the text of a macro
2451 and a key sequence to which it should be bound. The name may be
2452 specified in one of two ways: as a symbolic key name, possibly with
2453 Meta- or Control- prefixes, or as a key sequence.
2454
2455 When using the form keyname:function-name or macro, keyname is the name
2456 of a key spelled out in English. For example:
2457
2458 Control-u: universal-argument
2459 Meta-Rubout: backward-kill-word
2460 Control-o: "> output"
2461
2462 In the above example, C-u is bound to the function universal-argument,
2463 M-DEL is bound to the function backward-kill-word, and C-o is bound to
2464 run the macro expressed on the right hand side (that is, to insert the
2465 text ``> output'' into the line).
2466
2467 In the second form, "keyseq":function-name or macro, keyseq differs
2468 from keyname above in that strings denoting an entire key sequence may
2469 be specified by placing the sequence within double quotes. Some GNU
2470 Emacs style key escapes can be used, as in the following example, but
2471 the symbolic character names are not recognized.
2472
2473 "\C-u": universal-argument
2474 "\C-x\C-r": re-read-init-file
2475 "\e[11~": "Function Key 1"
2476
2477 In this example, C-u is again bound to the function universal-argument.
2478 C-x C-r is bound to the function re-read-init-file, and ESC [ 1 1 ~ is
2479 bound to insert the text ``Function Key 1''.
2480
2481 The full set of GNU Emacs style escape sequences is
2482 \C- control prefix
2483 \M- meta prefix
2484 \e an escape character
2485 \\ backslash
2486 \" literal "
2487 \' literal '
2488
2489 In addition to the GNU Emacs style escape sequences, a second set of
2490 backslash escapes is available:
2491 \a alert (bell)
2492 \b backspace
2493 \d delete
2494 \f form feed
2495 \n newline
2496 \r carriage return
2497 \t horizontal tab
2498 \v vertical tab
2499 \nnn the eight-bit character whose value is the octal value
2500 nnn (one to three digits)
2501 \xHH the eight-bit character whose value is the hexadecimal
2502 value HH (one or two hex digits)
2503
2504 When entering the text of a macro, single or double quotes must be used
2505 to indicate a macro definition. Unquoted text is assumed to be a
2506 function name. In the macro body, the backslash escapes described
2507 above are expanded. Backslash will quote any other character in the
2508 macro text, including " and '.
2509
2510 Bash allows the current readline key bindings to be displayed or
2511 modified with the bind builtin command. The editing mode may be
2512 switched during interactive use by using the -o option to the set
2513 builtin command (see SHELL BUILTIN COMMANDS below).
2514
2515 Readline Variables
2516 Readline has variables that can be used to further customize its
2517 behavior. A variable may be set in the inputrc file with a statement
2518 of the form
2519
2520 set variable-name value
2521
2522 Except where noted, readline variables can take the values On or Off
2523 (without regard to case). Unrecognized variable names are ignored.
2524 When a variable value is read, empty or null values, "on" (case-
2525 insensitive), and "1" are equivalent to On. All other values are
2526 equivalent to Off. The variables and their default values are:
2527
2528 bell-style (audible)
2529 Controls what happens when readline wants to ring the terminal
2530 bell. If set to none, readline never rings the bell. If set to
2531 visible, readline uses a visible bell if one is available. If
2532 set to audible, readline attempts to ring the terminal's bell.
2533 bind-tty-special-chars (On)
2534 If set to On, readline attempts to bind the control characters
2535 treated specially by the kernel's terminal driver to their
2536 readline equivalents.
2537 comment-begin (``#'')
2538 The string that is inserted when the readline insert-comment
2539 command is executed. This command is bound to M-# in emacs mode
2540 and to # in vi command mode.
2541 completion-ignore-case (Off)
2542 If set to On, readline performs filename matching and completion
2543 in a case-insensitive fashion.
2544 completion-query-items (100)
2545 This determines when the user is queried about viewing the
2546 number of possible completions generated by the
2547 possible-completions command. It may be set to any integer
2548 value greater than or equal to zero. If the number of possible
2549 completions is greater than or equal to the value of this
2550 variable, the user is asked whether or not he wishes to view
2551 them; otherwise they are simply listed on the terminal.
2552 convert-meta (On)
2553 If set to On, readline will convert characters with the eighth
2554 bit set to an ASCII key sequence by stripping the eighth bit and
2555 prefixing an escape character (in effect, using escape as the
2556 meta prefix).
2557 disable-completion (Off)
2558 If set to On, readline will inhibit word completion. Completion
2559 characters will be inserted into the line as if they had been
2560 mapped to self-insert.
2561 editing-mode (emacs)
2562 Controls whether readline begins with a set of key bindings
2563 similar to emacs or vi. editing-mode can be set to either emacs
2564 or vi.
2565 enable-keypad (Off)
2566 When set to On, readline will try to enable the application
2567 keypad when it is called. Some systems need this to enable the
2568 arrow keys.
2569 expand-tilde (Off)
2570 If set to on, tilde expansion is performed when readline
2571 attempts word completion.
2572 history-preserve-point (Off)
2573 If set to on, the history code attempts to place point at the
2574 same location on each history line retrieved with previous-
2575 history or next-history.
2576 horizontal-scroll-mode (Off)
2577 When set to On, makes readline use a single line for display,
2578 scrolling the input horizontally on a single screen line when it
2579 becomes longer than the screen width rather than wrapping to a
2580 new line.
2581 input-meta (Off)
2582 If set to On, readline will enable eight-bit input (that is, it
2583 will not strip the high bit from the characters it reads),
2584 regardless of what the terminal claims it can support. The name
2585 meta-flag is a synonym for this variable.
2586 isearch-terminators (``C-[C-J'')
2587 The string of characters that should terminate an incremental
2588 search without subsequently executing the character as a
2589 command. If this variable has not been given a value, the
2590 characters ESC and C-J will terminate an incremental search.
2591 keymap (emacs)
2592 Set the current readline keymap. The set of valid keymap names
2593 is emacs, emacs-standard, emacs-meta, emacs-ctlx, vi,
2594 vi-command, and vi-insert. vi is equivalent to vi-command;
2595 emacs is equivalent to emacs-standard. The default value is
2596 emacs; the value of editing-mode also affects the default
2597 keymap.
2598 mark-directories (On)
2599 If set to On, completed directory names have a slash appended.
2600 mark-modified-lines (Off)
2601 If set to On, history lines that have been modified are
2602 displayed with a preceding asterisk (*).
2603 mark-symlinked-directories (Off)
2604 If set to On, completed names which are symbolic links to
2605 directories have a slash appended (subject to the value of
2606 mark-directories).
2607 match-hidden-files (On)
2608 This variable, when set to On, causes readline to match files
2609 whose names begin with a `.' (hidden files) when performing
2610 filename completion, unless the leading `.' is supplied by the
2611 user in the filename to be completed.
2612 output-meta (Off)
2613 If set to On, readline will display characters with the eighth
2614 bit set directly rather than as a meta-prefixed escape sequence.
2615 page-completions (On)
2616 If set to On, readline uses an internal more-like pager to
2617 display a screenful of possible completions at a time.
2618 print-completions-horizontally (Off)
2619 If set to On, readline will display completions with matches
2620 sorted horizontally in alphabetical order, rather than down the
2621 screen.
2622 show-all-if-ambiguous (Off)
2623 This alters the default behavior of the completion functions.
2624 If set to on, words which have more than one possible completion
2625 cause the matches to be listed immediately instead of ringing
2626 the bell.
2627 show-all-if-unmodified (Off)
2628 This alters the default behavior of the completion functions in
2629 a fashion similar to show-all-if-ambiguous. If set to on, words
2630 which have more than one possible completion without any
2631 possible partial completion (the possible completions don't
2632 share a common prefix) cause the matches to be listed
2633 immediately instead of ringing the bell.
2634 visible-stats (Off)
2635 If set to On, a character denoting a file's type as reported by
2636 stat(2) is appended to the filename when listing possible
2637 completions.
2638
2639 Readline Conditional Constructs
2640 Readline implements a facility similar in spirit to the conditional
2641 compilation features of the C preprocessor which allows key bindings
2642 and variable settings to be performed as the result of tests. There
2643 are four parser directives used.
2644
2645 $if The $if construct allows bindings to be made based on the
2646 editing mode, the terminal being used, or the application using
2647 readline. The text of the test extends to the end of the line;
2648 no characters are required to isolate it.
2649
2650 mode The mode= form of the $if directive is used to test
2651 whether readline is in emacs or vi mode. This may be
2652 used in conjunction with the set keymap command, for
2653 instance, to set bindings in the emacs-standard and
2654 emacs-ctlx keymaps only if readline is starting out in
2655 emacs mode.
2656
2657 term The term= form may be used to include terminal-specific
2658 key bindings, perhaps to bind the key sequences output by
2659 the terminal's function keys. The word on the right side
2660 of the = is tested against the both full name of the
2661 terminal and the portion of the terminal name before the
2662 first -. This allows sun to match both sun and sun-cmd,
2663 for instance.
2664
2665 application
2666 The application construct is used to include application-
2667 specific settings. Each program using the readline
2668 library sets the application name, and an initialization
2669 file can test for a particular value. This could be used
2670 to bind key sequences to functions useful for a specific
2671 program. For instance, the following command adds a key
2672 sequence that quotes the current or previous word in
2673 Bash:
2674
2675 $if Bash
2676 # Quote the current or previous word
2677 "\C-xq": "\eb\"\ef\""
2678 $endif
2679
2680 $endif This command, as seen in the previous example, terminates an $if
2681 command.
2682
2683 $else Commands in this branch of the $if directive are executed if the
2684 test fails.
2685
2686 $include
2687 This directive takes a single filename as an argument and reads
2688 commands and bindings from that file. For example, the
2689 following directive would read /etc/inputrc:
2690
2691 $include /etc/inputrc
2692
2693 Searching
2694 Readline provides commands for searching through the command history
2695 (see HISTORY below) for lines containing a specified string. There are
2696 two search modes: incremental and non-incremental.
2697
2698 Incremental searches begin before the user has finished typing the
2699 search string. As each character of the search string is typed,
2700 readline displays the next entry from the history matching the string
2701 typed so far. An incremental search requires only as many characters
2702 as needed to find the desired history entry. The characters present in
2703 the value of the isearch-terminators variable are used to terminate an
2704 incremental search. If that variable has not been assigned a value the
2705 Escape and Control-J characters will terminate an incremental search.
2706 Control-G will abort an incremental search and restore the original
2707 line. When the search is terminated, the history entry containing the
2708 search string becomes the current line.
2709
2710 To find other matching entries in the history list, type Control-S or
2711 Control-R as appropriate. This will search backward or forward in the
2712 history for the next entry matching the search string typed so far.
2713 Any other key sequence bound to a readline command will terminate the
2714 search and execute that command. For instance, a newline will
2715 terminate the search and accept the line, thereby executing the command
2716 from the history list.
2717
2718 Readline remembers the last incremental search string. If two Control-
2719 Rs are typed without any intervening characters defining a new search
2720 string, any remembered search string is used.
2721
2722 Non-incremental searches read the entire search string before starting
2723 to search for matching history lines. The search string may be typed
2724 by the user or be part of the contents of the current line.
2725
2726 Readline Command Names
2727 The following is a list of the names of the commands and the default
2728 key sequences to which they are bound. Command names without an
2729 accompanying key sequence are unbound by default. In the following
2730 descriptions, point refers to the current cursor position, and mark
2731 refers to a cursor position saved by the set-mark command. The text
2732 between the point and mark is referred to as the region.
2733
2734 Commands for Moving
2735 beginning-of-line (C-a)
2736 Move to the start of the current line.
2737 end-of-line (C-e)
2738 Move to the end of the line.
2739 forward-char (C-f)
2740 Move forward a character.
2741 backward-char (C-b)
2742 Move back a character.
2743 forward-word (M-f)
2744 Move forward to the end of the next word. Words are composed of
2745 alphanumeric characters (letters and digits).
2746 backward-word (M-b)
2747 Move back to the start of the current or previous word. Words
2748 are composed of alphanumeric characters (letters and digits).
2749 clear-screen (C-l)
2750 Clear the screen leaving the current line at the top of the
2751 screen. With an argument, refresh the current line without
2752 clearing the screen.
2753 redraw-current-line
2754 Refresh the current line.
2755
2756 Commands for Manipulating the History
2757 accept-line (Newline, Return)
2758 Accept the line regardless of where the cursor is. If this line
2759 is non-empty, add it to the history list according to the state
2760 of the HISTCONTROL variable. If the line is a modified history
2761 line, then restore the history line to its original state.
2762 previous-history (C-p)
2763 Fetch the previous command from the history list, moving back in
2764 the list.
2765 next-history (C-n)
2766 Fetch the next command from the history list, moving forward in
2767 the list.
2768 beginning-of-history (M-<)
2769 Move to the first line in the history.
2770 end-of-history (M->)
2771 Move to the end of the input history, i.e., the line currently
2772 being entered.
2773 reverse-search-history (C-r)
2774 Search backward starting at the current line and moving `up'
2775 through the history as necessary. This is an incremental
2776 search.
2777 forward-search-history (C-s)
2778 Search forward starting at the current line and moving `down'
2779 through the history as necessary. This is an incremental
2780 search.
2781 non-incremental-reverse-search-history (M-p)
2782 Search backward through the history starting at the current line
2783 using a non-incremental search for a string supplied by the
2784 user.
2785 non-incremental-forward-search-history (M-n)
2786 Search forward through the history using a non-incremental
2787 search for a string supplied by the user.
2788 history-search-forward
2789 Search forward through the history for the string of characters
2790 between the start of the current line and the point. This is a
2791 non-incremental search.
2792 history-search-backward
2793 Search backward through the history for the string of characters
2794 between the start of the current line and the point. This is a
2795 non-incremental search.
2796 yank-nth-arg (M-C-y)
2797 Insert the first argument to the previous command (usually the
2798 second word on the previous line) at point. With an argument n,
2799 insert the nth word from the previous command (the words in the
2800 previous command begin with word 0). A negative argument
2801 inserts the nth word from the end of the previous command. Once
2802 the argument n is computed, the argument is extracted as if the
2803 "!n" history expansion had been specified.
2804 yank-last-arg (M-., M-_)
2805 Insert the last argument to the previous command (the last word
2806 of the previous history entry). With an argument, behave
2807 exactly like yank-nth-arg. Successive calls to yank-last-arg
2808 move back through the history list, inserting the last argument
2809 of each line in turn. The history expansion facilities are used
2810 to extract the last argument, as if the "!$" history expansion
2811 had been specified.
2812 shell-expand-line (M-C-e)
2813 Expand the line as the shell does. This performs alias and
2814 history expansion as well as all of the shell word expansions.
2815 See HISTORY EXPANSION below for a description of history
2816 expansion.
2817 history-expand-line (M-^)
2818 Perform history expansion on the current line. See HISTORY
2819 EXPANSION below for a description of history expansion.
2820 magic-space
2821 Perform history expansion on the current line and insert a
2822 space. See HISTORY EXPANSION below for a description of history
2823 expansion.
2824 alias-expand-line
2825 Perform alias expansion on the current line. See ALIASES above
2826 for a description of alias expansion.
2827 history-and-alias-expand-line
2828 Perform history and alias expansion on the current line.
2829 insert-last-argument (M-., M-_)
2830 A synonym for yank-last-arg.
2831 operate-and-get-next (C-o)
2832 Accept the current line for execution and fetch the next line
2833 relative to the current line from the history for editing. Any
2834 argument is ignored.
2835 edit-and-execute-command (C-xC-e)
2836 Invoke an editor on the current command line, and execute the
2837 result as shell commands. Bash attempts to invoke $FCEDIT,
2838 $EDITOR, and emacs as the editor, in that order.
2839
2840 Commands for Changing Text
2841 delete-char (C-d)
2842 Delete the character at point. If point is at the beginning of
2843 the line, there are no characters in the line, and the last
2844 character typed was not bound to delete-char, then return EOF.
2845 backward-delete-char (Rubout)
2846 Delete the character behind the cursor. When given a numeric
2847 argument, save the deleted text on the kill ring.
2848 forward-backward-delete-char
2849 Delete the character under the cursor, unless the cursor is at
2850 the end of the line, in which case the character behind the
2851 cursor is deleted.
2852 quoted-insert (C-q, C-v)
2853 Add the next character typed to the line verbatim. This is how
2854 to insert characters like C-q, for example.
2855 tab-insert (C-v TAB)
2856 Insert a tab character.
2857 self-insert (a, b, A, 1, !, ...)
2858 Insert the character typed.
2859 transpose-chars (C-t)
2860 Drag the character before point forward over the character at
2861 point, moving point forward as well. If point is at the end of
2862 the line, then this transposes the two characters before point.
2863 Negative arguments have no effect.
2864 transpose-words (M-t)
2865 Drag the word before point past the word after point, moving
2866 point over that word as well. If point is at the end of the
2867 line, this transposes the last two words on the line.
2868 upcase-word (M-u)
2869 Uppercase the current (or following) word. With a negative
2870 argument, uppercase the previous word, but do not move point.
2871 downcase-word (M-l)
2872 Lowercase the current (or following) word. With a negative
2873 argument, lowercase the previous word, but do not move point.
2874 capitalize-word (M-c)
2875 Capitalize the current (or following) word. With a negative
2876 argument, capitalize the previous word, but do not move point.
2877 overwrite-mode
2878 Toggle overwrite mode. With an explicit positive numeric
2879 argument, switches to overwrite mode. With an explicit non-
2880 positive numeric argument, switches to insert mode. This
2881 command affects only emacs mode; vi mode does overwrite
2882 differently. Each call to readline() starts in insert mode. In
2883 overwrite mode, characters bound to self-insert replace the text
2884 at point rather than pushing the text to the right. Characters
2885 bound to backward-delete-char replace the character before point
2886 with a space. By default, this command is unbound.
2887
2888 Killing and Yanking
2889 kill-line (C-k)
2890 Kill the text from point to the end of the line.
2891 backward-kill-line (C-x Rubout)
2892 Kill backward to the beginning of the line.
2893 unix-line-discard (C-u)
2894 Kill backward from point to the beginning of the line. The
2895 killed text is saved on the kill-ring.
2896 kill-whole-line
2897 Kill all characters on the current line, no matter where point
2898 is.
2899 kill-word (M-d)
2900 Kill from point to the end of the current word, or if between
2901 words, to the end of the next word. Word boundaries are the
2902 same as those used by forward-word.
2903 backward-kill-word (M-Rubout)
2904 Kill the word behind point. Word boundaries are the same as
2905 those used by backward-word.
2906 unix-word-rubout (C-w)
2907 Kill the word behind point, using white space as a word
2908 boundary. The killed text is saved on the kill-ring.
2909 unix-filename-rubout
2910 Kill the word behind point, using white space and the slash
2911 character as the word boundaries. The killed text is saved on
2912 the kill-ring.
2913 delete-horizontal-space (M-\)
2914 Delete all spaces and tabs around point.
2915 kill-region
2916 Kill the text in the current region.
2917 copy-region-as-kill
2918 Copy the text in the region to the kill buffer.
2919 copy-backward-word
2920 Copy the word before point to the kill buffer. The word
2921 boundaries are the same as backward-word.
2922 copy-forward-word
2923 Copy the word following point to the kill buffer. The word
2924 boundaries are the same as forward-word.
2925 yank (C-y)
2926 Yank the top of the kill ring into the buffer at point.
2927 yank-pop (M-y)
2928 Rotate the kill ring, and yank the new top. Only works
2929 following yank or yank-pop.
2930
2931 Numeric Arguments
2932 digit-argument (M-0, M-1, ..., M--)
2933 Add this digit to the argument already accumulating, or start a
2934 new argument. M-- starts a negative argument.
2935 universal-argument
2936 This is another way to specify an argument. If this command is
2937 followed by one or more digits, optionally with a leading minus
2938 sign, those digits define the argument. If the command is
2939 followed by digits, executing universal-argument again ends the
2940 numeric argument, but is otherwise ignored. As a special case,
2941 if this command is immediately followed by a character that is
2942 neither a digit or minus sign, the argument count for the next
2943 command is multiplied by four. The argument count is initially
2944 one, so executing this function the first time makes the
2945 argument count four, a second time makes the argument count
2946 sixteen, and so on.
2947
2948 Completing
2949 complete (TAB)
2950 Attempt to perform completion on the text before point. Bash
2951 attempts completion treating the text as a variable (if the text
2952 begins with $), username (if the text begins with ~), hostname
2953 (if the text begins with @), or command (including aliases and
2954 functions) in turn. If none of these produces a match, filename
2955 completion is attempted.
2956 possible-completions (M-?)
2957 List the possible completions of the text before point.
2958 insert-completions (M-*)
2959 Insert all completions of the text before point that would have
2960 been generated by possible-completions.
2961 menu-complete
2962 Similar to complete, but replaces the word to be completed with
2963 a single match from the list of possible completions. Repeated
2964 execution of menu-complete steps through the list of possible
2965 completions, inserting each match in turn. At the end of the
2966 list of completions, the bell is rung (subject to the setting of
2967 bell-style) and the original text is restored. An argument of n
2968 moves n positions forward in the list of matches; a negative
2969 argument may be used to move backward through the list. This
2970 command is intended to be bound to TAB, but is unbound by
2971 default.
2972 delete-char-or-list
2973 Deletes the character under the cursor if not at the beginning
2974 or end of the line (like delete-char). If at the end of the
2975 line, behaves identically to possible-completions. This command
2976 is unbound by default.
2977 complete-filename (M-/)
2978 Attempt filename completion on the text before point.
2979 possible-filename-completions (C-x /)
2980 List the possible completions of the text before point, treating
2981 it as a filename.
2982 complete-username (M-~)
2983 Attempt completion on the text before point, treating it as a
2984 username.
2985 possible-username-completions (C-x ~)
2986 List the possible completions of the text before point, treating
2987 it as a username.
2988 complete-variable (M-$)
2989 Attempt completion on the text before point, treating it as a
2990 shell variable.
2991 possible-variable-completions (C-x $)
2992 List the possible completions of the text before point, treating
2993 it as a shell variable.
2994 complete-hostname (M-@)
2995 Attempt completion on the text before point, treating it as a
2996 hostname.
2997 possible-hostname-completions (C-x @)
2998 List the possible completions of the text before point, treating
2999 it as a hostname.
3000 complete-command (M-!)
3001 Attempt completion on the text before point, treating it as a
3002 command name. Command completion attempts to match the text
3003 against aliases, reserved words, shell functions, shell
3004 builtins, and finally executable filenames, in that order.
3005 possible-command-completions (C-x !)
3006 List the possible completions of the text before point, treating
3007 it as a command name.
3008 dynamic-complete-history (M-TAB)
3009 Attempt completion on the text before point, comparing the text
3010 against lines from the history list for possible completion
3011 matches.
3012 complete-into-braces (M-{)
3013 Perform filename completion and insert the list of possible
3014 completions enclosed within braces so the list is available to
3015 the shell (see Brace Expansion above).
3016
3017 Keyboard Macros
3018 start-kbd-macro (C-x ()
3019 Begin saving the characters typed into the current keyboard
3020 macro.
3021 end-kbd-macro (C-x ))
3022 Stop saving the characters typed into the current keyboard macro
3023 and store the definition.
3024 call-last-kbd-macro (C-x e)
3025 Re-execute the last keyboard macro defined, by making the
3026 characters in the macro appear as if typed at the keyboard.
3027
3028 Miscellaneous
3029 re-read-init-file (C-x C-r)
3030 Read in the contents of the inputrc file, and incorporate any
3031 bindings or variable assignments found there.
3032 abort (C-g)
3033 Abort the current editing command and ring the terminal's bell
3034 (subject to the setting of bell-style).
3035 do-uppercase-version (M-a, M-b, M-x, ...)
3036 If the metafied character x is lowercase, run the command that
3037 is bound to the corresponding uppercase character.
3038 prefix-meta (ESC)
3039 Metafy the next character typed. ESC f is equivalent to Meta-f.
3040 undo (C-_, C-x C-u)
3041 Incremental undo, separately remembered for each line.
3042 revert-line (M-r)
3043 Undo all changes made to this line. This is like executing the
3044 undo command enough times to return the line to its initial
3045 state.
3046 tilde-expand (M-&)
3047 Perform tilde expansion on the current word.
3048 set-mark (C-@, M-<space>)
3049 Set the mark to the point. If a numeric argument is supplied,
3050 the mark is set to that position.
3051 exchange-point-and-mark (C-x C-x)
3052 Swap the point with the mark. The current cursor position is
3053 set to the saved position, and the old cursor position is saved
3054 as the mark.
3055 character-search (C-])
3056 A character is read and point is moved to the next occurrence of
3057 that character. A negative count searches for previous
3058 occurrences.
3059 character-search-backward (M-C-])
3060 A character is read and point is moved to the previous
3061 occurrence of that character. A negative count searches for
3062 subsequent occurrences.
3063 insert-comment (M-#)
3064 Without a numeric argument, the value of the readline
3065 comment-begin variable is inserted at the beginning of the
3066 current line. If a numeric argument is supplied, this command
3067 acts as a toggle: if the characters at the beginning of the
3068 line do not match the value of comment-begin, the value is
3069 inserted, otherwise the characters in comment-begin are deleted
3070 from the beginning of the line. In either case, the line is
3071 accepted as if a newline had been typed. The default value of
3072 comment-begin causes this command to make the current line a
3073 shell comment. If a numeric argument causes the comment
3074 character to be removed, the line will be executed by the shell.
3075 glob-complete-word (M-g)
3076 The word before point is treated as a pattern for pathname
3077 expansion, with an asterisk implicitly appended. This pattern
3078 is used to generate a list of matching file names for possible
3079 completions.
3080 glob-expand-word (C-x *)
3081 The word before point is treated as a pattern for pathname
3082 expansion, and the list of matching file names is inserted,
3083 replacing the word. If a numeric argument is supplied, an
3084 asterisk is appended before pathname expansion.
3085 glob-list-expansions (C-x g)
3086 The list of expansions that would have been generated by
3087 glob-expand-word is displayed, and the line is redrawn. If a
3088 numeric argument is supplied, an asterisk is appended before
3089 pathname expansion.
3090 dump-functions
3091 Print all of the functions and their key bindings to the
3092 readline output stream. If a numeric argument is supplied, the
3093 output is formatted in such a way that it can be made part of an
3094 inputrc file.
3095 dump-variables
3096 Print all of the settable readline variables and their values to
3097 the readline output stream. If a numeric argument is supplied,
3098 the output is formatted in such a way that it can be made part
3099 of an inputrc file.
3100 dump-macros
3101 Print all of the readline key sequences bound to macros and the
3102 strings they output. If a numeric argument is supplied, the
3103 output is formatted in such a way that it can be made part of an
3104 inputrc file.
3105 display-shell-version (C-x C-v)
3106 Display version information about the current instance of bash.
3107
3108 Programmable Completion
3109 When word completion is attempted for an argument to a command for
3110 which a completion specification (a compspec) has been defined using
3111 the complete builtin (see SHELL BUILTIN COMMANDS below), the
3112 programmable completion facilities are invoked.
3113
3114 First, the command name is identified. If a compspec has been defined
3115 for that command, the compspec is used to generate the list of possible
3116 completions for the word. If the command word is a full pathname, a
3117 compspec for the full pathname is searched for first. If no compspec
3118 is found for the full pathname, an attempt is made to find a compspec
3119 for the portion following the final slash.
3120
3121 Once a compspec has been found, it is used to generate the list of
3122 matching words. If a compspec is not found, the default bash
3123 completion as described above under Completing is performed.
3124
3125 First, the actions specified by the compspec are used. Only matches
3126 which are prefixed by the word being completed are returned. When the
3127 -f or -d option is used for filename or directory name completion, the
3128 shell variable FIGNORE is used to filter the matches.
3129
3130 Any completions specified by a filename expansion pattern to the -G
3131 option are generated next. The words generated by the pattern need not
3132 match the word being completed. The GLOBIGNORE shell variable is not
3133 used to filter the matches, but the FIGNORE variable is used.
3134
3135 Next, the string specified as the argument to the -W option is
3136 considered. The string is first split using the characters in the IFS
3137 special variable as delimiters. Shell quoting is honored. Each word
3138 is then expanded using brace expansion, tilde expansion, parameter and
3139 variable expansion, command substitution, and arithmetic expansion, as
3140 described above under EXPANSION. The results are split using the rules
3141 described above under Word Splitting. The results of the expansion are
3142 prefix-matched against the word being completed, and the matching words
3143 become the possible completions.
3144
3145 After these matches have been generated, any shell function or command
3146 specified with the -F and -C options is invoked. When the command or
3147 function is invoked, the COMP_LINE and COMP_POINT variables are
3148 assigned values as described above under Shell Variables. If a shell
3149 function is being invoked, the COMP_WORDS and COMP_CWORD variables are
3150 also set. When the function or command is invoked, the first argument
3151 is the name of the command whose arguments are being completed, the
3152 second argument is the word being completed, and the third argument is
3153 the word preceding the word being completed on the current command
3154 line. No filtering of the generated completions against the word being
3155 completed is performed; the function or command has complete freedom in
3156 generating the matches.
3157
3158 Any function specified with -F is invoked first. The function may use
3159 any of the shell facilities, including the compgen builtin described
3160 below, to generate the matches. It must put the possible completions
3161 in the COMPREPLY array variable.
3162
3163 Next, any command specified with the -C option is invoked in an
3164 environment equivalent to command substitution. It should print a list
3165 of completions, one per line, to the standard output. Backslash may be
3166 used to escape a newline, if necessary.
3167
3168 After all of the possible completions are generated, any filter
3169 specified with the -X option is applied to the list. The filter is a
3170 pattern as used for pathname expansion; a & in the pattern is replaced
3171 with the text of the word being completed. A literal & may be escaped
3172 with a backslash; the backslash is removed before attempting a match.
3173 Any completion that matches the pattern will be removed from the list.
3174 A leading ! negates the pattern; in this case any completion not
3175 matching the pattern will be removed.
3176
3177 Finally, any prefix and suffix specified with the -P and -S options are
3178 added to each member of the completion list, and the result is returned
3179 to the readline completion code as the list of possible completions.
3180
3181 If the previously-applied actions do not generate any matches, and the
3182 -o dirnames option was supplied to complete when the compspec was
3183 defined, directory name completion is attempted.
3184
3185 If the -o plusdirs option was supplied to complete when the compspec
3186 was defined, directory name completion is attempted and any matches are
3187 added to the results of the other actions.
3188
3189 By default, if a compspec is found, whatever it generates is returned
3190 to the completion code as the full set of possible completions. The
3191 default bash completions are not attempted, and the readline default of
3192 filename completion is disabled. If the -o bashdefault option was
3193 supplied to complete when the compspec was defined, the bash default
3194 completions are attempted if the compspec generates no matches. If the
3195 -o default option was supplied to complete when the compspec was
3196 defined, readline's default completion will be performed if the
3197 compspec (and, if attempted, the default bash completions) generate no
3198 matches.
3199
3200 When a compspec indicates that directory name completion is desired,
3201 the programmable completion functions force readline to append a slash
3202 to completed names which are symbolic links to directories, subject to
3203 the value of the mark-directories readline variable, regardless of the
3204 setting of the mark-symlinked-directories readline variable.
3205
3206HISTORY
3207 When the -o history option to the set builtin is enabled, the shell
3208 provides access to the command history, the list of commands previously
3209 typed. The value of the HISTSIZE variable is used as the number of
3210 commands to save in a history list. The text of the last HISTSIZE
3211 commands (default 500) is saved. The shell stores each command in the
3212 history list prior to parameter and variable expansion (see EXPANSION
3213 above) but after history expansion is performed, subject to the values
3214 of the shell variables HISTIGNORE and HISTCONTROL.
3215
3216 On startup, the history is initialized from the file named by the
3217 variable HISTFILE (default ~/.bash_history). The file named by the
3218 value of HISTFILE is truncated, if necessary, to contain no more than
3219 the number of lines specified by the value of HISTFILESIZE. When an
3220 interactive shell exits, the last $HISTSIZE lines are copied from the
3221 history list to $HISTFILE. If the histappend shell option is enabled
3222 (see the description of shopt under SHELL BUILTIN COMMANDS below), the
3223 lines are appended to the history file, otherwise the history file is
3224 overwritten. If HISTFILE is unset, or if the history file is
3225 unwritable, the history is not saved. After saving the history, the
3226 history file is truncated to contain no more than HISTFILESIZE lines.
3227 If HISTFILESIZE is not set, no truncation is performed.
3228
3229 The builtin command fc (see SHELL BUILTIN COMMANDS below) may be used
3230 to list or edit and re-execute a portion of the history list. The
3231 history builtin may be used to display or modify the history list and
3232 manipulate the history file. When using command-line editing, search
3233 commands are available in each editing mode that provide access to the
3234 history list.
3235
3236 The shell allows control over which commands are saved on the history
3237 list. The HISTCONTROL and HISTIGNORE variables may be set to cause the
3238 shell to save only a subset of the commands entered. The cmdhist shell
3239 option, if enabled, causes the shell to attempt to save each line of a
3240 multi-line command in the same history entry, adding semicolons where
3241 necessary to preserve syntactic correctness. The lithist shell option
3242 causes the shell to save the command with embedded newlines instead of
3243 semicolons. See the description of the shopt builtin below under SHELL
3244 BUILTIN COMMANDS for information on setting and unsetting shell
3245 options.
3246
3247HISTORY EXPANSION
3248 The shell supports a history expansion feature that is similar to the
3249 history expansion in csh. This section describes what syntax features
3250 are available. This feature is enabled by default for interactive
3251 shells, and can be disabled using the +H option to the set builtin
3252 command (see SHELL BUILTIN COMMANDS below). Non-interactive shells do
3253 not perform history expansion by default.
3254
3255 History expansions introduce words from the history list into the input
3256 stream, making it easy to repeat commands, insert the arguments to a
3257 previous command into the current input line, or fix errors in previous
3258 commands quickly.
3259
3260 History expansion is performed immediately after a complete line is
3261 read, before the shell breaks it into words. It takes place in two
3262 parts. The first is to determine which line from the history list to
3263 use during substitution. The second is to select portions of that line
3264 for inclusion into the current one. The line selected from the history
3265 is the event, and the portions of that line that are acted upon are
3266 words. Various modifiers are available to manipulate the selected
3267 words. The line is broken into words in the same fashion as when
3268 reading input, so that several metacharacter-separated words surrounded
3269 by quotes are considered one word. History expansions are introduced
3270 by the appearance of the history expansion character, which is ! by
3271 default. Only backslash (\) and single quotes can quote the history
3272 expansion character.
3273
3274 Several characters inhibit history expansion if found immediately
3275 following the history expansion character, even if it is unquoted:
3276 space, tab, newline, carriage return, and =. If the extglob shell
3277 option is enabled, ( will also inhibit expansion.
3278
3279 Several shell options settable with the shopt builtin may be used to
3280 tailor the behavior of history expansion. If the histverify shell
3281 option is enabled (see the description of the shopt builtin), and
3282 readline is being used, history substitutions are not immediately
3283 passed to the shell parser. Instead, the expanded line is reloaded
3284 into the readline editing buffer for further modification. If readline
3285 is being used, and the histreedit shell option is enabled, a failed
3286 history substitution will be reloaded into the readline editing buffer
3287 for correction. The -p option to the history builtin command may be
3288 used to see what a history expansion will do before using it. The -s
3289 option to the history builtin may be used to add commands to the end of
3290 the history list without actually executing them, so that they are
3291 available for subsequent recall.
3292
3293 The shell allows control of the various characters used by the history
3294 expansion mechanism (see the description of histchars above under Shell
3295 Variables).
3296
3297 Event Designators
3298 An event designator is a reference to a command line entry in the
3299 history list.
3300
3301 ! Start a history substitution, except when followed by a blank,
3302 newline, carriage return, = or ( (when the extglob shell option
3303 is enabled using the shopt builtin).
3304 !n Refer to command line n.
3305 !-n Refer to the current command line minus n.
3306 !! Refer to the previous command. This is a synonym for `!-1'.
3307 !string
3308 Refer to the most recent command starting with string.
3309 !?string[?]
3310 Refer to the most recent command containing string. The
3311 trailing ? may be omitted if string is followed immediately by a
3312 newline.
3313 ^string1^string2^
3314 Quick substitution. Repeat the last command, replacing string1
3315 with string2. Equivalent to ``!!:s/string1/string2/'' (see
3316 Modifiers below).
3317 !# The entire command line typed so far.
3318
3319 Word Designators
3320 Word designators are used to select desired words from the event. A :
3321 separates the event specification from the word designator. It may be
3322 omitted if the word designator begins with a ^, $, *, -, or %. Words
3323 are numbered from the beginning of the line, with the first word being
3324 denoted by 0 (zero). Words are inserted into the current line
3325 separated by single spaces.
3326
3327 0 (zero)
3328 The zeroth word. For the shell, this is the command word.
3329 n The nth word.
3330 ^ The first argument. That is, word 1.
3331 $ The last argument.
3332 % The word matched by the most recent `?string?' search.
3333 x-y A range of words; `-y' abbreviates `0-y'.
3334 * All of the words but the zeroth. This is a synonym for `1-$'.
3335 It is not an error to use * if there is just one word in the
3336 event; the empty string is returned in that case.
3337 x* Abbreviates x-$.
3338 x- Abbreviates x-$ like x*, but omits the last word.
3339
3340 If a word designator is supplied without an event specification, the
3341 previous command is used as the event.
3342
3343 Modifiers
3344 After the optional word designator, there may appear a sequence of one
3345 or more of the following modifiers, each preceded by a `:'.
3346
3347 h Remove a trailing file name component, leaving only the head.
3348 t Remove all leading file name components, leaving the tail.
3349 r Remove a trailing suffix of the form .xxx, leaving the basename.
3350 e Remove all but the trailing suffix.
3351 p Print the new command but do not execute it.
3352 q Quote the substituted words, escaping further substitutions.
3353 x Quote the substituted words as with q, but break into words at
3354 blanks and newlines.
3355 s/old/new/
3356 Substitute new for the first occurrence of old in the event
3357 line. Any delimiter can be used in place of /. The final
3358 delimiter is optional if it is the last character of the event
3359 line. The delimiter may be quoted in old and new with a single
3360 backslash. If & appears in new, it is replaced by old. A
3361 single backslash will quote the &. If old is null, it is set to
3362 the last old substituted, or, if no previous history
3363 substitutions took place, the last string in a !?string[?]
3364 search.
3365 & Repeat the previous substitution.
3366 g Cause changes to be applied over the entire event line. This is
3367 used in conjunction with `:s' (e.g., `:gs/old/new/') or `:&'.
3368 If used with `:s', any delimiter can be used in place of /, and
3369 the final delimiter is optional if it is the last character of
3370 the event line. An a may be used as a synonym for g.
3371 G Apply the following `s' modifier once to each word in the event
3372 line.
3373
3374SHELL BUILTIN COMMANDS
3375 Unless otherwise noted, each builtin command documented in this section
3376 as accepting options preceded by - accepts -- to signify the end of the
3377 options. For example, the :, true, false, and test builtins do not
3378 accept options.
3379 : [arguments]
3380 No effect; the command does nothing beyond expanding arguments
3381 and performing any specified redirections. A zero exit code is
3382 returned.
3383
3384 . filename [arguments]
3385 source filename [arguments]
3386 Read and execute commands from filename in the current shell
3387 environment and return the exit status of the last command
3388 executed from filename. If filename does not contain a slash,
3389 file names in PATH are used to find the directory containing
3390 filename. The file searched for in PATH need not be executable.
3391 When bash is not in posix mode, the current directory is
3392 searched if no file is found in PATH. If the sourcepath option
3393 to the shopt builtin command is turned off, the PATH is not
3394 searched. If any arguments are supplied, they become the
3395 positional parameters when filename is executed. Otherwise the
3396 positional parameters are unchanged. The return status is the
3397 status of the last command exited within the script (0 if no
3398 commands are executed), and false if filename is not found or
3399 cannot be read.
3400
3401 alias [-p] [name[=value] ...]
3402 Alias with no arguments or with the -p option prints the list of
3403 aliases in the form alias name=value on standard output. When
3404 arguments are supplied, an alias is defined for each name whose
3405 value is given. A trailing space in value causes the next word
3406 to be checked for alias substitution when the alias is expanded.
3407 For each name in the argument list for which no value is
3408 supplied, the name and value of the alias is printed. Alias
3409 returns true unless a name is given for which no alias has been
3410 defined.
3411
3412 bg [jobspec ...]
3413 Resume each suspended job jobspec in the background, as if it
3414 had been started with &. If jobspec is not present, the shell's
3415 notion of the current job is used. bg jobspec returns 0 unless
3416 run when job control is disabled or, when run with job control
3417 enabled, any specified jobspec was not found or was started
3418 without job control.
3419
3420 bind [-m keymap] [-lpsvPSV]
3421 bind [-m keymap] [-q function] [-u function] [-r keyseq]
3422 bind [-m keymap] -f filename
3423 bind [-m keymap] -x keyseq:shell-command
3424 bind [-m keymap] keyseq:function-name
3425 bind readline-command
3426 Display current readline key and function bindings, bind a key
3427 sequence to a readline function or macro, or set a readline
3428 variable. Each non-option argument is a command as it would
3429 appear in .inputrc, but each binding or command must be passed
3430 as a separate argument; e.g., '"\C-x\C-r": re-read-init-file'.
3431 Options, if supplied, have the following meanings:
3432 -m keymap
3433 Use keymap as the keymap to be affected by the subsequent
3434 bindings. Acceptable keymap names are emacs,
3435 emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
3436 vi-command, and vi-insert. vi is equivalent to
3437 vi-command; emacs is equivalent to emacs-standard.
3438 -l List the names of all readline functions.
3439 -p Display readline function names and bindings in such a
3440 way that they can be re-read.
3441 -P List current readline function names and bindings.
3442 -v Display readline variable names and values in such a way
3443 that they can be re-read.
3444 -V List current readline variable names and values.
3445 -s Display readline key sequences bound to macros and the
3446 strings they output in such a way that they can be re-
3447 read.
3448 -S Display readline key sequences bound to macros and the
3449 strings they output.
3450 -f filename
3451 Read key bindings from filename.
3452 -q function
3453 Query about which keys invoke the named function.
3454 -u function
3455 Unbind all keys bound to the named function.
3456 -r keyseq
3457 Remove any current binding for keyseq.
3458 -x keyseq:shell-command
3459 Cause shell-command to be executed whenever keyseq is
3460 entered.
3461
3462 The return value is 0 unless an unrecognized option is given or
3463 an error occurred.
3464
3465 break [n]
3466 Exit from within a for, while, until, or select loop. If n is
3467 specified, break n levels. n must be ≥ 1. If n is greater than
3468 the number of enclosing loops, all enclosing loops are exited.
3469 The return value is 0 unless the shell is not executing a loop
3470 when break is executed.
3471
3472 builtin shell-builtin [arguments]
3473 Execute the specified shell builtin, passing it arguments, and
3474 return its exit status. This is useful when defining a function
3475 whose name is the same as a shell builtin, retaining the
3476 functionality of the builtin within the function. The cd
3477 builtin is commonly redefined this way. The return status is
3478 false if shell-builtin is not a shell builtin command.
3479
3480 cd [-L|-P] [dir]
3481 Change the current directory to dir. The variable HOME is the
3482 default dir. The variable CDPATH defines the search path for
3483 the directory containing dir. Alternative directory names in
3484 CDPATH are separated by a colon (:). A null directory name in
3485 CDPATH is the same as the current directory, i.e., ``.''. If
3486 dir begins with a slash (/), then CDPATH is not used. The -P
3487 option says to use the physical directory structure instead of
3488 following symbolic links (see also the -P option to the set
3489 builtin command); the -L option forces symbolic links to be
3490 followed. An argument of - is equivalent to $OLDPWD. If a non-
3491 empty directory name from CDPATH is used, or if - is the first
3492 argument, and the directory change is successful, the absolute
3493 pathname of the new working directory is written to the standard
3494 output. The return value is true if the directory was
3495 successfully changed; false otherwise.
3496
3497 caller [expr]
3498 Returns the context of any active subroutine call (a shell
3499 function or a script executed with the . or source builtins.
3500 Without expr, caller displays the line number and source
3501 filename of the current subroutine call. If a non-negative
3502 integer is supplied as expr, caller displays the line number,
3503 subroutine name, and source file corresponding to that position
3504 in the current execution call stack. This extra information may
3505 be used, for example, to print a stack trace. The current frame
3506 is frame 0. The return value is 0 unless the shell is not
3507 executing a subroutine call or expr does not correspond to a
3508 valid position in the call stack.
3509
3510 command [-pVv] command [arg ...]
3511 Run command with args suppressing the normal shell function
3512 lookup. Only builtin commands or commands found in the PATH are
3513 executed. If the -p option is given, the search for command is
3514 performed using a default value for PATH that is guaranteed to
3515 find all of the standard utilities. If either the -V or -v
3516 option is supplied, a description of command is printed. The -v
3517 option causes a single word indicating the command or file name
3518 used to invoke command to be displayed; the -V option produces a
3519 more verbose description. If the -V or -v option is supplied,
3520 the exit status is 0 if command was found, and 1 if not. If
3521 neither option is supplied and an error occurred or command
3522 cannot be found, the exit status is 127. Otherwise, the exit
3523 status of the command builtin is the exit status of command.
3524
3525 compgen [option] [word]
3526 Generate possible completion matches for word according to the
3527 options, which may be any option accepted by the complete
3528 builtin with the exception of -p and -r, and write the matches
3529 to the standard output. When using the -F or -C options, the
3530 various shell variables set by the programmable completion
3531 facilities, while available, will not have useful values.
3532
3533 The matches will be generated in the same way as if the
3534 programmable completion code had generated them directly from a
3535 completion specification with the same flags. If word is
3536 specified, only those completions matching word will be
3537 displayed.
3538
3539 The return value is true unless an invalid option is supplied,
3540 or no matches were generated.
3541
3542 complete [-abcdefgjksuv] [-o comp-option] [-A action] [-G globpat] [-W
3543 wordlist] [-P prefix] [-S suffix]
3544 [-X filterpat] [-F function] [-C command] name [name ...]
3545 complete -pr [name ...]
3546 Specify how arguments to each name should be completed. If the
3547 -p option is supplied, or if no options are supplied, existing
3548 completion specifications are printed in a way that allows them
3549 to be reused as input. The -r option removes a completion
3550 specification for each name, or, if no names are supplied, all
3551 completion specifications.
3552
3553 The process of applying these completion specifications when
3554 word completion is attempted is described above under
3555 Programmable Completion.
3556
3557 Other options, if specified, have the following meanings. The
3558 arguments to the -G, -W, and -X options (and, if necessary, the
3559 -P and -S options) should be quoted to protect them from
3560 expansion before the complete builtin is invoked.
3561 -o comp-option
3562 The comp-option controls several aspects of the
3563 compspec's behavior beyond the simple generation of
3564 completions. comp-option may be one of:
3565 bashdefault
3566 Perform the rest of the default bash completions
3567 if the compspec generates no matches.
3568 default Use readline's default filename completion if
3569 the compspec generates no matches.
3570 dirnames
3571 Perform directory name completion if the
3572 compspec generates no matches.
3573 filenames
3574 Tell readline that the compspec generates
3575 filenames, so it can perform any
3576 filename-specific processing (like adding a
3577 slash to directory names or suppressing trailing
3578 spaces). Intended to be used with shell
3579 functions.
3580 nospace Tell readline not to append a space (the
3581 default) to words completed at the end of the
3582 line.
3583 plusdirs
3584 After any matches defined by the compspec are
3585 generated, directory name completion is
3586 attempted and any matches are added to the
3587 results of the other actions.
3588 -A action
3589 The action may be one of the following to generate a
3590 list of possible completions:
3591 alias Alias names. May also be specified as -a.
3592 arrayvar
3593 Array variable names.
3594 binding Readline key binding names.
3595 builtin Names of shell builtin commands. May also be
3596 specified as -b.
3597 command Command names. May also be specified as -c.
3598 directory
3599 Directory names. May also be specified as -d.
3600 disabled
3601 Names of disabled shell builtins.
3602 enabled Names of enabled shell builtins.
3603 export Names of exported shell variables. May also be
3604 specified as -e.
3605 file File names. May also be specified as -f.
3606 function
3607 Names of shell functions.
3608 group Group names. May also be specified as -g.
3609 helptopic
3610 Help topics as accepted by the help builtin.
3611 hostname
3612 Hostnames, as taken from the file specified by
3613 the HOSTFILE shell variable.
3614 job Job names, if job control is active. May also
3615 be specified as -j.
3616 keyword Shell reserved words. May also be specified as
3617 -k.
3618 running Names of running jobs, if job control is active.
3619 service Service names. May also be specified as -s.
3620 setopt Valid arguments for the -o option to the set
3621 builtin.
3622 shopt Shell option names as accepted by the shopt
3623 builtin.
3624 signal Signal names.
3625 stopped Names of stopped jobs, if job control is active.
3626 user User names. May also be specified as -u.
3627 variable
3628 Names of all shell variables. May also be
3629 specified as -v.
3630 -G globpat
3631 The filename expansion pattern globpat is expanded to
3632 generate the possible completions.
3633 -W wordlist
3634 The wordlist is split using the characters in the IFS
3635 special variable as delimiters, and each resultant word
3636 is expanded. The possible completions are the members
3637 of the resultant list which match the word being
3638 completed.
3639 -C command
3640 command is executed in a subshell environment, and its
3641 output is used as the possible completions.
3642 -F function
3643 The shell function function is executed in the current
3644 shell environment. When it finishes, the possible
3645 completions are retrieved from the value of the
3646 COMPREPLY array variable.
3647 -X filterpat
3648 filterpat is a pattern as used for filename expansion.
3649 It is applied to the list of possible completions
3650 generated by the preceding options and arguments, and
3651 each completion matching filterpat is removed from the
3652 list. A leading ! in filterpat negates the pattern; in
3653 this case, any completion not matching filterpat is
3654 removed.
3655 -P prefix
3656 prefix is added at the beginning of each possible
3657 completion after all other options have been applied.
3658 -S suffix
3659 suffix is appended to each possible completion after all
3660 other options have been applied.
3661
3662 The return value is true unless an invalid option is supplied,
3663 an option other than -p or -r is supplied without a name
3664 argument, an attempt is made to remove a completion
3665 specification for a name for which no specification exists, or
3666 an error occurs adding a completion specification.
3667
3668 continue [n]
3669 Resume the next iteration of the enclosing for, while, until, or
3670 select loop. If n is specified, resume at the nth enclosing
3671 loop. n must be ≥ 1. If n is greater than the number of
3672 enclosing loops, the last enclosing loop (the ``top-level''
3673 loop) is resumed. The return value is 0 unless the shell is not
3674 executing a loop when continue is executed.
3675
3676 declare [-afFirtx] [-p] [name[=value] ...]
3677 typeset [-afFirtx] [-p] [name[=value] ...]
3678 Declare variables and/or give them attributes. If no names are
3679 given then display the values of variables. The -p option will
3680 display the attributes and values of each name. When -p is
3681 used, additional options are ignored. The -F option inhibits
3682 the display of function definitions; only the function name and
3683 attributes are printed. If the extdebug shell option is enabled
3684 using shopt, the source file name and line number where the
3685 function is defined are displayed as well. The -F option
3686 implies -f. The following options can be used to restrict
3687 output to variables with the specified attribute or to give
3688 variables attributes:
3689 -a Each name is an array variable (see Arrays above).
3690 -f Use function names only.
3691 -i The variable is treated as an integer; arithmetic
3692 evaluation (see ARITHMETIC EVALUATION ) is performed
3693 when the variable is assigned a value.
3694 -r Make names readonly. These names cannot then be assigned
3695 values by subsequent assignment statements or unset.
3696 -t Give each name the trace attribute. Traced functions
3697 inherit the DEBUG and RETURN traps from the calling
3698 shell. The trace attribute has no special meaning for
3699 variables.
3700 -x Mark names for export to subsequent commands via the
3701 environment.
3702
3703 Using `+' instead of `-' turns off the attribute instead, with
3704 the exception that +a may not be used to destroy an array
3705 variable. When used in a function, makes each name local, as
3706 with the local command. If a variable name is followed by
3707 =value, the value of the variable is set to value. The return
3708 value is 0 unless an invalid option is encountered, an attempt
3709 is made to define a function using ``-f foo=bar'', an attempt is
3710 made to assign a value to a readonly variable, an attempt is
3711 made to assign a value to an array variable without using the
3712 compound assignment syntax (see Arrays above), one of the names
3713 is not a valid shell variable name, an attempt is made to turn
3714 off readonly status for a readonly variable, an attempt is made
3715 to turn off array status for an array variable, or an attempt is
3716 made to display a non-existent function with -f.
3717
3718 dirs [-clpv] [+n] [-n]
3719 Without options, displays the list of currently remembered
3720 directories. The default display is on a single line with
3721 directory names separated by spaces. Directories are added to
3722 the list with the pushd command; the popd command removes
3723 entries from the list.
3724 +n Displays the nth entry counting from the left of the list
3725 shown by dirs when invoked without options, starting with
3726 zero.
3727 -n Displays the nth entry counting from the right of the
3728 list shown by dirs when invoked without options, starting
3729 with zero.
3730 -c Clears the directory stack by deleting all of the
3731 entries.
3732 -l Produces a longer listing; the default listing format
3733 uses a tilde to denote the home directory.
3734 -p Print the directory stack with one entry per line.
3735 -v Print the directory stack with one entry per line,
3736 prefixing each entry with its index in the stack.
3737
3738 The return value is 0 unless an invalid option is supplied or n
3739 indexes beyond the end of the directory stack.
3740
3741 disown [-ar] [-h] [jobspec ...]
3742 Without options, each jobspec is removed from the table of
3743 active jobs. If the -h option is given, each jobspec is not
3744 removed from the table, but is marked so that SIGHUP is not sent
3745 to the job if the shell receives a SIGHUP. If no jobspec is
3746 present, and neither the -a nor the -r option is supplied, the
3747 current job is used. If no jobspec is supplied, the -a option
3748 means to remove or mark all jobs; the -r option without a
3749 jobspec argument restricts operation to running jobs. The
3750 return value is 0 unless a jobspec does not specify a valid job.
3751
3752 echo [-neE] [arg ...]
3753 Output the args, separated by spaces, followed by a newline.
3754 The return status is always 0. If -n is specified, the trailing
3755 newline is suppressed. If the -e option is given,
3756 interpretation of the following backslash-escaped characters is
3757 enabled. The -E option disables the interpretation of these
3758 escape characters, even on systems where they are interpreted by
3759 default. The xpg_echo shell option may be used to dynamically
3760 determine whether or not echo expands these escape characters by
3761 default. echo does not interpret -- to mean the end of options.
3762 echo interprets the following escape sequences:
3763 \a alert (bell)
3764 \b backspace
3765 \c suppress trailing newline
3766 \e an escape character
3767 \f form feed
3768 \n new line
3769 \r carriage return
3770 \t horizontal tab
3771 \v vertical tab
3772 \\ backslash
3773 \0nnn the eight-bit character whose value is the octal value
3774 nnn (zero to three octal digits)
3775 \xHH the eight-bit character whose value is the hexadecimal
3776 value HH (one or two hex digits)
3777
3778 enable [-adnps] [-f filename] [name ...]
3779 Enable and disable builtin shell commands. Disabling a builtin
3780 allows a disk command which has the same name as a shell builtin
3781 to be executed without specifying a full pathname, even though
3782 the shell normally searches for builtins before disk commands.
3783 If -n is used, each name is disabled; otherwise, names are
3784 enabled. For example, to use the test binary found via the PATH
3785 instead of the shell builtin version, run ``enable -n test''.
3786 The -f option means to load the new builtin command name from
3787 shared object filename, on systems that support dynamic loading.
3788 The -d option will delete a builtin previously loaded with -f.
3789 If no name arguments are given, or if the -p option is supplied,
3790 a list of shell builtins is printed. With no other option
3791 arguments, the list consists of all enabled shell builtins. If
3792 -n is supplied, only disabled builtins are printed. If -a is
3793 supplied, the list printed includes all builtins, with an
3794 indication of whether or not each is enabled. If -s is
3795 supplied, the output is restricted to the POSIX special
3796 builtins. The return value is 0 unless a name is not a shell
3797 builtin or there is an error loading a new builtin from a shared
3798 object.
3799
3800 eval [arg ...]
3801 The args are read and concatenated together into a single
3802 command. This command is then read and executed by the shell,
3803 and its exit status is returned as the value of eval. If there
3804 are no args, or only null arguments, eval returns 0.
3805
3806 exec [-cl] [-a name] [command [arguments]]
3807 If command is specified, it replaces the shell. No new process
3808 is created. The arguments become the arguments to command. If
3809 the -l option is supplied, the shell places a dash at the
3810 beginning of the zeroth arg passed to command. This is what
3811 login(1) does. The -c option causes command to be executed with
3812 an empty environment. If -a is supplied, the shell passes name
3813 as the zeroth argument to the executed command. If command
3814 cannot be executed for some reason, a non-interactive shell
3815 exits, unless the shell option execfail is enabled, in which
3816 case it returns failure. An interactive shell returns failure
3817 if the file cannot be executed. If command is not specified,
3818 any redirections take effect in the current shell, and the
3819 return status is 0. If there is a redirection error, the return
3820 status is 1.
3821
3822 exit [n]
3823 Cause the shell to exit with a status of n. If n is omitted,
3824 the exit status is that of the last command executed. A trap on
3825 EXIT is executed before the shell terminates.
3826
3827 export [-fn] [name[=word]] ...
3828 export -p
3829 The supplied names are marked for automatic export to the
3830 environment of subsequently executed commands. If the -f option
3831 is given, the names refer to functions. If no names are given,
3832 or if the -p option is supplied, a list of all names that are
3833 exported in this shell is printed. The -n option causes the
3834 export property to be removed from each name. If a variable
3835 name is followed by =word, the value of the variable is set to
3836 word. export returns an exit status of 0 unless an invalid
3837 option is encountered, one of the names is not a valid shell
3838 variable name, or -f is supplied with a name that is not a
3839 function.
3840
3841 fc [-e ename] [-nlr] [first] [last]
3842 fc -s [pat=rep] [cmd]
3843 Fix Command. In the first form, a range of commands from first
3844 to last is selected from the history list. First and last may
3845 be specified as a string (to locate the last command beginning
3846 with that string) or as a number (an index into the history
3847 list, where a negative number is used as an offset from the
3848 current command number). If last is not specified it is set to
3849 the current command for listing (so that ``fc -l -10'' prints
3850 the last 10 commands) and to first otherwise. If first is not
3851 specified it is set to the previous command for editing and -16
3852 for listing.
3853
3854 The -n option suppresses the command numbers when listing. The
3855 -r option reverses the order of the commands. If the -l option
3856 is given, the commands are listed on standard output.
3857 Otherwise, the editor given by ename is invoked on a file
3858 containing those commands. If ename is not given, the value of
3859 the FCEDIT variable is used, and the value of EDITOR if FCEDIT
3860 is not set. If neither variable is set, vi is used. When
3861 editing is complete, the edited commands are echoed and
3862 executed.
3863
3864 In the second form, command is re-executed after each instance
3865 of pat is replaced by rep. A useful alias to use with this is
3866 ``r="fc -s"'', so that typing ``r cc'' runs the last command
3867 beginning with ``cc'' and typing ``r'' re-executes the last
3868 command.
3869
3870 If the first form is used, the return value is 0 unless an
3871 invalid option is encountered or first or last specify history
3872 lines out of range. If the -e option is supplied, the return
3873 value is the value of the last command executed or failure if an
3874 error occurs with the temporary file of commands. If the second
3875 form is used, the return status is that of the command re-
3876 executed, unless cmd does not specify a valid history line, in
3877 which case fc returns failure.
3878
3879 fg [jobspec]
3880 Resume jobspec in the foreground, and make it the current job.
3881 If jobspec is not present, the shell's notion of the current job
3882 is used. The return value is that of the command placed into
3883 the foreground, or failure if run when job control is disabled
3884 or, when run with job control enabled, if jobspec does not
3885 specify a valid job or jobspec specifies a job that was started
3886 without job control.
3887
3888 getopts optstring name [args]
3889 getopts is used by shell procedures to parse positional
3890 parameters. optstring contains the option characters to be
3891 recognized; if a character is followed by a colon, the option is
3892 expected to have an argument, which should be separated from it
3893 by white space. The colon and question mark characters may not
3894 be used as option characters. Each time it is invoked, getopts
3895 places the next option in the shell variable name, initializing
3896 name if it does not exist, and the index of the next argument to
3897 be processed into the variable OPTIND. OPTIND is initialized to
3898 1 each time the shell or a shell script is invoked. When an
3899 option requires an argument, getopts places that argument into
3900 the variable OPTARG. The shell does not reset OPTIND
3901 automatically; it must be manually reset between multiple calls
3902 to getopts within the same shell invocation if a new set of
3903 parameters is to be used.
3904
3905 When the end of options is encountered, getopts exits with a
3906 return value greater than zero. OPTIND is set to the index of
3907 the first non-option argument, and name is set to ?.
3908
3909 getopts normally parses the positional parameters, but if more
3910 arguments are given in args, getopts parses those instead.
3911
3912 getopts can report errors in two ways. If the first character
3913 of optstring is a colon, silent error reporting is used. In
3914 normal operation diagnostic messages are printed when invalid
3915 options or missing option arguments are encountered. If the
3916 variable OPTERR is set to 0, no error messages will be
3917 displayed, even if the first character of optstring is not a
3918 colon.
3919
3920 If an invalid option is seen, getopts places ? into name and, if
3921 not silent, prints an error message and unsets OPTARG. If
3922 getopts is silent, the option character found is placed in
3923 OPTARG and no diagnostic message is printed.
3924
3925 If a required argument is not found, and getopts is not silent,
3926 a question mark (?) is placed in name, OPTARG is unset, and a
3927 diagnostic message is printed. If getopts is silent, then a
3928 colon (:) is placed in name and OPTARG is set to the option
3929 character found.
3930
3931 getopts returns true if an option, specified or unspecified, is
3932 found. It returns false if the end of options is encountered or
3933 an error occurs.
3934
3935 hash [-lr] [-p filename] [-dt] [name]
3936 For each name, the full file name of the command is determined
3937 by searching the directories in $PATH and remembered. If the -p
3938 option is supplied, no path search is performed, and filename is
3939 used as the full file name of the command. The -r option causes
3940 the shell to forget all remembered locations. The -d option
3941 causes the shell to forget the remembered location of each name.
3942 If the -t option is supplied, the full pathname to which each
3943 name corresponds is printed. If multiple name arguments are
3944 supplied with -t, the name is printed before the hashed full
3945 pathname. The -l option causes output to be displayed in a
3946 format that may be reused as input. If no arguments are given,
3947 or if only -l is supplied, information about remembered commands
3948 is printed. The return status is true unless a name is not
3949 found or an invalid option is supplied.
3950
3951 help [-s] [pattern]
3952 Display helpful information about builtin commands. If pattern
3953 is specified, help gives detailed help on all commands matching
3954 pattern; otherwise help for all the builtins and shell control
3955 structures is printed. The -s option restricts the information
3956 displayed to a short usage synopsis. The return status is 0
3957 unless no command matches pattern.
3958
3959 history [n]
3960 history -c
3961 history -d offset
3962 history -anrw [filename]
3963 history -p arg [arg ...]
3964 history -s arg [arg ...]
3965 With no options, display the command history list with line
3966 numbers. Lines listed with a * have been modified. An argument
3967 of n lists only the last n lines. If the shell variable
3968 HISTTIMEFORMAT is set and not null, it is used as a format
3969 string for strftime(3) to display the time stamp associated with
3970 each displayed history entry. No intervening blank is printed
3971 between the formatted time stamp and the history line. If
3972 filename is supplied, it is used as the name of the history
3973 file; if not, the value of HISTFILE is used. Options, if
3974 supplied, have the following meanings:
3975 -c Clear the history list by deleting all the entries.
3976 -d offset
3977 Delete the history entry at position offset.
3978 -a Append the ``new'' history lines (history lines entered
3979 since the beginning of the current bash session) to the
3980 history file.
3981 -n Read the history lines not already read from the history
3982 file into the current history list. These are lines
3983 appended to the history file since the beginning of the
3984 current bash session.
3985 -r Read the contents of the history file and use them as the
3986 current history.
3987 -w Write the current history to the history file,
3988 overwriting the history file's contents.
3989 -p Perform history substitution on the following args and
3990 display the result on the standard output. Does not
3991 store the results in the history list. Each arg must be
3992 quoted to disable normal history expansion.
3993 -s Store the args in the history list as a single entry.
3994 The last command in the history list is removed before
3995 the args are added.
3996
3997 If the HISTTIMEFORMAT is set, the time stamp information
3998 associated with each history entry is written to the history
3999 file. The return value is 0 unless an invalid option is
4000 encountered, an error occurs while reading or writing the
4001 history file, an invalid offset is supplied as an argument to
4002 -d, or the history expansion supplied as an argument to -p
4003 fails.
4004
4005 jobs [-lnprs] [ jobspec ... ]
4006 jobs -x command [ args ... ]
4007 The first form lists the active jobs. The options have the
4008 following meanings:
4009 -l List process IDs in addition to the normal information.
4010 -p List only the process ID of the job's process group
4011 leader.
4012 -n Display information only about jobs that have changed
4013 status since the user was last notified of their status.
4014 -r Restrict output to running jobs.
4015 -s Restrict output to stopped jobs.
4016
4017 If jobspec is given, output is restricted to information about
4018 that job. The return status is 0 unless an invalid option is
4019 encountered or an invalid jobspec is supplied.
4020
4021 If the -x option is supplied, jobs replaces any jobspec found in
4022 command or args with the corresponding process group ID, and
4023 executes command passing it args, returning its exit status.
4024
4025 kill [-s sigspec | -n signum | -sigspec] [pid | jobspec] ...
4026 kill -l [sigspec | exit_status]
4027 Send the signal named by sigspec or signum to the processes
4028 named by pid or jobspec. sigspec is either a case-insensitive
4029 signal name such as SIGKILL (with or without the SIG prefix) or
4030 a signal number; signum is a signal number. If sigspec is not
4031 present, then SIGTERM is assumed. An argument of -l lists the
4032 signal names. If any arguments are supplied when -l is given,
4033 the names of the signals corresponding to the arguments are
4034 listed, and the return status is 0. The exit_status argument to
4035 -l is a number specifying either a signal number or the exit
4036 status of a process terminated by a signal. kill returns true
4037 if at least one signal was successfully sent, or false if an
4038 error occurs or an invalid option is encountered.
4039
4040 let arg [arg ...]
4041 Each arg is an arithmetic expression to be evaluated (see
4042 ARITHMETIC EVALUATION). If the last arg evaluates to 0, let
4043 returns 1; 0 is returned otherwise.
4044
4045 local [option] [name[=value] ...]
4046 For each argument, a local variable named name is created, and
4047 assigned value. The option can be any of the options accepted
4048 by declare. When local is used within a function, it causes the
4049 variable name to have a visible scope restricted to that
4050 function and its children. With no operands, local writes a
4051 list of local variables to the standard output. It is an error
4052 to use local when not within a function. The return status is 0
4053 unless local is used outside a function, an invalid name is
4054 supplied, or name is a readonly variable.
4055
4056 logout Exit a login shell.
4057
4058 popd [-n] [+n] [-n]
4059 Removes entries from the directory stack. With no arguments,
4060 removes the top directory from the stack, and performs a cd to
4061 the new top directory. Arguments, if supplied, have the
4062 following meanings:
4063 +n Removes the nth entry counting from the left of the list
4064 shown by dirs, starting with zero. For example: ``popd
4065 +0'' removes the first directory, ``popd +1'' the second.
4066 -n Removes the nth entry counting from the right of the list
4067 shown by dirs, starting with zero. For example: ``popd
4068 -0'' removes the last directory, ``popd -1'' the next to
4069 last.
4070 -n Suppresses the normal change of directory when removing
4071 directories from the stack, so that only the stack is
4072 manipulated.
4073
4074 If the popd command is successful, a dirs is performed as well,
4075 and the return status is 0. popd returns false if an invalid
4076 option is encountered, the directory stack is empty, a non-
4077 existent directory stack entry is specified, or the directory
4078 change fails.
4079
4080 printf [-v var] format [arguments]
4081 Write the formatted arguments to the standard output under the
4082 control of the format. The format is a character string which
4083 contains three types of objects: plain characters, which are
4084 simply copied to standard output, character escape sequences,
4085 which are converted and copied to the standard output, and
4086 format specifications, each of which causes printing of the next
4087 successive argument. In addition to the standard printf(1)
4088 formats, %b causes printf to expand backslash escape sequences
4089 in the corresponding argument (except that \c terminates output,
4090 backslashes in \', \", and \? are not removed, and octal escapes
4091 beginning with \0 may contain up to four digits), and %q causes
4092 printf to output the corresponding argument in a format that can
4093 be reused as shell input.
4094
4095 The -v option causes the output to be assigned to the variable
4096 var rather than being printed to the standard output.
4097
4098 The format is reused as necessary to consume all of the
4099 arguments. If the format requires more arguments than are
4100 supplied, the extra format specifications behave as if a zero
4101 value or null string, as appropriate, had been supplied. The
4102 return value is zero on success, non-zero on failure.
4103
4104 pushd [-n] [dir]
4105 pushd [-n] [+n] [-n]
4106 Adds a directory to the top of the directory stack, or rotates
4107 the stack, making the new top of the stack the current working
4108 directory. With no arguments, exchanges the top two directories
4109 and returns 0, unless the directory stack is empty. Arguments,
4110 if supplied, have the following meanings:
4111 +n Rotates the stack so that the nth directory (counting
4112 from the left of the list shown by dirs, starting with
4113 zero) is at the top.
4114 -n Rotates the stack so that the nth directory (counting
4115 from the right of the list shown by dirs, starting with
4116 zero) is at the top.
4117 -n Suppresses the normal change of directory when adding
4118 directories to the stack, so that only the stack is
4119 manipulated.
4120 dir Adds dir to the directory stack at the top, making it the
4121 new current working directory.
4122
4123 If the pushd command is successful, a dirs is performed as well.
4124 If the first form is used, pushd returns 0 unless the cd to dir
4125 fails. With the second form, pushd returns 0 unless the
4126 directory stack is empty, a non-existent directory stack element
4127 is specified, or the directory change to the specified new
4128 current directory fails.
4129
4130 pwd [-LP]
4131 Print the absolute pathname of the current working directory.
4132 The pathname printed contains no symbolic links if the -P option
4133 is supplied or the -o physical option to the set builtin command
4134 is enabled. If the -L option is used, the pathname printed may
4135 contain symbolic links. The return status is 0 unless an error
4136 occurs while reading the name of the current directory or an
4137 invalid option is supplied.
4138
4139 read [-ers] [-u fd] [-t timeout] [-a aname] [-p prompt] [-n nchars] [-d
4140 delim] [name ...]
4141 One line is read from the standard input, or from the file
4142 descriptor fd supplied as an argument to the -u option, and the
4143 first word is assigned to the first name, the second word to the
4144 second name, and so on, with leftover words and their
4145 intervening separators assigned to the last name. If there are
4146 fewer words read from the input stream than names, the remaining
4147 names are assigned empty values. The characters in IFS are used
4148 to split the line into words. The backslash character (\) may
4149 be used to remove any special meaning for the next character
4150 read and for line continuation. Options, if supplied, have the
4151 following meanings:
4152 -a aname
4153 The words are assigned to sequential indices of the array
4154 variable aname, starting at 0. aname is unset before any
4155 new values are assigned. Other name arguments are
4156 ignored.
4157 -d delim
4158 The first character of delim is used to terminate the
4159 input line, rather than newline.
4160 -e If the standard input is coming from a terminal, readline
4161 (see READLINE above) is used to obtain the line.
4162 -n nchars
4163 read returns after reading nchars characters rather than
4164 waiting for a complete line of input.
4165 -p prompt
4166 Display prompt on standard error, without a trailing
4167 newline, before attempting to read any input. The prompt
4168 is displayed only if input is coming from a terminal.
4169 -r Backslash does not act as an escape character. The
4170 backslash is considered to be part of the line. In
4171 particular, a backslash-newline pair may not be used as a
4172 line continuation.
4173 -s Silent mode. If input is coming from a terminal,
4174 characters are not echoed.
4175 -t timeout
4176 Cause read to time out and return failure if a complete
4177 line of input is not read within timeout seconds. This
4178 option has no effect if read is not reading input from
4179 the terminal or a pipe.
4180 -u fd Read input from file descriptor fd.
4181
4182 If no names are supplied, the line read is assigned to the
4183 variable REPLY. The return code is zero, unless end-of-file is
4184 encountered, read times out, or an invalid file descriptor is
4185 supplied as the argument to -u.
4186
4187 readonly [-apf] [name[=word] ...]
4188 The given names are marked readonly; the values of these names
4189 may not be changed by subsequent assignment. If the -f option
4190 is supplied, the functions corresponding to the names are so
4191 marked. The -a option restricts the variables to arrays. If no
4192 name arguments are given, or if the -p option is supplied, a
4193 list of all readonly names is printed. The -p option causes
4194 output to be displayed in a format that may be reused as input.
4195 If a variable name is followed by =word, the value of the
4196 variable is set to word. The return status is 0 unless an
4197 invalid option is encountered, one of the names is not a valid
4198 shell variable name, or -f is supplied with a name that is not a
4199 function.
4200
4201 return [n]
4202 Causes a function to exit with the return value specified by n.
4203 If n is omitted, the return status is that of the last command
4204 executed in the function body. If used outside a function, but
4205 during execution of a script by the . (source) command, it
4206 causes the shell to stop executing that script and return either
4207 n or the exit status of the last command executed within the
4208 script as the exit status of the script. If used outside a
4209 function and not during execution of a script by ., the return
4210 status is false. Any command associated with the RETURN trap is
4211 executed before execution resumes after the function or script.
4212
4213 set [--abefhkmnptuvxBCHP] [-o option] [arg ...]
4214 Without options, the name and value of each shell variable are
4215 displayed in a format that can be reused as input for setting or
4216 resetting the currently-set variables. Read-only variables
4217 cannot be reset. In posix mode, only shell variables are
4218 listed. The output is sorted according to the current locale.
4219 When options are specified, they set or unset shell attributes.
4220 Any arguments remaining after the options are processed are
4221 treated as values for the positional parameters and are
4222 assigned, in order, to $1, $2, ... $n. Options, if specified,
4223 have the following meanings:
4224 -a Automatically mark variables and functions which are
4225 modified or created for export to the environment of
4226 subsequent commands.
4227 -b Report the status of terminated background jobs
4228 immediately, rather than before the next primary prompt.
4229 This is effective only when job control is enabled.
4230 -e Exit immediately if a simple command (see SHELL GRAMMAR
4231 above) exits with a non-zero status. The shell does not
4232 exit if the command that fails is part of the command
4233 list immediately following a while or until keyword,
4234 part of the test in an if statement, part of a && or ⎪⎪
4235 list, or if the command's return value is being inverted
4236 via !. A trap on ERR, if set, is executed before the
4237 shell exits.
4238 -f Disable pathname expansion.
4239 -h Remember the location of commands as they are looked up
4240 for execution. This is enabled by default.
4241 -k All arguments in the form of assignment statements are
4242 placed in the environment for a command, not just those
4243 that precede the command name.
4244 -m Monitor mode. Job control is enabled. This option is
4245 on by default for interactive shells on systems that
4246 support it (see JOB CONTROL above). Background
4247 processes run in a separate process group and a line
4248 containing their exit status is printed upon their
4249 completion.
4250 -n Read commands but do not execute them. This may be used
4251 to check a shell script for syntax errors. This is
4252 ignored by interactive shells.
4253 -o option-name
4254 The option-name can be one of the following:
4255 allexport
4256 Same as -a.
4257 braceexpand
4258 Same as -B.
4259 emacs Use an emacs-style command line editing
4260 interface. This is enabled by default when the
4261 shell is interactive, unless the shell is
4262 started with the --noediting option.
4263 errtrace
4264 Same as -E.
4265 functrace
4266 Same as -T.
4267 errexit Same as -e.
4268 hashall Same as -h.
4269 histexpand
4270 Same as -H.
4271 history Enable command history, as described above under
4272 HISTORY. This option is on by default in
4273 interactive shells.
4274 ignoreeof
4275 The effect is as if the shell command
4276 ``IGNOREEOF=10'' had been executed (see Shell
4277 Variables above).
4278 keyword Same as -k.
4279 monitor Same as -m.
4280 noclobber
4281 Same as -C.
4282 noexec Same as -n.
4283 noglob Same as -f. nolog Currently ignored.
4284 notify Same as -b.
4285 nounset Same as -u.
4286 onecmd Same as -t.
4287 physical
4288 Same as -P.
4289 pipefail
4290 If set, the return value of a pipeline is the
4291 value of the last (rightmost) command to exit
4292 with a non-zero status, or zero if all commands
4293 in the pipeline exit successfully. This option
4294 is disabled by default.
4295 posix Change the behavior of bash where the default
4296 operation differs from the POSIX standard to
4297 match the standard (posix mode).
4298 privileged
4299 Same as -p.
4300 verbose Same as -v.
4301 vi Use a vi-style command line editing interface.
4302 xtrace Same as -x.
4303 If -o is supplied with no option-name, the values of the
4304 current options are printed. If +o is supplied with no
4305 option-name, a series of set commands to recreate the
4306 current option settings is displayed on the standard
4307 output.
4308 -p Turn on privileged mode. In this mode, the $ENV and
4309 $BASH_ENV files are not processed, shell functions are
4310 not inherited from the environment, and the SHELLOPTS
4311 variable, if it appears in the environment, is ignored.
4312 If the shell is started with the effective user (group)
4313 id not equal to the real user (group) id, and the -p
4314 option is not supplied, these actions are taken and the
4315 effective user id is set to the real user id. If the -p
4316 option is supplied at startup, the effective user id is
4317 not reset. Turning this option off causes the effective
4318 user and group ids to be set to the real user and group
4319 ids.
4320 -t Exit after reading and executing one command.
4321 -u Treat unset variables as an error when performing
4322 parameter expansion. If expansion is attempted on an
4323 unset variable, the shell prints an error message, and,
4324 if not interactive, exits with a non-zero status.
4325 -v Print shell input lines as they are read.
4326 -x After expanding each simple command, for command, case
4327 command, select command, or arithmetic for command,
4328 display the expanded value of PS4, followed by the
4329 command and its expanded arguments or associated word
4330 list.
4331 -B The shell performs brace expansion (see Brace Expansion
4332 above). This is on by default.
4333 -C If set, bash does not overwrite an existing file with
4334 the >, >&, and <> redirection operators. This may be
4335 overridden when creating output files by using the
4336 redirection operator >| instead of >.
4337 -E If set, any trap on ERR is inherited by shell functions,
4338 command substitutions, and commands executed in a
4339 subshell environment. The ERR trap is normally not
4340 inherited in such cases.
4341 -H Enable ! style history substitution. This option is on
4342 by default when the shell is interactive.
4343 -P If set, the shell does not follow symbolic links when
4344 executing commands such as cd that change the current
4345 working directory. It uses the physical directory
4346 structure instead. By default, bash follows the logical
4347 chain of directories when performing commands which
4348 change the current directory.
4349 -T If set, any traps on DEBUG and RETURN are inherited by
4350 shell functions, command substitutions, and commands
4351 executed in a subshell environment. The DEBUG and
4352 RETURN traps are normally not inherited in such cases.
4353 -- If no arguments follow this option, then the positional
4354 parameters are unset. Otherwise, the positional
4355 parameters are set to the args, even if some of them
4356 begin with a -.
4357 - Signal the end of options, cause all remaining args to
4358 be assigned to the positional parameters. The -x and -v
4359 options are turned off. If there are no args, the
4360 positional parameters remain unchanged.
4361
4362 The options are off by default unless otherwise noted. Using +
4363 rather than - causes these options to be turned off. The
4364 options can also be specified as arguments to an invocation of
4365 the shell. The current set of options may be found in $-. The
4366 return status is always true unless an invalid option is
4367 encountered.
4368
4369 shift [n]
4370 The positional parameters from n+1 ... are renamed to $1 ....
4371 Parameters represented by the numbers $# down to $#-n+1 are
4372 unset. n must be a non-negative number less than or equal to
4373 $#. If n is 0, no parameters are changed. If n is not given,
4374 it is assumed to be 1. If n is greater than $#, the positional
4375 parameters are not changed. The return status is greater than
4376 zero if n is greater than $# or less than zero; otherwise 0.
4377
4378 shopt [-pqsu] [-o] [optname ...]
4379 Toggle the values of variables controlling optional shell
4380 behavior. With no options, or with the -p option, a list of all
4381 settable options is displayed, with an indication of whether or
4382 not each is set. The -p option causes output to be displayed in
4383 a form that may be reused as input. Other options have the
4384 following meanings:
4385 -s Enable (set) each optname.
4386 -u Disable (unset) each optname.
4387 -q Suppresses normal output (quiet mode); the return status
4388 indicates whether the optname is set or unset. If
4389 multiple optname arguments are given with -q, the return
4390 status is zero if all optnames are enabled; non-zero
4391 otherwise.
4392 -o Restricts the values of optname to be those defined for
4393 the -o option to the set builtin.
4394
4395 If either -s or -u is used with no optname arguments, the
4396 display is limited to those options which are set or unset,
4397 respectively. Unless otherwise noted, the shopt options are
4398 disabled (unset) by default.
4399
4400 The return status when listing options is zero if all optnames
4401 are enabled, non-zero otherwise. When setting or unsetting
4402 options, the return status is zero unless an optname is not a
4403 valid shell option.
4404
4405 The list of shopt options is:
4406
4407 cdable_vars
4408 If set, an argument to the cd builtin command that is
4409 not a directory is assumed to be the name of a variable
4410 whose value is the directory to change to.
4411 cdspell If set, minor errors in the spelling of a directory
4412 component in a cd command will be corrected. The errors
4413 checked for are transposed characters, a missing
4414 character, and one character too many. If a correction
4415 is found, the corrected file name is printed, and the
4416 command proceeds. This option is only used by
4417 interactive shells.
4418 checkhash
4419 If set, bash checks that a command found in the hash
4420 table exists before trying to execute it. If a hashed
4421 command no longer exists, a normal path search is
4422 performed.
4423 checkwinsize
4424 If set, bash checks the window size after each command
4425 and, if necessary, updates the values of LINES and
4426 COLUMNS.
4427 cmdhist If set, bash attempts to save all lines of a multiple-
4428 line command in the same history entry. This allows
4429 easy re-editing of multi-line commands.
4430 compat31
4431 If set, bash changes its behavior to that of version 3.1
4432 with respect to quoted arguments to the conditional
4433 command's =~ operator.
4434 dotglob If set, bash includes filenames beginning with a `.' in
4435 the results of pathname expansion.
4436 execfail
4437 If set, a non-interactive shell will not exit if it
4438 cannot execute the file specified as an argument to the
4439 exec builtin command. An interactive shell does not
4440 exit if exec fails.
4441 expand_aliases
4442 If set, aliases are expanded as described above under
4443 ALIASES. This option is enabled by default for
4444 interactive shells.
4445 extdebug
4446 If set, behavior intended for use by debuggers is
4447 enabled:
4448 1. The -F option to the declare builtin displays the
4449 source file name and line number corresponding to
4450 each function name supplied as an argument.
4451 2. If the command run by the DEBUG trap returns a
4452 non-zero value, the next command is skipped and
4453 not executed.
4454 3. If the command run by the DEBUG trap returns a
4455 value of 2, and the shell is executing in a
4456 subroutine (a shell function or a shell script
4457 executed by the . or source builtins), a call to
4458 return is simulated.
4459 4. BASH_ARGC and BASH_ARGV are updated as described
4460 in their descriptions above.
4461 5. Function tracing is enabled: command
4462 substitution, shell functions, and subshells
4463 invoked with ( command ) inherit the DEBUG and
4464 RETURN traps.
4465 6. Error tracing is enabled: command substitution,
4466 shell functions, and subshells invoked with (
4467 command ) inherit the ERROR trap.
4468 extglob If set, the extended pattern matching features described
4469 above under Pathname Expansion are enabled.
4470 extquote
4471 If set, $'string' and $"string" quoting is performed
4472 within ${parameter} expansions enclosed in double
4473 quotes. This option is enabled by default.
4474 failglob
4475 If set, patterns which fail to match filenames during
4476 pathname expansion result in an expansion error.
4477 force_fignore
4478 If set, the suffixes specified by the FIGNORE shell
4479 variable cause words to be ignored when performing word
4480 completion even if the ignored words are the only
4481 possible completions. See SHELL VARIABLES above for a
4482 description of FIGNORE. This option is enabled by
4483 default.
4484 gnu_errfmt
4485 If set, shell error messages are written in the standard
4486 GNU error message format.
4487 histappend
4488 If set, the history list is appended to the file named
4489 by the value of the HISTFILE variable when the shell
4490 exits, rather than overwriting the file.
4491 histreedit
4492 If set, and readline is being used, a user is given the
4493 opportunity to re-edit a failed history substitution.
4494 histverify
4495 If set, and readline is being used, the results of
4496 history substitution are not immediately passed to the
4497 shell parser. Instead, the resulting line is loaded
4498 into the readline editing buffer, allowing further
4499 modification.
4500 hostcomplete
4501 If set, and readline is being used, bash will attempt to
4502 perform hostname completion when a word containing a @
4503 is being completed (see Completing under READLINE
4504 above). This is enabled by default.
4505 huponexit
4506 If set, bash will send SIGHUP to all jobs when an
4507 interactive login shell exits.
4508 interactive_comments
4509 If set, allow a word beginning with # to cause that word
4510 and all remaining characters on that line to be ignored
4511 in an interactive shell (see COMMENTS above). This
4512 option is enabled by default.
4513 lithist If set, and the cmdhist option is enabled, multi-line
4514 commands are saved to the history with embedded newlines
4515 rather than using semicolon separators where possible.
4516 login_shell
4517 The shell sets this option if it is started as a login
4518 shell (see INVOCATION above). The value may not be
4519 changed.
4520 mailwarn
4521 If set, and a file that bash is checking for mail has
4522 been accessed since the last time it was checked, the
4523 message ``The mail in mailfile has been read'' is
4524 displayed.
4525 no_empty_cmd_completion
4526 If set, and readline is being used, bash will not
4527 attempt to search the PATH for possible completions when
4528 completion is attempted on an empty line.
4529 nocaseglob
4530 If set, bash matches filenames in a case-insensitive
4531 fashion when performing pathname expansion (see Pathname
4532 Expansion above).
4533 nocasematch
4534 If set, bash matches patterns in a case-insensitive
4535 fashion when performing matching while executing case or
4536 [[ conditional commands.
4537 nullglob
4538 If set, bash allows patterns which match no files (see
4539 Pathname Expansion above) to expand to a null string,
4540 rather than themselves.
4541 progcomp
4542 If set, the programmable completion facilities (see
4543 Programmable Completion above) are enabled. This option
4544 is enabled by default.
4545 promptvars
4546 If set, prompt strings undergo parameter expansion,
4547 command substitution, arithmetic expansion, and quote
4548 removal after being expanded as described in PROMPTING
4549 above. This option is enabled by default.
4550 restricted_shell
4551 The shell sets this option if it is started in
4552 restricted mode (see RESTRICTED SHELL below). The value
4553 may not be changed. This is not reset when the startup
4554 files are executed, allowing the startup files to
4555 discover whether or not a shell is restricted.
4556 shift_verbose
4557 If set, the shift builtin prints an error message when
4558 the shift count exceeds the number of positional
4559 parameters.
4560 sourcepath
4561 If set, the source (.) builtin uses the value of PATH to
4562 find the directory containing the file supplied as an
4563 argument. This option is enabled by default.
4564 xpg_echo
4565 If set, the echo builtin expands backslash-escape
4566 sequences by default.
4567 suspend [-f]
4568 Suspend the execution of this shell until it receives a SIGCONT
4569 signal. The -f option says not to complain if this is a login
4570 shell; just suspend anyway. The return status is 0 unless the
4571 shell is a login shell and -f is not supplied, or if job control
4572 is not enabled.
4573 test expr
4574 [ expr ]
4575 Return a status of 0 or 1 depending on the evaluation of the
4576 conditional expression expr. Each operator and operand must be
4577 a separate argument. Expressions are composed of the primaries
4578 described above under CONDITIONAL EXPRESSIONS. test does not
4579 accept any options, nor does it accept and ignore an argument of
4580 -- as signifying the end of options.
4581
4582 Expressions may be combined using the following operators,
4583 listed in decreasing order of precedence.
4584 ! expr True if expr is false.
4585 ( expr )
4586 Returns the value of expr. This may be used to override
4587 the normal precedence of operators.
4588 expr1 -a expr2
4589 True if both expr1 and expr2 are true.
4590 expr1 -o expr2
4591 True if either expr1 or expr2 is true.
4592
4593 test and [ evaluate conditional expressions using a set of rules
4594 based on the number of arguments.
4595
4596 0 arguments
4597 The expression is false.
4598 1 argument
4599 The expression is true if and only if the argument is not
4600 null.
4601 2 arguments
4602 If the first argument is !, the expression is true if and
4603 only if the second argument is null. If the first
4604 argument is one of the unary conditional operators listed
4605 above under CONDITIONAL EXPRESSIONS, the expression is
4606 true if the unary test is true. If the first argument is
4607 not a valid unary conditional operator, the expression is
4608 false.
4609 3 arguments
4610 If the second argument is one of the binary conditional
4611 operators listed above under CONDITIONAL EXPRESSIONS, the
4612 result of the expression is the result of the binary test
4613 using the first and third arguments as operands. If the
4614 first argument is !, the value is the negation of the
4615 two-argument test using the second and third arguments.
4616 If the first argument is exactly ( and the third argument
4617 is exactly ), the result is the one-argument test of the
4618 second argument. Otherwise, the expression is false.
4619 The -a and -o operators are considered binary operators
4620 in this case.
4621 4 arguments
4622 If the first argument is !, the result is the negation of
4623 the three-argument expression composed of the remaining
4624 arguments. Otherwise, the expression is parsed and
4625 evaluated according to precedence using the rules listed
4626 above.
4627 5 or more arguments
4628 The expression is parsed and evaluated according to
4629 precedence using the rules listed above.
4630
4631 times Print the accumulated user and system times for the shell and
4632 for processes run from the shell. The return status is 0.
4633
4634 trap [-lp] [[arg] sigspec ...]
4635 The command arg is to be read and executed when the shell
4636 receives signal(s) sigspec. If arg is absent (and there is a
4637 single sigspec) or -, each specified signal is reset to its
4638 original disposition (the value it had upon entrance to the
4639 shell). If arg is the null string the signal specified by each
4640 sigspec is ignored by the shell and by the commands it invokes.
4641 If arg is not present and -p has been supplied, then the trap
4642 commands associated with each sigspec are displayed. If no
4643 arguments are supplied or if only -p is given, trap prints the
4644 list of commands associated with each signal. The -l option
4645 causes the shell to print a list of signal names and their
4646 corresponding numbers. Each sigspec is either a signal name
4647 defined in <signal.h>, or a signal number. Signal names are
4648 case insensitive and the SIG prefix is optional. If a sigspec
4649 is EXIT (0) the command arg is executed on exit from the shell.
4650 If a sigspec is DEBUG, the command arg is executed before every
4651 simple command, for command, case command, select command, every
4652 arithmetic for command, and before the first command executes in
4653 a shell function (see SHELL GRAMMAR above). Refer to the
4654 description of the extdebug option to the shopt builtin for
4655 details of its effect on the DEBUG trap. If a sigspec is ERR,
4656 the command arg is executed whenever a simple command has a
4657 non-zero exit status, subject to the following conditions. The
4658 ERR trap is not executed if the failed command is part of the
4659 command list immediately following a while or until keyword,
4660 part of the test in an if statement, part of a && or ⎪⎪ list, or
4661 if the command's return value is being inverted via !. These
4662 are the same conditions obeyed by the errexit option. If a
4663 sigspec is RETURN, the command arg is executed each time a shell
4664 function or a script executed with the . or source builtins
4665 finishes executing. Signals ignored upon entry to the shell
4666 cannot be trapped or reset. Trapped signals that are not being
4667 ignored are reset to their original values in a child process
4668 when it is created. The return status is false if any sigspec
4669 is invalid; otherwise trap returns true.
4670
4671 type [-aftpP] name [name ...]
4672 With no options, indicate how each name would be interpreted if
4673 used as a command name. If the -t option is used, type prints a
4674 string which is one of alias, keyword, function, builtin, or
4675 file if name is an alias, shell reserved word, function,
4676 builtin, or disk file, respectively. If the name is not found,
4677 then nothing is printed, and an exit status of false is
4678 returned. If the -p option is used, type either returns the
4679 name of the disk file that would be executed if name were
4680 specified as a command name, or nothing if ``type -t name''
4681 would not return file. The -P option forces a PATH search for
4682 each name, even if ``type -t name'' would not return file. If a
4683 command is hashed, -p and -P print the hashed value, not
4684 necessarily the file that appears first in PATH. If the -a
4685 option is used, type prints all of the places that contain an
4686 executable named name. This includes aliases and functions, if
4687 and only if the -p option is not also used. The table of hashed
4688 commands is not consulted when using -a. The -f option
4689 suppresses shell function lookup, as with the command builtin.
4690 type returns true if any of the arguments are found, false if
4691 none are found.
4692
4693 ulimit [-SHacdefilmnpqrstuvx [limit]]
4694 Provides control over the resources available to the shell and
4695 to processes started by it, on systems that allow such control.
4696 The -H and -S options specify that the hard or soft limit is set
4697 for the given resource. A hard limit cannot be increased once
4698 it is set; a soft limit may be increased up to the value of the
4699 hard limit. If neither -H nor -S is specified, both the soft
4700 and hard limits are set. The value of limit can be a number in
4701 the unit specified for the resource or one of the special values
4702 hard, soft, or unlimited, which stand for the current hard
4703 limit, the current soft limit, and no limit, respectively. If
4704 limit is omitted, the current value of the soft limit of the
4705 resource is printed, unless the -H option is given. When more
4706 than one resource is specified, the limit name and unit are
4707 printed before the value. Other options are interpreted as
4708 follows:
4709 -a All current limits are reported
4710 -c The maximum size of core files created
4711 -d The maximum size of a process's data segment
4712 -e The maximum scheduling priority ("nice")
4713 -f The maximum size of files written by the shell and its
4714 children
4715 -i The maximum number of pending signals
4716 -l The maximum size that may be locked into memory
4717 -m The maximum resident set size
4718 -n The maximum number of open file descriptors (most systems
4719 do not allow this value to be set)
4720 -p The pipe size in 512-byte blocks (this may not be set)
4721 -q The maximum number of bytes in POSIX message queues
4722 -r The maximum real-time scheduling priority
4723 -s The maximum stack size
4724 -t The maximum amount of cpu time in seconds
4725 -u The maximum number of processes available to a single
4726 user
4727 -v The maximum amount of virtual memory available to the
4728 shell
4729 -x The maximum number of file locks
4730
4731 If limit is given, it is the new value of the specified resource
4732 (the -a option is display only). If no option is given, then -f
4733 is assumed. Values are in 1024-byte increments, except for -t,
4734 which is in seconds, -p, which is in units of 512-byte blocks,
4735 and -n and -u, which are unscaled values. The return status is
4736 0 unless an invalid option or argument is supplied, or an error
4737 occurs while setting a new limit.
4738
4739 umask [-p] [-S] [mode]
4740 The user file-creation mask is set to mode. If mode begins with
4741 a digit, it is interpreted as an octal number; otherwise it is
4742 interpreted as a symbolic mode mask similar to that accepted by
4743 chmod(1). If mode is omitted, the current value of the mask is
4744 printed. The -S option causes the mask to be printed in
4745 symbolic form; the default output is an octal number. If the -p
4746 option is supplied, and mode is omitted, the output is in a form
4747 that may be reused as input. The return status is 0 if the mode
4748 was successfully changed or if no mode argument was supplied,
4749 and false otherwise.
4750
4751 unalias [-a] [name ...]
4752 Remove each name from the list of defined aliases. If -a is
4753 supplied, all alias definitions are removed. The return value
4754 is true unless a supplied name is not a defined alias.
4755
4756 unset [-fv] [name ...]
4757 For each name, remove the corresponding variable or function.
4758 If no options are supplied, or the -v option is given, each name
4759 refers to a shell variable. Read-only variables may not be
4760 unset. If -f is specified, each name refers to a shell
4761 function, and the function definition is removed. Each unset
4762 variable or function is removed from the environment passed to
4763 subsequent commands. If any of RANDOM, SECONDS, LINENO,
4764 HISTCMD, FUNCNAME, GROUPS, or DIRSTACK are unset, they lose
4765 their special properties, even if they are subsequently reset.
4766 The exit status is true unless a name is readonly.
4767
4768 wait [n ...]
4769 Wait for each specified process and return its termination
4770 status. Each n may be a process ID or a job specification; if a
4771 job spec is given, all processes in that job's pipeline are
4772 waited for. If n is not given, all currently active child
4773 processes are waited for, and the return status is zero. If n
4774 specifies a non-existent process or job, the return status is
4775 127. Otherwise, the return status is the exit status of the
4776 last process or job waited for.
4777
4778RESTRICTED SHELL
4779 If bash is started with the name rbash, or the -r option is supplied at
4780 invocation, the shell becomes restricted. A restricted shell is used
4781 to set up an environment more controlled than the standard shell. It
4782 behaves identically to bash with the exception that the following are
4783 disallowed or not performed:
4784
4785 • changing directories with cd
4786
4787 • setting or unsetting the values of SHELL, PATH, ENV, or BASH_ENV
4788
4789 • specifying command names containing /
4790
4791 • specifying a file name containing a / as an argument to the .
4792 builtin command
4793
4794 • Specifying a filename containing a slash as an argument to the
4795 -p option to the hash builtin command
4796
4797 • importing function definitions from the shell environment at
4798 startup
4799
4800 • parsing the value of SHELLOPTS from the shell environment at
4801 startup
4802
4803 • redirecting output using the >, >|, <>, >&, &>, and >>
4804 redirection operators
4805
4806 • using the exec builtin command to replace the shell with another
4807 command
4808
4809 • adding or deleting builtin commands with the -f and -d options
4810 to the enable builtin command
4811
4812 • Using the enable builtin command to enable disabled shell
4813 builtins
4814
4815 • specifying the -p option to the command builtin command
4816
4817 • turning off restricted mode with set +r or set +o restricted.
4818
4819 These restrictions are enforced after any startup files are read.
4820
4821 When a command that is found to be a shell script is executed (see
4822 COMMAND EXECUTION above), rbash turns off any restrictions in the shell
4823 spawned to execute the script.
4824
4825SEE ALSO
4826 Bash Reference Manual, Brian Fox and Chet Ramey
4827 The Gnu Readline Library, Brian Fox and Chet Ramey
4828 The Gnu History Library, Brian Fox and Chet Ramey
4829 Portable Operating System Interface (POSIX) Part 2: Shell and
4830 Utilities, IEEE
4831 sh(1), ksh(1), csh(1)
4832 emacs(1), vi(1)
4833 readline(3)
4834
4835FILES
4836 /bin/bash
4837 The bash executable
4838 /etc/profile
4839 The systemwide initialization file, executed for login shells
4840 ~/.bash_profile
4841 The personal initialization file, executed for login shells
4842 ~/.bashrc
4843 The individual per-interactive-shell startup file
4844 ~/.bash_logout
4845 The individual login shell cleanup file, executed when a login
4846 shell exits
4847 ~/.inputrc
4848 Individual readline initialization file
4849
4850AUTHORS
4851 Brian Fox, Free Software Foundation
4852 bfox@gnu.org
4853
4854 Chet Ramey, Case Western Reserve University
4855 chet@po.cwru.edu
4856
4857BUG REPORTS
4858 If you find a bug in bash, you should report it. But first, you should
4859 make sure that it really is a bug, and that it appears in the latest
4860 version of bash. The latest version is always available from
4861 ftp://ftp.gnu.org/pub/bash/.
4862
4863 Once you have determined that a bug actually exists, use the bashbug
4864 command to submit a bug report. If you have a fix, you are encouraged
4865 to mail that as well! Suggestions and `philosophical' bug reports may
4866 be mailed to bug-bash@gnu.org or posted to the Usenet newsgroup
4867 gnu.bash.bug.
4868
4869 ALL bug reports should include:
4870
4871 The version number of bash
4872 The hardware and operating system
4873 The compiler used to compile
4874 A description of the bug behaviour
4875 A short script or `recipe' which exercises the bug
4876
4877 bashbug inserts the first three items automatically into the template
4878 it provides for filing a bug report.
4879
4880 Comments and bug reports concerning this manual page should be directed
4881 to chet@po.cwru.edu.
4882
4883BUGS
4884 It's too big and too slow.
4885
4886 There are some subtle differences between bash and traditional versions
4887 of sh, mostly because of the POSIX specification.
4888
4889 Aliases are confusing in some uses.
4890
4891 Shell builtin commands and functions are not stoppable/restartable.
4892
4893 Compound commands and command sequences of the form `a ; b ; c' are not
4894 handled gracefully when process suspension is attempted. When a
4895 process is stopped, the shell immediately executes the next command in
4896 the sequence. It suffices to place the sequence of commands between
4897 parentheses to force it into a subshell, which may be stopped as a
4898 unit.
4899
4900 Commands inside of $(...) command substitution are not parsed until
4901 substitution is attempted. This will delay error reporting until some
4902 time after the command is entered. For example, unmatched parentheses,
4903 even inside shell comments, will result in error messages while the
4904 construct is being read.
4905
4906 Array variables may not (yet) be exported.
4907
4908GNU Bash-3.2 2006 September 28 BASH(1)
4909