]>
Commit | Line | Data |
---|---|---|
a0c0a00f | 1 | BASH(1) General Commands Manual BASH(1) |
17345e5a JA |
2 | |
3 | ||
4 | ||
5 | N\bNA\bAM\bME\bE | |
6 | bash - GNU Bourne-Again SHell | |
7 | ||
8 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS | |
ac50fbac | 9 | b\bba\bas\bsh\bh [options] [command_string | file] |
17345e5a JA |
10 | |
11 | C\bCO\bOP\bPY\bYR\bRI\bIG\bGH\bHT\bT | |
74091dd4 | 12 | Bash is Copyright (C) 1989-2022 by the Free Software Foundation, Inc. |
17345e5a JA |
13 | |
14 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN | |
15 | B\bBa\bas\bsh\bh is an s\bsh\bh-compatible command language interpreter that executes | |
16 | commands read from the standard input or from a file. B\bBa\bas\bsh\bh also incor- | |
17 | porates useful features from the _\bK_\bo_\br_\bn and _\bC shells (k\bks\bsh\bh and c\bcs\bsh\bh). | |
18 | ||
19 | B\bBa\bas\bsh\bh is intended to be a conformant implementation of the Shell and | |
20 | Utilities portion of the IEEE POSIX specification (IEEE Standard | |
21 | 1003.1). B\bBa\bas\bsh\bh can be configured to be POSIX-conformant by default. | |
22 | ||
23 | O\bOP\bPT\bTI\bIO\bON\bNS\bS | |
a0c0a00f | 24 | All of the single-character shell options documented in the description |
d233b485 | 25 | of the s\bse\bet\bt builtin command, including -\b-o\bo, can be used as options when |
8868edaf CR |
26 | the shell is invoked. In addition, b\bba\bas\bsh\bh interprets the following op- |
27 | tions when it is invoked: | |
17345e5a | 28 | |
ac50fbac CR |
29 | -\b-c\bc If the -\b-c\bc option is present, then commands are read from the |
30 | first non-option argument _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b__\bs_\bt_\br_\bi_\bn_\bg. If there are argu- | |
8868edaf CR |
31 | ments after the _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b__\bs_\bt_\br_\bi_\bn_\bg, the first argument is as- |
32 | signed to $\b$0\b0 and any remaining arguments are assigned to the | |
33 | positional parameters. The assignment to $\b$0\b0 sets the name of | |
34 | the shell, which is used in warning and error messages. | |
17345e5a JA |
35 | -\b-i\bi If the -\b-i\bi option is present, the shell is _\bi_\bn_\bt_\be_\br_\ba_\bc_\bt_\bi_\bv_\be. |
36 | -\b-l\bl Make b\bba\bas\bsh\bh act as if it had been invoked as a login shell (see | |
37 | I\bIN\bNV\bVO\bOC\bCA\bAT\bTI\bIO\bON\bN below). | |
8868edaf | 38 | -\b-r\br If the -\b-r\br option is present, the shell becomes _\br_\be_\bs_\bt_\br_\bi_\bc_\bt_\be_\bd |
17345e5a | 39 | (see R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTE\bED\bD S\bSH\bHE\bEL\bLL\bL below). |
8868edaf CR |
40 | -\b-s\bs If the -\b-s\bs option is present, or if no arguments remain after |
41 | option processing, then commands are read from the standard | |
42 | input. This option allows the positional parameters to be | |
43 | set when invoking an interactive shell or when reading input | |
d233b485 | 44 | through a pipe. |
8868edaf CR |
45 | -\b-D\bD A list of all double-quoted strings preceded by $\b$ is printed |
46 | on the standard output. These are the strings that are sub- | |
17345e5a | 47 | ject to language translation when the current locale is not C\bC |
8868edaf | 48 | or P\bPO\bOS\bSI\bIX\bX. This implies the -\b-n\bn option; no commands will be |
17345e5a JA |
49 | executed. |
50 | [\b[-\b-+\b+]\b]O\bO [\b[_\bs_\bh_\bo_\bp_\bt_\b__\bo_\bp_\bt_\bi_\bo_\bn]\b] | |
8868edaf CR |
51 | _\bs_\bh_\bo_\bp_\bt_\b__\bo_\bp_\bt_\bi_\bo_\bn is one of the shell options accepted by the |
52 | s\bsh\bho\bop\bpt\bt builtin (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). If | |
17345e5a | 53 | _\bs_\bh_\bo_\bp_\bt_\b__\bo_\bp_\bt_\bi_\bo_\bn is present, -\b-O\bO sets the value of that option; +\b+O\bO |
8868edaf CR |
54 | unsets it. If _\bs_\bh_\bo_\bp_\bt_\b__\bo_\bp_\bt_\bi_\bo_\bn is not supplied, the names and |
55 | values of the shell options accepted by s\bsh\bho\bop\bpt\bt are printed on | |
56 | the standard output. If the invocation option is +\b+O\bO, the | |
a0c0a00f | 57 | output is displayed in a format that may be reused as input. |
8868edaf CR |
58 | -\b--\b- A -\b--\b- signals the end of options and disables further option |
59 | processing. Any arguments after the -\b--\b- are treated as file- | |
17345e5a JA |
60 | names and arguments. An argument of -\b- is equivalent to -\b--\b-. |
61 | ||
8868edaf CR |
62 | B\bBa\bas\bsh\bh also interprets a number of multi-character options. These op- |
63 | tions must appear on the command line before the single-character op- | |
64 | tions to be recognized. | |
17345e5a JA |
65 | |
66 | -\b--\b-d\bde\beb\bbu\bug\bgg\bge\ber\br | |
67 | Arrange for the debugger profile to be executed before the shell | |
8868edaf | 68 | starts. Turns on extended debugging mode (see the description |
495aee44 | 69 | of the e\bex\bxt\btd\bde\beb\bbu\bug\bg option to the s\bsh\bho\bop\bpt\bt builtin below). |
17345e5a | 70 | -\b--\b-d\bdu\bum\bmp\bp-\b-p\bpo\bo-\b-s\bst\btr\bri\bin\bng\bgs\bs |
8868edaf | 71 | Equivalent to -\b-D\bD, but the output is in the GNU _\bg_\be_\bt_\bt_\be_\bx_\bt p\bpo\bo (por- |
17345e5a JA |
72 | table object) file format. |
73 | -\b--\b-d\bdu\bum\bmp\bp-\b-s\bst\btr\bri\bin\bng\bgs\bs | |
74 | Equivalent to -\b-D\bD. | |
8868edaf | 75 | -\b--\b-h\bhe\bel\blp\bp Display a usage message on standard output and exit success- |
17345e5a JA |
76 | fully. |
77 | -\b--\b-i\bin\bni\bit\bt-\b-f\bfi\bil\ble\be _\bf_\bi_\bl_\be | |
78 | -\b--\b-r\brc\bcf\bfi\bil\ble\be _\bf_\bi_\bl_\be | |
79 | Execute commands from _\bf_\bi_\bl_\be instead of the standard personal ini- | |
8868edaf CR |
80 | tialization file _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc if the shell is interactive (see I\bIN\bN-\b- |
81 | V\bVO\bOC\bCA\bAT\bTI\bIO\bON\bN below). | |
17345e5a JA |
82 | |
83 | -\b--\b-l\blo\bog\bgi\bin\bn | |
84 | Equivalent to -\b-l\bl. | |
85 | ||
86 | -\b--\b-n\bno\boe\bed\bdi\bit\bti\bin\bng\bg | |
8868edaf | 87 | Do not use the GNU r\bre\bea\bad\bdl\bli\bin\bne\be library to read command lines when |
17345e5a JA |
88 | the shell is interactive. |
89 | ||
90 | -\b--\b-n\bno\bop\bpr\bro\bof\bfi\bil\ble\be | |
8868edaf CR |
91 | Do not read either the system-wide startup file _\b/_\be_\bt_\bc_\b/_\bp_\br_\bo_\bf_\bi_\bl_\be or |
92 | any of the personal initialization files _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bp_\br_\bo_\bf_\bi_\bl_\be, | |
93 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bl_\bo_\bg_\bi_\bn, or _\b~_\b/_\b._\bp_\br_\bo_\bf_\bi_\bl_\be. By default, b\bba\bas\bsh\bh reads these | |
94 | files when it is invoked as a login shell (see I\bIN\bNV\bVO\bOC\bCA\bAT\bTI\bIO\bON\bN be- | |
95 | low). | |
17345e5a JA |
96 | |
97 | -\b--\b-n\bno\bor\brc\bc Do not read and execute the personal initialization file | |
8868edaf CR |
98 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc if the shell is interactive. This option is on by de- |
99 | fault if the shell is invoked as s\bsh\bh. | |
17345e5a JA |
100 | |
101 | -\b--\b-p\bpo\bos\bsi\bix\bx | |
8868edaf | 102 | Change the behavior of b\bba\bas\bsh\bh where the default operation differs |
ac50fbac | 103 | from the POSIX standard to match the standard (_\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be). See |
8868edaf | 104 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO below for a reference to a document that details how |
ac50fbac | 105 | posix mode affects bash's behavior. |
17345e5a JA |
106 | |
107 | -\b--\b-r\bre\bes\bst\btr\bri\bic\bct\bte\bed\bd | |
108 | The shell becomes restricted (see R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTE\bED\bD S\bSH\bHE\bEL\bLL\bL below). | |
109 | ||
110 | -\b--\b-v\bve\ber\brb\bbo\bos\bse\be | |
a0c0a00f | 111 | Equivalent to -\b-v\bv. |
17345e5a JA |
112 | |
113 | -\b--\b-v\bve\ber\brs\bsi\bio\bon\bn | |
8868edaf | 114 | Show version information for this instance of b\bba\bas\bsh\bh on the stan- |
17345e5a JA |
115 | dard output and exit successfully. |
116 | ||
117 | A\bAR\bRG\bGU\bUM\bME\bEN\bNT\bTS\bS | |
118 | If arguments remain after option processing, and neither the -\b-c\bc nor the | |
8868edaf CR |
119 | -\b-s\bs option has been supplied, the first argument is assumed to be the |
120 | name of a file containing shell commands. If b\bba\bas\bsh\bh is invoked in this | |
121 | fashion, $\b$0\b0 is set to the name of the file, and the positional parame- | |
122 | ters are set to the remaining arguments. B\bBa\bas\bsh\bh reads and executes com- | |
123 | mands from this file, then exits. B\bBa\bas\bsh\bh's exit status is the exit sta- | |
124 | tus of the last command executed in the script. If no commands are ex- | |
125 | ecuted, the exit status is 0. An attempt is first made to open the | |
17345e5a JA |
126 | file in the current directory, and, if no file is found, then the shell |
127 | searches the directories in P\bPA\bAT\bTH\bH for the script. | |
128 | ||
129 | I\bIN\bNV\bVO\bOC\bCA\bAT\bTI\bIO\bON\bN | |
8868edaf | 130 | A _\bl_\bo_\bg_\bi_\bn _\bs_\bh_\be_\bl_\bl is one whose first character of argument zero is a -\b-, or |
17345e5a JA |
131 | one started with the -\b--\b-l\blo\bog\bgi\bin\bn option. |
132 | ||
8868edaf | 133 | An _\bi_\bn_\bt_\be_\br_\ba_\bc_\bt_\bi_\bv_\be shell is one started without non-option arguments (un- |
74091dd4 | 134 | less -\b-s\bs is specified) and without the -\b-c\bc option, whose standard input |
a0c0a00f | 135 | and error are both connected to terminals (as determined by _\bi_\bs_\ba_\bt_\bt_\by(3)), |
8868edaf CR |
136 | or one started with the -\b-i\bi option. P\bPS\bS1\b1 is set and $\b$-\b- includes i\bi if |
137 | b\bba\bas\bsh\bh is interactive, allowing a shell script or a startup file to test | |
a0c0a00f | 138 | this state. |
17345e5a | 139 | |
8868edaf CR |
140 | The following paragraphs describe how b\bba\bas\bsh\bh executes its startup files. |
141 | If any of the files exist but cannot be read, b\bba\bas\bsh\bh reports an error. | |
142 | Tildes are expanded in filenames as described below under T\bTi\bil\bld\bde\be E\bEx\bxp\bpa\ban\bn-\b- | |
17345e5a JA |
143 | s\bsi\bio\bon\bn in the E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN section. |
144 | ||
8868edaf CR |
145 | When b\bba\bas\bsh\bh is invoked as an interactive login shell, or as a non-inter- |
146 | active shell with the -\b--\b-l\blo\bog\bgi\bin\bn option, it first reads and executes com- | |
147 | mands from the file _\b/_\be_\bt_\bc_\b/_\bp_\br_\bo_\bf_\bi_\bl_\be, if that file exists. After reading | |
17345e5a | 148 | that file, it looks for _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bp_\br_\bo_\bf_\bi_\bl_\be, _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bl_\bo_\bg_\bi_\bn, and _\b~_\b/_\b._\bp_\br_\bo_\bf_\bi_\bl_\be, |
8868edaf CR |
149 | in that order, and reads and executes commands from the first one that |
150 | exists and is readable. The -\b--\b-n\bno\bop\bpr\bro\bof\bfi\bil\ble\be option may be used when the | |
17345e5a JA |
151 | shell is started to inhibit this behavior. |
152 | ||
a0c0a00f | 153 | When an interactive login shell exits, or a non-interactive login shell |
8868edaf | 154 | executes the e\bex\bxi\bit\bt builtin command, b\bba\bas\bsh\bh reads and executes commands |
a0c0a00f | 155 | from the file _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bl_\bo_\bg_\bo_\bu_\bt, if it exists. |
17345e5a | 156 | |
8868edaf CR |
157 | When an interactive shell that is not a login shell is started, b\bba\bas\bsh\bh |
158 | reads and executes commands from _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc, if that file exists. This | |
159 | may be inhibited by using the -\b--\b-n\bno\bor\brc\bc option. The -\b--\b-r\brc\bcf\bfi\bil\ble\be _\bf_\bi_\bl_\be option | |
160 | will force b\bba\bas\bsh\bh to read and execute commands from _\bf_\bi_\bl_\be instead of | |
17345e5a JA |
161 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc. |
162 | ||
8868edaf CR |
163 | When b\bba\bas\bsh\bh is started non-interactively, to run a shell script, for ex- |
164 | ample, it looks for the variable B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV in the environment, expands | |
165 | its value if it appears there, and uses the expanded value as the name | |
166 | of a file to read and execute. B\bBa\bas\bsh\bh behaves as if the following com- | |
17345e5a JA |
167 | mand were executed: |
168 | if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi | |
8868edaf | 169 | but the value of the P\bPA\bAT\bTH\bH variable is not used to search for the file- |
17345e5a JA |
170 | name. |
171 | ||
8868edaf CR |
172 | If b\bba\bas\bsh\bh is invoked with the name s\bsh\bh, it tries to mimic the startup be- |
173 | havior of historical versions of s\bsh\bh as closely as possible, while con- | |
174 | forming to the POSIX standard as well. When invoked as an interactive | |
175 | login shell, or a non-interactive shell with the -\b--\b-l\blo\bog\bgi\bin\bn option, it | |
176 | first attempts to read and execute commands from _\b/_\be_\bt_\bc_\b/_\bp_\br_\bo_\bf_\bi_\bl_\be and | |
177 | _\b~_\b/_\b._\bp_\br_\bo_\bf_\bi_\bl_\be, in that order. The -\b--\b-n\bno\bop\bpr\bro\bof\bfi\bil\ble\be option may be used to in- | |
178 | hibit this behavior. When invoked as an interactive shell with the | |
179 | name s\bsh\bh, b\bba\bas\bsh\bh looks for the variable E\bEN\bNV\bV, expands its value if it is | |
180 | defined, and uses the expanded value as the name of a file to read and | |
17345e5a | 181 | execute. Since a shell invoked as s\bsh\bh does not attempt to read and exe- |
8868edaf CR |
182 | cute commands from any other startup files, the -\b--\b-r\brc\bcf\bfi\bil\ble\be option has no |
183 | effect. A non-interactive shell invoked with the name s\bsh\bh does not at- | |
184 | tempt to read any other startup files. When invoked as s\bsh\bh, b\bba\bas\bsh\bh enters | |
185 | _\bp_\bo_\bs_\bi_\bx mode after the startup files are read. | |
17345e5a | 186 | |
8868edaf | 187 | When b\bba\bas\bsh\bh is started in _\bp_\bo_\bs_\bi_\bx mode, as with the -\b--\b-p\bpo\bos\bsi\bix\bx command line |
17345e5a | 188 | option, it follows the POSIX standard for startup files. In this mode, |
8868edaf CR |
189 | interactive shells expand the E\bEN\bNV\bV variable and commands are read and |
190 | executed from the file whose name is the expanded value. No other | |
17345e5a JA |
191 | startup files are read. |
192 | ||
193 | B\bBa\bas\bsh\bh attempts to determine when it is being run with its standard input | |
74091dd4 CR |
194 | connected to a network connection, as when executed by the historical |
195 | remote shell daemon, usually _\br_\bs_\bh_\bd, or the secure shell daemon _\bs_\bs_\bh_\bd. If | |
196 | b\bba\bas\bsh\bh determines it is being run non-interactively in this fashion, it | |
197 | reads and executes commands from _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc, if that file exists and is | |
198 | readable. It will not do this if invoked as s\bsh\bh. The -\b--\b-n\bno\bor\brc\bc option may | |
199 | be used to inhibit this behavior, and the -\b--\b-r\brc\bcf\bfi\bil\ble\be option may be used | |
200 | to force another file to be read, but neither _\br_\bs_\bh_\bd nor _\bs_\bs_\bh_\bd generally | |
201 | invoke the shell with those options or allow them to be specified. | |
17345e5a JA |
202 | |
203 | If the shell is started with the effective user (group) id not equal to | |
204 | the real user (group) id, and the -\b-p\bp option is not supplied, no startup | |
205 | files are read, shell functions are not inherited from the environment, | |
8868edaf CR |
206 | the S\bSH\bHE\bEL\bLL\bLO\bOP\bPT\bTS\bS, B\bBA\bAS\bSH\bHO\bOP\bPT\bTS\bS, C\bCD\bDP\bPA\bAT\bTH\bH, and G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE variables, if they ap- |
207 | pear in the environment, are ignored, and the effective user id is set | |
208 | to the real user id. If the -\b-p\bp option is supplied at invocation, the | |
209 | startup behavior is the same, but the effective user id is not reset. | |
17345e5a JA |
210 | |
211 | D\bDE\bEF\bFI\bIN\bNI\bIT\bTI\bIO\bON\bNS\bS | |
d233b485 | 212 | The following definitions are used throughout the rest of this docu- |
17345e5a JA |
213 | ment. |
214 | b\bbl\bla\ban\bnk\bk A space or tab. | |
d233b485 | 215 | w\bwo\bor\brd\bd A sequence of characters considered as a single unit by the |
17345e5a | 216 | shell. Also known as a t\bto\bok\bke\ben\bn. |
d233b485 CR |
217 | n\bna\bam\bme\be A _\bw_\bo_\br_\bd consisting only of alphanumeric characters and under- |
218 | scores, and beginning with an alphabetic character or an under- | |
17345e5a JA |
219 | score. Also referred to as an i\bid\bde\ben\bnt\bti\bif\bfi\bie\ber\br. |
220 | m\bme\bet\bta\bac\bch\bha\bar\bra\bac\bct\bte\ber\br | |
d233b485 | 221 | A character that, when unquoted, separates words. One of the |
17345e5a | 222 | following: |
a0c0a00f | 223 | |\b| &\b& ;\b; (\b( )\b) <\b< >\b> s\bsp\bpa\bac\bce\be t\bta\bab\bb n\bne\bew\bwl\bli\bin\bne\be |
17345e5a JA |
224 | c\bco\bon\bnt\btr\bro\bol\bl o\bop\bpe\ber\bra\bat\bto\bor\br |
225 | A _\bt_\bo_\bk_\be_\bn that performs a control function. It is one of the fol- | |
226 | lowing symbols: | |
a0c0a00f | 227 | |\b||\b| &\b& &\b&&\b& ;\b; ;\b;;\b; ;\b;&\b& ;\b;;\b;&\b& (\b( )\b) |\b| |\b|&\b& <\b<n\bne\bew\bwl\bli\bin\bne\be>\b> |
17345e5a JA |
228 | |
229 | R\bRE\bES\bSE\bER\bRV\bVE\bED\bD W\bWO\bOR\bRD\bDS\bS | |
230 | _\bR_\be_\bs_\be_\br_\bv_\be_\bd _\bw_\bo_\br_\bd_\bs are words that have a special meaning to the shell. The | |
231 | following words are recognized as reserved when unquoted and either the | |
8868edaf CR |
232 | first word of a command (see S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR below), the third word of a |
233 | c\bca\bas\bse\be or s\bse\bel\ble\bec\bct\bt command (only i\bin\bn is valid), or the third word of a f\bfo\bor\br | |
234 | command (only i\bin\bn and d\bdo\bo are valid): | |
17345e5a | 235 | |
8868edaf | 236 | !\b! c\bca\bas\bse\be c\bco\bop\bpr\bro\boc\bc d\bdo\bo d\bdo\bon\bne\be e\bel\bli\bif\bf e\bel\bls\bse\be e\bes\bsa\bac\bc f\bfi\bi f\bfo\bor\br f\bfu\bun\bnc\bct\bti\bio\bon\bn i\bif\bf i\bin\bn s\bse\bel\ble\bec\bct\bt |
ac50fbac | 237 | t\bth\bhe\ben\bn u\bun\bnt\bti\bil\bl w\bwh\bhi\bil\ble\be {\b{ }\b} t\bti\bim\bme\be [\b[[\b[ ]\b]]\b] |
17345e5a JA |
238 | |
239 | S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR | |
74091dd4 CR |
240 | This section describes the syntax of the various forms of shell com- |
241 | mands. | |
242 | ||
17345e5a | 243 | S\bSi\bim\bmp\bpl\ble\be C\bCo\bom\bmm\bma\ban\bnd\bds\bs |
74091dd4 CR |
244 | A _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd is a sequence of optional variable assignments fol- |
245 | lowed by b\bbl\bla\ban\bnk\bk-separated words and redirections, and terminated by a | |
17345e5a | 246 | _\bc_\bo_\bn_\bt_\br_\bo_\bl _\bo_\bp_\be_\br_\ba_\bt_\bo_\br. The first word specifies the command to be executed, |
74091dd4 | 247 | and is passed as argument zero. The remaining words are passed as ar- |
8868edaf | 248 | guments to the invoked command. |
17345e5a | 249 | |
74091dd4 | 250 | The return value of a _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd is its exit status, or 128+_\bn if |
17345e5a JA |
251 | the command is terminated by signal _\bn. |
252 | ||
253 | P\bPi\bip\bpe\bel\bli\bin\bne\bes\bs | |
74091dd4 | 254 | A _\bp_\bi_\bp_\be_\bl_\bi_\bn_\be is a sequence of one or more commands separated by one of |
17345e5a JA |
255 | the control operators |\b| or |\b|&\b&. The format for a pipeline is: |
256 | ||
74091dd4 | 257 | [t\bti\bim\bme\be [-\b-p\bp]] [ ! ] _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1 [ [|\b|||\b|&\b&] _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2 ... ] |
17345e5a | 258 | |
74091dd4 CR |
259 | The standard output of _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1 is connected via a pipe to the standard |
260 | input of _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2. This connection is performed before any redirec- | |
261 | tions specified by the _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1(see R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN below). If |\b|&\b& is used, | |
262 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1's standard error, in addition to its standard output, is con- | |
263 | nected to _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2's standard input through the pipe; it is shorthand | |
264 | for 2\b2>\b>&\b&1\b1 |\b|. This implicit redirection of the standard error to the | |
265 | standard output is performed after any redirections specified by _\bc_\bo_\bm_\b- | |
266 | _\bm_\ba_\bn_\bd_\b1. | |
17345e5a JA |
267 | |
268 | The return status of a pipeline is the exit status of the last command, | |
74091dd4 CR |
269 | unless the p\bpi\bip\bpe\bef\bfa\bai\bil\bl option is enabled. If p\bpi\bip\bpe\bef\bfa\bai\bil\bl is enabled, the |
270 | pipeline's return status is the value of the last (rightmost) command | |
271 | to exit with a non-zero status, or zero if all commands exit success- | |
17345e5a | 272 | fully. If the reserved word !\b! precedes a pipeline, the exit status of |
74091dd4 CR |
273 | that pipeline is the logical negation of the exit status as described |
274 | above. The shell waits for all commands in the pipeline to terminate | |
17345e5a JA |
275 | before returning a value. |
276 | ||
74091dd4 CR |
277 | If the t\bti\bim\bme\be reserved word precedes a pipeline, the elapsed as well as |
278 | user and system time consumed by its execution are reported when the | |
279 | pipeline terminates. The -\b-p\bp option changes the output format to that | |
280 | specified by POSIX. When the shell is in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, it does not rec- | |
281 | ognize t\bti\bim\bme\be as a reserved word if the next token begins with a `-'. | |
282 | The T\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT variable may be set to a format string that specifies | |
283 | how the timing information should be displayed; see the description of | |
495aee44 CR |
284 | T\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT under S\bSh\bhe\bel\bll\bl V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs below. |
285 | ||
286 | When the shell is in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, t\bti\bim\bme\be may be followed by a newline. In | |
74091dd4 CR |
287 | this case, the shell displays the total user and system time consumed |
288 | by the shell and its children. The T\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT variable may be used to | |
495aee44 | 289 | specify the format of the time information. |
17345e5a | 290 | |
74091dd4 CR |
291 | Each command in a multi-command pipeline, where pipes are created, is |
292 | executed in a _\bs_\bu_\bb_\bs_\bh_\be_\bl_\bl, which is a separate process. See C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXE\bE-\b- | |
293 | C\bCU\bUT\bTI\bIO\bON\bN E\bEN\bNV\bVI\bIR\bRO\bON\bNM\bME\bEN\bNT\bT for a description of subshells and a subshell envi- | |
294 | ronment. If the l\bla\bas\bst\btp\bpi\bip\bpe\be option is enabled using the s\bsh\bho\bop\bpt\bt builtin | |
295 | (see the description of s\bsh\bho\bop\bpt\bt below), the last element of a pipeline | |
296 | may be run by the shell process when job control is not active. | |
17345e5a JA |
297 | |
298 | L\bLi\bis\bst\bts\bs | |
8868edaf | 299 | A _\bl_\bi_\bs_\bt is a sequence of one or more pipelines separated by one of the |
17345e5a JA |
300 | operators ;\b;, &\b&, &\b&&\b&, or |\b||\b|, and optionally terminated by one of ;\b;, &\b&, or |
301 | <\b<n\bne\bew\bwl\bli\bin\bne\be>\b>. | |
302 | ||
303 | Of these list operators, &\b&&\b& and |\b||\b| have equal precedence, followed by ;\b; | |
304 | and &\b&, which have equal precedence. | |
305 | ||
8868edaf | 306 | A sequence of one or more newlines may appear in a _\bl_\bi_\bs_\bt instead of a |
17345e5a JA |
307 | semicolon to delimit commands. |
308 | ||
8868edaf CR |
309 | If a command is terminated by the control operator &\b&, the shell exe- |
310 | cutes the command in the _\bb_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd in a subshell. The shell does not | |
311 | wait for the command to finish, and the return status is 0. These are | |
312 | referred to as _\ba_\bs_\by_\bn_\bc_\bh_\br_\bo_\bn_\bo_\bu_\bs commands. Commands separated by a ;\b; are | |
d233b485 | 313 | executed sequentially; the shell waits for each command to terminate in |
8868edaf | 314 | turn. The return status is the exit status of the last command exe- |
d233b485 CR |
315 | cuted. |
316 | ||
8868edaf CR |
317 | AND and OR lists are sequences of one or more pipelines separated by |
318 | the &\b&&\b& and |\b||\b| control operators, respectively. AND and OR lists are | |
17345e5a JA |
319 | executed with left associativity. An AND list has the form |
320 | ||
321 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1 &\b&&\b& _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2 | |
322 | ||
8868edaf | 323 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2 is executed if, and only if, _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1 returns an exit status |
d233b485 | 324 | of zero (success). |
17345e5a JA |
325 | |
326 | An OR list has the form | |
327 | ||
328 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1 |\b||\b| _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2 | |
329 | ||
8868edaf CR |
330 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2 is executed if, and only if, _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1 returns a non-zero exit |
331 | status. The return status of AND and OR lists is the exit status of | |
17345e5a JA |
332 | the last command executed in the list. |
333 | ||
334 | C\bCo\bom\bmp\bpo\bou\bun\bnd\bd C\bCo\bom\bmm\bma\ban\bnd\bds\bs | |
8868edaf CR |
335 | A _\bc_\bo_\bm_\bp_\bo_\bu_\bn_\bd _\bc_\bo_\bm_\bm_\ba_\bn_\bd is one of the following. In most cases a _\bl_\bi_\bs_\bt in a |
336 | command's description may be separated from the rest of the command by | |
337 | one or more newlines, and may be followed by a newline in place of a | |
ac50fbac CR |
338 | semicolon. |
339 | ||
74091dd4 CR |
340 | (_\bl_\bi_\bs_\bt) _\bl_\bi_\bs_\bt is executed in a subshell (see C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN E\bEN\bNV\bVI\bIR\bRO\bON\bN-\b- |
341 | M\bME\bEN\bNT\bT below for a description of a subshell environment). Vari- | |
342 | able assignments and builtin commands that affect the shell's | |
343 | environment do not remain in effect after the command completes. | |
344 | The return status is the exit status of _\bl_\bi_\bs_\bt. | |
17345e5a JA |
345 | |
346 | { _\bl_\bi_\bs_\bt; } | |
8868edaf CR |
347 | _\bl_\bi_\bs_\bt is simply executed in the current shell environment. _\bl_\bi_\bs_\bt |
348 | must be terminated with a newline or semicolon. This is known | |
349 | as a _\bg_\br_\bo_\bu_\bp _\bc_\bo_\bm_\bm_\ba_\bn_\bd. The return status is the exit status of | |
350 | _\bl_\bi_\bs_\bt. Note that unlike the metacharacters (\b( and )\b), {\b{ and }\b} are | |
17345e5a | 351 | _\br_\be_\bs_\be_\br_\bv_\be_\bd _\bw_\bo_\br_\bd_\bs and must occur where a reserved word is permitted |
8868edaf CR |
352 | to be recognized. Since they do not cause a word break, they |
353 | must be separated from _\bl_\bi_\bs_\bt by whitespace or another shell | |
17345e5a JA |
354 | metacharacter. |
355 | ||
356 | ((_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn)) | |
8868edaf CR |
357 | The _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn is evaluated according to the rules described be- |
358 | low under A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN. If the value of the expression | |
359 | is non-zero, the return status is 0; otherwise the return status | |
74091dd4 CR |
360 | is 1. The _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn undergoes the same expansions as if it |
361 | were within double quotes, but double quote characters in _\be_\bx_\b- | |
362 | _\bp_\br_\be_\bs_\bs_\bi_\bo_\bn are not treated specially and are removed. | |
17345e5a JA |
363 | |
364 | [\b[[\b[ _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn ]\b]]\b] | |
8868edaf CR |
365 | Return a status of 0 or 1 depending on the evaluation of the |
366 | conditional expression _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn. Expressions are composed of | |
367 | the primaries described below under C\bCO\bON\bND\bDI\bIT\bTI\bIO\bON\bNA\bAL\bL E\bEX\bXP\bPR\bRE\bES\bSS\bSI\bIO\bON\bNS\bS. | |
74091dd4 CR |
368 | The words between the [\b[[\b[ and ]\b]]\b] do not undergo word splitting |
369 | and pathname expansion. The shell performs tilde expansion, pa- | |
370 | rameter and variable expansion, arithmetic expansion, command | |
371 | substitution, process substitution, and quote removal on those | |
372 | words (the expansions that would occur if the words were en- | |
373 | closed in double quotes). Conditional operators such as -\b-f\bf must | |
374 | be unquoted to be recognized as primaries. | |
375 | ||
376 | When used with [\b[[\b[, the <\b< and >\b> operators sort lexicographically | |
0001803f CR |
377 | using the current locale. |
378 | ||
74091dd4 | 379 | When the =\b==\b= and !\b!=\b= operators are used, the string to the right |
17345e5a | 380 | of the operator is considered a pattern and matched according to |
ac50fbac CR |
381 | the rules described below under P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg, as if the e\bex\bxt\bt-\b- |
382 | g\bgl\blo\bob\bb shell option were enabled. The =\b= operator is equivalent to | |
74091dd4 CR |
383 | =\b==\b=. If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh shell option is enabled, the match is |
384 | performed without regard to the case of alphabetic characters. | |
385 | The return value is 0 if the string matches (=\b==\b=) or does not | |
386 | match (!\b!=\b=) the pattern, and 1 otherwise. Any part of the pat- | |
387 | tern may be quoted to force the quoted portion to be matched as | |
ac50fbac CR |
388 | a string. |
389 | ||
74091dd4 CR |
390 | An additional binary operator, =\b=~\b~, is available, with the same |
391 | precedence as =\b==\b= and !\b!=\b=. When it is used, the string to the | |
8868edaf | 392 | right of the operator is considered a POSIX extended regular ex- |
74091dd4 CR |
393 | pression and matched accordingly (using the POSIX _\br_\be_\bg_\bc_\bo_\bm_\bp and |
394 | _\br_\be_\bg_\be_\bx_\be_\bc interfaces usually described in _\br_\be_\bg_\be_\bx(3)). The return | |
395 | value is 0 if the string matches the pattern, and 1 otherwise. | |
d233b485 CR |
396 | If the regular expression is syntactically incorrect, the condi- |
397 | tional expression's return value is 2. If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh shell | |
74091dd4 CR |
398 | option is enabled, the match is performed without regard to the |
399 | case of alphabetic characters. If any part of the pattern is | |
400 | quoted, the quoted portion is matched literally. This means ev- | |
401 | ery character in the quoted portion matches itself, instead of | |
402 | having any special pattern matching meaning. If the pattern is | |
403 | stored in a shell variable, quoting the variable expansion | |
404 | forces the entire pattern to be matched literally. Treat | |
405 | bracket expressions in regular expressions carefully, since nor- | |
406 | mal quoting and pattern characters lose their meanings between | |
407 | brackets. | |
408 | ||
409 | The pattern will match if it matches any part of the string. | |
410 | Anchor the pattern using the ^\b^ and $\b$ regular expression opera- | |
8868edaf | 411 | tors to force it to match the entire string. The array variable |
74091dd4 CR |
412 | B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH records which parts of the string matched the pat- |
413 | tern. The element of B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH with index 0 contains the | |
414 | portion of the string matching the entire regular expression. | |
415 | Substrings matched by parenthesized subexpressions within the | |
416 | regular expression are saved in the remaining B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH in- | |
417 | dices. The element of B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH with index _\bn is the portion | |
418 | of the string matching the _\bnth parenthesized subexpression. | |
419 | Bash sets B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH in the global scope; declaring it as a | |
420 | local variable will lead to unexpected results. | |
421 | ||
422 | Expressions may be combined using the following operators, | |
17345e5a JA |
423 | listed in decreasing order of precedence: |
424 | ||
425 | (\b( _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn )\b) | |
74091dd4 | 426 | Returns the value of _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn. This may be used to |
17345e5a JA |
427 | override the normal precedence of operators. |
428 | !\b! _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn | |
429 | True if _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn is false. | |
430 | _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b1 &\b&&\b& _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b2 | |
431 | True if both _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b1 and _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b2 are true. | |
432 | _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b1 |\b||\b| _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b2 | |
433 | True if either _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b1 or _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b2 is true. | |
434 | ||
435 | The &\b&&\b& and |\b||\b| operators do not evaluate _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b2 if the value | |
74091dd4 | 436 | of _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b1 is sufficient to determine the return value of |
17345e5a JA |
437 | the entire conditional expression. |
438 | ||
0001803f | 439 | f\bfo\bor\br _\bn_\ba_\bm_\be [ [ i\bin\bn [ _\bw_\bo_\br_\bd _\b._\b._\b. ] ] ; ] d\bdo\bo _\bl_\bi_\bs_\bt ; d\bdo\bon\bne\be |
17345e5a JA |
440 | The list of words following i\bin\bn is expanded, generating a list of |
441 | items. The variable _\bn_\ba_\bm_\be is set to each element of this list in | |
74091dd4 CR |
442 | turn, and _\bl_\bi_\bs_\bt is executed each time. If the i\bin\bn _\bw_\bo_\br_\bd is omit- |
443 | ted, the f\bfo\bor\br command executes _\bl_\bi_\bs_\bt once for each positional pa- | |
444 | rameter that is set (see P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS below). The return status | |
445 | is the exit status of the last command that executes. If the | |
17345e5a JA |
446 | expansion of the items following i\bin\bn results in an empty list, no |
447 | commands are executed, and the return status is 0. | |
448 | ||
449 | f\bfo\bor\br (( _\be_\bx_\bp_\br_\b1 ; _\be_\bx_\bp_\br_\b2 ; _\be_\bx_\bp_\br_\b3 )) ; d\bdo\bo _\bl_\bi_\bs_\bt ; d\bdo\bon\bne\be | |
450 | First, the arithmetic expression _\be_\bx_\bp_\br_\b1 is evaluated according to | |
74091dd4 CR |
451 | the rules described below under A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN. The |
452 | arithmetic expression _\be_\bx_\bp_\br_\b2 is then evaluated repeatedly until | |
453 | it evaluates to zero. Each time _\be_\bx_\bp_\br_\b2 evaluates to a non-zero | |
454 | value, _\bl_\bi_\bs_\bt is executed and the arithmetic expression _\be_\bx_\bp_\br_\b3 is | |
455 | evaluated. If any expression is omitted, it behaves as if it | |
17345e5a JA |
456 | evaluates to 1. The return value is the exit status of the last |
457 | command in _\bl_\bi_\bs_\bt that is executed, or false if any of the expres- | |
458 | sions is invalid. | |
459 | ||
460 | s\bse\bel\ble\bec\bct\bt _\bn_\ba_\bm_\be [ i\bin\bn _\bw_\bo_\br_\bd ] ; d\bdo\bo _\bl_\bi_\bs_\bt ; d\bdo\bon\bne\be | |
461 | The list of words following i\bin\bn is expanded, generating a list of | |
74091dd4 CR |
462 | items, and the set of expanded words is printed on the standard |
463 | error, each preceded by a number. If the i\bin\bn _\bw_\bo_\br_\bd is omitted, | |
464 | the positional parameters are printed (see P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS below). | |
465 | s\bse\bel\ble\bec\bct\bt then displays the P\bPS\bS3\b3 prompt and reads a line from the | |
466 | standard input. If the line consists of a number corresponding | |
467 | to one of the displayed words, then the value of _\bn_\ba_\bm_\be is set to | |
468 | that word. If the line is empty, the words and prompt are dis- | |
469 | played again. If EOF is read, the s\bse\bel\ble\bec\bct\bt command completes and | |
470 | returns 1. Any other value read causes _\bn_\ba_\bm_\be to be set to null. | |
471 | The line read is saved in the variable R\bRE\bEP\bPL\bLY\bY. The _\bl_\bi_\bs_\bt is exe- | |
472 | cuted after each selection until a b\bbr\bre\bea\bak\bk command is executed. | |
473 | The exit status of s\bse\bel\ble\bec\bct\bt is the exit status of the last command | |
474 | executed in _\bl_\bi_\bs_\bt, or zero if no commands were executed. | |
17345e5a JA |
475 | |
476 | c\bca\bas\bse\be _\bw_\bo_\br_\bd i\bin\bn [ [(] _\bp_\ba_\bt_\bt_\be_\br_\bn [ |\b| _\bp_\ba_\bt_\bt_\be_\br_\bn ] ... ) _\bl_\bi_\bs_\bt ;; ] ... e\bes\bsa\bac\bc | |
477 | A c\bca\bas\bse\be command first expands _\bw_\bo_\br_\bd, and tries to match it against | |
74091dd4 | 478 | each _\bp_\ba_\bt_\bt_\be_\br_\bn in turn, using the matching rules described under |
d233b485 | 479 | P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg below. The _\bw_\bo_\br_\bd is expanded using tilde expan- |
74091dd4 CR |
480 | sion, parameter and variable expansion, arithmetic expansion, |
481 | command substitution, process substitution and quote removal. | |
d233b485 | 482 | Each _\bp_\ba_\bt_\bt_\be_\br_\bn examined is expanded using tilde expansion, parame- |
74091dd4 CR |
483 | ter and variable expansion, arithmetic expansion, command sub- |
484 | stitution, process substitution, and quote removal. If the n\bno\bo-\b- | |
485 | c\bca\bas\bse\bem\bma\bat\btc\bch\bh shell option is enabled, the match is performed with- | |
486 | out regard to the case of alphabetic characters. When a match | |
487 | is found, the corresponding _\bl_\bi_\bs_\bt is executed. If the ;\b;;\b; opera- | |
488 | tor is used, no subsequent matches are attempted after the first | |
489 | pattern match. Using ;\b;&\b& in place of ;\b;;\b; causes execution to con- | |
490 | tinue with the _\bl_\bi_\bs_\bt associated with the next set of patterns. | |
491 | Using ;\b;;\b;&\b& in place of ;\b;;\b; causes the shell to test the next pat- | |
492 | tern list in the statement, if any, and execute any associated | |
493 | _\bl_\bi_\bs_\bt on a successful match, continuing the case statement execu- | |
494 | tion as if the pattern list had not matched. The exit status is | |
495 | zero if no pattern matches. Otherwise, it is the exit status of | |
496 | the last command executed in _\bl_\bi_\bs_\bt. | |
17345e5a | 497 | |
ac50fbac | 498 | i\bif\bf _\bl_\bi_\bs_\bt; t\bth\bhe\ben\bn _\bl_\bi_\bs_\bt; [ e\bel\bli\bif\bf _\bl_\bi_\bs_\bt; t\bth\bhe\ben\bn _\bl_\bi_\bs_\bt; ] ... [ e\bel\bls\bse\be _\bl_\bi_\bs_\bt; ] f\bfi\bi |
74091dd4 CR |
499 | The i\bif\bf _\bl_\bi_\bs_\bt is executed. If its exit status is zero, the t\bth\bhe\ben\bn |
500 | _\bl_\bi_\bs_\bt is executed. Otherwise, each e\bel\bli\bif\bf _\bl_\bi_\bs_\bt is executed in | |
501 | turn, and if its exit status is zero, the corresponding t\bth\bhe\ben\bn | |
17345e5a | 502 | _\bl_\bi_\bs_\bt is executed and the command completes. Otherwise, the e\bel\bls\bse\be |
74091dd4 | 503 | _\bl_\bi_\bs_\bt is executed, if present. The exit status is the exit sta- |
17345e5a JA |
504 | tus of the last command executed, or zero if no condition tested |
505 | true. | |
506 | ||
495aee44 CR |
507 | w\bwh\bhi\bil\ble\be _\bl_\bi_\bs_\bt_\b-_\b1; d\bdo\bo _\bl_\bi_\bs_\bt_\b-_\b2; d\bdo\bon\bne\be |
508 | u\bun\bnt\bti\bil\bl _\bl_\bi_\bs_\bt_\b-_\b1; d\bdo\bo _\bl_\bi_\bs_\bt_\b-_\b2; d\bdo\bon\bne\be | |
74091dd4 | 509 | The w\bwh\bhi\bil\ble\be command continuously executes the list _\bl_\bi_\bs_\bt_\b-_\b2 as long |
495aee44 | 510 | as the last command in the list _\bl_\bi_\bs_\bt_\b-_\b1 returns an exit status of |
74091dd4 | 511 | zero. The u\bun\bnt\bti\bil\bl command is identical to the w\bwh\bhi\bil\ble\be command, ex- |
8868edaf CR |
512 | cept that the test is negated: _\bl_\bi_\bs_\bt_\b-_\b2 is executed as long as the |
513 | last command in _\bl_\bi_\bs_\bt_\b-_\b1 returns a non-zero exit status. The exit | |
514 | status of the w\bwh\bhi\bil\ble\be and u\bun\bnt\bti\bil\bl commands is the exit status of the | |
515 | last command executed in _\bl_\bi_\bs_\bt_\b-_\b2, or zero if none was executed. | |
17345e5a JA |
516 | |
517 | C\bCo\bop\bpr\bro\boc\bce\bes\bss\bse\bes\bs | |
518 | A _\bc_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs is a shell command preceded by the c\bco\bop\bpr\bro\boc\bc reserved word. A | |
74091dd4 CR |
519 | coprocess is executed asynchronously in a subshell, as if the command |
520 | had been terminated with the &\b& control operator, with a two-way pipe | |
17345e5a JA |
521 | established between the executing shell and the coprocess. |
522 | ||
74091dd4 | 523 | The syntax for a coprocess is: |
17345e5a JA |
524 | |
525 | c\bco\bop\bpr\bro\boc\bc [_\bN_\bA_\bM_\bE] _\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\br_\be_\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn_\bs] | |
526 | ||
74091dd4 CR |
527 | This creates a coprocess named _\bN_\bA_\bM_\bE. _\bc_\bo_\bm_\bm_\ba_\bn_\bd may be either a simple |
528 | command or a compound command (see above). _\bN_\bA_\bM_\bE is a shell variable | |
529 | name. If _\bN_\bA_\bM_\bE is not supplied, the default name is C\bCO\bOP\bPR\bRO\bOC\bC. | |
530 | ||
531 | The recommended form to use for a coprocess is | |
532 | ||
533 | c\bco\bop\bpr\bro\boc\bc _\bN_\bA_\bM_\bE { _\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\br_\be_\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn_\bs]; } | |
534 | ||
535 | This form is recommended because simple commands result in the copro- | |
536 | cess always being named C\bCO\bOP\bPR\bRO\bOC\bC, and it is simpler to use and more com- | |
537 | plete than the other compound commands. | |
538 | ||
539 | If _\bc_\bo_\bm_\bm_\ba_\bn_\bd is a compound command, _\bN_\bA_\bM_\bE is optional. The word following | |
540 | c\bco\bop\bpr\bro\boc\bc determines whether that word is interpreted as a variable name: | |
541 | it is interpreted as _\bN_\bA_\bM_\bE if it is not a reserved word that introduces | |
542 | a compound command. If _\bc_\bo_\bm_\bm_\ba_\bn_\bd is a simple command, _\bN_\bA_\bM_\bE is not al- | |
543 | lowed; this is to avoid confusion between _\bN_\bA_\bM_\bE and the first word of | |
544 | the simple command. | |
545 | ||
546 | When the coprocess is executed, the shell creates an array variable | |
547 | (see A\bAr\brr\bra\bay\bys\bs below) named _\bN_\bA_\bM_\bE in the context of the executing shell. | |
548 | The standard output of _\bc_\bo_\bm_\bm_\ba_\bn_\bd is connected via a pipe to a file de- | |
549 | scriptor in the executing shell, and that file descriptor is assigned | |
550 | to _\bN_\bA_\bM_\bE[0]. The standard input of _\bc_\bo_\bm_\bm_\ba_\bn_\bd is connected via a pipe to a | |
551 | file descriptor in the executing shell, and that file descriptor is as- | |
552 | signed to _\bN_\bA_\bM_\bE[1]. This pipe is established before any redirections | |
553 | specified by the command (see R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN below). The file descriptors | |
554 | can be utilized as arguments to shell commands and redirections using | |
555 | standard word expansions. Other than those created to execute command | |
556 | and process substitutions, the file descriptors are not available in | |
557 | subshells. | |
558 | ||
559 | The process ID of the shell spawned to execute the coprocess is avail- | |
560 | able as the value of the variable _\bN_\bA_\bM_\bE_PID. The w\bwa\bai\bit\bt builtin command | |
561 | may be used to wait for the coprocess to terminate. | |
ac50fbac CR |
562 | |
563 | Since the coprocess is created as an asynchronous command, the c\bco\bop\bpr\bro\boc\bc | |
564 | command always returns success. The return status of a coprocess is | |
565 | the exit status of _\bc_\bo_\bm_\bm_\ba_\bn_\bd. | |
17345e5a JA |
566 | |
567 | S\bSh\bhe\bel\bll\bl F\bFu\bun\bnc\bct\bti\bio\bon\bn D\bDe\bef\bfi\bin\bni\bit\bti\bio\bon\bns\bs | |
495aee44 CR |
568 | A shell function is an object that is called like a simple command and |
569 | executes a compound command with a new set of positional parameters. | |
17345e5a JA |
570 | Shell functions are declared as follows: |
571 | ||
8868edaf CR |
572 | _\bf_\bn_\ba_\bm_\be () _\bc_\bo_\bm_\bp_\bo_\bu_\bn_\bd_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\br_\be_\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn] |
573 | f\bfu\bun\bnc\bct\bti\bio\bon\bn _\bf_\bn_\ba_\bm_\be [()] _\bc_\bo_\bm_\bp_\bo_\bu_\bn_\bd_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\br_\be_\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn] | |
574 | This defines a function named _\bf_\bn_\ba_\bm_\be. The reserved word f\bfu\bun\bnc\bct\bti\bio\bon\bn | |
495aee44 CR |
575 | is optional. If the f\bfu\bun\bnc\bct\bti\bio\bon\bn reserved word is supplied, the |
576 | parentheses are optional. The _\bb_\bo_\bd_\by of the function is the com- | |
577 | pound command _\bc_\bo_\bm_\bp_\bo_\bu_\bn_\bd_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd (see C\bCo\bom\bmp\bpo\bou\bun\bnd\bd C\bCo\bom\bmm\bma\ban\bnd\bds\bs above). | |
578 | That command is usually a _\bl_\bi_\bs_\bt of commands between { and }, but | |
74091dd4 CR |
579 | may be any command listed under C\bCo\bom\bmp\bpo\bou\bun\bnd\bd C\bCo\bom\bmm\bma\ban\bnd\bds\bs above. If the |
580 | f\bfu\bun\bnc\bct\bti\bio\bon\bn reserved word is used, but the parentheses are not sup- | |
581 | plied, the braces are recommended. _\bc_\bo_\bm_\bp_\bo_\bu_\bn_\bd_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd is executed | |
582 | whenever _\bf_\bn_\ba_\bm_\be is specified as the name of a simple command. | |
583 | When in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, _\bf_\bn_\ba_\bm_\be must be a valid shell _\bn_\ba_\bm_\be and may not | |
584 | be the name of one of the POSIX _\bs_\bp_\be_\bc_\bi_\ba_\bl _\bb_\bu_\bi_\bl_\bt_\bi_\bn_\bs. In default | |
585 | mode, a function name can be any unquoted shell word that does | |
586 | not contain $\b$. Any redirections (see R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN below) speci- | |
587 | fied when a function is defined are performed when the function | |
588 | is executed. The exit status of a function definition is zero | |
589 | unless a syntax error occurs or a readonly function with the | |
590 | same name already exists. When executed, the exit status of a | |
591 | function is the exit status of the last command executed in the | |
592 | body. (See F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS below.) | |
17345e5a JA |
593 | |
594 | C\bCO\bOM\bMM\bME\bEN\bNT\bTS\bS | |
595 | In a non-interactive shell, or an interactive shell in which the i\bin\bnt\bte\ber\br-\b- | |
ac50fbac CR |
596 | a\bac\bct\bti\biv\bve\be_\b_c\bco\bom\bmm\bme\ben\bnt\bts\bs option to the s\bsh\bho\bop\bpt\bt builtin is enabled (see S\bSH\bHE\bEL\bLL\bL |
597 | B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below), a word beginning with #\b# causes that word and | |
598 | all remaining characters on that line to be ignored. An interactive | |
599 | shell without the i\bin\bnt\bte\ber\bra\bac\bct\bti\biv\bve\be_\b_c\bco\bom\bmm\bme\ben\bnt\bts\bs option enabled does not allow | |
17345e5a JA |
600 | comments. The i\bin\bnt\bte\ber\bra\bac\bct\bti\biv\bve\be_\b_c\bco\bom\bmm\bme\ben\bnt\bts\bs option is on by default in interac- |
601 | tive shells. | |
602 | ||
603 | Q\bQU\bUO\bOT\bTI\bIN\bNG\bG | |
ac50fbac CR |
604 | _\bQ_\bu_\bo_\bt_\bi_\bn_\bg is used to remove the special meaning of certain characters or |
605 | words to the shell. Quoting can be used to disable special treatment | |
17345e5a JA |
606 | for special characters, to prevent reserved words from being recognized |
607 | as such, and to prevent parameter expansion. | |
608 | ||
ac50fbac | 609 | Each of the _\bm_\be_\bt_\ba_\bc_\bh_\ba_\br_\ba_\bc_\bt_\be_\br_\bs listed above under D\bDE\bEF\bFI\bIN\bNI\bIT\bTI\bIO\bON\bNS\bS has special |
17345e5a JA |
610 | meaning to the shell and must be quoted if it is to represent itself. |
611 | ||
ac50fbac | 612 | When the command history expansion facilities are being used (see H\bHI\bIS\bS-\b- |
17345e5a JA |
613 | T\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN below), the _\bh_\bi_\bs_\bt_\bo_\br_\by _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn character, usually !\b!, must |
614 | be quoted to prevent history expansion. | |
615 | ||
ac50fbac | 616 | There are three quoting mechanisms: the _\be_\bs_\bc_\ba_\bp_\be _\bc_\bh_\ba_\br_\ba_\bc_\bt_\be_\br, single |
17345e5a JA |
617 | quotes, and double quotes. |
618 | ||
ac50fbac | 619 | A non-quoted backslash (\\b\) is the _\be_\bs_\bc_\ba_\bp_\be _\bc_\bh_\ba_\br_\ba_\bc_\bt_\be_\br. It preserves the |
17345e5a | 620 | literal value of the next character that follows, with the exception of |
8868edaf CR |
621 | <newline>. If a \\b\<newline> pair appears, and the backslash is not it- |
622 | self quoted, the \\b\<newline> is treated as a line continuation (that is, | |
623 | it is removed from the input stream and effectively ignored). | |
17345e5a | 624 | |
ac50fbac | 625 | Enclosing characters in single quotes preserves the literal value of |
17345e5a JA |
626 | each character within the quotes. A single quote may not occur between |
627 | single quotes, even when preceded by a backslash. | |
628 | ||
ac50fbac CR |
629 | Enclosing characters in double quotes preserves the literal value of |
630 | all characters within the quotes, with the exception of $\b$, `\b`, \\b\, and, | |
a0c0a00f CR |
631 | when history expansion is enabled, !\b!. When the shell is in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, |
632 | the !\b! has no special meaning within double quotes, even when history | |
633 | expansion is enabled. The characters $\b$ and `\b` retain their special | |
634 | meaning within double quotes. The backslash retains its special mean- | |
635 | ing only when followed by one of the following characters: $\b$, `\b`, "\b", \\b\, | |
636 | or <\b<n\bne\bew\bwl\bli\bin\bne\be>\b>. A double quote may be quoted within double quotes by | |
637 | preceding it with a backslash. If enabled, history expansion will be | |
638 | performed unless an !\b! appearing in double quotes is escaped using a | |
639 | backslash. The backslash preceding the !\b! is not removed. | |
17345e5a | 640 | |
ac50fbac | 641 | The special parameters *\b* and @\b@ have special meaning when in double |
17345e5a JA |
642 | quotes (see P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS below). |
643 | ||
74091dd4 CR |
644 | Character sequences of the form $\b$'_\bs_\bt_\br_\bi_\bn_\bg' are treated as a special |
645 | variant of single quotes. The sequence expands to _\bs_\bt_\br_\bi_\bn_\bg, with back- | |
646 | slash-escaped characters in _\bs_\bt_\br_\bi_\bn_\bg replaced as specified by the ANSI C | |
647 | standard. Backslash escape sequences, if present, are decoded as fol- | |
648 | lows: | |
17345e5a JA |
649 | \\b\a\ba alert (bell) |
650 | \\b\b\bb backspace | |
0001803f CR |
651 | \\b\e\be |
652 | \\b\E\bE an escape character | |
17345e5a JA |
653 | \\b\f\bf form feed |
654 | \\b\n\bn new line | |
655 | \\b\r\br carriage return | |
656 | \\b\t\bt horizontal tab | |
657 | \\b\v\bv vertical tab | |
658 | \\b\\\b\ backslash | |
659 | \\b\'\b' single quote | |
0001803f | 660 | \\b\"\b" double quote |
a0c0a00f | 661 | \\b\?\b? question mark |
74091dd4 | 662 | \\b\_\bn_\bn_\bn the eight-bit character whose value is the octal value |
d233b485 | 663 | _\bn_\bn_\bn (one to three octal digits) |
74091dd4 | 664 | \\b\x\bx_\bH_\bH the eight-bit character whose value is the hexadecimal |
17345e5a | 665 | value _\bH_\bH (one or two hex digits) |
74091dd4 | 666 | \\b\u\bu_\bH_\bH_\bH_\bH the Unicode (ISO/IEC 10646) character whose value is the |
495aee44 CR |
667 | hexadecimal value _\bH_\bH_\bH_\bH (one to four hex digits) |
668 | \\b\U\bU_\bH_\bH_\bH_\bH_\bH_\bH_\bH_\bH | |
74091dd4 | 669 | the Unicode (ISO/IEC 10646) character whose value is the |
495aee44 | 670 | hexadecimal value _\bH_\bH_\bH_\bH_\bH_\bH_\bH_\bH (one to eight hex digits) |
17345e5a JA |
671 | \\b\c\bc_\bx a control-_\bx character |
672 | ||
74091dd4 | 673 | The expanded result is single-quoted, as if the dollar sign had not |
17345e5a JA |
674 | been present. |
675 | ||
0001803f | 676 | A double-quoted string preceded by a dollar sign ($\b$"_\bs_\bt_\br_\bi_\bn_\bg") will cause |
74091dd4 CR |
677 | the string to be translated according to the current locale. The _\bg_\be_\bt_\b- |
678 | _\bt_\be_\bx_\bt infrastructure performs the lookup and translation, using the | |
679 | L\bLC\bC_\b_M\bME\bES\bSS\bSA\bAG\bGE\bES\bS, T\bTE\bEX\bXT\bTD\bDO\bOM\bMA\bAI\bIN\bND\bDI\bIR\bR, and T\bTE\bEX\bXT\bTD\bDO\bOM\bMA\bAI\bIN\bN shell variables. If the | |
680 | current locale is C\bC or P\bPO\bOS\bSI\bIX\bX, if there are no translations available, | |
681 | or if the string is not translated, the dollar sign is ignored. This | |
682 | is a form of double quoting, so the string remains double-quoted by de- | |
683 | fault, whether or not it is translated and replaced. If the n\bno\boe\bex\bx-\b- | |
684 | p\bpa\ban\bnd\bd_\b_t\btr\bra\ban\bns\bsl\bla\bat\bti\bio\bon\bn option is enabled using the s\bsh\bho\bop\bpt\bt builtin, translated | |
685 | strings are single-quoted instead of double-quoted. See the descrip- | |
686 | tion of s\bsh\bho\bop\bpt\bt below under S\bSH\bHE\bEL\bLL\bLBUILTINC\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS. | |
17345e5a JA |
687 | |
688 | P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS | |
74091dd4 | 689 | A _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an entity that stores values. It can be a _\bn_\ba_\bm_\be, a num- |
17345e5a | 690 | ber, or one of the special characters listed below under S\bSp\bpe\bec\bci\bia\bal\bl P\bPa\bar\bra\bam\bm-\b- |
74091dd4 CR |
691 | e\bet\bte\ber\brs\bs. A _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be is a parameter denoted by a _\bn_\ba_\bm_\be. A variable has a |
692 | _\bv_\ba_\bl_\bu_\be and zero or more _\ba_\bt_\bt_\br_\bi_\bb_\bu_\bt_\be_\bs. Attributes are assigned using the | |
a0c0a00f | 693 | d\bde\bec\bcl\bla\bar\bre\be builtin command (see d\bde\bec\bcl\bla\bar\bre\be below in S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS). |
17345e5a JA |
694 | |
695 | A parameter is set if it has been assigned a value. The null string is | |
74091dd4 | 696 | a valid value. Once a variable is set, it may be unset only by using |
17345e5a JA |
697 | the u\bun\bns\bse\bet\bt builtin command (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). |
698 | ||
699 | A _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be may be assigned to by a statement of the form | |
700 | ||
701 | _\bn_\ba_\bm_\be=[_\bv_\ba_\bl_\bu_\be] | |
702 | ||
74091dd4 CR |
703 | If _\bv_\ba_\bl_\bu_\be is not given, the variable is assigned the null string. All |
704 | _\bv_\ba_\bl_\bu_\be_\bs undergo tilde expansion, parameter and variable expansion, com- | |
705 | mand substitution, arithmetic expansion, and quote removal (see E\bEX\bXP\bPA\bAN\bN-\b- | |
17345e5a JA |
706 | S\bSI\bIO\bON\bN below). If the variable has its i\bin\bnt\bte\beg\bge\ber\br attribute set, then _\bv_\ba_\bl_\bu_\be |
707 | is evaluated as an arithmetic expression even if the $((...)) expansion | |
74091dd4 CR |
708 | is not used (see A\bAr\bri\bit\bth\bhm\bme\bet\bti\bic\bc E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn below). Word splitting and path- |
709 | name expansion are not performed. Assignment statements may also ap- | |
710 | pear as arguments to the a\bal\bli\bia\bas\bs, d\bde\bec\bcl\bla\bar\bre\be, t\bty\byp\bpe\bes\bse\bet\bt, e\bex\bxp\bpo\bor\brt\bt, r\bre\bea\bad\bdo\bon\bnl\bly\by, and | |
711 | l\blo\boc\bca\bal\bl builtin commands (_\bd_\be_\bc_\bl_\ba_\br_\ba_\bt_\bi_\bo_\bn commands). When in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, | |
712 | these builtins may appear in a command after one or more instances of | |
713 | the c\bco\bom\bmm\bma\ban\bnd\bd builtin and retain these assignment statement properties. | |
714 | ||
715 | In the context where an assignment statement is assigning a value to a | |
17345e5a | 716 | shell variable or array index, the += operator can be used to append to |
74091dd4 CR |
717 | or add to the variable's previous value. This includes arguments to |
718 | builtin commands such as d\bde\bec\bcl\bla\bar\bre\be that accept assignment statements | |
a0c0a00f | 719 | (_\bd_\be_\bc_\bl_\ba_\br_\ba_\bt_\bi_\bo_\bn commands). When += is applied to a variable for which the |
74091dd4 | 720 | i\bin\bnt\bte\beg\bge\ber\br attribute has been set, _\bv_\ba_\bl_\bu_\be is evaluated as an arithmetic ex- |
8868edaf | 721 | pression and added to the variable's current value, which is also eval- |
74091dd4 CR |
722 | uated. When += is applied to an array variable using compound assign- |
723 | ment (see A\bAr\brr\bra\bay\bys\bs below), the variable's value is not unset (as it is | |
724 | when using =), and new values are appended to the array beginning at | |
725 | one greater than the array's maximum index (for indexed arrays) or | |
726 | added as additional key-value pairs in an associative array. When ap- | |
727 | plied to a string-valued variable, _\bv_\ba_\bl_\bu_\be is expanded and appended to | |
a0c0a00f | 728 | the variable's value. |
17345e5a | 729 | |
ac50fbac | 730 | A variable can be assigned the _\bn_\ba_\bm_\be_\br_\be_\bf attribute using the -\b-n\bn option to |
74091dd4 CR |
731 | the d\bde\bec\bcl\bla\bar\bre\be or l\blo\boc\bca\bal\bl builtin commands (see the descriptions of d\bde\bec\bcl\bla\bar\bre\be |
732 | and l\blo\boc\bca\bal\bl below) to create a _\bn_\ba_\bm_\be_\br_\be_\bf, or a reference to another vari- | |
733 | able. This allows variables to be manipulated indirectly. Whenever | |
734 | the nameref variable is referenced, assigned to, unset, or has its at- | |
735 | tributes modified (other than using or changing the _\bn_\ba_\bm_\be_\br_\be_\bf attribute | |
736 | itself), the operation is actually performed on the variable specified | |
737 | by the nameref variable's value. A nameref is commonly used within | |
a0c0a00f | 738 | shell functions to refer to a variable whose name is passed as an argu- |
74091dd4 | 739 | ment to the function. For instance, if a variable name is passed to a |
a0c0a00f | 740 | shell function as its first argument, running |
ac50fbac | 741 | declare -n ref=$1 |
74091dd4 | 742 | inside the function creates a nameref variable r\bre\bef\bf whose value is the |
ac50fbac | 743 | variable name passed as the first argument. References and assignments |
74091dd4 CR |
744 | to r\bre\bef\bf, and changes to its attributes, are treated as references, as- |
745 | signments, and attribute modifications to the variable whose name was | |
746 | passed as $\b$1\b1. If the control variable in a f\bfo\bor\br loop has the nameref | |
747 | attribute, the list of words can be a list of shell variables, and a | |
748 | name reference will be established for each word in the list, in turn, | |
a0c0a00f | 749 | when the loop is executed. Array variables cannot be given the n\bna\bam\bme\ber\bre\bef\bf |
74091dd4 CR |
750 | attribute. However, nameref variables can reference array variables |
751 | and subscripted array variables. Namerefs can be unset using the -\b-n\bn | |
752 | option to the u\bun\bns\bse\bet\bt builtin. Otherwise, if u\bun\bns\bse\bet\bt is executed with the | |
753 | name of a nameref variable as an argument, the variable referenced by | |
ac50fbac CR |
754 | the nameref variable will be unset. |
755 | ||
17345e5a | 756 | P\bPo\bos\bsi\bit\bti\bio\bon\bna\bal\bl P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs |
74091dd4 | 757 | A _\bp_\bo_\bs_\bi_\bt_\bi_\bo_\bn_\ba_\bl _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is a parameter denoted by one or more digits, |
17345e5a | 758 | other than the single digit 0. Positional parameters are assigned from |
74091dd4 CR |
759 | the shell's arguments when it is invoked, and may be reassigned using |
760 | the s\bse\bet\bt builtin command. Positional parameters may not be assigned to | |
761 | with assignment statements. The positional parameters are temporarily | |
17345e5a JA |
762 | replaced when a shell function is executed (see F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS below). |
763 | ||
74091dd4 | 764 | When a positional parameter consisting of more than a single digit is |
17345e5a JA |
765 | expanded, it must be enclosed in braces (see E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN below). |
766 | ||
767 | S\bSp\bpe\bec\bci\bia\bal\bl P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs | |
74091dd4 | 768 | The shell treats several parameters specially. These parameters may |
17345e5a | 769 | only be referenced; assignment to them is not allowed. |
74091dd4 CR |
770 | *\b* Expands to the positional parameters, starting from one. When |
771 | the expansion is not within double quotes, each positional pa- | |
772 | rameter expands to a separate word. In contexts where it is | |
ac50fbac | 773 | performed, those words are subject to further word splitting and |
74091dd4 CR |
774 | pathname expansion. When the expansion occurs within double |
775 | quotes, it expands to a single word with the value of each pa- | |
776 | rameter separated by the first character of the I\bIF\bFS\bS special | |
777 | variable. That is, "$\b$*\b*" is equivalent to "$\b$1\b1_\bc$\b$2\b2_\bc.\b..\b..\b.", where _\bc | |
ac50fbac | 778 | is the first character of the value of the I\bIF\bFS\bS variable. If I\bIF\bFS\bS |
74091dd4 | 779 | is unset, the parameters are separated by spaces. If I\bIF\bFS\bS is |
a0c0a00f | 780 | null, the parameters are joined without intervening separators. |
74091dd4 CR |
781 | @\b@ Expands to the positional parameters, starting from one. In |
782 | contexts where word splitting is performed, this expands each | |
783 | positional parameter to a separate word; if not within double | |
784 | quotes, these words are subject to word splitting. In contexts | |
785 | where word splitting is not performed, this expands to a single | |
786 | word with each positional parameter separated by a space. When | |
787 | the expansion occurs within double quotes, each parameter ex- | |
788 | pands to a separate word. That is, "$\b$@\b@" is equivalent to "$\b$1\b1" | |
789 | "$\b$2\b2" ... If the double-quoted expansion occurs within a word, | |
790 | the expansion of the first parameter is joined with the begin- | |
791 | ning part of the original word, and the expansion of the last | |
792 | parameter is joined with the last part of the original word. | |
793 | When there are no positional parameters, "$\b$@\b@" and $\b$@\b@ expand to | |
17345e5a JA |
794 | nothing (i.e., they are removed). |
795 | #\b# Expands to the number of positional parameters in decimal. | |
74091dd4 | 796 | ?\b? Expands to the exit status of the most recently executed fore- |
17345e5a | 797 | ground pipeline. |
74091dd4 CR |
798 | -\b- Expands to the current option flags as specified upon invoca- |
799 | tion, by the s\bse\bet\bt builtin command, or those set by the shell it- | |
8868edaf | 800 | self (such as the -\b-i\bi option). |
74091dd4 CR |
801 | $\b$ Expands to the process ID of the shell. In a subshell, it ex- |
802 | pands to the process ID of the current shell, not the subshell. | |
8868edaf CR |
803 | !\b! Expands to the process ID of the job most recently placed into |
804 | the background, whether executed as an asynchronous command or | |
ac50fbac | 805 | using the b\bbg\bg builtin (see J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL below). |
8868edaf | 806 | 0\b0 Expands to the name of the shell or shell script. This is set |
17345e5a | 807 | at shell initialization. If b\bba\bas\bsh\bh is invoked with a file of com- |
8868edaf CR |
808 | mands, $\b$0\b0 is set to the name of that file. If b\bba\bas\bsh\bh is started |
809 | with the -\b-c\bc option, then $\b$0\b0 is set to the first argument after | |
810 | the string to be executed, if one is present. Otherwise, it is | |
811 | set to the filename used to invoke b\bba\bas\bsh\bh, as given by argument | |
17345e5a | 812 | zero. |
17345e5a JA |
813 | |
814 | S\bSh\bhe\bel\bll\bl V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs | |
815 | The following variables are set by the shell: | |
816 | ||
8868edaf CR |
817 | _\b_ At shell startup, set to the pathname used to invoke the shell |
818 | or shell script being executed as passed in the environment or | |
819 | argument list. Subsequently, expands to the last argument to | |
820 | the previous simple command executed in the foreground, after | |
821 | expansion. Also set to the full pathname used to invoke each | |
822 | command executed and placed in the environment exported to that | |
823 | command. When checking mail, this parameter holds the name of | |
824 | the mail file currently being checked. | |
825 | B\bBA\bAS\bSH\bH Expands to the full filename used to invoke this instance of | |
17345e5a | 826 | b\bba\bas\bsh\bh. |
0001803f | 827 | B\bBA\bAS\bSH\bHO\bOP\bPT\bTS\bS |
8868edaf CR |
828 | A colon-separated list of enabled shell options. Each word in |
829 | the list is a valid argument for the -\b-s\bs option to the s\bsh\bho\bop\bpt\bt | |
0001803f | 830 | builtin command (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). The options |
8868edaf CR |
831 | appearing in B\bBA\bAS\bSH\bHO\bOP\bPT\bTS\bS are those reported as _\bo_\bn by s\bsh\bho\bop\bpt\bt. If |
832 | this variable is in the environment when b\bba\bas\bsh\bh starts up, each | |
833 | shell option in the list will be enabled before reading any | |
0001803f | 834 | startup files. This variable is read-only. |
17345e5a | 835 | B\bBA\bAS\bSH\bHP\bPI\bID\bD |
8868edaf CR |
836 | Expands to the process ID of the current b\bba\bas\bsh\bh process. This |
837 | differs from $\b$$\b$ under certain circumstances, such as subshells | |
838 | that do not require b\bba\bas\bsh\bh to be re-initialized. Assignments to | |
839 | B\bBA\bAS\bSH\bHP\bPI\bID\bD have no effect. If B\bBA\bAS\bSH\bHP\bPI\bID\bD is unset, it loses its spe- | |
d233b485 | 840 | cial properties, even if it is subsequently reset. |
17345e5a | 841 | B\bBA\bAS\bSH\bH_\b_A\bAL\bLI\bIA\bAS\bSE\bES\bS |
8868edaf CR |
842 | An associative array variable whose members correspond to the |
843 | internal list of aliases as maintained by the a\bal\bli\bia\bas\bs builtin. | |
844 | Elements added to this array appear in the alias list; however, | |
845 | unsetting array elements currently does not cause aliases to be | |
a0c0a00f CR |
846 | removed from the alias list. If B\bBA\bAS\bSH\bH_\b_A\bAL\bLI\bIA\bAS\bSE\bES\bS is unset, it loses |
847 | its special properties, even if it is subsequently reset. | |
17345e5a | 848 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGC\bC |
8868edaf | 849 | An array variable whose values are the number of parameters in |
17345e5a | 850 | each frame of the current b\bba\bas\bsh\bh execution call stack. The number |
8868edaf CR |
851 | of parameters to the current subroutine (shell function or |
852 | script executed with .\b. or s\bso\bou\bur\brc\bce\be) is at the top of the stack. | |
853 | When a subroutine is executed, the number of parameters passed | |
17345e5a | 854 | is pushed onto B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGC\bC. The shell sets B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGC\bC only when in |
8868edaf CR |
855 | extended debugging mode (see the description of the e\bex\bxt\btd\bde\beb\bbu\bug\bg op- |
856 | tion to the s\bsh\bho\bop\bpt\bt builtin below). Setting e\bex\bxt\btd\bde\beb\bbu\bug\bg after the | |
d233b485 | 857 | shell has started to execute a script, or referencing this vari- |
8868edaf | 858 | able when e\bex\bxt\btd\bde\beb\bbu\bug\bg is not set, may result in inconsistent val- |
d233b485 | 859 | ues. |
17345e5a | 860 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV |
8868edaf | 861 | An array variable containing all of the parameters in the cur- |
17345e5a | 862 | rent b\bba\bas\bsh\bh execution call stack. The final parameter of the last |
8868edaf | 863 | subroutine call is at the top of the stack; the first parameter |
17345e5a | 864 | of the initial call is at the bottom. When a subroutine is exe- |
8868edaf CR |
865 | cuted, the parameters supplied are pushed onto B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV. The |
866 | shell sets B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV only when in extended debugging mode (see | |
867 | the description of the e\bex\bxt\btd\bde\beb\bbu\bug\bg option to the s\bsh\bho\bop\bpt\bt builtin be- | |
868 | low). Setting e\bex\bxt\btd\bde\beb\bbu\bug\bg after the shell has started to execute a | |
869 | script, or referencing this variable when e\bex\bxt\btd\bde\beb\bbu\bug\bg is not set, | |
d233b485 CR |
870 | may result in inconsistent values. |
871 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV0\b0 | |
8868edaf | 872 | When referenced, this variable expands to the name of the shell |
d233b485 | 873 | or shell script (identical to $\b$0\b0; see the description of special |
8868edaf CR |
874 | parameter 0 above). Assignment to B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV0\b0 causes the value |
875 | assigned to also be assigned to $\b$0\b0. If B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV0\b0 is unset, it | |
d233b485 | 876 | loses its special properties, even if it is subsequently reset. |
17345e5a | 877 | B\bBA\bAS\bSH\bH_\b_C\bCM\bMD\bDS\bS |
8868edaf CR |
878 | An associative array variable whose members correspond to the |
879 | internal hash table of commands as maintained by the h\bha\bas\bsh\bh | |
17345e5a | 880 | builtin. Elements added to this array appear in the hash table; |
8868edaf CR |
881 | however, unsetting array elements currently does not cause com- |
882 | mand names to be removed from the hash table. If B\bBA\bAS\bSH\bH_\b_C\bCM\bMD\bDS\bS is | |
883 | unset, it loses its special properties, even if it is subse- | |
a0c0a00f | 884 | quently reset. |
17345e5a | 885 | B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMM\bMA\bAN\bND\bD |
8868edaf | 886 | The command currently being executed or about to be executed, |
17345e5a | 887 | unless the shell is executing a command as the result of a trap, |
8868edaf CR |
888 | in which case it is the command executing at the time of the |
889 | trap. If B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMM\bMA\bAN\bND\bD is unset, it loses its special proper- | |
890 | ties, even if it is subsequently reset. | |
17345e5a JA |
891 | B\bBA\bAS\bSH\bH_\b_E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN_\b_S\bST\bTR\bRI\bIN\bNG\bG |
892 | The command argument to the -\b-c\bc invocation option. | |
893 | B\bBA\bAS\bSH\bH_\b_L\bLI\bIN\bNE\bEN\bNO\bO | |
495aee44 CR |
894 | An array variable whose members are the line numbers in source |
895 | files where each corresponding member of F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE was invoked. | |
896 | $\b${\b{B\bBA\bAS\bSH\bH_\b_L\bLI\bIN\bNE\bEN\bNO\bO[\b[_\b$_\bi]\b]}\b} is the line number in the source file | |
897 | ($\b${\b{B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE[\b[_\b$_\bi_\b+_\b1]\b]}\b}) where $\b${\b{F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE[\b[_\b$_\bi]\b]}\b} was called (or | |
898 | $\b${\b{B\bBA\bAS\bSH\bH_\b_L\bLI\bIN\bNE\bEN\bNO\bO[\b[_\b$_\bi_\b-_\b1]\b]}\b} if referenced within another shell func- | |
899 | tion). Use L\bLI\bIN\bNE\bEN\bNO\bO to obtain the current line number. | |
a0c0a00f CR |
900 | B\bBA\bAS\bSH\bH_\b_L\bLO\bOA\bAD\bDA\bAB\bBL\bLE\bES\bS_\b_P\bPA\bAT\bTH\bH |
901 | A colon-separated list of directories in which the shell looks | |
902 | for dynamically loadable builtins specified by the e\ben\bna\bab\bbl\ble\be com- | |
903 | mand. | |
17345e5a JA |
904 | B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH |
905 | An array variable whose members are assigned by the =\b=~\b~ binary | |
906 | operator to the [\b[[\b[ conditional command. The element with index | |
8868edaf CR |
907 | 0 is the portion of the string matching the entire regular ex- |
908 | pression. The element with index _\bn is the portion of the string | |
909 | matching the _\bnth parenthesized subexpression. | |
17345e5a | 910 | B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE |
8868edaf CR |
911 | An array variable whose members are the source filenames where |
912 | the corresponding shell function names in the F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE array | |
913 | variable are defined. The shell function $\b${\b{F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE[\b[_\b$_\bi]\b]}\b} is de- | |
914 | fined in the file $\b${\b{B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE[\b[_\b$_\bi]\b]}\b} and called from | |
495aee44 | 915 | $\b${\b{B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE[\b[_\b$_\bi_\b+_\b1]\b]}\b}. |
17345e5a | 916 | B\bBA\bAS\bSH\bH_\b_S\bSU\bUB\bBS\bSH\bHE\bEL\bLL\bL |
8868edaf CR |
917 | Incremented by one within each subshell or subshell environment |
918 | when the shell begins executing in that environment. The ini- | |
919 | tial value is 0. If B\bBA\bAS\bSH\bH_\b_S\bSU\bUB\bBS\bSH\bHE\bEL\bLL\bL is unset, it loses its spe- | |
920 | cial properties, even if it is subsequently reset. | |
17345e5a JA |
921 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO |
922 | A readonly array variable whose members hold version information | |
ac50fbac | 923 | for this instance of b\bba\bas\bsh\bh. The values assigned to the array |
17345e5a | 924 | members are as follows: |
a0c0a00f CR |
925 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO[\b[0]\b] The major version number (the _\br_\be_\bl_\be_\ba_\bs_\be). |
926 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO[\b[1]\b] The minor version number (the _\bv_\be_\br_\bs_\bi_\bo_\bn). | |
17345e5a JA |
927 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO[\b[2]\b] The patch level. |
928 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO[\b[3]\b] The build version. | |
929 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO[\b[4]\b] The release status (e.g., _\bb_\be_\bt_\ba_\b1). | |
930 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO[\b[5]\b] The value of M\bMA\bAC\bCH\bHT\bTY\bYP\bPE\bE. | |
17345e5a | 931 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIO\bON\bN |
ac50fbac | 932 | Expands to a string describing the version of this instance of |
17345e5a | 933 | b\bba\bas\bsh\bh. |
17345e5a | 934 | C\bCO\bOM\bMP\bP_\b_C\bCW\bWO\bOR\bRD\bD |
ac50fbac | 935 | An index into $\b${\b{C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDS\bS}\b} of the word containing the current |
17345e5a | 936 | cursor position. This variable is available only in shell func- |
ac50fbac | 937 | tions invoked by the programmable completion facilities (see |
17345e5a | 938 | P\bPr\bro\bog\bgr\bra\bam\bmm\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn below). |
17345e5a JA |
939 | C\bCO\bOM\bMP\bP_\b_K\bKE\bEY\bY |
940 | The key (or final key of a key sequence) used to invoke the cur- | |
941 | rent completion function. | |
17345e5a | 942 | C\bCO\bOM\bMP\bP_\b_L\bLI\bIN\bNE\bE |
ac50fbac | 943 | The current command line. This variable is available only in |
a0c0a00f CR |
944 | shell functions and external commands invoked by the program- |
945 | mable completion facilities (see P\bPr\bro\bog\bgr\bra\bam\bmm\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn below). | |
17345e5a | 946 | C\bCO\bOM\bMP\bP_\b_P\bPO\bOI\bIN\bNT\bT |
a0c0a00f CR |
947 | The index of the current cursor position relative to the begin- |
948 | ning of the current command. If the current cursor position is | |
17345e5a | 949 | at the end of the current command, the value of this variable is |
a0c0a00f CR |
950 | equal to $\b${\b{#\b#C\bCO\bOM\bMP\bP_\b_L\bLI\bIN\bNE\bE}\b}. This variable is available only in |
951 | shell functions and external commands invoked by the program- | |
952 | mable completion facilities (see P\bPr\bro\bog\bgr\bra\bam\bmm\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn below). | |
17345e5a | 953 | C\bCO\bOM\bMP\bP_\b_T\bTY\bYP\bPE\bE |
ac50fbac CR |
954 | Set to an integer value corresponding to the type of completion |
955 | attempted that caused a completion function to be called: _\bT_\bA_\bB, | |
956 | for normal completion, _\b?, for listing completions after succes- | |
957 | sive tabs, _\b!, for listing alternatives on partial word comple- | |
958 | tion, _\b@, to list completions if the word is not unmodified, or | |
959 | _\b%, for menu completion. This variable is available only in | |
a0c0a00f CR |
960 | shell functions and external commands invoked by the program- |
961 | mable completion facilities (see P\bPr\bro\bog\bgr\bra\bam\bmm\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn below). | |
17345e5a | 962 | C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDB\bBR\bRE\bEA\bAK\bKS\bS |
a0c0a00f CR |
963 | The set of characters that the r\bre\bea\bad\bdl\bli\bin\bne\be library treats as word |
964 | separators when performing word completion. If C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDB\bBR\bRE\bEA\bAK\bKS\bS | |
965 | is unset, it loses its special properties, even if it is subse- | |
17345e5a | 966 | quently reset. |
17345e5a | 967 | C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDS\bS |
a0c0a00f CR |
968 | An array variable (see A\bAr\brr\bra\bay\bys\bs below) consisting of the individ- |
969 | ual words in the current command line. The line is split into | |
8868edaf CR |
970 | words as r\bre\bea\bad\bdl\bli\bin\bne\be would split it, using C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDB\bBR\bRE\bEA\bAK\bKS\bS as de- |
971 | scribed above. This variable is available only in shell func- | |
a0c0a00f | 972 | tions invoked by the programmable completion facilities (see |
0001803f | 973 | P\bPr\bro\bog\bgr\bra\bam\bmm\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn below). |
a0c0a00f CR |
974 | C\bCO\bOP\bPR\bRO\bOC\bC An array variable (see A\bAr\brr\bra\bay\bys\bs below) created to hold the file |
975 | descriptors for output from and input to an unnamed coprocess | |
495aee44 | 976 | (see C\bCo\bop\bpr\bro\boc\bce\bes\bss\bse\bes\bs above). |
17345e5a JA |
977 | D\bDI\bIR\bRS\bST\bTA\bAC\bCK\bK |
978 | An array variable (see A\bAr\brr\bra\bay\bys\bs below) containing the current con- | |
a0c0a00f CR |
979 | tents of the directory stack. Directories appear in the stack |
980 | in the order they are displayed by the d\bdi\bir\brs\bs builtin. Assigning | |
17345e5a | 981 | to members of this array variable may be used to modify directo- |
a0c0a00f | 982 | ries already in the stack, but the p\bpu\bus\bsh\bhd\bd and p\bpo\bop\bpd\bd builtins must |
17345e5a | 983 | be used to add and remove directories. Assignment to this vari- |
8868edaf CR |
984 | able will not change the current directory. If D\bDI\bIR\bRS\bST\bTA\bAC\bCK\bK is un- |
985 | set, it loses its special properties, even if it is subsequently | |
986 | reset. | |
d233b485 CR |
987 | E\bEP\bPO\bOC\bCH\bHR\bRE\bEA\bAL\bLT\bTI\bIM\bME\bE |
988 | Each time this parameter is referenced, it expands to the number | |
989 | of seconds since the Unix Epoch (see _\bt_\bi_\bm_\be(3)) as a floating | |
990 | point value with micro-second granularity. Assignments to | |
991 | E\bEP\bPO\bOC\bCH\bHR\bRE\bEA\bAL\bLT\bTI\bIM\bME\bE are ignored. If E\bEP\bPO\bOC\bCH\bHR\bRE\bEA\bAL\bLT\bTI\bIM\bME\bE is unset, it loses | |
992 | its special properties, even if it is subsequently reset. | |
993 | E\bEP\bPO\bOC\bCH\bHS\bSE\bEC\bCO\bON\bND\bDS\bS | |
994 | Each time this parameter is referenced, it expands to the number | |
995 | of seconds since the Unix Epoch (see _\bt_\bi_\bm_\be(3)). Assignments to | |
996 | E\bEP\bPO\bOC\bCH\bHS\bSE\bEC\bCO\bON\bND\bDS\bS are ignored. If E\bEP\bPO\bOC\bCH\bHS\bSE\bEC\bCO\bON\bND\bDS\bS is unset, it loses | |
997 | its special properties, even if it is subsequently reset. | |
998 | E\bEU\bUI\bID\bD Expands to the effective user ID of the current user, initial- | |
17345e5a | 999 | ized at shell startup. This variable is readonly. |
17345e5a | 1000 | F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE |
d233b485 | 1001 | An array variable containing the names of all shell functions |
17345e5a JA |
1002 | currently in the execution call stack. The element with index 0 |
1003 | is the name of any currently-executing shell function. The bot- | |
d233b485 CR |
1004 | tom-most element (the one with the highest index) is "main". |
1005 | This variable exists only when a shell function is executing. | |
1006 | Assignments to F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE have no effect. If F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE is unset, | |
8868edaf CR |
1007 | it loses its special properties, even if it is subsequently re- |
1008 | set. | |
495aee44 | 1009 | |
d233b485 CR |
1010 | This variable can be used with B\bBA\bAS\bSH\bH_\b_L\bLI\bIN\bNE\bEN\bNO\bO and B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE. |
1011 | Each element of F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE has corresponding elements in | |
8868edaf CR |
1012 | B\bBA\bAS\bSH\bH_\b_L\bLI\bIN\bNE\bEN\bNO\bO and B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE to describe the call stack. For in- |
1013 | stance, $\b${\b{F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE[\b[_\b$_\bi]\b]}\b} was called from the file | |
d233b485 | 1014 | $\b${\b{B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE[\b[_\b$_\bi_\b+_\b1]\b]}\b} at line number $\b${\b{B\bBA\bAS\bSH\bH_\b_L\bLI\bIN\bNE\bEN\bNO\bO[\b[_\b$_\bi]\b]}\b}. The |
495aee44 CR |
1015 | c\bca\bal\bll\ble\ber\br builtin displays the current call stack using this infor- |
1016 | mation. | |
d233b485 | 1017 | G\bGR\bRO\bOU\bUP\bPS\bS An array variable containing the list of groups of which the |
a0c0a00f | 1018 | current user is a member. Assignments to G\bGR\bRO\bOU\bUP\bPS\bS have no effect. |
d233b485 | 1019 | If G\bGR\bRO\bOU\bUP\bPS\bS is unset, it loses its special properties, even if it |
a0c0a00f | 1020 | is subsequently reset. |
17345e5a JA |
1021 | H\bHI\bIS\bST\bTC\bCM\bMD\bD |
1022 | The history number, or index in the history list, of the current | |
8868edaf CR |
1023 | command. Assignments to H\bHI\bIS\bST\bTC\bCM\bMD\bD are ignored. If H\bHI\bIS\bST\bTC\bCM\bMD\bD is un- |
1024 | set, it loses its special properties, even if it is subsequently | |
1025 | reset. | |
17345e5a JA |
1026 | H\bHO\bOS\bST\bTN\bNA\bAM\bME\bE |
1027 | Automatically set to the name of the current host. | |
17345e5a | 1028 | H\bHO\bOS\bST\bTT\bTY\bYP\bPE\bE |
8868edaf CR |
1029 | Automatically set to a string that uniquely describes the type |
1030 | of machine on which b\bba\bas\bsh\bh is executing. The default is system- | |
17345e5a | 1031 | dependent. |
8868edaf CR |
1032 | L\bLI\bIN\bNE\bEN\bNO\bO Each time this parameter is referenced, the shell substitutes a |
1033 | decimal number representing the current sequential line number | |
1034 | (starting with 1) within a script or function. When not in a | |
1035 | script or function, the value substituted is not guaranteed to | |
17345e5a JA |
1036 | be meaningful. If L\bLI\bIN\bNE\bEN\bNO\bO is unset, it loses its special proper- |
1037 | ties, even if it is subsequently reset. | |
17345e5a | 1038 | M\bMA\bAC\bCH\bHT\bTY\bYP\bPE\bE |
8868edaf CR |
1039 | Automatically set to a string that fully describes the system |
1040 | type on which b\bba\bas\bsh\bh is executing, in the standard GNU _\bc_\bp_\bu_\b-_\bc_\bo_\bm_\b- | |
17345e5a | 1041 | _\bp_\ba_\bn_\by_\b-_\bs_\by_\bs_\bt_\be_\bm format. The default is system-dependent. |
495aee44 | 1042 | M\bMA\bAP\bPF\bFI\bIL\bLE\bE |
8868edaf | 1043 | An array variable (see A\bAr\brr\bra\bay\bys\bs below) created to hold the text |
495aee44 | 1044 | read by the m\bma\bap\bpf\bfi\bil\ble\be builtin when no variable name is supplied. |
17345e5a | 1045 | O\bOL\bLD\bDP\bPW\bWD\bD The previous working directory as set by the c\bcd\bd command. |
8868edaf | 1046 | O\bOP\bPT\bTA\bAR\bRG\bG The value of the last option argument processed by the g\bge\bet\bto\bop\bpt\bts\bs |
17345e5a | 1047 | builtin command (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). |
8868edaf | 1048 | O\bOP\bPT\bTI\bIN\bND\bD The index of the next argument to be processed by the g\bge\bet\bto\bop\bpt\bts\bs |
17345e5a | 1049 | builtin command (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). |
8868edaf CR |
1050 | O\bOS\bST\bTY\bYP\bPE\bE Automatically set to a string that describes the operating sys- |
1051 | tem on which b\bba\bas\bsh\bh is executing. The default is system-depen- | |
17345e5a | 1052 | dent. |
17345e5a | 1053 | P\bPI\bIP\bPE\bES\bST\bTA\bAT\bTU\bUS\bS |
8868edaf CR |
1054 | An array variable (see A\bAr\brr\bra\bay\bys\bs below) containing a list of exit |
1055 | status values from the processes in the most-recently-executed | |
17345e5a | 1056 | foreground pipeline (which may contain only a single command). |
8868edaf | 1057 | P\bPP\bPI\bID\bD The process ID of the shell's parent. This variable is read- |
17345e5a | 1058 | only. |
17345e5a | 1059 | P\bPW\bWD\bD The current working directory as set by the c\bcd\bd command. |
8868edaf CR |
1060 | R\bRA\bAN\bND\bDO\bOM\bM Each time this parameter is referenced, it expands to a random |
1061 | integer between 0 and 32767. Assigning a value to R\bRA\bAN\bND\bDO\bOM\bM ini- | |
1062 | tializes (seeds) the sequence of random numbers. If R\bRA\bAN\bND\bDO\bOM\bM is | |
1063 | unset, it loses its special properties, even if it is subse- | |
1064 | quently reset. | |
74091dd4 CR |
1065 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_A\bAR\bRG\bGU\bUM\bME\bEN\bNT\bT |
1066 | Any numeric argument given to a readline command that was de- | |
1067 | fined using "bind -x" (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below) when it | |
1068 | was invoked. | |
495aee44 CR |
1069 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_L\bLI\bIN\bNE\bE |
1070 | The contents of the r\bre\bea\bad\bdl\bli\bin\bne\be line buffer, for use with "bind -x" | |
1071 | (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). | |
8868edaf CR |
1072 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_M\bMA\bAR\bRK\bK |
1073 | The position of the mark (saved insertion point) in the r\bre\bea\bad\bdl\bli\bin\bne\be | |
1074 | line buffer, for use with "bind -x" (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS | |
1075 | below). The characters between the insertion point and the mark | |
1076 | are often called the _\br_\be_\bg_\bi_\bo_\bn. | |
495aee44 CR |
1077 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_P\bPO\bOI\bIN\bNT\bT |
1078 | The position of the insertion point in the r\bre\bea\bad\bdl\bli\bin\bne\be line buffer, | |
1079 | for use with "bind -x" (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). | |
d233b485 | 1080 | R\bRE\bEP\bPL\bLY\bY Set to the line of input read by the r\bre\bea\bad\bd builtin command when |
17345e5a | 1081 | no arguments are supplied. |
17345e5a | 1082 | S\bSE\bEC\bCO\bON\bND\bDS\bS |
74091dd4 CR |
1083 | Each time this parameter is referenced, it expands to the number |
1084 | of seconds since shell invocation. If a value is assigned to | |
d233b485 CR |
1085 | S\bSE\bEC\bCO\bON\bND\bDS\bS, the value returned upon subsequent references is the |
1086 | number of seconds since the assignment plus the value assigned. | |
8868edaf | 1087 | The number of seconds at shell invocation and the current time |
74091dd4 | 1088 | are always determined by querying the system clock. If S\bSE\bEC\bCO\bON\bND\bDS\bS |
8868edaf CR |
1089 | is unset, it loses its special properties, even if it is subse- |
1090 | quently reset. | |
17345e5a | 1091 | S\bSH\bHE\bEL\bLL\bLO\bOP\bPT\bTS\bS |
d233b485 CR |
1092 | A colon-separated list of enabled shell options. Each word in |
1093 | the list is a valid argument for the -\b-o\bo option to the s\bse\bet\bt | |
17345e5a | 1094 | builtin command (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). The options |
d233b485 CR |
1095 | appearing in S\bSH\bHE\bEL\bLL\bLO\bOP\bPT\bTS\bS are those reported as _\bo_\bn by s\bse\bet\bt -\b-o\bo. If |
1096 | this variable is in the environment when b\bba\bas\bsh\bh starts up, each | |
1097 | shell option in the list will be enabled before reading any | |
17345e5a | 1098 | startup files. This variable is read-only. |
17345e5a | 1099 | S\bSH\bHL\bLV\bVL\bL Incremented by one each time an instance of b\bba\bas\bsh\bh is started. |
8868edaf CR |
1100 | S\bSR\bRA\bAN\bND\bDO\bOM\bM |
1101 | This variable expands to a 32-bit pseudo-random number each time | |
1102 | it is referenced. The random number generator is not linear on | |
1103 | systems that support /dev/urandom or _\ba_\br_\bc_\b4_\br_\ba_\bn_\bd_\bo_\bm, so each re- | |
1104 | turned number has no relationship to the numbers preceding it. | |
1105 | The random number generator cannot be seeded, so assignments to | |
1106 | this variable have no effect. If S\bSR\bRA\bAN\bND\bDO\bOM\bM is unset, it loses its | |
1107 | special properties, even if it is subsequently reset. | |
17345e5a JA |
1108 | U\bUI\bID\bD Expands to the user ID of the current user, initialized at shell |
1109 | startup. This variable is readonly. | |
1110 | ||
8868edaf CR |
1111 | The following variables are used by the shell. In some cases, b\bba\bas\bsh\bh as- |
1112 | signs a default value to a variable; these cases are noted below. | |
17345e5a | 1113 | |
ac50fbac | 1114 | B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT |
d233b485 | 1115 | The value is used to set the shell's compatibility level. See |
8868edaf CR |
1116 | S\bSH\bHE\bEL\bLL\bL C\bCO\bOM\bMP\bPA\bAT\bTI\bIB\bBI\bIL\bLI\bIT\bTY\bY M\bMO\bOD\bDE\bE below for a description of the various |
1117 | compatibility levels and their effects. The value may be a dec- | |
1118 | imal number (e.g., 4.2) or an integer (e.g., 42) corresponding | |
1119 | to the desired compatibility level. If B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT is unset or | |
1120 | set to the empty string, the compatibility level is set to the | |
1121 | default for the current version. If B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT is set to a | |
1122 | value that is not one of the valid compatibility levels, the | |
1123 | shell prints an error message and sets the compatibility level | |
1124 | to the default for the current version. The valid values corre- | |
74091dd4 CR |
1125 | spond to the compatibility levels described below under S\bSH\bHE\bEL\bLL\bL |
1126 | C\bCO\bOM\bMP\bPA\bAT\bTI\bIB\bBI\bIL\bLI\bIT\bTY\bY M\bMO\bOD\bDE\bE. For example, 4.2 and 42 are valid values | |
8868edaf CR |
1127 | that correspond to the c\bco\bom\bmp\bpa\bat\bt4\b42\b2 s\bsh\bho\bop\bpt\bt option and set the compat- |
1128 | ibility level to 42. The current version is also a valid value. | |
17345e5a | 1129 | B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV |
d233b485 CR |
1130 | If this parameter is set when b\bba\bas\bsh\bh is executing a shell script, |
1131 | its value is interpreted as a filename containing commands to | |
17345e5a | 1132 | initialize the shell, as in _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc. The value of B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV is |
d233b485 CR |
1133 | subjected to parameter expansion, command substitution, and |
1134 | arithmetic expansion before being interpreted as a filename. | |
ac50fbac | 1135 | P\bPA\bAT\bTH\bH is not used to search for the resultant filename. |
0001803f | 1136 | B\bBA\bAS\bSH\bH_\b_X\bXT\bTR\bRA\bAC\bCE\bEF\bFD\bD |
d233b485 | 1137 | If set to an integer corresponding to a valid file descriptor, |
8868edaf CR |
1138 | b\bba\bas\bsh\bh will write the trace output generated when _\bs_\be_\bt _\b-_\bx is en- |
1139 | abled to that file descriptor. The file descriptor is closed | |
d233b485 CR |
1140 | when B\bBA\bAS\bSH\bH_\b_X\bXT\bTR\bRA\bAC\bCE\bEF\bFD\bD is unset or assigned a new value. Unsetting |
1141 | B\bBA\bAS\bSH\bH_\b_X\bXT\bTR\bRA\bAC\bCE\bEF\bFD\bD or assigning it the empty string causes the trace | |
1142 | output to be sent to the standard error. Note that setting | |
0001803f CR |
1143 | B\bBA\bAS\bSH\bH_\b_X\bXT\bTR\bRA\bAC\bCE\bEF\bFD\bD to 2 (the standard error file descriptor) and then |
1144 | unsetting it will result in the standard error being closed. | |
d233b485 | 1145 | C\bCD\bDP\bPA\bAT\bTH\bH The search path for the c\bcd\bd command. This is a colon-separated |
8868edaf CR |
1146 | list of directories in which the shell looks for destination di- |
1147 | rectories specified by the c\bcd\bd command. A sample value is | |
495aee44 | 1148 | ".:~:/usr". |
ac50fbac | 1149 | C\bCH\bHI\bIL\bLD\bD_\b_M\bMA\bAX\bX |
d233b485 CR |
1150 | Set the number of exited child status values for the shell to |
1151 | remember. Bash will not allow this value to be decreased below | |
1152 | a POSIX-mandated minimum, and there is a maximum value (cur- | |
1153 | rently 8192) that this may not exceed. The minimum value is | |
ac50fbac | 1154 | system-dependent. |
17345e5a | 1155 | C\bCO\bOL\bLU\bUM\bMN\bNS\bS |
d233b485 CR |
1156 | Used by the s\bse\bel\ble\bec\bct\bt compound command to determine the terminal |
1157 | width when printing selection lists. Automatically set if the | |
1158 | c\bch\bhe\bec\bck\bkw\bwi\bin\bns\bsi\biz\bze\be option is enabled or in an interactive shell upon | |
495aee44 | 1159 | receipt of a S\bSI\bIG\bGW\bWI\bIN\bNC\bCH\bH. |
17345e5a JA |
1160 | C\bCO\bOM\bMP\bPR\bRE\bEP\bPL\bLY\bY |
1161 | An array variable from which b\bba\bas\bsh\bh reads the possible completions | |
d233b485 | 1162 | generated by a shell function invoked by the programmable com- |
8868edaf CR |
1163 | pletion facility (see P\bPr\bro\bog\bgr\bra\bam\bmm\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn below). Each ar- |
1164 | ray element contains one possible completion. | |
d233b485 CR |
1165 | E\bEM\bMA\bAC\bCS\bS If b\bba\bas\bsh\bh finds this variable in the environment when the shell |
1166 | starts with value "t", it assumes that the shell is running in | |
495aee44 | 1167 | an Emacs shell buffer and disables line editing. |
8868edaf CR |
1168 | E\bEN\bNV\bV Expanded and executed similarly to B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV (see I\bIN\bNV\bVO\bOC\bCA\bAT\bTI\bIO\bON\bN |
1169 | above) when an interactive shell is invoked in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be. | |
a0c0a00f | 1170 | E\bEX\bXE\bEC\bCI\bIG\bGN\bNO\bOR\bRE\bE |
d233b485 CR |
1171 | A colon-separated list of shell patterns (see P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg) |
1172 | defining the list of filenames to be ignored by command search | |
1173 | using P\bPA\bAT\bTH\bH. Files whose full pathnames match one of these pat- | |
1174 | terns are not considered executable files for the purposes of | |
a0c0a00f CR |
1175 | completion and command execution via P\bPA\bAT\bTH\bH lookup. This does not |
1176 | affect the behavior of the [\b[, t\bte\bes\bst\bt, and [\b[[\b[ commands. Full path- | |
d233b485 CR |
1177 | names in the command hash table are not subject to E\bEX\bXE\bEC\bCI\bIG\bGN\bNO\bOR\bRE\bE. |
1178 | Use this variable to ignore shared library files that have the | |
1179 | executable bit set, but are not executable files. The pattern | |
a0c0a00f | 1180 | matching honors the setting of the e\bex\bxt\btg\bgl\blo\bob\bb shell option. |
17345e5a JA |
1181 | F\bFC\bCE\bED\bDI\bIT\bT The default editor for the f\bfc\bc builtin command. |
1182 | F\bFI\bIG\bGN\bNO\bOR\bRE\bE | |
d233b485 | 1183 | A colon-separated list of suffixes to ignore when performing |
17345e5a | 1184 | filename completion (see R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE below). A filename whose suf- |
d233b485 | 1185 | fix matches one of the entries in F\bFI\bIG\bGN\bNO\bOR\bRE\bE is excluded from the |
17345e5a | 1186 | list of matched filenames. A sample value is ".o:~". |
495aee44 | 1187 | F\bFU\bUN\bNC\bCN\bNE\bES\bST\bT |
d233b485 CR |
1188 | If set to a numeric value greater than 0, defines a maximum |
1189 | function nesting level. Function invocations that exceed this | |
495aee44 | 1190 | nesting level will cause the current command to abort. |
17345e5a | 1191 | G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE |
d233b485 CR |
1192 | A colon-separated list of patterns defining the set of file |
1193 | names to be ignored by pathname expansion. If a file name | |
1194 | matched by a pathname expansion pattern also matches one of the | |
1195 | patterns in G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE, it is removed from the list of matches. | |
17345e5a | 1196 | H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL |
d233b485 | 1197 | A colon-separated list of values controlling how commands are |
8868edaf CR |
1198 | saved on the history list. If the list of values includes _\bi_\bg_\b- |
1199 | _\bn_\bo_\br_\be_\bs_\bp_\ba_\bc_\be, lines which begin with a s\bsp\bpa\bac\bce\be character are not | |
d233b485 | 1200 | saved in the history list. A value of _\bi_\bg_\bn_\bo_\br_\be_\bd_\bu_\bp_\bs causes lines |
17345e5a JA |
1201 | matching the previous history entry to not be saved. A value of |
1202 | _\bi_\bg_\bn_\bo_\br_\be_\bb_\bo_\bt_\bh is shorthand for _\bi_\bg_\bn_\bo_\br_\be_\bs_\bp_\ba_\bc_\be and _\bi_\bg_\bn_\bo_\br_\be_\bd_\bu_\bp_\bs. A value | |
1203 | of _\be_\br_\ba_\bs_\be_\bd_\bu_\bp_\bs causes all previous lines matching the current line | |
d233b485 CR |
1204 | to be removed from the history list before that line is saved. |
1205 | Any value not in the above list is ignored. If H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL is | |
1206 | unset, or does not include a valid value, all lines read by the | |
17345e5a | 1207 | shell parser are saved on the history list, subject to the value |
d233b485 CR |
1208 | of H\bHI\bIS\bST\bTI\bIG\bGN\bNO\bOR\bRE\bE. The second and subsequent lines of a multi-line |
1209 | compound command are not tested, and are added to the history | |
17345e5a JA |
1210 | regardless of the value of H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL. |
1211 | H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE | |
1212 | The name of the file in which command history is saved (see H\bHI\bIS\bS-\b- | |
d233b485 | 1213 | T\bTO\bOR\bRY\bY below). The default value is _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bh_\bi_\bs_\bt_\bo_\br_\by. If unset, |
ac50fbac | 1214 | the command history is not saved when a shell exits. |
17345e5a JA |
1215 | H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bES\bSI\bIZ\bZE\bE |
1216 | The maximum number of lines contained in the history file. When | |
d233b485 CR |
1217 | this variable is assigned a value, the history file is trun- |
1218 | cated, if necessary, to contain no more than that number of | |
1219 | lines by removing the oldest entries. The history file is also | |
1220 | truncated to this size after writing it when a shell exits. If | |
1221 | the value is 0, the history file is truncated to zero size. | |
1222 | Non-numeric values and numeric values less than zero inhibit | |
1223 | truncation. The shell sets the default value to the value of | |
ac50fbac | 1224 | H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE after reading any startup files. |
17345e5a | 1225 | H\bHI\bIS\bST\bTI\bIG\bGN\bNO\bOR\bRE\bE |
d233b485 | 1226 | A colon-separated list of patterns used to decide which command |
8868edaf CR |
1227 | lines should be saved on the history list. Each pattern is an- |
1228 | chored at the beginning of the line and must match the complete | |
1229 | line (no implicit `*\b*' is appended). Each pattern is tested | |
1230 | against the line after the checks specified by H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL are | |
1231 | applied. In addition to the normal shell pattern matching char- | |
1232 | acters, `&\b&' matches the previous history line. `&\b&' may be es- | |
1233 | caped using a backslash; the backslash is removed before at- | |
1234 | tempting a match. The second and subsequent lines of a multi- | |
1235 | line compound command are not tested, and are added to the his- | |
1236 | tory regardless of the value of H\bHI\bIS\bST\bTI\bIG\bGN\bNO\bOR\bRE\bE. The pattern match- | |
1237 | ing honors the setting of the e\bex\bxt\btg\bgl\blo\bob\bb shell option. | |
17345e5a | 1238 | H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE |
d233b485 CR |
1239 | The number of commands to remember in the command history (see |
1240 | H\bHI\bIS\bST\bTO\bOR\bRY\bY below). If the value is 0, commands are not saved in | |
ac50fbac | 1241 | the history list. Numeric values less than zero result in every |
d233b485 CR |
1242 | command being saved on the history list (there is no limit). |
1243 | The shell sets the default value to 500 after reading any | |
ac50fbac | 1244 | startup files. |
17345e5a | 1245 | H\bHI\bIS\bST\bTT\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT |
d233b485 | 1246 | If this variable is set and not null, its value is used as a |
17345e5a | 1247 | format string for _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be(3) to print the time stamp associated |
d233b485 CR |
1248 | with each history entry displayed by the h\bhi\bis\bst\bto\bor\bry\by builtin. If |
1249 | this variable is set, time stamps are written to the history | |
1250 | file so they may be preserved across shell sessions. This uses | |
1251 | the history comment character to distinguish timestamps from | |
17345e5a JA |
1252 | other history lines. |
1253 | H\bHO\bOM\bME\bE The home directory of the current user; the default argument for | |
1254 | the c\bcd\bd builtin command. The value of this variable is also used | |
1255 | when performing tilde expansion. | |
1256 | H\bHO\bOS\bST\bTF\bFI\bIL\bLE\bE | |
d233b485 | 1257 | Contains the name of a file in the same format as _\b/_\be_\bt_\bc_\b/_\bh_\bo_\bs_\bt_\bs |
17345e5a | 1258 | that should be read when the shell needs to complete a hostname. |
d233b485 | 1259 | The list of possible hostname completions may be changed while |
8868edaf CR |
1260 | the shell is running; the next time hostname completion is at- |
1261 | tempted after the value is changed, b\bba\bas\bsh\bh adds the contents of | |
d233b485 CR |
1262 | the new file to the existing list. If H\bHO\bOS\bST\bTF\bFI\bIL\bLE\bE is set, but has |
1263 | no value, or does not name a readable file, b\bba\bas\bsh\bh attempts to | |
1264 | read _\b/_\be_\bt_\bc_\b/_\bh_\bo_\bs_\bt_\bs to obtain the list of possible hostname comple- | |
0001803f | 1265 | tions. When H\bHO\bOS\bST\bTF\bFI\bIL\bLE\bE is unset, the hostname list is cleared. |
8868edaf CR |
1266 | I\bIF\bFS\bS The _\bI_\bn_\bt_\be_\br_\bn_\ba_\bl _\bF_\bi_\be_\bl_\bd _\bS_\be_\bp_\ba_\br_\ba_\bt_\bo_\br that is used for word splitting af- |
1267 | ter expansion and to split lines into words with the r\bre\bea\bad\bd | |
17345e5a JA |
1268 | builtin command. The default value is ``<space><tab><new- |
1269 | line>''. | |
1270 | I\bIG\bGN\bNO\bOR\bRE\bEE\bEO\bOF\bF | |
1271 | Controls the action of an interactive shell on receipt of an E\bEO\bOF\bF | |
1272 | character as the sole input. If set, the value is the number of | |
d233b485 CR |
1273 | consecutive E\bEO\bOF\bF characters which must be typed as the first |
1274 | characters on an input line before b\bba\bas\bsh\bh exits. If the variable | |
1275 | exists but does not have a numeric value, or has no value, the | |
1276 | default value is 10. If it does not exist, E\bEO\bOF\bF signifies the | |
17345e5a JA |
1277 | end of input to the shell. |
1278 | I\bIN\bNP\bPU\bUT\bTR\bRC\bC | |
8868edaf CR |
1279 | The filename for the r\bre\bea\bad\bdl\bli\bin\bne\be startup file, overriding the de- |
1280 | fault of _\b~_\b/_\b._\bi_\bn_\bp_\bu_\bt_\br_\bc (see R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE below). | |
d233b485 CR |
1281 | I\bIN\bNS\bSI\bID\bDE\bE_\b_E\bEM\bMA\bAC\bCS\bS |
1282 | If this variable appears in the environment when the shell | |
1283 | starts, b\bba\bas\bsh\bh assumes that it is running inside an Emacs shell | |
1284 | buffer and may disable line editing, depending on the value of | |
1285 | T\bTE\bER\bRM\bM. | |
a0c0a00f | 1286 | L\bLA\bAN\bNG\bG Used to determine the locale category for any category not |
17345e5a | 1287 | specifically selected with a variable starting with L\bLC\bC_\b_. |
a0c0a00f | 1288 | L\bLC\bC_\b_A\bAL\bLL\bL This variable overrides the value of L\bLA\bAN\bNG\bG and any other L\bLC\bC_\b_ |
17345e5a JA |
1289 | variable specifying a locale category. |
1290 | L\bLC\bC_\b_C\bCO\bOL\bLL\bLA\bAT\bTE\bE | |
a0c0a00f CR |
1291 | This variable determines the collation order used when sorting |
1292 | the results of pathname expansion, and determines the behavior | |
8868edaf CR |
1293 | of range expressions, equivalence classes, and collating se- |
1294 | quences within pathname expansion and pattern matching. | |
17345e5a | 1295 | L\bLC\bC_\b_C\bCT\bTY\bYP\bPE\bE |
a0c0a00f CR |
1296 | This variable determines the interpretation of characters and |
1297 | the behavior of character classes within pathname expansion and | |
17345e5a JA |
1298 | pattern matching. |
1299 | L\bLC\bC_\b_M\bME\bES\bSS\bSA\bAG\bGE\bES\bS | |
a0c0a00f | 1300 | This variable determines the locale used to translate double- |
17345e5a JA |
1301 | quoted strings preceded by a $\b$. |
1302 | L\bLC\bC_\b_N\bNU\bUM\bME\bER\bRI\bIC\bC | |
a0c0a00f | 1303 | This variable determines the locale category used for number |
17345e5a | 1304 | formatting. |
a0c0a00f CR |
1305 | L\bLC\bC_\b_T\bTI\bIM\bME\bE |
1306 | This variable determines the locale category used for data and | |
1307 | time formatting. | |
495aee44 | 1308 | L\bLI\bIN\bNE\bES\bS Used by the s\bse\bel\ble\bec\bct\bt compound command to determine the column |
ac50fbac CR |
1309 | length for printing selection lists. Automatically set if the |
1310 | c\bch\bhe\bec\bck\bkw\bwi\bin\bns\bsi\biz\bze\be option is enabled or in an interactive shell upon | |
0001803f | 1311 | receipt of a S\bSI\bIG\bGW\bWI\bIN\bNC\bCH\bH. |
ac50fbac | 1312 | M\bMA\bAI\bIL\bL If this parameter is set to a file or directory name and the |
8868edaf CR |
1313 | M\bMA\bAI\bIL\bLP\bPA\bAT\bTH\bH variable is not set, b\bba\bas\bsh\bh informs the user of the ar- |
1314 | rival of mail in the specified file or Maildir-format directory. | |
17345e5a | 1315 | M\bMA\bAI\bIL\bLC\bCH\bHE\bEC\bCK\bK |
8868edaf CR |
1316 | Specifies how often (in seconds) b\bba\bas\bsh\bh checks for mail. The de- |
1317 | fault is 60 seconds. When it is time to check for mail, the | |
1318 | shell does so before displaying the primary prompt. If this | |
1319 | variable is unset, or set to a value that is not a number | |
17345e5a JA |
1320 | greater than or equal to zero, the shell disables mail checking. |
1321 | M\bMA\bAI\bIL\bLP\bPA\bAT\bTH\bH | |
ac50fbac CR |
1322 | A colon-separated list of filenames to be checked for mail. The |
1323 | message to be printed when mail arrives in a particular file may | |
8868edaf CR |
1324 | be specified by separating the filename from the message with a |
1325 | `?'. When used in the text of the message, $\b$_\b_ expands to the | |
ac50fbac | 1326 | name of the current mailfile. Example: |
17345e5a JA |
1327 | M\bMA\bAI\bIL\bLP\bPA\bAT\bTH\bH='/var/mail/bfox?"You have mail":~/shell-mail?"$_ has |
1328 | mail!"' | |
8868edaf CR |
1329 | B\bBa\bas\bsh\bh can be configured to supply a default value for this vari- |
1330 | able (there is no value by default), but the location of the | |
a0c0a00f CR |
1331 | user mail files that it uses is system dependent (e.g., |
1332 | /var/mail/$\b$U\bUS\bSE\bER\bR). | |
17345e5a | 1333 | O\bOP\bPT\bTE\bER\bRR\bR If set to the value 1, b\bba\bas\bsh\bh displays error messages generated by |
8868edaf CR |
1334 | the g\bge\bet\bto\bop\bpt\bts\bs builtin command (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). |
1335 | O\bOP\bPT\bTE\bER\bRR\bR is initialized to 1 each time the shell is invoked or a | |
17345e5a | 1336 | shell script is executed. |
8868edaf CR |
1337 | P\bPA\bAT\bTH\bH The search path for commands. It is a colon-separated list of |
1338 | directories in which the shell looks for commands (see C\bCO\bOM\bMM\bMA\bAN\bND\bD | |
1339 | E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN below). A zero-length (null) directory name in the | |
17345e5a | 1340 | value of P\bPA\bAT\bTH\bH indicates the current directory. A null directory |
8868edaf CR |
1341 | name may appear as two adjacent colons, or as an initial or |
1342 | trailing colon. The default path is system-dependent, and is | |
a0c0a00f | 1343 | set by the administrator who installs b\bba\bas\bsh\bh. A common value is |
8868edaf CR |
1344 | ``/usr/local/bin:/usr/lo- |
1345 | cal/sbin:/usr/bin:/usr/sbin:/bin:/sbin''. | |
17345e5a | 1346 | P\bPO\bOS\bSI\bIX\bXL\bLY\bY_\b_C\bCO\bOR\bRR\bRE\bEC\bCT\bT |
8868edaf CR |
1347 | If this variable is in the environment when b\bba\bas\bsh\bh starts, the |
1348 | shell enters _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be before reading the startup files, as if | |
1349 | the -\b--\b-p\bpo\bos\bsi\bix\bx invocation option had been supplied. If it is set | |
1350 | while the shell is running, b\bba\bas\bsh\bh enables _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, as if the | |
1351 | command _\bs_\be_\bt _\b-_\bo _\bp_\bo_\bs_\bi_\bx had been executed. When the shell enters | |
d233b485 | 1352 | _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, it sets this variable if it was not already set. |
17345e5a | 1353 | P\bPR\bRO\bOM\bMP\bPT\bT_\b_C\bCO\bOM\bMM\bMA\bAN\bND\bD |
8868edaf CR |
1354 | If this variable is set, and is an array, the value of each set |
1355 | element is executed as a command prior to issuing each primary | |
1356 | prompt. If this is set but not an array variable, its value is | |
1357 | used as a command to execute instead. | |
17345e5a | 1358 | P\bPR\bRO\bOM\bMP\bPT\bT_\b_D\bDI\bIR\bRT\bTR\bRI\bIM\bM |
8868edaf | 1359 | If set to a number greater than zero, the value is used as the |
17345e5a | 1360 | number of trailing directory components to retain when expanding |
8868edaf | 1361 | the \\b\w\bw and \\b\W\bW prompt string escapes (see P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG below). |
17345e5a | 1362 | Characters removed are replaced with an ellipsis. |
8868edaf CR |
1363 | P\bPS\bS0\b0 The value of this parameter is expanded (see P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG below) |
1364 | and displayed by interactive shells after reading a command and | |
a0c0a00f | 1365 | before the command is executed. |
8868edaf CR |
1366 | P\bPS\bS1\b1 The value of this parameter is expanded (see P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG below) |
1367 | and used as the primary prompt string. The default value is | |
17345e5a | 1368 | ``\\b\s\bs-\b-\\b\v\bv\\b\$\b$ ''. |
8868edaf | 1369 | P\bPS\bS2\b2 The value of this parameter is expanded as with P\bPS\bS1\b1 and used as |
17345e5a JA |
1370 | the secondary prompt string. The default is ``>\b> ''. |
1371 | P\bPS\bS3\b3 The value of this parameter is used as the prompt for the s\bse\bel\ble\bec\bct\bt | |
1372 | command (see S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR above). | |
8868edaf CR |
1373 | P\bPS\bS4\b4 The value of this parameter is expanded as with P\bPS\bS1\b1 and the |
1374 | value is printed before each command b\bba\bas\bsh\bh displays during an ex- | |
1375 | ecution trace. The first character of the expanded value of P\bPS\bS4\b4 | |
1376 | is replicated multiple times, as necessary, to indicate multiple | |
1377 | levels of indirection. The default is ``+\b+ ''. | |
1378 | S\bSH\bHE\bEL\bLL\bL This variable expands to the full pathname to the shell. If it | |
1379 | is not set when the shell starts, b\bba\bas\bsh\bh assigns to it the full | |
1380 | pathname of the current user's login shell. | |
17345e5a | 1381 | T\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT |
8868edaf CR |
1382 | The value of this parameter is used as a format string specify- |
1383 | ing how the timing information for pipelines prefixed with the | |
1384 | t\bti\bim\bme\be reserved word should be displayed. The %\b% character intro- | |
1385 | duces an escape sequence that is expanded to a time value or | |
1386 | other information. The escape sequences and their meanings are | |
17345e5a JA |
1387 | as follows; the braces denote optional portions. |
1388 | %\b%%\b% A literal %\b%. | |
1389 | %\b%[\b[_\bp]\b][\b[l\bl]\b]R\bR The elapsed time in seconds. | |
1390 | %\b%[\b[_\bp]\b][\b[l\bl]\b]U\bU The number of CPU seconds spent in user mode. | |
1391 | %\b%[\b[_\bp]\b][\b[l\bl]\b]S\bS The number of CPU seconds spent in system mode. | |
1392 | %\b%P\bP The CPU percentage, computed as (%U + %S) / %R. | |
1393 | ||
8868edaf | 1394 | The optional _\bp is a digit specifying the _\bp_\br_\be_\bc_\bi_\bs_\bi_\bo_\bn, the number |
17345e5a JA |
1395 | of fractional digits after a decimal point. A value of 0 causes |
1396 | no decimal point or fraction to be output. At most three places | |
8868edaf CR |
1397 | after the decimal point may be specified; values of _\bp greater |
1398 | than 3 are changed to 3. If _\bp is not specified, the value 3 is | |
17345e5a JA |
1399 | used. |
1400 | ||
8868edaf CR |
1401 | The optional l\bl specifies a longer format, including minutes, of |
1402 | the form _\bM_\bMm_\bS_\bS._\bF_\bFs. The value of _\bp determines whether or not | |
17345e5a JA |
1403 | the fraction is included. |
1404 | ||
8868edaf CR |
1405 | If this variable is not set, b\bba\bas\bsh\bh acts as if it had the value |
1406 | $\b$'\b'\\b\n\bnr\bre\bea\bal\bl\\b\t\bt%\b%3\b3l\blR\bR\\b\n\bnu\bus\bse\ber\br\\b\t\bt%\b%3\b3l\blU\bU\\b\n\bns\bsy\bys\bs\\b\t\bt%\b%3\b3l\blS\bS'\b'. If the value is null, | |
ac50fbac | 1407 | no timing information is displayed. A trailing newline is added |
17345e5a | 1408 | when the format string is displayed. |
8868edaf CR |
1409 | T\bTM\bMO\bOU\bUT\bT If set to a value greater than zero, T\bTM\bMO\bOU\bUT\bT is treated as the de- |
1410 | fault timeout for the r\bre\bea\bad\bd builtin. The s\bse\bel\ble\bec\bct\bt command termi- | |
17345e5a | 1411 | nates if input does not arrive after T\bTM\bMO\bOU\bUT\bT seconds when input is |
8868edaf | 1412 | coming from a terminal. In an interactive shell, the value is |
ac50fbac CR |
1413 | interpreted as the number of seconds to wait for a line of input |
1414 | after issuing the primary prompt. B\bBa\bas\bsh\bh terminates after waiting | |
8868edaf | 1415 | for that number of seconds if a complete line of input does not |
ac50fbac | 1416 | arrive. |
8868edaf | 1417 | T\bTM\bMP\bPD\bDI\bIR\bR If set, b\bba\bas\bsh\bh uses its value as the name of a directory in which |
495aee44 | 1418 | b\bba\bas\bsh\bh creates temporary files for the shell's use. |
17345e5a JA |
1419 | a\bau\but\bto\bo_\b_r\bre\bes\bsu\bum\bme\be |
1420 | This variable controls how the shell interacts with the user and | |
8868edaf | 1421 | job control. If this variable is set, single word simple com- |
17345e5a JA |
1422 | mands without redirections are treated as candidates for resump- |
1423 | tion of an existing stopped job. There is no ambiguity allowed; | |
8868edaf CR |
1424 | if there is more than one job beginning with the string typed, |
1425 | the job most recently accessed is selected. The _\bn_\ba_\bm_\be of a | |
1426 | stopped job, in this context, is the command line used to start | |
1427 | it. If set to the value _\be_\bx_\ba_\bc_\bt, the string supplied must match | |
1428 | the name of a stopped job exactly; if set to _\bs_\bu_\bb_\bs_\bt_\br_\bi_\bn_\bg, the | |
1429 | string supplied needs to match a substring of the name of a | |
1430 | stopped job. The _\bs_\bu_\bb_\bs_\bt_\br_\bi_\bn_\bg value provides functionality analo- | |
1431 | gous to the %\b%?\b? job identifier (see J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL below). If set | |
1432 | to any other value, the supplied string must be a prefix of a | |
17345e5a JA |
1433 | stopped job's name; this provides functionality analogous to the |
1434 | %\b%_\bs_\bt_\br_\bi_\bn_\bg job identifier. | |
17345e5a | 1435 | h\bhi\bis\bst\btc\bch\bha\bar\brs\bs |
8868edaf | 1436 | The two or three characters which control history expansion and |
17345e5a | 1437 | tokenization (see H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN below). The first character |
8868edaf CR |
1438 | is the _\bh_\bi_\bs_\bt_\bo_\br_\by _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn character, the character which signals |
1439 | the start of a history expansion, normally `!\b!'. The second | |
1440 | character is the _\bq_\bu_\bi_\bc_\bk _\bs_\bu_\bb_\bs_\bt_\bi_\bt_\bu_\bt_\bi_\bo_\bn character, which is used as | |
1441 | shorthand for re-running the previous command entered, substi- | |
1442 | tuting one string for another in the command. The default is | |
1443 | `^\b^'. The optional third character is the character which indi- | |
1444 | cates that the remainder of the line is a comment when found as | |
1445 | the first character of a word, normally `#\b#'. The history com- | |
17345e5a | 1446 | ment character causes history substitution to be skipped for the |
8868edaf | 1447 | remaining words on the line. It does not necessarily cause the |
17345e5a JA |
1448 | shell parser to treat the rest of the line as a comment. |
1449 | ||
1450 | A\bAr\brr\bra\bay\bys\bs | |
8868edaf CR |
1451 | B\bBa\bas\bsh\bh provides one-dimensional indexed and associative array variables. |
1452 | Any variable may be used as an indexed array; the d\bde\bec\bcl\bla\bar\bre\be builtin will | |
1453 | explicitly declare an array. There is no maximum limit on the size of | |
1454 | an array, nor any requirement that members be indexed or assigned con- | |
1455 | tiguously. Indexed arrays are referenced using integers (including | |
a0c0a00f CR |
1456 | arithmetic expressions) and are zero-based; associative arrays are ref- |
1457 | erenced using arbitrary strings. Unless otherwise noted, indexed array | |
1458 | indices must be non-negative integers. | |
17345e5a | 1459 | |
8868edaf | 1460 | An indexed array is created automatically if any variable is assigned |
17345e5a | 1461 | to using the syntax _\bn_\ba_\bm_\be[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt]=_\bv_\ba_\bl_\bu_\be. The _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt is treated as |
ac50fbac | 1462 | an arithmetic expression that must evaluate to a number. To explicitly |
8868edaf CR |
1463 | declare an indexed array, use d\bde\bec\bcl\bla\bar\bre\be -\b-a\ba _\bn_\ba_\bm_\be (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bM-\b- |
1464 | M\bMA\bAN\bND\bDS\bS below). d\bde\bec\bcl\bla\bar\bre\be -\b-a\ba _\bn_\ba_\bm_\be[\b[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt]\b] is also accepted; the _\bs_\bu_\bb_\b- | |
ac50fbac | 1465 | _\bs_\bc_\br_\bi_\bp_\bt is ignored. |
17345e5a JA |
1466 | |
1467 | Associative arrays are created using d\bde\bec\bcl\bla\bar\bre\be -\b-A\bA _\bn_\ba_\bm_\be. | |
1468 | ||
1469 | Attributes may be specified for an array variable using the d\bde\bec\bcl\bla\bar\bre\be and | |
a0c0a00f | 1470 | r\bre\bea\bad\bdo\bon\bnl\bly\by builtins. Each attribute applies to all members of an array. |
17345e5a | 1471 | |
8868edaf CR |
1472 | Arrays are assigned to using compound assignments of the form |
1473 | _\bn_\ba_\bm_\be=(\b(value_\b1 ... value_\bn)\b), where each _\bv_\ba_\bl_\bu_\be may be of the form [_\bs_\bu_\bb_\b- | |
1474 | _\bs_\bc_\br_\bi_\bp_\bt]=_\bs_\bt_\br_\bi_\bn_\bg. Indexed array assignments do not require anything but | |
1475 | _\bs_\bt_\br_\bi_\bn_\bg. Each _\bv_\ba_\bl_\bu_\be in the list is expanded using all the shell expan- | |
1476 | sions described below under E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN. When assigning to indexed ar- | |
1477 | rays, if the optional brackets and subscript are supplied, that index | |
1478 | is assigned to; otherwise the index of the element assigned is the last | |
1479 | index assigned to by the statement plus one. Indexing starts at zero. | |
1480 | ||
1481 | When assigning to an associative array, the words in a compound assign- | |
1482 | ment may be either assignment statements, for which the subscript is | |
1483 | required, or a list of words that is interpreted as a sequence of al- | |
1484 | ternating keys and values: _\bn_\ba_\bm_\be=(\b( _\bk_\be_\by_\b1 _\bv_\ba_\bl_\bu_\be_\b1 _\bk_\be_\by_\b2 _\bv_\ba_\bl_\bu_\be_\b2 ...)\b). These | |
1485 | are treated identically to _\bn_\ba_\bm_\be=(\b( [_\bk_\be_\by_\b1]=_\bv_\ba_\bl_\bu_\be_\b1 [_\bk_\be_\by_\b2]=_\bv_\ba_\bl_\bu_\be_\b2 ...)\b). | |
1486 | The first word in the list determines how the remaining words are in- | |
1487 | terpreted; all assignments in a list must be of the same type. When | |
1488 | using key/value pairs, the keys may not be missing or empty; a final | |
1489 | missing value is treated like the empty string. | |
17345e5a | 1490 | |
d233b485 | 1491 | This syntax is also accepted by the d\bde\bec\bcl\bla\bar\bre\be builtin. Individual array |
8868edaf CR |
1492 | elements may be assigned to using the _\bn_\ba_\bm_\be[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt]=_\bv_\ba_\bl_\bu_\be syntax in- |
1493 | troduced above. When assigning to an indexed array, if _\bn_\ba_\bm_\be is sub- | |
d233b485 CR |
1494 | scripted by a negative number, that number is interpreted as relative |
1495 | to one greater than the maximum index of _\bn_\ba_\bm_\be, so negative indices | |
ac50fbac CR |
1496 | count back from the end of the array, and an index of -1 references the |
1497 | last element. | |
17345e5a | 1498 | |
74091dd4 CR |
1499 | The += operator will append to an array variable when assigning using |
1500 | the compound assignment syntax; see P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS above. | |
1501 | ||
1502 | Any element of an array may be referenced using ${_\bn_\ba_\bm_\be[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt]}. | |
17345e5a | 1503 | The braces are required to avoid conflicts with pathname expansion. If |
74091dd4 CR |
1504 | _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt is @\b@ or *\b*, the word expands to all members of _\bn_\ba_\bm_\be. These |
1505 | subscripts differ only when the word appears within double quotes. If | |
17345e5a | 1506 | the word is double-quoted, ${_\bn_\ba_\bm_\be[*]} expands to a single word with the |
74091dd4 | 1507 | value of each array member separated by the first character of the I\bIF\bFS\bS |
17345e5a | 1508 | special variable, and ${_\bn_\ba_\bm_\be[@]} expands each element of _\bn_\ba_\bm_\be to a sep- |
74091dd4 CR |
1509 | arate word. When there are no array members, ${_\bn_\ba_\bm_\be[@]} expands to |
1510 | nothing. If the double-quoted expansion occurs within a word, the ex- | |
8868edaf | 1511 | pansion of the first parameter is joined with the beginning part of the |
74091dd4 | 1512 | original word, and the expansion of the last parameter is joined with |
8868edaf | 1513 | the last part of the original word. This is analogous to the expansion |
74091dd4 CR |
1514 | of the special parameters *\b* and @\b@ (see S\bSp\bpe\bec\bci\bia\bal\bl P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs above). |
1515 | ${#_\bn_\ba_\bm_\be[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt]} expands to the length of ${_\bn_\ba_\bm_\be[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt]}. If | |
8868edaf CR |
1516 | _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt is *\b* or @\b@, the expansion is the number of elements in the ar- |
1517 | ray. If the _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt used to reference an element of an indexed array | |
74091dd4 CR |
1518 | evaluates to a number less than zero, it is interpreted as relative to |
1519 | one greater than the maximum index of the array, so negative indices | |
8868edaf CR |
1520 | count back from the end of the array, and an index of -1 references the |
1521 | last element. | |
a0c0a00f CR |
1522 | |
1523 | Referencing an array variable without a subscript is equivalent to ref- | |
74091dd4 | 1524 | erencing the array with a subscript of 0. Any reference to a variable |
a0c0a00f CR |
1525 | using a valid subscript is legal, and b\bba\bas\bsh\bh will create an array if nec- |
1526 | essary. | |
17345e5a | 1527 | |
74091dd4 | 1528 | An array variable is considered set if a subscript has been assigned a |
0001803f CR |
1529 | value. The null string is a valid value. |
1530 | ||
74091dd4 CR |
1531 | It is possible to obtain the keys (indices) of an array as well as the |
1532 | values. ${!\b!_\bn_\ba_\bm_\be[_\b@]} and ${!\b!_\bn_\ba_\bm_\be[_\b*]} expand to the indices assigned in | |
ac50fbac CR |
1533 | array variable _\bn_\ba_\bm_\be. The treatment when in double quotes is similar to |
1534 | the expansion of the special parameters _\b@ and _\b* within double quotes. | |
1535 | ||
8868edaf CR |
1536 | The u\bun\bns\bse\bet\bt builtin is used to destroy arrays. u\bun\bns\bse\bet\bt _\bn_\ba_\bm_\be[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt] de- |
1537 | stroys the array element at index _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt, for both indexed and asso- | |
74091dd4 CR |
1538 | ciative arrays. Negative subscripts to indexed arrays are interpreted |
1539 | as described above. Unsetting the last element of an array variable | |
1540 | does not unset the variable. u\bun\bns\bse\bet\bt _\bn_\ba_\bm_\be, where _\bn_\ba_\bm_\be is an array, re- | |
1541 | moves the entire array. u\bun\bns\bse\bet\bt _\bn_\ba_\bm_\be[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt], where _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt is *\b* or | |
1542 | @\b@, behaves differently depending on whether _\bn_\ba_\bm_\be is an indexed or asso- | |
1543 | ciative array. If _\bn_\ba_\bm_\be is an associative array, this unsets the ele- | |
1544 | ment with subscript *\b* or @\b@. If _\bn_\ba_\bm_\be is an indexed array, unset removes | |
1545 | all of the elements but does not remove the array itself. | |
d233b485 CR |
1546 | |
1547 | When using a variable name with a subscript as an argument to a com- | |
8868edaf CR |
1548 | mand, such as with u\bun\bns\bse\bet\bt, without using the word expansion syntax de- |
1549 | scribed above, the argument is subject to pathname expansion. If path- | |
1550 | name expansion is not desired, the argument should be quoted. | |
d233b485 CR |
1551 | |
1552 | The d\bde\bec\bcl\bla\bar\bre\be, l\blo\boc\bca\bal\bl, and r\bre\bea\bad\bdo\bon\bnl\bly\by builtins each accept a -\b-a\ba option to | |
8868edaf CR |
1553 | specify an indexed array and a -\b-A\bA option to specify an associative ar- |
1554 | ray. If both options are supplied, -\b-A\bA takes precedence. The r\bre\bea\bad\bd | |
d233b485 | 1555 | builtin accepts a -\b-a\ba option to assign a list of words read from the |
ac50fbac CR |
1556 | standard input to an array. The s\bse\bet\bt and d\bde\bec\bcl\bla\bar\bre\be builtins display array |
1557 | values in a way that allows them to be reused as assignments. | |
17345e5a JA |
1558 | |
1559 | E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
1560 | Expansion is performed on the command line after it has been split into | |
d233b485 CR |
1561 | words. There are seven kinds of expansion performed: _\bb_\br_\ba_\bc_\be _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn, |
1562 | _\bt_\bi_\bl_\bd_\be _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn, _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br _\ba_\bn_\bd _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn, _\bc_\bo_\bm_\bm_\ba_\bn_\bd _\bs_\bu_\bb_\bs_\bt_\bi_\bt_\bu_\b- | |
17345e5a JA |
1563 | _\bt_\bi_\bo_\bn, _\ba_\br_\bi_\bt_\bh_\bm_\be_\bt_\bi_\bc _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn, _\bw_\bo_\br_\bd _\bs_\bp_\bl_\bi_\bt_\bt_\bi_\bn_\bg, and _\bp_\ba_\bt_\bh_\bn_\ba_\bm_\be _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn. |
1564 | ||
ac50fbac | 1565 | The order of expansions is: brace expansion; tilde expansion, parameter |
d233b485 CR |
1566 | and variable expansion, arithmetic expansion, and command substitution |
1567 | (done in a left-to-right fashion); word splitting; and pathname expan- | |
ac50fbac | 1568 | sion. |
17345e5a JA |
1569 | |
1570 | On systems that can support it, there is an additional expansion avail- | |
d233b485 CR |
1571 | able: _\bp_\br_\bo_\bc_\be_\bs_\bs _\bs_\bu_\bb_\bs_\bt_\bi_\bt_\bu_\bt_\bi_\bo_\bn. This is performed at the same time as |
1572 | tilde, parameter, variable, and arithmetic expansion and command sub- | |
ac50fbac | 1573 | stitution. |
17345e5a | 1574 | |
d233b485 CR |
1575 | After these expansions are performed, quote characters present in the |
1576 | original word are removed unless they have been quoted themselves | |
a0c0a00f CR |
1577 | (_\bq_\bu_\bo_\bt_\be _\br_\be_\bm_\bo_\bv_\ba_\bl). |
1578 | ||
8868edaf CR |
1579 | Only brace expansion, word splitting, and pathname expansion can in- |
1580 | crease the number of words of the expansion; other expansions expand a | |
1581 | single word to a single word. The only exceptions to this are the ex- | |
1582 | pansions of "$\b$@\b@" and "$\b${\b{_\bn_\ba_\bm_\be[\b[@\b@]\b]}\b}", and, in most cases, $\b$*\b* and | |
d233b485 | 1583 | $\b${\b{_\bn_\ba_\bm_\be[\b[*\b*]\b]}\b} as explained above (see P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS). |
17345e5a JA |
1584 | |
1585 | B\bBr\bra\bac\bce\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
1586 | _\bB_\br_\ba_\bc_\be _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn is a mechanism by which arbitrary strings may be gener- | |
1587 | ated. This mechanism is similar to _\bp_\ba_\bt_\bh_\bn_\ba_\bm_\be _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn, but the file- | |
1588 | names generated need not exist. Patterns to be brace expanded take the | |
1589 | form of an optional _\bp_\br_\be_\ba_\bm_\bb_\bl_\be, followed by either a series of comma-sep- | |
1590 | arated strings or a sequence expression between a pair of braces, fol- | |
1591 | lowed by an optional _\bp_\bo_\bs_\bt_\bs_\bc_\br_\bi_\bp_\bt. The preamble is prefixed to each | |
1592 | string contained within the braces, and the postscript is then appended | |
1593 | to each resulting string, expanding left to right. | |
1594 | ||
1595 | Brace expansions may be nested. The results of each expanded string | |
1596 | are not sorted; left to right order is preserved. For example, | |
1597 | a{\b{d,c,b}\b}e expands into `ade ace abe'. | |
1598 | ||
1599 | A sequence expression takes the form {\b{_\bx.\b..\b._\by[\b[.\b..\b._\bi_\bn_\bc_\br]\b]}\b}, where _\bx and _\by are | |
74091dd4 CR |
1600 | either integers or single letters, and _\bi_\bn_\bc_\br, an optional increment, is |
1601 | an integer. When integers are supplied, the expression expands to each | |
1602 | number between _\bx and _\by, inclusive. Supplied integers may be prefixed | |
1603 | with _\b0 to force each term to have the same width. When either _\bx or _\by | |
1604 | begins with a zero, the shell attempts to force all generated terms to | |
1605 | contain the same number of digits, zero-padding where necessary. When | |
1606 | letters are supplied, the expression expands to each character lexico- | |
1607 | graphically between _\bx and _\by, inclusive, using the default C locale. | |
1608 | Note that both _\bx and _\by must be of the same type (integer or letter). | |
1609 | When the increment is supplied, it is used as the difference between | |
1610 | each term. The default increment is 1 or -1 as appropriate. | |
17345e5a JA |
1611 | |
1612 | Brace expansion is performed before any other expansions, and any char- | |
1613 | acters special to other expansions are preserved in the result. It is | |
1614 | strictly textual. B\bBa\bas\bsh\bh does not apply any syntactic interpretation to | |
1615 | the context of the expansion or the text between the braces. | |
1616 | ||
1617 | A correctly-formed brace expansion must contain unquoted opening and | |
8868edaf CR |
1618 | closing braces, and at least one unquoted comma or a valid sequence ex- |
1619 | pression. Any incorrectly formed brace expansion is left unchanged. A | |
1620 | {\b{ or ,\b, may be quoted with a backslash to prevent its being considered | |
17345e5a | 1621 | part of a brace expression. To avoid conflicts with parameter expan- |
d233b485 CR |
1622 | sion, the string $\b${\b{ is not considered eligible for brace expansion, and |
1623 | inhibits brace expansion until the closing }\b}. | |
17345e5a JA |
1624 | |
1625 | This construct is typically used as shorthand when the common prefix of | |
1626 | the strings to be generated is longer than in the above example: | |
1627 | ||
1628 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
1629 | or | |
1630 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
1631 | ||
d233b485 CR |
1632 | Brace expansion introduces a slight incompatibility with historical |
1633 | versions of s\bsh\bh. s\bsh\bh does not treat opening or closing braces specially | |
1634 | when they appear as part of a word, and preserves them in the output. | |
1635 | B\bBa\bas\bsh\bh removes braces from words as a consequence of brace expansion. | |
1636 | For example, a word entered to s\bsh\bh as _\bf_\bi_\bl_\be_\b{_\b1_\b,_\b2_\b} appears identically in | |
1637 | the output. The same word is output as _\bf_\bi_\bl_\be_\b1 _\bf_\bi_\bl_\be_\b2 after expansion by | |
1638 | b\bba\bas\bsh\bh. If strict compatibility with s\bsh\bh is desired, start b\bba\bas\bsh\bh with the | |
17345e5a JA |
1639 | +\b+B\bB option or disable brace expansion with the +\b+B\bB option to the s\bse\bet\bt com- |
1640 | mand (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). | |
1641 | ||
1642 | T\bTi\bil\bld\bde\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
d233b485 CR |
1643 | If a word begins with an unquoted tilde character (`~\b~'), all of the |
1644 | characters preceding the first unquoted slash (or all characters, if | |
1645 | there is no unquoted slash) are considered a _\bt_\bi_\bl_\bd_\be_\b-_\bp_\br_\be_\bf_\bi_\bx. If none of | |
1646 | the characters in the tilde-prefix are quoted, the characters in the | |
1647 | tilde-prefix following the tilde are treated as a possible _\bl_\bo_\bg_\bi_\bn _\bn_\ba_\bm_\be. | |
1648 | If this login name is the null string, the tilde is replaced with the | |
1649 | value of the shell parameter H\bHO\bOM\bME\bE. If H\bHO\bOM\bME\bE is unset, the home direc- | |
1650 | tory of the user executing the shell is substituted instead. Other- | |
1651 | wise, the tilde-prefix is replaced with the home directory associated | |
17345e5a JA |
1652 | with the specified login name. |
1653 | ||
8868edaf CR |
1654 | If the tilde-prefix is a `~+', the value of the shell variable P\bPW\bWD\bD re- |
1655 | places the tilde-prefix. If the tilde-prefix is a `~-', the value of | |
d233b485 CR |
1656 | the shell variable O\bOL\bLD\bDP\bPW\bWD\bD, if it is set, is substituted. If the char- |
1657 | acters following the tilde in the tilde-prefix consist of a number _\bN, | |
1658 | optionally prefixed by a `+' or a `-', the tilde-prefix is replaced | |
17345e5a JA |
1659 | with the corresponding element from the directory stack, as it would be |
1660 | displayed by the d\bdi\bir\brs\bs builtin invoked with the tilde-prefix as an argu- | |
d233b485 | 1661 | ment. If the characters following the tilde in the tilde-prefix con- |
17345e5a JA |
1662 | sist of a number without a leading `+' or `-', `+' is assumed. |
1663 | ||
1664 | If the login name is invalid, or the tilde expansion fails, the word is | |
1665 | unchanged. | |
1666 | ||
1667 | Each variable assignment is checked for unquoted tilde-prefixes immedi- | |
1668 | ately following a :\b: or the first =\b=. In these cases, tilde expansion is | |
8868edaf CR |
1669 | also performed. Consequently, one may use filenames with tildes in as- |
1670 | signments to P\bPA\bAT\bTH\bH, M\bMA\bAI\bIL\bLP\bPA\bAT\bTH\bH, and C\bCD\bDP\bPA\bAT\bTH\bH, and the shell assigns the ex- | |
1671 | panded value. | |
17345e5a | 1672 | |
d233b485 CR |
1673 | Bash also performs tilde expansion on words satisfying the conditions |
1674 | of variable assignments (as described above under P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS) when they | |
1675 | appear as arguments to simple commands. Bash does not do this, except | |
1676 | for the _\bd_\be_\bc_\bl_\ba_\br_\ba_\bt_\bi_\bo_\bn commands listed above, when in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be. | |
1677 | ||
17345e5a JA |
1678 | P\bPa\bar\bra\bam\bme\bet\bte\ber\br E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn |
1679 | The `$\b$' character introduces parameter expansion, command substitution, | |
1680 | or arithmetic expansion. The parameter name or symbol to be expanded | |
1681 | may be enclosed in braces, which are optional but serve to protect the | |
1682 | variable to be expanded from characters immediately following it which | |
1683 | could be interpreted as part of the name. | |
1684 | ||
1685 | When braces are used, the matching ending brace is the first `}\b}' not | |
8868edaf CR |
1686 | escaped by a backslash or within a quoted string, and not within an em- |
1687 | bedded arithmetic expansion, command substitution, or parameter expan- | |
1688 | sion. | |
17345e5a JA |
1689 | |
1690 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br} | |
1691 | The value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is substituted. The braces are required | |
1692 | when _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is a positional parameter with more than one | |
1693 | digit, or when _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is followed by a character which is not | |
ac50fbac CR |
1694 | to be interpreted as part of its name. The _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is a shell |
1695 | parameter as described above P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS) or an array reference | |
1696 | (A\bAr\brr\bra\bay\bys\bs). | |
1697 | ||
a0c0a00f | 1698 | If the first character of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an exclamation point (!\b!), and |
d233b485 | 1699 | _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is not a _\bn_\ba_\bm_\be_\br_\be_\bf, it introduces a level of indirection. B\bBa\bas\bsh\bh |
8868edaf CR |
1700 | uses the value formed by expanding the rest of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br as the new _\bp_\ba_\b- |
1701 | _\br_\ba_\bm_\be_\bt_\be_\br; this is then expanded and that value is used in the rest of | |
d233b485 | 1702 | the expansion, rather than the expansion of the original _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br. |
8868edaf CR |
1703 | This is known as _\bi_\bn_\bd_\bi_\br_\be_\bc_\bt _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn. The value is subject to tilde ex- |
1704 | pansion, parameter expansion, command substitution, and arithmetic ex- | |
1705 | pansion. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is a nameref, this expands to the name of the | |
d233b485 CR |
1706 | parameter referenced by _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br instead of performing the complete |
1707 | indirect expansion. The exceptions to this are the expansions of | |
1708 | ${!\b!_\bp_\br_\be_\bf_\bi_\bx*\b*} and ${!\b!_\bn_\ba_\bm_\be[_\b@]} described below. The exclamation point | |
1709 | must immediately follow the left brace in order to introduce indirec- | |
1710 | tion. | |
17345e5a JA |
1711 | |
1712 | In each of the cases below, _\bw_\bo_\br_\bd is subject to tilde expansion, parame- | |
1713 | ter expansion, command substitution, and arithmetic expansion. | |
1714 | ||
8868edaf CR |
1715 | When not performing substring expansion, using the forms documented be- |
1716 | low (e.g., :\b:-\b-), b\bba\bas\bsh\bh tests for a parameter that is unset or null. | |
1717 | Omitting the colon results in a test only for a parameter that is un- | |
1718 | set. | |
17345e5a JA |
1719 | |
1720 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:-\b-_\bw_\bo_\br_\bd} | |
ac50fbac CR |
1721 | U\bUs\bse\be D\bDe\bef\bfa\bau\bul\blt\bt V\bVa\bal\blu\bue\bes\bs. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is unset or null, the expan- |
1722 | sion of _\bw_\bo_\br_\bd is substituted. Otherwise, the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br | |
17345e5a JA |
1723 | is substituted. |
1724 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:=\b=_\bw_\bo_\br_\bd} | |
8868edaf CR |
1725 | A\bAs\bss\bsi\big\bgn\bn D\bDe\bef\bfa\bau\bul\blt\bt V\bVa\bal\blu\bue\bes\bs. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is unset or null, the ex- |
1726 | pansion of _\bw_\bo_\br_\bd is assigned to _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br. The value of _\bp_\ba_\br_\ba_\bm_\be_\b- | |
1727 | _\bt_\be_\br is then substituted. Positional parameters and special pa- | |
1728 | rameters may not be assigned to in this way. | |
17345e5a | 1729 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:?\b?_\bw_\bo_\br_\bd} |
ac50fbac CR |
1730 | D\bDi\bis\bsp\bpl\bla\bay\by E\bEr\brr\bro\bor\br i\bif\bf N\bNu\bul\bll\bl o\bor\br U\bUn\bns\bse\bet\bt. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is null or unset, |
1731 | the expansion of _\bw_\bo_\br_\bd (or a message to that effect if _\bw_\bo_\br_\bd is | |
1732 | not present) is written to the standard error and the shell, if | |
17345e5a JA |
1733 | it is not interactive, exits. Otherwise, the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
1734 | is substituted. | |
1735 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:+\b+_\bw_\bo_\br_\bd} | |
ac50fbac | 1736 | U\bUs\bse\be A\bAl\blt\bte\ber\brn\bna\bat\bte\be V\bVa\bal\blu\bue\be. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is null or unset, nothing is |
17345e5a JA |
1737 | substituted, otherwise the expansion of _\bw_\bo_\br_\bd is substituted. |
1738 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:_\bo_\bf_\bf_\bs_\be_\bt} | |
1739 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:_\bo_\bf_\bf_\bs_\be_\bt:\b:_\bl_\be_\bn_\bg_\bt_\bh} | |
ac50fbac CR |
1740 | S\bSu\bub\bbs\bst\btr\bri\bin\bng\bg E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn. Expands to up to _\bl_\be_\bn_\bg_\bt_\bh characters of the |
1741 | value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br starting at the character specified by _\bo_\bf_\bf_\b- | |
74091dd4 CR |
1742 | _\bs_\be_\bt. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, an indexed array subscripted by @\b@ |
1743 | or *\b*, or an associative array name, the results differ as de- | |
1744 | scribed below. If _\bl_\be_\bn_\bg_\bt_\bh is omitted, expands to the substring | |
1745 | of the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br starting at the character specified by | |
1746 | _\bo_\bf_\bf_\bs_\be_\bt and extending to the end of the value. _\bl_\be_\bn_\bg_\bt_\bh and _\bo_\bf_\bf_\bs_\be_\bt | |
1747 | are arithmetic expressions (see A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN below). | |
ac50fbac CR |
1748 | |
1749 | If _\bo_\bf_\bf_\bs_\be_\bt evaluates to a number less than zero, the value is | |
8868edaf CR |
1750 | used as an offset in characters from the end of the value of _\bp_\ba_\b- |
1751 | _\br_\ba_\bm_\be_\bt_\be_\br. If _\bl_\be_\bn_\bg_\bt_\bh evaluates to a number less than zero, it is | |
1752 | interpreted as an offset in characters from the end of the value | |
1753 | of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br rather than a number of characters, and the expan- | |
1754 | sion is the characters between _\bo_\bf_\bf_\bs_\be_\bt and that result. Note | |
1755 | that a negative offset must be separated from the colon by at | |
1756 | least one space to avoid being confused with the :\b:-\b- expansion. | |
1757 | ||
74091dd4 CR |
1758 | If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the result is _\bl_\be_\bn_\bg_\bt_\bh positional parame- |
1759 | ters beginning at _\bo_\bf_\bf_\bs_\be_\bt. A negative _\bo_\bf_\bf_\bs_\be_\bt is taken relative | |
1760 | to one greater than the greatest positional parameter, so an | |
1761 | offset of -1 evaluates to the last positional parameter. It is | |
1762 | an expansion error if _\bl_\be_\bn_\bg_\bt_\bh evaluates to a number less than | |
1763 | zero. | |
ac50fbac CR |
1764 | |
1765 | If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an indexed array name subscripted by @ or *, the | |
74091dd4 CR |
1766 | result is the _\bl_\be_\bn_\bg_\bt_\bh members of the array beginning with ${_\bp_\ba_\b- |
1767 | _\br_\ba_\bm_\be_\bt_\be_\br[_\bo_\bf_\bf_\bs_\be_\bt]}. A negative _\bo_\bf_\bf_\bs_\be_\bt is taken relative to one | |
8868edaf CR |
1768 | greater than the maximum index of the specified array. It is an |
1769 | expansion error if _\bl_\be_\bn_\bg_\bt_\bh evaluates to a number less than zero. | |
ac50fbac | 1770 | |
8868edaf CR |
1771 | Substring expansion applied to an associative array produces un- |
1772 | defined results. | |
ac50fbac | 1773 | |
74091dd4 CR |
1774 | Substring indexing is zero-based unless the positional parame- |
1775 | ters are used, in which case the indexing starts at 1 by de- | |
1776 | fault. If _\bo_\bf_\bf_\bs_\be_\bt is 0, and the positional parameters are used, | |
8868edaf | 1777 | $\b$0\b0 is prefixed to the list. |
17345e5a JA |
1778 | |
1779 | ${!\b!_\bp_\br_\be_\bf_\bi_\bx*\b*} | |
1780 | ${!\b!_\bp_\br_\be_\bf_\bi_\bx@\b@} | |
74091dd4 | 1781 | N\bNa\bam\bme\bes\bs m\bma\bat\btc\bch\bhi\bin\bng\bg p\bpr\bre\bef\bfi\bix\bx. Expands to the names of variables whose |
17345e5a | 1782 | names begin with _\bp_\br_\be_\bf_\bi_\bx, separated by the first character of the |
74091dd4 CR |
1783 | I\bIF\bFS\bS special variable. When _\b@ is used and the expansion appears |
1784 | within double quotes, each variable name expands to a separate | |
17345e5a JA |
1785 | word. |
1786 | ||
1787 | ${!\b!_\bn_\ba_\bm_\be[_\b@]} | |
1788 | ${!\b!_\bn_\ba_\bm_\be[_\b*]} | |
74091dd4 CR |
1789 | L\bLi\bis\bst\bt o\bof\bf a\bar\brr\bra\bay\by k\bke\bey\bys\bs. If _\bn_\ba_\bm_\be is an array variable, expands to |
1790 | the list of array indices (keys) assigned in _\bn_\ba_\bm_\be. If _\bn_\ba_\bm_\be is | |
1791 | not an array, expands to 0 if _\bn_\ba_\bm_\be is set and null otherwise. | |
1792 | When _\b@ is used and the expansion appears within double quotes, | |
17345e5a JA |
1793 | each key expands to a separate word. |
1794 | ||
1795 | ${#\b#_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br} | |
74091dd4 CR |
1796 | P\bPa\bar\bra\bam\bme\bet\bte\ber\br l\ble\ben\bng\bgt\bth\bh. The length in characters of the value of _\bp_\ba_\b- |
1797 | _\br_\ba_\bm_\be_\bt_\be_\br is substituted. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is *\b* or @\b@, the value sub- | |
1798 | stituted is the number of positional parameters. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br | |
8868edaf CR |
1799 | is an array name subscripted by *\b* or @\b@, the value substituted is |
1800 | the number of elements in the array. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an indexed | |
74091dd4 CR |
1801 | array name subscripted by a negative number, that number is in- |
1802 | terpreted as relative to one greater than the maximum index of | |
1803 | _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br, so negative indices count back from the end of the | |
8868edaf | 1804 | array, and an index of -1 references the last element. |
17345e5a JA |
1805 | |
1806 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br#\b#_\bw_\bo_\br_\bd} | |
1807 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br#\b##\b#_\bw_\bo_\br_\bd} | |
495aee44 | 1808 | R\bRe\bem\bmo\bov\bve\be m\bma\bat\btc\bch\bhi\bin\bng\bg p\bpr\bre\bef\bfi\bix\bx p\bpa\bat\btt\bte\ber\brn\bn. The _\bw_\bo_\br_\bd is expanded to produce |
d233b485 CR |
1809 | a pattern just as in pathname expansion, and matched against the |
1810 | expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br using the rules described under P\bPa\bat\bt-\b- | |
74091dd4 CR |
1811 | t\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg below. If the pattern matches the beginning of |
1812 | the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br, then the result of the expansion is the | |
1813 | expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br with the shortest matching pattern | |
1814 | (the ``#\b#'' case) or the longest matching pattern (the ``#\b##\b#'' | |
1815 | case) deleted. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the pattern removal op- | |
8868edaf CR |
1816 | eration is applied to each positional parameter in turn, and the |
1817 | expansion is the resultant list. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an array vari- | |
74091dd4 CR |
1818 | able subscripted with @\b@ or *\b*, the pattern removal operation is |
1819 | applied to each member of the array in turn, and the expansion | |
8868edaf | 1820 | is the resultant list. |
d233b485 CR |
1821 | |
1822 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br%\b%_\bw_\bo_\br_\bd} | |
1823 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br%\b%%\b%_\bw_\bo_\br_\bd} | |
1824 | R\bRe\bem\bmo\bov\bve\be m\bma\bat\btc\bch\bhi\bin\bng\bg s\bsu\buf\bff\bfi\bix\bx p\bpa\bat\btt\bte\ber\brn\bn. The _\bw_\bo_\br_\bd is expanded to produce | |
1825 | a pattern just as in pathname expansion, and matched against the | |
1826 | expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br using the rules described under P\bPa\bat\bt-\b- | |
74091dd4 CR |
1827 | t\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg below. If the pattern matches a trailing portion |
1828 | of the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br, then the result of the ex- | |
1829 | pansion is the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br with the shortest | |
1830 | matching pattern (the ``%\b%'' case) or the longest matching pat- | |
1831 | tern (the ``%\b%%\b%'' case) deleted. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the | |
1832 | pattern removal operation is applied to each positional parame- | |
17345e5a | 1833 | ter in turn, and the expansion is the resultant list. If _\bp_\ba_\br_\ba_\bm_\b- |
74091dd4 CR |
1834 | _\be_\bt_\be_\br is an array variable subscripted with @\b@ or *\b*, the pattern |
1835 | removal operation is applied to each member of the array in | |
17345e5a JA |
1836 | turn, and the expansion is the resultant list. |
1837 | ||
17345e5a | 1838 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br/\b/_\bp_\ba_\bt_\bt_\be_\br_\bn/\b/_\bs_\bt_\br_\bi_\bn_\bg} |
74091dd4 CR |
1839 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br/\b//\b/_\bp_\ba_\bt_\bt_\be_\br_\bn/\b/_\bs_\bt_\br_\bi_\bn_\bg} |
1840 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br/\b/#\b#_\bp_\ba_\bt_\bt_\be_\br_\bn/\b/_\bs_\bt_\br_\bi_\bn_\bg} | |
1841 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br/\b/%\b%_\bp_\ba_\bt_\bt_\be_\br_\bn/\b/_\bs_\bt_\br_\bi_\bn_\bg} | |
495aee44 | 1842 | P\bPa\bat\btt\bte\ber\brn\bn s\bsu\bub\bbs\bst\bti\bit\btu\but\bti\bio\bon\bn. The _\bp_\ba_\bt_\bt_\be_\br_\bn is expanded to produce a pat- |
74091dd4 CR |
1843 | tern just as in pathname expansion. _\bP_\ba_\br_\ba_\bm_\be_\bt_\be_\br is expanded and |
1844 | the longest match of _\bp_\ba_\bt_\bt_\be_\br_\bn against its value is replaced with | |
1845 | _\bs_\bt_\br_\bi_\bn_\bg. _\bs_\bt_\br_\bi_\bn_\bg undergoes tilde expansion, parameter and vari- | |
1846 | able expansion, arithmetic expansion, command and process sub- | |
1847 | stitution, and quote removal. The match is performed using the | |
1848 | rules described under P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg below. In the first form | |
1849 | above, only the first match is replaced. If there are two | |
1850 | slashes separating _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br and _\bp_\ba_\bt_\bt_\be_\br_\bn (the second form | |
1851 | above), all matches of _\bp_\ba_\bt_\bt_\be_\br_\bn are replaced with _\bs_\bt_\br_\bi_\bn_\bg. If | |
1852 | _\bp_\ba_\bt_\bt_\be_\br_\bn is preceded by #\b# (the third form above), it must match | |
1853 | at the beginning of the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br. If _\bp_\ba_\bt_\bt_\be_\br_\bn | |
1854 | is preceded by %\b% (the fourth form above), it must match at the | |
1855 | end of the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br. If the expansion of | |
1856 | _\bs_\bt_\br_\bi_\bn_\bg is null, matches of _\bp_\ba_\bt_\bt_\be_\br_\bn are deleted. If _\bs_\bt_\br_\bi_\bn_\bg is | |
1857 | null, matches of _\bp_\ba_\bt_\bt_\be_\br_\bn are deleted and the /\b/ following _\bp_\ba_\bt_\bt_\be_\br_\bn | |
1858 | may be omitted. | |
1859 | ||
1860 | If the p\bpa\bat\bts\bsu\bub\bb_\b_r\bre\bep\bpl\bla\bac\bce\bem\bme\ben\bnt\bt shell option is enabled using s\bsh\bho\bop\bpt\bt, | |
1861 | any unquoted instances of &\b& in _\bs_\bt_\br_\bi_\bn_\bg are replaced with the | |
1862 | matching portion of _\bp_\ba_\bt_\bt_\be_\br_\bn. | |
1863 | ||
1864 | Quoting any part of _\bs_\bt_\br_\bi_\bn_\bg inhibits replacement in the expansion | |
1865 | of the quoted portion, including replacement strings stored in | |
1866 | shell variables. Backslash will escape &\b& in _\bs_\bt_\br_\bi_\bn_\bg; the back- | |
1867 | slash is removed in order to permit a literal &\b& in the replace- | |
1868 | ment string. Backslash can also be used to escape a backslash; | |
1869 | \\b\\\b\ results in a literal backslash in the replacement. Users | |
1870 | should take care if _\bs_\bt_\br_\bi_\bn_\bg is double-quoted to avoid unwanted | |
1871 | interactions between the backslash and double-quoting, since | |
1872 | backslash has special meaning within double quotes. Pattern | |
1873 | substitution performs the check for unquoted &\b& after expanding | |
1874 | _\bs_\bt_\br_\bi_\bn_\bg; shell programmers should quote any occurrences of &\b& they | |
1875 | want to be taken literally in the replacement and ensure any in- | |
1876 | stances of &\b& they want to be replaced are unquoted. | |
1877 | ||
1878 | If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh shell option is enabled, the match is per- | |
1879 | formed without regard to the case of alphabetic characters. If | |
1880 | _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the substitution operation is applied to | |
1881 | each positional parameter in turn, and the expansion is the re- | |
1882 | sultant list. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an array variable subscripted | |
1883 | with @\b@ or *\b*, the substitution operation is applied to each mem- | |
1884 | ber of the array in turn, and the expansion is the resultant | |
1885 | list. | |
17345e5a JA |
1886 | |
1887 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br^\b^_\bp_\ba_\bt_\bt_\be_\br_\bn} | |
1888 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br^\b^^\b^_\bp_\ba_\bt_\bt_\be_\br_\bn} | |
1889 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br,\b,_\bp_\ba_\bt_\bt_\be_\br_\bn} | |
1890 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br,\b,,\b,_\bp_\ba_\bt_\bt_\be_\br_\bn} | |
74091dd4 CR |
1891 | C\bCa\bas\bse\be m\bmo\bod\bdi\bif\bfi\bic\bca\bat\bti\bio\bon\bn. This expansion modifies the case of alpha- |
1892 | betic characters in _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br. The _\bp_\ba_\bt_\bt_\be_\br_\bn is expanded to pro- | |
ac50fbac | 1893 | duce a pattern just as in pathname expansion. Each character in |
74091dd4 CR |
1894 | the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is tested against _\bp_\ba_\bt_\bt_\be_\br_\bn, and, |
1895 | if it matches the pattern, its case is converted. The pattern | |
1896 | should not attempt to match more than one character. The ^\b^ op- | |
8868edaf CR |
1897 | erator converts lowercase letters matching _\bp_\ba_\bt_\bt_\be_\br_\bn to uppercase; |
1898 | the ,\b, operator converts matching uppercase letters to lowercase. | |
74091dd4 CR |
1899 | The ^\b^^\b^ and ,\b,,\b, expansions convert each matched character in the |
1900 | expanded value; the ^\b^ and ,\b, expansions match and convert only | |
1901 | the first character in the expanded value. If _\bp_\ba_\bt_\bt_\be_\br_\bn is omit- | |
1902 | ted, it is treated like a ?\b?, which matches every character. If | |
1903 | _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the case modification operation is applied | |
1904 | to each positional parameter in turn, and the expansion is the | |
1905 | resultant list. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an array variable subscripted | |
1906 | with @\b@ or *\b*, the case modification operation is applied to each | |
1907 | member of the array in turn, and the expansion is the resultant | |
8868edaf | 1908 | list. |
17345e5a | 1909 | |
a0c0a00f CR |
1910 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br@\b@_\bo_\bp_\be_\br_\ba_\bt_\bo_\br} |
1911 | P\bPa\bar\bra\bam\bme\bet\bte\ber\br t\btr\bra\ban\bns\bsf\bfo\bor\brm\bma\bat\bti\bio\bon\bn. The expansion is either a transforma- | |
74091dd4 CR |
1912 | tion of the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br or information about _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
1913 | itself, depending on the value of _\bo_\bp_\be_\br_\ba_\bt_\bo_\br. Each _\bo_\bp_\be_\br_\ba_\bt_\bo_\br is a | |
a0c0a00f CR |
1914 | single letter: |
1915 | ||
74091dd4 CR |
1916 | U\bU The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
1917 | with lowercase alphabetic characters converted to upper- | |
8868edaf | 1918 | case. |
74091dd4 | 1919 | u\bu The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
8868edaf CR |
1920 | with the first character converted to uppercase, if it is |
1921 | alphabetic. | |
74091dd4 CR |
1922 | L\bL The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
1923 | with uppercase alphabetic characters converted to lower- | |
8868edaf | 1924 | case. |
74091dd4 | 1925 | Q\bQ The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
a0c0a00f | 1926 | quoted in a format that can be reused as input. |
74091dd4 CR |
1927 | E\bE The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
1928 | with backslash escape sequences expanded as with the | |
d233b485 | 1929 | $\b$'\b'.\b..\b..\b.'\b' quoting mechanism. |
a0c0a00f CR |
1930 | P\bP The expansion is a string that is the result of expanding |
1931 | the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br as if it were a prompt string (see | |
1932 | P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG below). | |
74091dd4 CR |
1933 | A\bA The expansion is a string in the form of an assignment |
1934 | statement or d\bde\bec\bcl\bla\bar\bre\be command that, if evaluated, will | |
a0c0a00f | 1935 | recreate _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br with its attributes and value. |
8868edaf CR |
1936 | K\bK Produces a possibly-quoted version of the value of _\bp_\ba_\br_\ba_\bm_\b- |
1937 | _\be_\bt_\be_\br, except that it prints the values of indexed and as- | |
74091dd4 | 1938 | sociative arrays as a sequence of quoted key-value pairs |
8868edaf | 1939 | (see A\bAr\brr\bra\bay\bys\bs above). |
74091dd4 | 1940 | a\ba The expansion is a string consisting of flag values rep- |
a0c0a00f | 1941 | resenting _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br's attributes. |
74091dd4 CR |
1942 | k\bk Like the K transformation, but expands the keys and val- |
1943 | ues of indexed and associative arrays to separate words | |
1944 | after word splitting. | |
a0c0a00f | 1945 | |
74091dd4 CR |
1946 | If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the operation is applied to each posi- |
1947 | tional parameter in turn, and the expansion is the resultant | |
1948 | list. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an array variable subscripted with @\b@ or | |
d233b485 CR |
1949 | *\b*, the operation is applied to each member of the array in turn, |
1950 | and the expansion is the resultant list. | |
a0c0a00f | 1951 | |
74091dd4 | 1952 | The result of the expansion is subject to word splitting and |
a0c0a00f CR |
1953 | pathname expansion as described below. |
1954 | ||
17345e5a JA |
1955 | C\bCo\bom\bmm\bma\ban\bnd\bd S\bSu\bub\bbs\bst\bti\bit\btu\but\bti\bio\bon\bn |
1956 | _\bC_\bo_\bm_\bm_\ba_\bn_\bd _\bs_\bu_\bb_\bs_\bt_\bi_\bt_\bu_\bt_\bi_\bo_\bn allows the output of a command to replace the com- | |
1957 | mand name. There are two forms: | |
1958 | ||
17345e5a JA |
1959 | $\b$(\b(_\bc_\bo_\bm_\bm_\ba_\bn_\bd)\b) |
1960 | or | |
1961 | `\b`_\bc_\bo_\bm_\bm_\ba_\bn_\bd`\b` | |
1962 | ||
a0c0a00f CR |
1963 | B\bBa\bas\bsh\bh performs the expansion by executing _\bc_\bo_\bm_\bm_\ba_\bn_\bd in a subshell environ- |
1964 | ment and replacing the command substitution with the standard output of | |
1965 | the command, with any trailing newlines deleted. Embedded newlines are | |
74091dd4 CR |
1966 | not deleted, but they may be removed during word splitting. The com- |
1967 | mand substitution $\b$(\b(c\bca\bat\bt _\bf_\bi_\bl_\be)\b) can be replaced by the equivalent but | |
a0c0a00f | 1968 | faster $\b$(\b(<\b< _\bf_\bi_\bl_\be)\b). |
17345e5a | 1969 | |
74091dd4 CR |
1970 | When the old-style backquote form of substitution is used, backslash |
1971 | retains its literal meaning except when followed by $\b$, `\b`, or \\b\. The | |
17345e5a | 1972 | first backquote not preceded by a backslash terminates the command sub- |
74091dd4 | 1973 | stitution. When using the $(_\bc_\bo_\bm_\bm_\ba_\bn_\bd) form, all characters between the |
17345e5a JA |
1974 | parentheses make up the command; none are treated specially. |
1975 | ||
1976 | Command substitutions may be nested. To nest when using the backquoted | |
1977 | form, escape the inner backquotes with backslashes. | |
1978 | ||
74091dd4 | 1979 | If the substitution appears within double quotes, word splitting and |
17345e5a JA |
1980 | pathname expansion are not performed on the results. |
1981 | ||
1982 | A\bAr\bri\bit\bth\bhm\bme\bet\bti\bic\bc E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
74091dd4 CR |
1983 | Arithmetic expansion allows the evaluation of an arithmetic expression |
1984 | and the substitution of the result. The format for arithmetic expan- | |
17345e5a JA |
1985 | sion is: |
1986 | ||
1987 | $\b$(\b((\b(_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn)\b))\b) | |
1988 | ||
74091dd4 CR |
1989 | The _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn undergoes the same expansions as if it were within dou- |
1990 | ble quotes, but double quote characters in _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn are not treated | |
1991 | specially and are removed. All tokens in the expression undergo param- | |
1992 | eter and variable expansion, command substitution, and quote removal. | |
1993 | The result is treated as the arithmetic expression to be evaluated. | |
1994 | Arithmetic expansions may be nested. | |
17345e5a | 1995 | |
74091dd4 | 1996 | The evaluation is performed according to the rules listed below under |
17345e5a JA |
1997 | A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN. If _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn is invalid, b\bba\bas\bsh\bh prints a message |
1998 | indicating failure and no substitution occurs. | |
1999 | ||
2000 | P\bPr\bro\boc\bce\bes\bss\bs S\bSu\bub\bbs\bst\bti\bit\btu\but\bti\bio\bon\bn | |
74091dd4 CR |
2001 | _\bP_\br_\bo_\bc_\be_\bs_\bs _\bs_\bu_\bb_\bs_\bt_\bi_\bt_\bu_\bt_\bi_\bo_\bn allows a process's input or output to be referred |
2002 | to using a filename. It takes the form of <\b<(\b(_\bl_\bi_\bs_\bt)\b) or >\b>(\b(_\bl_\bi_\bs_\bt)\b). The | |
2003 | process _\bl_\bi_\bs_\bt is run asynchronously, and its input or output appears as | |
a0c0a00f | 2004 | a filename. This filename is passed as an argument to the current com- |
74091dd4 CR |
2005 | mand as the result of the expansion. If the >\b>(\b(_\bl_\bi_\bs_\bt)\b) form is used, |
2006 | writing to the file will provide input for _\bl_\bi_\bs_\bt. If the <\b<(\b(_\bl_\bi_\bs_\bt)\b) form | |
2007 | is used, the file passed as an argument should be read to obtain the | |
a0c0a00f CR |
2008 | output of _\bl_\bi_\bs_\bt. Process substitution is supported on systems that sup- |
2009 | port named pipes (_\bF_\bI_\bF_\bO_\bs) or the /\b/d\bde\bev\bv/\b/f\bfd\bd method of naming open files. | |
17345e5a | 2010 | |
74091dd4 CR |
2011 | When available, process substitution is performed simultaneously with |
2012 | parameter and variable expansion, command substitution, and arithmetic | |
17345e5a JA |
2013 | expansion. |
2014 | ||
2015 | W\bWo\bor\brd\bd S\bSp\bpl\bli\bit\btt\bti\bin\bng\bg | |
74091dd4 CR |
2016 | The shell scans the results of parameter expansion, command substitu- |
2017 | tion, and arithmetic expansion that did not occur within double quotes | |
17345e5a JA |
2018 | for _\bw_\bo_\br_\bd _\bs_\bp_\bl_\bi_\bt_\bt_\bi_\bn_\bg. |
2019 | ||
74091dd4 CR |
2020 | The shell treats each character of I\bIF\bFS\bS as a delimiter, and splits the |
2021 | results of the other expansions into words using these characters as | |
2022 | field terminators. If I\bIF\bFS\bS is unset, or its value is exactly | |
2023 | <\b<s\bsp\bpa\bac\bce\be>\b><\b<t\bta\bab\bb>\b><\b<n\bne\bew\bwl\bli\bin\bne\be>\b>, the default, then sequences of <\b<s\bsp\bpa\bac\bce\be>\b>, <\b<t\bta\bab\bb>\b>, | |
2024 | and <\b<n\bne\bew\bwl\bli\bin\bne\be>\b> at the beginning and end of the results of the previous | |
2025 | expansions are ignored, and any sequence of I\bIF\bFS\bS characters not at the | |
2026 | beginning or end serves to delimit words. If I\bIF\bFS\bS has a value other | |
2027 | than the default, then sequences of the whitespace characters s\bsp\bpa\bac\bce\be, | |
2028 | t\bta\bab\bb, and n\bne\bew\bwl\bli\bin\bne\be are ignored at the beginning and end of the word, as | |
2029 | long as the whitespace character is in the value of I\bIF\bFS\bS (an I\bIF\bFS\bS white- | |
2030 | space character). Any character in I\bIF\bFS\bS that is not I\bIF\bFS\bS whitespace, | |
a0c0a00f | 2031 | along with any adjacent I\bIF\bFS\bS whitespace characters, delimits a field. A |
74091dd4 | 2032 | sequence of I\bIF\bFS\bS whitespace characters is also treated as a delimiter. |
a0c0a00f CR |
2033 | If the value of I\bIF\bFS\bS is null, no word splitting occurs. |
2034 | ||
74091dd4 | 2035 | Explicit null arguments ("\b""\b" or '\b''\b') are retained and passed to commands |
a0c0a00f CR |
2036 | as empty strings. Unquoted implicit null arguments, resulting from the |
2037 | expansion of parameters that have no values, are removed. If a parame- | |
8868edaf CR |
2038 | ter with no value is expanded within double quotes, a null argument re- |
2039 | sults and is retained and passed to a command as an empty string. When | |
74091dd4 | 2040 | a quoted null argument appears as part of a word whose expansion is |
8868edaf CR |
2041 | non-null, the null argument is removed. That is, the word -d'' becomes |
2042 | -d after word splitting and null argument removal. | |
17345e5a JA |
2043 | |
2044 | Note that if no expansion occurs, no splitting is performed. | |
2045 | ||
2046 | P\bPa\bat\bth\bhn\bna\bam\bme\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
74091dd4 CR |
2047 | After word splitting, unless the -\b-f\bf option has been set, b\bba\bas\bsh\bh scans |
2048 | each word for the characters *\b*, ?\b?, and [\b[. If one of these characters | |
8868edaf | 2049 | appears, and is not quoted, then the word is regarded as a _\bp_\ba_\bt_\bt_\be_\br_\bn, and |
74091dd4 CR |
2050 | replaced with an alphabetically sorted list of filenames matching the |
2051 | pattern (see P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg below). If no matching filenames are | |
2052 | found, and the shell option n\bnu\bul\bll\blg\bgl\blo\bob\bb is not enabled, the word is left | |
2053 | unchanged. If the n\bnu\bul\bll\blg\bgl\blo\bob\bb option is set, and no matches are found, | |
2054 | the word is removed. If the f\bfa\bai\bil\blg\bgl\blo\bob\bb shell option is set, and no | |
2055 | matches are found, an error message is printed and the command is not | |
8868edaf | 2056 | executed. If the shell option n\bno\boc\bca\bas\bse\beg\bgl\blo\bob\bb is enabled, the match is per- |
74091dd4 CR |
2057 | formed without regard to the case of alphabetic characters. When a |
2058 | pattern is used for pathname expansion, the character `\b``\b`.\b.'\b''\b' at the | |
2059 | start of a name or immediately following a slash must be matched ex- | |
2060 | plicitly, unless the shell option d\bdo\bot\btg\bgl\blo\bob\bb is set. In order to match | |
2061 | the filenames `\b``\b`.\b.'\b''\b' and `\b``\b`.\b..\b.'\b''\b', the pattern must begin with ``.'' (for | |
2062 | example, ``.?''), even if d\bdo\bot\btg\bgl\blo\bob\bb is set. If the g\bgl\blo\bob\bbs\bsk\bki\bip\bpd\bdo\bot\bts\bs shell | |
2063 | option is enabled, the filenames `\b``\b`.\b.'\b''\b' and `\b``\b`.\b..\b.'\b''\b' are never matched, | |
2064 | even if the pattern begins with a `\b``\b`.\b.'\b''\b'. When not matching pathnames, | |
2065 | the `\b``\b`.\b.'\b''\b' character is not treated specially. When matching a path- | |
2066 | name, the slash character must always be matched explicitly by a slash | |
2067 | in the pattern, but in other matching contexts it can be matched by a | |
2068 | special pattern character as described below under P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg. | |
2069 | See the description of s\bsh\bho\bop\bpt\bt below under S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS for a | |
2070 | description of the n\bno\boc\bca\bas\bse\beg\bgl\blo\bob\bb, n\bnu\bul\bll\blg\bgl\blo\bob\bb, g\bgl\blo\bob\bbs\bsk\bki\bip\bpd\bdo\bot\bts\bs, f\bfa\bai\bil\blg\bgl\blo\bob\bb, and | |
8868edaf | 2071 | d\bdo\bot\btg\bgl\blo\bob\bb shell options. |
d233b485 CR |
2072 | |
2073 | The G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE shell variable may be used to restrict the set of file | |
2074 | names matching a _\bp_\ba_\bt_\bt_\be_\br_\bn. If G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE is set, each matching file | |
2075 | name that also matches one of the patterns in G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE is removed | |
2076 | from the list of matches. If the n\bno\boc\bca\bas\bse\beg\bgl\blo\bob\bb option is set, the match- | |
2077 | ing against the patterns in G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE is performed without regard to | |
2078 | case. The filenames `\b``\b`.\b.'\b''\b' and `\b``\b`.\b..\b.'\b''\b' are always ignored when G\bGL\bLO\bOB\bBI\bIG\bG-\b- | |
2079 | N\bNO\bOR\bRE\bE is set and not null. However, setting G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE to a non-null | |
2080 | value has the effect of enabling the d\bdo\bot\btg\bgl\blo\bob\bb shell option, so all other | |
2081 | filenames beginning with a `\b``\b`.\b.'\b''\b' will match. To get the old behavior | |
2082 | of ignoring filenames beginning with a `\b``\b`.\b.'\b''\b', make `\b``\b`.\b.*\b*'\b''\b' one of the | |
2083 | patterns in G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE. The d\bdo\bot\btg\bgl\blo\bob\bb option is disabled when G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE | |
2084 | is unset. The pattern matching honors the setting of the e\bex\bxt\btg\bgl\blo\bob\bb shell | |
a0c0a00f | 2085 | option. |
17345e5a JA |
2086 | |
2087 | P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg | |
2088 | ||
2089 | Any character that appears in a pattern, other than the special pattern | |
d233b485 CR |
2090 | characters described below, matches itself. The NUL character may not |
2091 | occur in a pattern. A backslash escapes the following character; the | |
2092 | escaping backslash is discarded when matching. The special pattern | |
17345e5a JA |
2093 | characters must be quoted if they are to be matched literally. |
2094 | ||
2095 | The special pattern characters have the following meanings: | |
2096 | ||
d233b485 CR |
2097 | *\b* Matches any string, including the null string. When the |
2098 | g\bgl\blo\bob\bbs\bst\bta\bar\br shell option is enabled, and *\b* is used in a | |
2099 | pathname expansion context, two adjacent *\b*s used as a | |
8868edaf CR |
2100 | single pattern will match all files and zero or more di- |
2101 | rectories and subdirectories. If followed by a /\b/, two | |
d233b485 | 2102 | adjacent *\b*s will match only directories and subdirecto- |
495aee44 CR |
2103 | ries. |
2104 | ?\b? Matches any single character. | |
d233b485 CR |
2105 | [\b[.\b..\b..\b.]\b] Matches any one of the enclosed characters. A pair of |
2106 | characters separated by a hyphen denotes a _\br_\ba_\bn_\bg_\be _\be_\bx_\bp_\br_\be_\bs_\b- | |
2107 | _\bs_\bi_\bo_\bn; any character that falls between those two charac- | |
8868edaf CR |
2108 | ters, inclusive, using the current locale's collating se- |
2109 | quence and character set, is matched. If the first char- | |
2110 | acter following the [\b[ is a !\b! or a ^\b^ then any character | |
2111 | not enclosed is matched. The sorting order of characters | |
74091dd4 CR |
2112 | in range expressions, and the characters included in the |
2113 | range, are determined by the current locale and the val- | |
2114 | ues of the L\bLC\bC_\b_C\bCO\bOL\bLL\bLA\bAT\bTE\bE or L\bLC\bC_\b_A\bAL\bLL\bL shell variables, if set. | |
2115 | To obtain the traditional interpretation of range expres- | |
2116 | sions, where [\b[a\ba-\b-d\bd]\b] is equivalent to [\b[a\bab\bbc\bcd\bd]\b], set value of | |
2117 | the L\bLC\bC_\b_A\bAL\bLL\bL shell variable to C\bC, or enable the g\bgl\blo\bob\bba\bas\bsc\bci\bi-\b- | |
2118 | i\bir\bra\ban\bng\bge\bes\bs shell option. A -\b- may be matched by including it | |
2119 | as the first or last character in the set. A ]\b] may be | |
2120 | matched by including it as the first character in the | |
2121 | set. | |
2122 | ||
2123 | Within [\b[ and ]\b], _\bc_\bh_\ba_\br_\ba_\bc_\bt_\be_\br _\bc_\bl_\ba_\bs_\bs_\be_\bs can be specified using | |
495aee44 CR |
2124 | the syntax [\b[:\b:_\bc_\bl_\ba_\bs_\bs:\b:]\b], where _\bc_\bl_\ba_\bs_\bs is one of the following |
2125 | classes defined in the POSIX standard: | |
74091dd4 | 2126 | a\bal\bln\bnu\bum\bm a\bal\blp\bph\bha\ba a\bas\bsc\bci\bii\bi b\bbl\bla\ban\bnk\bk c\bcn\bnt\btr\brl\bl d\bdi\big\bgi\bit\bt g\bgr\bra\bap\bph\bh l\blo\bow\bwe\ber\br p\bpr\bri\bin\bnt\bt |
495aee44 CR |
2127 | p\bpu\bun\bnc\bct\bt s\bsp\bpa\bac\bce\be u\bup\bpp\bpe\ber\br w\bwo\bor\brd\bd x\bxd\bdi\big\bgi\bit\bt |
2128 | A character class matches any character belonging to that | |
2129 | class. The w\bwo\bor\brd\bd character class matches letters, digits, | |
2130 | and the character _. | |
2131 | ||
8868edaf | 2132 | Within [\b[ and ]\b], an _\be_\bq_\bu_\bi_\bv_\ba_\bl_\be_\bn_\bc_\be _\bc_\bl_\ba_\bs_\bs can be specified us- |
74091dd4 CR |
2133 | ing the syntax [\b[=\b=_\bc=\b=]\b], which matches all characters with |
2134 | the same collation weight (as defined by the current lo- | |
8868edaf | 2135 | cale) as the character _\bc. |
495aee44 CR |
2136 | |
2137 | Within [\b[ and ]\b], the syntax [\b[.\b._\bs_\by_\bm_\bb_\bo_\bl.\b.]\b] matches the collat- | |
2138 | ing symbol _\bs_\by_\bm_\bb_\bo_\bl. | |
17345e5a | 2139 | |
74091dd4 CR |
2140 | If the e\bex\bxt\btg\bgl\blo\bob\bb shell option is enabled using the s\bsh\bho\bop\bpt\bt builtin, the |
2141 | shell recognizes several extended pattern matching operators. In the | |
2142 | following description, a _\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt is a list of one or more patterns | |
2143 | separated by a |\b|. Composite patterns may be formed using one or more | |
2144 | of the following sub-patterns: | |
17345e5a JA |
2145 | |
2146 | ?\b?(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2147 | Matches zero or one occurrence of the given patterns | |
2148 | *\b*(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2149 | Matches zero or more occurrences of the given patterns | |
2150 | +\b+(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2151 | Matches one or more occurrences of the given patterns | |
2152 | @\b@(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2153 | Matches one of the given patterns | |
2154 | !\b!(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2155 | Matches anything except one of the given patterns | |
2156 | ||
74091dd4 CR |
2157 | Thee\bex\bxt\btg\bgl\blo\bob\bb option changes the behavior of the parser, since the paren- |
2158 | theses are normally treated as operators with syntactic meaning. To | |
2159 | ensure that extended matching patterns are parsed correctly, make sure | |
2160 | that e\bex\bxt\btg\bgl\blo\bob\bb is enabled before parsing constructs containing the pat- | |
2161 | terns, including shell functions and command substitutions. | |
2162 | ||
2163 | When matching filenames, the d\bdo\bot\btg\bgl\blo\bob\bb shell option determines the set of | |
2164 | filenames that are tested: when d\bdo\bot\btg\bgl\blo\bob\bb is enabled, the set of file- | |
2165 | names includes all files beginning with ``.'', but ``.'' and ``..'' | |
2166 | must be matched by a pattern or sub-pattern that begins with a dot; | |
2167 | when it is disabled, the set does not include any filenames beginning | |
2168 | with ``.'' unless the pattern or sub-pattern begins with a ``.''. As | |
2169 | above, ``.'' only has a special meaning when matching filenames. | |
2170 | ||
8868edaf CR |
2171 | Complicated extended pattern matching against long strings is slow, es- |
2172 | pecially when the patterns contain alternations and the strings contain | |
74091dd4 | 2173 | multiple matches. Using separate matches against shorter strings, or |
8868edaf | 2174 | using arrays of strings instead of a single long string, may be faster. |
d233b485 | 2175 | |
17345e5a JA |
2176 | Q\bQu\buo\bot\bte\be R\bRe\bem\bmo\bov\bva\bal\bl |
2177 | After the preceding expansions, all unquoted occurrences of the charac- | |
74091dd4 | 2178 | ters \\b\, '\b', and "\b" that did not result from one of the above expansions |
17345e5a JA |
2179 | are removed. |
2180 | ||
2181 | R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN | |
74091dd4 CR |
2182 | Before a command is executed, its input and output may be _\br_\be_\bd_\bi_\br_\be_\bc_\bt_\be_\bd |
2183 | using a special notation interpreted by the shell. _\bR_\be_\bd_\bi_\br_\be_\bc_\bt_\bi_\bo_\bn allows | |
2184 | commands' file handles to be duplicated, opened, closed, made to refer | |
ac50fbac | 2185 | to different files, and can change the files the command reads from and |
74091dd4 CR |
2186 | writes to. Redirection may also be used to modify file handles in the |
2187 | current shell execution environment. The following redirection opera- | |
ac50fbac | 2188 | tors may precede or appear anywhere within a _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd or may fol- |
74091dd4 | 2189 | low a _\bc_\bo_\bm_\bm_\ba_\bn_\bd. Redirections are processed in the order they appear, |
ac50fbac | 2190 | from left to right. |
17345e5a | 2191 | |
74091dd4 | 2192 | Each redirection that may be preceded by a file descriptor number may |
0001803f CR |
2193 | instead be preceded by a word of the form {_\bv_\ba_\br_\bn_\ba_\bm_\be}. In this case, for |
2194 | each redirection operator except >&- and <&-, the shell will allocate a | |
74091dd4 CR |
2195 | file descriptor greater than or equal to 10 and assign it to _\bv_\ba_\br_\bn_\ba_\bm_\be. |
2196 | If >&- or <&- is preceded by {_\bv_\ba_\br_\bn_\ba_\bm_\be}, the value of _\bv_\ba_\br_\bn_\ba_\bm_\be defines | |
2197 | the file descriptor to close. If {_\bv_\ba_\br_\bn_\ba_\bm_\be} is supplied, the redirect- | |
2198 | ion persists beyond the scope of the command, allowing the shell pro- | |
2199 | grammer to manage the file descriptor's lifetime manually. The | |
2200 | v\bva\bar\brr\bre\bed\bdi\bir\br_\b_c\bcl\blo\bos\bse\be shell option manages this behavior. | |
d233b485 | 2201 | |
8868edaf CR |
2202 | In the following descriptions, if the file descriptor number is omit- |
2203 | ted, and the first character of the redirection operator is <\b<, the re- | |
2204 | direction refers to the standard input (file descriptor 0). If the | |
2205 | first character of the redirection operator is >\b>, the redirection | |
17345e5a JA |
2206 | refers to the standard output (file descriptor 1). |
2207 | ||
8868edaf CR |
2208 | The word following the redirection operator in the following descrip- |
2209 | tions, unless otherwise noted, is subjected to brace expansion, tilde | |
2210 | expansion, parameter and variable expansion, command substitution, | |
2211 | arithmetic expansion, quote removal, pathname expansion, and word | |
ac50fbac | 2212 | splitting. If it expands to more than one word, b\bba\bas\bsh\bh reports an error. |
17345e5a | 2213 | |
8868edaf | 2214 | Note that the order of redirections is significant. For example, the |
17345e5a JA |
2215 | command |
2216 | ||
2217 | ls >\b> dirlist 2>\b>&\b&1 | |
2218 | ||
8868edaf | 2219 | directs both standard output and standard error to the file _\bd_\bi_\br_\bl_\bi_\bs_\bt, |
17345e5a JA |
2220 | while the command |
2221 | ||
2222 | ls 2>\b>&\b&1 >\b> dirlist | |
2223 | ||
8868edaf CR |
2224 | directs only the standard output to file _\bd_\bi_\br_\bl_\bi_\bs_\bt, because the standard |
2225 | error was duplicated from the standard output before the standard out- | |
0001803f | 2226 | put was redirected to _\bd_\bi_\br_\bl_\bi_\bs_\bt. |
17345e5a JA |
2227 | |
2228 | B\bBa\bas\bsh\bh handles several filenames specially when they are used in redirec- | |
a0c0a00f CR |
2229 | tions, as described in the following table. If the operating system on |
2230 | which b\bba\bas\bsh\bh is running provides these special files, bash will use them; | |
8868edaf | 2231 | otherwise it will emulate them internally with the behavior described |
a0c0a00f | 2232 | below. |
17345e5a JA |
2233 | |
2234 | /\b/d\bde\bev\bv/\b/f\bfd\bd/\b/_\bf_\bd | |
8868edaf | 2235 | If _\bf_\bd is a valid integer, file descriptor _\bf_\bd is dupli- |
17345e5a JA |
2236 | cated. |
2237 | /\b/d\bde\bev\bv/\b/s\bst\btd\bdi\bin\bn | |
2238 | File descriptor 0 is duplicated. | |
2239 | /\b/d\bde\bev\bv/\b/s\bst\btd\bdo\bou\but\bt | |
2240 | File descriptor 1 is duplicated. | |
2241 | /\b/d\bde\bev\bv/\b/s\bst\btd\bde\ber\brr\br | |
2242 | File descriptor 2 is duplicated. | |
2243 | /\b/d\bde\bev\bv/\b/t\btc\bcp\bp/\b/_\bh_\bo_\bs_\bt/\b/_\bp_\bo_\br_\bt | |
2244 | If _\bh_\bo_\bs_\bt is a valid hostname or Internet address, and _\bp_\bo_\br_\bt | |
8868edaf | 2245 | is an integer port number or service name, b\bba\bas\bsh\bh attempts |
ac50fbac | 2246 | to open the corresponding TCP socket. |
17345e5a JA |
2247 | /\b/d\bde\bev\bv/\b/u\bud\bdp\bp/\b/_\bh_\bo_\bs_\bt/\b/_\bp_\bo_\br_\bt |
2248 | If _\bh_\bo_\bs_\bt is a valid hostname or Internet address, and _\bp_\bo_\br_\bt | |
8868edaf | 2249 | is an integer port number or service name, b\bba\bas\bsh\bh attempts |
ac50fbac | 2250 | to open the corresponding UDP socket. |
17345e5a JA |
2251 | |
2252 | A failure to open or create a file causes the redirection to fail. | |
2253 | ||
8868edaf CR |
2254 | Redirections using file descriptors greater than 9 should be used with |
2255 | care, as they may conflict with file descriptors the shell uses inter- | |
17345e5a JA |
2256 | nally. |
2257 | ||
2258 | R\bRe\bed\bdi\bir\bre\bec\bct\bti\bin\bng\bg I\bIn\bnp\bpu\but\bt | |
2259 | Redirection of input causes the file whose name results from the expan- | |
8868edaf | 2260 | sion of _\bw_\bo_\br_\bd to be opened for reading on file descriptor _\bn, or the |
17345e5a JA |
2261 | standard input (file descriptor 0) if _\bn is not specified. |
2262 | ||
2263 | The general format for redirecting input is: | |
2264 | ||
2265 | [_\bn]<\b<_\bw_\bo_\br_\bd | |
2266 | ||
2267 | R\bRe\bed\bdi\bir\bre\bec\bct\bti\bin\bng\bg O\bOu\but\btp\bpu\but\bt | |
8868edaf CR |
2268 | Redirection of output causes the file whose name results from the ex- |
2269 | pansion of _\bw_\bo_\br_\bd to be opened for writing on file descriptor _\bn, or the | |
17345e5a | 2270 | standard output (file descriptor 1) if _\bn is not specified. If the file |
8868edaf | 2271 | does not exist it is created; if it does exist it is truncated to zero |
17345e5a JA |
2272 | size. |
2273 | ||
2274 | The general format for redirecting output is: | |
2275 | ||
2276 | [_\bn]>\b>_\bw_\bo_\br_\bd | |
2277 | ||
8868edaf CR |
2278 | If the redirection operator is >\b>, and the n\bno\boc\bcl\blo\bob\bbb\bbe\ber\br option to the s\bse\bet\bt |
2279 | builtin has been enabled, the redirection will fail if the file whose | |
2280 | name results from the expansion of _\bw_\bo_\br_\bd exists and is a regular file. | |
17345e5a JA |
2281 | If the redirection operator is >\b>|\b|, or the redirection operator is >\b> and |
2282 | the n\bno\boc\bcl\blo\bob\bbb\bbe\ber\br option to the s\bse\bet\bt builtin command is not enabled, the re- | |
2283 | direction is attempted even if the file named by _\bw_\bo_\br_\bd exists. | |
2284 | ||
2285 | A\bAp\bpp\bpe\ben\bnd\bdi\bin\bng\bg R\bRe\bed\bdi\bir\bre\bec\bct\bte\bed\bd O\bOu\but\btp\bpu\but\bt | |
8868edaf CR |
2286 | Redirection of output in this fashion causes the file whose name re- |
2287 | sults from the expansion of _\bw_\bo_\br_\bd to be opened for appending on file de- | |
2288 | scriptor _\bn, or the standard output (file descriptor 1) if _\bn is not | |
17345e5a JA |
2289 | specified. If the file does not exist it is created. |
2290 | ||
2291 | The general format for appending output is: | |
2292 | ||
2293 | [_\bn]>\b>>\b>_\bw_\bo_\br_\bd | |
2294 | ||
17345e5a | 2295 | R\bRe\bed\bdi\bir\bre\bec\bct\bti\bin\bng\bg S\bSt\bta\ban\bnd\bda\bar\brd\bd O\bOu\but\btp\bpu\but\bt a\ban\bnd\bd S\bSt\bta\ban\bnd\bda\bar\brd\bd E\bEr\brr\bro\bor\br |
8868edaf CR |
2296 | This construct allows both the standard output (file descriptor 1) and |
2297 | the standard error output (file descriptor 2) to be redirected to the | |
17345e5a JA |
2298 | file whose name is the expansion of _\bw_\bo_\br_\bd. |
2299 | ||
8868edaf CR |
2300 | There are two formats for redirecting standard output and standard er- |
2301 | ror: | |
17345e5a JA |
2302 | |
2303 | &\b&>\b>_\bw_\bo_\br_\bd | |
2304 | and | |
2305 | >\b>&\b&_\bw_\bo_\br_\bd | |
2306 | ||
2307 | Of the two forms, the first is preferred. This is semantically equiva- | |
2308 | lent to | |
2309 | ||
2310 | >\b>_\bw_\bo_\br_\bd 2>\b>&\b&1 | |
2311 | ||
8868edaf CR |
2312 | When using the second form, _\bw_\bo_\br_\bd may not expand to a number or -\b-. If |
2313 | it does, other redirection operators apply (see D\bDu\bup\bpl\bli\bic\bca\bat\bti\bin\bng\bg F\bFi\bil\ble\be D\bDe\be-\b- | |
2314 | s\bsc\bcr\bri\bip\bpt\bto\bor\brs\bs below) for compatibility reasons. | |
17345e5a JA |
2315 | |
2316 | A\bAp\bpp\bpe\ben\bnd\bdi\bin\bng\bg S\bSt\bta\ban\bnd\bda\bar\brd\bd O\bOu\but\btp\bpu\but\bt a\ban\bnd\bd S\bSt\bta\ban\bnd\bda\bar\brd\bd E\bEr\brr\bro\bor\br | |
8868edaf CR |
2317 | This construct allows both the standard output (file descriptor 1) and |
2318 | the standard error output (file descriptor 2) to be appended to the | |
17345e5a JA |
2319 | file whose name is the expansion of _\bw_\bo_\br_\bd. |
2320 | ||
2321 | The format for appending standard output and standard error is: | |
2322 | ||
2323 | &\b&>\b>>\b>_\bw_\bo_\br_\bd | |
2324 | ||
2325 | This is semantically equivalent to | |
2326 | ||
2327 | >\b>>\b>_\bw_\bo_\br_\bd 2>\b>&\b&1 | |
2328 | ||
ac50fbac CR |
2329 | (see D\bDu\bup\bpl\bli\bic\bca\bat\bti\bin\bng\bg F\bFi\bil\ble\be D\bDe\bes\bsc\bcr\bri\bip\bpt\bto\bor\brs\bs below). |
2330 | ||
17345e5a | 2331 | H\bHe\ber\bre\be D\bDo\boc\bcu\bum\bme\ben\bnt\bts\bs |
8868edaf | 2332 | This type of redirection instructs the shell to read input from the |
17345e5a | 2333 | current source until a line containing only _\bd_\be_\bl_\bi_\bm_\bi_\bt_\be_\br (with no trailing |
8868edaf CR |
2334 | blanks) is seen. All of the lines read up to that point are then used |
2335 | as the standard input (or file descriptor _\bn if _\bn is specified) for a | |
a0c0a00f | 2336 | command. |
17345e5a JA |
2337 | |
2338 | The format of here-documents is: | |
2339 | ||
a0c0a00f | 2340 | [_\bn]<\b<<\b<[-\b-]_\bw_\bo_\br_\bd |
17345e5a JA |
2341 | _\bh_\be_\br_\be_\b-_\bd_\bo_\bc_\bu_\bm_\be_\bn_\bt |
2342 | _\bd_\be_\bl_\bi_\bm_\bi_\bt_\be_\br | |
2343 | ||
8868edaf CR |
2344 | No parameter and variable expansion, command substitution, arithmetic |
2345 | expansion, or pathname expansion is performed on _\bw_\bo_\br_\bd. If any part of | |
2346 | _\bw_\bo_\br_\bd is quoted, the _\bd_\be_\bl_\bi_\bm_\bi_\bt_\be_\br is the result of quote removal on _\bw_\bo_\br_\bd, | |
2347 | and the lines in the here-document are not expanded. If _\bw_\bo_\br_\bd is un- | |
2348 | quoted, all lines of the here-document are subjected to parameter ex- | |
2349 | pansion, command substitution, and arithmetic expansion, the character | |
2350 | sequence \\b\<\b<n\bne\bew\bwl\bli\bin\bne\be>\b> is ignored, and \\b\ must be used to quote the charac- | |
2351 | ters \\b\, $\b$, and `\b`. | |
17345e5a JA |
2352 | |
2353 | If the redirection operator is <\b<<\b<-\b-, then all leading tab characters are | |
8868edaf CR |
2354 | stripped from input lines and the line containing _\bd_\be_\bl_\bi_\bm_\bi_\bt_\be_\br. This al- |
2355 | lows here-documents within shell scripts to be indented in a natural | |
17345e5a JA |
2356 | fashion. |
2357 | ||
2358 | H\bHe\ber\bre\be S\bSt\btr\bri\bin\bng\bgs\bs | |
2359 | A variant of here documents, the format is: | |
2360 | ||
a0c0a00f | 2361 | [_\bn]<\b<<\b<<\b<_\bw_\bo_\br_\bd |
17345e5a | 2362 | |
8868edaf CR |
2363 | The _\bw_\bo_\br_\bd undergoes tilde expansion, parameter and variable expansion, |
2364 | command substitution, arithmetic expansion, and quote removal. Path- | |
2365 | name expansion and word splitting are not performed. The result is | |
d233b485 CR |
2366 | supplied as a single string, with a newline appended, to the command on |
2367 | its standard input (or file descriptor _\bn if _\bn is specified). | |
17345e5a JA |
2368 | |
2369 | D\bDu\bup\bpl\bli\bic\bca\bat\bti\bin\bng\bg F\bFi\bil\ble\be D\bDe\bes\bsc\bcr\bri\bip\bpt\bto\bor\brs\bs | |
2370 | The redirection operator | |
2371 | ||
2372 | [_\bn]<\b<&\b&_\bw_\bo_\br_\bd | |
2373 | ||
2374 | is used to duplicate input file descriptors. If _\bw_\bo_\br_\bd expands to one or | |
8868edaf CR |
2375 | more digits, the file descriptor denoted by _\bn is made to be a copy of |
2376 | that file descriptor. If the digits in _\bw_\bo_\br_\bd do not specify a file de- | |
2377 | scriptor open for input, a redirection error occurs. If _\bw_\bo_\br_\bd evaluates | |
2378 | to -\b-, file descriptor _\bn is closed. If _\bn is not specified, the standard | |
2379 | input (file descriptor 0) is used. | |
17345e5a JA |
2380 | |
2381 | The operator | |
2382 | ||
2383 | [_\bn]>\b>&\b&_\bw_\bo_\br_\bd | |
2384 | ||
8868edaf CR |
2385 | is used similarly to duplicate output file descriptors. If _\bn is not |
2386 | specified, the standard output (file descriptor 1) is used. If the | |
2387 | digits in _\bw_\bo_\br_\bd do not specify a file descriptor open for output, a re- | |
2388 | direction error occurs. If _\bw_\bo_\br_\bd evaluates to -\b-, file descriptor _\bn is | |
2389 | closed. As a special case, if _\bn is omitted, and _\bw_\bo_\br_\bd does not expand | |
2390 | to one or more digits or -\b-, the standard output and standard error are | |
ac50fbac | 2391 | redirected as described previously. |
17345e5a JA |
2392 | |
2393 | M\bMo\bov\bvi\bin\bng\bg F\bFi\bil\ble\be D\bDe\bes\bsc\bcr\bri\bip\bpt\bto\bor\brs\bs | |
2394 | The redirection operator | |
2395 | ||
2396 | [_\bn]<\b<&\b&_\bd_\bi_\bg_\bi_\bt-\b- | |
2397 | ||
8868edaf | 2398 | moves the file descriptor _\bd_\bi_\bg_\bi_\bt to file descriptor _\bn, or the standard |
17345e5a JA |
2399 | input (file descriptor 0) if _\bn is not specified. _\bd_\bi_\bg_\bi_\bt is closed after |
2400 | being duplicated to _\bn. | |
2401 | ||
2402 | Similarly, the redirection operator | |
2403 | ||
2404 | [_\bn]>\b>&\b&_\bd_\bi_\bg_\bi_\bt-\b- | |
2405 | ||
8868edaf | 2406 | moves the file descriptor _\bd_\bi_\bg_\bi_\bt to file descriptor _\bn, or the standard |
17345e5a JA |
2407 | output (file descriptor 1) if _\bn is not specified. |
2408 | ||
2409 | O\bOp\bpe\ben\bni\bin\bng\bg F\bFi\bil\ble\be D\bDe\bes\bsc\bcr\bri\bip\bpt\bto\bor\brs\bs f\bfo\bor\br R\bRe\bea\bad\bdi\bin\bng\bg a\ban\bnd\bd W\bWr\bri\bit\bti\bin\bng\bg | |
2410 | The redirection operator | |
2411 | ||
2412 | [_\bn]<\b<>\b>_\bw_\bo_\br_\bd | |
2413 | ||
8868edaf CR |
2414 | causes the file whose name is the expansion of _\bw_\bo_\br_\bd to be opened for |
2415 | both reading and writing on file descriptor _\bn, or on file descriptor 0 | |
17345e5a JA |
2416 | if _\bn is not specified. If the file does not exist, it is created. |
2417 | ||
2418 | A\bAL\bLI\bIA\bAS\bSE\bES\bS | |
8868edaf CR |
2419 | _\bA_\bl_\bi_\ba_\bs_\be_\bs allow a string to be substituted for a word when it is used as |
2420 | the first word of a simple command. The shell maintains a list of | |
2421 | aliases that may be set and unset with the a\bal\bli\bia\bas\bs and u\bun\bna\bal\bli\bia\bas\bs builtin | |
2422 | commands (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). The first word of each | |
2423 | simple command, if unquoted, is checked to see if it has an alias. If | |
2424 | so, that word is replaced by the text of the alias. The characters /\b/, | |
2425 | $\b$, `\b`, and =\b= and any of the shell _\bm_\be_\bt_\ba_\bc_\bh_\ba_\br_\ba_\bc_\bt_\be_\br_\bs or quoting characters | |
17345e5a | 2426 | listed above may not appear in an alias name. The replacement text may |
8868edaf CR |
2427 | contain any valid shell input, including shell metacharacters. The |
2428 | first word of the replacement text is tested for aliases, but a word | |
2429 | that is identical to an alias being expanded is not expanded a second | |
2430 | time. This means that one may alias l\bls\bs to l\bls\bs -\b-F\bF, for instance, and | |
2431 | b\bba\bas\bsh\bh does not try to recursively expand the replacement text. If the | |
2432 | last character of the alias value is a _\bb_\bl_\ba_\bn_\bk, then the next command | |
17345e5a JA |
2433 | word following the alias is also checked for alias expansion. |
2434 | ||
2435 | Aliases are created and listed with the a\bal\bli\bia\bas\bs command, and removed with | |
2436 | the u\bun\bna\bal\bli\bia\bas\bs command. | |
2437 | ||
8868edaf | 2438 | There is no mechanism for using arguments in the replacement text. If |
74091dd4 | 2439 | arguments are needed, use a shell function (see F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS below). |
17345e5a | 2440 | |
74091dd4 CR |
2441 | Aliases are not expanded when the shell is not interactive, unless the |
2442 | e\bex\bxp\bpa\ban\bnd\bd_\b_a\bal\bli\bia\bas\bse\bes\bs shell option is set using s\bsh\bho\bop\bpt\bt (see the description of | |
17345e5a JA |
2443 | s\bsh\bho\bop\bpt\bt under S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). |
2444 | ||
74091dd4 CR |
2445 | The rules concerning the definition and use of aliases are somewhat |
2446 | confusing. B\bBa\bas\bsh\bh always reads at least one complete line of input, and | |
2447 | all lines that make up a compound command, before executing any of the | |
2448 | commands on that line or the compound command. Aliases are expanded | |
2449 | when a command is read, not when it is executed. Therefore, an alias | |
2450 | definition appearing on the same line as another command does not take | |
2451 | effect until the next line of input is read. The commands following | |
2452 | the alias definition on that line are not affected by the new alias. | |
2453 | This behavior is also an issue when functions are executed. Aliases | |
2454 | are expanded when a function definition is read, not when the function | |
2455 | is executed, because a function definition is itself a command. As a | |
2456 | consequence, aliases defined in a function are not available until af- | |
2457 | ter that function is executed. To be safe, always put alias defini- | |
d233b485 | 2458 | tions on a separate line, and do not use a\bal\bli\bia\bas\bs in compound commands. |
17345e5a JA |
2459 | |
2460 | For almost every purpose, aliases are superseded by shell functions. | |
2461 | ||
2462 | F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS | |
74091dd4 CR |
2463 | A shell function, defined as described above under S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR, |
2464 | stores a series of commands for later execution. When the name of a | |
2465 | shell function is used as a simple command name, the list of commands | |
17345e5a | 2466 | associated with that function name is executed. Functions are executed |
74091dd4 CR |
2467 | in the context of the current shell; no new process is created to in- |
2468 | terpret them (contrast this with the execution of a shell script). | |
2469 | When a function is executed, the arguments to the function become the | |
17345e5a | 2470 | positional parameters during its execution. The special parameter #\b# is |
74091dd4 CR |
2471 | updated to reflect the change. Special parameter 0\b0 is unchanged. The |
2472 | first element of the F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE variable is set to the name of the func- | |
0001803f CR |
2473 | tion while the function is executing. |
2474 | ||
74091dd4 CR |
2475 | All other aspects of the shell execution environment are identical be- |
2476 | tween a function and its caller with these exceptions: the D\bDE\bEB\bBU\bUG\bG and | |
2477 | R\bRE\bET\bTU\bUR\bRN\bN traps (see the description of the t\btr\bra\bap\bp builtin under S\bSH\bHE\bEL\bLL\bL | |
2478 | B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below) are not inherited unless the function has been | |
2479 | given the t\btr\bra\bac\bce\be attribute (see the description of the d\bde\bec\bcl\bla\bar\bre\be builtin | |
2480 | below) or the -\b-o\bo f\bfu\bun\bnc\bct\btr\bra\bac\bce\be shell option has been enabled with the s\bse\bet\bt | |
2481 | builtin (in which case all functions inherit the D\bDE\bEB\bBU\bUG\bG and R\bRE\bET\bTU\bUR\bRN\bN | |
2482 | traps), and the E\bER\bRR\bR trap is not inherited unless the -\b-o\bo e\ber\brr\brt\btr\bra\bac\bce\be shell | |
0001803f | 2483 | option has been enabled. |
17345e5a | 2484 | |
74091dd4 CR |
2485 | Variables local to the function may be declared with the l\blo\boc\bca\bal\bl builtin |
2486 | command (_\bl_\bo_\bc_\ba_\bl _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be_\bs). Ordinarily, variables and their values are | |
2487 | shared between the function and its caller. If a variable is declared | |
2488 | l\blo\boc\bca\bal\bl, the variable's visible scope is restricted to that function and | |
2489 | its children (including the functions it calls). | |
2490 | ||
2491 | In the following description, the _\bc_\bu_\br_\br_\be_\bn_\bt _\bs_\bc_\bo_\bp_\be is a currently- execut- | |
2492 | ing function. Previous scopes consist of that function's caller and so | |
2493 | on, back to the "global" scope, where the shell is not executing any | |
2494 | shell function. Consequently, a local variable at the current scope is | |
2495 | a variable declared using the l\blo\boc\bca\bal\bl or d\bde\bec\bcl\bla\bar\bre\be builtins in the function | |
2496 | that is currently executing. | |
2497 | ||
2498 | Local variables "shadow" variables with the same name declared at pre- | |
2499 | vious scopes. For instance, a local variable declared in a function | |
2500 | hides a global variable of the same name: references and assignments | |
2501 | refer to the local variable, leaving the global variable unmodified. | |
2502 | When the function returns, the global variable is once again visible. | |
2503 | ||
2504 | The shell uses _\bd_\by_\bn_\ba_\bm_\bi_\bc _\bs_\bc_\bo_\bp_\bi_\bn_\bg to control a variable's visibility | |
2505 | within functions. With dynamic scoping, visible variables and their | |
2506 | values are a result of the sequence of function calls that caused exe- | |
2507 | cution to reach the current function. The value of a variable that a | |
2508 | function sees depends on its value within its caller, if any, whether | |
2509 | that caller is the "global" scope or another shell function. This is | |
2510 | also the value that a local variable declaration "shadows", and the | |
d233b485 CR |
2511 | value that is restored when the function returns. |
2512 | ||
74091dd4 CR |
2513 | For example, if a variable _\bv_\ba_\br is declared as local in function _\bf_\bu_\bn_\bc_\b1, |
2514 | and _\bf_\bu_\bn_\bc_\b1 calls another function _\bf_\bu_\bn_\bc_\b2, references to _\bv_\ba_\br made from | |
d233b485 CR |
2515 | within _\bf_\bu_\bn_\bc_\b2 will resolve to the local variable _\bv_\ba_\br from _\bf_\bu_\bn_\bc_\b1, shadow- |
2516 | ing any global variable named _\bv_\ba_\br. | |
2517 | ||
2518 | The u\bun\bns\bse\bet\bt builtin also acts using the same dynamic scope: if a variable | |
2519 | is local to the current scope, u\bun\bns\bse\bet\bt will unset it; otherwise the unset | |
74091dd4 CR |
2520 | will refer to the variable found in any calling scope as described |
2521 | above. If a variable at the current local scope is unset, it will re- | |
2522 | main so (appearing as unset) until it is reset in that scope or until | |
2523 | the function returns. Once the function returns, any instance of the | |
2524 | variable at a previous scope will become visible. If the unset acts on | |
2525 | a variable at a previous scope, any instance of a variable with that | |
2526 | name that had been shadowed will become visible (see below how the l\blo\bo-\b- | |
2527 | c\bca\bal\blv\bva\bar\br_\b_u\bun\bns\bse\bet\bt shell option changes this behavior). | |
8868edaf CR |
2528 | |
2529 | The F\bFU\bUN\bNC\bCN\bNE\bES\bST\bT variable, if set to a numeric value greater than 0, de- | |
2530 | fines a maximum function nesting level. Function invocations that ex- | |
2531 | ceed the limit cause the entire command to abort. | |
2532 | ||
2533 | If the builtin command r\bre\bet\btu\bur\brn\bn is executed in a function, the function | |
2534 | completes and execution resumes with the next command after the func- | |
2535 | tion call. Any command associated with the R\bRE\bET\bTU\bUR\bRN\bN trap is executed be- | |
2536 | fore execution resumes. When a function completes, the values of the | |
2537 | positional parameters and the special parameter #\b# are restored to the | |
17345e5a JA |
2538 | values they had prior to the function's execution. |
2539 | ||
8868edaf | 2540 | Function names and definitions may be listed with the -\b-f\bf option to the |
17345e5a | 2541 | d\bde\bec\bcl\bla\bar\bre\be or t\bty\byp\bpe\bes\bse\bet\bt builtin commands. The -\b-F\bF option to d\bde\bec\bcl\bla\bar\bre\be or t\bty\byp\bpe\be-\b- |
8868edaf CR |
2542 | s\bse\bet\bt will list the function names only (and optionally the source file |
2543 | and line number, if the e\bex\bxt\btd\bde\beb\bbu\bug\bg shell option is enabled). Functions | |
74091dd4 CR |
2544 | may be exported so that child shell processes (those created when exe- |
2545 | cuting a separate shell invocation) automatically have them defined | |
2546 | with the -\b-f\bf option to the e\bex\bxp\bpo\bor\brt\bt builtin. A function definition may be | |
d233b485 | 2547 | deleted using the -\b-f\bf option to the u\bun\bns\bse\bet\bt builtin. |
17345e5a | 2548 | |
495aee44 | 2549 | Functions may be recursive. The F\bFU\bUN\bNC\bCN\bNE\bES\bST\bT variable may be used to limit |
74091dd4 | 2550 | the depth of the function call stack and restrict the number of func- |
8868edaf CR |
2551 | tion invocations. By default, no limit is imposed on the number of re- |
2552 | cursive calls. | |
17345e5a JA |
2553 | |
2554 | A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN | |
74091dd4 CR |
2555 | The shell allows arithmetic expressions to be evaluated, under certain |
2556 | circumstances (see the l\ble\bet\bt and d\bde\bec\bcl\bla\bar\bre\be builtin commands, the (\b((\b( com- | |
a0c0a00f | 2557 | pound command, and A\bAr\bri\bit\bth\bhm\bme\bet\bti\bic\bc E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn). Evaluation is done in fixed- |
74091dd4 CR |
2558 | width integers with no check for overflow, though division by 0 is |
2559 | trapped and flagged as an error. The operators and their precedence, | |
2560 | associativity, and values are the same as in the C language. The fol- | |
8868edaf CR |
2561 | lowing list of operators is grouped into levels of equal-precedence op- |
2562 | erators. The levels are listed in order of decreasing precedence. | |
17345e5a JA |
2563 | |
2564 | _\bi_\bd+\b++\b+ _\bi_\bd-\b--\b- | |
2565 | variable post-increment and post-decrement | |
d233b485 | 2566 | -\b- +\b+ unary minus and plus |
17345e5a JA |
2567 | +\b++\b+_\bi_\bd -\b--\b-_\bi_\bd |
2568 | variable pre-increment and pre-decrement | |
17345e5a JA |
2569 | !\b! ~\b~ logical and bitwise negation |
2570 | *\b**\b* exponentiation | |
2571 | *\b* /\b/ %\b% multiplication, division, remainder | |
2572 | +\b+ -\b- addition, subtraction | |
2573 | <\b<<\b< >\b>>\b> left and right bitwise shifts | |
2574 | <\b<=\b= >\b>=\b= <\b< >\b> | |
2575 | comparison | |
2576 | =\b==\b= !\b!=\b= equality and inequality | |
2577 | &\b& bitwise AND | |
2578 | ^\b^ bitwise exclusive OR | |
2579 | |\b| bitwise OR | |
2580 | &\b&&\b& logical AND | |
2581 | |\b||\b| logical OR | |
2582 | _\be_\bx_\bp_\br?\b?_\be_\bx_\bp_\br:\b:_\be_\bx_\bp_\br | |
2583 | conditional operator | |
2584 | =\b= *\b*=\b= /\b/=\b= %\b%=\b= +\b+=\b= -\b-=\b= <\b<<\b<=\b= >\b>>\b>=\b= &\b&=\b= ^\b^=\b= |\b|=\b= | |
2585 | assignment | |
2586 | _\be_\bx_\bp_\br_\b1 ,\b, _\be_\bx_\bp_\br_\b2 | |
2587 | comma | |
2588 | ||
74091dd4 | 2589 | Shell variables are allowed as operands; parameter expansion is per- |
17345e5a | 2590 | formed before the expression is evaluated. Within an expression, shell |
74091dd4 CR |
2591 | variables may also be referenced by name without using the parameter |
2592 | expansion syntax. A shell variable that is null or unset evaluates to | |
17345e5a | 2593 | 0 when referenced by name without using the parameter expansion syntax. |
74091dd4 CR |
2594 | The value of a variable is evaluated as an arithmetic expression when |
2595 | it is referenced, or when a variable which has been given the _\bi_\bn_\bt_\be_\bg_\be_\br | |
17345e5a | 2596 | attribute using d\bde\bec\bcl\bla\bar\bre\be -\b-i\bi is assigned a value. A null value evaluates |
74091dd4 | 2597 | to 0. A shell variable need not have its _\bi_\bn_\bt_\be_\bg_\be_\br attribute turned on |
17345e5a JA |
2598 | to be used in an expression. |
2599 | ||
8868edaf CR |
2600 | Integer constants follow the C language definition, without suffixes or |
2601 | character constants. Constants with a leading 0 are interpreted as oc- | |
74091dd4 CR |
2602 | tal numbers. A leading 0x or 0X denotes hexadecimal. Otherwise, num- |
2603 | bers take the form [_\bb_\ba_\bs_\be_\b#]n, where the optional _\bb_\ba_\bs_\be is a decimal num- | |
2604 | ber between 2 and 64 representing the arithmetic base, and _\bn is a num- | |
2605 | ber in that base. If _\bb_\ba_\bs_\be_\b# is omitted, then base 10 is used. When | |
8868edaf | 2606 | specifying _\bn, if a non-digit is required, the digits greater than 9 are |
74091dd4 CR |
2607 | represented by the lowercase letters, the uppercase letters, @, and _, |
2608 | in that order. If _\bb_\ba_\bs_\be is less than or equal to 36, lowercase and up- | |
2609 | percase letters may be used interchangeably to represent numbers be- | |
8868edaf CR |
2610 | tween 10 and 35. |
2611 | ||
74091dd4 CR |
2612 | Operators are evaluated in order of precedence. Sub-expressions in |
2613 | parentheses are evaluated first and may override the precedence rules | |
17345e5a JA |
2614 | above. |
2615 | ||
2616 | C\bCO\bON\bND\bDI\bIT\bTI\bIO\bON\bNA\bAL\bL E\bEX\bXP\bPR\bRE\bES\bSS\bSI\bIO\bON\bNS\bS | |
74091dd4 CR |
2617 | Conditional expressions are used by the [\b[[\b[ compound command and the |
2618 | t\bte\bes\bst\bt and [\b[ builtin commands to test file attributes and perform string | |
2619 | and arithmetic comparisons. The t\bte\bes\bst\bt and [\b[ commands determine their | |
2620 | behavior based on the number of arguments; see the descriptions of | |
d233b485 CR |
2621 | those commands for any other command-specific actions. |
2622 | ||
74091dd4 CR |
2623 | Expressions are formed from the following unary or binary primaries. |
2624 | B\bBa\bas\bsh\bh handles several filenames specially when they are used in expres- | |
d233b485 | 2625 | sions. If the operating system on which b\bba\bas\bsh\bh is running provides these |
74091dd4 CR |
2626 | special files, bash will use them; otherwise it will emulate them in- |
2627 | ternally with this behavior: If any _\bf_\bi_\bl_\be argument to one of the pri- | |
d233b485 | 2628 | maries is of the form _\b/_\bd_\be_\bv_\b/_\bf_\bd_\b/_\bn, then file descriptor _\bn is checked. If |
74091dd4 CR |
2629 | the _\bf_\bi_\bl_\be argument to one of the primaries is one of _\b/_\bd_\be_\bv_\b/_\bs_\bt_\bd_\bi_\bn, |
2630 | _\b/_\bd_\be_\bv_\b/_\bs_\bt_\bd_\bo_\bu_\bt, or _\b/_\bd_\be_\bv_\b/_\bs_\bt_\bd_\be_\br_\br, file descriptor 0, 1, or 2, respectively, | |
d233b485 | 2631 | is checked. |
17345e5a JA |
2632 | |
2633 | Unless otherwise specified, primaries that operate on files follow sym- | |
2634 | bolic links and operate on the target of the link, rather than the link | |
2635 | itself. | |
2636 | ||
74091dd4 | 2637 | When used with [\b[[\b[, the <\b< and >\b> operators sort lexicographically using |
495aee44 | 2638 | the current locale. The t\bte\bes\bst\bt command sorts using ASCII ordering. |
0001803f | 2639 | |
17345e5a JA |
2640 | -\b-a\ba _\bf_\bi_\bl_\be |
2641 | True if _\bf_\bi_\bl_\be exists. | |
2642 | -\b-b\bb _\bf_\bi_\bl_\be | |
2643 | True if _\bf_\bi_\bl_\be exists and is a block special file. | |
2644 | -\b-c\bc _\bf_\bi_\bl_\be | |
2645 | True if _\bf_\bi_\bl_\be exists and is a character special file. | |
2646 | -\b-d\bd _\bf_\bi_\bl_\be | |
2647 | True if _\bf_\bi_\bl_\be exists and is a directory. | |
2648 | -\b-e\be _\bf_\bi_\bl_\be | |
2649 | True if _\bf_\bi_\bl_\be exists. | |
2650 | -\b-f\bf _\bf_\bi_\bl_\be | |
2651 | True if _\bf_\bi_\bl_\be exists and is a regular file. | |
2652 | -\b-g\bg _\bf_\bi_\bl_\be | |
2653 | True if _\bf_\bi_\bl_\be exists and is set-group-id. | |
2654 | -\b-h\bh _\bf_\bi_\bl_\be | |
2655 | True if _\bf_\bi_\bl_\be exists and is a symbolic link. | |
2656 | -\b-k\bk _\bf_\bi_\bl_\be | |
2657 | True if _\bf_\bi_\bl_\be exists and its ``sticky'' bit is set. | |
2658 | -\b-p\bp _\bf_\bi_\bl_\be | |
2659 | True if _\bf_\bi_\bl_\be exists and is a named pipe (FIFO). | |
2660 | -\b-r\br _\bf_\bi_\bl_\be | |
2661 | True if _\bf_\bi_\bl_\be exists and is readable. | |
2662 | -\b-s\bs _\bf_\bi_\bl_\be | |
2663 | True if _\bf_\bi_\bl_\be exists and has a size greater than zero. | |
2664 | -\b-t\bt _\bf_\bd True if file descriptor _\bf_\bd is open and refers to a terminal. | |
2665 | -\b-u\bu _\bf_\bi_\bl_\be | |
2666 | True if _\bf_\bi_\bl_\be exists and its set-user-id bit is set. | |
2667 | -\b-w\bw _\bf_\bi_\bl_\be | |
2668 | True if _\bf_\bi_\bl_\be exists and is writable. | |
2669 | -\b-x\bx _\bf_\bi_\bl_\be | |
2670 | True if _\bf_\bi_\bl_\be exists and is executable. | |
17345e5a JA |
2671 | -\b-G\bG _\bf_\bi_\bl_\be |
2672 | True if _\bf_\bi_\bl_\be exists and is owned by the effective group id. | |
2673 | -\b-L\bL _\bf_\bi_\bl_\be | |
2674 | True if _\bf_\bi_\bl_\be exists and is a symbolic link. | |
17345e5a | 2675 | -\b-N\bN _\bf_\bi_\bl_\be |
74091dd4 | 2676 | True if _\bf_\bi_\bl_\be exists and has been modified since it was last |
17345e5a | 2677 | read. |
495aee44 CR |
2678 | -\b-O\bO _\bf_\bi_\bl_\be |
2679 | True if _\bf_\bi_\bl_\be exists and is owned by the effective user id. | |
2680 | -\b-S\bS _\bf_\bi_\bl_\be | |
2681 | True if _\bf_\bi_\bl_\be exists and is a socket. | |
2682 | _\bf_\bi_\bl_\be_\b1 -\b-e\bef\bf _\bf_\bi_\bl_\be_\b2 | |
74091dd4 | 2683 | True if _\bf_\bi_\bl_\be_\b1 and _\bf_\bi_\bl_\be_\b2 refer to the same device and inode num- |
495aee44 | 2684 | bers. |
17345e5a | 2685 | _\bf_\bi_\bl_\be_\b1 -n\bnt\bt _\bf_\bi_\bl_\be_\b2 |
74091dd4 | 2686 | True if _\bf_\bi_\bl_\be_\b1 is newer (according to modification date) than |
17345e5a JA |
2687 | _\bf_\bi_\bl_\be_\b2, or if _\bf_\bi_\bl_\be_\b1 exists and _\bf_\bi_\bl_\be_\b2 does not. |
2688 | _\bf_\bi_\bl_\be_\b1 -o\bot\bt _\bf_\bi_\bl_\be_\b2 | |
74091dd4 | 2689 | True if _\bf_\bi_\bl_\be_\b1 is older than _\bf_\bi_\bl_\be_\b2, or if _\bf_\bi_\bl_\be_\b2 exists and _\bf_\bi_\bl_\be_\b1 |
17345e5a | 2690 | does not. |
17345e5a | 2691 | -\b-o\bo _\bo_\bp_\bt_\bn_\ba_\bm_\be |
74091dd4 CR |
2692 | True if the shell option _\bo_\bp_\bt_\bn_\ba_\bm_\be is enabled. See the list of |
2693 | options under the description of the -\b-o\bo option to the s\bse\bet\bt | |
17345e5a | 2694 | builtin below. |
495aee44 | 2695 | -\b-v\bv _\bv_\ba_\br_\bn_\ba_\bm_\be |
74091dd4 | 2696 | True if the shell variable _\bv_\ba_\br_\bn_\ba_\bm_\be is set (has been assigned a |
495aee44 | 2697 | value). |
ac50fbac | 2698 | -\b-R\bR _\bv_\ba_\br_\bn_\ba_\bm_\be |
74091dd4 | 2699 | True if the shell variable _\bv_\ba_\br_\bn_\ba_\bm_\be is set and is a name refer- |
ac50fbac | 2700 | ence. |
17345e5a JA |
2701 | -\b-z\bz _\bs_\bt_\br_\bi_\bn_\bg |
2702 | True if the length of _\bs_\bt_\br_\bi_\bn_\bg is zero. | |
2703 | _\bs_\bt_\br_\bi_\bn_\bg | |
2704 | -\b-n\bn _\bs_\bt_\br_\bi_\bn_\bg | |
2705 | True if the length of _\bs_\bt_\br_\bi_\bn_\bg is non-zero. | |
2706 | ||
2707 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 =\b==\b= _\bs_\bt_\br_\bi_\bn_\bg_\b2 | |
0001803f | 2708 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 =\b= _\bs_\bt_\br_\bi_\bn_\bg_\b2 |
74091dd4 CR |
2709 | True if the strings are equal. =\b= should be used with the t\bte\bes\bst\bt |
2710 | command for POSIX conformance. When used with the [\b[[\b[ command, | |
ac50fbac CR |
2711 | this performs pattern matching as described above (C\bCo\bom\bmp\bpo\bou\bun\bnd\bd C\bCo\bom\bm-\b- |
2712 | m\bma\ban\bnd\bds\bs). | |
17345e5a JA |
2713 | |
2714 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 !\b!=\b= _\bs_\bt_\br_\bi_\bn_\bg_\b2 | |
2715 | True if the strings are not equal. | |
2716 | ||
2717 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 <\b< _\bs_\bt_\br_\bi_\bn_\bg_\b2 | |
0001803f | 2718 | True if _\bs_\bt_\br_\bi_\bn_\bg_\b1 sorts before _\bs_\bt_\br_\bi_\bn_\bg_\b2 lexicographically. |
17345e5a JA |
2719 | |
2720 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 >\b> _\bs_\bt_\br_\bi_\bn_\bg_\b2 | |
0001803f | 2721 | True if _\bs_\bt_\br_\bi_\bn_\bg_\b1 sorts after _\bs_\bt_\br_\bi_\bn_\bg_\b2 lexicographically. |
17345e5a JA |
2722 | |
2723 | _\ba_\br_\bg_\b1 O\bOP\bP _\ba_\br_\bg_\b2 | |
74091dd4 CR |
2724 | O\bOP\bP is one of -\b-e\beq\bq, -\b-n\bne\be, -\b-l\blt\bt, -\b-l\ble\be, -\b-g\bgt\bt, or -\b-g\bge\be. These arithmetic |
2725 | binary operators return true if _\ba_\br_\bg_\b1 is equal to, not equal to, | |
2726 | less than, less than or equal to, greater than, or greater than | |
2727 | or equal to _\ba_\br_\bg_\b2, respectively. _\bA_\br_\bg_\b1 and _\ba_\br_\bg_\b2 may be positive | |
2728 | or negative integers. When used with the [\b[[\b[ command, _\bA_\br_\bg_\b1 and | |
2729 | _\bA_\br_\bg_\b2 are evaluated as arithmetic expressions (see A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC | |
d233b485 | 2730 | E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN above). |
17345e5a JA |
2731 | |
2732 | S\bSI\bIM\bMP\bPL\bLE\bE C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
8868edaf | 2733 | When a simple command is executed, the shell performs the following ex- |
74091dd4 | 2734 | pansions, assignments, and redirections, from left to right, in the |
8868edaf | 2735 | following order. |
17345e5a | 2736 | |
74091dd4 CR |
2737 | 1. The words that the parser has marked as variable assignments |
2738 | (those preceding the command name) and redirections are saved | |
17345e5a JA |
2739 | for later processing. |
2740 | ||
74091dd4 CR |
2741 | 2. The words that are not variable assignments or redirections are |
2742 | expanded. If any words remain after expansion, the first word | |
2743 | is taken to be the name of the command and the remaining words | |
17345e5a JA |
2744 | are the arguments. |
2745 | ||
2746 | 3. Redirections are performed as described above under R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN. | |
2747 | ||
2748 | 4. The text after the =\b= in each variable assignment undergoes tilde | |
2749 | expansion, parameter expansion, command substitution, arithmetic | |
74091dd4 | 2750 | expansion, and quote removal before being assigned to the vari- |
17345e5a JA |
2751 | able. |
2752 | ||
2753 | If no command name results, the variable assignments affect the current | |
74091dd4 CR |
2754 | shell environment. In the case of such a command (one that consists |
2755 | only of assignment statements and redirections), assignment statements | |
2756 | are performed before redirections. Otherwise, the variables are added | |
2757 | to the environment of the executed command and do not affect the cur- | |
2758 | rent shell environment. If any of the assignments attempts to assign a | |
2759 | value to a readonly variable, an error occurs, and the command exits | |
2760 | with a non-zero status. | |
2761 | ||
2762 | If no command name results, redirections are performed, but do not af- | |
2763 | fect the current shell environment. A redirection error causes the | |
17345e5a JA |
2764 | command to exit with a non-zero status. |
2765 | ||
74091dd4 CR |
2766 | If there is a command name left after expansion, execution proceeds as |
2767 | described below. Otherwise, the command exits. If one of the expan- | |
2768 | sions contained a command substitution, the exit status of the command | |
2769 | is the exit status of the last command substitution performed. If | |
17345e5a JA |
2770 | there were no command substitutions, the command exits with a status of |
2771 | zero. | |
2772 | ||
2773 | C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN | |
74091dd4 CR |
2774 | After a command has been split into words, if it results in a simple |
2775 | command and an optional list of arguments, the following actions are | |
17345e5a JA |
2776 | taken. |
2777 | ||
74091dd4 CR |
2778 | If the command name contains no slashes, the shell attempts to locate |
2779 | it. If there exists a shell function by that name, that function is | |
2780 | invoked as described above in F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS. If the name does not match a | |
2781 | function, the shell searches for it in the list of shell builtins. If | |
17345e5a JA |
2782 | a match is found, that builtin is invoked. |
2783 | ||
74091dd4 CR |
2784 | If the name is neither a shell function nor a builtin, and contains no |
2785 | slashes, b\bba\bas\bsh\bh searches each element of the P\bPA\bAT\bTH\bH for a directory con- | |
8868edaf | 2786 | taining an executable file by that name. B\bBa\bas\bsh\bh uses a hash table to re- |
74091dd4 CR |
2787 | member the full pathnames of executable files (see h\bha\bas\bsh\bh under S\bSH\bHE\bEL\bLL\bL |
2788 | B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). A full search of the directories in P\bPA\bAT\bTH\bH is | |
2789 | performed only if the command is not found in the hash table. If the | |
17345e5a JA |
2790 | search is unsuccessful, the shell searches for a defined shell function |
2791 | named c\bco\bom\bmm\bma\ban\bnd\bd_\b_n\bno\bot\bt_\b_f\bfo\bou\bun\bnd\bd_\b_h\bha\ban\bnd\bdl\ble\be. If that function exists, it is invoked | |
74091dd4 CR |
2792 | in a separate execution environment with the original command and the |
2793 | original command's arguments as its arguments, and the function's exit | |
2794 | status becomes the exit status of that subshell. If that function is | |
d233b485 CR |
2795 | not defined, the shell prints an error message and returns an exit sta- |
2796 | tus of 127. | |
17345e5a | 2797 | |
74091dd4 | 2798 | If the search is successful, or if the command name contains one or |
17345e5a JA |
2799 | more slashes, the shell executes the named program in a separate execu- |
2800 | tion environment. Argument 0 is set to the name given, and the remain- | |
2801 | ing arguments to the command are set to the arguments given, if any. | |
2802 | ||
74091dd4 CR |
2803 | If this execution fails because the file is not in executable format, |
2804 | and the file is not a directory, it is assumed to be a _\bs_\bh_\be_\bl_\bl _\bs_\bc_\br_\bi_\bp_\bt, a | |
2805 | file containing shell commands, and the shell creates a new instance of | |
2806 | itself to execute it. This subshell reinitializes itself, so that the | |
2807 | effect is as if a new shell had been invoked to handle the script, with | |
2808 | the exception that the locations of commands remembered by the parent | |
2809 | (see h\bha\bas\bsh\bh below under S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS) are retained by the | |
2810 | child. | |
17345e5a | 2811 | |
d233b485 CR |
2812 | If the program is a file beginning with #\b#!\b!, the remainder of the first |
2813 | line specifies an interpreter for the program. The shell executes the | |
17345e5a JA |
2814 | specified interpreter on operating systems that do not handle this exe- |
2815 | cutable format themselves. The arguments to the interpreter consist of | |
d233b485 CR |
2816 | a single optional argument following the interpreter name on the first |
2817 | line of the program, followed by the name of the program, followed by | |
17345e5a JA |
2818 | the command arguments, if any. |
2819 | ||
2820 | C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN E\bEN\bNV\bVI\bIR\bRO\bON\bNM\bME\bEN\bNT\bT | |
d233b485 | 2821 | The shell has an _\be_\bx_\be_\bc_\bu_\bt_\bi_\bo_\bn _\be_\bn_\bv_\bi_\br_\bo_\bn_\bm_\be_\bn_\bt, which consists of the follow- |
17345e5a JA |
2822 | ing: |
2823 | ||
d233b485 | 2824 | +\bo open files inherited by the shell at invocation, as modified by |
17345e5a JA |
2825 | redirections supplied to the e\bex\bxe\bec\bc builtin |
2826 | ||
d233b485 | 2827 | +\bo the current working directory as set by c\bcd\bd, p\bpu\bus\bsh\bhd\bd, or p\bpo\bop\bpd\bd, or |
17345e5a JA |
2828 | inherited by the shell at invocation |
2829 | ||
d233b485 | 2830 | +\bo the file creation mode mask as set by u\bum\bma\bas\bsk\bk or inherited from |
17345e5a JA |
2831 | the shell's parent |
2832 | ||
2833 | +\bo current traps set by t\btr\bra\bap\bp | |
2834 | ||
2835 | +\bo shell parameters that are set by variable assignment or with s\bse\bet\bt | |
2836 | or inherited from the shell's parent in the environment | |
2837 | ||
d233b485 | 2838 | +\bo shell functions defined during execution or inherited from the |
17345e5a JA |
2839 | shell's parent in the environment |
2840 | ||
d233b485 | 2841 | +\bo options enabled at invocation (either by default or with com- |
17345e5a JA |
2842 | mand-line arguments) or by s\bse\bet\bt |
2843 | ||
2844 | +\bo options enabled by s\bsh\bho\bop\bpt\bt | |
2845 | ||
2846 | +\bo shell aliases defined with a\bal\bli\bia\bas\bs | |
2847 | ||
d233b485 | 2848 | +\bo various process IDs, including those of background jobs, the |
0001803f | 2849 | value of $\b$$\b$, and the value of P\bPP\bPI\bID\bD |
17345e5a | 2850 | |
d233b485 CR |
2851 | When a simple command other than a builtin or shell function is to be |
2852 | executed, it is invoked in a separate execution environment that con- | |
2853 | sists of the following. Unless otherwise noted, the values are inher- | |
17345e5a JA |
2854 | ited from the shell. |
2855 | ||
2856 | ||
d233b485 | 2857 | +\bo the shell's open files, plus any modifications and additions |
17345e5a JA |
2858 | specified by redirections to the command |
2859 | ||
2860 | +\bo the current working directory | |
2861 | ||
2862 | +\bo the file creation mode mask | |
2863 | ||
d233b485 | 2864 | +\bo shell variables and functions marked for export, along with |
17345e5a JA |
2865 | variables exported for the command, passed in the environment |
2866 | ||
2867 | +\bo traps caught by the shell are reset to the values inherited from | |
2868 | the shell's parent, and traps ignored by the shell are ignored | |
2869 | ||
d233b485 | 2870 | A command invoked in this separate environment cannot affect the |
17345e5a JA |
2871 | shell's execution environment. |
2872 | ||
74091dd4 CR |
2873 | A _\bs_\bu_\bb_\bs_\bh_\be_\bl_\bl is a copy of the shell process. |
2874 | ||
d233b485 | 2875 | Command substitution, commands grouped with parentheses, and asynchro- |
17345e5a | 2876 | nous commands are invoked in a subshell environment that is a duplicate |
8868edaf CR |
2877 | of the shell environment, except that traps caught by the shell are re- |
2878 | set to the values that the shell inherited from its parent at invoca- | |
17345e5a JA |
2879 | tion. Builtin commands that are invoked as part of a pipeline are also |
2880 | executed in a subshell environment. Changes made to the subshell envi- | |
2881 | ronment cannot affect the shell's execution environment. | |
2882 | ||
2883 | Subshells spawned to execute command substitutions inherit the value of | |
d233b485 | 2884 | the -\b-e\be option from the parent shell. When not in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, b\bba\bas\bsh\bh |
17345e5a JA |
2885 | clears the -\b-e\be option in such subshells. |
2886 | ||
8868edaf CR |
2887 | If a command is followed by a &\b& and job control is not active, the de- |
2888 | fault standard input for the command is the empty file _\b/_\bd_\be_\bv_\b/_\bn_\bu_\bl_\bl. Oth- | |
2889 | erwise, the invoked command inherits the file descriptors of the call- | |
2890 | ing shell as modified by redirections. | |
17345e5a JA |
2891 | |
2892 | E\bEN\bNV\bVI\bIR\bRO\bON\bNM\bME\bEN\bNT\bT | |
d233b485 | 2893 | When a program is invoked it is given an array of strings called the |
17345e5a JA |
2894 | _\be_\bn_\bv_\bi_\br_\bo_\bn_\bm_\be_\bn_\bt. This is a list of _\bn_\ba_\bm_\be-_\bv_\ba_\bl_\bu_\be pairs, of the form |
2895 | _\bn_\ba_\bm_\be=_\bv_\ba_\bl_\bu_\be. | |
2896 | ||
8868edaf CR |
2897 | The shell provides several ways to manipulate the environment. On in- |
2898 | vocation, the shell scans its own environment and creates a parameter | |
d233b485 | 2899 | for each name found, automatically marking it for _\be_\bx_\bp_\bo_\br_\bt to child pro- |
8868edaf CR |
2900 | cesses. Executed commands inherit the environment. The e\bex\bxp\bpo\bor\brt\bt and d\bde\be-\b- |
2901 | c\bcl\bla\bar\bre\be -\b-x\bx commands allow parameters and functions to be added to and | |
17345e5a | 2902 | deleted from the environment. If the value of a parameter in the envi- |
8868edaf CR |
2903 | ronment is modified, the new value becomes part of the environment, re- |
2904 | placing the old. The environment inherited by any executed command | |
d233b485 CR |
2905 | consists of the shell's initial environment, whose values may be modi- |
2906 | fied in the shell, less any pairs removed by the u\bun\bns\bse\bet\bt command, plus | |
17345e5a JA |
2907 | any additions via the e\bex\bxp\bpo\bor\brt\bt and d\bde\bec\bcl\bla\bar\bre\be -\b-x\bx commands. |
2908 | ||
d233b485 CR |
2909 | The environment for any _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd or function may be augmented |
2910 | temporarily by prefixing it with parameter assignments, as described | |
17345e5a JA |
2911 | above in P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS. These assignment statements affect only the envi- |
2912 | ronment seen by that command. | |
2913 | ||
d233b485 CR |
2914 | If the -\b-k\bk option is set (see the s\bse\bet\bt builtin command below), then _\ba_\bl_\bl |
2915 | parameter assignments are placed in the environment for a command, not | |
17345e5a JA |
2916 | just those that precede the command name. |
2917 | ||
d233b485 | 2918 | When b\bba\bas\bsh\bh invokes an external command, the variable _\b_ is set to the |
ac50fbac CR |
2919 | full filename of the command and passed to that command in its environ- |
2920 | ment. | |
17345e5a JA |
2921 | |
2922 | E\bEX\bXI\bIT\bT S\bST\bTA\bAT\bTU\bUS\bS | |
d233b485 | 2923 | The exit status of an executed command is the value returned by the |
17345e5a | 2924 | _\bw_\ba_\bi_\bt_\bp_\bi_\bd system call or equivalent function. Exit statuses fall between |
d233b485 | 2925 | 0 and 255, though, as explained below, the shell may use values above |
17345e5a | 2926 | 125 specially. Exit statuses from shell builtins and compound commands |
a0c0a00f | 2927 | are also limited to this range. Under certain circumstances, the shell |
17345e5a JA |
2928 | will use special values to indicate specific failure modes. |
2929 | ||
2930 | For the shell's purposes, a command which exits with a zero exit status | |
d233b485 CR |
2931 | has succeeded. An exit status of zero indicates success. A non-zero |
2932 | exit status indicates failure. When a command terminates on a fatal | |
17345e5a JA |
2933 | signal _\bN, b\bba\bas\bsh\bh uses the value of 128+_\bN as the exit status. |
2934 | ||
8868edaf CR |
2935 | If a command is not found, the child process created to execute it re- |
2936 | turns a status of 127. If a command is found but is not executable, | |
17345e5a JA |
2937 | the return status is 126. |
2938 | ||
2939 | If a command fails because of an error during expansion or redirection, | |
2940 | the exit status is greater than zero. | |
2941 | ||
d233b485 CR |
2942 | Shell builtin commands return a status of 0 (_\bt_\br_\bu_\be) if successful, and |
2943 | non-zero (_\bf_\ba_\bl_\bs_\be) if an error occurs while they execute. All builtins | |
8868edaf CR |
2944 | return an exit status of 2 to indicate incorrect usage, generally in- |
2945 | valid options or missing arguments. | |
17345e5a | 2946 | |
74091dd4 CR |
2947 | The exit status of the last command is available in the special parame- |
2948 | ter $?. | |
2949 | ||
2950 | B\bBa\bas\bsh\bh itself returns the exit status of the last command executed, un- | |
2951 | less a syntax error occurs, in which case it exits with a non-zero | |
17345e5a JA |
2952 | value. See also the e\bex\bxi\bit\bt builtin command below. |
2953 | ||
2954 | S\bSI\bIG\bGN\bNA\bAL\bLS\bS | |
74091dd4 | 2955 | When b\bba\bas\bsh\bh is interactive, in the absence of any traps, it ignores |
17345e5a | 2956 | S\bSI\bIG\bGT\bTE\bER\bRM\bM (so that k\bki\bil\bll\bl 0\b0 does not kill an interactive shell), and S\bSI\bIG\bGI\bIN\bNT\bT |
74091dd4 | 2957 | is caught and handled (so that the w\bwa\bai\bit\bt builtin is interruptible). In |
8868edaf CR |
2958 | all cases, b\bba\bas\bsh\bh ignores S\bSI\bIG\bGQ\bQU\bUI\bIT\bT. If job control is in effect, b\bba\bas\bsh\bh ig- |
2959 | nores S\bSI\bIG\bGT\bTT\bTI\bIN\bN, S\bSI\bIG\bGT\bTT\bTO\bOU\bU, and S\bSI\bIG\bGT\bTS\bST\bTP\bP. | |
17345e5a JA |
2960 | |
2961 | Non-builtin commands run by b\bba\bas\bsh\bh have signal handlers set to the values | |
8868edaf | 2962 | inherited by the shell from its parent. When job control is not in ef- |
74091dd4 CR |
2963 | fect, asynchronous commands ignore S\bSI\bIG\bGI\bIN\bNT\bT and S\bSI\bIG\bGQ\bQU\bUI\bIT\bT in addition to |
2964 | these inherited handlers. Commands run as a result of command substi- | |
17345e5a JA |
2965 | tution ignore the keyboard-generated job control signals S\bSI\bIG\bGT\bTT\bTI\bIN\bN, S\bSI\bIG\bGT\bT-\b- |
2966 | T\bTO\bOU\bU, and S\bSI\bIG\bGT\bTS\bST\bTP\bP. | |
2967 | ||
74091dd4 CR |
2968 | The shell exits by default upon receipt of a S\bSI\bIG\bGH\bHU\bUP\bP. Before exiting, |
2969 | an interactive shell resends the S\bSI\bIG\bGH\bHU\bUP\bP to all jobs, running or | |
17345e5a | 2970 | stopped. Stopped jobs are sent S\bSI\bIG\bGC\bCO\bON\bNT\bT to ensure that they receive the |
74091dd4 CR |
2971 | S\bSI\bIG\bGH\bHU\bUP\bP. To prevent the shell from sending the signal to a particular |
2972 | job, it should be removed from the jobs table with the d\bdi\bis\bso\bow\bwn\bn builtin | |
2973 | (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below) or marked to not receive S\bSI\bIG\bGH\bHU\bUP\bP us- | |
8868edaf | 2974 | ing d\bdi\bis\bso\bow\bwn\bn -\b-h\bh. |
17345e5a | 2975 | |
74091dd4 | 2976 | If the h\bhu\bup\bpo\bon\bne\bex\bxi\bit\bt shell option has been set with s\bsh\bho\bop\bpt\bt, b\bba\bas\bsh\bh sends a |
17345e5a JA |
2977 | S\bSI\bIG\bGH\bHU\bUP\bP to all jobs when an interactive login shell exits. |
2978 | ||
74091dd4 | 2979 | If b\bba\bas\bsh\bh is waiting for a command to complete and receives a signal for |
17345e5a | 2980 | which a trap has been set, the trap will not be executed until the com- |
74091dd4 CR |
2981 | mand completes. When b\bba\bas\bsh\bh is waiting for an asynchronous command via |
2982 | the w\bwa\bai\bit\bt builtin, the reception of a signal for which a trap has been | |
17345e5a JA |
2983 | set will cause the w\bwa\bai\bit\bt builtin to return immediately with an exit sta- |
2984 | tus greater than 128, immediately after which the trap is executed. | |
2985 | ||
74091dd4 CR |
2986 | When job control is not enabled, and b\bba\bas\bsh\bh is waiting for a foreground |
2987 | command to complete, the shell receives keyboard-generated signals such | |
2988 | as S\bSI\bIG\bGI\bIN\bNT\bT (usually generated by ^\b^C\bC) that users commonly intend to send | |
2989 | to that command. This happens because the shell and the command are in | |
2990 | the same process group as the terminal, and ^\b^C\bC sends S\bSI\bIG\bGI\bIN\bNT\bT to all pro- | |
2991 | cesses in that process group. | |
2992 | ||
2993 | When b\bba\bas\bsh\bh is running without job control enabled and receives S\bSI\bIG\bGI\bIN\bNT\bT | |
2994 | while waiting for a foreground command, it waits until that foreground | |
2995 | command terminates and then decides what to do about the S\bSI\bIG\bGI\bIN\bNT\bT: | |
2996 | ||
2997 | 1. If the command terminates due to the S\bSI\bIG\bGI\bIN\bNT\bT, b\bba\bas\bsh\bh concludes that | |
2998 | the user meant to end the entire script, and acts on the S\bSI\bIG\bGI\bIN\bNT\bT | |
2999 | (e.g., by running a S\bSI\bIG\bGI\bIN\bNT\bT trap or exiting itself); | |
3000 | ||
3001 | 2. If the command does not terminate due to S\bSI\bIG\bGI\bIN\bNT\bT, the program | |
3002 | handled the S\bSI\bIG\bGI\bIN\bNT\bT itself and did not treat it as a fatal sig- | |
3003 | nal. In that case, b\bba\bas\bsh\bh does not treat S\bSI\bIG\bGI\bIN\bNT\bT as a fatal sig- | |
3004 | nal, either, instead assuming that the S\bSI\bIG\bGI\bIN\bNT\bT was used as part | |
3005 | of the program's normal operation (e.g., emacs uses it to abort | |
3006 | editing commands) or deliberately discarded. However, b\bba\bas\bsh\bh will | |
3007 | run any trap set on S\bSI\bIG\bGI\bIN\bNT\bT, as it does with any other trapped | |
3008 | signal it receives while it is waiting for the foreground com- | |
3009 | mand to complete, for compatibility. | |
3010 | ||
17345e5a | 3011 | J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL |
8868edaf CR |
3012 | _\bJ_\bo_\bb _\bc_\bo_\bn_\bt_\br_\bo_\bl refers to the ability to selectively stop (_\bs_\bu_\bs_\bp_\be_\bn_\bd) the ex- |
3013 | ecution of processes and continue (_\br_\be_\bs_\bu_\bm_\be) their execution at a later | |
3014 | point. A user typically employs this facility via an interactive in- | |
3015 | terface supplied jointly by the operating system kernel's terminal | |
0001803f | 3016 | driver and b\bba\bas\bsh\bh. |
17345e5a | 3017 | |
d233b485 CR |
3018 | The shell associates a _\bj_\bo_\bb with each pipeline. It keeps a table of |
3019 | currently executing jobs, which may be listed with the j\bjo\bob\bbs\bs command. | |
3020 | When b\bba\bas\bsh\bh starts a job asynchronously (in the _\bb_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd), it prints a | |
17345e5a JA |
3021 | line that looks like: |
3022 | ||
3023 | [1] 25647 | |
3024 | ||
3025 | indicating that this job is job number 1 and that the process ID of the | |
3026 | last process in the pipeline associated with this job is 25647. All of | |
d233b485 | 3027 | the processes in a single pipeline are members of the same job. B\bBa\bas\bsh\bh |
17345e5a JA |
3028 | uses the _\bj_\bo_\bb abstraction as the basis for job control. |
3029 | ||
d233b485 | 3030 | To facilitate the implementation of the user interface to job control, |
17345e5a JA |
3031 | the operating system maintains the notion of a _\bc_\bu_\br_\br_\be_\bn_\bt _\bt_\be_\br_\bm_\bi_\bn_\ba_\bl _\bp_\br_\bo_\bc_\be_\bs_\bs |
3032 | _\bg_\br_\bo_\bu_\bp _\bI_\bD. Members of this process group (processes whose process group | |
3033 | ID is equal to the current terminal process group ID) receive keyboard- | |
d233b485 CR |
3034 | generated signals such as S\bSI\bIG\bGI\bIN\bNT\bT. These processes are said to be in |
3035 | the _\bf_\bo_\br_\be_\bg_\br_\bo_\bu_\bn_\bd. _\bB_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd processes are those whose process group ID | |
17345e5a | 3036 | differs from the terminal's; such processes are immune to keyboard-gen- |
0001803f | 3037 | erated signals. Only foreground processes are allowed to read from or, |
d233b485 CR |
3038 | if the user so specifies with stty tostop, write to the terminal. |
3039 | Background processes which attempt to read from (write to when stty | |
3040 | tostop is in effect) the terminal are sent a S\bSI\bIG\bGT\bTT\bTI\bIN\bN (\b(S\bSI\bIG\bGT\bTT\bTO\bOU\bU)\b) signal | |
3041 | by the kernel's terminal driver, which, unless caught, suspends the | |
0001803f | 3042 | process. |
17345e5a | 3043 | |
d233b485 | 3044 | If the operating system on which b\bba\bas\bsh\bh is running supports job control, |
17345e5a JA |
3045 | b\bba\bas\bsh\bh contains facilities to use it. Typing the _\bs_\bu_\bs_\bp_\be_\bn_\bd character (typ- |
3046 | ically ^\b^Z\bZ, Control-Z) while a process is running causes that process to | |
d233b485 CR |
3047 | be stopped and returns control to b\bba\bas\bsh\bh. Typing the _\bd_\be_\bl_\ba_\by_\be_\bd _\bs_\bu_\bs_\bp_\be_\bn_\bd |
3048 | character (typically ^\b^Y\bY, Control-Y) causes the process to be stopped | |
8868edaf CR |
3049 | when it attempts to read input from the terminal, and control to be re- |
3050 | turned to b\bba\bas\bsh\bh. The user may then manipulate the state of this job, | |
d233b485 | 3051 | using the b\bbg\bg command to continue it in the background, the f\bfg\bg command |
17345e5a JA |
3052 | to continue it in the foreground, or the k\bki\bil\bll\bl command to kill it. A ^\b^Z\bZ |
3053 | takes effect immediately, and has the additional side effect of causing | |
3054 | pending output and typeahead to be discarded. | |
3055 | ||
3056 | There are a number of ways to refer to a job in the shell. The charac- | |
d233b485 | 3057 | ter %\b% introduces a job specification (_\bj_\bo_\bb_\bs_\bp_\be_\bc). Job number _\bn may be |
17345e5a JA |
3058 | referred to as %\b%n\bn. A job may also be referred to using a prefix of the |
3059 | name used to start it, or using a substring that appears in its command | |
8868edaf CR |
3060 | line. For example, %\b%c\bce\be refers to a stopped job whose command name be- |
3061 | gins with c\bce\be. If a prefix matches more than one job, b\bba\bas\bsh\bh reports an | |
3062 | error. Using %\b%?\b?c\bce\be, on the other hand, refers to any job containing the | |
3063 | string c\bce\be in its command line. If the substring matches more than one | |
3064 | job, b\bba\bas\bsh\bh reports an error. The symbols %\b%%\b% and %\b%+\b+ refer to the shell's | |
3065 | notion of the _\bc_\bu_\br_\br_\be_\bn_\bt _\bj_\bo_\bb, which is the last job stopped while it was | |
3066 | in the foreground or started in the background. The _\bp_\br_\be_\bv_\bi_\bo_\bu_\bs _\bj_\bo_\bb may | |
3067 | be referenced using %\b%-\b-. If there is only a single job, %\b%+\b+ and %\b%-\b- can | |
3068 | both be used to refer to that job. In output pertaining to jobs (e.g., | |
3069 | the output of the j\bjo\bob\bbs\bs command), the current job is always flagged with | |
3070 | a +\b+, and the previous job with a -\b-. A single % (with no accompanying | |
3071 | job specification) also refers to the current job. | |
17345e5a | 3072 | |
d233b485 CR |
3073 | Simply naming a job can be used to bring it into the foreground: %\b%1\b1 is |
3074 | a synonym for `\b``\b`f\bfg\bg %\b%1\b1'\b''\b', bringing job 1 from the background into the | |
3075 | foreground. Similarly, `\b``\b`%\b%1\b1 &\b&'\b''\b' resumes job 1 in the background, | |
17345e5a JA |
3076 | equivalent to `\b``\b`b\bbg\bg %\b%1\b1'\b''\b'. |
3077 | ||
d233b485 | 3078 | The shell learns immediately whenever a job changes state. Normally, |
17345e5a | 3079 | b\bba\bas\bsh\bh waits until it is about to print a prompt before reporting changes |
d233b485 | 3080 | in a job's status so as to not interrupt any other output. If the -\b-b\bb |
17345e5a | 3081 | option to the s\bse\bet\bt builtin command is enabled, b\bba\bas\bsh\bh reports such changes |
8868edaf CR |
3082 | immediately. Any trap on S\bSI\bIG\bGC\bCH\bHL\bLD\bD is executed for each child that ex- |
3083 | its. | |
17345e5a | 3084 | |
d233b485 CR |
3085 | If an attempt to exit b\bba\bas\bsh\bh is made while jobs are stopped (or, if the |
3086 | c\bch\bhe\bec\bck\bkj\bjo\bob\bbs\bs shell option has been enabled using the s\bsh\bho\bop\bpt\bt builtin, run- | |
17345e5a | 3087 | ning), the shell prints a warning message, and, if the c\bch\bhe\bec\bck\bkj\bjo\bob\bbs\bs option |
d233b485 CR |
3088 | is enabled, lists the jobs and their statuses. The j\bjo\bob\bbs\bs command may |
3089 | then be used to inspect their status. If a second attempt to exit is | |
3090 | made without an intervening command, the shell does not print another | |
17345e5a JA |
3091 | warning, and any stopped jobs are terminated. |
3092 | ||
d233b485 CR |
3093 | When the shell is waiting for a job or process using the w\bwa\bai\bit\bt builtin, |
3094 | and job control is enabled, w\bwa\bai\bit\bt will return when the job changes | |
8868edaf CR |
3095 | state. The -\b-f\bf option causes w\bwa\bai\bit\bt to wait until the job or process ter- |
3096 | minates before returning. | |
d233b485 | 3097 | |
17345e5a JA |
3098 | P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG |
3099 | When executing interactively, b\bba\bas\bsh\bh displays the primary prompt P\bPS\bS1\b1 when | |
3100 | it is ready to read a command, and the secondary prompt P\bPS\bS2\b2 when it | |
a0c0a00f | 3101 | needs more input to complete a command. B\bBa\bas\bsh\bh displays P\bPS\bS0\b0 after it |
8868edaf CR |
3102 | reads a command but before executing it. B\bBa\bas\bsh\bh displays P\bPS\bS4\b4 as de- |
3103 | scribed above before tracing each command when the -\b-x\bx option is en- | |
3104 | abled. B\bBa\bas\bsh\bh allows these prompt strings to be customized by inserting | |
3105 | a number of backslash-escaped special characters that are decoded as | |
3106 | follows: | |
17345e5a | 3107 | \\b\a\ba an ASCII bell character (07) |
a0c0a00f | 3108 | \\b\d\bd the date in "Weekday Month Date" format (e.g., "Tue May |
17345e5a JA |
3109 | 26") |
3110 | \\b\D\bD{\b{_\bf_\bo_\br_\bm_\ba_\bt}\b} | |
8868edaf CR |
3111 | the _\bf_\bo_\br_\bm_\ba_\bt is passed to _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be(3) and the result is in- |
3112 | serted into the prompt string; an empty _\bf_\bo_\br_\bm_\ba_\bt results in | |
3113 | a locale-specific time representation. The braces are | |
17345e5a JA |
3114 | required |
3115 | \\b\e\be an ASCII escape character (033) | |
3116 | \\b\h\bh the hostname up to the first `.' | |
3117 | \\b\H\bH the hostname | |
3118 | \\b\j\bj the number of jobs currently managed by the shell | |
3119 | \\b\l\bl the basename of the shell's terminal device name | |
3120 | \\b\n\bn newline | |
3121 | \\b\r\br carriage return | |
a0c0a00f | 3122 | \\b\s\bs the name of the shell, the basename of $\b$0\b0 (the portion |
17345e5a JA |
3123 | following the final slash) |
3124 | \\b\t\bt the current time in 24-hour HH:MM:SS format | |
3125 | \\b\T\bT the current time in 12-hour HH:MM:SS format | |
3126 | \\b\@\b@ the current time in 12-hour am/pm format | |
3127 | \\b\A\bA the current time in 24-hour HH:MM format | |
3128 | \\b\u\bu the username of the current user | |
3129 | \\b\v\bv the version of b\bba\bas\bsh\bh (e.g., 2.00) | |
3130 | \\b\V\bV the release of b\bba\bas\bsh\bh, version + patch level (e.g., 2.00.0) | |
74091dd4 CR |
3131 | \\b\w\bw the value of the P\bPW\bWD\bD shell variable ($\b$P\bPW\bWD\bD), with $\b$H\bHO\bOM\bME\bE |
3132 | abbreviated with a tilde (uses the value of the | |
3133 | P\bPR\bRO\bOM\bMP\bPT\bT_\b_D\bDI\bIR\bRT\bTR\bRI\bIM\bM variable) | |
3134 | \\b\W\bW the basename of $\b$P\bPW\bWD\bD, with $\b$H\bHO\bOM\bME\bE abbreviated with a tilde | |
17345e5a JA |
3135 | \\b\!\b! the history number of this command |
3136 | \\b\#\b# the command number of this command | |
3137 | \\b\$\b$ if the effective UID is 0, a #\b#, otherwise a $\b$ | |
3138 | \\b\_\bn_\bn_\bn the character corresponding to the octal number _\bn_\bn_\bn | |
3139 | \\b\\\b\ a backslash | |
74091dd4 CR |
3140 | \\b\[\b[ begin a sequence of non-printing characters, which could |
3141 | be used to embed a terminal control sequence into the | |
17345e5a JA |
3142 | prompt |
3143 | \\b\]\b] end a sequence of non-printing characters | |
3144 | ||
74091dd4 CR |
3145 | The command number and the history number are usually different: the |
3146 | history number of a command is its position in the history list, which | |
3147 | may include commands restored from the history file (see H\bHI\bIS\bST\bTO\bOR\bRY\bY be- | |
3148 | low), while the command number is the position in the sequence of com- | |
3149 | mands executed during the current shell session. After the string is | |
3150 | decoded, it is expanded via parameter expansion, command substitution, | |
3151 | arithmetic expansion, and quote removal, subject to the value of the | |
8868edaf | 3152 | p\bpr\bro\bom\bmp\bpt\btv\bva\bar\brs\bs shell option (see the description of the s\bsh\bho\bop\bpt\bt command under |
74091dd4 CR |
3153 | S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). This can have unwanted side effects if |
3154 | escaped portions of the string appear within command substitution or | |
8868edaf | 3155 | contain characters special to word expansion. |
17345e5a JA |
3156 | |
3157 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE | |
74091dd4 | 3158 | This is the library that handles reading input when using an interac- |
17345e5a JA |
3159 | tive shell, unless the -\b--\b-n\bno\boe\bed\bdi\bit\bti\bin\bng\bg option is given at shell invocation. |
3160 | Line editing is also used when using the -\b-e\be option to the r\bre\bea\bad\bd builtin. | |
495aee44 | 3161 | By default, the line editing commands are similar to those of Emacs. A |
17345e5a | 3162 | vi-style line editing interface is also available. Line editing can be |
74091dd4 CR |
3163 | enabled at any time using the -\b-o\bo e\bem\bma\bac\bcs\bs or -\b-o\bo v\bvi\bi options to the s\bse\bet\bt |
3164 | builtin (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). To turn off line editing | |
3165 | after the shell is running, use the +\b+o\bo e\bem\bma\bac\bcs\bs or +\b+o\bo v\bvi\bi options to the | |
17345e5a JA |
3166 | s\bse\bet\bt builtin. |
3167 | ||
3168 | R\bRe\bea\bad\bdl\bli\bin\bne\be N\bNo\bot\bta\bat\bti\bio\bon\bn | |
495aee44 | 3169 | In this section, the Emacs-style notation is used to denote keystrokes. |
74091dd4 CR |
3170 | Control keys are denoted by C-_\bk_\be_\by, e.g., C-n means Control-N. Simi- |
3171 | larly, _\bm_\be_\bt_\ba keys are denoted by M-_\bk_\be_\by, so M-x means Meta-X. (On key- | |
3172 | boards without a _\bm_\be_\bt_\ba key, M-_\bx means ESC _\bx, i.e., press the Escape key | |
17345e5a | 3173 | then the _\bx key. This makes ESC the _\bm_\be_\bt_\ba _\bp_\br_\be_\bf_\bi_\bx. The combination M-C-_\bx |
74091dd4 | 3174 | means ESC-Control-_\bx, or press the Escape key then hold the Control key |
17345e5a JA |
3175 | while pressing the _\bx key.) |
3176 | ||
3177 | Readline commands may be given numeric _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs, which normally act as | |
74091dd4 CR |
3178 | a repeat count. Sometimes, however, it is the sign of the argument |
3179 | that is significant. Passing a negative argument to a command that | |
3180 | acts in the forward direction (e.g., k\bki\bil\bll\bl-\b-l\bli\bin\bne\be) causes that command to | |
3181 | act in a backward direction. Commands whose behavior with arguments | |
17345e5a JA |
3182 | deviates from this are noted below. |
3183 | ||
74091dd4 | 3184 | When a command is described as _\bk_\bi_\bl_\bl_\bi_\bn_\bg text, the text deleted is saved |
17345e5a JA |
3185 | for possible future retrieval (_\by_\ba_\bn_\bk_\bi_\bn_\bg). The killed text is saved in a |
3186 | _\bk_\bi_\bl_\bl _\br_\bi_\bn_\bg. Consecutive kills cause the text to be accumulated into one | |
3187 | unit, which can be yanked all at once. Commands which do not kill text | |
3188 | separate the chunks of text on the kill ring. | |
3189 | ||
3190 | R\bRe\bea\bad\bdl\bli\bin\bne\be I\bIn\bni\bit\bti\bia\bal\bli\biz\bza\bat\bti\bio\bon\bn | |
74091dd4 CR |
3191 | Readline is customized by putting commands in an initialization file |
3192 | (the _\bi_\bn_\bp_\bu_\bt_\br_\bc file). The name of this file is taken from the value of | |
8868edaf | 3193 | the I\bIN\bNP\bPU\bUT\bTR\bRC\bC variable. If that variable is unset, the default is _\b~_\b/_\b._\bi_\bn_\b- |
74091dd4 CR |
3194 | _\bp_\bu_\bt_\br_\bc. If that file does not exist or cannot be read, the ultimate |
3195 | default is _\b/_\be_\bt_\bc_\b/_\bi_\bn_\bp_\bu_\bt_\br_\bc. When a program which uses the readline li- | |
3196 | brary starts up, the initialization file is read, and the key bindings | |
3197 | and variables are set. There are only a few basic constructs allowed | |
3198 | in the readline initialization file. Blank lines are ignored. Lines | |
3199 | beginning with a #\b# are comments. Lines beginning with a $\b$ indicate | |
3200 | conditional constructs. Other lines denote key bindings and variable | |
8868edaf | 3201 | settings. |
17345e5a | 3202 | |
74091dd4 | 3203 | The default key-bindings may be changed with an _\bi_\bn_\bp_\bu_\bt_\br_\bc file. Other |
17345e5a JA |
3204 | programs that use this library may add their own commands and bindings. |
3205 | ||
3206 | For example, placing | |
3207 | ||
3208 | M-Control-u: universal-argument | |
3209 | or | |
3210 | C-Meta-u: universal-argument | |
74091dd4 | 3211 | into the _\bi_\bn_\bp_\bu_\bt_\br_\bc would make M-C-u execute the readline command _\bu_\bn_\bi_\bv_\be_\br_\b- |
17345e5a JA |
3212 | _\bs_\ba_\bl_\b-_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt. |
3213 | ||
74091dd4 | 3214 | The following symbolic character names are recognized: _\bR_\bU_\bB_\bO_\bU_\bT, _\bD_\bE_\bL, |
17345e5a JA |
3215 | _\bE_\bS_\bC, _\bL_\bF_\bD, _\bN_\bE_\bW_\bL_\bI_\bN_\bE, _\bR_\bE_\bT, _\bR_\bE_\bT_\bU_\bR_\bN, _\bS_\bP_\bC, _\bS_\bP_\bA_\bC_\bE, and _\bT_\bA_\bB. |
3216 | ||
74091dd4 | 3217 | In addition to command names, readline allows keys to be bound to a |
17345e5a JA |
3218 | string that is inserted when the key is pressed (a _\bm_\ba_\bc_\br_\bo). |
3219 | ||
3220 | R\bRe\bea\bad\bdl\bli\bin\bne\be K\bKe\bey\by B\bBi\bin\bnd\bdi\bin\bng\bgs\bs | |
74091dd4 CR |
3221 | The syntax for controlling key bindings in the _\bi_\bn_\bp_\bu_\bt_\br_\bc file is simple. |
3222 | All that is required is the name of the command or the text of a macro | |
a0c0a00f | 3223 | and a key sequence to which it should be bound. The name may be speci- |
17345e5a JA |
3224 | fied in one of two ways: as a symbolic key name, possibly with _\bM_\be_\bt_\ba_\b- or |
3225 | _\bC_\bo_\bn_\bt_\br_\bo_\bl_\b- prefixes, or as a key sequence. | |
3226 | ||
3227 | When using the form k\bke\bey\byn\bna\bam\bme\be:_\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be or _\bm_\ba_\bc_\br_\bo, _\bk_\be_\by_\bn_\ba_\bm_\be is the name | |
3228 | of a key spelled out in English. For example: | |
3229 | ||
3230 | Control-u: universal-argument | |
3231 | Meta-Rubout: backward-kill-word | |
3232 | Control-o: "> output" | |
3233 | ||
74091dd4 CR |
3234 | In the above example, _\bC_\b-_\bu is bound to the function u\bun\bni\biv\bve\ber\brs\bsa\bal\bl-\b-a\bar\brg\bgu\bum\bme\ben\bnt\bt, |
3235 | _\bM_\b-_\bD_\bE_\bL is bound to the function b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-k\bki\bil\bll\bl-\b-w\bwo\bor\brd\bd, and _\bC_\b-_\bo is bound to | |
3236 | run the macro expressed on the right hand side (that is, to insert the | |
17345e5a JA |
3237 | text ``> output'' into the line). |
3238 | ||
74091dd4 CR |
3239 | In the second form, "\b"k\bke\bey\bys\bse\beq\bq"\b":_\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be or _\bm_\ba_\bc_\br_\bo, k\bke\bey\bys\bse\beq\bq differs |
3240 | from k\bke\bey\byn\bna\bam\bme\be above in that strings denoting an entire key sequence may | |
3241 | be specified by placing the sequence within double quotes. Some GNU | |
3242 | Emacs style key escapes can be used, as in the following example, but | |
17345e5a JA |
3243 | the symbolic character names are not recognized. |
3244 | ||
3245 | "\C-u": universal-argument | |
3246 | "\C-x\C-r": re-read-init-file | |
3247 | "\e[11~": "Function Key 1" | |
3248 | ||
3249 | In this example, _\bC_\b-_\bu is again bound to the function u\bun\bni\biv\bve\ber\brs\bsa\bal\bl-\b-a\bar\brg\bgu\bum\bme\ben\bnt\bt. | |
74091dd4 | 3250 | _\bC_\b-_\bx _\bC_\b-_\br is bound to the function r\bre\be-\b-r\bre\bea\bad\bd-\b-i\bin\bni\bit\bt-\b-f\bfi\bil\ble\be, and _\bE_\bS_\bC _\b[ _\b1 _\b1 _\b~ is |
17345e5a JA |
3251 | bound to insert the text ``Function Key 1''. |
3252 | ||
3253 | The full set of GNU Emacs style escape sequences is | |
3254 | \\b\C\bC-\b- control prefix | |
3255 | \\b\M\bM-\b- meta prefix | |
3256 | \\b\e\be an escape character | |
3257 | \\b\\\b\ backslash | |
3258 | \\b\"\b" literal " | |
3259 | \\b\'\b' literal ' | |
3260 | ||
74091dd4 | 3261 | In addition to the GNU Emacs style escape sequences, a second set of |
17345e5a JA |
3262 | backslash escapes is available: |
3263 | \\b\a\ba alert (bell) | |
3264 | \\b\b\bb backspace | |
3265 | \\b\d\bd delete | |
3266 | \\b\f\bf form feed | |
3267 | \\b\n\bn newline | |
3268 | \\b\r\br carriage return | |
3269 | \\b\t\bt horizontal tab | |
3270 | \\b\v\bv vertical tab | |
74091dd4 | 3271 | \\b\_\bn_\bn_\bn the eight-bit character whose value is the octal value |
17345e5a | 3272 | _\bn_\bn_\bn (one to three digits) |
74091dd4 | 3273 | \\b\x\bx_\bH_\bH the eight-bit character whose value is the hexadecimal |
17345e5a JA |
3274 | value _\bH_\bH (one or two hex digits) |
3275 | ||
3276 | When entering the text of a macro, single or double quotes must be used | |
3277 | to indicate a macro definition. Unquoted text is assumed to be a func- | |
74091dd4 CR |
3278 | tion name. In the macro body, the backslash escapes described above |
3279 | are expanded. Backslash will quote any other character in the macro | |
17345e5a JA |
3280 | text, including " and '. |
3281 | ||
74091dd4 CR |
3282 | B\bBa\bas\bsh\bh allows the current readline key bindings to be displayed or modi- |
3283 | fied with the b\bbi\bin\bnd\bd builtin command. The editing mode may be switched | |
3284 | during interactive use by using the -\b-o\bo option to the s\bse\bet\bt builtin com- | |
17345e5a JA |
3285 | mand (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). |
3286 | ||
3287 | R\bRe\bea\bad\bdl\bli\bin\bne\be V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs | |
3288 | Readline has variables that can be used to further customize its behav- | |
3289 | ior. A variable may be set in the _\bi_\bn_\bp_\bu_\bt_\br_\bc file with a statement of the | |
3290 | form | |
3291 | ||
3292 | s\bse\bet\bt _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be_\b-_\bn_\ba_\bm_\be _\bv_\ba_\bl_\bu_\be | |
8868edaf | 3293 | or using the b\bbi\bin\bnd\bd builtin command (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). |
17345e5a | 3294 | |
74091dd4 CR |
3295 | Except where noted, readline variables can take the values O\bOn\bn or O\bOf\bff\bf |
3296 | (without regard to case). Unrecognized variable names are ignored. | |
3297 | When a variable value is read, empty or null values, "on" (case-insen- | |
17345e5a JA |
3298 | sitive), and "1" are equivalent to O\bOn\bn. All other values are equivalent |
3299 | to O\bOf\bff\bf. The variables and their default values are: | |
3300 | ||
74091dd4 CR |
3301 | a\bac\bct\bti\biv\bve\be-\b-r\bre\beg\bgi\bio\bon\bn-\b-s\bst\bta\bar\brt\bt-\b-c\bco\bol\blo\bor\br |
3302 | A string variable that controls the text color and background | |
3303 | when displaying the text in the active region (see the descrip- | |
3304 | tion of e\ben\bna\bab\bbl\ble\be-\b-a\bac\bct\bti\biv\bve\be-\b-r\bre\beg\bgi\bio\bon\bn below). This string must not take | |
3305 | up any physical character positions on the display, so it should | |
3306 | consist only of terminal escape sequences. It is output to the | |
3307 | terminal before displaying the text in the active region. This | |
3308 | variable is reset to the default value whenever the terminal | |
3309 | type changes. The default value is the string that puts the | |
3310 | terminal in standout mode, as obtained from the terminal's ter- | |
3311 | minfo description. A sample value might be "\e[01;33m". | |
3312 | a\bac\bct\bti\biv\bve\be-\b-r\bre\beg\bgi\bio\bon\bn-\b-e\ben\bnd\bd-\b-c\bco\bol\blo\bor\br | |
3313 | A string variable that "undoes" the effects of a\bac\bct\bti\biv\bve\be-\b-r\bre\be-\b- | |
3314 | g\bgi\bio\bon\bn-\b-s\bst\bta\bar\brt\bt-\b-c\bco\bol\blo\bor\br and restores "normal" terminal display appear- | |
3315 | ance after displaying text in the active region. This string | |
3316 | must not take up any physical character positions on the dis- | |
3317 | play, so it should consist only of terminal escape sequences. | |
3318 | It is output to the terminal after displaying the text in the | |
3319 | active region. This variable is reset to the default value | |
3320 | whenever the terminal type changes. The default value is the | |
3321 | string that restores the terminal from standout mode, as ob- | |
3322 | tained from the terminal's terminfo description. A sample value | |
3323 | might be "\e[0m". | |
17345e5a | 3324 | b\bbe\bel\bll\bl-\b-s\bst\bty\byl\ble\be (\b(a\bau\bud\bdi\bib\bbl\ble\be)\b) |
a0c0a00f | 3325 | Controls what happens when readline wants to ring the terminal |
17345e5a | 3326 | bell. If set to n\bno\bon\bne\be, readline never rings the bell. If set to |
a0c0a00f | 3327 | v\bvi\bis\bsi\bib\bbl\ble\be, readline uses a visible bell if one is available. If |
17345e5a JA |
3328 | set to a\bau\bud\bdi\bib\bbl\ble\be, readline attempts to ring the terminal's bell. |
3329 | b\bbi\bin\bnd\bd-\b-t\btt\bty\by-\b-s\bsp\bpe\bec\bci\bia\bal\bl-\b-c\bch\bha\bar\brs\bs (\b(O\bOn\bn)\b) | |
a0c0a00f | 3330 | If set to O\bOn\bn, readline attempts to bind the control characters |
17345e5a JA |
3331 | treated specially by the kernel's terminal driver to their read- |
3332 | line equivalents. | |
a0c0a00f CR |
3333 | b\bbl\bli\bin\bnk\bk-\b-m\bma\bat\btc\bch\bhi\bin\bng\bg-\b-p\bpa\bar\bre\ben\bn (\b(O\bOf\bff\bf)\b) |
3334 | If set to O\bOn\bn, readline attempts to briefly move the cursor to an | |
3335 | opening parenthesis when a closing parenthesis is inserted. | |
3336 | c\bco\bol\blo\bor\bre\bed\bd-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn-\b-p\bpr\bre\bef\bfi\bix\bx (\b(O\bOf\bff\bf)\b) | |
3337 | If set to O\bOn\bn, when listing completions, readline displays the | |
3338 | common prefix of the set of possible completions using a differ- | |
3339 | ent color. The color definitions are taken from the value of | |
74091dd4 CR |
3340 | the L\bLS\bS_\b_C\bCO\bOL\bLO\bOR\bRS\bS environment variable. If there is a color defini- |
3341 | tion in $\b$L\bLS\bS_\b_C\bCO\bOL\bLO\bOR\bRS\bS for the custom suffix "readline-colored-com- | |
3342 | pletion-prefix", readline uses this color for the common prefix | |
3343 | instead of its default. | |
ac50fbac | 3344 | c\bco\bol\blo\bor\bre\bed\bd-\b-s\bst\bta\bat\bts\bs (\b(O\bOf\bff\bf)\b) |
74091dd4 CR |
3345 | If set to O\bOn\bn, readline displays possible completions using dif- |
3346 | ferent colors to indicate their file type. The color defini- | |
3347 | tions are taken from the value of the L\bLS\bS_\b_C\bCO\bOL\bLO\bOR\bRS\bS environment | |
ac50fbac | 3348 | variable. |
17345e5a | 3349 | c\bco\bom\bmm\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn (\b(`\b``\b`#\b#'\b''\b')\b) |
74091dd4 | 3350 | The string that is inserted when the readline i\bin\bns\bse\ber\brt\bt-\b-c\bco\bom\bmm\bme\ben\bnt\bt |
17345e5a JA |
3351 | command is executed. This command is bound to M\bM-\b-#\b# in emacs mode |
3352 | and to #\b# in vi command mode. | |
a0c0a00f | 3353 | c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn-\b-d\bdi\bis\bsp\bpl\bla\bay\by-\b-w\bwi\bid\bdt\bth\bh (\b(-\b-1\b1)\b) |
74091dd4 CR |
3354 | The number of screen columns used to display possible matches |
3355 | when performing completion. The value is ignored if it is less | |
3356 | than 0 or greater than the terminal screen width. A value of 0 | |
3357 | will cause matches to be displayed one per line. The default | |
a0c0a00f | 3358 | value is -1. |
17345e5a JA |
3359 | c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn-\b-i\big\bgn\bno\bor\bre\be-\b-c\bca\bas\bse\be (\b(O\bOf\bff\bf)\b) |
3360 | If set to O\bOn\bn, readline performs filename matching and completion | |
3361 | in a case-insensitive fashion. | |
a0c0a00f | 3362 | c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn-\b-m\bma\bap\bp-\b-c\bca\bas\bse\be (\b(O\bOf\bff\bf)\b) |
74091dd4 CR |
3363 | If set to O\bOn\bn, and c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn-\b-i\big\bgn\bno\bor\bre\be-\b-c\bca\bas\bse\be is enabled, readline |
3364 | treats hyphens (_\b-) and underscores (_\b_) as equivalent when per- | |
a0c0a00f | 3365 | forming case-insensitive filename matching and completion. |
17345e5a | 3366 | c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn-\b-p\bpr\bre\bef\bfi\bix\bx-\b-d\bdi\bis\bsp\bpl\bla\bay\by-\b-l\ble\ben\bng\bgt\bth\bh (\b(0\b0)\b) |
74091dd4 CR |
3367 | The length in characters of the common prefix of a list of pos- |
3368 | sible completions that is displayed without modification. When | |
3369 | set to a value greater than zero, common prefixes longer than | |
3370 | this value are replaced with an ellipsis when displaying possi- | |
17345e5a JA |
3371 | ble completions. |
3372 | c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn-\b-q\bqu\bue\ber\bry\by-\b-i\bit\bte\bem\bms\bs (\b(1\b10\b00\b0)\b) | |
74091dd4 CR |
3373 | This determines when the user is queried about viewing the num- |
3374 | ber of possible completions generated by the p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-c\bco\bom\bmp\bpl\ble\be-\b- | |
3375 | t\bti\bio\bon\bns\bs command. It may be set to any integer value greater than | |
3376 | or equal to zero. If the number of possible completions is | |
3377 | greater than or equal to the value of this variable, readline | |
3378 | will ask whether or not the user wishes to view them; otherwise | |
3379 | they are simply listed on the terminal. A zero value means | |
3380 | readline should never ask; negative values are treated as zero. | |
17345e5a | 3381 | c\bco\bon\bnv\bve\ber\brt\bt-\b-m\bme\bet\bta\ba (\b(O\bOn\bn)\b) |
a0c0a00f | 3382 | If set to O\bOn\bn, readline will convert characters with the eighth |
17345e5a | 3383 | bit set to an ASCII key sequence by stripping the eighth bit and |
a0c0a00f CR |
3384 | prefixing an escape character (in effect, using escape as the |
3385 | _\bm_\be_\bt_\ba _\bp_\br_\be_\bf_\bi_\bx). The default is _\bO_\bn, but readline will set it to | |
74091dd4 CR |
3386 | _\bO_\bf_\bf if the locale contains eight-bit characters. This variable |
3387 | is dependent on the L\bLC\bC_\b_C\bCT\bTY\bYP\bPE\bE locale category, and may change if | |
3388 | the locale is changed. | |
17345e5a JA |
3389 | d\bdi\bis\bsa\bab\bbl\ble\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn (\b(O\bOf\bff\bf)\b) |
3390 | If set to O\bOn\bn, readline will inhibit word completion. Completion | |
ac50fbac | 3391 | characters will be inserted into the line as if they had been |
17345e5a | 3392 | mapped to s\bse\bel\blf\bf-\b-i\bin\bns\bse\ber\brt\bt. |
0001803f | 3393 | e\bec\bch\bho\bo-\b-c\bco\bon\bnt\btr\bro\bol\bl-\b-c\bch\bha\bar\bra\bac\bct\bte\ber\brs\bs (\b(O\bOn\bn)\b) |
ac50fbac | 3394 | When set to O\bOn\bn, on operating systems that indicate they support |
0001803f CR |
3395 | it, readline echoes a character corresponding to a signal gener- |
3396 | ated from the keyboard. | |
a0c0a00f CR |
3397 | e\bed\bdi\bit\bti\bin\bng\bg-\b-m\bmo\bod\bde\be (\b(e\bem\bma\bac\bcs\bs)\b) |
3398 | Controls whether readline begins with a set of key bindings sim- | |
3399 | ilar to _\bE_\bm_\ba_\bc_\bs or _\bv_\bi. e\bed\bdi\bit\bti\bin\bng\bg-\b-m\bmo\bod\bde\be can be set to either e\bem\bma\bac\bcs\bs or | |
3400 | v\bvi\bi. | |
d233b485 CR |
3401 | e\bem\bma\bac\bcs\bs-\b-m\bmo\bod\bde\be-\b-s\bst\btr\bri\bin\bng\bg (\b(@\b@)\b) |
3402 | If the _\bs_\bh_\bo_\bw_\b-_\bm_\bo_\bd_\be_\b-_\bi_\bn_\b-_\bp_\br_\bo_\bm_\bp_\bt variable is enabled, this string is | |
3403 | displayed immediately before the last line of the primary prompt | |
3404 | when emacs editing mode is active. The value is expanded like a | |
3405 | key binding, so the standard set of meta- and control prefixes | |
3406 | and backslash escape sequences is available. Use the \1 and \2 | |
3407 | escapes to begin and end sequences of non-printing characters, | |
3408 | which can be used to embed a terminal control sequence into the | |
3409 | mode string. | |
74091dd4 CR |
3410 | e\ben\bna\bab\bbl\ble\be-\b-a\bac\bct\bti\biv\bve\be-\b-r\bre\beg\bgi\bio\bon\bn (\b(O\bOn\bn)\b) |
3411 | The _\bp_\bo_\bi_\bn_\bt is the current cursor position, and _\bm_\ba_\br_\bk refers to a | |
3412 | saved cursor position. The text between the point and mark is | |
3413 | referred to as the _\br_\be_\bg_\bi_\bo_\bn. When this variable is set to _\bO_\bn, | |
3414 | readline allows certain commands to designate the region as _\ba_\bc_\b- | |
3415 | _\bt_\bi_\bv_\be. When the region is active, readline highlights the text | |
3416 | in the region using the value of the a\bac\bct\bti\biv\bve\be-\b-r\bre\beg\bgi\bio\bon\bn-\b-s\bst\bta\bar\brt\bt-\b-c\bco\bol\blo\bor\br, | |
3417 | which defaults to the string that enables the terminal's stand- | |
3418 | out mode. The active region shows the text inserted by brack- | |
3419 | eted-paste and any matching text found by incremental and non- | |
3420 | incremental history searches. | |
8868edaf | 3421 | e\ben\bna\bab\bbl\ble\be-\b-b\bbr\bra\bac\bck\bke\bet\bte\bed\bd-\b-p\bpa\bas\bst\bte\be (\b(O\bOn\bn)\b) |
74091dd4 CR |
3422 | When set to O\bOn\bn, readline configures the terminal to insert each |
3423 | paste into the editing buffer as a single string of characters, | |
3424 | instead of treating each character as if it had been read from | |
3425 | the keyboard. This prevents readline from executing any editing | |
3426 | commands bound to key sequences appearing in the pasted text. | |
17345e5a JA |
3427 | e\ben\bna\bab\bbl\ble\be-\b-k\bke\bey\byp\bpa\bad\bd (\b(O\bOf\bff\bf)\b) |
3428 | When set to O\bOn\bn, readline will try to enable the application key- | |
8868edaf CR |
3429 | pad when it is called. Some systems need this to enable the ar- |
3430 | row keys. | |
0001803f | 3431 | e\ben\bna\bab\bbl\ble\be-\b-m\bme\bet\bta\ba-\b-k\bke\bey\by (\b(O\bOn\bn)\b) |
d233b485 CR |
3432 | When set to O\bOn\bn, readline will try to enable any meta modifier |
3433 | key the terminal claims to support when it is called. On many | |
0001803f | 3434 | terminals, the meta key is used to send eight-bit characters. |
17345e5a | 3435 | e\bex\bxp\bpa\ban\bnd\bd-\b-t\bti\bil\bld\bde\be (\b(O\bOf\bff\bf)\b) |
8868edaf CR |
3436 | If set to O\bOn\bn, tilde expansion is performed when readline at- |
3437 | tempts word completion. | |
17345e5a | 3438 | h\bhi\bis\bst\bto\bor\bry\by-\b-p\bpr\bre\bes\bse\ber\brv\bve\be-\b-p\bpo\boi\bin\bnt\bt (\b(O\bOf\bff\bf)\b) |
d233b485 CR |
3439 | If set to O\bOn\bn, the history code attempts to place point at the |
3440 | same location on each history line retrieved with p\bpr\bre\bev\bvi\bio\bou\bus\bs-\b-h\bhi\bis\bs-\b- | |
17345e5a | 3441 | t\bto\bor\bry\by or n\bne\bex\bxt\bt-\b-h\bhi\bis\bst\bto\bor\bry\by. |
a0c0a00f | 3442 | h\bhi\bis\bst\bto\bor\bry\by-\b-s\bsi\biz\bze\be (\b(u\bun\bns\bse\bet\bt)\b) |
d233b485 CR |
3443 | Set the maximum number of history entries saved in the history |
3444 | list. If set to zero, any existing history entries are deleted | |
ac50fbac | 3445 | and no new entries are saved. If set to a value less than zero, |
d233b485 CR |
3446 | the number of history entries is not limited. By default, the |
3447 | number of history entries is set to the value of the H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE | |
3448 | shell variable. If an attempt is made to set _\bh_\bi_\bs_\bt_\bo_\br_\by_\b-_\bs_\bi_\bz_\be to a | |
a0c0a00f CR |
3449 | non-numeric value, the maximum number of history entries will be |
3450 | set to 500. | |
17345e5a | 3451 | h\bho\bor\bri\biz\bzo\bon\bnt\bta\bal\bl-\b-s\bsc\bcr\bro\bol\bll\bl-\b-m\bmo\bod\bde\be (\b(O\bOf\bff\bf)\b) |
d233b485 | 3452 | When set to O\bOn\bn, makes readline use a single line for display, |
17345e5a | 3453 | scrolling the input horizontally on a single screen line when it |
d233b485 | 3454 | becomes longer than the screen width rather than wrapping to a |
8868edaf CR |
3455 | new line. This setting is automatically enabled for terminals |
3456 | of height 1. | |
17345e5a | 3457 | i\bin\bnp\bpu\but\bt-\b-m\bme\bet\bta\ba (\b(O\bOf\bff\bf)\b) |
8868edaf CR |
3458 | If set to O\bOn\bn, readline will enable eight-bit input (that is, it |
3459 | will not strip the eighth bit from the characters it reads), re- | |
3460 | gardless of what the terminal claims it can support. The name | |
3461 | m\bme\bet\bta\ba-\b-f\bfl\bla\bag\bg is a synonym for this variable. The default is _\bO_\bf_\bf, | |
3462 | but readline will set it to _\bO_\bn if the locale contains eight-bit | |
74091dd4 CR |
3463 | characters. This variable is dependent on the L\bLC\bC_\b_C\bCT\bTY\bYP\bPE\bE locale |
3464 | category, and may change if the locale is changed. | |
17345e5a | 3465 | i\bis\bse\bea\bar\brc\bch\bh-\b-t\bte\ber\brm\bmi\bin\bna\bat\bto\bor\brs\bs (\b(`\b``\b`C\bC-\b-[\b[C\bC-\b-J\bJ'\b''\b')\b) |
74091dd4 CR |
3466 | The string of characters that should terminate an incremental |
3467 | search without subsequently executing the character as a com- | |
3468 | mand. If this variable has not been given a value, the charac- | |
17345e5a JA |
3469 | ters _\bE_\bS_\bC and _\bC_\b-_\bJ will terminate an incremental search. |
3470 | k\bke\bey\bym\bma\bap\bp (\b(e\bem\bma\bac\bcs\bs)\b) | |
74091dd4 CR |
3471 | Set the current readline keymap. The set of valid keymap names |
3472 | is _\be_\bm_\ba_\bc_\bs_\b, _\be_\bm_\ba_\bc_\bs_\b-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd_\b, _\be_\bm_\ba_\bc_\bs_\b-_\bm_\be_\bt_\ba_\b, _\be_\bm_\ba_\bc_\bs_\b-_\bc_\bt_\bl_\bx_\b, _\bv_\bi_\b, _\bv_\bi_\b-_\bc_\bo_\bm_\b- | |
3473 | _\bm_\ba_\bn_\bd, and _\bv_\bi_\b-_\bi_\bn_\bs_\be_\br_\bt. _\bv_\bi is equivalent to _\bv_\bi_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd; _\be_\bm_\ba_\bc_\bs is | |
3474 | equivalent to _\be_\bm_\ba_\bc_\bs_\b-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd. The default value is _\be_\bm_\ba_\bc_\bs; the | |
17345e5a | 3475 | value of e\bed\bdi\bit\bti\bin\bng\bg-\b-m\bmo\bod\bde\be also affects the default keymap. |
ac50fbac | 3476 | k\bke\bey\bys\bse\beq\bq-\b-t\bti\bim\bme\beo\bou\but\bt (\b(5\b50\b00\b0)\b) |
74091dd4 CR |
3477 | Specifies the duration _\br_\be_\ba_\bd_\bl_\bi_\bn_\be will wait for a character when |
3478 | reading an ambiguous key sequence (one that can form a complete | |
ac50fbac | 3479 | key sequence using the input read so far, or can take additional |
74091dd4 CR |
3480 | input to complete a longer key sequence). If no input is re- |
3481 | ceived within the timeout, _\br_\be_\ba_\bd_\bl_\bi_\bn_\be will use the shorter but | |
3482 | complete key sequence. The value is specified in milliseconds, | |
3483 | so a value of 1000 means that _\br_\be_\ba_\bd_\bl_\bi_\bn_\be will wait one second for | |
3484 | additional input. If this variable is set to a value less than | |
3485 | or equal to zero, or to a non-numeric value, _\br_\be_\ba_\bd_\bl_\bi_\bn_\be will wait | |
3486 | until another key is pressed to decide which key sequence to | |
ac50fbac | 3487 | complete. |
17345e5a JA |
3488 | m\bma\bar\brk\bk-\b-d\bdi\bir\bre\bec\bct\bto\bor\bri\bie\bes\bs (\b(O\bOn\bn)\b) |
3489 | If set to O\bOn\bn, completed directory names have a slash appended. | |
3490 | m\bma\bar\brk\bk-\b-m\bmo\bod\bdi\bif\bfi\bie\bed\bd-\b-l\bli\bin\bne\bes\bs (\b(O\bOf\bff\bf)\b) | |
74091dd4 | 3491 | If set to O\bOn\bn, history lines that have been modified are dis- |
17345e5a JA |
3492 | played with a preceding asterisk (*\b*). |
3493 | m\bma\bar\brk\bk-\b-s\bsy\bym\bml\bli\bin\bnk\bke\bed\bd-\b-d\bdi\bir\bre\bec\bct\bto\bor\bri\bie\bes\bs (\b(O\bOf\bff\bf)\b) | |
3494 | If set to O\bOn\bn, completed names which are symbolic links to direc- | |
74091dd4 | 3495 | tories have a slash appended (subject to the value of m\bma\bar\brk\bk-\b-d\bdi\bi-\b- |
8868edaf | 3496 | r\bre\bec\bct\bto\bor\bri\bie\bes\bs). |
17345e5a | 3497 | m\bma\bat\btc\bch\bh-\b-h\bhi\bid\bdd\bde\ben\bn-\b-f\bfi\bil\ble\bes\bs (\b(O\bOn\bn)\b) |
74091dd4 CR |
3498 | This variable, when set to O\bOn\bn, causes readline to match files |
3499 | whose names begin with a `.' (hidden files) when performing | |
3500 | filename completion. If set to O\bOf\bff\bf, the leading `.' must be | |
495aee44 CR |
3501 | supplied by the user in the filename to be completed. |
3502 | m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-d\bdi\bis\bsp\bpl\bla\bay\by-\b-p\bpr\bre\bef\bfi\bix\bx (\b(O\bOf\bff\bf)\b) | |
74091dd4 | 3503 | If set to O\bOn\bn, menu completion displays the common prefix of the |
495aee44 CR |
3504 | list of possible completions (which may be empty) before cycling |
3505 | through the list. | |
17345e5a | 3506 | o\bou\but\btp\bpu\but\bt-\b-m\bme\bet\bta\ba (\b(O\bOf\bff\bf)\b) |
74091dd4 | 3507 | If set to O\bOn\bn, readline will display characters with the eighth |
17345e5a | 3508 | bit set directly rather than as a meta-prefixed escape sequence. |
a0c0a00f | 3509 | The default is _\bO_\bf_\bf, but readline will set it to _\bO_\bn if the locale |
74091dd4 CR |
3510 | contains eight-bit characters. This variable is dependent on |
3511 | the L\bLC\bC_\b_C\bCT\bTY\bYP\bPE\bE locale category, and may change if the locale is | |
3512 | changed. | |
17345e5a | 3513 | p\bpa\bag\bge\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(O\bOn\bn)\b) |
74091dd4 | 3514 | If set to O\bOn\bn, readline uses an internal _\bm_\bo_\br_\be-like pager to dis- |
17345e5a JA |
3515 | play a screenful of possible completions at a time. |
3516 | p\bpr\bri\bin\bnt\bt-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs-\b-h\bho\bor\bri\biz\bzo\bon\bnt\bta\bal\bll\bly\by (\b(O\bOf\bff\bf)\b) | |
74091dd4 CR |
3517 | If set to O\bOn\bn, readline will display completions with matches |
3518 | sorted horizontally in alphabetical order, rather than down the | |
17345e5a JA |
3519 | screen. |
3520 | r\bre\bev\bve\ber\brt\bt-\b-a\bal\bll\bl-\b-a\bat\bt-\b-n\bne\bew\bwl\bli\bin\bne\be (\b(O\bOf\bff\bf)\b) | |
74091dd4 | 3521 | If set to O\bOn\bn, readline will undo all changes to history lines |
17345e5a | 3522 | before returning when a\bac\bcc\bce\bep\bpt\bt-\b-l\bli\bin\bne\be is executed. By default, his- |
74091dd4 | 3523 | tory lines may be modified and retain individual undo lists |
17345e5a JA |
3524 | across calls to r\bre\bea\bad\bdl\bli\bin\bne\be. |
3525 | s\bsh\bho\bow\bw-\b-a\bal\bll\bl-\b-i\bif\bf-\b-a\bam\bmb\bbi\big\bgu\buo\bou\bus\bs (\b(O\bOf\bff\bf)\b) | |
74091dd4 | 3526 | This alters the default behavior of the completion functions. |
495aee44 | 3527 | If set to O\bOn\bn, words which have more than one possible completion |
74091dd4 | 3528 | cause the matches to be listed immediately instead of ringing |
17345e5a JA |
3529 | the bell. |
3530 | s\bsh\bho\bow\bw-\b-a\bal\bll\bl-\b-i\bif\bf-\b-u\bun\bnm\bmo\bod\bdi\bif\bfi\bie\bed\bd (\b(O\bOf\bff\bf)\b) | |
74091dd4 | 3531 | This alters the default behavior of the completion functions in |
495aee44 | 3532 | a fashion similar to s\bsh\bho\bow\bw-\b-a\bal\bll\bl-\b-i\bif\bf-\b-a\bam\bmb\bbi\big\bgu\buo\bou\bus\bs. If set to O\bOn\bn, words |
74091dd4 CR |
3533 | which have more than one possible completion without any possi- |
3534 | ble partial completion (the possible completions don't share a | |
3535 | common prefix) cause the matches to be listed immediately in- | |
8868edaf | 3536 | stead of ringing the bell. |
ac50fbac | 3537 | s\bsh\bho\bow\bw-\b-m\bmo\bod\bde\be-\b-i\bin\bn-\b-p\bpr\bro\bom\bmp\bpt\bt (\b(O\bOf\bff\bf)\b) |
74091dd4 CR |
3538 | If set to O\bOn\bn, add a string to the beginning of the prompt indi- |
3539 | cating the editing mode: emacs, vi command, or vi insertion. | |
d233b485 | 3540 | The mode strings are user-settable (e.g., _\be_\bm_\ba_\bc_\bs_\b-_\bm_\bo_\bd_\be_\b-_\bs_\bt_\br_\bi_\bn_\bg). |
0001803f | 3541 | s\bsk\bki\bip\bp-\b-c\bco\bom\bmp\bpl\ble\bet\bte\bed\bd-\b-t\bte\bex\bxt\bt (\b(O\bOf\bff\bf)\b) |
74091dd4 CR |
3542 | If set to O\bOn\bn, this alters the default completion behavior when |
3543 | inserting a single match into the line. It's only active when | |
3544 | performing completion in the middle of a word. If enabled, | |
3545 | readline does not insert characters from the completion that | |
3546 | match characters after point in the word being completed, so | |
0001803f | 3547 | portions of the word following the cursor are not duplicated. |
a0c0a00f | 3548 | v\bvi\bi-\b-c\bcm\bmd\bd-\b-m\bmo\bod\bde\be-\b-s\bst\btr\bri\bin\bng\bg (\b((\b(c\bcm\bmd\bd)\b))\b) |
74091dd4 | 3549 | If the _\bs_\bh_\bo_\bw_\b-_\bm_\bo_\bd_\be_\b-_\bi_\bn_\b-_\bp_\br_\bo_\bm_\bp_\bt variable is enabled, this string is |
d233b485 | 3550 | displayed immediately before the last line of the primary prompt |
74091dd4 | 3551 | when vi editing mode is active and in command mode. The value |
d233b485 | 3552 | is expanded like a key binding, so the standard set of meta- and |
74091dd4 CR |
3553 | control prefixes and backslash escape sequences is available. |
3554 | Use the \1 and \2 escapes to begin and end sequences of non- | |
3555 | printing characters, which can be used to embed a terminal con- | |
d233b485 | 3556 | trol sequence into the mode string. |
a0c0a00f | 3557 | v\bvi\bi-\b-i\bin\bns\bs-\b-m\bmo\bod\bde\be-\b-s\bst\btr\bri\bin\bng\bg (\b((\b(i\bin\bns\bs)\b))\b) |
74091dd4 | 3558 | If the _\bs_\bh_\bo_\bw_\b-_\bm_\bo_\bd_\be_\b-_\bi_\bn_\b-_\bp_\br_\bo_\bm_\bp_\bt variable is enabled, this string is |
d233b485 CR |
3559 | displayed immediately before the last line of the primary prompt |
3560 | when vi editing mode is active and in insertion mode. The value | |
3561 | is expanded like a key binding, so the standard set of meta- and | |
74091dd4 CR |
3562 | control prefixes and backslash escape sequences is available. |
3563 | Use the \1 and \2 escapes to begin and end sequences of non- | |
3564 | printing characters, which can be used to embed a terminal con- | |
d233b485 | 3565 | trol sequence into the mode string. |
17345e5a | 3566 | v\bvi\bis\bsi\bib\bbl\ble\be-\b-s\bst\bta\bat\bts\bs (\b(O\bOf\bff\bf)\b) |
74091dd4 CR |
3567 | If set to O\bOn\bn, a character denoting a file's type as reported by |
3568 | _\bs_\bt_\ba_\bt(2) is appended to the filename when listing possible com- | |
17345e5a JA |
3569 | pletions. |
3570 | ||
3571 | R\bRe\bea\bad\bdl\bli\bin\bne\be C\bCo\bon\bnd\bdi\bit\bti\bio\bon\bna\bal\bl C\bCo\bon\bns\bst\btr\bru\buc\bct\bts\bs | |
74091dd4 CR |
3572 | Readline implements a facility similar in spirit to the conditional |
3573 | compilation features of the C preprocessor which allows key bindings | |
3574 | and variable settings to be performed as the result of tests. There | |
17345e5a JA |
3575 | are four parser directives used. |
3576 | ||
74091dd4 CR |
3577 | $\b$i\bif\bf The $\b$i\bif\bf construct allows bindings to be made based on the edit- |
3578 | ing mode, the terminal being used, or the application using | |
d233b485 | 3579 | readline. The text of the test, after any comparison operator, |
74091dd4 | 3580 | extends to the end of the line; unless otherwise noted, no |
d233b485 CR |
3581 | characters are required to isolate it. |
3582 | ||
74091dd4 CR |
3583 | m\bmo\bod\bde\be The m\bmo\bod\bde\be=\b= form of the $\b$i\bif\bf directive is used to test |
3584 | whether readline is in emacs or vi mode. This may be | |
3585 | used in conjunction with the s\bse\bet\bt k\bke\bey\bym\bma\bap\bp command, for in- | |
3586 | stance, to set bindings in the _\be_\bm_\ba_\bc_\bs_\b-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd and | |
3587 | _\be_\bm_\ba_\bc_\bs_\b-_\bc_\bt_\bl_\bx keymaps only if readline is starting out in | |
17345e5a JA |
3588 | emacs mode. |
3589 | ||
74091dd4 | 3590 | t\bte\ber\brm\bm The t\bte\ber\brm\bm=\b= form may be used to include terminal-specific |
17345e5a JA |
3591 | key bindings, perhaps to bind the key sequences output by |
3592 | the terminal's function keys. The word on the right side | |
a0c0a00f | 3593 | of the =\b= is tested against both the full name of the ter- |
74091dd4 CR |
3594 | minal and the portion of the terminal name before the |
3595 | first -\b-. This allows _\bs_\bu_\bn to match both _\bs_\bu_\bn and _\bs_\bu_\bn_\b-_\bc_\bm_\bd, | |
17345e5a JA |
3596 | for instance. |
3597 | ||
d233b485 | 3598 | v\bve\ber\brs\bsi\bio\bon\bn |
74091dd4 CR |
3599 | The v\bve\ber\brs\bsi\bio\bon\bn test may be used to perform comparisons |
3600 | against specific readline versions. The v\bve\ber\brs\bsi\bio\bon\bn expands | |
3601 | to the current readline version. The set of comparison | |
3602 | operators includes =\b=, (and =\b==\b=), !\b!=\b=, <\b<=\b=, >\b>=\b=, <\b<, and >\b>. | |
3603 | The version number supplied on the right side of the op- | |
3604 | erator consists of a major version number, an optional | |
d233b485 | 3605 | decimal point, and an optional minor version (e.g., 7\b7.\b.1\b1). |
74091dd4 | 3606 | If the minor version is omitted, it is assumed to be 0\b0. |
d233b485 CR |
3607 | The operator may be separated from the string v\bve\ber\brs\bsi\bio\bon\bn and |
3608 | from the version number argument by whitespace. | |
3609 | ||
17345e5a JA |
3610 | a\bap\bpp\bpl\bli\bic\bca\bat\bti\bio\bon\bn |
3611 | The a\bap\bpp\bpl\bli\bic\bca\bat\bti\bio\bon\bn construct is used to include application- | |
74091dd4 CR |
3612 | specific settings. Each program using the readline li- |
3613 | brary sets the _\ba_\bp_\bp_\bl_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\bn_\ba_\bm_\be, and an initialization | |
17345e5a | 3614 | file can test for a particular value. This could be used |
74091dd4 CR |
3615 | to bind key sequences to functions useful for a specific |
3616 | program. For instance, the following command adds a key | |
3617 | sequence that quotes the current or previous word in | |
495aee44 | 3618 | b\bba\bas\bsh\bh: |
17345e5a JA |
3619 | |
3620 | $\b$i\bif\bf Bash | |
3621 | # Quote the current or previous word | |
3622 | "\C-xq": "\eb\"\ef\"" | |
3623 | $\b$e\ben\bnd\bdi\bif\bf | |
3624 | ||
d233b485 CR |
3625 | _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be |
3626 | The _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be construct provides simple equality tests for | |
74091dd4 CR |
3627 | readline variables and values. The permitted comparison |
3628 | operators are _\b=, _\b=_\b=, and _\b!_\b=. The variable name must be | |
d233b485 | 3629 | separated from the comparison operator by whitespace; the |
74091dd4 CR |
3630 | operator may be separated from the value on the right |
3631 | hand side by whitespace. Both string and boolean vari- | |
3632 | ables may be tested. Boolean variables must be tested | |
d233b485 CR |
3633 | against the values _\bo_\bn and _\bo_\bf_\bf. |
3634 | ||
17345e5a JA |
3635 | $\b$e\ben\bnd\bdi\bif\bf This command, as seen in the previous example, terminates an $\b$i\bif\bf |
3636 | command. | |
3637 | ||
3638 | $\b$e\bel\bls\bse\be Commands in this branch of the $\b$i\bif\bf directive are executed if the | |
3639 | test fails. | |
3640 | ||
3641 | $\b$i\bin\bnc\bcl\blu\bud\bde\be | |
74091dd4 CR |
3642 | This directive takes a single filename as an argument and reads |
3643 | commands and bindings from that file. For example, the follow- | |
17345e5a JA |
3644 | ing directive would read _\b/_\be_\bt_\bc_\b/_\bi_\bn_\bp_\bu_\bt_\br_\bc: |
3645 | ||
3646 | $\b$i\bin\bnc\bcl\blu\bud\bde\be _\b/_\be_\bt_\bc_\b/_\bi_\bn_\bp_\bu_\bt_\br_\bc | |
3647 | ||
3648 | S\bSe\bea\bar\brc\bch\bhi\bin\bng\bg | |
74091dd4 | 3649 | Readline provides commands for searching through the command history |
17345e5a JA |
3650 | (see H\bHI\bIS\bST\bTO\bOR\bRY\bY below) for lines containing a specified string. There are |
3651 | two search modes: _\bi_\bn_\bc_\br_\be_\bm_\be_\bn_\bt_\ba_\bl and _\bn_\bo_\bn_\b-_\bi_\bn_\bc_\br_\be_\bm_\be_\bn_\bt_\ba_\bl. | |
3652 | ||
74091dd4 CR |
3653 | Incremental searches begin before the user has finished typing the |
3654 | search string. As each character of the search string is typed, read- | |
17345e5a | 3655 | line displays the next entry from the history matching the string typed |
74091dd4 CR |
3656 | so far. An incremental search requires only as many characters as |
3657 | needed to find the desired history entry. The characters present in | |
3658 | the value of the i\bis\bse\bea\bar\brc\bch\bh-\b-t\bte\ber\brm\bmi\bin\bna\bat\bto\bor\brs\bs variable are used to terminate an | |
17345e5a | 3659 | incremental search. If that variable has not been assigned a value the |
74091dd4 CR |
3660 | Escape and Control-J characters will terminate an incremental search. |
3661 | Control-G will abort an incremental search and restore the original | |
3662 | line. When the search is terminated, the history entry containing the | |
17345e5a JA |
3663 | search string becomes the current line. |
3664 | ||
74091dd4 CR |
3665 | To find other matching entries in the history list, type Control-S or |
3666 | Control-R as appropriate. This will search backward or forward in the | |
3667 | history for the next entry matching the search string typed so far. | |
3668 | Any other key sequence bound to a readline command will terminate the | |
3669 | search and execute that command. For instance, a _\bn_\be_\bw_\bl_\bi_\bn_\be will termi- | |
17345e5a JA |
3670 | nate the search and accept the line, thereby executing the command from |
3671 | the history list. | |
3672 | ||
3673 | Readline remembers the last incremental search string. If two Control- | |
74091dd4 | 3674 | Rs are typed without any intervening characters defining a new search |
17345e5a JA |
3675 | string, any remembered search string is used. |
3676 | ||
74091dd4 CR |
3677 | Non-incremental searches read the entire search string before starting |
3678 | to search for matching history lines. The search string may be typed | |
17345e5a JA |
3679 | by the user or be part of the contents of the current line. |
3680 | ||
3681 | R\bRe\bea\bad\bdl\bli\bin\bne\be C\bCo\bom\bmm\bma\ban\bnd\bd N\bNa\bam\bme\bes\bs | |
74091dd4 | 3682 | The following is a list of the names of the commands and the default |
17345e5a JA |
3683 | key sequences to which they are bound. Command names without an accom- |
3684 | panying key sequence are unbound by default. In the following descrip- | |
74091dd4 CR |
3685 | tions, _\bp_\bo_\bi_\bn_\bt refers to the current cursor position, and _\bm_\ba_\br_\bk refers to |
3686 | a cursor position saved by the s\bse\bet\bt-\b-m\bma\bar\brk\bk command. The text between the | |
17345e5a JA |
3687 | point and mark is referred to as the _\br_\be_\bg_\bi_\bo_\bn. |
3688 | ||
3689 | C\bCo\bom\bmm\bma\ban\bnd\bds\bs f\bfo\bor\br M\bMo\bov\bvi\bin\bng\bg | |
3690 | b\bbe\beg\bgi\bin\bnn\bni\bin\bng\bg-\b-o\bof\bf-\b-l\bli\bin\bne\be (\b(C\bC-\b-a\ba)\b) | |
3691 | Move to the start of the current line. | |
3692 | e\ben\bnd\bd-\b-o\bof\bf-\b-l\bli\bin\bne\be (\b(C\bC-\b-e\be)\b) | |
3693 | Move to the end of the line. | |
3694 | f\bfo\bor\brw\bwa\bar\brd\bd-\b-c\bch\bha\bar\br (\b(C\bC-\b-f\bf)\b) | |
3695 | Move forward a character. | |
3696 | b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-c\bch\bha\bar\br (\b(C\bC-\b-b\bb)\b) | |
3697 | Move back a character. | |
3698 | f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-f\bf)\b) | |
3699 | Move forward to the end of the next word. Words are composed of | |
3700 | alphanumeric characters (letters and digits). | |
3701 | b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-b\bb)\b) | |
74091dd4 | 3702 | Move back to the start of the current or previous word. Words |
17345e5a JA |
3703 | are composed of alphanumeric characters (letters and digits). |
3704 | s\bsh\bhe\bel\bll\bl-\b-f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd | |
74091dd4 | 3705 | Move forward to the end of the next word. Words are delimited |
17345e5a JA |
3706 | by non-quoted shell metacharacters. |
3707 | s\bsh\bhe\bel\bll\bl-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd | |
74091dd4 | 3708 | Move back to the start of the current or previous word. Words |
17345e5a | 3709 | are delimited by non-quoted shell metacharacters. |
d233b485 | 3710 | p\bpr\bre\bev\bvi\bio\bou\bus\bs-\b-s\bsc\bcr\bre\bee\ben\bn-\b-l\bli\bin\bne\be |
74091dd4 CR |
3711 | Attempt to move point to the same physical screen column on the |
3712 | previous physical screen line. This will not have the desired | |
3713 | effect if the current readline line does not take up more than | |
3714 | one physical line or if point is not greater than the length of | |
d233b485 CR |
3715 | the prompt plus the screen width. |
3716 | n\bne\bex\bxt\bt-\b-s\bsc\bcr\bre\bee\ben\bn-\b-l\bli\bin\bne\be | |
74091dd4 | 3717 | Attempt to move point to the same physical screen column on the |
d233b485 | 3718 | next physical screen line. This will not have the desired effect |
74091dd4 CR |
3719 | if the current readline line does not take up more than one |
3720 | physical line or if the length of the current readline line is | |
d233b485 | 3721 | not greater than the length of the prompt plus the screen width. |
8868edaf | 3722 | c\bcl\ble\bea\bar\br-\b-d\bdi\bis\bsp\bpl\bla\bay\by (\b(M\bM-\b-C\bC-\b-l\bl)\b) |
74091dd4 CR |
3723 | Clear the screen and, if possible, the terminal's scrollback |
3724 | buffer, then redraw the current line, leaving the current line | |
8868edaf | 3725 | at the top of the screen. |
17345e5a | 3726 | c\bcl\ble\bea\bar\br-\b-s\bsc\bcr\bre\bee\ben\bn (\b(C\bC-\b-l\bl)\b) |
8868edaf | 3727 | Clear the screen, then redraw the current line, leaving the cur- |
74091dd4 | 3728 | rent line at the top of the screen. With an argument, refresh |
8868edaf | 3729 | the current line without clearing the screen. |
17345e5a JA |
3730 | r\bre\bed\bdr\bra\baw\bw-\b-c\bcu\bur\brr\bre\ben\bnt\bt-\b-l\bli\bin\bne\be |
3731 | Refresh the current line. | |
3732 | ||
3733 | C\bCo\bom\bmm\bma\ban\bnd\bds\bs f\bfo\bor\br M\bMa\ban\bni\bip\bpu\bul\bla\bat\bti\bin\bng\bg t\bth\bhe\be H\bHi\bis\bst\bto\bor\bry\by | |
3734 | a\bac\bcc\bce\bep\bpt\bt-\b-l\bli\bin\bne\be (\b(N\bNe\bew\bwl\bli\bin\bne\be,\b, R\bRe\bet\btu\bur\brn\bn)\b) | |
3735 | Accept the line regardless of where the cursor is. If this line | |
74091dd4 CR |
3736 | is non-empty, add it to the history list according to the state |
3737 | of the H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL variable. If the line is a modified history | |
17345e5a JA |
3738 | line, then restore the history line to its original state. |
3739 | p\bpr\bre\bev\bvi\bio\bou\bus\bs-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(C\bC-\b-p\bp)\b) | |
3740 | Fetch the previous command from the history list, moving back in | |
3741 | the list. | |
3742 | n\bne\bex\bxt\bt-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(C\bC-\b-n\bn)\b) | |
74091dd4 | 3743 | Fetch the next command from the history list, moving forward in |
17345e5a JA |
3744 | the list. |
3745 | b\bbe\beg\bgi\bin\bnn\bni\bin\bng\bg-\b-o\bof\bf-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(M\bM-\b-<\b<)\b) | |
3746 | Move to the first line in the history. | |
3747 | e\ben\bnd\bd-\b-o\bof\bf-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(M\bM-\b->\b>)\b) | |
74091dd4 | 3748 | Move to the end of the input history, i.e., the line currently |
17345e5a | 3749 | being entered. |
74091dd4 CR |
3750 | o\bop\bpe\ber\bra\bat\bte\be-\b-a\ban\bnd\bd-\b-g\bge\bet\bt-\b-n\bne\bex\bxt\bt (\b(C\bC-\b-o\bo)\b) |
3751 | Accept the current line for execution and fetch the next line | |
3752 | relative to the current line from the history for editing. A | |
3753 | numeric argument, if supplied, specifies the history entry to | |
3754 | use instead of the current line. | |
3755 | f\bfe\bet\btc\bch\bh-\b-h\bhi\bis\bst\bto\bor\bry\by | |
3756 | With a numeric argument, fetch that entry from the history list | |
3757 | and make it the current line. Without an argument, move back to | |
3758 | the first entry in the history list. | |
17345e5a | 3759 | r\bre\bev\bve\ber\brs\bse\be-\b-s\bse\bea\bar\brc\bch\bh-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(C\bC-\b-r\br)\b) |
8868edaf CR |
3760 | Search backward starting at the current line and moving `up' |
3761 | through the history as necessary. This is an incremental | |
17345e5a JA |
3762 | search. |
3763 | f\bfo\bor\brw\bwa\bar\brd\bd-\b-s\bse\bea\bar\brc\bch\bh-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(C\bC-\b-s\bs)\b) | |
8868edaf CR |
3764 | Search forward starting at the current line and moving `down' |
3765 | through the history as necessary. This is an incremental | |
17345e5a JA |
3766 | search. |
3767 | n\bno\bon\bn-\b-i\bin\bnc\bcr\bre\bem\bme\ben\bnt\bta\bal\bl-\b-r\bre\bev\bve\ber\brs\bse\be-\b-s\bse\bea\bar\brc\bch\bh-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(M\bM-\b-p\bp)\b) | |
3768 | Search backward through the history starting at the current line | |
8868edaf | 3769 | using a non-incremental search for a string supplied by the |
17345e5a JA |
3770 | user. |
3771 | n\bno\bon\bn-\b-i\bin\bnc\bcr\bre\bem\bme\ben\bnt\bta\bal\bl-\b-f\bfo\bor\brw\bwa\bar\brd\bd-\b-s\bse\bea\bar\brc\bch\bh-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(M\bM-\b-n\bn)\b) | |
8868edaf | 3772 | Search forward through the history using a non-incremental |
17345e5a JA |
3773 | search for a string supplied by the user. |
3774 | h\bhi\bis\bst\bto\bor\bry\by-\b-s\bse\bea\bar\brc\bch\bh-\b-f\bfo\bor\brw\bwa\bar\brd\bd | |
8868edaf CR |
3775 | Search forward through the history for the string of characters |
3776 | between the start of the current line and the point. This is a | |
17345e5a JA |
3777 | non-incremental search. |
3778 | h\bhi\bis\bst\bto\bor\bry\by-\b-s\bse\bea\bar\brc\bch\bh-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd | |
3779 | Search backward through the history for the string of characters | |
8868edaf | 3780 | between the start of the current line and the point. This is a |
17345e5a | 3781 | non-incremental search. |
d233b485 CR |
3782 | h\bhi\bis\bst\bto\bor\bry\by-\b-s\bsu\bub\bbs\bst\btr\bri\bin\bng\bg-\b-s\bse\bea\bar\brc\bch\bh-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd |
3783 | Search backward through the history for the string of characters | |
8868edaf CR |
3784 | between the start of the current line and the current cursor po- |
3785 | sition (the _\bp_\bo_\bi_\bn_\bt). The search string may match anywhere in a | |
d233b485 CR |
3786 | history line. This is a non-incremental search. |
3787 | h\bhi\bis\bst\bto\bor\bry\by-\b-s\bsu\bub\bbs\bst\btr\bri\bin\bng\bg-\b-s\bse\bea\bar\brc\bch\bh-\b-f\bfo\bor\brw\bwa\bar\brd\bd | |
8868edaf | 3788 | Search forward through the history for the string of characters |
d233b485 | 3789 | between the start of the current line and the point. The search |
8868edaf CR |
3790 | string may match anywhere in a history line. This is a non-in- |
3791 | cremental search. | |
17345e5a | 3792 | y\bya\ban\bnk\bk-\b-n\bnt\bth\bh-\b-a\bar\brg\bg (\b(M\bM-\b-C\bC-\b-y\by)\b) |
8868edaf | 3793 | Insert the first argument to the previous command (usually the |
17345e5a | 3794 | second word on the previous line) at point. With an argument _\bn, |
8868edaf CR |
3795 | insert the _\bnth word from the previous command (the words in the |
3796 | previous command begin with word 0). A negative argument in- | |
3797 | serts the _\bnth word from the end of the previous command. Once | |
3798 | the argument _\bn is computed, the argument is extracted as if the | |
17345e5a JA |
3799 | "!_\bn" history expansion had been specified. |
3800 | y\bya\ban\bnk\bk-\b-l\bla\bas\bst\bt-\b-a\bar\brg\bg (\b(M\bM-\b-.\b.,\b, M\bM-\b-_\b_)\b) | |
8868edaf | 3801 | Insert the last argument to the previous command (the last word |
495aee44 | 3802 | of the previous history entry). With a numeric argument, behave |
8868edaf CR |
3803 | exactly like y\bya\ban\bnk\bk-\b-n\bnt\bth\bh-\b-a\bar\brg\bg. Successive calls to y\bya\ban\bnk\bk-\b-l\bla\bas\bst\bt-\b-a\bar\brg\bg |
3804 | move back through the history list, inserting the last word (or | |
3805 | the word specified by the argument to the first call) of each | |
495aee44 | 3806 | line in turn. Any numeric argument supplied to these successive |
8868edaf CR |
3807 | calls determines the direction to move through the history. A |
3808 | negative argument switches the direction through the history | |
495aee44 | 3809 | (back or forward). The history expansion facilities are used to |
ac50fbac CR |
3810 | extract the last word, as if the "!$" history expansion had been |
3811 | specified. | |
17345e5a JA |
3812 | s\bsh\bhe\bel\bll\bl-\b-e\bex\bxp\bpa\ban\bnd\bd-\b-l\bli\bin\bne\be (\b(M\bM-\b-C\bC-\b-e\be)\b) |
3813 | Expand the line as the shell does. This performs alias and his- | |
3814 | tory expansion as well as all of the shell word expansions. See | |
a0c0a00f | 3815 | H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN below for a description of history expansion. |
17345e5a | 3816 | h\bhi\bis\bst\bto\bor\bry\by-\b-e\bex\bxp\bpa\ban\bnd\bd-\b-l\bli\bin\bne\be (\b(M\bM-\b-^\b^)\b) |
8868edaf CR |
3817 | Perform history expansion on the current line. See H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bX-\b- |
3818 | P\bPA\bAN\bNS\bSI\bIO\bON\bN below for a description of history expansion. | |
17345e5a | 3819 | m\bma\bag\bgi\bic\bc-\b-s\bsp\bpa\bac\bce\be |
8868edaf | 3820 | Perform history expansion on the current line and insert a |
17345e5a JA |
3821 | space. See H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN below for a description of history |
3822 | expansion. | |
3823 | a\bal\bli\bia\bas\bs-\b-e\bex\bxp\bpa\ban\bnd\bd-\b-l\bli\bin\bne\be | |
8868edaf | 3824 | Perform alias expansion on the current line. See A\bAL\bLI\bIA\bAS\bSE\bES\bS above |
17345e5a JA |
3825 | for a description of alias expansion. |
3826 | h\bhi\bis\bst\bto\bor\bry\by-\b-a\ban\bnd\bd-\b-a\bal\bli\bia\bas\bs-\b-e\bex\bxp\bpa\ban\bnd\bd-\b-l\bli\bin\bne\be | |
3827 | Perform history and alias expansion on the current line. | |
3828 | i\bin\bns\bse\ber\brt\bt-\b-l\bla\bas\bst\bt-\b-a\bar\brg\bgu\bum\bme\ben\bnt\bt (\b(M\bM-\b-.\b.,\b, M\bM-\b-_\b_)\b) | |
3829 | A synonym for y\bya\ban\bnk\bk-\b-l\bla\bas\bst\bt-\b-a\bar\brg\bg. | |
d233b485 | 3830 | e\bed\bdi\bit\bt-\b-a\ban\bnd\bd-\b-e\bex\bxe\bec\bcu\but\bte\be-\b-c\bco\bom\bmm\bma\ban\bnd\bd (\b(C\bC-\b-x\bx C\bC-\b-e\be)\b) |
74091dd4 | 3831 | Invoke an editor on the current command line, and execute the |
8868edaf CR |
3832 | result as shell commands. B\bBa\bas\bsh\bh attempts to invoke $\b$V\bVI\bIS\bSU\bUA\bAL\bL, $\b$E\bED\bD-\b- |
3833 | I\bIT\bTO\bOR\bR, and _\be_\bm_\ba_\bc_\bs as the editor, in that order. | |
17345e5a JA |
3834 | |
3835 | C\bCo\bom\bmm\bma\ban\bnd\bds\bs f\bfo\bor\br C\bCh\bha\ban\bng\bgi\bin\bng\bg T\bTe\bex\bxt\bt | |
ac50fbac | 3836 | _\be_\bn_\bd_\b-_\bo_\bf_\b-_\bf_\bi_\bl_\be (\b(u\bus\bsu\bua\bal\bll\bly\by C\bC-\b-d\bd)\b) |
74091dd4 CR |
3837 | The character indicating end-of-file as set, for example, by |
3838 | ``stty''. If this character is read when there are no charac- | |
3839 | ters on the line, and point is at the beginning of the line, | |
3840 | readline interprets it as the end of input and returns E\bEO\bOF\bF. | |
17345e5a | 3841 | d\bde\bel\ble\bet\bte\be-\b-c\bch\bha\bar\br (\b(C\bC-\b-d\bd)\b) |
ac50fbac CR |
3842 | Delete the character at point. If this function is bound to the |
3843 | same character as the tty E\bEO\bOF\bF character, as C\bC-\b-d\bd commonly is, see | |
3844 | above for the effects. | |
17345e5a | 3845 | b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-d\bde\bel\ble\bet\bte\be-\b-c\bch\bha\bar\br (\b(R\bRu\bub\bbo\bou\but\bt)\b) |
74091dd4 | 3846 | Delete the character behind the cursor. When given a numeric |
17345e5a JA |
3847 | argument, save the deleted text on the kill ring. |
3848 | f\bfo\bor\brw\bwa\bar\brd\bd-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-d\bde\bel\ble\bet\bte\be-\b-c\bch\bha\bar\br | |
74091dd4 | 3849 | Delete the character under the cursor, unless the cursor is at |
17345e5a JA |
3850 | the end of the line, in which case the character behind the cur- |
3851 | sor is deleted. | |
3852 | q\bqu\buo\bot\bte\bed\bd-\b-i\bin\bns\bse\ber\brt\bt (\b(C\bC-\b-q\bq,\b, C\bC-\b-v\bv)\b) | |
74091dd4 | 3853 | Add the next character typed to the line verbatim. This is how |
17345e5a JA |
3854 | to insert characters like C\bC-\b-q\bq, for example. |
3855 | t\bta\bab\bb-\b-i\bin\bns\bse\ber\brt\bt (\b(C\bC-\b-v\bv T\bTA\bAB\bB)\b) | |
3856 | Insert a tab character. | |
3857 | s\bse\bel\blf\bf-\b-i\bin\bns\bse\ber\brt\bt (\b(a\ba,\b, b\bb,\b, A\bA,\b, 1\b1,\b, !\b!,\b, .\b..\b..\b.)\b) | |
3858 | Insert the character typed. | |
3859 | t\btr\bra\ban\bns\bsp\bpo\bos\bse\be-\b-c\bch\bha\bar\brs\bs (\b(C\bC-\b-t\bt)\b) | |
74091dd4 CR |
3860 | Drag the character before point forward over the character at |
3861 | point, moving point forward as well. If point is at the end of | |
3862 | the line, then this transposes the two characters before point. | |
17345e5a JA |
3863 | Negative arguments have no effect. |
3864 | t\btr\bra\ban\bns\bsp\bpo\bos\bse\be-\b-w\bwo\bor\brd\bds\bs (\b(M\bM-\b-t\bt)\b) | |
74091dd4 CR |
3865 | Drag the word before point past the word after point, moving |
3866 | point over that word as well. If point is at the end of the | |
17345e5a JA |
3867 | line, this transposes the last two words on the line. |
3868 | u\bup\bpc\bca\bas\bse\be-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-u\bu)\b) | |
74091dd4 | 3869 | Uppercase the current (or following) word. With a negative ar- |
8868edaf | 3870 | gument, uppercase the previous word, but do not move point. |
17345e5a | 3871 | d\bdo\bow\bwn\bnc\bca\bas\bse\be-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-l\bl)\b) |
74091dd4 | 3872 | Lowercase the current (or following) word. With a negative ar- |
8868edaf | 3873 | gument, lowercase the previous word, but do not move point. |
17345e5a | 3874 | c\bca\bap\bpi\bit\bta\bal\bli\biz\bze\be-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-c\bc)\b) |
8868edaf CR |
3875 | Capitalize the current (or following) word. With a negative ar- |
3876 | gument, capitalize the previous word, but do not move point. | |
17345e5a | 3877 | o\bov\bve\ber\brw\bwr\bri\bit\bte\be-\b-m\bmo\bod\bde\be |
74091dd4 | 3878 | Toggle overwrite mode. With an explicit positive numeric argu- |
17345e5a JA |
3879 | ment, switches to overwrite mode. With an explicit non-positive |
3880 | numeric argument, switches to insert mode. This command affects | |
74091dd4 | 3881 | only e\bem\bma\bac\bcs\bs mode; v\bvi\bi mode does overwrite differently. Each call |
17345e5a | 3882 | to _\br_\be_\ba_\bd_\bl_\bi_\bn_\be_\b(_\b) starts in insert mode. In overwrite mode, charac- |
74091dd4 CR |
3883 | ters bound to s\bse\bel\blf\bf-\b-i\bin\bns\bse\ber\brt\bt replace the text at point rather than |
3884 | pushing the text to the right. Characters bound to b\bba\bac\bck\bk-\b- | |
3885 | w\bwa\bar\brd\bd-\b-d\bde\bel\ble\bet\bte\be-\b-c\bch\bha\bar\br replace the character before point with a | |
17345e5a JA |
3886 | space. By default, this command is unbound. |
3887 | ||
3888 | K\bKi\bil\bll\bli\bin\bng\bg a\ban\bnd\bd Y\bYa\ban\bnk\bki\bin\bng\bg | |
3889 | k\bki\bil\bll\bl-\b-l\bli\bin\bne\be (\b(C\bC-\b-k\bk)\b) | |
3890 | Kill the text from point to the end of the line. | |
3891 | b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-k\bki\bil\bll\bl-\b-l\bli\bin\bne\be (\b(C\bC-\b-x\bx R\bRu\bub\bbo\bou\but\bt)\b) | |
3892 | Kill backward to the beginning of the line. | |
3893 | u\bun\bni\bix\bx-\b-l\bli\bin\bne\be-\b-d\bdi\bis\bsc\bca\bar\brd\bd (\b(C\bC-\b-u\bu)\b) | |
74091dd4 | 3894 | Kill backward from point to the beginning of the line. The |
17345e5a JA |
3895 | killed text is saved on the kill-ring. |
3896 | k\bki\bil\bll\bl-\b-w\bwh\bho\bol\ble\be-\b-l\bli\bin\bne\be | |
74091dd4 | 3897 | Kill all characters on the current line, no matter where point |
17345e5a JA |
3898 | is. |
3899 | k\bki\bil\bll\bl-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-d\bd)\b) | |
74091dd4 CR |
3900 | Kill from point to the end of the current word, or if between |
3901 | words, to the end of the next word. Word boundaries are the | |
17345e5a JA |
3902 | same as those used by f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
3903 | b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-k\bki\bil\bll\bl-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-R\bRu\bub\bbo\bou\but\bt)\b) | |
74091dd4 | 3904 | Kill the word behind point. Word boundaries are the same as |
17345e5a | 3905 | those used by b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
a0c0a00f | 3906 | s\bsh\bhe\bel\bll\bl-\b-k\bki\bil\bll\bl-\b-w\bwo\bor\brd\bd |
74091dd4 CR |
3907 | Kill from point to the end of the current word, or if between |
3908 | words, to the end of the next word. Word boundaries are the | |
17345e5a | 3909 | same as those used by s\bsh\bhe\bel\bll\bl-\b-f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
a0c0a00f | 3910 | s\bsh\bhe\bel\bll\bl-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-k\bki\bil\bll\bl-\b-w\bwo\bor\brd\bd |
74091dd4 | 3911 | Kill the word behind point. Word boundaries are the same as |
17345e5a JA |
3912 | those used by s\bsh\bhe\bel\bll\bl-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
3913 | u\bun\bni\bix\bx-\b-w\bwo\bor\brd\bd-\b-r\bru\bub\bbo\bou\but\bt (\b(C\bC-\b-w\bw)\b) | |
74091dd4 | 3914 | Kill the word behind point, using white space as a word bound- |
17345e5a JA |
3915 | ary. The killed text is saved on the kill-ring. |
3916 | u\bun\bni\bix\bx-\b-f\bfi\bil\ble\ben\bna\bam\bme\be-\b-r\bru\bub\bbo\bou\but\bt | |
74091dd4 CR |
3917 | Kill the word behind point, using white space and the slash |
3918 | character as the word boundaries. The killed text is saved on | |
17345e5a JA |
3919 | the kill-ring. |
3920 | d\bde\bel\ble\bet\bte\be-\b-h\bho\bor\bri\biz\bzo\bon\bnt\bta\bal\bl-\b-s\bsp\bpa\bac\bce\be (\b(M\bM-\b-\\b\)\b) | |
3921 | Delete all spaces and tabs around point. | |
3922 | k\bki\bil\bll\bl-\b-r\bre\beg\bgi\bio\bon\bn | |
3923 | Kill the text in the current region. | |
3924 | c\bco\bop\bpy\by-\b-r\bre\beg\bgi\bio\bon\bn-\b-a\bas\bs-\b-k\bki\bil\bll\bl | |
3925 | Copy the text in the region to the kill buffer. | |
3926 | c\bco\bop\bpy\by-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd | |
74091dd4 | 3927 | Copy the word before point to the kill buffer. The word bound- |
17345e5a JA |
3928 | aries are the same as b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
3929 | c\bco\bop\bpy\by-\b-f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd | |
74091dd4 | 3930 | Copy the word following point to the kill buffer. The word |
17345e5a JA |
3931 | boundaries are the same as f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
3932 | y\bya\ban\bnk\bk (\b(C\bC-\b-y\by)\b) | |
3933 | Yank the top of the kill ring into the buffer at point. | |
3934 | y\bya\ban\bnk\bk-\b-p\bpo\bop\bp (\b(M\bM-\b-y\by)\b) | |
74091dd4 | 3935 | Rotate the kill ring, and yank the new top. Only works follow- |
17345e5a JA |
3936 | ing y\bya\ban\bnk\bk or y\bya\ban\bnk\bk-\b-p\bpo\bop\bp. |
3937 | ||
3938 | N\bNu\bum\bme\ber\bri\bic\bc A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
3939 | d\bdi\big\bgi\bit\bt-\b-a\bar\brg\bgu\bum\bme\ben\bnt\bt (\b(M\bM-\b-0\b0,\b, M\bM-\b-1\b1,\b, .\b..\b..\b.,\b, M\bM-\b--\b-)\b) | |
74091dd4 | 3940 | Add this digit to the argument already accumulating, or start a |
17345e5a JA |
3941 | new argument. M-- starts a negative argument. |
3942 | u\bun\bni\biv\bve\ber\brs\bsa\bal\bl-\b-a\bar\brg\bgu\bum\bme\ben\bnt\bt | |
74091dd4 CR |
3943 | This is another way to specify an argument. If this command is |
3944 | followed by one or more digits, optionally with a leading minus | |
3945 | sign, those digits define the argument. If the command is fol- | |
8868edaf CR |
3946 | lowed by digits, executing u\bun\bni\biv\bve\ber\brs\bsa\bal\bl-\b-a\bar\brg\bgu\bum\bme\ben\bnt\bt again ends the nu- |
3947 | meric argument, but is otherwise ignored. As a special case, if | |
3948 | this command is immediately followed by a character that is nei- | |
74091dd4 CR |
3949 | ther a digit nor minus sign, the argument count for the next |
3950 | command is multiplied by four. The argument count is initially | |
3951 | one, so executing this function the first time makes the argu- | |
17345e5a JA |
3952 | ment count four, a second time makes the argument count sixteen, |
3953 | and so on. | |
3954 | ||
3955 | C\bCo\bom\bmp\bpl\ble\bet\bti\bin\bng\bg | |
3956 | c\bco\bom\bmp\bpl\ble\bet\bte\be (\b(T\bTA\bAB\bB)\b) | |
74091dd4 | 3957 | Attempt to perform completion on the text before point. B\bBa\bas\bsh\bh |
17345e5a | 3958 | attempts completion treating the text as a variable (if the text |
74091dd4 CR |
3959 | begins with $\b$), username (if the text begins with ~\b~), hostname |
3960 | (if the text begins with @\b@), or command (including aliases and | |
17345e5a JA |
3961 | functions) in turn. If none of these produces a match, filename |
3962 | completion is attempted. | |
3963 | p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(M\bM-\b-?\b?)\b) | |
3964 | List the possible completions of the text before point. | |
3965 | i\bin\bns\bse\ber\brt\bt-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(M\bM-\b-*\b*)\b) | |
74091dd4 | 3966 | Insert all completions of the text before point that would have |
17345e5a JA |
3967 | been generated by p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs. |
3968 | m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be | |
74091dd4 CR |
3969 | Similar to c\bco\bom\bmp\bpl\ble\bet\bte\be, but replaces the word to be completed with |
3970 | a single match from the list of possible completions. Repeated | |
3971 | execution of m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be steps through the list of possible | |
3972 | completions, inserting each match in turn. At the end of the | |
17345e5a JA |
3973 | list of completions, the bell is rung (subject to the setting of |
3974 | b\bbe\bel\bll\bl-\b-s\bst\bty\byl\ble\be) and the original text is restored. An argument of _\bn | |
8868edaf CR |
3975 | moves _\bn positions forward in the list of matches; a negative ar- |
3976 | gument may be used to move backward through the list. This com- | |
3977 | mand is intended to be bound to T\bTA\bAB\bB, but is unbound by default. | |
495aee44 | 3978 | m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd |
74091dd4 CR |
3979 | Identical to m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be, but moves backward through the list |
3980 | of possible completions, as if m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be had been given a | |
0001803f | 3981 | negative argument. This command is unbound by default. |
17345e5a | 3982 | d\bde\bel\ble\bet\bte\be-\b-c\bch\bha\bar\br-\b-o\bor\br-\b-l\bli\bis\bst\bt |
74091dd4 CR |
3983 | Deletes the character under the cursor if not at the beginning |
3984 | or end of the line (like d\bde\bel\ble\bet\bte\be-\b-c\bch\bha\bar\br). If at the end of the | |
17345e5a JA |
3985 | line, behaves identically to p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs. This command |
3986 | is unbound by default. | |
3987 | c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-f\bfi\bil\ble\ben\bna\bam\bme\be (\b(M\bM-\b-/\b/)\b) | |
3988 | Attempt filename completion on the text before point. | |
3989 | p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-f\bfi\bil\ble\ben\bna\bam\bme\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(C\bC-\b-x\bx /\b/)\b) | |
3990 | List the possible completions of the text before point, treating | |
3991 | it as a filename. | |
3992 | c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-u\bus\bse\ber\brn\bna\bam\bme\be (\b(M\bM-\b-~\b~)\b) | |
74091dd4 | 3993 | Attempt completion on the text before point, treating it as a |
17345e5a JA |
3994 | username. |
3995 | p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-u\bus\bse\ber\brn\bna\bam\bme\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(C\bC-\b-x\bx ~\b~)\b) | |
3996 | List the possible completions of the text before point, treating | |
3997 | it as a username. | |
3998 | c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-v\bva\bar\bri\bia\bab\bbl\ble\be (\b(M\bM-\b-$\b$)\b) | |
74091dd4 | 3999 | Attempt completion on the text before point, treating it as a |
17345e5a JA |
4000 | shell variable. |
4001 | p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-v\bva\bar\bri\bia\bab\bbl\ble\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(C\bC-\b-x\bx $\b$)\b) | |
4002 | List the possible completions of the text before point, treating | |
4003 | it as a shell variable. | |
4004 | c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-h\bho\bos\bst\btn\bna\bam\bme\be (\b(M\bM-\b-@\b@)\b) | |
74091dd4 | 4005 | Attempt completion on the text before point, treating it as a |
17345e5a JA |
4006 | hostname. |
4007 | p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-h\bho\bos\bst\btn\bna\bam\bme\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(C\bC-\b-x\bx @\b@)\b) | |
4008 | List the possible completions of the text before point, treating | |
4009 | it as a hostname. | |
4010 | c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-c\bco\bom\bmm\bma\ban\bnd\bd (\b(M\bM-\b-!\b!)\b) | |
74091dd4 CR |
4011 | Attempt completion on the text before point, treating it as a |
4012 | command name. Command completion attempts to match the text | |
4013 | against aliases, reserved words, shell functions, shell | |
17345e5a JA |
4014 | builtins, and finally executable filenames, in that order. |
4015 | p\bpo\bos\bss\bsi\bib\bbl\ble\be-\b-c\bco\bom\bmm\bma\ban\bnd\bd-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(C\bC-\b-x\bx !\b!)\b) | |
4016 | List the possible completions of the text before point, treating | |
4017 | it as a command name. | |
4018 | d\bdy\byn\bna\bam\bmi\bic\bc-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(M\bM-\b-T\bTA\bAB\bB)\b) | |
74091dd4 CR |
4019 | Attempt completion on the text before point, comparing the text |
4020 | against lines from the history list for possible completion | |
17345e5a JA |
4021 | matches. |
4022 | d\bda\bab\bbb\bbr\bre\bev\bv-\b-e\bex\bxp\bpa\ban\bnd\bd | |
74091dd4 | 4023 | Attempt menu completion on the text before point, comparing the |
17345e5a JA |
4024 | text against lines from the history list for possible completion |
4025 | matches. | |
4026 | c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-i\bin\bnt\bto\bo-\b-b\bbr\bra\bac\bce\bes\bs (\b(M\bM-\b-{\b{)\b) | |
4027 | Perform filename completion and insert the list of possible com- | |
74091dd4 | 4028 | pletions enclosed within braces so the list is available to the |
17345e5a JA |
4029 | shell (see B\bBr\bra\bac\bce\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn above). |
4030 | ||
4031 | K\bKe\bey\byb\bbo\boa\bar\brd\bd M\bMa\bac\bcr\bro\bos\bs | |
4032 | s\bst\bta\bar\brt\bt-\b-k\bkb\bbd\bd-\b-m\bma\bac\bcr\bro\bo (\b(C\bC-\b-x\bx (\b()\b) | |
74091dd4 | 4033 | Begin saving the characters typed into the current keyboard |
17345e5a JA |
4034 | macro. |
4035 | e\ben\bnd\bd-\b-k\bkb\bbd\bd-\b-m\bma\bac\bcr\bro\bo (\b(C\bC-\b-x\bx )\b))\b) | |
4036 | Stop saving the characters typed into the current keyboard macro | |
4037 | and store the definition. | |
4038 | c\bca\bal\bll\bl-\b-l\bla\bas\bst\bt-\b-k\bkb\bbd\bd-\b-m\bma\bac\bcr\bro\bo (\b(C\bC-\b-x\bx e\be)\b) | |
74091dd4 | 4039 | Re-execute the last keyboard macro defined, by making the char- |
17345e5a | 4040 | acters in the macro appear as if typed at the keyboard. |
ac50fbac | 4041 | p\bpr\bri\bin\bnt\bt-\b-l\bla\bas\bst\bt-\b-k\bkb\bbd\bd-\b-m\bma\bac\bcr\bro\bo (\b()\b) |
74091dd4 | 4042 | Print the last keyboard macro defined in a format suitable for |
ac50fbac | 4043 | the _\bi_\bn_\bp_\bu_\bt_\br_\bc file. |
17345e5a JA |
4044 | |
4045 | M\bMi\bis\bsc\bce\bel\bll\bla\ban\bne\beo\bou\bus\bs | |
4046 | r\bre\be-\b-r\bre\bea\bad\bd-\b-i\bin\bni\bit\bt-\b-f\bfi\bil\ble\be (\b(C\bC-\b-x\bx C\bC-\b-r\br)\b) | |
74091dd4 | 4047 | Read in the contents of the _\bi_\bn_\bp_\bu_\bt_\br_\bc file, and incorporate any |
17345e5a JA |
4048 | bindings or variable assignments found there. |
4049 | a\bab\bbo\bor\brt\bt (\b(C\bC-\b-g\bg)\b) | |
74091dd4 | 4050 | Abort the current editing command and ring the terminal's bell |
17345e5a | 4051 | (subject to the setting of b\bbe\bel\bll\bl-\b-s\bst\bty\byl\ble\be). |
d233b485 | 4052 | d\bdo\bo-\b-l\blo\bow\bwe\ber\brc\bca\bas\bse\be-\b-v\bve\ber\brs\bsi\bio\bon\bn (\b(M\bM-\b-A\bA,\b, M\bM-\b-B\bB,\b, M\bM-\b-_\bx,\b, .\b..\b..\b.)\b) |
74091dd4 | 4053 | If the metafied character _\bx is uppercase, run the command that |
d233b485 CR |
4054 | is bound to the corresponding metafied lowercase character. The |
4055 | behavior is undefined if _\bx is already lowercase. | |
17345e5a JA |
4056 | p\bpr\bre\bef\bfi\bix\bx-\b-m\bme\bet\bta\ba (\b(E\bES\bSC\bC)\b) |
4057 | Metafy the next character typed. E\bES\bSC\bC f\bf is equivalent to M\bMe\bet\bta\ba-\b-f\bf. | |
4058 | u\bun\bnd\bdo\bo (\b(C\bC-\b-_\b_,\b, C\bC-\b-x\bx C\bC-\b-u\bu)\b) | |
4059 | Incremental undo, separately remembered for each line. | |
4060 | r\bre\bev\bve\ber\brt\bt-\b-l\bli\bin\bne\be (\b(M\bM-\b-r\br)\b) | |
74091dd4 CR |
4061 | Undo all changes made to this line. This is like executing the |
4062 | u\bun\bnd\bdo\bo command enough times to return the line to its initial | |
17345e5a JA |
4063 | state. |
4064 | t\bti\bil\bld\bde\be-\b-e\bex\bxp\bpa\ban\bnd\bd (\b(M\bM-\b-&\b&)\b) | |
4065 | Perform tilde expansion on the current word. | |
4066 | s\bse\bet\bt-\b-m\bma\bar\brk\bk (\b(C\bC-\b-@\b@,\b, M\bM-\b-<\b<s\bsp\bpa\bac\bce\be>\b>)\b) | |
74091dd4 | 4067 | Set the mark to the point. If a numeric argument is supplied, |
17345e5a JA |
4068 | the mark is set to that position. |
4069 | e\bex\bxc\bch\bha\ban\bng\bge\be-\b-p\bpo\boi\bin\bnt\bt-\b-a\ban\bnd\bd-\b-m\bma\bar\brk\bk (\b(C\bC-\b-x\bx C\bC-\b-x\bx)\b) | |
74091dd4 CR |
4070 | Swap the point with the mark. The current cursor position is |
4071 | set to the saved position, and the old cursor position is saved | |
17345e5a JA |
4072 | as the mark. |
4073 | c\bch\bha\bar\bra\bac\bct\bte\ber\br-\b-s\bse\bea\bar\brc\bch\bh (\b(C\bC-\b-]\b])\b) | |
4074 | A character is read and point is moved to the next occurrence of | |
74091dd4 CR |
4075 | that character. A negative argument searches for previous oc- |
4076 | currences. | |
17345e5a | 4077 | c\bch\bha\bar\bra\bac\bct\bte\ber\br-\b-s\bse\bea\bar\brc\bch\bh-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd (\b(M\bM-\b-C\bC-\b-]\b])\b) |
74091dd4 CR |
4078 | A character is read and point is moved to the previous occur- |
4079 | rence of that character. A negative argument searches for sub- | |
4080 | sequent occurrences. | |
495aee44 | 4081 | s\bsk\bki\bip\bp-\b-c\bcs\bsi\bi-\b-s\bse\beq\bqu\bue\ben\bnc\bce\be |
74091dd4 CR |
4082 | Read enough characters to consume a multi-key sequence such as |
4083 | those defined for keys like Home and End. Such sequences begin | |
0001803f | 4084 | with a Control Sequence Indicator (CSI), usually ESC-[. If this |
74091dd4 CR |
4085 | sequence is bound to "\[", keys producing such sequences will |
4086 | have no effect unless explicitly bound to a readline command, | |
4087 | instead of inserting stray characters into the editing buffer. | |
0001803f | 4088 | This is unbound by default, but usually bound to ESC-[. |
17345e5a | 4089 | i\bin\bns\bse\ber\brt\bt-\b-c\bco\bom\bmm\bme\ben\bnt\bt (\b(M\bM-\b-#\b#)\b) |
74091dd4 CR |
4090 | Without a numeric argument, the value of the readline c\bco\bom\bm-\b- |
4091 | m\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn variable is inserted at the beginning of the current | |
17345e5a | 4092 | line. If a numeric argument is supplied, this command acts as a |
74091dd4 CR |
4093 | toggle: if the characters at the beginning of the line do not |
4094 | match the value of c\bco\bom\bmm\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn, the value is inserted, other- | |
17345e5a | 4095 | wise the characters in c\bco\bom\bmm\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn are deleted from the begin- |
74091dd4 CR |
4096 | ning of the line. In either case, the line is accepted as if a |
4097 | newline had been typed. The default value of c\bco\bom\bmm\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn | |
4098 | causes this command to make the current line a shell comment. | |
4099 | If a numeric argument causes the comment character to be re- | |
8868edaf | 4100 | moved, the line will be executed by the shell. |
74091dd4 CR |
4101 | s\bsp\bpe\bel\bll\bl-\b-c\bco\bor\brr\bre\bec\bct\bt-\b-w\bwo\bor\brd\bd (\b(C\bC-\b-x\bx s\bs)\b) |
4102 | Perform spelling correction on the current word, treating it as | |
4103 | a directory or filename, in the same way as the c\bcd\bds\bsp\bpe\bel\bll\bl shell | |
4104 | option. Word boundaries are the same as those used by | |
4105 | s\bsh\bhe\bel\bll\bl-\b-f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. | |
17345e5a | 4106 | g\bgl\blo\bob\bb-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-g\bg)\b) |
8868edaf CR |
4107 | The word before point is treated as a pattern for pathname ex- |
4108 | pansion, with an asterisk implicitly appended. This pattern is | |
4109 | used to generate a list of matching filenames for possible com- | |
4110 | pletions. | |
17345e5a | 4111 | g\bgl\blo\bob\bb-\b-e\bex\bxp\bpa\ban\bnd\bd-\b-w\bwo\bor\brd\bd (\b(C\bC-\b-x\bx *\b*)\b) |
8868edaf CR |
4112 | The word before point is treated as a pattern for pathname ex- |
4113 | pansion, and the list of matching filenames is inserted, replac- | |
4114 | ing the word. If a numeric argument is supplied, an asterisk is | |
4115 | appended before pathname expansion. | |
17345e5a | 4116 | g\bgl\blo\bob\bb-\b-l\bli\bis\bst\bt-\b-e\bex\bxp\bpa\ban\bns\bsi\bio\bon\bns\bs (\b(C\bC-\b-x\bx g\bg)\b) |
d233b485 CR |
4117 | The list of expansions that would have been generated by |
4118 | g\bgl\blo\bob\bb-\b-e\bex\bxp\bpa\ban\bnd\bd-\b-w\bwo\bor\brd\bd is displayed, and the line is redrawn. If a | |
4119 | numeric argument is supplied, an asterisk is appended before | |
17345e5a JA |
4120 | pathname expansion. |
4121 | d\bdu\bum\bmp\bp-\b-f\bfu\bun\bnc\bct\bti\bio\bon\bns\bs | |
d233b485 | 4122 | Print all of the functions and their key bindings to the read- |
17345e5a | 4123 | line output stream. If a numeric argument is supplied, the out- |
d233b485 | 4124 | put is formatted in such a way that it can be made part of an |
17345e5a JA |
4125 | _\bi_\bn_\bp_\bu_\bt_\br_\bc file. |
4126 | d\bdu\bum\bmp\bp-\b-v\bva\bar\bri\bia\bab\bbl\ble\bes\bs | |
4127 | Print all of the settable readline variables and their values to | |
d233b485 CR |
4128 | the readline output stream. If a numeric argument is supplied, |
4129 | the output is formatted in such a way that it can be made part | |
17345e5a JA |
4130 | of an _\bi_\bn_\bp_\bu_\bt_\br_\bc file. |
4131 | d\bdu\bum\bmp\bp-\b-m\bma\bac\bcr\bro\bos\bs | |
d233b485 CR |
4132 | Print all of the readline key sequences bound to macros and the |
4133 | strings they output. If a numeric argument is supplied, the | |
17345e5a JA |
4134 | output is formatted in such a way that it can be made part of an |
4135 | _\bi_\bn_\bp_\bu_\bt_\br_\bc file. | |
4136 | d\bdi\bis\bsp\bpl\bla\bay\by-\b-s\bsh\bhe\bel\bll\bl-\b-v\bve\ber\brs\bsi\bio\bon\bn (\b(C\bC-\b-x\bx C\bC-\b-v\bv)\b) | |
a0c0a00f | 4137 | Display version information about the current instance of b\bba\bas\bsh\bh. |
17345e5a JA |
4138 | |
4139 | P\bPr\bro\bog\bgr\bra\bam\bmm\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn | |
d233b485 CR |
4140 | When word completion is attempted for an argument to a command for |
4141 | which a completion specification (a _\bc_\bo_\bm_\bp_\bs_\bp_\be_\bc) has been defined using | |
4142 | the c\bco\bom\bmp\bpl\ble\bet\bte\be builtin (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below), the program- | |
a0c0a00f | 4143 | mable completion facilities are invoked. |
17345e5a | 4144 | |
d233b485 CR |
4145 | First, the command name is identified. If the command word is the |
4146 | empty string (completion attempted at the beginning of an empty line), | |
4147 | any compspec defined with the -\b-E\bE option to c\bco\bom\bmp\bpl\ble\bet\bte\be is used. If a | |
4148 | compspec has been defined for that command, the compspec is used to | |
0001803f | 4149 | generate the list of possible completions for the word. If the command |
d233b485 CR |
4150 | word is a full pathname, a compspec for the full pathname is searched |
4151 | for first. If no compspec is found for the full pathname, an attempt | |
4152 | is made to find a compspec for the portion following the final slash. | |
4153 | If those searches do not result in a compspec, any compspec defined | |
4154 | with the -\b-D\bD option to c\bco\bom\bmp\bpl\ble\bet\bte\be is used as the default. If there is no | |
4155 | default compspec, b\bba\bas\bsh\bh attempts alias expansion on the command word as | |
4156 | a final resort, and attempts to find a compspec for the command word | |
4157 | from any successful expansion. | |
17345e5a | 4158 | |
ac50fbac CR |
4159 | Once a compspec has been found, it is used to generate the list of |
4160 | matching words. If a compspec is not found, the default b\bba\bas\bsh\bh comple- | |
17345e5a JA |
4161 | tion as described above under C\bCo\bom\bmp\bpl\ble\bet\bti\bin\bng\bg is performed. |
4162 | ||
ac50fbac CR |
4163 | First, the actions specified by the compspec are used. Only matches |
4164 | which are prefixed by the word being completed are returned. When the | |
4165 | -\b-f\bf or -\b-d\bd option is used for filename or directory name completion, the | |
17345e5a JA |
4166 | shell variable F\bFI\bIG\bGN\bNO\bOR\bRE\bE is used to filter the matches. |
4167 | ||
8868edaf CR |
4168 | Any completions specified by a pathname expansion pattern to the -\b-G\bG op- |
4169 | tion are generated next. The words generated by the pattern need not | |
ac50fbac | 4170 | match the word being completed. The G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE shell variable is not |
17345e5a JA |
4171 | used to filter the matches, but the F\bFI\bIG\bGN\bNO\bOR\bRE\bE variable is used. |
4172 | ||
ac50fbac CR |
4173 | Next, the string specified as the argument to the -\b-W\bW option is consid- |
4174 | ered. The string is first split using the characters in the I\bIF\bFS\bS spe- | |
4175 | cial variable as delimiters. Shell quoting is honored. Each word is | |
4176 | then expanded using brace expansion, tilde expansion, parameter and | |
4177 | variable expansion, command substitution, and arithmetic expansion, as | |
17345e5a JA |
4178 | described above under E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN. The results are split using the rules |
4179 | described above under W\bWo\bor\brd\bd S\bSp\bpl\bli\bit\btt\bti\bin\bng\bg. The results of the expansion are | |
4180 | prefix-matched against the word being completed, and the matching words | |
4181 | become the possible completions. | |
4182 | ||
ac50fbac CR |
4183 | After these matches have been generated, any shell function or command |
4184 | specified with the -\b-F\bF and -\b-C\bC options is invoked. When the command or | |
17345e5a JA |
4185 | function is invoked, the C\bCO\bOM\bMP\bP_\b_L\bLI\bIN\bNE\bE, C\bCO\bOM\bMP\bP_\b_P\bPO\bOI\bIN\bNT\bT, C\bCO\bOM\bMP\bP_\b_K\bKE\bEY\bY, and C\bCO\bOM\bMP\bP_\b_T\bTY\bYP\bPE\bE |
4186 | variables are assigned values as described above under S\bSh\bhe\bel\bll\bl V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs. | |
ac50fbac CR |
4187 | If a shell function is being invoked, the C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDS\bS and C\bCO\bOM\bMP\bP_\b_C\bCW\bWO\bOR\bRD\bD |
4188 | variables are also set. When the function or command is invoked, the | |
8868edaf CR |
4189 | first argument ($\b$1\b1) is the name of the command whose arguments are be- |
4190 | ing completed, the second argument ($\b$2\b2) is the word being completed, | |
ac50fbac CR |
4191 | and the third argument ($\b$3\b3) is the word preceding the word being com- |
4192 | pleted on the current command line. No filtering of the generated com- | |
4193 | pletions against the word being completed is performed; the function or | |
4194 | command has complete freedom in generating the matches. | |
4195 | ||
4196 | Any function specified with -\b-F\bF is invoked first. The function may use | |
4197 | any of the shell facilities, including the c\bco\bom\bmp\bpg\bge\ben\bn builtin described | |
4198 | below, to generate the matches. It must put the possible completions | |
4199 | in the C\bCO\bOM\bMP\bPR\bRE\bEP\bPL\bLY\bY array variable, one per array element. | |
4200 | ||
4201 | Next, any command specified with the -\b-C\bC option is invoked in an envi- | |
4202 | ronment equivalent to command substitution. It should print a list of | |
4203 | completions, one per line, to the standard output. Backslash may be | |
17345e5a JA |
4204 | used to escape a newline, if necessary. |
4205 | ||
ac50fbac CR |
4206 | After all of the possible completions are generated, any filter speci- |
4207 | fied with the -\b-X\bX option is applied to the list. The filter is a pat- | |
4208 | tern as used for pathname expansion; a &\b& in the pattern is replaced | |
4209 | with the text of the word being completed. A literal &\b& may be escaped | |
4210 | with a backslash; the backslash is removed before attempting a match. | |
4211 | Any completion that matches the pattern will be removed from the list. | |
17345e5a | 4212 | A leading !\b! negates the pattern; in this case any completion not match- |
a0c0a00f CR |
4213 | ing the pattern will be removed. If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh shell option is |
4214 | enabled, the match is performed without regard to the case of alpha- | |
4215 | betic characters. | |
17345e5a JA |
4216 | |
4217 | Finally, any prefix and suffix specified with the -\b-P\bP and -\b-S\bS options are | |
4218 | added to each member of the completion list, and the result is returned | |
4219 | to the readline completion code as the list of possible completions. | |
4220 | ||
ac50fbac | 4221 | If the previously-applied actions do not generate any matches, and the |
8868edaf CR |
4222 | -\b-o\bo d\bdi\bir\brn\bna\bam\bme\bes\bs option was supplied to c\bco\bom\bmp\bpl\ble\bet\bte\be when the compspec was de- |
4223 | fined, directory name completion is attempted. | |
17345e5a | 4224 | |
ac50fbac | 4225 | If the -\b-o\bo p\bpl\blu\bus\bsd\bdi\bir\brs\bs option was supplied to c\bco\bom\bmp\bpl\ble\bet\bte\be when the compspec |
17345e5a JA |
4226 | was defined, directory name completion is attempted and any matches are |
4227 | added to the results of the other actions. | |
4228 | ||
ac50fbac CR |
4229 | By default, if a compspec is found, whatever it generates is returned |
4230 | to the completion code as the full set of possible completions. The | |
17345e5a JA |
4231 | default b\bba\bas\bsh\bh completions are not attempted, and the readline default of |
4232 | filename completion is disabled. If the -\b-o\bo b\bba\bas\bsh\bhd\bde\bef\bfa\bau\bul\blt\bt option was sup- | |
ac50fbac | 4233 | plied to c\bco\bom\bmp\bpl\ble\bet\bte\be when the compspec was defined, the b\bba\bas\bsh\bh default com- |
17345e5a | 4234 | pletions are attempted if the compspec generates no matches. If the -\b-o\bo |
ac50fbac CR |
4235 | d\bde\bef\bfa\bau\bul\blt\bt option was supplied to c\bco\bom\bmp\bpl\ble\bet\bte\be when the compspec was defined, |
4236 | readline's default completion will be performed if the compspec (and, | |
17345e5a JA |
4237 | if attempted, the default b\bba\bas\bsh\bh completions) generate no matches. |
4238 | ||
ac50fbac CR |
4239 | When a compspec indicates that directory name completion is desired, |
4240 | the programmable completion functions force readline to append a slash | |
4241 | to completed names which are symbolic links to directories, subject to | |
4242 | the value of the m\bma\bar\brk\bk-\b-d\bdi\bir\bre\bec\bct\bto\bor\bri\bie\bes\bs readline variable, regardless of the | |
17345e5a JA |
4243 | setting of the m\bma\bar\brk\bk-\b-s\bsy\bym\bml\bli\bin\bnk\bke\bed\bd-\b-d\bdi\bir\bre\bec\bct\bto\bor\bri\bie\bes\bs readline variable. |
4244 | ||
ac50fbac CR |
4245 | There is some support for dynamically modifying completions. This is |
4246 | most useful when used in combination with a default completion speci- | |
4247 | fied with c\bco\bom\bmp\bpl\ble\bet\bte\be -\b-D\bD. It's possible for shell functions executed as | |
4248 | completion handlers to indicate that completion should be retried by | |
4249 | returning an exit status of 124. If a shell function returns 124, and | |
0001803f | 4250 | changes the compspec associated with the command on which completion is |
ac50fbac | 4251 | being attempted (supplied as the first argument when the function is |
0001803f | 4252 | executed), programmable completion restarts from the beginning, with an |
ac50fbac CR |
4253 | attempt to find a new compspec for that command. This allows a set of |
4254 | completions to be built dynamically as completion is attempted, rather | |
0001803f CR |
4255 | than being loaded all at once. |
4256 | ||
ac50fbac | 4257 | For instance, assuming that there is a library of compspecs, each kept |
8868edaf CR |
4258 | in a file corresponding to the name of the command, the following de- |
4259 | fault completion function would load completions dynamically: | |
0001803f CR |
4260 | |
4261 | _completion_loader() | |
4262 | { | |
4263 | . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 | |
4264 | } | |
ac50fbac | 4265 | complete -D -F _completion_loader -o bashdefault -o default |
0001803f CR |
4266 | |
4267 | ||
17345e5a | 4268 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
ac50fbac | 4269 | When the -\b-o\bo h\bhi\bis\bst\bto\bor\bry\by option to the s\bse\bet\bt builtin is enabled, the shell |
17345e5a | 4270 | provides access to the _\bc_\bo_\bm_\bm_\ba_\bn_\bd _\bh_\bi_\bs_\bt_\bo_\br_\by, the list of commands previously |
ac50fbac | 4271 | typed. The value of the H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE variable is used as the number of |
17345e5a | 4272 | commands to save in a history list. The text of the last H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE com- |
ac50fbac CR |
4273 | mands (default 500) is saved. The shell stores each command in the |
4274 | history list prior to parameter and variable expansion (see E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
4275 | above) but after history expansion is performed, subject to the values | |
17345e5a JA |
4276 | of the shell variables H\bHI\bIS\bST\bTI\bIG\bGN\bNO\bOR\bRE\bE and H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL. |
4277 | ||
4278 | On startup, the history is initialized from the file named by the vari- | |
ac50fbac CR |
4279 | able H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE (default _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bh_\bi_\bs_\bt_\bo_\br_\by). The file named by the value |
4280 | of H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE is truncated, if necessary, to contain no more than the | |
4281 | number of lines specified by the value of H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bES\bSI\bIZ\bZE\bE. If H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE-\b- | |
4282 | S\bSI\bIZ\bZE\bE is unset, or set to null, a non-numeric value, or a numeric value | |
4283 | less than zero, the history file is not truncated. When the history | |
4284 | file is read, lines beginning with the history comment character fol- | |
d233b485 CR |
4285 | lowed immediately by a digit are interpreted as timestamps for the fol- |
4286 | lowing history line. These timestamps are optionally displayed depend- | |
ac50fbac CR |
4287 | ing on the value of the H\bHI\bIS\bST\bTT\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT variable. When a shell with |
4288 | history enabled exits, the last $\b$H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE lines are copied from the | |
4289 | history list to $\b$H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE. If the h\bhi\bis\bst\bta\bap\bpp\bpe\ben\bnd\bd shell option is enabled | |
4290 | (see the description of s\bsh\bho\bop\bpt\bt under S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below), the | |
4291 | lines are appended to the history file, otherwise the history file is | |
8868edaf CR |
4292 | overwritten. If H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE is unset, or if the history file is un- |
4293 | writable, the history is not saved. If the H\bHI\bIS\bST\bTT\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT variable is | |
4294 | set, time stamps are written to the history file, marked with the his- | |
4295 | tory comment character, so they may be preserved across shell sessions. | |
4296 | This uses the history comment character to distinguish timestamps from | |
4297 | other history lines. After saving the history, the history file is | |
4298 | truncated to contain no more than H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bES\bSI\bIZ\bZE\bE lines. If H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bES\bSI\bIZ\bZE\bE | |
4299 | is unset, or set to null, a non-numeric value, or a numeric value less | |
4300 | than zero, the history file is not truncated. | |
17345e5a JA |
4301 | |
4302 | The builtin command f\bfc\bc (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below) may be used | |
4303 | to list or edit and re-execute a portion of the history list. The h\bhi\bis\bs-\b- | |
8868edaf CR |
4304 | t\bto\bor\bry\by builtin may be used to display or modify the history list and ma- |
4305 | nipulate the history file. When using command-line editing, search | |
17345e5a JA |
4306 | commands are available in each editing mode that provide access to the |
4307 | history list. | |
4308 | ||
4309 | The shell allows control over which commands are saved on the history | |
4310 | list. The H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL and H\bHI\bIS\bST\bTI\bIG\bGN\bNO\bOR\bRE\bE variables may be set to cause the | |
4311 | shell to save only a subset of the commands entered. The c\bcm\bmd\bdh\bhi\bis\bst\bt shell | |
4312 | option, if enabled, causes the shell to attempt to save each line of a | |
4313 | multi-line command in the same history entry, adding semicolons where | |
4314 | necessary to preserve syntactic correctness. The l\bli\bit\bth\bhi\bis\bst\bt shell option | |
4315 | causes the shell to save the command with embedded newlines instead of | |
4316 | semicolons. See the description of the s\bsh\bho\bop\bpt\bt builtin below under S\bSH\bHE\bEL\bLL\bL | |
8868edaf CR |
4317 | B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS for information on setting and unsetting shell op- |
4318 | tions. | |
17345e5a JA |
4319 | |
4320 | H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
4321 | The shell supports a history expansion feature that is similar to the | |
d233b485 | 4322 | history expansion in c\bcs\bsh\bh. This section describes what syntax features |
17345e5a JA |
4323 | are available. This feature is enabled by default for interactive |
4324 | shells, and can be disabled using the +\b+H\bH option to the s\bse\bet\bt builtin com- | |
4325 | mand (see S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS below). Non-interactive shells do not | |
4326 | perform history expansion by default. | |
4327 | ||
4328 | History expansions introduce words from the history list into the input | |
4329 | stream, making it easy to repeat commands, insert the arguments to a | |
4330 | previous command into the current input line, or fix errors in previous | |
4331 | commands quickly. | |
4332 | ||
4333 | History expansion is performed immediately after a complete line is | |
d233b485 | 4334 | read, before the shell breaks it into words, and is performed on each |
8868edaf CR |
4335 | line individually without taking quoting on previous lines into ac- |
4336 | count. It takes place in two parts. The first is to determine which | |
d233b485 CR |
4337 | line from the history list to use during substitution. The second is |
4338 | to select portions of that line for inclusion into the current one. | |
4339 | The line selected from the history is the _\be_\bv_\be_\bn_\bt, and the portions of | |
4340 | that line that are acted upon are _\bw_\bo_\br_\bd_\bs. Various _\bm_\bo_\bd_\bi_\bf_\bi_\be_\br_\bs are avail- | |
4341 | able to manipulate the selected words. The line is broken into words | |
4342 | in the same fashion as when reading input, so that several _\bm_\be_\bt_\ba_\bc_\bh_\ba_\br_\ba_\bc_\b- | |
4343 | _\bt_\be_\br-separated words surrounded by quotes are considered one word. His- | |
4344 | tory expansions are introduced by the appearance of the history expan- | |
4345 | sion character, which is !\b! by default. Only backslash (\\b\) and single | |
8868edaf CR |
4346 | quotes can quote the history expansion character, but the history ex- |
4347 | pansion character is also treated as quoted if it immediately precedes | |
4348 | the closing double quote in a double-quoted string. | |
d233b485 CR |
4349 | |
4350 | Several characters inhibit history expansion if found immediately fol- | |
4351 | lowing the history expansion character, even if it is unquoted: space, | |
4352 | tab, newline, carriage return, and =\b=. If the e\bex\bxt\btg\bgl\blo\bob\bb shell option is | |
17345e5a JA |
4353 | enabled, (\b( will also inhibit expansion. |
4354 | ||
d233b485 | 4355 | Several shell options settable with the s\bsh\bho\bop\bpt\bt builtin may be used to |
8868edaf CR |
4356 | tailor the behavior of history expansion. If the h\bhi\bis\bst\btv\bve\ber\bri\bif\bfy\by shell op- |
4357 | tion is enabled (see the description of the s\bsh\bho\bop\bpt\bt builtin below), and | |
d233b485 CR |
4358 | r\bre\bea\bad\bdl\bli\bin\bne\be is being used, history substitutions are not immediately |
4359 | passed to the shell parser. Instead, the expanded line is reloaded | |
0001803f | 4360 | into the r\bre\bea\bad\bdl\bli\bin\bne\be editing buffer for further modification. If r\bre\bea\bad\bdl\bli\bin\bne\be |
d233b485 CR |
4361 | is being used, and the h\bhi\bis\bst\btr\bre\bee\bed\bdi\bit\bt shell option is enabled, a failed |
4362 | history substitution will be reloaded into the r\bre\bea\bad\bdl\bli\bin\bne\be editing buffer | |
4363 | for correction. The -\b-p\bp option to the h\bhi\bis\bst\bto\bor\bry\by builtin command may be | |
4364 | used to see what a history expansion will do before using it. The -\b-s\bs | |
0001803f | 4365 | option to the h\bhi\bis\bst\bto\bor\bry\by builtin may be used to add commands to the end of |
d233b485 | 4366 | the history list without actually executing them, so that they are |
0001803f | 4367 | available for subsequent recall. |
17345e5a | 4368 | |
d233b485 | 4369 | The shell allows control of the various characters used by the history |
17345e5a | 4370 | expansion mechanism (see the description of h\bhi\bis\bst\btc\bch\bha\bar\brs\bs above under S\bSh\bhe\bel\bll\bl |
d233b485 | 4371 | V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs). The shell uses the history comment character to mark his- |
17345e5a JA |
4372 | tory timestamps when writing the history file. |
4373 | ||
4374 | E\bEv\bve\ben\bnt\bt D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs | |
d233b485 CR |
4375 | An event designator is a reference to a command line entry in the his- |
4376 | tory list. Unless the reference is absolute, events are relative to | |
495aee44 | 4377 | the current position in the history list. |
17345e5a | 4378 | |
d233b485 CR |
4379 | !\b! Start a history substitution, except when followed by a b\bbl\bla\ban\bnk\bk, |
4380 | newline, carriage return, = or ( (when the e\bex\bxt\btg\bgl\blo\bob\bb shell option | |
17345e5a JA |
4381 | is enabled using the s\bsh\bho\bop\bpt\bt builtin). |
4382 | !\b!_\bn Refer to command line _\bn. | |
495aee44 | 4383 | !\b!-\b-_\bn Refer to the current command minus _\bn. |
17345e5a JA |
4384 | !\b!!\b! Refer to the previous command. This is a synonym for `!-1'. |
4385 | !\b!_\bs_\bt_\br_\bi_\bn_\bg | |
d233b485 | 4386 | Refer to the most recent command preceding the current position |
495aee44 | 4387 | in the history list starting with _\bs_\bt_\br_\bi_\bn_\bg. |
17345e5a | 4388 | !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b] |
d233b485 CR |
4389 | Refer to the most recent command preceding the current position |
4390 | in the history list containing _\bs_\bt_\br_\bi_\bn_\bg. The trailing ?\b? may be | |
8868edaf CR |
4391 | omitted if _\bs_\bt_\br_\bi_\bn_\bg is followed immediately by a newline. If |
4392 | _\bs_\bt_\br_\bi_\bn_\bg is missing, the string from the most recent search is | |
4393 | used; it is an error if there is no previous search string. | |
17345e5a | 4394 | ^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b1^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b2^\b^ |
d233b485 | 4395 | Quick substitution. Repeat the previous command, replacing |
8868edaf | 4396 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 with _\bs_\bt_\br_\bi_\bn_\bg_\b2. Equivalent to ``!!:s^_\bs_\bt_\br_\bi_\bn_\bg_\b1^_\bs_\bt_\br_\bi_\bn_\bg_\b2^'' |
495aee44 | 4397 | (see M\bMo\bod\bdi\bif\bfi\bie\ber\brs\bs below). |
17345e5a JA |
4398 | !\b!#\b# The entire command line typed so far. |
4399 | ||
4400 | W\bWo\bor\brd\bd D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs | |
d233b485 CR |
4401 | Word designators are used to select desired words from the event. A :\b: |
4402 | separates the event specification from the word designator. It may be | |
4403 | omitted if the word designator begins with a ^\b^, $\b$, *\b*, -\b-, or %\b%. Words | |
4404 | are numbered from the beginning of the line, with the first word being | |
4405 | denoted by 0 (zero). Words are inserted into the current line sepa- | |
17345e5a JA |
4406 | rated by single spaces. |
4407 | ||
4408 | 0\b0 (\b(z\bze\ber\bro\bo)\b) | |
4409 | The zeroth word. For the shell, this is the command word. | |
4410 | _\bn The _\bnth word. | |
4411 | ^\b^ The first argument. That is, word 1. | |
8868edaf CR |
4412 | $\b$ The last word. This is usually the last argument, but will ex- |
4413 | pand to the zeroth word if there is only one word in the line. | |
4414 | %\b% The first word matched by the most recent `?_\bs_\bt_\br_\bi_\bn_\bg?' search, if | |
4415 | the search string begins with a character that is part of a | |
4416 | word. | |
17345e5a | 4417 | _\bx-\b-_\by A range of words; `-_\by' abbreviates `0-_\by'. |
d233b485 CR |
4418 | *\b* All of the words but the zeroth. This is a synonym for `_\b1_\b-_\b$'. |
4419 | It is not an error to use *\b* if there is just one word in the | |
17345e5a JA |
4420 | event; the empty string is returned in that case. |
4421 | x\bx*\b* Abbreviates _\bx_\b-_\b$. | |
8868edaf CR |
4422 | x\bx-\b- Abbreviates _\bx_\b-_\b$ like x\bx*\b*, but omits the last word. If x\bx is miss- |
4423 | ing, it defaults to 0. | |
17345e5a | 4424 | |
8868edaf | 4425 | If a word designator is supplied without an event specification, the |
17345e5a JA |
4426 | previous command is used as the event. |
4427 | ||
4428 | M\bMo\bod\bdi\bif\bfi\bie\ber\brs\bs | |
8868edaf CR |
4429 | After the optional word designator, there may appear a sequence of one |
4430 | or more of the following modifiers, each preceded by a `:'. These mod- | |
4431 | ify, or edit, the word or words selected from the history event. | |
17345e5a | 4432 | |
ac50fbac CR |
4433 | h\bh Remove a trailing filename component, leaving only the head. |
4434 | t\bt Remove all leading filename components, leaving the tail. | |
17345e5a JA |
4435 | r\br Remove a trailing suffix of the form _\b._\bx_\bx_\bx, leaving the basename. |
4436 | e\be Remove all but the trailing suffix. | |
4437 | p\bp Print the new command but do not execute it. | |
4438 | q\bq Quote the substituted words, escaping further substitutions. | |
d233b485 | 4439 | x\bx Quote the substituted words as with q\bq, but break into words at |
8868edaf CR |
4440 | b\bbl\bla\ban\bnk\bks\bs and newlines. The q\bq and x\bx modifiers are mutually exclu- |
4441 | sive; the last one supplied is used. | |
17345e5a | 4442 | s\bs/\b/_\bo_\bl_\bd/\b/_\bn_\be_\bw/\b/ |
8868edaf CR |
4443 | Substitute _\bn_\be_\bw for the first occurrence of _\bo_\bl_\bd in the event |
4444 | line. Any character may be used as the delimiter in place of /. | |
4445 | The final delimiter is optional if it is the last character of | |
4446 | the event line. The delimiter may be quoted in _\bo_\bl_\bd and _\bn_\be_\bw with | |
4447 | a single backslash. If & appears in _\bn_\be_\bw, it is replaced by _\bo_\bl_\bd. | |
4448 | A single backslash will quote the &. If _\bo_\bl_\bd is null, it is set | |
4449 | to the last _\bo_\bl_\bd substituted, or, if no previous history substi- | |
4450 | tutions took place, the last _\bs_\bt_\br_\bi_\bn_\bg in a !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b] search. | |
4451 | If _\bn_\be_\bw is null, each matching _\bo_\bl_\bd is deleted. | |
17345e5a JA |
4452 | &\b& Repeat the previous substitution. |
4453 | g\bg Cause changes to be applied over the entire event line. This is | |
d233b485 CR |
4454 | used in conjunction with `:\b:s\bs' (e.g., `:\b:g\bgs\bs/\b/_\bo_\bl_\bd/\b/_\bn_\be_\bw/\b/') or `:\b:&\b&'. |
4455 | If used with `:\b:s\bs', any delimiter can be used in place of /, and | |
4456 | the final delimiter is optional if it is the last character of | |
17345e5a | 4457 | the event line. An a\ba may be used as a synonym for g\bg. |
8868edaf CR |
4458 | G\bG Apply the following `s\bs' or `&\b&' modifier once to each word in the |
4459 | event line. | |
17345e5a JA |
4460 | |
4461 | S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS | |
4462 | Unless otherwise noted, each builtin command documented in this section | |
4463 | as accepting options preceded by -\b- accepts -\b--\b- to signify the end of the | |
d233b485 CR |
4464 | options. The :\b:, t\btr\bru\bue\be, f\bfa\bal\bls\bse\be, and t\bte\bes\bst\bt/[\b[ builtins do not accept options |
4465 | and do not treat -\b--\b- specially. The e\bex\bxi\bit\bt, l\blo\bog\bgo\bou\but\bt, r\bre\bet\btu\bur\brn\bn, b\bbr\bre\bea\bak\bk, c\bco\bon\bn-\b- | |
4466 | t\bti\bin\bnu\bue\be, l\ble\bet\bt, and s\bsh\bhi\bif\bft\bt builtins accept and process arguments beginning | |
4467 | with -\b- without requiring -\b--\b-. Other builtins that accept arguments but | |
4468 | are not specified as accepting options interpret arguments beginning | |
4469 | with -\b- as invalid options and require -\b--\b- to prevent this interpreta- | |
a0c0a00f | 4470 | tion. |
17345e5a | 4471 | :\b: [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs] |
d233b485 | 4472 | No effect; the command does nothing beyond expanding _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs |
a0c0a00f CR |
4473 | and performing any specified redirections. The return status is |
4474 | zero. | |
17345e5a JA |
4475 | |
4476 | .\b. _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs] | |
4477 | s\bso\bou\bur\brc\bce\be _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs] | |
8868edaf CR |
4478 | Read and execute commands from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be in the current shell en- |
4479 | vironment and return the exit status of the last command exe- | |
d233b485 CR |
4480 | cuted from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be does not contain a slash, |
4481 | filenames in P\bPA\bAT\bTH\bH are used to find the directory containing | |
74091dd4 CR |
4482 | _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, but _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be does not need to be executable. The file |
4483 | searched for in P\bPA\bAT\bTH\bH need not be executable. When b\bba\bas\bsh\bh is not | |
4484 | in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, it searches the current directory if no file is | |
4485 | found in P\bPA\bAT\bTH\bH. If the s\bso\bou\bur\brc\bce\bep\bpa\bat\bth\bh option to the s\bsh\bho\bop\bpt\bt builtin | |
4486 | command is turned off, the P\bPA\bAT\bTH\bH is not searched. If any _\ba_\br_\bg_\bu_\b- | |
4487 | _\bm_\be_\bn_\bt_\bs are supplied, they become the positional parameters when | |
4488 | _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is executed. Otherwise the positional parameters are | |
4489 | unchanged. If the -\b-T\bT option is enabled, .\b. inherits any trap on | |
4490 | D\bDE\bEB\bBU\bUG\bG; if it is not, any D\bDE\bEB\bBU\bUG\bG trap string is saved and restored | |
4491 | around the call to .\b., and .\b. unsets the D\bDE\bEB\bBU\bUG\bG trap while it exe- | |
4492 | cutes. If -\b-T\bT is not set, and the sourced file changes the D\bDE\bEB\bBU\bUG\bG | |
4493 | trap, the new value is retained when .\b. completes. The return | |
4494 | status is the status of the last command exited within the | |
4495 | script (0 if no commands are executed), and false if _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is | |
4496 | not found or cannot be read. | |
17345e5a JA |
4497 | |
4498 | a\bal\bli\bia\bas\bs [-\b-p\bp] [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be] ...] | |
4499 | A\bAl\bli\bia\bas\bs with no arguments or with the -\b-p\bp option prints the list of | |
d233b485 CR |
4500 | aliases in the form a\bal\bli\bia\bas\bs _\bn_\ba_\bm_\be=_\bv_\ba_\bl_\bu_\be on standard output. When |
4501 | arguments are supplied, an alias is defined for each _\bn_\ba_\bm_\be whose | |
4502 | _\bv_\ba_\bl_\bu_\be is given. A trailing space in _\bv_\ba_\bl_\bu_\be causes the next word | |
17345e5a | 4503 | to be checked for alias substitution when the alias is expanded. |
d233b485 | 4504 | For each _\bn_\ba_\bm_\be in the argument list for which no _\bv_\ba_\bl_\bu_\be is sup- |
8868edaf CR |
4505 | plied, the name and value of the alias is printed. A\bAl\bli\bia\bas\bs re- |
4506 | turns true unless a _\bn_\ba_\bm_\be is given for which no alias has been | |
17345e5a JA |
4507 | defined. |
4508 | ||
4509 | b\bbg\bg [_\bj_\bo_\bb_\bs_\bp_\be_\bc ...] | |
d233b485 | 4510 | Resume each suspended job _\bj_\bo_\bb_\bs_\bp_\be_\bc in the background, as if it |
17345e5a | 4511 | had been started with &\b&. If _\bj_\bo_\bb_\bs_\bp_\be_\bc is not present, the shell's |
d233b485 CR |
4512 | notion of the _\bc_\bu_\br_\br_\be_\bn_\bt _\bj_\bo_\bb is used. b\bbg\bg _\bj_\bo_\bb_\bs_\bp_\be_\bc returns 0 unless |
4513 | run when job control is disabled or, when run with job control | |
4514 | enabled, any specified _\bj_\bo_\bb_\bs_\bp_\be_\bc was not found or was started | |
17345e5a JA |
4515 | without job control. |
4516 | ||
ac50fbac | 4517 | b\bbi\bin\bnd\bd [-\b-m\bm _\bk_\be_\by_\bm_\ba_\bp] [-\b-l\blp\bps\bsv\bvP\bPS\bSV\bVX\bX] |
17345e5a JA |
4518 | b\bbi\bin\bnd\bd [-\b-m\bm _\bk_\be_\by_\bm_\ba_\bp] [-\b-q\bq _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn] [-\b-u\bu _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn] [-\b-r\br _\bk_\be_\by_\bs_\be_\bq] |
4519 | b\bbi\bin\bnd\bd [-\b-m\bm _\bk_\be_\by_\bm_\ba_\bp] -\b-f\bf _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be | |
4520 | b\bbi\bin\bnd\bd [-\b-m\bm _\bk_\be_\by_\bm_\ba_\bp] -\b-x\bx _\bk_\be_\by_\bs_\be_\bq:_\bs_\bh_\be_\bl_\bl_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd | |
4521 | b\bbi\bin\bnd\bd [-\b-m\bm _\bk_\be_\by_\bm_\ba_\bp] _\bk_\be_\by_\bs_\be_\bq:_\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be | |
a0c0a00f | 4522 | b\bbi\bin\bnd\bd [-\b-m\bm _\bk_\be_\by_\bm_\ba_\bp] _\bk_\be_\by_\bs_\be_\bq:_\br_\be_\ba_\bd_\bl_\bi_\bn_\be_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd |
74091dd4 | 4523 | b\bbi\bin\bnd\bd _\br_\be_\ba_\bd_\bl_\bi_\bn_\be_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b-_\bl_\bi_\bn_\be |
d233b485 CR |
4524 | Display current r\bre\bea\bad\bdl\bli\bin\bne\be key and function bindings, bind a key |
4525 | sequence to a r\bre\bea\bad\bdl\bli\bin\bne\be function or macro, or set a r\bre\bea\bad\bdl\bli\bin\bne\be | |
8868edaf | 4526 | variable. Each non-option argument is a command as it would ap- |
74091dd4 CR |
4527 | pear in a r\bre\bea\bad\bdl\bli\bin\bne\be initialization file such as _\b._\bi_\bn_\bp_\bu_\bt_\br_\bc, but |
4528 | each binding or command must be passed as a separate argument; | |
4529 | e.g., '"\C-x\C-r": re-read-init-file'. Options, if supplied, | |
4530 | have the following meanings: | |
17345e5a JA |
4531 | -\b-m\bm _\bk_\be_\by_\bm_\ba_\bp |
4532 | Use _\bk_\be_\by_\bm_\ba_\bp as the keymap to be affected by the subsequent | |
4533 | bindings. Acceptable _\bk_\be_\by_\bm_\ba_\bp names are _\be_\bm_\ba_\bc_\bs_\b, _\be_\bm_\ba_\bc_\bs_\b-_\bs_\bt_\ba_\bn_\b- | |
74091dd4 CR |
4534 | _\bd_\ba_\br_\bd_\b, _\be_\bm_\ba_\bc_\bs_\b-_\bm_\be_\bt_\ba_\b, _\be_\bm_\ba_\bc_\bs_\b-_\bc_\bt_\bl_\bx_\b, _\bv_\bi_\b, _\bv_\bi_\b-_\bm_\bo_\bv_\be_\b, _\bv_\bi_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd, |
4535 | and _\bv_\bi_\b-_\bi_\bn_\bs_\be_\br_\bt. _\bv_\bi is equivalent to _\bv_\bi_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd (_\bv_\bi_\b-_\bm_\bo_\bv_\be | |
4536 | is also a synonym); _\be_\bm_\ba_\bc_\bs is equivalent to _\be_\bm_\ba_\bc_\bs_\b-_\bs_\bt_\ba_\bn_\b- | |
a0c0a00f | 4537 | _\bd_\ba_\br_\bd. |
17345e5a | 4538 | -\b-l\bl List the names of all r\bre\bea\bad\bdl\bli\bin\bne\be functions. |
74091dd4 | 4539 | -\b-p\bp Display r\bre\bea\bad\bdl\bli\bin\bne\be function names and bindings in such a |
17345e5a JA |
4540 | way that they can be re-read. |
4541 | -\b-P\bP List current r\bre\bea\bad\bdl\bli\bin\bne\be function names and bindings. | |
74091dd4 CR |
4542 | -\b-s\bs Display r\bre\bea\bad\bdl\bli\bin\bne\be key sequences bound to macros and the |
4543 | strings they output in such a way that they can be re- | |
17345e5a | 4544 | read. |
74091dd4 | 4545 | -\b-S\bS Display r\bre\bea\bad\bdl\bli\bin\bne\be key sequences bound to macros and the |
17345e5a | 4546 | strings they output. |
74091dd4 | 4547 | -\b-v\bv Display r\bre\bea\bad\bdl\bli\bin\bne\be variable names and values in such a way |
17345e5a JA |
4548 | that they can be re-read. |
4549 | -\b-V\bV List current r\bre\bea\bad\bdl\bli\bin\bne\be variable names and values. | |
4550 | -\b-f\bf _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be | |
4551 | Read key bindings from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be. | |
4552 | -\b-q\bq _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn | |
4553 | Query about which keys invoke the named _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn. | |
4554 | -\b-u\bu _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn | |
4555 | Unbind all keys bound to the named _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn. | |
4556 | -\b-r\br _\bk_\be_\by_\bs_\be_\bq | |
4557 | Remove any current binding for _\bk_\be_\by_\bs_\be_\bq. | |
4558 | -\b-x\bx _\bk_\be_\by_\bs_\be_\bq:\b:_\bs_\bh_\be_\bl_\bl_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd | |
8868edaf | 4559 | Cause _\bs_\bh_\be_\bl_\bl_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd to be executed whenever _\bk_\be_\by_\bs_\be_\bq is en- |
74091dd4 CR |
4560 | tered. When _\bs_\bh_\be_\bl_\bl_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd is executed, the shell sets |
4561 | the R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_L\bLI\bIN\bNE\bE variable to the contents of the r\bre\bea\bad\bd-\b- | |
8868edaf | 4562 | l\bli\bin\bne\be line buffer and the R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_P\bPO\bOI\bIN\bNT\bT and R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_M\bMA\bAR\bRK\bK |
74091dd4 CR |
4563 | variables to the current location of the insertion point |
4564 | and the saved insertion point (the mark), respectively. | |
4565 | The shell assigns any numeric argument the user supplied | |
4566 | to the R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_A\bAR\bRG\bGU\bUM\bME\bEN\bNT\bT variable. If there was no argu- | |
4567 | ment, that variable is not set. If the executed command | |
4568 | changes the value of any of R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_L\bLI\bIN\bNE\bE, R\bRE\bEA\bAD\bD-\b- | |
4569 | L\bLI\bIN\bNE\bE_\b_P\bPO\bOI\bIN\bNT\bT, or R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_M\bMA\bAR\bRK\bK, those new values will be | |
4570 | reflected in the editing state. | |
8868edaf CR |
4571 | -\b-X\bX List all key sequences bound to shell commands and the |
4572 | associated commands in a format that can be reused as in- | |
4573 | put. | |
4574 | ||
4575 | The return value is 0 unless an unrecognized option is given or | |
17345e5a JA |
4576 | an error occurred. |
4577 | ||
4578 | b\bbr\bre\bea\bak\bk [_\bn] | |
8868edaf CR |
4579 | Exit from within a f\bfo\bor\br, w\bwh\bhi\bil\ble\be, u\bun\bnt\bti\bil\bl, or s\bse\bel\ble\bec\bct\bt loop. If _\bn is |
4580 | specified, break _\bn levels. _\bn must be >= 1. If _\bn is greater | |
4581 | than the number of enclosing loops, all enclosing loops are ex- | |
4582 | ited. The return value is 0 unless _\bn is not greater than or | |
17345e5a JA |
4583 | equal to 1. |
4584 | ||
4585 | b\bbu\bui\bil\blt\bti\bin\bn _\bs_\bh_\be_\bl_\bl_\b-_\bb_\bu_\bi_\bl_\bt_\bi_\bn [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs] | |
8868edaf | 4586 | Execute the specified shell builtin, passing it _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs, and |
17345e5a | 4587 | return its exit status. This is useful when defining a function |
8868edaf | 4588 | whose name is the same as a shell builtin, retaining the func- |
17345e5a | 4589 | tionality of the builtin within the function. The c\bcd\bd builtin is |
8868edaf | 4590 | commonly redefined this way. The return status is false if |
17345e5a JA |
4591 | _\bs_\bh_\be_\bl_\bl_\b-_\bb_\bu_\bi_\bl_\bt_\bi_\bn is not a shell builtin command. |
4592 | ||
4593 | c\bca\bal\bll\ble\ber\br [_\be_\bx_\bp_\br] | |
4594 | Returns the context of any active subroutine call (a shell func- | |
495aee44 | 4595 | tion or a script executed with the .\b. or s\bso\bou\bur\brc\bce\be builtins). With- |
17345e5a | 4596 | out _\be_\bx_\bp_\br, c\bca\bal\bll\ble\ber\br displays the line number and source filename of |
8868edaf | 4597 | the current subroutine call. If a non-negative integer is sup- |
17345e5a | 4598 | plied as _\be_\bx_\bp_\br, c\bca\bal\bll\ble\ber\br displays the line number, subroutine name, |
8868edaf CR |
4599 | and source file corresponding to that position in the current |
4600 | execution call stack. This extra information may be used, for | |
4601 | example, to print a stack trace. The current frame is frame 0. | |
4602 | The return value is 0 unless the shell is not executing a sub- | |
4603 | routine call or _\be_\bx_\bp_\br does not correspond to a valid position in | |
17345e5a JA |
4604 | the call stack. |
4605 | ||
ac50fbac | 4606 | c\bcd\bd [-\b-L\bL|[-\b-P\bP [-\b-e\be]] [-@]] [_\bd_\bi_\br] |
8868edaf | 4607 | Change the current directory to _\bd_\bi_\br. if _\bd_\bi_\br is not supplied, |
74091dd4 CR |
4608 | the value of the H\bHO\bOM\bME\bE shell variable is the default. The vari- |
4609 | able C\bCD\bDP\bPA\bAT\bTH\bH defines the search path for the directory containing | |
4610 | _\bd_\bi_\br: each directory name in C\bCD\bDP\bPA\bAT\bTH\bH is searched for _\bd_\bi_\br. Alter- | |
4611 | native directory names in C\bCD\bDP\bPA\bAT\bTH\bH are separated by a colon (:). | |
4612 | A null directory name in C\bCD\bDP\bPA\bAT\bTH\bH is the same as the current di- | |
4613 | rectory, i.e., ``.\b.''. If _\bd_\bi_\br begins with a slash (/), then C\bCD\bD-\b- | |
4614 | P\bPA\bAT\bTH\bH is not used. The -\b-P\bP option causes c\bcd\bd to use the physical | |
4615 | directory structure by resolving symbolic links while traversing | |
4616 | _\bd_\bi_\br and before processing instances of _\b._\b. in _\bd_\bi_\br (see also the | |
4617 | -\b-P\bP option to the s\bse\bet\bt builtin command); the -\b-L\bL option forces sym- | |
4618 | bolic links to be followed by resolving the link after process- | |
4619 | ing instances of _\b._\b. in _\bd_\bi_\br. If _\b._\b. appears in _\bd_\bi_\br, it is pro- | |
4620 | cessed by removing the immediately previous pathname component | |
4621 | from _\bd_\bi_\br, back to a slash or the beginning of _\bd_\bi_\br. If the -\b-e\be | |
4622 | option is supplied with -\b-P\bP, and the current working directory | |
4623 | cannot be successfully determined after a successful directory | |
4624 | change, c\bcd\bd will return an unsuccessful status. On systems that | |
4625 | support it, the -\b-@\b@ option presents the extended attributes asso- | |
4626 | ciated with a file as a directory. An argument of -\b- is con- | |
4627 | verted to $\b$O\bOL\bLD\bDP\bPW\bWD\bD before the directory change is attempted. If | |
4628 | a non-empty directory name from C\bCD\bDP\bPA\bAT\bTH\bH is used, or if -\b- is the | |
4629 | first argument, and the directory change is successful, the ab- | |
4630 | solute pathname of the new working directory is written to the | |
4631 | standard output. If the directory change is successful, c\bcd\bd sets | |
4632 | the value of the P\bPW\bWD\bD environment variable to the new directory | |
4633 | name, and sets the O\bOL\bLD\bDP\bPW\bWD\bD environment variable to the value of | |
4634 | the current working directory before the change. The return | |
4635 | value is true if the directory was successfully changed; false | |
4636 | otherwise. | |
17345e5a JA |
4637 | |
4638 | c\bco\bom\bmm\bma\ban\bnd\bd [-\b-p\bpV\bVv\bv] _\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\ba_\br_\bg ...] | |
74091dd4 | 4639 | Run _\bc_\bo_\bm_\bm_\ba_\bn_\bd with _\ba_\br_\bg_\bs suppressing the normal shell function |
a0c0a00f | 4640 | lookup. Only builtin commands or commands found in the P\bPA\bAT\bTH\bH are |
74091dd4 CR |
4641 | executed. If the -\b-p\bp option is given, the search for _\bc_\bo_\bm_\bm_\ba_\bn_\bd is |
4642 | performed using a default value for P\bPA\bAT\bTH\bH that is guaranteed to | |
4643 | find all of the standard utilities. If either the -\b-V\bV or -\b-v\bv op- | |
4644 | tion is supplied, a description of _\bc_\bo_\bm_\bm_\ba_\bn_\bd is printed. The -\b-v\bv | |
4645 | option causes a single word indicating the command or filename | |
17345e5a | 4646 | used to invoke _\bc_\bo_\bm_\bm_\ba_\bn_\bd to be displayed; the -\b-V\bV option produces a |
74091dd4 CR |
4647 | more verbose description. If the -\b-V\bV or -\b-v\bv option is supplied, |
4648 | the exit status is 0 if _\bc_\bo_\bm_\bm_\ba_\bn_\bd was found, and 1 if not. If | |
17345e5a | 4649 | neither option is supplied and an error occurred or _\bc_\bo_\bm_\bm_\ba_\bn_\bd can- |
74091dd4 | 4650 | not be found, the exit status is 127. Otherwise, the exit sta- |
17345e5a JA |
4651 | tus of the c\bco\bom\bmm\bma\ban\bnd\bd builtin is the exit status of _\bc_\bo_\bm_\bm_\ba_\bn_\bd. |
4652 | ||
4653 | c\bco\bom\bmp\bpg\bge\ben\bn [_\bo_\bp_\bt_\bi_\bo_\bn] [_\bw_\bo_\br_\bd] | |
74091dd4 CR |
4654 | Generate possible completion matches for _\bw_\bo_\br_\bd according to the |
4655 | _\bo_\bp_\bt_\bi_\bo_\bns, which may be any option accepted by the c\bco\bom\bmp\bpl\ble\bet\bte\be | |
4656 | builtin with the exception of -\b-p\bp and -\b-r\br, and write the matches | |
4657 | to the standard output. When using the -\b-F\bF or -\b-C\bC options, the | |
4658 | various shell variables set by the programmable completion fa- | |
8868edaf | 4659 | cilities, while available, will not have useful values. |
17345e5a | 4660 | |
a0c0a00f CR |
4661 | The matches will be generated in the same way as if the program- |
4662 | mable completion code had generated them directly from a comple- | |
74091dd4 | 4663 | tion specification with the same flags. If _\bw_\bo_\br_\bd is specified, |
a0c0a00f | 4664 | only those completions matching _\bw_\bo_\br_\bd will be displayed. |
17345e5a | 4665 | |
74091dd4 | 4666 | The return value is true unless an invalid option is supplied, |
17345e5a JA |
4667 | or no matches were generated. |
4668 | ||
74091dd4 | 4669 | c\bco\bom\bmp\bpl\ble\bet\bte\be [-\b-a\bab\bbc\bcd\bde\bef\bfg\bgj\bjk\bks\bsu\buv\bv] [-\b-o\bo _\bc_\bo_\bm_\bp_\b-_\bo_\bp_\bt_\bi_\bo_\bn] [-\b-D\bDE\bEI\bI] [-\b-A\bA _\ba_\bc_\bt_\bi_\bo_\bn] [-\b-G\bG _\bg_\bl_\bo_\bb_\b- |
8868edaf | 4670 | _\bp_\ba_\bt] [-\b-W\bW _\bw_\bo_\br_\bd_\bl_\bi_\bs_\bt] |
74091dd4 | 4671 | [-\b-F\bF _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn] [-\b-C\bC _\bc_\bo_\bm_\bm_\ba_\bn_\bd] [-\b-X\bX _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt] [-\b-P\bP _\bp_\br_\be_\bf_\bi_\bx] [-\b-S\bS _\bs_\bu_\bf_\b- |
8868edaf | 4672 | _\bf_\bi_\bx] _\bn_\ba_\bm_\be [_\bn_\ba_\bm_\be _\b._\b._\b.] |
d233b485 | 4673 | c\bco\bom\bmp\bpl\ble\bet\bte\be -\b-p\bpr\br [-\b-D\bDE\bEI\bI] [_\bn_\ba_\bm_\be ...] |
74091dd4 CR |
4674 | Specify how arguments to each _\bn_\ba_\bm_\be should be completed. If the |
4675 | -\b-p\bp option is supplied, or if no options are supplied, existing | |
4676 | completion specifications are printed in a way that allows them | |
17345e5a | 4677 | to be reused as input. The -\b-r\br option removes a completion spec- |
74091dd4 | 4678 | ification for each _\bn_\ba_\bm_\be, or, if no _\bn_\ba_\bm_\bes are supplied, all com- |
d233b485 | 4679 | pletion specifications. The -\b-D\bD option indicates that other sup- |
74091dd4 CR |
4680 | plied options and actions should apply to the ``default'' com- |
4681 | mand completion; that is, completion attempted on a command for | |
4682 | which no completion has previously been defined. The -\b-E\bE option | |
4683 | indicates that other supplied options and actions should apply | |
4684 | to ``empty'' command completion; that is, completion attempted | |
4685 | on a blank line. The -\b-I\bI option indicates that other supplied | |
4686 | options and actions should apply to completion on the initial | |
4687 | non-assignment word on the line, or after a command delimiter | |
4688 | such as ;\b; or |\b|, which is usually command name completion. If | |
4689 | multiple options are supplied, the -\b-D\bD option takes precedence | |
d233b485 | 4690 | over -\b-E\bE, and both take precedence over -\b-I\bI. If any of -\b-D\bD, -\b-E\bE, or |
74091dd4 | 4691 | -\b-I\bI are supplied, any other _\bn_\ba_\bm_\be arguments are ignored; these |
d233b485 | 4692 | completions only apply to the case specified by the option. |
17345e5a | 4693 | |
74091dd4 CR |
4694 | The process of applying these completion specifications when |
4695 | word completion is attempted is described above under P\bPr\bro\bog\bgr\bra\bam\bm-\b- | |
a0c0a00f | 4696 | m\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn. |
17345e5a | 4697 | |
74091dd4 CR |
4698 | Other options, if specified, have the following meanings. The |
4699 | arguments to the -\b-G\bG, -\b-W\bW, and -\b-X\bX options (and, if necessary, the | |
4700 | -\b-P\bP and -\b-S\bS options) should be quoted to protect them from expan- | |
17345e5a JA |
4701 | sion before the c\bco\bom\bmp\bpl\ble\bet\bte\be builtin is invoked. |
4702 | -\b-o\bo _\bc_\bo_\bm_\bp_\b-_\bo_\bp_\bt_\bi_\bo_\bn | |
74091dd4 CR |
4703 | The _\bc_\bo_\bm_\bp_\b-_\bo_\bp_\bt_\bi_\bo_\bn controls several aspects of the comp- |
4704 | spec's behavior beyond the simple generation of comple- | |
17345e5a JA |
4705 | tions. _\bc_\bo_\bm_\bp_\b-_\bo_\bp_\bt_\bi_\bo_\bn may be one of: |
4706 | b\bba\bas\bsh\bhd\bde\bef\bfa\bau\bul\blt\bt | |
4707 | Perform the rest of the default b\bba\bas\bsh\bh completions | |
4708 | if the compspec generates no matches. | |
74091dd4 | 4709 | d\bde\bef\bfa\bau\bul\blt\bt Use readline's default filename completion if |
17345e5a JA |
4710 | the compspec generates no matches. |
4711 | d\bdi\bir\brn\bna\bam\bme\bes\bs | |
74091dd4 | 4712 | Perform directory name completion if the comp- |
17345e5a JA |
4713 | spec generates no matches. |
4714 | f\bfi\bil\ble\ben\bna\bam\bme\bes\bs | |
74091dd4 CR |
4715 | Tell readline that the compspec generates file- |
4716 | names, so it can perform any filename-specific | |
4717 | processing (like adding a slash to directory | |
4718 | names, quoting special characters, or suppress- | |
4719 | ing trailing spaces). Intended to be used with | |
17345e5a | 4720 | shell functions. |
74091dd4 CR |
4721 | n\bno\boq\bqu\buo\bot\bte\be Tell readline not to quote the completed words |
4722 | if they are filenames (quoting filenames is the | |
ac50fbac | 4723 | default). |
74091dd4 | 4724 | n\bno\bos\bso\bor\brt\bt Tell readline not to sort the list of possible |
a0c0a00f | 4725 | completions alphabetically. |
74091dd4 CR |
4726 | n\bno\bos\bsp\bpa\bac\bce\be Tell readline not to append a space (the de- |
4727 | fault) to words completed at the end of the | |
17345e5a JA |
4728 | line. |
4729 | p\bpl\blu\bus\bsd\bdi\bir\brs\bs | |
74091dd4 | 4730 | After any matches defined by the compspec are |
8868edaf CR |
4731 | generated, directory name completion is at- |
4732 | tempted and any matches are added to the results | |
4733 | of the other actions. | |
17345e5a | 4734 | -\b-A\bA _\ba_\bc_\bt_\bi_\bo_\bn |
74091dd4 | 4735 | The _\ba_\bc_\bt_\bi_\bo_\bn may be one of the following to generate a |
17345e5a JA |
4736 | list of possible completions: |
4737 | a\bal\bli\bia\bas\bs Alias names. May also be specified as -\b-a\ba. | |
4738 | a\bar\brr\bra\bay\byv\bva\bar\br | |
4739 | Array variable names. | |
4740 | b\bbi\bin\bnd\bdi\bin\bng\bg R\bRe\bea\bad\bdl\bli\bin\bne\be key binding names. | |
74091dd4 | 4741 | b\bbu\bui\bil\blt\bti\bin\bn Names of shell builtin commands. May also be |
17345e5a JA |
4742 | specified as -\b-b\bb. |
4743 | c\bco\bom\bmm\bma\ban\bnd\bd Command names. May also be specified as -\b-c\bc. | |
4744 | d\bdi\bir\bre\bec\bct\bto\bor\bry\by | |
4745 | Directory names. May also be specified as -\b-d\bd. | |
4746 | d\bdi\bis\bsa\bab\bbl\ble\bed\bd | |
4747 | Names of disabled shell builtins. | |
4748 | e\ben\bna\bab\bbl\ble\bed\bd Names of enabled shell builtins. | |
74091dd4 | 4749 | e\bex\bxp\bpo\bor\brt\bt Names of exported shell variables. May also be |
17345e5a JA |
4750 | specified as -\b-e\be. |
4751 | f\bfi\bil\ble\be File names. May also be specified as -\b-f\bf. | |
4752 | f\bfu\bun\bnc\bct\bti\bio\bon\bn | |
4753 | Names of shell functions. | |
4754 | g\bgr\bro\bou\bup\bp Group names. May also be specified as -\b-g\bg. | |
4755 | h\bhe\bel\blp\bpt\bto\bop\bpi\bic\bc | |
4756 | Help topics as accepted by the h\bhe\bel\blp\bp builtin. | |
4757 | h\bho\bos\bst\btn\bna\bam\bme\be | |
74091dd4 | 4758 | Hostnames, as taken from the file specified by |
17345e5a | 4759 | the H\bHO\bOS\bST\bTF\bFI\bIL\bLE\bE shell variable. |
74091dd4 | 4760 | j\bjo\bob\bb Job names, if job control is active. May also |
17345e5a | 4761 | be specified as -\b-j\bj. |
74091dd4 | 4762 | k\bke\bey\byw\bwo\bor\brd\bd Shell reserved words. May also be specified as |
17345e5a JA |
4763 | -\b-k\bk. |
4764 | r\bru\bun\bnn\bni\bin\bng\bg Names of running jobs, if job control is active. | |
4765 | s\bse\ber\brv\bvi\bic\bce\be Service names. May also be specified as -\b-s\bs. | |
74091dd4 | 4766 | s\bse\bet\bto\bop\bpt\bt Valid arguments for the -\b-o\bo option to the s\bse\bet\bt |
17345e5a | 4767 | builtin. |
74091dd4 | 4768 | s\bsh\bho\bop\bpt\bt Shell option names as accepted by the s\bsh\bho\bop\bpt\bt |
17345e5a JA |
4769 | builtin. |
4770 | s\bsi\big\bgn\bna\bal\bl Signal names. | |
4771 | s\bst\bto\bop\bpp\bpe\bed\bd Names of stopped jobs, if job control is active. | |
4772 | u\bus\bse\ber\br User names. May also be specified as -\b-u\bu. | |
4773 | v\bva\bar\bri\bia\bab\bbl\ble\be | |
4774 | Names of all shell variables. May also be spec- | |
4775 | ified as -\b-v\bv. | |
17345e5a | 4776 | -\b-C\bC _\bc_\bo_\bm_\bm_\ba_\bn_\bd |
74091dd4 CR |
4777 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd is executed in a subshell environment, and its |
4778 | output is used as the possible completions. Arguments | |
4779 | are passed as with the -\b-F\bF option. | |
17345e5a | 4780 | -\b-F\bF _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn |
a0c0a00f CR |
4781 | The shell function _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn is executed in the current |
4782 | shell environment. When the function is executed, the | |
8868edaf CR |
4783 | first argument ($\b$1\b1) is the name of the command whose ar- |
4784 | guments are being completed, the second argument ($\b$2\b2) is | |
4785 | the word being completed, and the third argument ($\b$3\b3) is | |
4786 | the word preceding the word being completed on the cur- | |
4787 | rent command line. When it finishes, the possible com- | |
4788 | pletions are retrieved from the value of the C\bCO\bOM\bMP\bPR\bRE\bEP\bPL\bLY\bY | |
4789 | array variable. | |
495aee44 | 4790 | -\b-G\bG _\bg_\bl_\bo_\bb_\bp_\ba_\bt |
a0c0a00f | 4791 | The pathname expansion pattern _\bg_\bl_\bo_\bb_\bp_\ba_\bt is expanded to |
495aee44 | 4792 | generate the possible completions. |
17345e5a | 4793 | -\b-P\bP _\bp_\br_\be_\bf_\bi_\bx |
a0c0a00f | 4794 | _\bp_\br_\be_\bf_\bi_\bx is added at the beginning of each possible com- |
17345e5a JA |
4795 | pletion after all other options have been applied. |
4796 | -\b-S\bS _\bs_\bu_\bf_\bf_\bi_\bx | |
4797 | _\bs_\bu_\bf_\bf_\bi_\bx is appended to each possible completion after all | |
4798 | other options have been applied. | |
495aee44 | 4799 | -\b-W\bW _\bw_\bo_\br_\bd_\bl_\bi_\bs_\bt |
a0c0a00f CR |
4800 | The _\bw_\bo_\br_\bd_\bl_\bi_\bs_\bt is split using the characters in the I\bIF\bFS\bS |
4801 | special variable as delimiters, and each resultant word | |
d233b485 CR |
4802 | is expanded. Shell quoting is honored within _\bw_\bo_\br_\bd_\bl_\bi_\bs_\bt, |
4803 | in order to provide a mechanism for the words to contain | |
4804 | shell metacharacters or characters in the value of I\bIF\bFS\bS. | |
4805 | The possible completions are the members of the resul- | |
4806 | tant list which match the word being completed. | |
495aee44 | 4807 | -\b-X\bX _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt |
a0c0a00f | 4808 | _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt is a pattern as used for pathname expansion. |
495aee44 | 4809 | It is applied to the list of possible completions gener- |
a0c0a00f CR |
4810 | ated by the preceding options and arguments, and each |
4811 | completion matching _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt is removed from the list. | |
4812 | A leading !\b! in _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt negates the pattern; in this | |
4813 | case, any completion not matching _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt is removed. | |
495aee44 CR |
4814 | |
4815 | The return value is true unless an invalid option is supplied, | |
4816 | an option other than -\b-p\bp or -\b-r\br is supplied without a _\bn_\ba_\bm_\be argu- | |
4817 | ment, an attempt is made to remove a completion specification | |
17345e5a JA |
4818 | for a _\bn_\ba_\bm_\be for which no specification exists, or an error occurs |
4819 | adding a completion specification. | |
4820 | ||
d233b485 | 4821 | c\bco\bom\bmp\bpo\bop\bpt\bt [-\b-o\bo _\bo_\bp_\bt_\bi_\bo_\bn] [-\b-D\bDE\bEI\bI] [+\b+o\bo _\bo_\bp_\bt_\bi_\bo_\bn] [_\bn_\ba_\bm_\be] |
8868edaf CR |
4822 | Modify completion options for each _\bn_\ba_\bm_\be according to the _\bo_\bp_\b- |
4823 | _\bt_\bi_\bo_\bns, or for the currently-executing completion if no _\bn_\ba_\bm_\bes are | |
4824 | supplied. If no _\bo_\bp_\bt_\bi_\bo_\bns are given, display the completion op- | |
4825 | tions for each _\bn_\ba_\bm_\be or the current completion. The possible | |
4826 | values of _\bo_\bp_\bt_\bi_\bo_\bn are those valid for the c\bco\bom\bmp\bpl\ble\bet\bte\be builtin de- | |
4827 | scribed above. The -\b-D\bD option indicates that other supplied op- | |
4828 | tions should apply to the ``default'' command completion; that | |
495aee44 | 4829 | is, completion attempted on a command for which no completion |
d233b485 CR |
4830 | has previously been defined. The -\b-E\bE option indicates that other |
4831 | supplied options should apply to ``empty'' command completion; | |
4832 | that is, completion attempted on a blank line. The -\b-I\bI option | |
4833 | indicates that other supplied options should apply to completion | |
8868edaf | 4834 | on the initial non-assignment word on the line, or after a com- |
d233b485 CR |
4835 | mand delimiter such as ;\b; or |\b|, which is usually command name |
4836 | completion. | |
0001803f | 4837 | |
495aee44 CR |
4838 | The return value is true unless an invalid option is supplied, |
4839 | an attempt is made to modify the options for a _\bn_\ba_\bm_\be for which no | |
4840 | completion specification exists, or an output error occurs. | |
17345e5a JA |
4841 | |
4842 | c\bco\bon\bnt\bti\bin\bnu\bue\be [_\bn] | |
4843 | Resume the next iteration of the enclosing f\bfo\bor\br, w\bwh\bhi\bil\ble\be, u\bun\bnt\bti\bil\bl, or | |
495aee44 | 4844 | s\bse\bel\ble\bec\bct\bt loop. If _\bn is specified, resume at the _\bnth enclosing |
8868edaf CR |
4845 | loop. _\bn must be >= 1. If _\bn is greater than the number of en- |
4846 | closing loops, the last enclosing loop (the ``top-level'' loop) | |
4847 | is resumed. The return value is 0 unless _\bn is not greater than | |
4848 | or equal to 1. | |
17345e5a | 4849 | |
8868edaf CR |
4850 | d\bde\bec\bcl\bla\bar\bre\be [-\b-a\baA\bAf\bfF\bFg\bgi\biI\bIl\bln\bnr\brt\btu\bux\bx] [-\b-p\bp] [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be] ...] |
4851 | t\bty\byp\bpe\bes\bse\bet\bt [-\b-a\baA\bAf\bfF\bFg\bgi\biI\bIl\bln\bnr\brt\btu\bux\bx] [-\b-p\bp] [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be] ...] | |
495aee44 CR |
4852 | Declare variables and/or give them attributes. If no _\bn_\ba_\bm_\bes are |
4853 | given then display the values of variables. The -\b-p\bp option will | |
17345e5a | 4854 | display the attributes and values of each _\bn_\ba_\bm_\be. When -\b-p\bp is used |
ac50fbac CR |
4855 | with _\bn_\ba_\bm_\be arguments, additional options, other than -\b-f\bf and -\b-F\bF, |
4856 | are ignored. When -\b-p\bp is supplied without _\bn_\ba_\bm_\be arguments, it | |
4857 | will display the attributes and values of all variables having | |
4858 | the attributes specified by the additional options. If no other | |
8868edaf CR |
4859 | options are supplied with -\b-p\bp, d\bde\bec\bcl\bla\bar\bre\be will display the at- |
4860 | tributes and values of all shell variables. The -\b-f\bf option will | |
4861 | restrict the display to shell functions. The -\b-F\bF option inhibits | |
4862 | the display of function definitions; only the function name and | |
4863 | attributes are printed. If the e\bex\bxt\btd\bde\beb\bbu\bug\bg shell option is enabled | |
4864 | using s\bsh\bho\bop\bpt\bt, the source file name and line number where each | |
4865 | _\bn_\ba_\bm_\be is defined are displayed as well. The -\b-F\bF option implies | |
4866 | -\b-f\bf. The -\b-g\bg option forces variables to be created or modified at | |
4867 | the global scope, even when d\bde\bec\bcl\bla\bar\bre\be is executed in a shell func- | |
4868 | tion. It is ignored in all other cases. The -\b-I\bI option causes | |
4869 | local variables to inherit the attributes (except the _\bn_\ba_\bm_\be_\br_\be_\bf | |
4870 | attribute) and value of any existing variable with the same _\bn_\ba_\bm_\be | |
4871 | at a surrounding scope. If there is no existing variable, the | |
4872 | local variable is initially unset. The following options can be | |
4873 | used to restrict output to variables with the specified attri- | |
4874 | bute or to give variables attributes: | |
0001803f | 4875 | -\b-a\ba Each _\bn_\ba_\bm_\be is an indexed array variable (see A\bAr\brr\bra\bay\bys\bs |
17345e5a | 4876 | above). |
0001803f | 4877 | -\b-A\bA Each _\bn_\ba_\bm_\be is an associative array variable (see A\bAr\brr\bra\bay\bys\bs |
17345e5a JA |
4878 | above). |
4879 | -\b-f\bf Use function names only. | |
4880 | -\b-i\bi The variable is treated as an integer; arithmetic evalua- | |
0001803f CR |
4881 | tion (see A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN above) is performed when |
4882 | the variable is assigned a value. | |
4883 | -\b-l\bl When the variable is assigned a value, all upper-case | |
4884 | characters are converted to lower-case. The upper-case | |
17345e5a | 4885 | attribute is disabled. |
ac50fbac CR |
4886 | -\b-n\bn Give each _\bn_\ba_\bm_\be the _\bn_\ba_\bm_\be_\br_\be_\bf attribute, making it a name |
4887 | reference to another variable. That other variable is | |
a0c0a00f CR |
4888 | defined by the value of _\bn_\ba_\bm_\be. All references, assign- |
4889 | ments, and attribute modifications to _\bn_\ba_\bm_\be, except those | |
4890 | using or changing the -\b-n\bn attribute itself, are performed | |
4891 | on the variable referenced by _\bn_\ba_\bm_\be's value. The nameref | |
4892 | attribute cannot be applied to array variables. | |
17345e5a JA |
4893 | -\b-r\br Make _\bn_\ba_\bm_\bes readonly. These names cannot then be assigned |
4894 | values by subsequent assignment statements or unset. | |
8868edaf CR |
4895 | -\b-t\bt Give each _\bn_\ba_\bm_\be the _\bt_\br_\ba_\bc_\be attribute. Traced functions in- |
4896 | herit the D\bDE\bEB\bBU\bUG\bG and R\bRE\bET\bTU\bUR\bRN\bN traps from the calling shell. | |
4897 | The trace attribute has no special meaning for variables. | |
4898 | -\b-u\bu When the variable is assigned a value, all lower-case | |
4899 | characters are converted to upper-case. The lower-case | |
17345e5a | 4900 | attribute is disabled. |
8868edaf CR |
4901 | -\b-x\bx Mark _\bn_\ba_\bm_\bes for export to subsequent commands via the en- |
4902 | vironment. | |
17345e5a | 4903 | |
8868edaf CR |
4904 | Using `+' instead of `-' turns off the attribute instead, with |
4905 | the exceptions that +\b+a\ba and +\b+A\bA may not be used to destroy array | |
4906 | variables and +\b+r\br will not remove the readonly attribute. When | |
d233b485 | 4907 | used in a function, d\bde\bec\bcl\bla\bar\bre\be and t\bty\byp\bpe\bes\bse\bet\bt make each _\bn_\ba_\bm_\be local, as |
8868edaf CR |
4908 | with the l\blo\boc\bca\bal\bl command, unless the -\b-g\bg option is supplied. If a |
4909 | variable name is followed by =_\bv_\ba_\bl_\bu_\be, the value of the variable | |
4910 | is set to _\bv_\ba_\bl_\bu_\be. When using -\b-a\ba or -\b-A\bA and the compound assign- | |
4911 | ment syntax to create array variables, additional attributes do | |
4912 | not take effect until subsequent assignments. The return value | |
d233b485 CR |
4913 | is 0 unless an invalid option is encountered, an attempt is made |
4914 | to define a function using ``-f foo=bar'', an attempt is made to | |
8868edaf CR |
4915 | assign a value to a readonly variable, an attempt is made to as- |
4916 | sign a value to an array variable without using the compound as- | |
4917 | signment syntax (see A\bAr\brr\bra\bay\bys\bs above), one of the _\bn_\ba_\bm_\be_\bs is not a | |
4918 | valid shell variable name, an attempt is made to turn off read- | |
4919 | only status for a readonly variable, an attempt is made to turn | |
ac50fbac CR |
4920 | off array status for an array variable, or an attempt is made to |
4921 | display a non-existent function with -\b-f\bf. | |
4922 | ||
4923 | d\bdi\bir\brs\bs [\b[-\b-c\bcl\blp\bpv\bv]\b] [\b[+\b+_\bn]\b] [\b[-\b-_\bn]\b] | |
8868edaf CR |
4924 | Without options, displays the list of currently remembered di- |
4925 | rectories. The default display is on a single line with direc- | |
4926 | tory names separated by spaces. Directories are added to the | |
4927 | list with the p\bpu\bus\bsh\bhd\bd command; the p\bpo\bop\bpd\bd command removes entries | |
4928 | from the list. The current directory is always the first direc- | |
4929 | tory in the stack. | |
4930 | -\b-c\bc Clears the directory stack by deleting all of the en- | |
4931 | tries. | |
4932 | -\b-l\bl Produces a listing using full pathnames; the default | |
ac50fbac | 4933 | listing format uses a tilde to denote the home directory. |
17345e5a | 4934 | -\b-p\bp Print the directory stack with one entry per line. |
8868edaf | 4935 | -\b-v\bv Print the directory stack with one entry per line, pre- |
17345e5a | 4936 | fixing each entry with its index in the stack. |
ac50fbac CR |
4937 | +\b+_\bn Displays the _\bnth entry counting from the left of the list |
4938 | shown by d\bdi\bir\brs\bs when invoked without options, starting with | |
4939 | zero. | |
8868edaf | 4940 | -\b-_\bn Displays the _\bnth entry counting from the right of the |
ac50fbac CR |
4941 | list shown by d\bdi\bir\brs\bs when invoked without options, starting |
4942 | with zero. | |
17345e5a | 4943 | |
8868edaf | 4944 | The return value is 0 unless an invalid option is supplied or _\bn |
17345e5a JA |
4945 | indexes beyond the end of the directory stack. |
4946 | ||
a0c0a00f | 4947 | d\bdi\bis\bso\bow\bwn\bn [-\b-a\bar\br] [-\b-h\bh] [_\bj_\bo_\bb_\bs_\bp_\be_\bc ... | _\bp_\bi_\bd ... ] |
8868edaf CR |
4948 | Without options, remove each _\bj_\bo_\bb_\bs_\bp_\be_\bc from the table of active |
4949 | jobs. If _\bj_\bo_\bb_\bs_\bp_\be_\bc is not present, and neither the -\b-a\ba nor the -\b-r\br | |
4950 | option is supplied, the _\bc_\bu_\br_\br_\be_\bn_\bt _\bj_\bo_\bb is used. If the -\b-h\bh option | |
4951 | is given, each _\bj_\bo_\bb_\bs_\bp_\be_\bc is not removed from the table, but is | |
4952 | marked so that S\bSI\bIG\bGH\bHU\bUP\bP is not sent to the job if the shell re- | |
4953 | ceives a S\bSI\bIG\bGH\bHU\bUP\bP. If no _\bj_\bo_\bb_\bs_\bp_\be_\bc is supplied, the -\b-a\ba option means | |
4954 | to remove or mark all jobs; the -\b-r\br option without a _\bj_\bo_\bb_\bs_\bp_\be_\bc ar- | |
4955 | gument restricts operation to running jobs. The return value is | |
4956 | 0 unless a _\bj_\bo_\bb_\bs_\bp_\be_\bc does not specify a valid job. | |
17345e5a JA |
4957 | |
4958 | e\bec\bch\bho\bo [-\b-n\bne\beE\bE] [_\ba_\br_\bg ...] | |
8868edaf CR |
4959 | Output the _\ba_\br_\bgs, separated by spaces, followed by a newline. |
4960 | The return status is 0 unless a write error occurs. If -\b-n\bn is | |
ac50fbac | 4961 | specified, the trailing newline is suppressed. If the -\b-e\be option |
8868edaf CR |
4962 | is given, interpretation of the following backslash-escaped |
4963 | characters is enabled. The -\b-E\bE option disables the interpreta- | |
4964 | tion of these escape characters, even on systems where they are | |
4965 | interpreted by default. The x\bxp\bpg\bg_\b_e\bec\bch\bho\bo shell option may be used | |
4966 | to dynamically determine whether or not e\bec\bch\bho\bo expands these es- | |
4967 | cape characters by default. e\bec\bch\bho\bo does not interpret -\b--\b- to mean | |
4968 | the end of options. e\bec\bch\bho\bo interprets the following escape se- | |
4969 | quences: | |
17345e5a JA |
4970 | \\b\a\ba alert (bell) |
4971 | \\b\b\bb backspace | |
4972 | \\b\c\bc suppress further output | |
495aee44 CR |
4973 | \\b\e\be |
4974 | \\b\E\bE an escape character | |
17345e5a JA |
4975 | \\b\f\bf form feed |
4976 | \\b\n\bn new line | |
4977 | \\b\r\br carriage return | |
4978 | \\b\t\bt horizontal tab | |
4979 | \\b\v\bv vertical tab | |
4980 | \\b\\\b\ backslash | |
8868edaf | 4981 | \\b\0\b0_\bn_\bn_\bn the eight-bit character whose value is the octal value |
17345e5a | 4982 | _\bn_\bn_\bn (zero to three octal digits) |
8868edaf | 4983 | \\b\x\bx_\bH_\bH the eight-bit character whose value is the hexadecimal |
17345e5a | 4984 | value _\bH_\bH (one or two hex digits) |
8868edaf | 4985 | \\b\u\bu_\bH_\bH_\bH_\bH the Unicode (ISO/IEC 10646) character whose value is the |
495aee44 CR |
4986 | hexadecimal value _\bH_\bH_\bH_\bH (one to four hex digits) |
4987 | \\b\U\bU_\bH_\bH_\bH_\bH_\bH_\bH_\bH_\bH | |
8868edaf | 4988 | the Unicode (ISO/IEC 10646) character whose value is the |
495aee44 | 4989 | hexadecimal value _\bH_\bH_\bH_\bH_\bH_\bH_\bH_\bH (one to eight hex digits) |
17345e5a JA |
4990 | |
4991 | e\ben\bna\bab\bbl\ble\be [-\b-a\ba] [-\b-d\bdn\bnp\bps\bs] [-\b-f\bf _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be] [_\bn_\ba_\bm_\be ...] | |
8868edaf | 4992 | Enable and disable builtin shell commands. Disabling a builtin |
17345e5a | 4993 | allows a disk command which has the same name as a shell builtin |
8868edaf CR |
4994 | to be executed without specifying a full pathname, even though |
4995 | the shell normally searches for builtins before disk commands. | |
4996 | If -\b-n\bn is used, each _\bn_\ba_\bm_\be is disabled; otherwise, _\bn_\ba_\bm_\be_\bs are en- | |
4997 | abled. For example, to use the t\bte\bes\bst\bt binary found via the P\bPA\bAT\bTH\bH | |
4998 | instead of the shell builtin version, run ``enable -n test''. | |
4999 | The -\b-f\bf option means to load the new builtin command _\bn_\ba_\bm_\be from | |
17345e5a | 5000 | shared object _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, on systems that support dynamic loading. |
74091dd4 CR |
5001 | Bash will use the value of the B\bBA\bAS\bSH\bH_\b_L\bLO\bOA\bAD\bDA\bAB\bBL\bLE\bES\bS_\b_P\bPA\bAT\bTH\bH variable as a |
5002 | colon-separated list of directories in which to search for _\bf_\bi_\bl_\be_\b- | |
5003 | _\bn_\ba_\bm_\be. The default is system-dependent. The -\b-d\bd option will | |
5004 | delete a builtin previously loaded with -\b-f\bf. If no _\bn_\ba_\bm_\be argu- | |
5005 | ments are given, or if the -\b-p\bp option is supplied, a list of | |
5006 | shell builtins is printed. With no other option arguments, the | |
5007 | list consists of all enabled shell builtins. If -\b-n\bn is supplied, | |
5008 | only disabled builtins are printed. If -\b-a\ba is supplied, the list | |
5009 | printed includes all builtins, with an indication of whether or | |
5010 | not each is enabled. If -\b-s\bs is supplied, the output is re- | |
5011 | stricted to the POSIX _\bs_\bp_\be_\bc_\bi_\ba_\bl builtins. If no options are sup- | |
5012 | plied and a _\bn_\ba_\bm_\be is not a shell builtin, e\ben\bna\bab\bbl\ble\be will attempt to | |
5013 | load _\bn_\ba_\bm_\be from a shared object named _\bn_\ba_\bm_\be, as if the command | |
5014 | were ``enable -f _\bn_\ba_\bm_\be _\bn_\ba_\bm_\be . The return value is 0 unless a | |
5015 | _\bn_\ba_\bm_\be is not a shell builtin or there is an error loading a new | |
5016 | builtin from a shared object. | |
17345e5a JA |
5017 | |
5018 | e\bev\bva\bal\bl [_\ba_\br_\bg ...] | |
8868edaf CR |
5019 | The _\ba_\br_\bgs are read and concatenated together into a single com- |
5020 | mand. This command is then read and executed by the shell, and | |
5021 | its exit status is returned as the value of e\bev\bva\bal\bl. If there are | |
17345e5a JA |
5022 | no _\ba_\br_\bg_\bs, or only null arguments, e\bev\bva\bal\bl returns 0. |
5023 | ||
5024 | e\bex\bxe\bec\bc [-\b-c\bcl\bl] [-\b-a\ba _\bn_\ba_\bm_\be] [_\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs]] | |
8868edaf CR |
5025 | If _\bc_\bo_\bm_\bm_\ba_\bn_\bd is specified, it replaces the shell. No new process |
5026 | is created. The _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs become the arguments to _\bc_\bo_\bm_\bm_\ba_\bn_\bd. If | |
17345e5a | 5027 | the -\b-l\bl option is supplied, the shell places a dash at the begin- |
8868edaf CR |
5028 | ning of the zeroth argument passed to _\bc_\bo_\bm_\bm_\ba_\bn_\bd. This is what _\bl_\bo_\b- |
5029 | _\bg_\bi_\bn(1) does. The -\b-c\bc option causes _\bc_\bo_\bm_\bm_\ba_\bn_\bd to be executed with | |
5030 | an empty environment. If -\b-a\ba is supplied, the shell passes _\bn_\ba_\bm_\be | |
17345e5a | 5031 | as the zeroth argument to the executed command. If _\bc_\bo_\bm_\bm_\ba_\bn_\bd can- |
8868edaf CR |
5032 | not be executed for some reason, a non-interactive shell exits, |
5033 | unless the e\bex\bxe\bec\bcf\bfa\bai\bil\bl shell option is enabled. In that case, it | |
5034 | returns failure. An interactive shell returns failure if the | |
5035 | file cannot be executed. A subshell exits unconditionally if | |
5036 | e\bex\bxe\bec\bc fails. If _\bc_\bo_\bm_\bm_\ba_\bn_\bd is not specified, any redirections take | |
5037 | effect in the current shell, and the return status is 0. If | |
d233b485 | 5038 | there is a redirection error, the return status is 1. |
17345e5a JA |
5039 | |
5040 | e\bex\bxi\bit\bt [_\bn] | |
8868edaf | 5041 | Cause the shell to exit with a status of _\bn. If _\bn is omitted, |
17345e5a JA |
5042 | the exit status is that of the last command executed. A trap on |
5043 | E\bEX\bXI\bIT\bT is executed before the shell terminates. | |
5044 | ||
5045 | e\bex\bxp\bpo\bor\brt\bt [-\b-f\bfn\bn] [_\bn_\ba_\bm_\be[=_\bw_\bo_\br_\bd]] ... | |
5046 | e\bex\bxp\bpo\bor\brt\bt -\b-p\bp | |
8868edaf CR |
5047 | The supplied _\bn_\ba_\bm_\be_\bs are marked for automatic export to the envi- |
5048 | ronment of subsequently executed commands. If the -\b-f\bf option is | |
5049 | given, the _\bn_\ba_\bm_\be_\bs refer to functions. If no _\bn_\ba_\bm_\be_\bs are given, or | |
5050 | if the -\b-p\bp option is supplied, a list of names of all exported | |
5051 | variables is printed. The -\b-n\bn option causes the export property | |
ac50fbac CR |
5052 | to be removed from each _\bn_\ba_\bm_\be. If a variable name is followed by |
5053 | =_\bw_\bo_\br_\bd, the value of the variable is set to _\bw_\bo_\br_\bd. e\bex\bxp\bpo\bor\brt\bt returns | |
5054 | an exit status of 0 unless an invalid option is encountered, one | |
8868edaf | 5055 | of the _\bn_\ba_\bm_\be_\bs is not a valid shell variable name, or -\b-f\bf is sup- |
ac50fbac | 5056 | plied with a _\bn_\ba_\bm_\be that is not a function. |
17345e5a JA |
5057 | |
5058 | f\bfc\bc [-\b-e\be _\be_\bn_\ba_\bm_\be] [-\b-l\bln\bnr\br] [_\bf_\bi_\br_\bs_\bt] [_\bl_\ba_\bs_\bt] | |
5059 | f\bfc\bc -\b-s\bs [_\bp_\ba_\bt=_\br_\be_\bp] [_\bc_\bm_\bd] | |
8868edaf CR |
5060 | The first form selects a range of commands from _\bf_\bi_\br_\bs_\bt to _\bl_\ba_\bs_\bt |
5061 | from the history list and displays or edits and re-executes | |
5062 | them. _\bF_\bi_\br_\bs_\bt and _\bl_\ba_\bs_\bt may be specified as a string (to locate | |
5063 | the last command beginning with that string) or as a number (an | |
5064 | index into the history list, where a negative number is used as | |
5065 | an offset from the current command number). When listing, a | |
5066 | _\bf_\bi_\br_\bs_\bt or _\bl_\ba_\bs_\bt of 0 is equivalent to -1 and -0 is equivalent to | |
5067 | the current command (usually the f\bfc\bc command); otherwise 0 is | |
5068 | equivalent to -1 and -0 is invalid. If _\bl_\ba_\bs_\bt is not specified, | |
5069 | it is set to the current command for listing (so that ``fc -l | |
5070 | -10'' prints the last 10 commands) and to _\bf_\bi_\br_\bs_\bt otherwise. If | |
5071 | _\bf_\bi_\br_\bs_\bt is not specified, it is set to the previous command for | |
5072 | editing and -16 for listing. | |
17345e5a | 5073 | |
d233b485 CR |
5074 | The -\b-n\bn option suppresses the command numbers when listing. The |
5075 | -\b-r\br option reverses the order of the commands. If the -\b-l\bl option | |
5076 | is given, the commands are listed on standard output. Other- | |
5077 | wise, the editor given by _\be_\bn_\ba_\bm_\be is invoked on a file containing | |
5078 | those commands. If _\be_\bn_\ba_\bm_\be is not given, the value of the F\bFC\bCE\bED\bDI\bIT\bT | |
5079 | variable is used, and the value of E\bED\bDI\bIT\bTO\bOR\bR if F\bFC\bCE\bED\bDI\bIT\bT is not set. | |
5080 | If neither variable is set, _\bv_\bi is used. When editing is com- | |
17345e5a JA |
5081 | plete, the edited commands are echoed and executed. |
5082 | ||
d233b485 CR |
5083 | In the second form, _\bc_\bo_\bm_\bm_\ba_\bn_\bd is re-executed after each instance |
5084 | of _\bp_\ba_\bt is replaced by _\br_\be_\bp. _\bC_\bo_\bm_\bm_\ba_\bn_\bd is interpreted the same as | |
5085 | _\bf_\bi_\br_\bs_\bt above. A useful alias to use with this is ``r="fc -s"'', | |
5086 | so that typing ``r cc'' runs the last command beginning with | |
ac50fbac | 5087 | ``cc'' and typing ``r'' re-executes the last command. |
17345e5a | 5088 | |
8868edaf CR |
5089 | If the first form is used, the return value is 0 unless an in- |
5090 | valid option is encountered or _\bf_\bi_\br_\bs_\bt or _\bl_\ba_\bs_\bt specify history | |
d233b485 | 5091 | lines out of range. If the -\b-e\be option is supplied, the return |
17345e5a JA |
5092 | value is the value of the last command executed or failure if an |
5093 | error occurs with the temporary file of commands. If the second | |
d233b485 CR |
5094 | form is used, the return status is that of the command re-exe- |
5095 | cuted, unless _\bc_\bm_\bd does not specify a valid history line, in | |
17345e5a JA |
5096 | which case f\bfc\bc returns failure. |
5097 | ||
5098 | f\bfg\bg [_\bj_\bo_\bb_\bs_\bp_\be_\bc] | |
d233b485 | 5099 | Resume _\bj_\bo_\bb_\bs_\bp_\be_\bc in the foreground, and make it the current job. |
17345e5a | 5100 | If _\bj_\bo_\bb_\bs_\bp_\be_\bc is not present, the shell's notion of the _\bc_\bu_\br_\br_\be_\bn_\bt _\bj_\bo_\bb |
d233b485 CR |
5101 | is used. The return value is that of the command placed into |
5102 | the foreground, or failure if run when job control is disabled | |
17345e5a | 5103 | or, when run with job control enabled, if _\bj_\bo_\bb_\bs_\bp_\be_\bc does not spec- |
d233b485 | 5104 | ify a valid job or _\bj_\bo_\bb_\bs_\bp_\be_\bc specifies a job that was started |
17345e5a JA |
5105 | without job control. |
5106 | ||
8868edaf | 5107 | g\bge\bet\bto\bop\bpt\bts\bs _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg _\bn_\ba_\bm_\be [_\ba_\br_\bg _\b._\b._\b.] |
d233b485 CR |
5108 | g\bge\bet\bto\bop\bpt\bts\bs is used by shell procedures to parse positional parame- |
5109 | ters. _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg contains the option characters to be recog- | |
8868edaf CR |
5110 | nized; if a character is followed by a colon, the option is ex- |
5111 | pected to have an argument, which should be separated from it by | |
5112 | white space. The colon and question mark characters may not be | |
5113 | used as option characters. Each time it is invoked, g\bge\bet\bto\bop\bpt\bts\bs | |
d233b485 | 5114 | places the next option in the shell variable _\bn_\ba_\bm_\be, initializing |
17345e5a JA |
5115 | _\bn_\ba_\bm_\be if it does not exist, and the index of the next argument to |
5116 | be processed into the variable O\bOP\bPT\bTI\bIN\bND\bD. O\bOP\bPT\bTI\bIN\bND\bD is initialized to | |
8868edaf CR |
5117 | 1 each time the shell or a shell script is invoked. When an op- |
5118 | tion requires an argument, g\bge\bet\bto\bop\bpt\bts\bs places that argument into the | |
5119 | variable O\bOP\bPT\bTA\bAR\bRG\bG. The shell does not reset O\bOP\bPT\bTI\bIN\bND\bD automatically; | |
5120 | it must be manually reset between multiple calls to g\bge\bet\bto\bop\bpt\bts\bs | |
5121 | within the same shell invocation if a new set of parameters is | |
5122 | to be used. | |
17345e5a | 5123 | |
8868edaf CR |
5124 | When the end of options is encountered, g\bge\bet\bto\bop\bpt\bts\bs exits with a re- |
5125 | turn value greater than zero. O\bOP\bPT\bTI\bIN\bND\bD is set to the index of the | |
5126 | first non-option argument, and _\bn_\ba_\bm_\be is set to ?. | |
17345e5a | 5127 | |
d233b485 | 5128 | g\bge\bet\bto\bop\bpt\bts\bs normally parses the positional parameters, but if more |
8868edaf CR |
5129 | arguments are supplied as _\ba_\br_\bg values, g\bge\bet\bto\bop\bpt\bts\bs parses those in- |
5130 | stead. | |
5131 | ||
5132 | g\bge\bet\bto\bop\bpt\bts\bs can report errors in two ways. If the first character | |
5133 | of _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg is a colon, _\bs_\bi_\bl_\be_\bn_\bt error reporting is used. In | |
5134 | normal operation, diagnostic messages are printed when invalid | |
5135 | options or missing option arguments are encountered. If the | |
5136 | variable O\bOP\bPT\bTE\bER\bRR\bR is set to 0, no error messages will be dis- | |
17345e5a JA |
5137 | played, even if the first character of _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg is not a colon. |
5138 | ||
5139 | If an invalid option is seen, g\bge\bet\bto\bop\bpt\bts\bs places ? into _\bn_\ba_\bm_\be and, if | |
8868edaf CR |
5140 | not silent, prints an error message and unsets O\bOP\bPT\bTA\bAR\bRG\bG. If |
5141 | g\bge\bet\bto\bop\bpt\bts\bs is silent, the option character found is placed in O\bOP\bP-\b- | |
5142 | T\bTA\bAR\bRG\bG and no diagnostic message is printed. | |
5143 | ||
5144 | If a required argument is not found, and g\bge\bet\bto\bop\bpt\bts\bs is not silent, | |
5145 | a question mark (?\b?) is placed in _\bn_\ba_\bm_\be, O\bOP\bPT\bTA\bAR\bRG\bG is unset, and a | |
5146 | diagnostic message is printed. If g\bge\bet\bto\bop\bpt\bts\bs is silent, then a | |
5147 | colon (:\b:) is placed in _\bn_\ba_\bm_\be and O\bOP\bPT\bTA\bAR\bRG\bG is set to the option | |
17345e5a JA |
5148 | character found. |
5149 | ||
8868edaf | 5150 | g\bge\bet\bto\bop\bpt\bts\bs returns true if an option, specified or unspecified, is |
17345e5a JA |
5151 | found. It returns false if the end of options is encountered or |
5152 | an error occurs. | |
5153 | ||
5154 | h\bha\bas\bsh\bh [-\b-l\blr\br] [-\b-p\bp _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be] [-\b-d\bdt\bt] [_\bn_\ba_\bm_\be] | |
495aee44 | 5155 | Each time h\bha\bas\bsh\bh is invoked, the full pathname of the command _\bn_\ba_\bm_\be |
8868edaf | 5156 | is determined by searching the directories in $\b$P\bPA\bAT\bTH\bH and remem- |
495aee44 CR |
5157 | bered. Any previously-remembered pathname is discarded. If the |
5158 | -\b-p\bp option is supplied, no path search is performed, and _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be | |
8868edaf CR |
5159 | is used as the full filename of the command. The -\b-r\br option |
5160 | causes the shell to forget all remembered locations. The -\b-d\bd op- | |
5161 | tion causes the shell to forget the remembered location of each | |
5162 | _\bn_\ba_\bm_\be. If the -\b-t\bt option is supplied, the full pathname to which | |
5163 | each _\bn_\ba_\bm_\be corresponds is printed. If multiple _\bn_\ba_\bm_\be arguments | |
5164 | are supplied with -\b-t\bt, the _\bn_\ba_\bm_\be is printed before the hashed full | |
5165 | pathname. The -\b-l\bl option causes output to be displayed in a for- | |
5166 | mat that may be reused as input. If no arguments are given, or | |
5167 | if only -\b-l\bl is supplied, information about remembered commands is | |
5168 | printed. The return status is true unless a _\bn_\ba_\bm_\be is not found | |
5169 | or an invalid option is supplied. | |
17345e5a JA |
5170 | |
5171 | h\bhe\bel\blp\bp [-\b-d\bdm\bms\bs] [_\bp_\ba_\bt_\bt_\be_\br_\bn] | |
8868edaf CR |
5172 | Display helpful information about builtin commands. If _\bp_\ba_\bt_\bt_\be_\br_\bn |
5173 | is specified, h\bhe\bel\blp\bp gives detailed help on all commands matching | |
5174 | _\bp_\ba_\bt_\bt_\be_\br_\bn; otherwise help for all the builtins and shell control | |
17345e5a JA |
5175 | structures is printed. |
5176 | -\b-d\bd Display a short description of each _\bp_\ba_\bt_\bt_\be_\br_\bn | |
0001803f | 5177 | -\b-m\bm Display the description of each _\bp_\ba_\bt_\bt_\be_\br_\bn in a manpage-like |
17345e5a JA |
5178 | format |
5179 | -\b-s\bs Display only a short usage synopsis for each _\bp_\ba_\bt_\bt_\be_\br_\bn | |
ac50fbac CR |
5180 | |
5181 | The return status is 0 unless no command matches _\bp_\ba_\bt_\bt_\be_\br_\bn. | |
17345e5a JA |
5182 | |
5183 | h\bhi\bis\bst\bto\bor\bry\by [\b[_\bn]\b] | |
5184 | h\bhi\bis\bst\bto\bor\bry\by -\b-c\bc | |
5185 | h\bhi\bis\bst\bto\bor\bry\by -\b-d\bd _\bo_\bf_\bf_\bs_\be_\bt | |
d233b485 | 5186 | h\bhi\bis\bst\bto\bor\bry\by -\b-d\bd _\bs_\bt_\ba_\br_\bt-_\be_\bn_\bd |
17345e5a JA |
5187 | h\bhi\bis\bst\bto\bor\bry\by -\b-a\ban\bnr\brw\bw [_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be] |
5188 | h\bhi\bis\bst\bto\bor\bry\by -\b-p\bp _\ba_\br_\bg [_\ba_\br_\bg _\b._\b._\b.] | |
5189 | h\bhi\bis\bst\bto\bor\bry\by -\b-s\bs _\ba_\br_\bg [_\ba_\br_\bg _\b._\b._\b.] | |
5190 | With no options, display the command history list with line num- | |
5191 | bers. Lines listed with a *\b* have been modified. An argument of | |
8868edaf CR |
5192 | _\bn lists only the last _\bn lines. If the shell variable H\bHI\bIS\bST\bTT\bTI\bIM\bME\bE-\b- |
5193 | F\bFO\bOR\bRM\bMA\bAT\bT is set and not null, it is used as a format string for | |
5194 | _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be(3) to display the time stamp associated with each dis- | |
5195 | played history entry. No intervening blank is printed between | |
5196 | the formatted time stamp and the history line. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is | |
5197 | supplied, it is used as the name of the history file; if not, | |
5198 | the value of H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE is used. Options, if supplied, have the | |
17345e5a JA |
5199 | following meanings: |
5200 | -\b-c\bc Clear the history list by deleting all the entries. | |
5201 | -\b-d\bd _\bo_\bf_\bf_\bs_\be_\bt | |
8868edaf | 5202 | Delete the history entry at position _\bo_\bf_\bf_\bs_\be_\bt. If _\bo_\bf_\bf_\bs_\be_\bt |
d233b485 CR |
5203 | is negative, it is interpreted as relative to one greater |
5204 | than the last history position, so negative indices count | |
8868edaf | 5205 | back from the end of the history, and an index of -1 |
d233b485 CR |
5206 | refers to the current h\bhi\bis\bst\bto\bor\bry\by -\b-d\bd command. |
5207 | -\b-d\bd _\bs_\bt_\ba_\br_\bt-_\be_\bn_\bd | |
74091dd4 CR |
5208 | Delete the range of history entries between positions |
5209 | _\bs_\bt_\ba_\br_\bt and _\be_\bn_\bd, inclusive. Positive and negative values | |
5210 | for _\bs_\bt_\ba_\br_\bt and _\be_\bn_\bd are interpreted as described above. | |
8868edaf CR |
5211 | -\b-a\ba Append the ``new'' history lines to the history file. |
5212 | These are history lines entered since the beginning of | |
a0c0a00f | 5213 | the current b\bba\bas\bsh\bh session, but not already appended to the |
17345e5a | 5214 | history file. |
8868edaf CR |
5215 | -\b-n\bn Read the history lines not already read from the history |
5216 | file into the current history list. These are lines ap- | |
5217 | pended to the history file since the beginning of the | |
17345e5a | 5218 | current b\bba\bas\bsh\bh session. |
8868edaf | 5219 | -\b-r\br Read the contents of the history file and append them to |
ac50fbac CR |
5220 | the current history list. |
5221 | -\b-w\bw Write the current history list to the history file, over- | |
5222 | writing the history file's contents. | |
8868edaf CR |
5223 | -\b-p\bp Perform history substitution on the following _\ba_\br_\bg_\bs and |
5224 | display the result on the standard output. Does not | |
5225 | store the results in the history list. Each _\ba_\br_\bg must be | |
17345e5a | 5226 | quoted to disable normal history expansion. |
8868edaf CR |
5227 | -\b-s\bs Store the _\ba_\br_\bg_\bs in the history list as a single entry. |
5228 | The last command in the history list is removed before | |
17345e5a JA |
5229 | the _\ba_\br_\bg_\bs are added. |
5230 | ||
8868edaf CR |
5231 | If the H\bHI\bIS\bST\bTT\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT variable is set, the time stamp informa- |
5232 | tion associated with each history entry is written to the his- | |
5233 | tory file, marked with the history comment character. When the | |
5234 | history file is read, lines beginning with the history comment | |
5235 | character followed immediately by a digit are interpreted as | |
a0c0a00f CR |
5236 | timestamps for the following history entry. The return value is |
5237 | 0 unless an invalid option is encountered, an error occurs while | |
74091dd4 CR |
5238 | reading or writing the history file, an invalid _\bo_\bf_\bf_\bs_\be_\bt or range |
5239 | is supplied as an argument to -\b-d\bd, or the history expansion sup- | |
5240 | plied as an argument to -\b-p\bp fails. | |
17345e5a JA |
5241 | |
5242 | j\bjo\bob\bbs\bs [-\b-l\bln\bnp\bpr\brs\bs] [ _\bj_\bo_\bb_\bs_\bp_\be_\bc ... ] | |
5243 | j\bjo\bob\bbs\bs -\b-x\bx _\bc_\bo_\bm_\bm_\ba_\bn_\bd [ _\ba_\br_\bg_\bs ... ] | |
5244 | The first form lists the active jobs. The options have the fol- | |
5245 | lowing meanings: | |
5246 | -\b-l\bl List process IDs in addition to the normal information. | |
8868edaf | 5247 | -\b-n\bn Display information only about jobs that have changed |
a0c0a00f | 5248 | status since the user was last notified of their status. |
8868edaf | 5249 | -\b-p\bp List only the process ID of the job's process group |
495aee44 | 5250 | leader. |
ac50fbac CR |
5251 | -\b-r\br Display only running jobs. |
5252 | -\b-s\bs Display only stopped jobs. | |
17345e5a | 5253 | |
8868edaf CR |
5254 | If _\bj_\bo_\bb_\bs_\bp_\be_\bc is given, output is restricted to information about |
5255 | that job. The return status is 0 unless an invalid option is | |
17345e5a JA |
5256 | encountered or an invalid _\bj_\bo_\bb_\bs_\bp_\be_\bc is supplied. |
5257 | ||
5258 | If the -\b-x\bx option is supplied, j\bjo\bob\bbs\bs replaces any _\bj_\bo_\bb_\bs_\bp_\be_\bc found in | |
8868edaf CR |
5259 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd or _\ba_\br_\bg_\bs with the corresponding process group ID, and ex- |
5260 | ecutes _\bc_\bo_\bm_\bm_\ba_\bn_\bd passing it _\ba_\br_\bg_\bs, returning its exit status. | |
17345e5a JA |
5261 | |
5262 | k\bki\bil\bll\bl [-\b-s\bs _\bs_\bi_\bg_\bs_\bp_\be_\bc | -\b-n\bn _\bs_\bi_\bg_\bn_\bu_\bm | -\b-_\bs_\bi_\bg_\bs_\bp_\be_\bc] [_\bp_\bi_\bd | _\bj_\bo_\bb_\bs_\bp_\be_\bc] ... | |
a0c0a00f | 5263 | k\bki\bil\bll\bl -\b-l\bl|-\b-L\bL [_\bs_\bi_\bg_\bs_\bp_\be_\bc | _\be_\bx_\bi_\bt_\b__\bs_\bt_\ba_\bt_\bu_\bs] |
8868edaf CR |
5264 | Send the signal named by _\bs_\bi_\bg_\bs_\bp_\be_\bc or _\bs_\bi_\bg_\bn_\bu_\bm to the processes |
5265 | named by _\bp_\bi_\bd or _\bj_\bo_\bb_\bs_\bp_\be_\bc. _\bs_\bi_\bg_\bs_\bp_\be_\bc is either a case-insensitive | |
5266 | signal name such as S\bSI\bIG\bGK\bKI\bIL\bLL\bL (with or without the S\bSI\bIG\bG prefix) or | |
5267 | a signal number; _\bs_\bi_\bg_\bn_\bu_\bm is a signal number. If _\bs_\bi_\bg_\bs_\bp_\be_\bc is not | |
5268 | present, then S\bSI\bIG\bGT\bTE\bER\bRM\bM is assumed. An argument of -\b-l\bl lists the | |
5269 | signal names. If any arguments are supplied when -\b-l\bl is given, | |
5270 | the names of the signals corresponding to the arguments are | |
17345e5a | 5271 | listed, and the return status is 0. The _\be_\bx_\bi_\bt_\b__\bs_\bt_\ba_\bt_\bu_\bs argument to |
8868edaf CR |
5272 | -\b-l\bl is a number specifying either a signal number or the exit |
5273 | status of a process terminated by a signal. The -\b-L\bL option is | |
5274 | equivalent to -\b-l\bl. k\bki\bil\bll\bl returns true if at least one signal was | |
5275 | successfully sent, or false if an error occurs or an invalid op- | |
5276 | tion is encountered. | |
17345e5a JA |
5277 | |
5278 | l\ble\bet\bt _\ba_\br_\bg [_\ba_\br_\bg ...] | |
5279 | Each _\ba_\br_\bg is an arithmetic expression to be evaluated (see A\bAR\bRI\bIT\bTH\bH-\b- | |
8868edaf | 5280 | M\bME\bET\bTI\bIC\bC E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN above). If the last _\ba_\br_\bg evaluates to 0, l\ble\bet\bt |
0001803f | 5281 | returns 1; 0 is returned otherwise. |
17345e5a | 5282 | |
a0c0a00f | 5283 | l\blo\boc\bca\bal\bl [_\bo_\bp_\bt_\bi_\bo_\bn] [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be] ... | - ] |
8868edaf CR |
5284 | For each argument, a local variable named _\bn_\ba_\bm_\be is created, and |
5285 | assigned _\bv_\ba_\bl_\bu_\be. The _\bo_\bp_\bt_\bi_\bo_\bn can be any of the options accepted | |
17345e5a | 5286 | by d\bde\bec\bcl\bla\bar\bre\be. When l\blo\boc\bca\bal\bl is used within a function, it causes the |
8868edaf CR |
5287 | variable _\bn_\ba_\bm_\be to have a visible scope restricted to that func- |
5288 | tion and its children. If _\bn_\ba_\bm_\be is -, the set of shell options | |
5289 | is made local to the function in which l\blo\boc\bca\bal\bl is invoked: shell | |
5290 | options changed using the s\bse\bet\bt builtin inside the function are | |
5291 | restored to their original values when the function returns. | |
5292 | The restore is effected as if a series of s\bse\bet\bt commands were exe- | |
5293 | cuted to restore the values that were in place before the func- | |
5294 | tion. With no operands, l\blo\boc\bca\bal\bl writes a list of local variables | |
5295 | to the standard output. It is an error to use l\blo\boc\bca\bal\bl when not | |
5296 | within a function. The return status is 0 unless l\blo\boc\bca\bal\bl is used | |
5297 | outside a function, an invalid _\bn_\ba_\bm_\be is supplied, or _\bn_\ba_\bm_\be is a | |
5298 | readonly variable. | |
17345e5a JA |
5299 | |
5300 | l\blo\bog\bgo\bou\but\bt Exit a login shell. | |
5301 | ||
8868edaf | 5302 | m\bma\bap\bpf\bfi\bil\ble\be [-\b-d\bd _\bd_\be_\bl_\bi_\bm] [-\b-n\bn _\bc_\bo_\bu_\bn_\bt] [-\b-O\bO _\bo_\br_\bi_\bg_\bi_\bn] [-\b-s\bs _\bc_\bo_\bu_\bn_\bt] [-\b-t\bt] [-\b-u\bu _\bf_\bd] [-\b-C\bC |
a0c0a00f CR |
5303 | _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk] [-\b-c\bc _\bq_\bu_\ba_\bn_\bt_\bu_\bm] [_\ba_\br_\br_\ba_\by] |
5304 | r\bre\bea\bad\bda\bar\brr\bra\bay\by [-\b-d\bd _\bd_\be_\bl_\bi_\bm] [-\b-n\bn _\bc_\bo_\bu_\bn_\bt] [-\b-O\bO _\bo_\br_\bi_\bg_\bi_\bn] [-\b-s\bs _\bc_\bo_\bu_\bn_\bt] [-\b-t\bt] [-\b-u\bu _\bf_\bd] [-\b-C\bC | |
5305 | _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk] [-\b-c\bc _\bq_\bu_\ba_\bn_\bt_\bu_\bm] [_\ba_\br_\br_\ba_\by] | |
8868edaf CR |
5306 | Read lines from the standard input into the indexed array vari- |
5307 | able _\ba_\br_\br_\ba_\by, or from file descriptor _\bf_\bd if the -\b-u\bu option is sup- | |
5308 | plied. The variable M\bMA\bAP\bPF\bFI\bIL\bLE\bE is the default _\ba_\br_\br_\ba_\by. Options, if | |
0001803f | 5309 | supplied, have the following meanings: |
8868edaf CR |
5310 | -\b-d\bd The first character of _\bd_\be_\bl_\bi_\bm is used to terminate each |
5311 | input line, rather than newline. If _\bd_\be_\bl_\bi_\bm is the empty | |
d233b485 CR |
5312 | string, m\bma\bap\bpf\bfi\bil\ble\be will terminate a line when it reads a NUL |
5313 | character. | |
8868edaf | 5314 | -\b-n\bn Copy at most _\bc_\bo_\bu_\bn_\bt lines. If _\bc_\bo_\bu_\bn_\bt is 0, all lines are |
17345e5a | 5315 | copied. |
8868edaf | 5316 | -\b-O\bO Begin assigning to _\ba_\br_\br_\ba_\by at index _\bo_\br_\bi_\bg_\bi_\bn. The default |
17345e5a JA |
5317 | index is 0. |
5318 | -\b-s\bs Discard the first _\bc_\bo_\bu_\bn_\bt lines read. | |
8868edaf | 5319 | -\b-t\bt Remove a trailing _\bd_\be_\bl_\bi_\bm (default newline) from each line |
a0c0a00f | 5320 | read. |
8868edaf | 5321 | -\b-u\bu Read lines from file descriptor _\bf_\bd instead of the stan- |
17345e5a | 5322 | dard input. |
8868edaf | 5323 | -\b-C\bC Evaluate _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk each time _\bq_\bu_\ba_\bn_\bt_\bu_\bm lines are read. The |
17345e5a | 5324 | -\b-c\bc option specifies _\bq_\bu_\ba_\bn_\bt_\bu_\bm. |
8868edaf | 5325 | -\b-c\bc Specify the number of lines read between each call to |
17345e5a JA |
5326 | _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk. |
5327 | ||
8868edaf | 5328 | If -\b-C\bC is specified without -\b-c\bc, the default quantum is 5000. |
17345e5a | 5329 | When _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk is evaluated, it is supplied the index of the next |
495aee44 | 5330 | array element to be assigned and the line to be assigned to that |
8868edaf | 5331 | element as additional arguments. _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk is evaluated after |
495aee44 | 5332 | the line is read but before the array element is assigned. |
17345e5a | 5333 | |
8868edaf CR |
5334 | If not supplied with an explicit origin, m\bma\bap\bpf\bfi\bil\ble\be will clear _\ba_\br_\b- |
5335 | _\br_\ba_\by before assigning to it. | |
17345e5a | 5336 | |
8868edaf CR |
5337 | m\bma\bap\bpf\bfi\bil\ble\be returns successfully unless an invalid option or option |
5338 | argument is supplied, _\ba_\br_\br_\ba_\by is invalid or unassignable, or if | |
0001803f | 5339 | _\ba_\br_\br_\ba_\by is not an indexed array. |
17345e5a JA |
5340 | |
5341 | p\bpo\bop\bpd\bd [-n\bn] [+_\bn] [-_\bn] | |
74091dd4 CR |
5342 | Removes entries from the directory stack. The elements are num- |
5343 | bered from 0 starting at the first directory listed by d\bdi\bir\brs\bs. | |
5344 | With no arguments, p\bpo\bop\bpd\bd removes the top directory from the | |
5345 | stack, and changes to the new top directory. Arguments, if sup- | |
5346 | plied, have the following meanings: | |
5347 | -\b-n\bn Suppresses the normal change of directory when removing | |
8868edaf CR |
5348 | directories from the stack, so that only the stack is ma- |
5349 | nipulated. | |
74091dd4 CR |
5350 | +\b+_\bn Removes the _\bnth entry counting from the left of the list |
5351 | shown by d\bdi\bir\brs\bs, starting with zero, from the stack. For | |
5352 | example: ``popd +0'' removes the first directory, ``popd | |
5353 | +1'' the second. | |
17345e5a | 5354 | -\b-_\bn Removes the _\bnth entry counting from the right of the list |
8868edaf CR |
5355 | shown by d\bdi\bir\brs\bs, starting with zero. For example: ``popd |
5356 | -0'' removes the last directory, ``popd -1'' the next to | |
17345e5a JA |
5357 | last. |
5358 | ||
74091dd4 CR |
5359 | If the top element of the directory stack is modified, and the |
5360 | _\b-_\bn option was not supplied, p\bpo\bop\bpd\bd uses the c\bcd\bd builtin to change | |
5361 | to the directory at the top of the stack. If the c\bcd\bd fails, p\bpo\bop\bpd\bd | |
5362 | returns a non-zero value. | |
5363 | ||
5364 | Otherwise, p\bpo\bop\bpd\bd returns false if an invalid option is encoun- | |
5365 | tered, the directory stack is empty, or a non-existent directory | |
5366 | stack entry is specified. | |
5367 | ||
5368 | If the p\bpo\bop\bpd\bd command is successful, bash runs d\bdi\bir\brs\bs to show the | |
5369 | final contents of the directory stack, and the return status is | |
5370 | 0. | |
17345e5a JA |
5371 | |
5372 | p\bpr\bri\bin\bnt\btf\bf [-\b-v\bv _\bv_\ba_\br] _\bf_\bo_\br_\bm_\ba_\bt [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs] | |
74091dd4 CR |
5373 | Write the formatted _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs to the standard output under the |
5374 | control of the _\bf_\bo_\br_\bm_\ba_\bt. The -\b-v\bv option causes the output to be | |
5375 | assigned to the variable _\bv_\ba_\br rather than being printed to the | |
495aee44 CR |
5376 | standard output. |
5377 | ||
74091dd4 CR |
5378 | The _\bf_\bo_\br_\bm_\ba_\bt is a character string which contains three types of |
5379 | objects: plain characters, which are simply copied to standard | |
5380 | output, character escape sequences, which are converted and | |
5381 | copied to the standard output, and format specifications, each | |
5382 | of which causes printing of the next successive _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt. In | |
495aee44 CR |
5383 | addition to the standard _\bp_\br_\bi_\bn_\bt_\bf(1) format specifications, p\bpr\bri\bin\bnt\btf\bf |
5384 | interprets the following extensions: | |
5385 | %\b%b\bb causes p\bpr\bri\bin\bnt\btf\bf to expand backslash escape sequences in the | |
a0c0a00f | 5386 | corresponding _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt in the same way as e\bec\bch\bho\bo -\b-e\be. |
74091dd4 | 5387 | %\b%q\bq causes p\bpr\bri\bin\bnt\btf\bf to output the corresponding _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt in a |
495aee44 | 5388 | format that can be reused as shell input. |
74091dd4 CR |
5389 | %\b%Q\bQ like %\b%q\bq, but applies any supplied precision to the _\ba_\br_\bg_\bu_\b- |
5390 | _\bm_\be_\bn_\bt before quoting it. | |
495aee44 | 5391 | %\b%(\b(_\bd_\ba_\bt_\be_\bf_\bm_\bt)\b)T\bT |
8868edaf CR |
5392 | causes p\bpr\bri\bin\bnt\btf\bf to output the date-time string resulting |
5393 | from using _\bd_\ba_\bt_\be_\bf_\bm_\bt as a format string for _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be(3). | |
495aee44 | 5394 | The corresponding _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt is an integer representing the |
8868edaf CR |
5395 | number of seconds since the epoch. Two special argument |
5396 | values may be used: -1 represents the current time, and | |
5397 | -2 represents the time the shell was invoked. If no ar- | |
5398 | gument is specified, conversion behaves as if -1 had been | |
5399 | given. This is an exception to the usual p\bpr\bri\bin\bnt\btf\bf behav- | |
5400 | ior. | |
5401 | ||
5402 | The %b, %q, and %T directives all use the field width and preci- | |
5403 | sion arguments from the format specification and write that many | |
5404 | bytes from (or use that wide a field for) the expanded argument, | |
5405 | which usually contains more characters than the original. | |
495aee44 | 5406 | |
d233b485 | 5407 | Arguments to non-string format specifiers are treated as C con- |
495aee44 | 5408 | stants, except that a leading plus or minus sign is allowed, and |
d233b485 | 5409 | if the leading character is a single or double quote, the value |
495aee44 | 5410 | is the ASCII value of the following character. |
17345e5a | 5411 | |
d233b485 | 5412 | The _\bf_\bo_\br_\bm_\ba_\bt is reused as necessary to consume all of the _\ba_\br_\bg_\bu_\b- |
17345e5a | 5413 | _\bm_\be_\bn_\bt_\bs. If the _\bf_\bo_\br_\bm_\ba_\bt requires more _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs than are supplied, |
d233b485 CR |
5414 | the extra format specifications behave as if a zero value or |
5415 | null string, as appropriate, had been supplied. The return | |
17345e5a JA |
5416 | value is zero on success, non-zero on failure. |
5417 | ||
5418 | p\bpu\bus\bsh\bhd\bd [-\b-n\bn] [+_\bn] [-_\bn] | |
5419 | p\bpu\bus\bsh\bhd\bd [-\b-n\bn] [_\bd_\bi_\br] | |
d233b485 CR |
5420 | Adds a directory to the top of the directory stack, or rotates |
5421 | the stack, making the new top of the stack the current working | |
74091dd4 CR |
5422 | directory. With no arguments, p\bpu\bus\bsh\bhd\bd exchanges the top two ele- |
5423 | ments of the directory stack. Arguments, if supplied, have the | |
5424 | following meanings: | |
d233b485 CR |
5425 | -\b-n\bn Suppresses the normal change of directory when rotating |
5426 | or adding directories to the stack, so that only the | |
a0c0a00f | 5427 | stack is manipulated. |
d233b485 CR |
5428 | +\b+_\bn Rotates the stack so that the _\bnth directory (counting |
5429 | from the left of the list shown by d\bdi\bir\brs\bs, starting with | |
17345e5a | 5430 | zero) is at the top. |
d233b485 CR |
5431 | -\b-_\bn Rotates the stack so that the _\bnth directory (counting |
5432 | from the right of the list shown by d\bdi\bir\brs\bs, starting with | |
17345e5a | 5433 | zero) is at the top. |
74091dd4 CR |
5434 | _\bd_\bi_\br Adds _\bd_\bi_\br to the directory stack at the top |
5435 | ||
5436 | After the stack has been modified, if the -\b-n\bn option was not sup- | |
5437 | plied, p\bpu\bus\bsh\bhd\bd uses the c\bcd\bd builtin to change to the directory at | |
5438 | the top of the stack. If the c\bcd\bd fails, p\bpu\bus\bsh\bhd\bd returns a non-zero | |
5439 | value. | |
5440 | ||
5441 | Otherwise, if no arguments are supplied, p\bpu\bus\bsh\bhd\bd returns 0 unless | |
5442 | the directory stack is empty. When rotating the directory | |
5443 | stack, p\bpu\bus\bsh\bhd\bd returns 0 unless the directory stack is empty or a | |
5444 | non-existent directory stack element is specified. | |
17345e5a | 5445 | |
74091dd4 CR |
5446 | If the p\bpu\bus\bsh\bhd\bd command is successful, bash runs d\bdi\bir\brs\bs to show the |
5447 | final contents of the directory stack. | |
17345e5a JA |
5448 | |
5449 | p\bpw\bwd\bd [-\b-L\bLP\bP] | |
d233b485 | 5450 | Print the absolute pathname of the current working directory. |
17345e5a JA |
5451 | The pathname printed contains no symbolic links if the -\b-P\bP option |
5452 | is supplied or the -\b-o\bo p\bph\bhy\bys\bsi\bic\bca\bal\bl option to the s\bse\bet\bt builtin command | |
d233b485 CR |
5453 | is enabled. If the -\b-L\bL option is used, the pathname printed may |
5454 | contain symbolic links. The return status is 0 unless an error | |
8868edaf CR |
5455 | occurs while reading the name of the current directory or an in- |
5456 | valid option is supplied. | |
17345e5a | 5457 | |
0001803f CR |
5458 | r\bre\bea\bad\bd [-\b-e\ber\brs\bs] [-\b-a\ba _\ba_\bn_\ba_\bm_\be] [-\b-d\bd _\bd_\be_\bl_\bi_\bm] [-\b-i\bi _\bt_\be_\bx_\bt] [-\b-n\bn _\bn_\bc_\bh_\ba_\br_\bs] [-\b-N\bN _\bn_\bc_\bh_\ba_\br_\bs] [-\b-p\bp |
5459 | _\bp_\br_\bo_\bm_\bp_\bt] [-\b-t\bt _\bt_\bi_\bm_\be_\bo_\bu_\bt] [-\b-u\bu _\bf_\bd] [_\bn_\ba_\bm_\be ...] | |
8868edaf CR |
5460 | One line is read from the standard input, or from the file de- |
5461 | scriptor _\bf_\bd supplied as an argument to the -\b-u\bu option, split into | |
5462 | words as described above under W\bWo\bor\brd\bd S\bSp\bpl\bli\bit\btt\bti\bin\bng\bg, and the first | |
5463 | word is assigned to the first _\bn_\ba_\bm_\be, the second word to the sec- | |
5464 | ond _\bn_\ba_\bm_\be, and so on. If there are more words than names, the | |
a0c0a00f | 5465 | remaining words and their intervening delimiters are assigned to |
d233b485 CR |
5466 | the last _\bn_\ba_\bm_\be. If there are fewer words read from the input |
5467 | stream than names, the remaining names are assigned empty val- | |
5468 | ues. The characters in I\bIF\bFS\bS are used to split the line into | |
8868edaf CR |
5469 | words using the same rules the shell uses for expansion (de- |
5470 | scribed above under W\bWo\bor\brd\bd S\bSp\bpl\bli\bit\btt\bti\bin\bng\bg). The backslash character | |
a0c0a00f | 5471 | (\\b\) may be used to remove any special meaning for the next char- |
d233b485 | 5472 | acter read and for line continuation. Options, if supplied, |
a0c0a00f | 5473 | have the following meanings: |
17345e5a JA |
5474 | -\b-a\ba _\ba_\bn_\ba_\bm_\be |
5475 | The words are assigned to sequential indices of the array | |
5476 | variable _\ba_\bn_\ba_\bm_\be, starting at 0. _\ba_\bn_\ba_\bm_\be is unset before any | |
8868edaf CR |
5477 | new values are assigned. Other _\bn_\ba_\bm_\be arguments are ig- |
5478 | nored. | |
17345e5a | 5479 | -\b-d\bd _\bd_\be_\bl_\bi_\bm |
8868edaf CR |
5480 | The first character of _\bd_\be_\bl_\bi_\bm is used to terminate the in- |
5481 | put line, rather than newline. If _\bd_\be_\bl_\bi_\bm is the empty | |
d233b485 CR |
5482 | string, r\bre\bea\bad\bd will terminate a line when it reads a NUL |
5483 | character. | |
17345e5a | 5484 | -\b-e\be If the standard input is coming from a terminal, r\bre\bea\bad\bdl\bli\bin\bne\be |
d233b485 CR |
5485 | (see R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE above) is used to obtain the line. Read- |
5486 | line uses the current (or default, if line editing was | |
74091dd4 | 5487 | not previously active) editing settings, but uses read- |
d233b485 | 5488 | line's default filename completion. |
17345e5a | 5489 | -\b-i\bi _\bt_\be_\bx_\bt |
ac50fbac | 5490 | If r\bre\bea\bad\bdl\bli\bin\bne\be is being used to read the line, _\bt_\be_\bx_\bt is |
17345e5a JA |
5491 | placed into the editing buffer before editing begins. |
5492 | -\b-n\bn _\bn_\bc_\bh_\ba_\br_\bs | |
ac50fbac | 5493 | r\bre\bea\bad\bd returns after reading _\bn_\bc_\bh_\ba_\br_\bs characters rather than |
a0c0a00f | 5494 | waiting for a complete line of input, but honors a delim- |
ac50fbac | 5495 | iter if fewer than _\bn_\bc_\bh_\ba_\br_\bs characters are read before the |
0001803f CR |
5496 | delimiter. |
5497 | -\b-N\bN _\bn_\bc_\bh_\ba_\br_\bs | |
ac50fbac CR |
5498 | r\bre\bea\bad\bd returns after reading exactly _\bn_\bc_\bh_\ba_\br_\bs characters |
5499 | rather than waiting for a complete line of input, unless | |
5500 | EOF is encountered or r\bre\bea\bad\bd times out. Delimiter charac- | |
5501 | ters encountered in the input are not treated specially | |
5502 | and do not cause r\bre\bea\bad\bd to return until _\bn_\bc_\bh_\ba_\br_\bs characters | |
a0c0a00f CR |
5503 | are read. The result is not split on the characters in |
5504 | I\bIF\bFS\bS; the intent is that the variable is assigned exactly | |
5505 | the characters read (with the exception of backslash; see | |
5506 | the -\b-r\br option below). | |
17345e5a JA |
5507 | -\b-p\bp _\bp_\br_\bo_\bm_\bp_\bt |
5508 | Display _\bp_\br_\bo_\bm_\bp_\bt on standard error, without a trailing new- | |
5509 | line, before attempting to read any input. The prompt is | |
5510 | displayed only if input is coming from a terminal. | |
5511 | -\b-r\br Backslash does not act as an escape character. The back- | |
a0c0a00f | 5512 | slash is considered to be part of the line. In particu- |
d233b485 CR |
5513 | lar, a backslash-newline pair may not then be used as a |
5514 | line continuation. | |
17345e5a JA |
5515 | -\b-s\bs Silent mode. If input is coming from a terminal, charac- |
5516 | ters are not echoed. | |
5517 | -\b-t\bt _\bt_\bi_\bm_\be_\bo_\bu_\bt | |
a0c0a00f CR |
5518 | Cause r\bre\bea\bad\bd to time out and return failure if a complete |
5519 | line of input (or a specified number of characters) is | |
5520 | not read within _\bt_\bi_\bm_\be_\bo_\bu_\bt seconds. _\bt_\bi_\bm_\be_\bo_\bu_\bt may be a deci- | |
5521 | mal number with a fractional portion following the deci- | |
5522 | mal point. This option is only effective if r\bre\bea\bad\bd is | |
5523 | reading input from a terminal, pipe, or other special | |
5524 | file; it has no effect when reading from regular files. | |
ac50fbac | 5525 | If r\bre\bea\bad\bd times out, r\bre\bea\bad\bd saves any partial input read into |
8868edaf CR |
5526 | the specified variable _\bn_\ba_\bm_\be. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is 0, r\bre\bea\bad\bd re- |
5527 | turns immediately, without trying to read any data. The | |
5528 | exit status is 0 if input is available on the specified | |
74091dd4 CR |
5529 | file descriptor, or the read will return EOF, non-zero |
5530 | otherwise. The exit status is greater than 128 if the | |
5531 | timeout is exceeded. | |
17345e5a JA |
5532 | -\b-u\bu _\bf_\bd Read input from file descriptor _\bf_\bd. |
5533 | ||
74091dd4 CR |
5534 | If no _\bn_\ba_\bm_\be_\bs are supplied, the line read, without the ending de- |
5535 | limiter but otherwise unmodified, is assigned to the variable | |
5536 | R\bRE\bEP\bPL\bLY\bY. The exit status is zero, unless end-of-file is encoun- | |
5537 | tered, r\bre\bea\bad\bd times out (in which case the status is greater than | |
5538 | 128), a variable assignment error (such as assigning to a read- | |
8868edaf CR |
5539 | only variable) occurs, or an invalid file descriptor is supplied |
5540 | as the argument to -\b-u\bu. | |
ac50fbac CR |
5541 | |
5542 | r\bre\bea\bad\bdo\bon\bnl\bly\by [-\b-a\baA\bAf\bf] [-\b-p\bp] [_\bn_\ba_\bm_\be[=_\bw_\bo_\br_\bd] ...] | |
74091dd4 CR |
5543 | The given _\bn_\ba_\bm_\be_\bs are marked readonly; the values of these _\bn_\ba_\bm_\be_\bs |
5544 | may not be changed by subsequent assignment. If the -\b-f\bf option | |
5545 | is supplied, the functions corresponding to the _\bn_\ba_\bm_\be_\bs are so | |
5546 | marked. The -\b-a\ba option restricts the variables to indexed ar- | |
5547 | rays; the -\b-A\bA option restricts the variables to associative ar- | |
8868edaf | 5548 | rays. If both options are supplied, -\b-A\bA takes precedence. If no |
74091dd4 | 5549 | _\bn_\ba_\bm_\be arguments are given, or if the -\b-p\bp option is supplied, a |
ac50fbac | 5550 | list of all readonly names is printed. The other options may be |
74091dd4 CR |
5551 | used to restrict the output to a subset of the set of readonly |
5552 | names. The -\b-p\bp option causes output to be displayed in a format | |
5553 | that may be reused as input. If a variable name is followed by | |
5554 | =_\bw_\bo_\br_\bd, the value of the variable is set to _\bw_\bo_\br_\bd. The return | |
5555 | status is 0 unless an invalid option is encountered, one of the | |
ac50fbac CR |
5556 | _\bn_\ba_\bm_\be_\bs is not a valid shell variable name, or -\b-f\bf is supplied with |
5557 | a _\bn_\ba_\bm_\be that is not a function. | |
17345e5a JA |
5558 | |
5559 | r\bre\bet\btu\bur\brn\bn [_\bn] | |
74091dd4 CR |
5560 | Causes a function to stop executing and return the value speci- |
5561 | fied by _\bn to its caller. If _\bn is omitted, the return status is | |
5562 | that of the last command executed in the function body. If r\bre\be-\b- | |
8868edaf | 5563 | t\btu\bur\brn\bn is executed by a trap handler, the last command used to de- |
74091dd4 CR |
5564 | termine the status is the last command executed before the trap |
5565 | handler. If r\bre\bet\btu\bur\brn\bn is executed during a D\bDE\bEB\bBU\bUG\bG trap, the last | |
5566 | command used to determine the status is the last command exe- | |
5567 | cuted by the trap handler before r\bre\bet\btu\bur\brn\bn was invoked. If r\bre\bet\btu\bur\brn\bn | |
5568 | is used outside a function, but during execution of a script by | |
5569 | the .\b. (s\bso\bou\bur\brc\bce\be) command, it causes the shell to stop executing | |
5570 | that script and return either _\bn or the exit status of the last | |
5571 | command executed within the script as the exit status of the | |
8868edaf | 5572 | script. If _\bn is supplied, the return value is its least signif- |
74091dd4 CR |
5573 | icant 8 bits. The return status is non-zero if r\bre\bet\btu\bur\brn\bn is sup- |
5574 | plied a non-numeric argument, or is used outside a function and | |
5575 | not during execution of a script by .\b. or s\bso\bou\bur\brc\bce\be. Any command | |
8868edaf CR |
5576 | associated with the R\bRE\bET\bTU\bUR\bRN\bN trap is executed before execution re- |
5577 | sumes after the function or script. | |
17345e5a | 5578 | |
74091dd4 CR |
5579 | s\bse\bet\bt [-\b-a\bab\bbe\bef\bfh\bhk\bkm\bmn\bnp\bpt\btu\buv\bvx\bxB\bBC\bCE\bEH\bHP\bPT\bT] [-\b-o\bo _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be] [-\b--\b-] [-\b-] [_\ba_\br_\bg ...] |
5580 | s\bse\bet\bt [+\b+a\bab\bbe\bef\bfh\bhk\bkm\bmn\bnp\bpt\btu\buv\bvx\bxB\bBC\bCE\bEH\bHP\bPT\bT] [+\b+o\bo _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be] [-\b--\b-] [-\b-] [_\ba_\br_\bg ...] | |
5581 | Without options, display the name and value of each shell vari- | |
5582 | able in a format that can be reused as input for setting or re- | |
5583 | setting the currently-set variables. Read-only variables cannot | |
5584 | be reset. In _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, only shell variables are listed. The | |
5585 | output is sorted according to the current locale. When options | |
5586 | are specified, they set or unset shell attributes. Any argu- | |
5587 | ments remaining after option processing are treated as values | |
5588 | for the positional parameters and are assigned, in order, to $\b$1\b1, | |
5589 | $\b$2\b2, .\b..\b..\b. $\b$_\bn. Options, if specified, have the following mean- | |
5590 | ings: | |
a0c0a00f | 5591 | -\b-a\ba Each variable or function that is created or modified is |
74091dd4 | 5592 | given the export attribute and marked for export to the |
a0c0a00f | 5593 | environment of subsequent commands. |
74091dd4 | 5594 | -\b-b\bb Report the status of terminated background jobs immedi- |
17345e5a JA |
5595 | ately, rather than before the next primary prompt. This |
5596 | is effective only when job control is enabled. | |
74091dd4 CR |
5597 | -\b-e\be Exit immediately if a _\bp_\bi_\bp_\be_\bl_\bi_\bn_\be (which may consist of a |
5598 | single _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd), a _\bl_\bi_\bs_\bt, or a _\bc_\bo_\bm_\bp_\bo_\bu_\bn_\bd _\bc_\bo_\bm_\bm_\ba_\bn_\bd | |
a0c0a00f | 5599 | (see S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR above), exits with a non-zero status. |
74091dd4 CR |
5600 | The shell does not exit if the command that fails is |
5601 | part of the command list immediately following a w\bwh\bhi\bil\ble\be | |
5602 | or u\bun\bnt\bti\bil\bl keyword, part of the test following the i\bif\bf or | |
5603 | e\bel\bli\bif\bf reserved words, part of any command executed in a | |
5604 | &\b&&\b& or |\b||\b| list except the command following the final &\b&&\b& | |
a0c0a00f | 5605 | or |\b||\b|, any command in a pipeline but the last, or if the |
74091dd4 CR |
5606 | command's return value is being inverted with !\b!. If a |
5607 | compound command other than a subshell returns a non- | |
5608 | zero status because a command failed while -\b-e\be was being | |
5609 | ignored, the shell does not exit. A trap on E\bER\bRR\bR, if | |
5610 | set, is executed before the shell exits. This option | |
0001803f | 5611 | applies to the shell environment and each subshell envi- |
74091dd4 | 5612 | ronment separately (see C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN E\bEN\bNV\bVI\bIR\bRO\bON\bNM\bME\bEN\bNT\bT |
0001803f CR |
5613 | above), and may cause subshells to exit before executing |
5614 | all the commands in the subshell. | |
ac50fbac | 5615 | |
74091dd4 CR |
5616 | If a compound command or shell function executes in a |
5617 | context where -\b-e\be is being ignored, none of the commands | |
5618 | executed within the compound command or function body | |
5619 | will be affected by the -\b-e\be setting, even if -\b-e\be is set | |
5620 | and a command returns a failure status. If a compound | |
5621 | command or shell function sets -\b-e\be while executing in a | |
5622 | context where -\b-e\be is ignored, that setting will not have | |
5623 | any effect until the compound command or the command | |
ac50fbac | 5624 | containing the function call completes. |
17345e5a | 5625 | -\b-f\bf Disable pathname expansion. |
74091dd4 | 5626 | -\b-h\bh Remember the location of commands as they are looked up |
17345e5a | 5627 | for execution. This is enabled by default. |
74091dd4 CR |
5628 | -\b-k\bk All arguments in the form of assignment statements are |
5629 | placed in the environment for a command, not just those | |
17345e5a | 5630 | that precede the command name. |
74091dd4 CR |
5631 | -\b-m\bm Monitor mode. Job control is enabled. This option is |
5632 | on by default for interactive shells on systems that | |
5633 | support it (see J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL above). All processes run | |
ac50fbac CR |
5634 | in a separate process group. When a background job com- |
5635 | pletes, the shell prints a line containing its exit sta- | |
5636 | tus. | |
17345e5a | 5637 | -\b-n\bn Read commands but do not execute them. This may be used |
74091dd4 | 5638 | to check a shell script for syntax errors. This is ig- |
8868edaf | 5639 | nored by interactive shells. |
17345e5a JA |
5640 | -\b-o\bo _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be |
5641 | The _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be can be one of the following: | |
5642 | a\bal\bll\ble\bex\bxp\bpo\bor\brt\bt | |
5643 | Same as -\b-a\ba. | |
5644 | b\bbr\bra\bac\bce\bee\bex\bxp\bpa\ban\bnd\bd | |
5645 | Same as -\b-B\bB. | |
74091dd4 | 5646 | e\bem\bma\bac\bcs\bs Use an emacs-style command line editing inter- |
17345e5a JA |
5647 | face. This is enabled by default when the shell |
5648 | is interactive, unless the shell is started with | |
74091dd4 | 5649 | the -\b--\b-n\bno\boe\bed\bdi\bit\bti\bin\bng\bg option. This also affects the |
17345e5a | 5650 | editing interface used for r\bre\bea\bad\bd -\b-e\be. |
0001803f | 5651 | e\ber\brr\bre\bex\bxi\bit\bt Same as -\b-e\be. |
17345e5a JA |
5652 | e\ber\brr\brt\btr\bra\bac\bce\be |
5653 | Same as -\b-E\bE. | |
5654 | f\bfu\bun\bnc\bct\btr\bra\bac\bce\be | |
5655 | Same as -\b-T\bT. | |
17345e5a JA |
5656 | h\bha\bas\bsh\bha\bal\bll\bl Same as -\b-h\bh. |
5657 | h\bhi\bis\bst\bte\bex\bxp\bpa\ban\bnd\bd | |
5658 | Same as -\b-H\bH. | |
5659 | h\bhi\bis\bst\bto\bor\bry\by Enable command history, as described above under | |
5660 | H\bHI\bIS\bST\bTO\bOR\bRY\bY. This option is on by default in inter- | |
5661 | active shells. | |
5662 | i\big\bgn\bno\bor\bre\bee\beo\bof\bf | |
74091dd4 CR |
5663 | The effect is as if the shell command ``IG- |
5664 | NOREEOF=10'' had been executed (see S\bSh\bhe\bel\bll\bl V\bVa\bar\bri\bi-\b- | |
8868edaf | 5665 | a\bab\bbl\ble\bes\bs above). |
17345e5a JA |
5666 | k\bke\bey\byw\bwo\bor\brd\bd Same as -\b-k\bk. |
5667 | m\bmo\bon\bni\bit\bto\bor\br Same as -\b-m\bm. | |
5668 | n\bno\boc\bcl\blo\bob\bbb\bbe\ber\br | |
5669 | Same as -\b-C\bC. | |
5670 | n\bno\boe\bex\bxe\bec\bc Same as -\b-n\bn. | |
5671 | n\bno\bog\bgl\blo\bob\bb Same as -\b-f\bf. | |
5672 | n\bno\bol\blo\bog\bg Currently ignored. | |
5673 | n\bno\bot\bti\bif\bfy\by Same as -\b-b\bb. | |
5674 | n\bno\bou\bun\bns\bse\bet\bt Same as -\b-u\bu. | |
5675 | o\bon\bne\bec\bcm\bmd\bd Same as -\b-t\bt. | |
5676 | p\bph\bhy\bys\bsi\bic\bca\bal\bl | |
5677 | Same as -\b-P\bP. | |
5678 | p\bpi\bip\bpe\bef\bfa\bai\bil\bl | |
74091dd4 CR |
5679 | If set, the return value of a pipeline is the |
5680 | value of the last (rightmost) command to exit | |
5681 | with a non-zero status, or zero if all commands | |
5682 | in the pipeline exit successfully. This option | |
17345e5a | 5683 | is disabled by default. |
74091dd4 CR |
5684 | p\bpo\bos\bsi\bix\bx Change the behavior of b\bba\bas\bsh\bh where the default |
5685 | operation differs from the POSIX standard to | |
5686 | match the standard (_\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be). See S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
ac50fbac CR |
5687 | below for a reference to a document that details |
5688 | how posix mode affects bash's behavior. | |
17345e5a JA |
5689 | p\bpr\bri\biv\bvi\bil\ble\beg\bge\bed\bd |
5690 | Same as -\b-p\bp. | |
5691 | v\bve\ber\brb\bbo\bos\bse\be Same as -\b-v\bv. | |
74091dd4 | 5692 | v\bvi\bi Use a vi-style command line editing interface. |
17345e5a JA |
5693 | This also affects the editing interface used for |
5694 | r\bre\bea\bad\bd -\b-e\be. | |
5695 | x\bxt\btr\bra\bac\bce\be Same as -\b-x\bx. | |
5696 | If -\b-o\bo is supplied with no _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be, the values of the | |
74091dd4 CR |
5697 | current options are printed. If +\b+o\bo is supplied with no |
5698 | _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be, a series of s\bse\bet\bt commands to recreate the | |
5699 | current option settings is displayed on the standard | |
17345e5a | 5700 | output. |
74091dd4 CR |
5701 | -\b-p\bp Turn on _\bp_\br_\bi_\bv_\bi_\bl_\be_\bg_\be_\bd mode. In this mode, the $\b$E\bEN\bNV\bV and |
5702 | $\b$B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV files are not processed, shell functions are | |
5703 | not inherited from the environment, and the S\bSH\bHE\bEL\bLL\bLO\bOP\bPT\bTS\bS, | |
5704 | B\bBA\bAS\bSH\bHO\bOP\bPT\bTS\bS, C\bCD\bDP\bPA\bAT\bTH\bH, and G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE variables, if they ap- | |
5705 | pear in the environment, are ignored. If the shell is | |
5706 | started with the effective user (group) id not equal to | |
5707 | the real user (group) id, and the -\b-p\bp option is not sup- | |
0001803f | 5708 | plied, these actions are taken and the effective user id |
74091dd4 CR |
5709 | is set to the real user id. If the -\b-p\bp option is sup- |
5710 | plied at startup, the effective user id is not reset. | |
5711 | Turning this option off causes the effective user and | |
0001803f | 5712 | group ids to be set to the real user and group ids. |
74091dd4 CR |
5713 | -\b-r\br Enable restricted shell mode. This option cannot be un- |
5714 | set once it has been set. | |
17345e5a | 5715 | -\b-t\bt Exit after reading and executing one command. |
0001803f | 5716 | -\b-u\bu Treat unset variables and parameters other than the spe- |
74091dd4 CR |
5717 | cial parameters "@" and "*", or array variables sub- |
5718 | scripted with "@" or "*", as an error when performing | |
5719 | parameter expansion. If expansion is attempted on an | |
5720 | unset variable or parameter, the shell prints an error | |
5721 | message, and, if not interactive, exits with a non-zero | |
0001803f | 5722 | status. |
17345e5a | 5723 | -\b-v\bv Print shell input lines as they are read. |
74091dd4 | 5724 | -\b-x\bx After expanding each _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd, f\bfo\bor\br command, c\bca\bas\bse\be |
17345e5a | 5725 | command, s\bse\bel\ble\bec\bct\bt command, or arithmetic f\bfo\bor\br command, dis- |
74091dd4 | 5726 | play the expanded value of P\bPS\bS4\b4, followed by the command |
17345e5a | 5727 | and its expanded arguments or associated word list. |
74091dd4 | 5728 | -\b-B\bB The shell performs brace expansion (see B\bBr\bra\bac\bce\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn |
17345e5a | 5729 | above). This is on by default. |
74091dd4 CR |
5730 | -\b-C\bC If set, b\bba\bas\bsh\bh does not overwrite an existing file with |
5731 | the >\b>, >\b>&\b&, and <\b<>\b> redirection operators. This may be | |
17345e5a JA |
5732 | overridden when creating output files by using the redi- |
5733 | rection operator >\b>|\b| instead of >\b>. | |
5734 | -\b-E\bE If set, any trap on E\bER\bRR\bR is inherited by shell functions, | |
74091dd4 CR |
5735 | command substitutions, and commands executed in a sub- |
5736 | shell environment. The E\bER\bRR\bR trap is normally not inher- | |
17345e5a JA |
5737 | ited in such cases. |
5738 | -\b-H\bH Enable !\b! style history substitution. This option is on | |
5739 | by default when the shell is interactive. | |
74091dd4 CR |
5740 | -\b-P\bP If set, the shell does not resolve symbolic links when |
5741 | executing commands such as c\bcd\bd that change the current | |
17345e5a JA |
5742 | working directory. It uses the physical directory |
5743 | structure instead. By default, b\bba\bas\bsh\bh follows the logical | |
74091dd4 | 5744 | chain of directories when performing commands which |
17345e5a | 5745 | change the current directory. |
74091dd4 | 5746 | -\b-T\bT If set, any traps on D\bDE\bEB\bBU\bUG\bG and R\bRE\bET\bTU\bUR\bRN\bN are inherited by |
8868edaf | 5747 | shell functions, command substitutions, and commands ex- |
74091dd4 | 5748 | ecuted in a subshell environment. The D\bDE\bEB\bBU\bUG\bG and R\bRE\bET\bTU\bUR\bRN\bN |
8868edaf | 5749 | traps are normally not inherited in such cases. |
74091dd4 | 5750 | -\b--\b- If no arguments follow this option, then the positional |
17345e5a | 5751 | parameters are unset. Otherwise, the positional parame- |
74091dd4 | 5752 | ters are set to the _\ba_\br_\bgs, even if some of them begin |
17345e5a | 5753 | with a -\b-. |
74091dd4 | 5754 | -\b- Signal the end of options, cause all remaining _\ba_\br_\bgs to |
17345e5a JA |
5755 | be assigned to the positional parameters. The -\b-x\bx and -\b-v\bv |
5756 | options are turned off. If there are no _\ba_\br_\bgs, the posi- | |
5757 | tional parameters remain unchanged. | |
5758 | ||
74091dd4 CR |
5759 | The options are off by default unless otherwise noted. Using + |
5760 | rather than - causes these options to be turned off. The op- | |
8868edaf | 5761 | tions can also be specified as arguments to an invocation of the |
74091dd4 CR |
5762 | shell. The current set of options may be found in $\b$-\b-. The re- |
5763 | turn status is always true unless an invalid option is encoun- | |
17345e5a JA |
5764 | tered. |
5765 | ||
5766 | s\bsh\bhi\bif\bft\bt [_\bn] | |
74091dd4 CR |
5767 | The positional parameters from _\bn+1 ... are renamed to $\b$1\b1 .\b..\b..\b..\b. |
5768 | Parameters represented by the numbers $\b$#\b# down to $\b$#\b#-_\bn+1 are un- | |
5769 | set. _\bn must be a non-negative number less than or equal to $\b$#\b#. | |
5770 | If _\bn is 0, no parameters are changed. If _\bn is not given, it is | |
8868edaf | 5771 | assumed to be 1. If _\bn is greater than $\b$#\b#, the positional param- |
74091dd4 | 5772 | eters are not changed. The return status is greater than zero |
8868edaf | 5773 | if _\bn is greater than $\b$#\b# or less than zero; otherwise 0. |
17345e5a JA |
5774 | |
5775 | s\bsh\bho\bop\bpt\bt [-\b-p\bpq\bqs\bsu\bu] [-\b-o\bo] [_\bo_\bp_\bt_\bn_\ba_\bm_\be ...] | |
74091dd4 CR |
5776 | Toggle the values of settings controlling optional shell behav- |
5777 | ior. The settings can be either those listed below, or, if the | |
ac50fbac CR |
5778 | -\b-o\bo option is used, those available with the -\b-o\bo option to the s\bse\bet\bt |
5779 | builtin command. With no options, or with the -\b-p\bp option, a list | |
74091dd4 | 5780 | of all settable options is displayed, with an indication of |
d233b485 | 5781 | whether or not each is set; if _\bo_\bp_\bt_\bn_\ba_\bm_\be_\bs are supplied, the output |
74091dd4 CR |
5782 | is restricted to those options. The -\b-p\bp option causes output to |
5783 | be displayed in a form that may be reused as input. Other op- | |
8868edaf | 5784 | tions have the following meanings: |
17345e5a JA |
5785 | -\b-s\bs Enable (set) each _\bo_\bp_\bt_\bn_\ba_\bm_\be. |
5786 | -\b-u\bu Disable (unset) each _\bo_\bp_\bt_\bn_\ba_\bm_\be. | |
74091dd4 | 5787 | -\b-q\bq Suppresses normal output (quiet mode); the return status |
17345e5a | 5788 | indicates whether the _\bo_\bp_\bt_\bn_\ba_\bm_\be is set or unset. If multi- |
74091dd4 CR |
5789 | ple _\bo_\bp_\bt_\bn_\ba_\bm_\be arguments are given with -\b-q\bq, the return sta- |
5790 | tus is zero if all _\bo_\bp_\bt_\bn_\ba_\bm_\be_\bs are enabled; non-zero other- | |
17345e5a | 5791 | wise. |
74091dd4 | 5792 | -\b-o\bo Restricts the values of _\bo_\bp_\bt_\bn_\ba_\bm_\be to be those defined for |
17345e5a JA |
5793 | the -\b-o\bo option to the s\bse\bet\bt builtin. |
5794 | ||
74091dd4 CR |
5795 | If either -\b-s\bs or -\b-u\bu is used with no _\bo_\bp_\bt_\bn_\ba_\bm_\be arguments, s\bsh\bho\bop\bpt\bt |
5796 | shows only those options which are set or unset, respectively. | |
5797 | Unless otherwise noted, the s\bsh\bho\bop\bpt\bt options are disabled (unset) | |
ac50fbac | 5798 | by default. |
17345e5a | 5799 | |
74091dd4 CR |
5800 | The return status when listing options is zero if all _\bo_\bp_\bt_\bn_\ba_\bm_\be_\bs |
5801 | are enabled, non-zero otherwise. When setting or unsetting op- | |
5802 | tions, the return status is zero unless an _\bo_\bp_\bt_\bn_\ba_\bm_\be is not a | |
17345e5a JA |
5803 | valid shell option. |
5804 | ||
5805 | The list of s\bsh\bho\bop\bpt\bt options is: | |
5806 | ||
d233b485 | 5807 | a\bas\bss\bso\boc\bc_\b_e\bex\bxp\bpa\ban\bnd\bd_\b_o\bon\bnc\bce\be |
74091dd4 CR |
5808 | If set, the shell suppresses multiple evaluation of as- |
5809 | sociative array subscripts during arithmetic expression | |
5810 | evaluation, while executing builtins that can perform | |
5811 | variable assignments, and while executing builtins that | |
8868edaf | 5812 | perform array dereferencing. |
74091dd4 CR |
5813 | a\bau\but\bto\boc\bcd\bd If set, a command name that is the name of a directory |
5814 | is executed as if it were the argument to the c\bcd\bd com- | |
17345e5a JA |
5815 | mand. This option is only used by interactive shells. |
5816 | c\bcd\bda\bab\bbl\ble\be_\b_v\bva\bar\brs\bs | |
74091dd4 CR |
5817 | If set, an argument to the c\bcd\bd builtin command that is |
5818 | not a directory is assumed to be the name of a variable | |
17345e5a JA |
5819 | whose value is the directory to change to. |
5820 | c\bcd\bds\bsp\bpe\bel\bll\bl If set, minor errors in the spelling of a directory com- | |
74091dd4 | 5821 | ponent in a c\bcd\bd command will be corrected. The errors |
17345e5a | 5822 | checked for are transposed characters, a missing charac- |
74091dd4 CR |
5823 | ter, and one character too many. If a correction is |
5824 | found, the corrected filename is printed, and the com- | |
5825 | mand proceeds. This option is only used by interactive | |
17345e5a JA |
5826 | shells. |
5827 | c\bch\bhe\bec\bck\bkh\bha\bas\bsh\bh | |
5828 | If set, b\bba\bas\bsh\bh checks that a command found in the hash ta- | |
74091dd4 CR |
5829 | ble exists before trying to execute it. If a hashed |
5830 | command no longer exists, a normal path search is per- | |
17345e5a JA |
5831 | formed. |
5832 | c\bch\bhe\bec\bck\bkj\bjo\bob\bbs\bs | |
5833 | If set, b\bba\bas\bsh\bh lists the status of any stopped and running | |
74091dd4 | 5834 | jobs before exiting an interactive shell. If any jobs |
17345e5a | 5835 | are running, this causes the exit to be deferred until a |
74091dd4 | 5836 | second exit is attempted without an intervening command |
8868edaf CR |
5837 | (see J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL above). The shell always postpones ex- |
5838 | iting if any jobs are stopped. | |
17345e5a | 5839 | c\bch\bhe\bec\bck\bkw\bwi\bin\bns\bsi\biz\bze\be |
74091dd4 CR |
5840 | If set, b\bba\bas\bsh\bh checks the window size after each external |
5841 | (non-builtin) command and, if necessary, updates the | |
5842 | values of L\bLI\bIN\bNE\bES\bS and C\bCO\bOL\bLU\bUM\bMN\bNS\bS. This option is enabled by | |
d233b485 | 5843 | default. |
74091dd4 CR |
5844 | c\bcm\bmd\bdh\bhi\bis\bst\bt If set, b\bba\bas\bsh\bh attempts to save all lines of a multiple- |
5845 | line command in the same history entry. This allows | |
5846 | easy re-editing of multi-line commands. This option is | |
5847 | enabled by default, but only has an effect if command | |
d233b485 | 5848 | history is enabled, as described above under H\bHI\bIS\bST\bTO\bOR\bRY\bY. |
17345e5a | 5849 | c\bco\bom\bmp\bpa\bat\bt3\b31\b1 |
0001803f | 5850 | c\bco\bom\bmp\bpa\bat\bt3\b32\b2 |
0001803f | 5851 | c\bco\bom\bmp\bpa\bat\bt4\b40\b0 |
495aee44 | 5852 | c\bco\bom\bmp\bpa\bat\bt4\b41\b1 |
ac50fbac | 5853 | c\bco\bom\bmp\bpa\bat\bt4\b42\b2 |
a0c0a00f | 5854 | c\bco\bom\bmp\bpa\bat\bt4\b43\b3 |
d233b485 | 5855 | c\bco\bom\bmp\bpa\bat\bt4\b44\b4 |
74091dd4 CR |
5856 | c\bco\bom\bmp\bpa\bat\bt5\b50\b0 |
5857 | These control aspects of the shell's compatibility mode | |
8868edaf CR |
5858 | (see S\bSH\bHE\bEL\bLL\bL C\bCO\bOM\bMP\bPA\bAT\bTI\bIB\bBI\bIL\bLI\bIT\bTY\bY M\bMO\bOD\bDE\bE below). |
5859 | ||
ac50fbac | 5860 | c\bco\bom\bmp\bpl\ble\bet\bte\be_\b_f\bfu\bul\bll\blq\bqu\buo\bot\bte\be |
74091dd4 CR |
5861 | If set, b\bba\bas\bsh\bh quotes all shell metacharacters in file- |
5862 | names and directory names when performing completion. | |
ac50fbac | 5863 | If not set, b\bba\bas\bsh\bh removes metacharacters such as the dol- |
74091dd4 CR |
5864 | lar sign from the set of characters that will be quoted |
5865 | in completed filenames when these metacharacters appear | |
5866 | in shell variable references in words to be completed. | |
5867 | This means that dollar signs in variable names that ex- | |
5868 | pand to directories will not be quoted; however, any | |
5869 | dollar signs appearing in filenames will not be quoted, | |
5870 | either. This is active only when bash is using back- | |
5871 | slashes to quote completed filenames. This variable is | |
5872 | set by default, which is the default bash behavior in | |
ac50fbac | 5873 | versions through 4.2. |
8868edaf | 5874 | |
ac50fbac | 5875 | d\bdi\bir\bre\bex\bxp\bpa\ban\bnd\bd |
74091dd4 CR |
5876 | If set, b\bba\bas\bsh\bh replaces directory names with the results |
5877 | of word expansion when performing filename completion. | |
5878 | This changes the contents of the readline editing buf- | |
5879 | fer. If not set, b\bba\bas\bsh\bh attempts to preserve what the | |
ac50fbac | 5880 | user typed. |
8868edaf | 5881 | |
17345e5a | 5882 | d\bdi\bir\brs\bsp\bpe\bel\bll\bl |
74091dd4 CR |
5883 | If set, b\bba\bas\bsh\bh attempts spelling correction on directory |
5884 | names during word completion if the directory name ini- | |
17345e5a | 5885 | tially supplied does not exist. |
8868edaf | 5886 | |
74091dd4 CR |
5887 | d\bdo\bot\btg\bgl\blo\bob\bb If set, b\bba\bas\bsh\bh includes filenames beginning with a `.' in |
5888 | the results of pathname expansion. The filenames `\b``\b`.\b.'\b''\b' | |
5889 | and `\b``\b`.\b..\b.'\b''\b' must always be matched explicitly, even if | |
d233b485 | 5890 | d\bdo\bot\btg\bgl\blo\bob\bb is set. |
8868edaf | 5891 | |
17345e5a JA |
5892 | e\bex\bxe\bec\bcf\bfa\bai\bil\bl |
5893 | If set, a non-interactive shell will not exit if it can- | |
74091dd4 CR |
5894 | not execute the file specified as an argument to the |
5895 | e\bex\bxe\bec\bc builtin command. An interactive shell does not | |
17345e5a | 5896 | exit if e\bex\bxe\bec\bc fails. |
8868edaf | 5897 | |
17345e5a | 5898 | e\bex\bxp\bpa\ban\bnd\bd_\b_a\bal\bli\bia\bas\bse\bes\bs |
74091dd4 | 5899 | If set, aliases are expanded as described above under |
17345e5a JA |
5900 | A\bAL\bLI\bIA\bAS\bSE\bES\bS. This option is enabled by default for interac- |
5901 | tive shells. | |
8868edaf | 5902 | |
17345e5a | 5903 | e\bex\bxt\btd\bde\beb\bbu\bug\bg |
74091dd4 | 5904 | If set at shell invocation, or in a shell startup file, |
8868edaf | 5905 | arrange to execute the debugger profile before the shell |
74091dd4 CR |
5906 | starts, identical to the -\b--\b-d\bde\beb\bbu\bug\bgg\bge\ber\br option. If set af- |
5907 | ter invocation, behavior intended for use by debuggers | |
8868edaf CR |
5908 | is enabled: |
5909 | ||
17345e5a JA |
5910 | 1\b1.\b. The -\b-F\bF option to the d\bde\bec\bcl\bla\bar\bre\be builtin displays the |
5911 | source file name and line number corresponding to | |
5912 | each function name supplied as an argument. | |
8868edaf | 5913 | |
74091dd4 CR |
5914 | 2\b2.\b. If the command run by the D\bDE\bEB\bBU\bUG\bG trap returns a |
5915 | non-zero value, the next command is skipped and | |
17345e5a | 5916 | not executed. |
8868edaf | 5917 | |
74091dd4 CR |
5918 | 3\b3.\b. If the command run by the D\bDE\bEB\bBU\bUG\bG trap returns a |
5919 | value of 2, and the shell is executing in a sub- | |
5920 | routine (a shell function or a shell script exe- | |
5921 | cuted by the .\b. or s\bso\bou\bur\brc\bce\be builtins), the shell | |
a0c0a00f | 5922 | simulates a call to r\bre\bet\btu\bur\brn\bn. |
8868edaf | 5923 | |
74091dd4 CR |
5924 | 4\b4.\b. B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGC\bC and B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV are updated as described |
5925 | in their descriptions above). | |
8868edaf | 5926 | |
74091dd4 | 5927 | 5\b5.\b. Function tracing is enabled: command substitu- |
17345e5a JA |
5928 | tion, shell functions, and subshells invoked with |
5929 | (\b( _\bc_\bo_\bm_\bm_\ba_\bn_\bd )\b) inherit the D\bDE\bEB\bBU\bUG\bG and R\bRE\bET\bTU\bUR\bRN\bN traps. | |
8868edaf | 5930 | |
74091dd4 CR |
5931 | 6\b6.\b. Error tracing is enabled: command substitution, |
5932 | shell functions, and subshells invoked with (\b( | |
495aee44 | 5933 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd )\b) inherit the E\bER\bRR\bR trap. |
8868edaf | 5934 | |
17345e5a JA |
5935 | e\bex\bxt\btg\bgl\blo\bob\bb If set, the extended pattern matching features described |
5936 | above under P\bPa\bat\bth\bhn\bna\bam\bme\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn are enabled. | |
8868edaf | 5937 | |
17345e5a | 5938 | e\bex\bxt\btq\bqu\buo\bot\bte\be |
74091dd4 CR |
5939 | If set, $\b$'_\bs_\bt_\br_\bi_\bn_\bg' and $\b$"_\bs_\bt_\br_\bi_\bn_\bg" quoting is performed |
5940 | within $\b${\b{_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br}\b} expansions enclosed in double | |
17345e5a | 5941 | quotes. This option is enabled by default. |
8868edaf | 5942 | |
17345e5a | 5943 | f\bfa\bai\bil\blg\bgl\blo\bob\bb |
74091dd4 | 5944 | If set, patterns which fail to match filenames during |
17345e5a | 5945 | pathname expansion result in an expansion error. |
8868edaf | 5946 | |
17345e5a | 5947 | f\bfo\bor\brc\bce\be_\b_f\bfi\big\bgn\bno\bor\bre\be |
74091dd4 CR |
5948 | If set, the suffixes specified by the F\bFI\bIG\bGN\bNO\bOR\bRE\bE shell |
5949 | variable cause words to be ignored when performing word | |
17345e5a | 5950 | completion even if the ignored words are the only possi- |
74091dd4 CR |
5951 | ble completions. See S\bSH\bHE\bEL\bLL\bL V\bVA\bAR\bRI\bIA\bAB\bBL\bLE\bES\bS above for a de- |
5952 | scription of F\bFI\bIG\bGN\bNO\bOR\bRE\bE. This option is enabled by de- | |
8868edaf CR |
5953 | fault. |
5954 | ||
ac50fbac | 5955 | g\bgl\blo\bob\bba\bas\bsc\bci\bii\bir\bra\ban\bng\bge\bes\bs |
74091dd4 CR |
5956 | If set, range expressions used in pattern matching |
5957 | bracket expressions (see P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg above) behave | |
5958 | as if in the traditional C locale when performing com- | |
5959 | parisons. That is, the current locale's collating se- | |
5960 | quence is not taken into account, so b\bb will not collate | |
5961 | between A\bA and B\bB, and upper-case and lower-case ASCII | |
8868edaf CR |
5962 | characters will collate together. |
5963 | ||
74091dd4 CR |
5964 | g\bgl\blo\bob\bbs\bsk\bki\bip\bpd\bdo\bot\bts\bs |
5965 | If set, pathname expansion will never match the file- | |
5966 | names `\b``\b`.\b.'\b''\b' and `\b``\b`.\b..\b.'\b''\b', even if the pattern begins with | |
5967 | a `\b``\b`.\b.'\b''\b'. This option is enabled by default. | |
5968 | ||
17345e5a | 5969 | g\bgl\blo\bob\bbs\bst\bta\bar\br |
0001803f | 5970 | If set, the pattern *\b**\b* used in a pathname expansion con- |
74091dd4 CR |
5971 | text will match all files and zero or more directories |
5972 | and subdirectories. If the pattern is followed by a /\b/, | |
ac50fbac | 5973 | only directories and subdirectories match. |
8868edaf | 5974 | |
17345e5a JA |
5975 | g\bgn\bnu\bu_\b_e\ber\brr\brf\bfm\bmt\bt |
5976 | If set, shell error messages are written in the standard | |
5977 | GNU error message format. | |
8868edaf | 5978 | |
17345e5a | 5979 | h\bhi\bis\bst\bta\bap\bpp\bpe\ben\bnd\bd |
74091dd4 | 5980 | If set, the history list is appended to the file named |
8868edaf CR |
5981 | by the value of the H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE variable when the shell ex- |
5982 | its, rather than overwriting the file. | |
5983 | ||
17345e5a | 5984 | h\bhi\bis\bst\btr\bre\bee\bed\bdi\bit\bt |
74091dd4 | 5985 | If set, and r\bre\bea\bad\bdl\bli\bin\bne\be is being used, a user is given the |
17345e5a | 5986 | opportunity to re-edit a failed history substitution. |
8868edaf | 5987 | |
17345e5a | 5988 | h\bhi\bis\bst\btv\bve\ber\bri\bif\bfy\by |
74091dd4 CR |
5989 | If set, and r\bre\bea\bad\bdl\bli\bin\bne\be is being used, the results of his- |
5990 | tory substitution are not immediately passed to the | |
5991 | shell parser. Instead, the resulting line is loaded | |
17345e5a JA |
5992 | into the r\bre\bea\bad\bdl\bli\bin\bne\be editing buffer, allowing further modi- |
5993 | fication. | |
8868edaf | 5994 | |
17345e5a JA |
5995 | h\bho\bos\bst\btc\bco\bom\bmp\bpl\ble\bet\bte\be |
5996 | If set, and r\bre\bea\bad\bdl\bli\bin\bne\be is being used, b\bba\bas\bsh\bh will attempt to | |
74091dd4 CR |
5997 | perform hostname completion when a word containing a @\b@ |
5998 | is being completed (see C\bCo\bom\bmp\bpl\ble\bet\bti\bin\bng\bg under R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE | |
17345e5a | 5999 | above). This is enabled by default. |
8868edaf | 6000 | |
17345e5a JA |
6001 | h\bhu\bup\bpo\bon\bne\bex\bxi\bit\bt |
6002 | If set, b\bba\bas\bsh\bh will send S\bSI\bIG\bGH\bHU\bUP\bP to all jobs when an inter- | |
6003 | active login shell exits. | |
8868edaf | 6004 | |
a0c0a00f | 6005 | i\bin\bnh\bhe\ber\bri\bit\bt_\b_e\ber\brr\bre\bex\bxi\bit\bt |
74091dd4 CR |
6006 | If set, command substitution inherits the value of the |
6007 | e\ber\brr\bre\bex\bxi\bit\bt option, instead of unsetting it in the subshell | |
6008 | environment. This option is enabled when _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be is | |
a0c0a00f | 6009 | enabled. |
8868edaf | 6010 | |
17345e5a JA |
6011 | i\bin\bnt\bte\ber\bra\bac\bct\bti\biv\bve\be_\b_c\bco\bom\bmm\bme\ben\bnt\bts\bs |
6012 | If set, allow a word beginning with #\b# to cause that word | |
74091dd4 CR |
6013 | and all remaining characters on that line to be ignored |
6014 | in an interactive shell (see C\bCO\bOM\bMM\bME\bEN\bNT\bTS\bS above). This op- | |
8868edaf CR |
6015 | tion is enabled by default. |
6016 | ||
495aee44 | 6017 | l\bla\bas\bst\btp\bpi\bip\bpe\be |
74091dd4 | 6018 | If set, and job control is not active, the shell runs |
495aee44 CR |
6019 | the last command of a pipeline not executed in the back- |
6020 | ground in the current shell environment. | |
8868edaf | 6021 | |
74091dd4 | 6022 | l\bli\bit\bth\bhi\bis\bst\bt If set, and the c\bcm\bmd\bdh\bhi\bis\bst\bt option is enabled, multi-line |
17345e5a JA |
6023 | commands are saved to the history with embedded newlines |
6024 | rather than using semicolon separators where possible. | |
8868edaf | 6025 | |
d233b485 CR |
6026 | l\blo\boc\bca\bal\blv\bva\bar\br_\b_i\bin\bnh\bhe\ber\bri\bit\bt |
6027 | If set, local variables inherit the value and attributes | |
6028 | of a variable of the same name that exists at a previous | |
8868edaf CR |
6029 | scope before any new value is assigned. The nameref at- |
6030 | tribute is not inherited. | |
6031 | ||
d233b485 | 6032 | l\blo\boc\bca\bal\blv\bva\bar\br_\b_u\bun\bns\bse\bet\bt |
74091dd4 CR |
6033 | If set, calling u\bun\bns\bse\bet\bt on local variables in previous |
6034 | function scopes marks them so subsequent lookups find | |
6035 | them unset until that function returns. This is identi- | |
6036 | cal to the behavior of unsetting local variables at the | |
d233b485 | 6037 | current function scope. |
8868edaf | 6038 | |
17345e5a | 6039 | l\blo\bog\bgi\bin\bn_\b_s\bsh\bhe\bel\bll\bl |
74091dd4 CR |
6040 | The shell sets this option if it is started as a login |
6041 | shell (see I\bIN\bNV\bVO\bOC\bCA\bAT\bTI\bIO\bON\bN above). The value may not be | |
17345e5a | 6042 | changed. |
8868edaf | 6043 | |
17345e5a | 6044 | m\bma\bai\bil\blw\bwa\bar\brn\bn |
74091dd4 CR |
6045 | If set, and a file that b\bba\bas\bsh\bh is checking for mail has |
6046 | been accessed since the last time it was checked, the | |
6047 | message ``The mail in _\bm_\ba_\bi_\bl_\bf_\bi_\bl_\be has been read'' is dis- | |
17345e5a | 6048 | played. |
8868edaf | 6049 | |
17345e5a | 6050 | n\bno\bo_\b_e\bem\bmp\bpt\bty\by_\b_c\bcm\bmd\bd_\b_c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bn |
74091dd4 CR |
6051 | If set, and r\bre\bea\bad\bdl\bli\bin\bne\be is being used, b\bba\bas\bsh\bh will not at- |
6052 | tempt to search the P\bPA\bAT\bTH\bH for possible completions when | |
17345e5a | 6053 | completion is attempted on an empty line. |
8868edaf | 6054 | |
17345e5a | 6055 | n\bno\boc\bca\bas\bse\beg\bgl\blo\bob\bb |
74091dd4 | 6056 | If set, b\bba\bas\bsh\bh matches filenames in a case-insensitive |
17345e5a JA |
6057 | fashion when performing pathname expansion (see P\bPa\bat\bth\bhn\bna\bam\bme\be |
6058 | E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn above). | |
8868edaf | 6059 | |
17345e5a | 6060 | n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh |
74091dd4 | 6061 | If set, b\bba\bas\bsh\bh matches patterns in a case-insensitive |
17345e5a | 6062 | fashion when performing matching while executing c\bca\bas\bse\be or |
a0c0a00f | 6063 | [\b[[\b[ conditional commands, when performing pattern substi- |
74091dd4 | 6064 | tution word expansions, or when filtering possible com- |
a0c0a00f | 6065 | pletions as part of programmable completion. |
8868edaf | 6066 | |
74091dd4 CR |
6067 | n\bno\boe\bex\bxp\bpa\ban\bnd\bd_\b_t\btr\bra\ban\bns\bsl\bla\bat\bti\bio\bon\bn |
6068 | If set, b\bba\bas\bsh\bh encloses the translated results of $"..." | |
6069 | quoting in single quotes instead of double quotes. If | |
6070 | the string is not translated, this has no effect. | |
6071 | ||
17345e5a | 6072 | n\bnu\bul\bll\blg\bgl\blo\bob\bb |
74091dd4 CR |
6073 | If set, b\bba\bas\bsh\bh allows patterns which match no files (see |
6074 | P\bPa\bat\bth\bhn\bna\bam\bme\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn above) to expand to a null string, | |
17345e5a | 6075 | rather than themselves. |
8868edaf | 6076 | |
74091dd4 CR |
6077 | p\bpa\bat\bts\bsu\bub\bb_\b_r\bre\bep\bpl\bla\bac\bce\bem\bme\ben\bnt\bt |
6078 | If set, b\bba\bas\bsh\bh expands occurrences of &\b& in the replacement | |
6079 | string of pattern substitution to the text matched by | |
6080 | the pattern, as described under P\bPa\bar\bra\bam\bme\bet\bte\ber\br E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
6081 | above. This option is enabled by default. | |
6082 | ||
17345e5a JA |
6083 | p\bpr\bro\bog\bgc\bco\bom\bmp\bp |
6084 | If set, the programmable completion facilities (see P\bPr\bro\bo-\b- | |
6085 | g\bgr\bra\bam\bmm\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn above) are enabled. This option is | |
6086 | enabled by default. | |
8868edaf | 6087 | |
d233b485 CR |
6088 | p\bpr\bro\bog\bgc\bco\bom\bmp\bp_\b_a\bal\bli\bia\bas\bs |
6089 | If set, and programmable completion is enabled, b\bba\bas\bsh\bh | |
6090 | treats a command name that doesn't have any completions | |
6091 | as a possible alias and attempts alias expansion. If it | |
8868edaf CR |
6092 | has an alias, b\bba\bas\bsh\bh attempts programmable completion us- |
6093 | ing the command word resulting from the expanded alias. | |
6094 | ||
17345e5a JA |
6095 | p\bpr\bro\bom\bmp\bpt\btv\bva\bar\brs\bs |
6096 | If set, prompt strings undergo parameter expansion, com- | |
8868edaf CR |
6097 | mand substitution, arithmetic expansion, and quote re- |
6098 | moval after being expanded as described in P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG | |
17345e5a | 6099 | above. This option is enabled by default. |
8868edaf | 6100 | |
17345e5a | 6101 | r\bre\bes\bst\btr\bri\bic\bct\bte\bed\bd_\b_s\bsh\bhe\bel\bll\bl |
8868edaf CR |
6102 | The shell sets this option if it is started in re- |
6103 | stricted mode (see R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTE\bED\bD S\bSH\bHE\bEL\bLL\bL below). The value | |
6104 | may not be changed. This is not reset when the startup | |
6105 | files are executed, allowing the startup files to dis- | |
17345e5a | 6106 | cover whether or not a shell is restricted. |
8868edaf | 6107 | |
17345e5a | 6108 | s\bsh\bhi\bif\bft\bt_\b_v\bve\ber\brb\bbo\bos\bse\be |
8868edaf | 6109 | If set, the s\bsh\bhi\bif\bft\bt builtin prints an error message when |
17345e5a JA |
6110 | the shift count exceeds the number of positional parame- |
6111 | ters. | |
8868edaf | 6112 | |
17345e5a | 6113 | s\bso\bou\bur\brc\bce\bep\bpa\bat\bth\bh |
74091dd4 | 6114 | If set, the .\b. (s\bso\bou\bur\brc\bce\be) builtin uses the value of P\bPA\bAT\bTH\bH to |
8868edaf | 6115 | find the directory containing the file supplied as an |
17345e5a | 6116 | argument. This option is enabled by default. |
8868edaf | 6117 | |
74091dd4 CR |
6118 | v\bva\bar\brr\bre\bed\bdi\bir\br_\b_c\bcl\blo\bos\bse\be |
6119 | If set, the shell automatically closes file descriptors | |
6120 | assigned using the _\b{_\bv_\ba_\br_\bn_\ba_\bm_\be_\b} redirection syntax (see R\bRE\bE-\b- | |
6121 | D\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN above) instead of leaving them open when the | |
6122 | command completes. | |
6123 | ||
17345e5a | 6124 | x\bxp\bpg\bg_\b_e\bec\bch\bho\bo |
74091dd4 | 6125 | If set, the e\bec\bch\bho\bo builtin expands backslash-escape se- |
8868edaf | 6126 | quences by default. |
ac50fbac | 6127 | |
17345e5a | 6128 | s\bsu\bus\bsp\bpe\ben\bnd\bd [-\b-f\bf] |
74091dd4 CR |
6129 | Suspend the execution of this shell until it receives a S\bSI\bIG\bGC\bCO\bON\bNT\bT |
6130 | signal. A login shell, or a shell without job control enabled, | |
6131 | cannot be suspended; the -\b-f\bf option can be used to override this | |
6132 | and force the suspension. The return status is 0 unless the | |
6133 | shell is a login shell or job control is not enabled and -\b-f\bf is | |
6134 | not supplied. | |
ac50fbac | 6135 | |
17345e5a JA |
6136 | t\bte\bes\bst\bt _\be_\bx_\bp_\br |
6137 | [\b[ _\be_\bx_\bp_\br ]\b] | |
ac50fbac CR |
6138 | Return a status of 0 (true) or 1 (false) depending on the evalu- |
6139 | ation of the conditional expression _\be_\bx_\bp_\br. Each operator and op- | |
8868edaf CR |
6140 | erand must be a separate argument. Expressions are composed of |
6141 | the primaries described above under C\bCO\bON\bND\bDI\bIT\bTI\bIO\bON\bNA\bAL\bL E\bEX\bXP\bPR\bRE\bES\bSS\bSI\bIO\bON\bNS\bS. | |
6142 | t\bte\bes\bst\bt does not accept any options, nor does it accept and ignore | |
ac50fbac CR |
6143 | an argument of -\b--\b- as signifying the end of options. |
6144 | ||
8868edaf CR |
6145 | Expressions may be combined using the following operators, |
6146 | listed in decreasing order of precedence. The evaluation de- | |
6147 | pends on the number of arguments; see below. Operator prece- | |
495aee44 | 6148 | dence is used when there are five or more arguments. |
17345e5a JA |
6149 | !\b! _\be_\bx_\bp_\br True if _\be_\bx_\bp_\br is false. |
6150 | (\b( _\be_\bx_\bp_\br )\b) | |
8868edaf | 6151 | Returns the value of _\be_\bx_\bp_\br. This may be used to override |
17345e5a JA |
6152 | the normal precedence of operators. |
6153 | _\be_\bx_\bp_\br_\b1 -a\ba _\be_\bx_\bp_\br_\b2 | |
6154 | True if both _\be_\bx_\bp_\br_\b1 and _\be_\bx_\bp_\br_\b2 are true. | |
6155 | _\be_\bx_\bp_\br_\b1 -o\bo _\be_\bx_\bp_\br_\b2 | |
6156 | True if either _\be_\bx_\bp_\br_\b1 or _\be_\bx_\bp_\br_\b2 is true. | |
6157 | ||
6158 | t\bte\bes\bst\bt and [\b[ evaluate conditional expressions using a set of rules | |
6159 | based on the number of arguments. | |
6160 | ||
6161 | 0 arguments | |
6162 | The expression is false. | |
6163 | 1 argument | |
6164 | The expression is true if and only if the argument is not | |
6165 | null. | |
6166 | 2 arguments | |
6167 | If the first argument is !\b!, the expression is true if and | |
8868edaf CR |
6168 | only if the second argument is null. If the first argu- |
6169 | ment is one of the unary conditional operators listed | |
6170 | above under C\bCO\bON\bND\bDI\bIT\bTI\bIO\bON\bNA\bAL\bL E\bEX\bXP\bPR\bRE\bES\bSS\bSI\bIO\bON\bNS\bS, the expression is | |
17345e5a JA |
6171 | true if the unary test is true. If the first argument is |
6172 | not a valid unary conditional operator, the expression is | |
6173 | false. | |
6174 | 3 arguments | |
495aee44 | 6175 | The following conditions are applied in the order listed. |
8868edaf | 6176 | If the second argument is one of the binary conditional |
17345e5a JA |
6177 | operators listed above under C\bCO\bON\bND\bDI\bIT\bTI\bIO\bON\bNA\bAL\bL E\bEX\bXP\bPR\bRE\bES\bSS\bSI\bIO\bON\bNS\bS, the |
6178 | result of the expression is the result of the binary test | |
8868edaf CR |
6179 | using the first and third arguments as operands. The -\b-a\ba |
6180 | and -\b-o\bo operators are considered binary operators when | |
6181 | there are three arguments. If the first argument is !\b!, | |
6182 | the value is the negation of the two-argument test using | |
17345e5a JA |
6183 | the second and third arguments. If the first argument is |
6184 | exactly (\b( and the third argument is exactly )\b), the result | |
8868edaf | 6185 | is the one-argument test of the second argument. Other- |
17345e5a JA |
6186 | wise, the expression is false. |
6187 | 4 arguments | |
74091dd4 | 6188 | The following conditions are applied in the order listed. |
17345e5a | 6189 | If the first argument is !\b!, the result is the negation of |
74091dd4 CR |
6190 | the three-argument expression composed of the remaining |
6191 | arguments. the two-argument test using the second and | |
6192 | third arguments. If the first argument is exactly (\b( and | |
6193 | the fourth argument is exactly )\b), the result is the two- | |
6194 | argument test of the second and third arguments. Other- | |
6195 | wise, the expression is parsed and evaluated according to | |
6196 | precedence using the rules listed above. | |
17345e5a | 6197 | 5 or more arguments |
8868edaf | 6198 | The expression is parsed and evaluated according to |
17345e5a JA |
6199 | precedence using the rules listed above. |
6200 | ||
8868edaf | 6201 | When used with t\bte\bes\bst\bt or [\b[, the <\b< and >\b> operators sort lexico- |
495aee44 CR |
6202 | graphically using ASCII ordering. |
6203 | ||
8868edaf | 6204 | t\bti\bim\bme\bes\bs Print the accumulated user and system times for the shell and |
17345e5a JA |
6205 | for processes run from the shell. The return status is 0. |
6206 | ||
6207 | t\btr\bra\bap\bp [-\b-l\blp\bp] [[_\ba_\br_\bg] _\bs_\bi_\bg_\bs_\bp_\be_\bc ...] | |
8868edaf CR |
6208 | The command _\ba_\br_\bg is to be read and executed when the shell re- |
6209 | ceives signal(s) _\bs_\bi_\bg_\bs_\bp_\be_\bc. If _\ba_\br_\bg is absent (and there is a sin- | |
6210 | gle _\bs_\bi_\bg_\bs_\bp_\be_\bc) or -\b-, each specified signal is reset to its origi- | |
6211 | nal disposition (the value it had upon entrance to the shell). | |
6212 | If _\ba_\br_\bg is the null string the signal specified by each _\bs_\bi_\bg_\bs_\bp_\be_\bc | |
6213 | is ignored by the shell and by the commands it invokes. If _\ba_\br_\bg | |
6214 | is not present and -\b-p\bp has been supplied, then the trap commands | |
6215 | associated with each _\bs_\bi_\bg_\bs_\bp_\be_\bc are displayed. If no arguments are | |
6216 | supplied or if only -\b-p\bp is given, t\btr\bra\bap\bp prints the list of com- | |
6217 | mands associated with each signal. The -\b-l\bl option causes the | |
6218 | shell to print a list of signal names and their corresponding | |
6219 | numbers. Each _\bs_\bi_\bg_\bs_\bp_\be_\bc is either a signal name defined in <_\bs_\bi_\bg_\b- | |
6220 | _\bn_\ba_\bl_\b._\bh>, or a signal number. Signal names are case insensitive | |
6221 | and the S\bSI\bIG\bG prefix is optional. | |
6222 | ||
6223 | If a _\bs_\bi_\bg_\bs_\bp_\be_\bc is E\bEX\bXI\bIT\bT (0) the command _\ba_\br_\bg is executed on exit | |
6224 | from the shell. If a _\bs_\bi_\bg_\bs_\bp_\be_\bc is D\bDE\bEB\bBU\bUG\bG, the command _\ba_\br_\bg is exe- | |
6225 | cuted before every _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd, _\bf_\bo_\br command, _\bc_\ba_\bs_\be command, | |
6226 | _\bs_\be_\bl_\be_\bc_\bt command, every arithmetic _\bf_\bo_\br command, and before the | |
6227 | first command executes in a shell function (see S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR | |
6228 | above). Refer to the description of the e\bex\bxt\btd\bde\beb\bbu\bug\bg option to the | |
0001803f CR |
6229 | s\bsh\bho\bop\bpt\bt builtin for details of its effect on the D\bDE\bEB\bBU\bUG\bG trap. If a |
6230 | _\bs_\bi_\bg_\bs_\bp_\be_\bc is R\bRE\bET\bTU\bUR\bRN\bN, the command _\ba_\br_\bg is executed each time a shell | |
6231 | function or a script executed with the .\b. or s\bso\bou\bur\brc\bce\be builtins fin- | |
6232 | ishes executing. | |
6233 | ||
8868edaf | 6234 | If a _\bs_\bi_\bg_\bs_\bp_\be_\bc is E\bER\bRR\bR, the command _\ba_\br_\bg is executed whenever a |
ac50fbac CR |
6235 | pipeline (which may consist of a single simple command), a list, |
6236 | or a compound command returns a non-zero exit status, subject to | |
8868edaf | 6237 | the following conditions. The E\bER\bRR\bR trap is not executed if the |
ac50fbac | 6238 | failed command is part of the command list immediately following |
8868edaf | 6239 | a w\bwh\bhi\bil\ble\be or u\bun\bnt\bti\bil\bl keyword, part of the test in an _\bi_\bf statement, |
ac50fbac | 6240 | part of a command executed in a &\b&&\b& or |\b||\b| list except the command |
8868edaf CR |
6241 | following the final &\b&&\b& or |\b||\b|, any command in a pipeline but the |
6242 | last, or if the command's return value is being inverted using | |
6243 | !\b!. These are the same conditions obeyed by the e\ber\brr\bre\bex\bxi\bit\bt (-\b-e\be) op- | |
6244 | tion. | |
0001803f | 6245 | |
8868edaf CR |
6246 | Signals ignored upon entry to the shell cannot be trapped or re- |
6247 | set. Trapped signals that are not being ignored are reset to | |
0001803f | 6248 | their original values in a subshell or subshell environment when |
8868edaf | 6249 | one is created. The return status is false if any _\bs_\bi_\bg_\bs_\bp_\be_\bc is |
0001803f | 6250 | invalid; otherwise t\btr\bra\bap\bp returns true. |
17345e5a JA |
6251 | |
6252 | t\bty\byp\bpe\be [-\b-a\baf\bft\btp\bpP\bP] _\bn_\ba_\bm_\be [_\bn_\ba_\bm_\be ...] | |
8868edaf | 6253 | With no options, indicate how each _\bn_\ba_\bm_\be would be interpreted if |
17345e5a | 6254 | used as a command name. If the -\b-t\bt option is used, t\bty\byp\bpe\be prints a |
8868edaf CR |
6255 | string which is one of _\ba_\bl_\bi_\ba_\bs, _\bk_\be_\by_\bw_\bo_\br_\bd, _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn, _\bb_\bu_\bi_\bl_\bt_\bi_\bn, or |
6256 | _\bf_\bi_\bl_\be if _\bn_\ba_\bm_\be is an alias, shell reserved word, function, | |
6257 | builtin, or disk file, respectively. If the _\bn_\ba_\bm_\be is not found, | |
6258 | then nothing is printed, and an exit status of false is re- | |
6259 | turned. If the -\b-p\bp option is used, t\bty\byp\bpe\be either returns the name | |
6260 | of the disk file that would be executed if _\bn_\ba_\bm_\be were specified | |
6261 | as a command name, or nothing if ``type -t name'' would not re- | |
6262 | turn _\bf_\bi_\bl_\be. The -\b-P\bP option forces a P\bPA\bAT\bTH\bH search for each _\bn_\ba_\bm_\be, | |
17345e5a | 6263 | even if ``type -t name'' would not return _\bf_\bi_\bl_\be. If a command is |
ac50fbac | 6264 | hashed, -\b-p\bp and -\b-P\bP print the hashed value, which is not necessar- |
8868edaf CR |
6265 | ily the file that appears first in P\bPA\bAT\bTH\bH. If the -\b-a\ba option is |
6266 | used, t\bty\byp\bpe\be prints all of the places that contain an executable | |
ac50fbac CR |
6267 | named _\bn_\ba_\bm_\be. This includes aliases and functions, if and only if |
6268 | the -\b-p\bp option is not also used. The table of hashed commands is | |
8868edaf | 6269 | not consulted when using -\b-a\ba. The -\b-f\bf option suppresses shell |
ac50fbac CR |
6270 | function lookup, as with the c\bco\bom\bmm\bma\ban\bnd\bd builtin. t\bty\byp\bpe\be returns true |
6271 | if all of the arguments are found, false if any are not found. | |
17345e5a | 6272 | |
8868edaf CR |
6273 | u\bul\bli\bim\bmi\bit\bt [-\b-H\bHS\bS] -\b-a\ba |
6274 | u\bul\bli\bim\bmi\bit\bt [-\b-H\bHS\bS] [-\b-b\bbc\bcd\bde\bef\bfi\bik\bkl\blm\bmn\bnp\bpq\bqr\brs\bst\btu\buv\bvx\bxP\bPR\bRT\bT [_\bl_\bi_\bm_\bi_\bt]] | |
6275 | Provides control over the resources available to the shell and | |
6276 | to processes started by it, on systems that allow such control. | |
17345e5a | 6277 | The -\b-H\bH and -\b-S\bS options specify that the hard or soft limit is set |
8868edaf CR |
6278 | for the given resource. A hard limit cannot be increased by a |
6279 | non-root user once it is set; a soft limit may be increased up | |
6280 | to the value of the hard limit. If neither -\b-H\bH nor -\b-S\bS is speci- | |
17345e5a JA |
6281 | fied, both the soft and hard limits are set. The value of _\bl_\bi_\bm_\bi_\bt |
6282 | can be a number in the unit specified for the resource or one of | |
6283 | the special values h\bha\bar\brd\bd, s\bso\bof\bft\bt, or u\bun\bnl\bli\bim\bmi\bit\bte\bed\bd, which stand for the | |
8868edaf CR |
6284 | current hard limit, the current soft limit, and no limit, re- |
6285 | spectively. If _\bl_\bi_\bm_\bi_\bt is omitted, the current value of the soft | |
6286 | limit of the resource is printed, unless the -\b-H\bH option is given. | |
6287 | When more than one resource is specified, the limit name and | |
6288 | unit, if appropriate, are printed before the value. Other op- | |
6289 | tions are interpreted as follows: | |
6290 | -\b-a\ba All current limits are reported; no limits are set | |
17345e5a JA |
6291 | -\b-b\bb The maximum socket buffer size |
6292 | -\b-c\bc The maximum size of core files created | |
6293 | -\b-d\bd The maximum size of a process's data segment | |
6294 | -\b-e\be The maximum scheduling priority ("nice") | |
8868edaf | 6295 | -\b-f\bf The maximum size of files written by the shell and its |
17345e5a JA |
6296 | children |
6297 | -\b-i\bi The maximum number of pending signals | |
a0c0a00f | 6298 | -\b-k\bk The maximum number of kqueues that may be allocated |
17345e5a | 6299 | -\b-l\bl The maximum size that may be locked into memory |
8868edaf | 6300 | -\b-m\bm The maximum resident set size (many systems do not honor |
0001803f | 6301 | this limit) |
17345e5a JA |
6302 | -\b-n\bn The maximum number of open file descriptors (most systems |
6303 | do not allow this value to be set) | |
6304 | -\b-p\bp The pipe size in 512-byte blocks (this may not be set) | |
6305 | -\b-q\bq The maximum number of bytes in POSIX message queues | |
6306 | -\b-r\br The maximum real-time scheduling priority | |
6307 | -\b-s\bs The maximum stack size | |
6308 | -\b-t\bt The maximum amount of cpu time in seconds | |
8868edaf | 6309 | -\b-u\bu The maximum number of processes available to a single |
17345e5a | 6310 | user |
8868edaf | 6311 | -\b-v\bv The maximum amount of virtual memory available to the |
495aee44 | 6312 | shell and, on some systems, to its children |
17345e5a | 6313 | -\b-x\bx The maximum number of file locks |
a0c0a00f | 6314 | -\b-P\bP The maximum number of pseudoterminals |
8868edaf CR |
6315 | -\b-R\bR The maximum time a real-time process can run before |
6316 | blocking, in microseconds | |
17345e5a JA |
6317 | -\b-T\bT The maximum number of threads |
6318 | ||
ac50fbac CR |
6319 | If _\bl_\bi_\bm_\bi_\bt is given, and the -\b-a\ba option is not used, _\bl_\bi_\bm_\bi_\bt is the |
6320 | new value of the specified resource. If no option is given, | |
6321 | then -\b-f\bf is assumed. Values are in 1024-byte increments, except | |
8868edaf CR |
6322 | for -\b-t\bt, which is in seconds; -\b-R\bR, which is in microseconds; -\b-p\bp, |
6323 | which is in units of 512-byte blocks; -\b-P\bP, -\b-T\bT, -\b-b\bb, -\b-k\bk, -\b-n\bn, and | |
6324 | -\b-u\bu, which are unscaled values; and, when in posix mode, -\b-c\bc and | |
6325 | -\b-f\bf, which are in 512-byte increments. The return status is 0 | |
6326 | unless an invalid option or argument is supplied, or an error | |
6327 | occurs while setting a new limit. | |
17345e5a JA |
6328 | |
6329 | u\bum\bma\bas\bsk\bk [-\b-p\bp] [-\b-S\bS] [_\bm_\bo_\bd_\be] | |
6330 | The user file-creation mask is set to _\bm_\bo_\bd_\be. If _\bm_\bo_\bd_\be begins with | |
8868edaf CR |
6331 | a digit, it is interpreted as an octal number; otherwise it is |
6332 | interpreted as a symbolic mode mask similar to that accepted by | |
6333 | _\bc_\bh_\bm_\bo_\bd(1). If _\bm_\bo_\bd_\be is omitted, the current value of the mask is | |
6334 | printed. The -\b-S\bS option causes the mask to be printed in sym- | |
6335 | bolic form; the default output is an octal number. If the -\b-p\bp | |
17345e5a JA |
6336 | option is supplied, and _\bm_\bo_\bd_\be is omitted, the output is in a form |
6337 | that may be reused as input. The return status is 0 if the mode | |
8868edaf | 6338 | was successfully changed or if no _\bm_\bo_\bd_\be argument was supplied, |
17345e5a JA |
6339 | and false otherwise. |
6340 | ||
6341 | u\bun\bna\bal\bli\bia\bas\bs [-a\ba] [_\bn_\ba_\bm_\be ...] | |
8868edaf CR |
6342 | Remove each _\bn_\ba_\bm_\be from the list of defined aliases. If -\b-a\ba is |
6343 | supplied, all alias definitions are removed. The return value | |
17345e5a JA |
6344 | is true unless a supplied _\bn_\ba_\bm_\be is not a defined alias. |
6345 | ||
ac50fbac | 6346 | u\bun\bns\bse\bet\bt [-f\bfv\bv] [-n\bn] [_\bn_\ba_\bm_\be ...] |
8868edaf | 6347 | For each _\bn_\ba_\bm_\be, remove the corresponding variable or function. |
ac50fbac | 6348 | If the -\b-v\bv option is given, each _\bn_\ba_\bm_\be refers to a shell variable, |
8868edaf CR |
6349 | and that variable is removed. Read-only variables may not be |
6350 | unset. If -\b-f\bf is specified, each _\bn_\ba_\bm_\be refers to a shell func- | |
6351 | tion, and the function definition is removed. If the -\b-n\bn option | |
6352 | is supplied, and _\bn_\ba_\bm_\be is a variable with the _\bn_\ba_\bm_\be_\br_\be_\bf attribute, | |
6353 | _\bn_\ba_\bm_\be will be unset rather than the variable it references. -\b-n\bn | |
6354 | has no effect if the -\b-f\bf option is supplied. If no options are | |
6355 | supplied, each _\bn_\ba_\bm_\be refers to a variable; if there is no vari- | |
6356 | able by that name, a function with that name, if any, is unset. | |
6357 | Each unset variable or function is removed from the environment | |
6358 | passed to subsequent commands. If any of B\bBA\bAS\bSH\bH_\b_A\bAL\bLI\bIA\bAS\bSE\bES\bS, | |
6359 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV0\b0, B\bBA\bAS\bSH\bH_\b_C\bCM\bMD\bDS\bS, B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMM\bMA\bAN\bND\bD, B\bBA\bAS\bSH\bH_\b_S\bSU\bUB\bBS\bSH\bHE\bEL\bLL\bL, B\bBA\bAS\bSH\bHP\bPI\bID\bD, | |
6360 | C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDB\bBR\bRE\bEA\bAK\bKS\bS, D\bDI\bIR\bRS\bST\bTA\bAC\bCK\bK, E\bEP\bPO\bOC\bCH\bHR\bRE\bEA\bAL\bLT\bTI\bIM\bME\bE, E\bEP\bPO\bOC\bCH\bHS\bSE\bEC\bCO\bON\bND\bDS\bS, F\bFU\bUN\bNC\bC-\b- | |
6361 | N\bNA\bAM\bME\bE, G\bGR\bRO\bOU\bUP\bPS\bS, H\bHI\bIS\bST\bTC\bCM\bMD\bD, L\bLI\bIN\bNE\bEN\bNO\bO, R\bRA\bAN\bND\bDO\bOM\bM, S\bSE\bEC\bCO\bON\bND\bDS\bS, or S\bSR\bRA\bAN\bND\bDO\bOM\bM are | |
ac50fbac CR |
6362 | unset, they lose their special properties, even if they are sub- |
6363 | sequently reset. The exit status is true unless a _\bn_\ba_\bm_\be is read- | |
74091dd4 | 6364 | only or may not be unset. |
ac50fbac | 6365 | |
8868edaf | 6366 | w\bwa\bai\bit\bt [-\b-f\bfn\bn] [-\b-p\bp _\bv_\ba_\br_\bn_\ba_\bm_\be] [_\bi_\bd _\b._\b._\b.] |
ac50fbac | 6367 | Wait for each specified child process and return its termination |
8868edaf CR |
6368 | status. Each _\bi_\bd may be a process ID or a job specification; if |
6369 | a job spec is given, all processes in that job's pipeline are | |
6370 | waited for. If _\bi_\bd is not given, w\bwa\bai\bit\bt waits for all running | |
6371 | background jobs and the last-executed process substitution, if | |
6372 | its process id is the same as $\b$!\b!, and the return status is zero. | |
6373 | If the -\b-n\bn option is supplied, w\bwa\bai\bit\bt waits for a single job from | |
6374 | the list of _\bi_\bds or, if no _\bi_\bds are supplied, any job, to complete | |
6375 | and returns its exit status. If none of the supplied arguments | |
6376 | is a child of the shell, or if no arguments are supplied and the | |
6377 | shell has no unwaited-for children, the exit status is 127. If | |
6378 | the -\b-p\bp option is supplied, the process or job identifier of the | |
6379 | job for which the exit status is returned is assigned to the | |
6380 | variable _\bv_\ba_\br_\bn_\ba_\bm_\be named by the option argument. The variable | |
6381 | will be unset initially, before any assignment. This is useful | |
6382 | only when the -\b-n\bn option is supplied. Supplying the -\b-f\bf option, | |
6383 | when job control is enabled, forces w\bwa\bai\bit\bt to wait for _\bi_\bd to ter- | |
6384 | minate before returning its status, instead of returning when it | |
6385 | changes status. If _\bi_\bd specifies a non-existent process or job, | |
74091dd4 CR |
6386 | the return status is 127. If w\bwa\bai\bit\bt is interrupted by a signal, |
6387 | the return status will be greater than 128, as described under | |
6388 | S\bSI\bIG\bGN\bNA\bAL\bLS\bS above. Otherwise, the return status is the exit status | |
6389 | of the last process or job waited for. | |
8868edaf CR |
6390 | |
6391 | S\bSH\bHE\bEL\bLL\bL C\bCO\bOM\bMP\bPA\bAT\bTI\bIB\bBI\bIL\bLI\bIT\bTY\bY M\bMO\bOD\bDE\bE | |
74091dd4 CR |
6392 | Bash-4.0 introduced the concept of a _\bs_\bh_\be_\bl_\bl _\bc_\bo_\bm_\bp_\ba_\bt_\bi_\bb_\bi_\bl_\bi_\bt_\by _\bl_\be_\bv_\be_\bl, speci- |
6393 | fied as a set of options to the shopt builtin ( c\bco\bom\bmp\bpa\bat\bt3\b31\b1, c\bco\bom\bmp\bpa\bat\bt3\b32\b2, | |
6394 | c\bco\bom\bmp\bpa\bat\bt4\b40\b0, c\bco\bom\bmp\bpa\bat\bt4\b41\b1, and so on). There is only one current compatibil- | |
6395 | ity level -- each option is mutually exclusive. The compatibility | |
6396 | level is intended to allow users to select behavior from previous ver- | |
6397 | sions that is incompatible with newer versions while they migrate | |
6398 | scripts to use current features and behavior. It's intended to be a | |
6399 | temporary solution. | |
8868edaf CR |
6400 | |
6401 | This section does not mention behavior that is standard for a particu- | |
6402 | lar version (e.g., setting c\bco\bom\bmp\bpa\bat\bt3\b32\b2 means that quoting the rhs of the | |
6403 | regexp matching operator quotes special regexp characters in the word, | |
74091dd4 | 6404 | which is default behavior in bash-3.2 and subsequent versions). |
8868edaf CR |
6405 | |
6406 | If a user enables, say, c\bco\bom\bmp\bpa\bat\bt3\b32\b2, it may affect the behavior of other | |
6407 | compatibility levels up to and including the current compatibility | |
6408 | level. The idea is that each compatibility level controls behavior | |
6409 | that changed in that version of b\bba\bas\bsh\bh, but that behavior may have been | |
6410 | present in earlier versions. For instance, the change to use locale- | |
6411 | based comparisons with the [\b[[\b[ command came in bash-4.1, and earlier | |
6412 | versions used ASCII-based comparisons, so enabling c\bco\bom\bmp\bpa\bat\bt3\b32\b2 will enable | |
6413 | ASCII-based comparisons as well. That granularity may not be suffi- | |
6414 | cient for all uses, and as a result users should employ compatibility | |
6415 | levels carefully. Read the documentation for a particular feature to | |
6416 | find out the current behavior. | |
6417 | ||
6418 | Bash-4.3 introduced a new shell variable: B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT. The value as- | |
6419 | signed to this variable (a decimal version number like 4.2, or an inte- | |
6420 | ger corresponding to the c\bco\bom\bmp\bpa\bat\bt_\bN_\bN option, like 42) determines the com- | |
6421 | patibility level. | |
6422 | ||
6423 | Starting with bash-4.4, Bash has begun deprecating older compatibility | |
6424 | levels. Eventually, the options will be removed in favor of B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bM-\b- | |
6425 | P\bPA\bAT\bT. | |
6426 | ||
6427 | Bash-5.0 is the final version for which there will be an individual | |
6428 | shopt option for the previous version. Users should use B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT on | |
6429 | bash-5.0 and later versions. | |
6430 | ||
6431 | The following table describes the behavior changes controlled by each | |
6432 | compatibility level setting. The c\bco\bom\bmp\bpa\bat\bt_\bN_\bN tag is used as shorthand for | |
6433 | setting the compatibility level to _\bN_\bN using one of the following mecha- | |
6434 | nisms. For versions prior to bash-5.0, the compatibility level may be | |
6435 | set using the corresponding c\bco\bom\bmp\bpa\bat\bt_\bN_\bN shopt option. For bash-4.3 and | |
6436 | later versions, the B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT variable is preferred, and it is re- | |
6437 | quired for bash-5.1 and later versions. | |
6438 | ||
6439 | c\bco\bom\bmp\bpa\bat\bt3\b31\b1 | |
6440 | +\bo quoting the rhs of the [\b[[\b[ command's regexp matching oper- | |
6441 | ator (=~) has no special effect | |
6442 | ||
6443 | c\bco\bom\bmp\bpa\bat\bt3\b32\b2 | |
6444 | +\bo interrupting a command list such as "a ; b ; c" causes | |
6445 | the execution of the next command in the list (in | |
6446 | bash-4.0 and later versions, the shell acts as if it re- | |
6447 | ceived the interrupt, so interrupting one command in a | |
6448 | list aborts the execution of the entire list) | |
6449 | ||
6450 | c\bco\bom\bmp\bpa\bat\bt4\b40\b0 | |
6451 | +\bo the <\b< and >\b> operators to the [\b[[\b[ command do not consider | |
6452 | the current locale when comparing strings; they use ASCII | |
6453 | ordering. Bash versions prior to bash-4.1 use ASCII col- | |
6454 | lation and _\bs_\bt_\br_\bc_\bm_\bp(3); bash-4.1 and later use the current | |
6455 | locale's collation sequence and _\bs_\bt_\br_\bc_\bo_\bl_\bl(3). | |
6456 | ||
6457 | c\bco\bom\bmp\bpa\bat\bt4\b41\b1 | |
6458 | +\bo in _\bp_\bo_\bs_\bi_\bx mode, t\bti\bim\bme\be may be followed by options and still | |
6459 | be recognized as a reserved word (this is POSIX interpre- | |
6460 | tation 267) | |
6461 | +\bo in _\bp_\bo_\bs_\bi_\bx mode, the parser requires that an even number of | |
6462 | single quotes occur in the _\bw_\bo_\br_\bd portion of a double- | |
6463 | quoted parameter expansion and treats them specially, so | |
6464 | that characters within the single quotes are considered | |
6465 | quoted (this is POSIX interpretation 221) | |
6466 | ||
6467 | c\bco\bom\bmp\bpa\bat\bt4\b42\b2 | |
6468 | +\bo the replacement string in double-quoted pattern substitu- | |
6469 | tion does not undergo quote removal, as it does in ver- | |
6470 | sions after bash-4.2 | |
6471 | +\bo in posix mode, single quotes are considered special when | |
6472 | expanding the _\bw_\bo_\br_\bd portion of a double-quoted parameter | |
6473 | expansion and can be used to quote a closing brace or | |
6474 | other special character (this is part of POSIX interpre- | |
6475 | tation 221); in later versions, single quotes are not | |
6476 | special within double-quoted word expansions | |
6477 | ||
6478 | c\bco\bom\bmp\bpa\bat\bt4\b43\b3 | |
6479 | +\bo the shell does not print a warning message if an attempt | |
6480 | is made to use a quoted compound assignment as an argu- | |
74091dd4 CR |
6481 | ment to declare (e.g., declare -a foo='(1 2)'). Later |
6482 | versions warn that this usage is deprecated | |
8868edaf CR |
6483 | +\bo word expansion errors are considered non-fatal errors |
6484 | that cause the current command to fail, even in posix | |
6485 | mode (the default behavior is to make them fatal errors | |
6486 | that cause the shell to exit) | |
6487 | +\bo when executing a shell function, the loop state | |
6488 | (while/until/etc.) is not reset, so b\bbr\bre\bea\bak\bk or c\bco\bon\bnt\bti\bin\bnu\bue\be in | |
6489 | that function will break or continue loops in the calling | |
6490 | context. Bash-4.4 and later reset the loop state to pre- | |
6491 | vent this | |
6492 | ||
6493 | c\bco\bom\bmp\bpa\bat\bt4\b44\b4 | |
6494 | +\bo the shell sets up the values used by B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV and | |
6495 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGC\bC so they can expand to the shell's positional | |
6496 | parameters even if extended debugging mode is not enabled | |
6497 | +\bo a subshell inherits loops from its parent context, so | |
6498 | b\bbr\bre\bea\bak\bk or c\bco\bon\bnt\bti\bin\bnu\bue\be will cause the subshell to exit. | |
6499 | Bash-5.0 and later reset the loop state to prevent the | |
6500 | exit | |
6501 | +\bo variable assignments preceding builtins like e\bex\bxp\bpo\bor\brt\bt and | |
6502 | r\bre\bea\bad\bdo\bon\bnl\bly\by that set attributes continue to affect variables | |
6503 | with the same name in the calling environment even if the | |
6504 | shell is not in posix mode | |
6505 | ||
6506 | c\bco\bom\bmp\bpa\bat\bt5\b50\b0 | |
6507 | +\bo Bash-5.1 changed the way $\b$R\bRA\bAN\bND\bDO\bOM\bM is generated to intro- | |
6508 | duce slightly more randomness. If the shell compatibility | |
6509 | level is set to 50 or lower, it reverts to the method | |
6510 | from bash-5.0 and previous versions, so seeding the ran- | |
6511 | dom number generator by assigning a value to R\bRA\bAN\bND\bDO\bOM\bM will | |
6512 | produce the same sequence as in bash-5.0 | |
6513 | +\bo If the command hash table is empty, bash versions prior | |
6514 | to bash-5.1 printed an informational message to that ef- | |
6515 | fect, even when producing output that can be reused as | |
6516 | input. Bash-5.1 suppresses that message when the -\b-l\bl op- | |
6517 | tion is supplied. | |
17345e5a | 6518 | |
74091dd4 CR |
6519 | c\bco\bom\bmp\bpa\bat\bt5\b51\b1 |
6520 | +\bo The u\bun\bns\bse\bet\bt builtin treats attempts to unset array sub- | |
6521 | scripts @\b@ and *\b* differently depending on whether the ar- | |
6522 | ray is indexed or associative, and differently than in | |
6523 | previous versions. | |
6524 | ||
17345e5a JA |
6525 | R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTE\bED\bD S\bSH\bHE\bEL\bLL\bL |
6526 | If b\bba\bas\bsh\bh is started with the name r\brb\bba\bas\bsh\bh, or the -\b-r\br option is supplied at | |
74091dd4 CR |
6527 | invocation, the shell becomes restricted. A restricted shell is used |
6528 | to set up an environment more controlled than the standard shell. It | |
6529 | behaves identically to b\bba\bas\bsh\bh with the exception that the following are | |
17345e5a JA |
6530 | disallowed or not performed: |
6531 | ||
6532 | +\bo changing directories with c\bcd\bd | |
6533 | ||
74091dd4 | 6534 | +\bo setting or unsetting the values of S\bSH\bHE\bEL\bLL\bL, P\bPA\bAT\bTH\bH, H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE, E\bEN\bNV\bV, |
8868edaf | 6535 | or B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV |
17345e5a JA |
6536 | |
6537 | +\bo specifying command names containing /\b/ | |
6538 | ||
74091dd4 | 6539 | +\bo specifying a filename containing a /\b/ as an argument to the .\b. |
17345e5a JA |
6540 | builtin command |
6541 | ||
74091dd4 | 6542 | +\bo specifying a filename containing a slash as an argument to the |
8868edaf CR |
6543 | h\bhi\bis\bst\bto\bor\bry\by builtin command |
6544 | ||
74091dd4 | 6545 | +\bo specifying a filename containing a slash as an argument to the |
17345e5a JA |
6546 | -\b-p\bp option to the h\bha\bas\bsh\bh builtin command |
6547 | ||
74091dd4 | 6548 | +\bo importing function definitions from the shell environment at |
17345e5a JA |
6549 | startup |
6550 | ||
74091dd4 | 6551 | +\bo parsing the value of S\bSH\bHE\bEL\bLL\bLO\bOP\bPT\bTS\bS from the shell environment at |
17345e5a JA |
6552 | startup |
6553 | ||
6554 | +\bo redirecting output using the >, >|, <>, >&, &>, and >> redirect- | |
6555 | ion operators | |
6556 | ||
6557 | +\bo using the e\bex\bxe\bec\bc builtin command to replace the shell with another | |
6558 | command | |
6559 | ||
74091dd4 | 6560 | +\bo adding or deleting builtin commands with the -\b-f\bf and -\b-d\bd options |
17345e5a JA |
6561 | to the e\ben\bna\bab\bbl\ble\be builtin command |
6562 | ||
74091dd4 | 6563 | +\bo using the e\ben\bna\bab\bbl\ble\be builtin command to enable disabled shell |
17345e5a JA |
6564 | builtins |
6565 | ||
6566 | +\bo specifying the -\b-p\bp option to the c\bco\bom\bmm\bma\ban\bnd\bd builtin command | |
6567 | ||
74091dd4 CR |
6568 | +\bo turning off restricted mode with s\bse\bet\bt +\b+r\br or s\bsh\bho\bop\bpt\bt -\b-u\bu r\bre\be-\b- |
6569 | s\bst\btr\bri\bic\bct\bte\bed\bd_\b_s\bsh\bhe\bel\bll\bl. | |
17345e5a JA |
6570 | |
6571 | These restrictions are enforced after any startup files are read. | |
6572 | ||
6573 | When a command that is found to be a shell script is executed (see C\bCO\bOM\bM-\b- | |
d233b485 | 6574 | M\bMA\bAN\bND\bD E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN above), r\brb\bba\bas\bsh\bh turns off any restrictions in the shell |
17345e5a JA |
6575 | spawned to execute the script. |
6576 | ||
6577 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
6578 | _\bB_\ba_\bs_\bh _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl, Brian Fox and Chet Ramey | |
6579 | _\bT_\bh_\be _\bG_\bn_\bu _\bR_\be_\ba_\bd_\bl_\bi_\bn_\be _\bL_\bi_\bb_\br_\ba_\br_\by, Brian Fox and Chet Ramey | |
6580 | _\bT_\bh_\be _\bG_\bn_\bu _\bH_\bi_\bs_\bt_\bo_\br_\by _\bL_\bi_\bb_\br_\ba_\br_\by, Brian Fox and Chet Ramey | |
d233b485 | 6581 | _\bP_\bo_\br_\bt_\ba_\bb_\bl_\be _\bO_\bp_\be_\br_\ba_\bt_\bi_\bn_\bg _\bS_\by_\bs_\bt_\be_\bm _\bI_\bn_\bt_\be_\br_\bf_\ba_\bc_\be _\b(_\bP_\bO_\bS_\bI_\bX_\b) _\bP_\ba_\br_\bt _\b2_\b: _\bS_\bh_\be_\bl_\bl _\ba_\bn_\bd _\bU_\bt_\bi_\bl_\bi_\b- |
ac50fbac CR |
6582 | _\bt_\bi_\be_\bs, IEEE -- |
6583 | http://pubs.opengroup.org/onlinepubs/9699919799/ | |
6584 | http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode | |
17345e5a JA |
6585 | _\bs_\bh(1), _\bk_\bs_\bh(1), _\bc_\bs_\bh(1) |
6586 | _\be_\bm_\ba_\bc_\bs(1), _\bv_\bi(1) | |
6587 | _\br_\be_\ba_\bd_\bl_\bi_\bn_\be(3) | |
6588 | ||
6589 | F\bFI\bIL\bLE\bES\bS | |
6590 | _\b/_\bb_\bi_\bn_\b/_\bb_\ba_\bs_\bh | |
6591 | The b\bba\bas\bsh\bh executable | |
6592 | _\b/_\be_\bt_\bc_\b/_\bp_\br_\bo_\bf_\bi_\bl_\be | |
6593 | The systemwide initialization file, executed for login shells | |
6594 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bp_\br_\bo_\bf_\bi_\bl_\be | |
6595 | The personal initialization file, executed for login shells | |
6596 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc | |
6597 | The individual per-interactive-shell startup file | |
6598 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bl_\bo_\bg_\bo_\bu_\bt | |
d233b485 | 6599 | The individual login shell cleanup file, executed when a login |
17345e5a | 6600 | shell exits |
74091dd4 CR |
6601 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bh_\bi_\bs_\bt_\bo_\br_\by |
6602 | The default value of H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE, the file in which bash saves the | |
6603 | command history | |
17345e5a JA |
6604 | _\b~_\b/_\b._\bi_\bn_\bp_\bu_\bt_\br_\bc |
6605 | Individual _\br_\be_\ba_\bd_\bl_\bi_\bn_\be initialization file | |
6606 | ||
6607 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS | |
6608 | Brian Fox, Free Software Foundation | |
6609 | bfox@gnu.org | |
6610 | ||
6611 | Chet Ramey, Case Western Reserve University | |
0001803f | 6612 | chet.ramey@case.edu |
17345e5a JA |
6613 | |
6614 | B\bBU\bUG\bG R\bRE\bEP\bPO\bOR\bRT\bTS\bS | |
6615 | If you find a bug in b\bba\bas\bsh\bh,\b, you should report it. But first, you should | |
74091dd4 CR |
6616 | make sure that it really is a bug, and that it appears in the latest |
6617 | version of b\bba\bas\bsh\bh. The latest version is always available from | |
6618 | _\bf_\bt_\bp_\b:_\b/_\b/_\bf_\bt_\bp_\b._\bg_\bn_\bu_\b._\bo_\br_\bg_\b/_\bp_\bu_\bb_\b/_\bg_\bn_\bu_\b/_\bb_\ba_\bs_\bh_\b/ and _\bh_\bt_\bt_\bp_\b:_\b/_\b/_\bg_\bi_\bt_\b._\bs_\ba_\bv_\ba_\bn_\b- | |
6619 | _\bn_\ba_\bh_\b._\bg_\bn_\bu_\b._\bo_\br_\bg_\b/_\bc_\bg_\bi_\bt_\b/_\bb_\ba_\bs_\bh_\b._\bg_\bi_\bt_\b/_\bs_\bn_\ba_\bp_\bs_\bh_\bo_\bt_\b/_\bb_\ba_\bs_\bh_\b-_\bm_\ba_\bs_\bt_\be_\br_\b._\bt_\ba_\br_\b._\bg_\bz. | |
495aee44 | 6620 | |
d233b485 CR |
6621 | Once you have determined that a bug actually exists, use the _\bb_\ba_\bs_\bh_\bb_\bu_\bg |
6622 | command to submit a bug report. If you have a fix, you are encouraged | |
6623 | to mail that as well! Suggestions and `philosophical' bug reports may | |
6624 | be mailed to _\bb_\bu_\bg_\b-_\bb_\ba_\bs_\bh_\b@_\bg_\bn_\bu_\b._\bo_\br_\bg or posted to the Usenet newsgroup | |
17345e5a JA |
6625 | g\bgn\bnu\bu.\b.b\bba\bas\bsh\bh.\b.b\bbu\bug\bg. |
6626 | ||
6627 | ALL bug reports should include: | |
6628 | ||
6629 | The version number of b\bba\bas\bsh\bh | |
6630 | The hardware and operating system | |
6631 | The compiler used to compile | |
6632 | A description of the bug behaviour | |
6633 | A short script or `recipe' which exercises the bug | |
6634 | ||
d233b485 | 6635 | _\bb_\ba_\bs_\bh_\bb_\bu_\bg inserts the first three items automatically into the template |
17345e5a JA |
6636 | it provides for filing a bug report. |
6637 | ||
6638 | Comments and bug reports concerning this manual page should be directed | |
ac50fbac | 6639 | to _\bc_\bh_\be_\bt_\b._\br_\ba_\bm_\be_\by_\b@_\bc_\ba_\bs_\be_\b._\be_\bd_\bu. |
17345e5a JA |
6640 | |
6641 | B\bBU\bUG\bGS\bS | |
6642 | It's too big and too slow. | |
6643 | ||
6644 | There are some subtle differences between b\bba\bas\bsh\bh and traditional versions | |
6645 | of s\bsh\bh, mostly because of the P\bPO\bOS\bSI\bIX\bX specification. | |
6646 | ||
6647 | Aliases are confusing in some uses. | |
6648 | ||
6649 | Shell builtin commands and functions are not stoppable/restartable. | |
6650 | ||
6651 | Compound commands and command sequences of the form `a ; b ; c' are not | |
d233b485 CR |
6652 | handled gracefully when process suspension is attempted. When a |
6653 | process is stopped, the shell immediately executes the next command in | |
6654 | the sequence. It suffices to place the sequence of commands between | |
6655 | parentheses to force it into a subshell, which may be stopped as a | |
17345e5a JA |
6656 | unit. |
6657 | ||
6658 | Array variables may not (yet) be exported. | |
6659 | ||
6660 | There may be only one active coprocess at a time. | |
6661 | ||
6662 | ||
6663 | ||
74091dd4 | 6664 | GNU Bash 5.2 2022 September 19 BASH(1) |