]>
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 | |
712f80b0 | 12 | Bash is Copyright (C) 1989-2020 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 |
712f80b0 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- | |
712f80b0 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). | |
712f80b0 | 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). |
712f80b0 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. |
712f80b0 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 |
712f80b0 | 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] | |
712f80b0 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 |
712f80b0 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. |
712f80b0 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 | ||
712f80b0 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 | |
712f80b0 | 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 |
712f80b0 | 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. | |
712f80b0 | 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- | |
712f80b0 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 | |
712f80b0 | 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 | |
712f80b0 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 | |
712f80b0 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 | |
712f80b0 | 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 |
712f80b0 | 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 | |
712f80b0 | 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 | |
712f80b0 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 | |
712f80b0 | 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 | ||
712f80b0 CR |
133 | An _\bi_\bn_\bt_\be_\br_\ba_\bc_\bt_\bi_\bv_\be shell is one started without non-option arguments (un- |
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)), |
712f80b0 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 | |
712f80b0 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 | ||
712f80b0 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, |
712f80b0 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 |
712f80b0 | 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 | |
712f80b0 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 | ||
712f80b0 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 | |
712f80b0 | 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 | ||
712f80b0 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- |
712f80b0 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 | |
712f80b0 | 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, |
712f80b0 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 | |
495aee44 | 194 | connected to a network connection, as when executed by the remote shell |
712f80b0 CR |
195 | daemon, usually _\br_\bs_\bh_\bd, or the secure shell daemon _\bs_\bs_\bh_\bd. If b\bba\bas\bsh\bh deter- |
196 | mines it is being run in this fashion, it reads and executes commands | |
197 | from _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc, if that file exists and is readable. It will not do | |
198 | this if invoked as s\bsh\bh. The -\b--\b-n\bno\bor\brc\bc option may be used to inhibit this | |
199 | behavior, and the -\b--\b-r\brc\bcf\bfi\bil\ble\be option may be used to force another file to | |
200 | be read, but neither _\br_\bs_\bh_\bd nor _\bs_\bs_\bh_\bd generally invoke the shell with | |
ac50fbac | 201 | 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, | |
712f80b0 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 | |
712f80b0 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 | |
712f80b0 | 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 | |
240 | S\bSi\bim\bmp\bpl\ble\be C\bCo\bom\bmm\bma\ban\bnd\bds\bs | |
712f80b0 CR |
241 | A _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd is a sequence of optional variable assignments fol- |
242 | lowed by b\bbl\bla\ban\bnk\bk-separated words and redirections, and terminated by a | |
17345e5a | 243 | _\bc_\bo_\bn_\bt_\br_\bo_\bl _\bo_\bp_\be_\br_\ba_\bt_\bo_\br. The first word specifies the command to be executed, |
712f80b0 CR |
244 | and is passed as argument zero. The remaining words are passed as ar- |
245 | guments to the invoked command. | |
17345e5a | 246 | |
712f80b0 | 247 | 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 |
248 | the command is terminated by signal _\bn. |
249 | ||
250 | P\bPi\bip\bpe\bel\bli\bin\bne\bes\bs | |
712f80b0 | 251 | A _\bp_\bi_\bp_\be_\bl_\bi_\bn_\be is a sequence of one or more commands separated by one of |
17345e5a JA |
252 | the control operators |\b| or |\b|&\b&. The format for a pipeline is: |
253 | ||
254 | [t\bti\bim\bme\be [-\b-p\bp]] [ ! ] _\bc_\bo_\bm_\bm_\ba_\bn_\bd [ [|\b|||\b|&\b&] _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2 ... ] | |
255 | ||
712f80b0 CR |
256 | The standard output of _\bc_\bo_\bm_\bm_\ba_\bn_\bd is connected via a pipe to the standard |
257 | input of _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2. This connection is performed before any redirec- | |
17345e5a | 258 | tions specified by the command (see R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN below). If |\b|&\b& is used, |
712f80b0 CR |
259 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd's standard error, in addition to its standard output, is con- |
260 | nected to _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2's standard input through the pipe; it is shorthand | |
261 | for 2\b2>\b>&\b&1\b1 |\b|. This implicit redirection of the standard error to the | |
262 | standard output is performed after any redirections specified by the | |
ac50fbac | 263 | command. |
17345e5a JA |
264 | |
265 | The return status of a pipeline is the exit status of the last command, | |
712f80b0 CR |
266 | 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 |
267 | pipeline's return status is the value of the last (rightmost) command | |
268 | to exit with a non-zero status, or zero if all commands exit success- | |
17345e5a | 269 | fully. If the reserved word !\b! precedes a pipeline, the exit status of |
712f80b0 CR |
270 | that pipeline is the logical negation of the exit status as described |
271 | above. The shell waits for all commands in the pipeline to terminate | |
17345e5a JA |
272 | before returning a value. |
273 | ||
712f80b0 CR |
274 | If the t\bti\bim\bme\be reserved word precedes a pipeline, the elapsed as well as |
275 | user and system time consumed by its execution are reported when the | |
276 | pipeline terminates. The -\b-p\bp option changes the output format to that | |
277 | specified by POSIX. When the shell is in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, it does not rec- | |
278 | ognize t\bti\bim\bme\be as a reserved word if the next token begins with a `-'. | |
279 | The T\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT variable may be set to a format string that specifies | |
280 | how the timing information should be displayed; see the description of | |
495aee44 CR |
281 | 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. |
282 | ||
283 | 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 | |
712f80b0 CR |
284 | this case, the shell displays the total user and system time consumed |
285 | by the shell and its children. The T\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT variable may be used to | |
495aee44 | 286 | specify the format of the time information. |
17345e5a | 287 | |
712f80b0 CR |
288 | Each command in a pipeline is executed as a separate process (i.e., in |
289 | 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\bNM\bME\bEN\bNT\bT for a description of a | |
290 | subshell environment. If the l\bla\bas\bst\btp\bpi\bip\bpe\be option is enabled using the | |
d233b485 CR |
291 | s\bsh\bho\bop\bpt\bt builtin (see the description of s\bsh\bho\bop\bpt\bt below), the last element of |
292 | a pipeline may be run by the shell process. | |
17345e5a JA |
293 | |
294 | L\bLi\bis\bst\bts\bs | |
712f80b0 | 295 | A _\bl_\bi_\bs_\bt is a sequence of one or more pipelines separated by one of the |
17345e5a JA |
296 | operators ;\b;, &\b&, &\b&&\b&, or |\b||\b|, and optionally terminated by one of ;\b;, &\b&, or |
297 | <\b<n\bne\bew\bwl\bli\bin\bne\be>\b>. | |
298 | ||
299 | Of these list operators, &\b&&\b& and |\b||\b| have equal precedence, followed by ;\b; | |
300 | and &\b&, which have equal precedence. | |
301 | ||
712f80b0 | 302 | A sequence of one or more newlines may appear in a _\bl_\bi_\bs_\bt instead of a |
17345e5a JA |
303 | semicolon to delimit commands. |
304 | ||
712f80b0 CR |
305 | If a command is terminated by the control operator &\b&, the shell exe- |
306 | cutes the command in the _\bb_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd in a subshell. The shell does not | |
307 | wait for the command to finish, and the return status is 0. These are | |
308 | referred to as _\ba_\bs_\by_\bn_\bc_\bh_\br_\bo_\bn_\bo_\bu_\bs commands. Commands separated by a ;\b; are | |
d233b485 | 309 | executed sequentially; the shell waits for each command to terminate in |
712f80b0 | 310 | turn. The return status is the exit status of the last command exe- |
d233b485 CR |
311 | cuted. |
312 | ||
712f80b0 CR |
313 | AND and OR lists are sequences of one or more pipelines separated by |
314 | the &\b&&\b& and |\b||\b| control operators, respectively. AND and OR lists are | |
17345e5a JA |
315 | executed with left associativity. An AND list has the form |
316 | ||
317 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1 &\b&&\b& _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2 | |
318 | ||
712f80b0 | 319 | _\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 | 320 | of zero (success). |
17345e5a JA |
321 | |
322 | An OR list has the form | |
323 | ||
324 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b1 |\b||\b| _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b2 | |
325 | ||
712f80b0 CR |
326 | _\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 |
327 | status. The return status of AND and OR lists is the exit status of | |
17345e5a JA |
328 | the last command executed in the list. |
329 | ||
330 | C\bCo\bom\bmp\bpo\bou\bun\bnd\bd C\bCo\bom\bmm\bma\ban\bnd\bds\bs | |
712f80b0 CR |
331 | 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 |
332 | command's description may be separated from the rest of the command by | |
333 | one or more newlines, and may be followed by a newline in place of a | |
ac50fbac CR |
334 | semicolon. |
335 | ||
712f80b0 CR |
336 | (_\bl_\bi_\bs_\bt) _\bl_\bi_\bs_\bt is executed in a subshell environment (see C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXE\bEC\bCU\bU-\b- |
337 | T\bTI\bIO\bON\bN E\bEN\bNV\bVI\bIR\bRO\bON\bNM\bME\bEN\bNT\bT below). Variable assignments and builtin com- | |
338 | mands that affect the shell's environment do not remain in ef- | |
339 | fect after the command completes. The return status is the exit | |
340 | status of _\bl_\bi_\bs_\bt. | |
17345e5a JA |
341 | |
342 | { _\bl_\bi_\bs_\bt; } | |
712f80b0 CR |
343 | _\bl_\bi_\bs_\bt is simply executed in the current shell environment. _\bl_\bi_\bs_\bt |
344 | must be terminated with a newline or semicolon. This is known | |
345 | as a _\bg_\br_\bo_\bu_\bp _\bc_\bo_\bm_\bm_\ba_\bn_\bd. The return status is the exit status of | |
346 | _\bl_\bi_\bs_\bt. Note that unlike the metacharacters (\b( and )\b), {\b{ and }\b} are | |
17345e5a | 347 | _\br_\be_\bs_\be_\br_\bv_\be_\bd _\bw_\bo_\br_\bd_\bs and must occur where a reserved word is permitted |
712f80b0 CR |
348 | to be recognized. Since they do not cause a word break, they |
349 | must be separated from _\bl_\bi_\bs_\bt by whitespace or another shell | |
17345e5a JA |
350 | metacharacter. |
351 | ||
352 | ((_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn)) | |
712f80b0 CR |
353 | The _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn is evaluated according to the rules described be- |
354 | 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 | |
355 | is non-zero, the return status is 0; otherwise the return status | |
356 | is 1. This is exactly equivalent to l\ble\bet\bt "\b"_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn"\b". | |
17345e5a JA |
357 | |
358 | [\b[[\b[ _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn ]\b]]\b] | |
712f80b0 CR |
359 | Return a status of 0 or 1 depending on the evaluation of the |
360 | conditional expression _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn. Expressions are composed of | |
361 | 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. | |
362 | Word splitting and pathname expansion are not performed on the | |
363 | words between the [\b[[\b[ and ]\b]]\b]; tilde expansion, parameter and | |
364 | variable expansion, arithmetic expansion, command substitution, | |
365 | process substitution, and quote removal are performed. Condi- | |
17345e5a JA |
366 | tional operators such as -\b-f\bf must be unquoted to be recognized as |
367 | primaries. | |
368 | ||
712f80b0 | 369 | When used with [\b[[\b[, the <\b< and >\b> operators sort lexicographically |
0001803f CR |
370 | using the current locale. |
371 | ||
712f80b0 | 372 | When the =\b==\b= and !\b!=\b= operators are used, the string to the right |
17345e5a | 373 | of the operator is considered a pattern and matched according to |
ac50fbac CR |
374 | 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- |
375 | g\bgl\blo\bob\bb shell option were enabled. The =\b= operator is equivalent to | |
712f80b0 CR |
376 | =\b==\b=. If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh shell option is enabled, the match is |
377 | performed without regard to the case of alphabetic characters. | |
378 | The return value is 0 if the string matches (=\b==\b=) or does not | |
379 | match (!\b!=\b=) the pattern, and 1 otherwise. Any part of the pat- | |
380 | tern may be quoted to force the quoted portion to be matched as | |
ac50fbac CR |
381 | a string. |
382 | ||
712f80b0 CR |
383 | An additional binary operator, =\b=~\b~, is available, with the same |
384 | precedence as =\b==\b= and !\b!=\b=. When it is used, the string to the | |
385 | right of the operator is considered a POSIX extended regular ex- | |
386 | pression and matched accordingly (using the POSIX _\br_\be_\bg_\bc_\bo_\bm_\bp and | |
387 | _\br_\be_\bg_\be_\bx_\be_\bc interfaces usually described in _\br_\be_\bg_\be_\bx(3)). The return | |
d233b485 CR |
388 | value is 0 if the string matches the pattern, and 1 otherwise. |
389 | If the regular expression is syntactically incorrect, the condi- | |
390 | tional expression's return value is 2. If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh shell | |
391 | option is enabled, the match is performed without regard to the | |
392 | case of alphabetic characters. Any part of the pattern may be | |
393 | quoted to force the quoted portion to be matched as a string. | |
394 | Bracket expressions in regular expressions must be treated care- | |
712f80b0 CR |
395 | fully, since normal quoting characters lose their meanings be- |
396 | tween brackets. If the pattern is stored in a shell variable, | |
d233b485 | 397 | quoting the variable expansion forces the entire pattern to be |
712f80b0 CR |
398 | matched as a string. |
399 | ||
400 | The pattern will match if it matches any part of the string. | |
401 | Anchor the pattern using the ^\b^ and $\b$ regular expression opera- | |
402 | tors to force it to match the entire string. The array variable | |
403 | B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH records which parts of the string matched the pat- | |
404 | tern. The element of B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH with index 0 contains the | |
405 | portion of the string matching the entire regular expression. | |
406 | Substrings matched by parenthesized subexpressions within the | |
407 | regular expression are saved in the remaining B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH in- | |
408 | dices. The element of B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH with index _\bn is the portion | |
d233b485 CR |
409 | of the string matching the _\bnth parenthesized subexpression. |
410 | ||
411 | Expressions may be combined using the following operators, | |
17345e5a JA |
412 | listed in decreasing order of precedence: |
413 | ||
414 | (\b( _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn )\b) | |
d233b485 | 415 | Returns the value of _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn. This may be used to |
17345e5a JA |
416 | override the normal precedence of operators. |
417 | !\b! _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn | |
418 | True if _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn is false. | |
419 | _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b1 &\b&&\b& _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b2 | |
420 | 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. | |
421 | _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b1 |\b||\b| _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b2 | |
422 | 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. | |
423 | ||
424 | The &\b&&\b& and |\b||\b| operators do not evaluate _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b2 if the value | |
d233b485 | 425 | of _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn_\b1 is sufficient to determine the return value of |
17345e5a JA |
426 | the entire conditional expression. |
427 | ||
0001803f | 428 | 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 |
429 | The list of words following i\bin\bn is expanded, generating a list of |
430 | items. The variable _\bn_\ba_\bm_\be is set to each element of this list in | |
d233b485 | 431 | turn, and _\bl_\bi_\bs_\bt is executed each time. If the i\bin\bn _\bw_\bo_\br_\bd is omit- |
712f80b0 CR |
432 | ted, the f\bfo\bor\br command executes _\bl_\bi_\bs_\bt once for each positional pa- |
433 | rameter that is set (see P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS below). The return status | |
d233b485 | 434 | is the exit status of the last command that executes. If the |
17345e5a JA |
435 | expansion of the items following i\bin\bn results in an empty list, no |
436 | commands are executed, and the return status is 0. | |
437 | ||
438 | 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 | |
439 | First, the arithmetic expression _\be_\bx_\bp_\br_\b1 is evaluated according to | |
d233b485 CR |
440 | 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 |
441 | arithmetic expression _\be_\bx_\bp_\br_\b2 is then evaluated repeatedly until | |
442 | it evaluates to zero. Each time _\be_\bx_\bp_\br_\b2 evaluates to a non-zero | |
443 | value, _\bl_\bi_\bs_\bt is executed and the arithmetic expression _\be_\bx_\bp_\br_\b3 is | |
444 | evaluated. If any expression is omitted, it behaves as if it | |
17345e5a JA |
445 | evaluates to 1. The return value is the exit status of the last |
446 | command in _\bl_\bi_\bs_\bt that is executed, or false if any of the expres- | |
447 | sions is invalid. | |
448 | ||
449 | 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 | |
450 | The list of words following i\bin\bn is expanded, generating a list of | |
712f80b0 CR |
451 | items. The set of expanded words is printed on the standard er- |
452 | ror, each preceded by a number. If the i\bin\bn _\bw_\bo_\br_\bd is omitted, the | |
453 | positional parameters are printed (see P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS below). The | |
454 | P\bPS\bS3\b3 prompt is then displayed and a line read from the standard | |
455 | input. If the line consists of a number corresponding to one of | |
456 | the displayed words, then the value of _\bn_\ba_\bm_\be is set to that word. | |
457 | If the line is empty, the words and prompt are displayed again. | |
458 | If EOF is read, the command completes. Any other value read | |
459 | causes _\bn_\ba_\bm_\be to be set to null. The line read is saved in the | |
460 | variable R\bRE\bEP\bPL\bLY\bY. The _\bl_\bi_\bs_\bt is executed after each selection until | |
461 | a b\bbr\bre\bea\bak\bk command is executed. The exit status of s\bse\bel\ble\bec\bct\bt is the | |
462 | exit status of the last command executed in _\bl_\bi_\bs_\bt, or zero if no | |
463 | commands were executed. | |
17345e5a JA |
464 | |
465 | 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 | |
466 | A c\bca\bas\bse\be command first expands _\bw_\bo_\br_\bd, and tries to match it against | |
d233b485 CR |
467 | each _\bp_\ba_\bt_\bt_\be_\br_\bn in turn, using the matching rules described under |
468 | 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- | |
469 | sion, parameter and variable expansion, arithmetic expansion, | |
470 | command substitution, process substitution and quote removal. | |
471 | Each _\bp_\ba_\bt_\bt_\be_\br_\bn examined is expanded using tilde expansion, parame- | |
472 | ter and variable expansion, arithmetic expansion, command sub- | |
473 | stitution, and process substitution. If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh shell | |
474 | option is enabled, the match is performed without regard to the | |
475 | case of alphabetic characters. When a match is found, the cor- | |
476 | responding _\bl_\bi_\bs_\bt is executed. If the ;\b;;\b; operator is used, no | |
477 | subsequent matches are attempted after the first pattern match. | |
478 | Using ;\b;&\b& in place of ;\b;;\b; causes execution to continue with the | |
479 | _\bl_\bi_\bs_\bt associated with the next set of patterns. Using ;\b;;\b;&\b& in | |
480 | place of ;\b;;\b; causes the shell to test the next pattern list in | |
481 | the statement, if any, and execute any associated _\bl_\bi_\bs_\bt on a suc- | |
712f80b0 CR |
482 | cessful match, continuing the case statement execution as if the |
483 | pattern list had not matched. The exit status is zero if no | |
484 | pattern matches. Otherwise, it is the exit status of the last | |
485 | command executed in _\bl_\bi_\bs_\bt. | |
17345e5a | 486 | |
ac50fbac | 487 | 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 |
712f80b0 CR |
488 | The i\bif\bf _\bl_\bi_\bs_\bt is executed. If its exit status is zero, the t\bth\bhe\ben\bn |
489 | _\bl_\bi_\bs_\bt is executed. Otherwise, each e\bel\bli\bif\bf _\bl_\bi_\bs_\bt is executed in | |
490 | turn, and if its exit status is zero, the corresponding t\bth\bhe\ben\bn | |
17345e5a | 491 | _\bl_\bi_\bs_\bt is executed and the command completes. Otherwise, the e\bel\bls\bse\be |
712f80b0 | 492 | _\bl_\bi_\bs_\bt is executed, if present. The exit status is the exit sta- |
17345e5a JA |
493 | tus of the last command executed, or zero if no condition tested |
494 | true. | |
495 | ||
495aee44 CR |
496 | 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 |
497 | 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 | |
712f80b0 | 498 | The w\bwh\bhi\bil\ble\be command continuously executes the list _\bl_\bi_\bs_\bt_\b-_\b2 as long |
495aee44 | 499 | as the last command in the list _\bl_\bi_\bs_\bt_\b-_\b1 returns an exit status of |
712f80b0 CR |
500 | zero. The u\bun\bnt\bti\bil\bl command is identical to the w\bwh\bhi\bil\ble\be command, ex- |
501 | cept that the test is negated: _\bl_\bi_\bs_\bt_\b-_\b2 is executed as long as the | |
502 | last command in _\bl_\bi_\bs_\bt_\b-_\b1 returns a non-zero exit status. The exit | |
503 | status of the w\bwh\bhi\bil\ble\be and u\bun\bnt\bti\bil\bl commands is the exit status of the | |
504 | last command executed in _\bl_\bi_\bs_\bt_\b-_\b2, or zero if none was executed. | |
17345e5a JA |
505 | |
506 | C\bCo\bop\bpr\bro\boc\bce\bes\bss\bse\bes\bs | |
507 | 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 | |
d233b485 CR |
508 | coprocess is executed asynchronously in a subshell, as if the command |
509 | had been terminated with the &\b& control operator, with a two-way pipe | |
17345e5a JA |
510 | established between the executing shell and the coprocess. |
511 | ||
512 | The format for a coprocess is: | |
513 | ||
514 | 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] | |
515 | ||
712f80b0 CR |
516 | This creates a coprocess named _\bN_\bA_\bM_\bE. If _\bN_\bA_\bM_\bE is not supplied, the de- |
517 | fault name is C\bCO\bOP\bPR\bRO\bOC\bC. _\bN_\bA_\bM_\bE must not be supplied if _\bc_\bo_\bm_\bm_\ba_\bn_\bd is a _\bs_\bi_\bm_\bp_\bl_\be | |
518 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd (see above); otherwise, it is interpreted as the first word of | |
519 | the simple command. When the coprocess is executed, the shell creates | |
520 | an array variable (see A\bAr\brr\bra\bay\bys\bs below) named _\bN_\bA_\bM_\bE in the context of the | |
521 | executing shell. The standard output of _\bc_\bo_\bm_\bm_\ba_\bn_\bd is connected via a | |
522 | pipe to a file descriptor in the executing shell, and that file de- | |
523 | scriptor is assigned to _\bN_\bA_\bM_\bE[0]. The standard input of _\bc_\bo_\bm_\bm_\ba_\bn_\bd is con- | |
524 | nected via a pipe to a file descriptor in the executing shell, and that | |
525 | file descriptor is assigned to _\bN_\bA_\bM_\bE[1]. This pipe is established be- | |
526 | fore any redirections specified by the command (see R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN below). | |
527 | The file descriptors can be utilized as arguments to shell commands and | |
528 | redirections using standard word expansions. Other than those created | |
529 | to execute command and process substitutions, the file descriptors are | |
530 | not available in subshells. The process ID of the shell spawned to ex- | |
531 | ecute the coprocess is available as the value of the variable _\bN_\bA_\bM_\bE_PID. | |
532 | The w\bwa\bai\bit\bt builtin command may be used to wait for the coprocess to ter- | |
533 | minate. | |
ac50fbac CR |
534 | |
535 | Since the coprocess is created as an asynchronous command, the c\bco\bop\bpr\bro\boc\bc | |
536 | command always returns success. The return status of a coprocess is | |
537 | the exit status of _\bc_\bo_\bm_\bm_\ba_\bn_\bd. | |
17345e5a JA |
538 | |
539 | 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 |
540 | A shell function is an object that is called like a simple command and |
541 | executes a compound command with a new set of positional parameters. | |
17345e5a JA |
542 | Shell functions are declared as follows: |
543 | ||
712f80b0 CR |
544 | _\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] |
545 | 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] | |
546 | This defines a function named _\bf_\bn_\ba_\bm_\be. The reserved word f\bfu\bun\bnc\bct\bti\bio\bon\bn | |
495aee44 CR |
547 | is optional. If the f\bfu\bun\bnc\bct\bti\bio\bon\bn reserved word is supplied, the |
548 | parentheses are optional. The _\bb_\bo_\bd_\by of the function is the com- | |
549 | 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). | |
550 | That command is usually a _\bl_\bi_\bs_\bt of commands between { and }, but | |
a0c0a00f CR |
551 | 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, with |
552 | one exception: If the f\bfu\bun\bnc\bct\bti\bio\bon\bn reserved word is used, but the | |
553 | parentheses are not supplied, the braces are required. _\bc_\bo_\bm_\b- | |
712f80b0 CR |
554 | _\bp_\bo_\bu_\bn_\bd_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd is executed whenever _\bf_\bn_\ba_\bm_\be is specified as the |
555 | name of a simple command. When in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, _\bf_\bn_\ba_\bm_\be must be a | |
556 | valid shell _\bn_\ba_\bm_\be and may not be the name of one of the POSIX | |
557 | _\bs_\bp_\be_\bc_\bi_\ba_\bl _\bb_\bu_\bi_\bl_\bt_\bi_\bn_\bs. In default mode, a function name can be any | |
558 | unquoted shell word that does not contain $\b$. Any redirections | |
ac50fbac CR |
559 | (see R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN below) specified when a function is defined are |
560 | performed when the function is executed. The exit status of a | |
561 | function definition is zero unless a syntax error occurs or a | |
562 | readonly function with the same name already exists. When exe- | |
563 | cuted, the exit status of a function is the exit status of the | |
564 | last command executed in the body. (See F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS below.) | |
17345e5a JA |
565 | |
566 | C\bCO\bOM\bMM\bME\bEN\bNT\bTS\bS | |
567 | In a non-interactive shell, or an interactive shell in which the i\bin\bnt\bte\ber\br-\b- | |
ac50fbac CR |
568 | 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 |
569 | 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 | |
570 | all remaining characters on that line to be ignored. An interactive | |
571 | 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 |
572 | 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- |
573 | tive shells. | |
574 | ||
575 | Q\bQU\bUO\bOT\bTI\bIN\bNG\bG | |
ac50fbac CR |
576 | _\bQ_\bu_\bo_\bt_\bi_\bn_\bg is used to remove the special meaning of certain characters or |
577 | words to the shell. Quoting can be used to disable special treatment | |
17345e5a JA |
578 | for special characters, to prevent reserved words from being recognized |
579 | as such, and to prevent parameter expansion. | |
580 | ||
ac50fbac | 581 | 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 |
582 | meaning to the shell and must be quoted if it is to represent itself. |
583 | ||
ac50fbac | 584 | When the command history expansion facilities are being used (see H\bHI\bIS\bS-\b- |
17345e5a JA |
585 | 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 |
586 | be quoted to prevent history expansion. | |
587 | ||
ac50fbac | 588 | There are three quoting mechanisms: the _\be_\bs_\bc_\ba_\bp_\be _\bc_\bh_\ba_\br_\ba_\bc_\bt_\be_\br, single |
17345e5a JA |
589 | quotes, and double quotes. |
590 | ||
ac50fbac | 591 | 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 | 592 | literal value of the next character that follows, with the exception of |
712f80b0 CR |
593 | <newline>. If a \\b\<newline> pair appears, and the backslash is not it- |
594 | self quoted, the \\b\<newline> is treated as a line continuation (that is, | |
595 | it is removed from the input stream and effectively ignored). | |
17345e5a | 596 | |
ac50fbac | 597 | Enclosing characters in single quotes preserves the literal value of |
17345e5a JA |
598 | each character within the quotes. A single quote may not occur between |
599 | single quotes, even when preceded by a backslash. | |
600 | ||
ac50fbac CR |
601 | Enclosing characters in double quotes preserves the literal value of |
602 | all characters within the quotes, with the exception of $\b$, `\b`, \\b\, and, | |
a0c0a00f CR |
603 | when history expansion is enabled, !\b!. When the shell is in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, |
604 | the !\b! has no special meaning within double quotes, even when history | |
605 | expansion is enabled. The characters $\b$ and `\b` retain their special | |
606 | meaning within double quotes. The backslash retains its special mean- | |
607 | ing only when followed by one of the following characters: $\b$, `\b`, "\b", \\b\, | |
608 | or <\b<n\bne\bew\bwl\bli\bin\bne\be>\b>. A double quote may be quoted within double quotes by | |
609 | preceding it with a backslash. If enabled, history expansion will be | |
610 | performed unless an !\b! appearing in double quotes is escaped using a | |
611 | backslash. The backslash preceding the !\b! is not removed. | |
17345e5a | 612 | |
ac50fbac | 613 | The special parameters *\b* and @\b@ have special meaning when in double |
17345e5a JA |
614 | quotes (see P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS below). |
615 | ||
616 | Words of the form $\b$'_\bs_\bt_\br_\bi_\bn_\bg' are treated specially. The word expands to | |
ac50fbac CR |
617 | _\bs_\bt_\br_\bi_\bn_\bg, with backslash-escaped characters replaced as specified by the |
618 | ANSI C standard. Backslash escape sequences, if present, are decoded | |
17345e5a JA |
619 | as follows: |
620 | \\b\a\ba alert (bell) | |
621 | \\b\b\bb backspace | |
0001803f CR |
622 | \\b\e\be |
623 | \\b\E\bE an escape character | |
17345e5a JA |
624 | \\b\f\bf form feed |
625 | \\b\n\bn new line | |
626 | \\b\r\br carriage return | |
627 | \\b\t\bt horizontal tab | |
628 | \\b\v\bv vertical tab | |
629 | \\b\\\b\ backslash | |
630 | \\b\'\b' single quote | |
0001803f | 631 | \\b\"\b" double quote |
a0c0a00f | 632 | \\b\?\b? question mark |
ac50fbac | 633 | \\b\_\bn_\bn_\bn the eight-bit character whose value is the octal value |
d233b485 | 634 | _\bn_\bn_\bn (one to three octal digits) |
ac50fbac | 635 | \\b\x\bx_\bH_\bH the eight-bit character whose value is the hexadecimal |
17345e5a | 636 | value _\bH_\bH (one or two hex digits) |
ac50fbac | 637 | \\b\u\bu_\bH_\bH_\bH_\bH the Unicode (ISO/IEC 10646) character whose value is the |
495aee44 CR |
638 | hexadecimal value _\bH_\bH_\bH_\bH (one to four hex digits) |
639 | \\b\U\bU_\bH_\bH_\bH_\bH_\bH_\bH_\bH_\bH | |
ac50fbac | 640 | the Unicode (ISO/IEC 10646) character whose value is the |
495aee44 | 641 | hexadecimal value _\bH_\bH_\bH_\bH_\bH_\bH_\bH_\bH (one to eight hex digits) |
17345e5a JA |
642 | \\b\c\bc_\bx a control-_\bx character |
643 | ||
ac50fbac | 644 | The expanded result is single-quoted, as if the dollar sign had not |
17345e5a JA |
645 | been present. |
646 | ||
0001803f | 647 | A double-quoted string preceded by a dollar sign ($\b$"_\bs_\bt_\br_\bi_\bn_\bg") will cause |
712f80b0 CR |
648 | the string to be translated according to the current locale. The _\bg_\be_\bt_\b- |
649 | _\bt_\be_\bx_\bt infrastructure performs the message catalog lookup and transla- | |
650 | tion, using the L\bLC\bC_\b_M\bME\bES\bSS\bSA\bAG\bGE\bES\bS and T\bTE\bEX\bXT\bTD\bDO\bOM\bMA\bAI\bIN\bN shell variables. If the | |
651 | current locale is C\bC or P\bPO\bOS\bSI\bIX\bX, or if there are no translations avail- | |
652 | able, the dollar sign is ignored. If the string is translated and re- | |
653 | placed, the replacement is double-quoted. | |
17345e5a JA |
654 | |
655 | P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS | |
712f80b0 | 656 | 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 | 657 | 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- |
712f80b0 CR |
658 | 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 |
659 | _\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 | 660 | 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 |
661 | |
662 | A parameter is set if it has been assigned a value. The null string is | |
712f80b0 | 663 | a valid value. Once a variable is set, it may be unset only by using |
17345e5a JA |
664 | 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). |
665 | ||
666 | A _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be may be assigned to by a statement of the form | |
667 | ||
668 | _\bn_\ba_\bm_\be=[_\bv_\ba_\bl_\bu_\be] | |
669 | ||
712f80b0 CR |
670 | If _\bv_\ba_\bl_\bu_\be is not given, the variable is assigned the null string. All |
671 | _\bv_\ba_\bl_\bu_\be_\bs undergo tilde expansion, parameter and variable expansion, com- | |
672 | mand substitution, arithmetic expansion, and quote removal (see E\bEX\bXP\bPA\bAN\bN-\b- | |
17345e5a JA |
673 | 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 |
674 | is evaluated as an arithmetic expression even if the $((...)) expansion | |
712f80b0 CR |
675 | 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 is not |
676 | performed, with the exception of "\b"$\b$@\b@"\b" as explained below under S\bSp\bpe\bec\bci\bia\bal\bl | |
677 | P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs. Pathname expansion is not performed. Assignment state- | |
678 | ments may also appear 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\bx-\b- | |
679 | p\bpo\bor\brt\bt, r\bre\bea\bad\bdo\bon\bnl\bly\by, and l\blo\boc\bca\bal\bl builtin commands (_\bd_\be_\bc_\bl_\ba_\br_\ba_\bt_\bi_\bo_\bn commands). | |
a0c0a00f | 680 | When in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, these builtins may appear in a command after one or |
712f80b0 | 681 | more instances of the c\bco\bom\bmm\bma\ban\bnd\bd builtin and retain these assignment |
a0c0a00f | 682 | statement properties. |
ac50fbac | 683 | |
712f80b0 | 684 | In the context where an assignment statement is assigning a value to a |
17345e5a | 685 | shell variable or array index, the += operator can be used to append to |
712f80b0 CR |
686 | or add to the variable's previous value. This includes arguments to |
687 | builtin commands such as d\bde\bec\bcl\bla\bar\bre\be that accept assignment statements | |
a0c0a00f | 688 | (_\bd_\be_\bc_\bl_\ba_\br_\ba_\bt_\bi_\bo_\bn commands). When += is applied to a variable for which the |
712f80b0 CR |
689 | _\bi_\bn_\bt_\be_\bg_\be_\br attribute has been set, _\bv_\ba_\bl_\bu_\be is evaluated as an arithmetic ex- |
690 | pression and added to the variable's current value, which is also eval- | |
691 | uated. When += is applied to an array variable using compound assign- | |
692 | ment (see A\bAr\brr\bra\bay\bys\bs below), the variable's value is not unset (as it is | |
693 | when using =), and new values are appended to the array beginning at | |
694 | one greater than the array's maximum index (for indexed arrays) or | |
695 | added as additional key-value pairs in an associative array. When ap- | |
696 | plied to a string-valued variable, _\bv_\ba_\bl_\bu_\be is expanded and appended to | |
a0c0a00f | 697 | the variable's value. |
17345e5a | 698 | |
ac50fbac | 699 | A variable can be assigned the _\bn_\ba_\bm_\be_\br_\be_\bf attribute using the -\b-n\bn option to |
712f80b0 CR |
700 | 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 |
701 | and l\blo\boc\bca\bal\bl below) to create a _\bn_\ba_\bm_\be_\br_\be_\bf, or a reference to another vari- | |
702 | able. This allows variables to be manipulated indirectly. Whenever | |
703 | the nameref variable is referenced, assigned to, unset, or has its at- | |
704 | tributes modified (other than using or changing the _\bn_\ba_\bm_\be_\br_\be_\bf attribute | |
705 | itself), the operation is actually performed on the variable specified | |
706 | by the nameref variable's value. A nameref is commonly used within | |
a0c0a00f | 707 | shell functions to refer to a variable whose name is passed as an argu- |
712f80b0 | 708 | ment to the function. For instance, if a variable name is passed to a |
a0c0a00f | 709 | shell function as its first argument, running |
ac50fbac | 710 | declare -n ref=$1 |
712f80b0 | 711 | inside the function creates a nameref variable r\bre\bef\bf whose value is the |
ac50fbac | 712 | variable name passed as the first argument. References and assignments |
712f80b0 CR |
713 | to r\bre\bef\bf, and changes to its attributes, are treated as references, as- |
714 | signments, and attribute modifications to the variable whose name was | |
715 | passed as $\b$1\b1. If the control variable in a f\bfo\bor\br loop has the nameref | |
716 | attribute, the list of words can be a list of shell variables, and a | |
717 | name reference will be established for each word in the list, in turn, | |
a0c0a00f | 718 | when the loop is executed. Array variables cannot be given the n\bna\bam\bme\ber\bre\bef\bf |
712f80b0 CR |
719 | attribute. However, nameref variables can reference array variables |
720 | and subscripted array variables. Namerefs can be unset using the -\b-n\bn | |
721 | option to the u\bun\bns\bse\bet\bt builtin. Otherwise, if u\bun\bns\bse\bet\bt is executed with the | |
722 | name of a nameref variable as an argument, the variable referenced by | |
ac50fbac CR |
723 | the nameref variable will be unset. |
724 | ||
17345e5a | 725 | P\bPo\bos\bsi\bit\bti\bio\bon\bna\bal\bl P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs |
712f80b0 | 726 | 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 | 727 | other than the single digit 0. Positional parameters are assigned from |
712f80b0 CR |
728 | the shell's arguments when it is invoked, and may be reassigned using |
729 | the s\bse\bet\bt builtin command. Positional parameters may not be assigned to | |
730 | with assignment statements. The positional parameters are temporarily | |
17345e5a JA |
731 | replaced when a shell function is executed (see F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS below). |
732 | ||
712f80b0 | 733 | When a positional parameter consisting of more than a single digit is |
17345e5a JA |
734 | expanded, it must be enclosed in braces (see E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN below). |
735 | ||
736 | S\bSp\bpe\bec\bci\bia\bal\bl P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs | |
712f80b0 | 737 | The shell treats several parameters specially. These parameters may |
17345e5a | 738 | only be referenced; assignment to them is not allowed. |
712f80b0 CR |
739 | *\b* Expands to the positional parameters, starting from one. When |
740 | the expansion is not within double quotes, each positional pa- | |
741 | rameter expands to a separate word. In contexts where it is | |
ac50fbac | 742 | performed, those words are subject to further word splitting and |
712f80b0 CR |
743 | pathname expansion. When the expansion occurs within double |
744 | quotes, it expands to a single word with the value of each pa- | |
745 | rameter separated by the first character of the I\bIF\bFS\bS special | |
746 | variable. That is, "$\b$*\b*" is equivalent to "$\b$1\b1_\bc$\b$2\b2_\bc.\b..\b..\b.", where _\bc | |
ac50fbac | 747 | is the first character of the value of the I\bIF\bFS\bS variable. If I\bIF\bFS\bS |
712f80b0 | 748 | is unset, the parameters are separated by spaces. If I\bIF\bFS\bS is |
a0c0a00f | 749 | null, the parameters are joined without intervening separators. |
712f80b0 CR |
750 | @\b@ Expands to the positional parameters, starting from one. In |
751 | contexts where word splitting is performed, this expands each | |
752 | positional parameter to a separate word; if not within double | |
753 | quotes, these words are subject to word splitting. In contexts | |
754 | where word splitting is not performed, this expands to a single | |
755 | word with each positional parameter separated by a space. When | |
756 | the expansion occurs within double quotes, each parameter ex- | |
757 | pands to a separate word. That is, "$\b$@\b@" is equivalent to "$\b$1\b1" | |
758 | "$\b$2\b2" ... If the double-quoted expansion occurs within a word, | |
759 | the expansion of the first parameter is joined with the begin- | |
760 | ning part of the original word, and the expansion of the last | |
761 | parameter is joined with the last part of the original word. | |
762 | When there are no positional parameters, "$\b$@\b@" and $\b$@\b@ expand to | |
17345e5a JA |
763 | nothing (i.e., they are removed). |
764 | #\b# Expands to the number of positional parameters in decimal. | |
712f80b0 | 765 | ?\b? Expands to the exit status of the most recently executed fore- |
17345e5a | 766 | ground pipeline. |
712f80b0 CR |
767 | -\b- Expands to the current option flags as specified upon invoca- |
768 | tion, by the s\bse\bet\bt builtin command, or those set by the shell it- | |
769 | self (such as the -\b-i\bi option). | |
770 | $\b$ Expands to the process ID of the shell. In a () subshell, it | |
771 | expands to the process ID of the current shell, not the sub- | |
17345e5a | 772 | shell. |
712f80b0 CR |
773 | !\b! Expands to the process ID of the job most recently placed into |
774 | the background, whether executed as an asynchronous command or | |
ac50fbac | 775 | using the b\bbg\bg builtin (see J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL below). |
712f80b0 | 776 | 0\b0 Expands to the name of the shell or shell script. This is set |
17345e5a | 777 | at shell initialization. If b\bba\bas\bsh\bh is invoked with a file of com- |
712f80b0 CR |
778 | mands, $\b$0\b0 is set to the name of that file. If b\bba\bas\bsh\bh is started |
779 | with the -\b-c\bc option, then $\b$0\b0 is set to the first argument after | |
780 | the string to be executed, if one is present. Otherwise, it is | |
781 | set to the filename used to invoke b\bba\bas\bsh\bh, as given by argument | |
17345e5a | 782 | zero. |
17345e5a JA |
783 | |
784 | S\bSh\bhe\bel\bll\bl V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs | |
785 | The following variables are set by the shell: | |
786 | ||
712f80b0 CR |
787 | _\b_ At shell startup, set to the pathname used to invoke the shell |
788 | or shell script being executed as passed in the environment or | |
789 | argument list. Subsequently, expands to the last argument to | |
790 | the previous simple command executed in the foreground, after | |
791 | expansion. Also set to the full pathname used to invoke each | |
792 | command executed and placed in the environment exported to that | |
793 | command. When checking mail, this parameter holds the name of | |
794 | the mail file currently being checked. | |
795 | B\bBA\bAS\bSH\bH Expands to the full filename used to invoke this instance of | |
17345e5a | 796 | b\bba\bas\bsh\bh. |
0001803f | 797 | B\bBA\bAS\bSH\bHO\bOP\bPT\bTS\bS |
712f80b0 CR |
798 | A colon-separated list of enabled shell options. Each word in |
799 | the list is a valid argument for the -\b-s\bs option to the s\bsh\bho\bop\bpt\bt | |
0001803f | 800 | 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 |
712f80b0 CR |
801 | 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 |
802 | this variable is in the environment when b\bba\bas\bsh\bh starts up, each | |
803 | shell option in the list will be enabled before reading any | |
0001803f | 804 | startup files. This variable is read-only. |
17345e5a | 805 | B\bBA\bAS\bSH\bHP\bPI\bID\bD |
712f80b0 CR |
806 | Expands to the process ID of the current b\bba\bas\bsh\bh process. This |
807 | differs from $\b$$\b$ under certain circumstances, such as subshells | |
808 | that do not require b\bba\bas\bsh\bh to be re-initialized. Assignments to | |
809 | 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 | 810 | cial properties, even if it is subsequently reset. |
17345e5a | 811 | B\bBA\bAS\bSH\bH_\b_A\bAL\bLI\bIA\bAS\bSE\bES\bS |
712f80b0 CR |
812 | An associative array variable whose members correspond to the |
813 | internal list of aliases as maintained by the a\bal\bli\bia\bas\bs builtin. | |
814 | Elements added to this array appear in the alias list; however, | |
815 | unsetting array elements currently does not cause aliases to be | |
a0c0a00f CR |
816 | removed from the alias list. If B\bBA\bAS\bSH\bH_\b_A\bAL\bLI\bIA\bAS\bSE\bES\bS is unset, it loses |
817 | its special properties, even if it is subsequently reset. | |
17345e5a | 818 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGC\bC |
712f80b0 | 819 | An array variable whose values are the number of parameters in |
17345e5a | 820 | each frame of the current b\bba\bas\bsh\bh execution call stack. The number |
712f80b0 CR |
821 | of parameters to the current subroutine (shell function or |
822 | script executed with .\b. or s\bso\bou\bur\brc\bce\be) is at the top of the stack. | |
823 | When a subroutine is executed, the number of parameters passed | |
17345e5a | 824 | 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 |
712f80b0 CR |
825 | extended debugging mode (see the description of the e\bex\bxt\btd\bde\beb\bbu\bug\bg op- |
826 | tion to the s\bsh\bho\bop\bpt\bt builtin below). Setting e\bex\bxt\btd\bde\beb\bbu\bug\bg after the | |
d233b485 | 827 | shell has started to execute a script, or referencing this vari- |
712f80b0 | 828 | able when e\bex\bxt\btd\bde\beb\bbu\bug\bg is not set, may result in inconsistent val- |
d233b485 | 829 | ues. |
17345e5a | 830 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV |
712f80b0 | 831 | An array variable containing all of the parameters in the cur- |
17345e5a | 832 | rent b\bba\bas\bsh\bh execution call stack. The final parameter of the last |
712f80b0 | 833 | subroutine call is at the top of the stack; the first parameter |
17345e5a | 834 | of the initial call is at the bottom. When a subroutine is exe- |
712f80b0 CR |
835 | cuted, the parameters supplied are pushed onto B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV. The |
836 | shell sets B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV only when in extended debugging mode (see | |
837 | the description of the e\bex\bxt\btd\bde\beb\bbu\bug\bg option to the s\bsh\bho\bop\bpt\bt builtin be- | |
838 | low). Setting e\bex\bxt\btd\bde\beb\bbu\bug\bg after the shell has started to execute a | |
839 | script, or referencing this variable when e\bex\bxt\btd\bde\beb\bbu\bug\bg is not set, | |
d233b485 CR |
840 | may result in inconsistent values. |
841 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV0\b0 | |
712f80b0 | 842 | When referenced, this variable expands to the name of the shell |
d233b485 | 843 | or shell script (identical to $\b$0\b0; see the description of special |
712f80b0 CR |
844 | parameter 0 above). Assignment to B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV0\b0 causes the value |
845 | 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 | 846 | loses its special properties, even if it is subsequently reset. |
17345e5a | 847 | B\bBA\bAS\bSH\bH_\b_C\bCM\bMD\bDS\bS |
712f80b0 CR |
848 | An associative array variable whose members correspond to the |
849 | internal hash table of commands as maintained by the h\bha\bas\bsh\bh | |
17345e5a | 850 | builtin. Elements added to this array appear in the hash table; |
712f80b0 CR |
851 | however, unsetting array elements currently does not cause com- |
852 | mand names to be removed from the hash table. If B\bBA\bAS\bSH\bH_\b_C\bCM\bMD\bDS\bS is | |
853 | unset, it loses its special properties, even if it is subse- | |
a0c0a00f | 854 | quently reset. |
17345e5a | 855 | B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMM\bMA\bAN\bND\bD |
712f80b0 | 856 | The command currently being executed or about to be executed, |
17345e5a | 857 | unless the shell is executing a command as the result of a trap, |
712f80b0 CR |
858 | in which case it is the command executing at the time of the |
859 | trap. If B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMM\bMA\bAN\bND\bD is unset, it loses its special proper- | |
860 | ties, even if it is subsequently reset. | |
17345e5a JA |
861 | B\bBA\bAS\bSH\bH_\b_E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN_\b_S\bST\bTR\bRI\bIN\bNG\bG |
862 | The command argument to the -\b-c\bc invocation option. | |
863 | B\bBA\bAS\bSH\bH_\b_L\bLI\bIN\bNE\bEN\bNO\bO | |
495aee44 CR |
864 | An array variable whose members are the line numbers in source |
865 | files where each corresponding member of F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE was invoked. | |
866 | $\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 | |
867 | ($\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 | |
868 | $\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- | |
869 | tion). Use L\bLI\bIN\bNE\bEN\bNO\bO to obtain the current line number. | |
a0c0a00f CR |
870 | B\bBA\bAS\bSH\bH_\b_L\bLO\bOA\bAD\bDA\bAB\bBL\bLE\bES\bS_\b_P\bPA\bAT\bTH\bH |
871 | A colon-separated list of directories in which the shell looks | |
872 | for dynamically loadable builtins specified by the e\ben\bna\bab\bbl\ble\be com- | |
873 | mand. | |
17345e5a JA |
874 | B\bBA\bAS\bSH\bH_\b_R\bRE\bEM\bMA\bAT\bTC\bCH\bH |
875 | An array variable whose members are assigned by the =\b=~\b~ binary | |
876 | operator to the [\b[[\b[ conditional command. The element with index | |
712f80b0 CR |
877 | 0 is the portion of the string matching the entire regular ex- |
878 | pression. The element with index _\bn is the portion of the string | |
879 | matching the _\bnth parenthesized subexpression. | |
17345e5a | 880 | B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE |
712f80b0 CR |
881 | An array variable whose members are the source filenames where |
882 | the corresponding shell function names in the F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE array | |
883 | variable are defined. The shell function $\b${\b{F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE[\b[_\b$_\bi]\b]}\b} is de- | |
884 | 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 | 885 | $\b${\b{B\bBA\bAS\bSH\bH_\b_S\bSO\bOU\bUR\bRC\bCE\bE[\b[_\b$_\bi_\b+_\b1]\b]}\b}. |
17345e5a | 886 | B\bBA\bAS\bSH\bH_\b_S\bSU\bUB\bBS\bSH\bHE\bEL\bLL\bL |
712f80b0 CR |
887 | Incremented by one within each subshell or subshell environment |
888 | when the shell begins executing in that environment. The ini- | |
889 | 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- | |
890 | cial properties, even if it is subsequently reset. | |
17345e5a JA |
891 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO |
892 | A readonly array variable whose members hold version information | |
ac50fbac | 893 | for this instance of b\bba\bas\bsh\bh. The values assigned to the array |
17345e5a | 894 | members are as follows: |
a0c0a00f CR |
895 | 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). |
896 | 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 |
897 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO[\b[2]\b] The patch level. |
898 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIN\bNF\bFO\bO[\b[3]\b] The build version. | |
899 | 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). | |
900 | 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 | 901 | B\bBA\bAS\bSH\bH_\b_V\bVE\bER\bRS\bSI\bIO\bON\bN |
ac50fbac | 902 | Expands to a string describing the version of this instance of |
17345e5a | 903 | b\bba\bas\bsh\bh. |
17345e5a | 904 | C\bCO\bOM\bMP\bP_\b_C\bCW\bWO\bOR\bRD\bD |
ac50fbac | 905 | 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 | 906 | cursor position. This variable is available only in shell func- |
ac50fbac | 907 | tions invoked by the programmable completion facilities (see |
17345e5a | 908 | 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 |
909 | C\bCO\bOM\bMP\bP_\b_K\bKE\bEY\bY |
910 | The key (or final key of a key sequence) used to invoke the cur- | |
911 | rent completion function. | |
17345e5a | 912 | C\bCO\bOM\bMP\bP_\b_L\bLI\bIN\bNE\bE |
ac50fbac | 913 | The current command line. This variable is available only in |
a0c0a00f CR |
914 | shell functions and external commands invoked by the program- |
915 | 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 | 916 | C\bCO\bOM\bMP\bP_\b_P\bPO\bOI\bIN\bNT\bT |
a0c0a00f CR |
917 | The index of the current cursor position relative to the begin- |
918 | ning of the current command. If the current cursor position is | |
17345e5a | 919 | at the end of the current command, the value of this variable is |
a0c0a00f CR |
920 | equal to $\b${\b{#\b#C\bCO\bOM\bMP\bP_\b_L\bLI\bIN\bNE\bE}\b}. This variable is available only in |
921 | shell functions and external commands invoked by the program- | |
922 | 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 | 923 | C\bCO\bOM\bMP\bP_\b_T\bTY\bYP\bPE\bE |
ac50fbac CR |
924 | Set to an integer value corresponding to the type of completion |
925 | attempted that caused a completion function to be called: _\bT_\bA_\bB, | |
926 | for normal completion, _\b?, for listing completions after succes- | |
927 | sive tabs, _\b!, for listing alternatives on partial word comple- | |
928 | tion, _\b@, to list completions if the word is not unmodified, or | |
929 | _\b%, for menu completion. This variable is available only in | |
a0c0a00f CR |
930 | shell functions and external commands invoked by the program- |
931 | 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 | 932 | C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDB\bBR\bRE\bEA\bAK\bKS\bS |
a0c0a00f CR |
933 | The set of characters that the r\bre\bea\bad\bdl\bli\bin\bne\be library treats as word |
934 | separators when performing word completion. If C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDB\bBR\bRE\bEA\bAK\bKS\bS | |
935 | is unset, it loses its special properties, even if it is subse- | |
17345e5a | 936 | quently reset. |
17345e5a | 937 | C\bCO\bOM\bMP\bP_\b_W\bWO\bOR\bRD\bDS\bS |
a0c0a00f CR |
938 | An array variable (see A\bAr\brr\bra\bay\bys\bs below) consisting of the individ- |
939 | ual words in the current command line. The line is split into | |
712f80b0 CR |
940 | 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- |
941 | scribed above. This variable is available only in shell func- | |
a0c0a00f | 942 | tions invoked by the programmable completion facilities (see |
0001803f | 943 | 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 |
944 | C\bCO\bOP\bPR\bRO\bOC\bC An array variable (see A\bAr\brr\bra\bay\bys\bs below) created to hold the file |
945 | descriptors for output from and input to an unnamed coprocess | |
495aee44 | 946 | (see C\bCo\bop\bpr\bro\boc\bce\bes\bss\bse\bes\bs above). |
17345e5a JA |
947 | D\bDI\bIR\bRS\bST\bTA\bAC\bCK\bK |
948 | An array variable (see A\bAr\brr\bra\bay\bys\bs below) containing the current con- | |
a0c0a00f CR |
949 | tents of the directory stack. Directories appear in the stack |
950 | in the order they are displayed by the d\bdi\bir\brs\bs builtin. Assigning | |
17345e5a | 951 | to members of this array variable may be used to modify directo- |
a0c0a00f | 952 | ries already in the stack, but the p\bpu\bus\bsh\bhd\bd and p\bpo\bop\bpd\bd builtins must |
17345e5a | 953 | be used to add and remove directories. Assignment to this vari- |
712f80b0 CR |
954 | able will not change the current directory. If D\bDI\bIR\bRS\bST\bTA\bAC\bCK\bK is un- |
955 | set, it loses its special properties, even if it is subsequently | |
956 | reset. | |
d233b485 CR |
957 | E\bEP\bPO\bOC\bCH\bHR\bRE\bEA\bAL\bLT\bTI\bIM\bME\bE |
958 | Each time this parameter is referenced, it expands to the number | |
959 | of seconds since the Unix Epoch (see _\bt_\bi_\bm_\be(3)) as a floating | |
960 | point value with micro-second granularity. Assignments to | |
961 | 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 | |
962 | its special properties, even if it is subsequently reset. | |
963 | E\bEP\bPO\bOC\bCH\bHS\bSE\bEC\bCO\bON\bND\bDS\bS | |
964 | Each time this parameter is referenced, it expands to the number | |
965 | of seconds since the Unix Epoch (see _\bt_\bi_\bm_\be(3)). Assignments to | |
966 | 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 | |
967 | its special properties, even if it is subsequently reset. | |
968 | E\bEU\bUI\bID\bD Expands to the effective user ID of the current user, initial- | |
17345e5a | 969 | ized at shell startup. This variable is readonly. |
17345e5a | 970 | F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE |
d233b485 | 971 | An array variable containing the names of all shell functions |
17345e5a JA |
972 | currently in the execution call stack. The element with index 0 |
973 | is the name of any currently-executing shell function. The bot- | |
d233b485 CR |
974 | tom-most element (the one with the highest index) is "main". |
975 | This variable exists only when a shell function is executing. | |
976 | 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, | |
712f80b0 CR |
977 | it loses its special properties, even if it is subsequently re- |
978 | set. | |
495aee44 | 979 | |
d233b485 CR |
980 | 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. |
981 | Each element of F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE has corresponding elements in | |
712f80b0 CR |
982 | 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- |
983 | stance, $\b${\b{F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE[\b[_\b$_\bi]\b]}\b} was called from the file | |
d233b485 | 984 | $\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 |
985 | c\bca\bal\bll\ble\ber\br builtin displays the current call stack using this infor- |
986 | mation. | |
d233b485 | 987 | G\bGR\bRO\bOU\bUP\bPS\bS An array variable containing the list of groups of which the |
a0c0a00f | 988 | current user is a member. Assignments to G\bGR\bRO\bOU\bUP\bPS\bS have no effect. |
d233b485 | 989 | If G\bGR\bRO\bOU\bUP\bPS\bS is unset, it loses its special properties, even if it |
a0c0a00f | 990 | is subsequently reset. |
17345e5a JA |
991 | H\bHI\bIS\bST\bTC\bCM\bMD\bD |
992 | The history number, or index in the history list, of the current | |
712f80b0 CR |
993 | command. Assignments to H\bHI\bIS\bST\bTC\bCM\bMD\bD are ignored. If H\bHI\bIS\bST\bTC\bCM\bMD\bD is un- |
994 | set, it loses its special properties, even if it is subsequently | |
995 | reset. | |
17345e5a JA |
996 | H\bHO\bOS\bST\bTN\bNA\bAM\bME\bE |
997 | Automatically set to the name of the current host. | |
17345e5a | 998 | H\bHO\bOS\bST\bTT\bTY\bYP\bPE\bE |
712f80b0 CR |
999 | Automatically set to a string that uniquely describes the type |
1000 | of machine on which b\bba\bas\bsh\bh is executing. The default is system- | |
17345e5a | 1001 | dependent. |
712f80b0 CR |
1002 | L\bLI\bIN\bNE\bEN\bNO\bO Each time this parameter is referenced, the shell substitutes a |
1003 | decimal number representing the current sequential line number | |
1004 | (starting with 1) within a script or function. When not in a | |
1005 | script or function, the value substituted is not guaranteed to | |
17345e5a JA |
1006 | be meaningful. If L\bLI\bIN\bNE\bEN\bNO\bO is unset, it loses its special proper- |
1007 | ties, even if it is subsequently reset. | |
17345e5a | 1008 | M\bMA\bAC\bCH\bHT\bTY\bYP\bPE\bE |
712f80b0 CR |
1009 | Automatically set to a string that fully describes the system |
1010 | type on which b\bba\bas\bsh\bh is executing, in the standard GNU _\bc_\bp_\bu_\b-_\bc_\bo_\bm_\b- | |
17345e5a | 1011 | _\bp_\ba_\bn_\by_\b-_\bs_\by_\bs_\bt_\be_\bm format. The default is system-dependent. |
495aee44 | 1012 | M\bMA\bAP\bPF\bFI\bIL\bLE\bE |
712f80b0 | 1013 | An array variable (see A\bAr\brr\bra\bay\bys\bs below) created to hold the text |
495aee44 | 1014 | read by the m\bma\bap\bpf\bfi\bil\ble\be builtin when no variable name is supplied. |
17345e5a | 1015 | O\bOL\bLD\bDP\bPW\bWD\bD The previous working directory as set by the c\bcd\bd command. |
712f80b0 | 1016 | 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 | 1017 | 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). |
712f80b0 | 1018 | 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 | 1019 | 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). |
712f80b0 CR |
1020 | O\bOS\bST\bTY\bYP\bPE\bE Automatically set to a string that describes the operating sys- |
1021 | tem on which b\bba\bas\bsh\bh is executing. The default is system-depen- | |
17345e5a | 1022 | dent. |
17345e5a | 1023 | P\bPI\bIP\bPE\bES\bST\bTA\bAT\bTU\bUS\bS |
712f80b0 CR |
1024 | An array variable (see A\bAr\brr\bra\bay\bys\bs below) containing a list of exit |
1025 | status values from the processes in the most-recently-executed | |
17345e5a | 1026 | foreground pipeline (which may contain only a single command). |
712f80b0 | 1027 | P\bPP\bPI\bID\bD The process ID of the shell's parent. This variable is read- |
17345e5a | 1028 | only. |
17345e5a | 1029 | P\bPW\bWD\bD The current working directory as set by the c\bcd\bd command. |
712f80b0 CR |
1030 | R\bRA\bAN\bND\bDO\bOM\bM Each time this parameter is referenced, it expands to a random |
1031 | integer between 0 and 32767. Assigning a value to R\bRA\bAN\bND\bDO\bOM\bM ini- | |
1032 | tializes (seeds) the sequence of random numbers. If R\bRA\bAN\bND\bDO\bOM\bM is | |
1033 | unset, it loses its special properties, even if it is subse- | |
1034 | quently reset. | |
495aee44 CR |
1035 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_L\bLI\bIN\bNE\bE |
1036 | The contents of the r\bre\bea\bad\bdl\bli\bin\bne\be line buffer, for use with "bind -x" | |
1037 | (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). | |
712f80b0 CR |
1038 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_M\bMA\bAR\bRK\bK |
1039 | The position of the mark (saved insertion point) in the r\bre\bea\bad\bdl\bli\bin\bne\be | |
1040 | 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 | |
1041 | below). The characters between the insertion point and the mark | |
1042 | are often called the _\br_\be_\bg_\bi_\bo_\bn. | |
495aee44 CR |
1043 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE_\b_P\bPO\bOI\bIN\bNT\bT |
1044 | The position of the insertion point in the r\bre\bea\bad\bdl\bli\bin\bne\be line buffer, | |
1045 | 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 | 1046 | R\bRE\bEP\bPL\bLY\bY Set to the line of input read by the r\bre\bea\bad\bd builtin command when |
17345e5a | 1047 | no arguments are supplied. |
17345e5a | 1048 | S\bSE\bEC\bCO\bON\bND\bDS\bS |
d233b485 CR |
1049 | Each time this parameter is referenced, the number of seconds |
1050 | since shell invocation is returned. If a value is assigned to | |
1051 | S\bSE\bEC\bCO\bON\bND\bDS\bS, the value returned upon subsequent references is the | |
1052 | number of seconds since the assignment plus the value assigned. | |
712f80b0 CR |
1053 | The number of seconds at shell invocation and the current time |
1054 | is always determined by querying the system clock. If S\bSE\bEC\bCO\bON\bND\bDS\bS | |
1055 | is unset, it loses its special properties, even if it is subse- | |
1056 | quently reset. | |
17345e5a | 1057 | S\bSH\bHE\bEL\bLL\bLO\bOP\bPT\bTS\bS |
d233b485 CR |
1058 | A colon-separated list of enabled shell options. Each word in |
1059 | the list is a valid argument for the -\b-o\bo option to the s\bse\bet\bt | |
17345e5a | 1060 | 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 |
1061 | 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 |
1062 | this variable is in the environment when b\bba\bas\bsh\bh starts up, each | |
1063 | shell option in the list will be enabled before reading any | |
17345e5a | 1064 | startup files. This variable is read-only. |
17345e5a | 1065 | S\bSH\bHL\bLV\bVL\bL Incremented by one each time an instance of b\bba\bas\bsh\bh is started. |
712f80b0 CR |
1066 | S\bSR\bRA\bAN\bND\bDO\bOM\bM |
1067 | This variable expands to a 32-bit pseudo-random number each time | |
1068 | it is referenced. The random number generator is not linear on | |
1069 | systems that support /dev/urandom or _\ba_\br_\bc_\b4_\br_\ba_\bn_\bd_\bo_\bm, so each re- | |
1070 | turned number has no relationship to the numbers preceding it. | |
1071 | The random number generator cannot be seeded, so assignments to | |
1072 | this variable have no effect. If S\bSR\bRA\bAN\bND\bDO\bOM\bM is unset, it loses its | |
1073 | special properties, even if it is subsequently reset. | |
17345e5a JA |
1074 | U\bUI\bID\bD Expands to the user ID of the current user, initialized at shell |
1075 | startup. This variable is readonly. | |
1076 | ||
712f80b0 CR |
1077 | The following variables are used by the shell. In some cases, b\bba\bas\bsh\bh as- |
1078 | signs a default value to a variable; these cases are noted below. | |
17345e5a | 1079 | |
ac50fbac | 1080 | B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT |
d233b485 | 1081 | The value is used to set the shell's compatibility level. See |
712f80b0 CR |
1082 | 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 |
1083 | compatibility levels and their effects. The value may be a dec- | |
1084 | imal number (e.g., 4.2) or an integer (e.g., 42) corresponding | |
1085 | to the desired compatibility level. If B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT is unset or | |
1086 | set to the empty string, the compatibility level is set to the | |
1087 | default for the current version. If B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT is set to a | |
1088 | value that is not one of the valid compatibility levels, the | |
1089 | shell prints an error message and sets the compatibility level | |
1090 | to the default for the current version. The valid values corre- | |
3eb0018e CR |
1091 | spond to the compatibility levels described below under B\bBS\bSH\bHE\bEL\bLL\bL-\b- |
1092 | COMPATIBILITYM\bMO\bOD\bDE\bE. For example, 4.2 and 42 are valid values | |
712f80b0 CR |
1093 | that correspond to the c\bco\bom\bmp\bpa\bat\bt4\b42\b2 s\bsh\bho\bop\bpt\bt option and set the compat- |
1094 | ibility level to 42. The current version is also a valid value. | |
17345e5a | 1095 | B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV |
d233b485 CR |
1096 | If this parameter is set when b\bba\bas\bsh\bh is executing a shell script, |
1097 | its value is interpreted as a filename containing commands to | |
17345e5a | 1098 | 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 |
1099 | subjected to parameter expansion, command substitution, and |
1100 | arithmetic expansion before being interpreted as a filename. | |
ac50fbac | 1101 | P\bPA\bAT\bTH\bH is not used to search for the resultant filename. |
0001803f | 1102 | B\bBA\bAS\bSH\bH_\b_X\bXT\bTR\bRA\bAC\bCE\bEF\bFD\bD |
d233b485 | 1103 | If set to an integer corresponding to a valid file descriptor, |
712f80b0 CR |
1104 | b\bba\bas\bsh\bh will write the trace output generated when _\bs_\be_\bt _\b-_\bx is en- |
1105 | abled to that file descriptor. The file descriptor is closed | |
d233b485 CR |
1106 | when B\bBA\bAS\bSH\bH_\b_X\bXT\bTR\bRA\bAC\bCE\bEF\bFD\bD is unset or assigned a new value. Unsetting |
1107 | B\bBA\bAS\bSH\bH_\b_X\bXT\bTR\bRA\bAC\bCE\bEF\bFD\bD or assigning it the empty string causes the trace | |
1108 | output to be sent to the standard error. Note that setting | |
0001803f CR |
1109 | B\bBA\bAS\bSH\bH_\b_X\bXT\bTR\bRA\bAC\bCE\bEF\bFD\bD to 2 (the standard error file descriptor) and then |
1110 | unsetting it will result in the standard error being closed. | |
d233b485 | 1111 | C\bCD\bDP\bPA\bAT\bTH\bH The search path for the c\bcd\bd command. This is a colon-separated |
712f80b0 CR |
1112 | list of directories in which the shell looks for destination di- |
1113 | rectories specified by the c\bcd\bd command. A sample value is | |
495aee44 | 1114 | ".:~:/usr". |
ac50fbac | 1115 | C\bCH\bHI\bIL\bLD\bD_\b_M\bMA\bAX\bX |
d233b485 CR |
1116 | Set the number of exited child status values for the shell to |
1117 | remember. Bash will not allow this value to be decreased below | |
1118 | a POSIX-mandated minimum, and there is a maximum value (cur- | |
1119 | rently 8192) that this may not exceed. The minimum value is | |
ac50fbac | 1120 | system-dependent. |
17345e5a | 1121 | C\bCO\bOL\bLU\bUM\bMN\bNS\bS |
d233b485 CR |
1122 | Used by the s\bse\bel\ble\bec\bct\bt compound command to determine the terminal |
1123 | width when printing selection lists. Automatically set if the | |
1124 | c\bch\bhe\bec\bck\bkw\bwi\bin\bns\bsi\biz\bze\be option is enabled or in an interactive shell upon | |
495aee44 | 1125 | receipt of a S\bSI\bIG\bGW\bWI\bIN\bNC\bCH\bH. |
17345e5a JA |
1126 | C\bCO\bOM\bMP\bPR\bRE\bEP\bPL\bLY\bY |
1127 | An array variable from which b\bba\bas\bsh\bh reads the possible completions | |
d233b485 | 1128 | generated by a shell function invoked by the programmable com- |
712f80b0 CR |
1129 | 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- |
1130 | ray element contains one possible completion. | |
d233b485 CR |
1131 | E\bEM\bMA\bAC\bCS\bS If b\bba\bas\bsh\bh finds this variable in the environment when the shell |
1132 | starts with value "t", it assumes that the shell is running in | |
495aee44 | 1133 | an Emacs shell buffer and disables line editing. |
d233b485 CR |
1134 | E\bEN\bNV\bV Similar to B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV; used when the shell is invoked in _\bp_\bo_\bs_\bi_\bx |
1135 | _\bm_\bo_\bd_\be. | |
a0c0a00f | 1136 | E\bEX\bXE\bEC\bCI\bIG\bGN\bNO\bOR\bRE\bE |
d233b485 CR |
1137 | 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) |
1138 | defining the list of filenames to be ignored by command search | |
1139 | using P\bPA\bAT\bTH\bH. Files whose full pathnames match one of these pat- | |
1140 | terns are not considered executable files for the purposes of | |
a0c0a00f CR |
1141 | completion and command execution via P\bPA\bAT\bTH\bH lookup. This does not |
1142 | affect the behavior of the [\b[, t\bte\bes\bst\bt, and [\b[[\b[ commands. Full path- | |
d233b485 CR |
1143 | names in the command hash table are not subject to E\bEX\bXE\bEC\bCI\bIG\bGN\bNO\bOR\bRE\bE. |
1144 | Use this variable to ignore shared library files that have the | |
1145 | executable bit set, but are not executable files. The pattern | |
a0c0a00f | 1146 | matching honors the setting of the e\bex\bxt\btg\bgl\blo\bob\bb shell option. |
17345e5a JA |
1147 | F\bFC\bCE\bED\bDI\bIT\bT The default editor for the f\bfc\bc builtin command. |
1148 | F\bFI\bIG\bGN\bNO\bOR\bRE\bE | |
d233b485 | 1149 | A colon-separated list of suffixes to ignore when performing |
17345e5a | 1150 | filename completion (see R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE below). A filename whose suf- |
d233b485 | 1151 | fix matches one of the entries in F\bFI\bIG\bGN\bNO\bOR\bRE\bE is excluded from the |
17345e5a | 1152 | list of matched filenames. A sample value is ".o:~". |
495aee44 | 1153 | F\bFU\bUN\bNC\bCN\bNE\bES\bST\bT |
d233b485 CR |
1154 | If set to a numeric value greater than 0, defines a maximum |
1155 | function nesting level. Function invocations that exceed this | |
495aee44 | 1156 | nesting level will cause the current command to abort. |
17345e5a | 1157 | G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE |
d233b485 CR |
1158 | A colon-separated list of patterns defining the set of file |
1159 | names to be ignored by pathname expansion. If a file name | |
1160 | matched by a pathname expansion pattern also matches one of the | |
1161 | patterns in G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE, it is removed from the list of matches. | |
17345e5a | 1162 | H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL |
d233b485 | 1163 | A colon-separated list of values controlling how commands are |
712f80b0 CR |
1164 | saved on the history list. If the list of values includes _\bi_\bg_\b- |
1165 | _\bn_\bo_\br_\be_\bs_\bp_\ba_\bc_\be, lines which begin with a s\bsp\bpa\bac\bce\be character are not | |
d233b485 | 1166 | saved in the history list. A value of _\bi_\bg_\bn_\bo_\br_\be_\bd_\bu_\bp_\bs causes lines |
17345e5a JA |
1167 | matching the previous history entry to not be saved. A value of |
1168 | _\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 | |
1169 | of _\be_\br_\ba_\bs_\be_\bd_\bu_\bp_\bs causes all previous lines matching the current line | |
d233b485 CR |
1170 | to be removed from the history list before that line is saved. |
1171 | Any value not in the above list is ignored. If H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL is | |
1172 | unset, or does not include a valid value, all lines read by the | |
17345e5a | 1173 | shell parser are saved on the history list, subject to the value |
d233b485 CR |
1174 | of H\bHI\bIS\bST\bTI\bIG\bGN\bNO\bOR\bRE\bE. The second and subsequent lines of a multi-line |
1175 | compound command are not tested, and are added to the history | |
17345e5a JA |
1176 | regardless of the value of H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL. |
1177 | H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE | |
1178 | The name of the file in which command history is saved (see H\bHI\bIS\bS-\b- | |
d233b485 | 1179 | 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 | 1180 | the command history is not saved when a shell exits. |
17345e5a JA |
1181 | H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bES\bSI\bIZ\bZE\bE |
1182 | The maximum number of lines contained in the history file. When | |
d233b485 CR |
1183 | this variable is assigned a value, the history file is trun- |
1184 | cated, if necessary, to contain no more than that number of | |
1185 | lines by removing the oldest entries. The history file is also | |
1186 | truncated to this size after writing it when a shell exits. If | |
1187 | the value is 0, the history file is truncated to zero size. | |
1188 | Non-numeric values and numeric values less than zero inhibit | |
1189 | truncation. The shell sets the default value to the value of | |
ac50fbac | 1190 | H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE after reading any startup files. |
17345e5a | 1191 | H\bHI\bIS\bST\bTI\bIG\bGN\bNO\bOR\bRE\bE |
d233b485 | 1192 | A colon-separated list of patterns used to decide which command |
712f80b0 CR |
1193 | lines should be saved on the history list. Each pattern is an- |
1194 | chored at the beginning of the line and must match the complete | |
1195 | line (no implicit `*\b*' is appended). Each pattern is tested | |
1196 | against the line after the checks specified by H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL are | |
1197 | applied. In addition to the normal shell pattern matching char- | |
1198 | acters, `&\b&' matches the previous history line. `&\b&' may be es- | |
1199 | caped using a backslash; the backslash is removed before at- | |
1200 | tempting a match. The second and subsequent lines of a multi- | |
1201 | line compound command are not tested, and are added to the his- | |
1202 | tory regardless of the value of H\bHI\bIS\bST\bTI\bIG\bGN\bNO\bOR\bRE\bE. The pattern match- | |
1203 | ing honors the setting of the e\bex\bxt\btg\bgl\blo\bob\bb shell option. | |
17345e5a | 1204 | H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE |
d233b485 CR |
1205 | The number of commands to remember in the command history (see |
1206 | H\bHI\bIS\bST\bTO\bOR\bRY\bY below). If the value is 0, commands are not saved in | |
ac50fbac | 1207 | the history list. Numeric values less than zero result in every |
d233b485 CR |
1208 | command being saved on the history list (there is no limit). |
1209 | The shell sets the default value to 500 after reading any | |
ac50fbac | 1210 | startup files. |
17345e5a | 1211 | H\bHI\bIS\bST\bTT\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT |
d233b485 | 1212 | If this variable is set and not null, its value is used as a |
17345e5a | 1213 | format string for _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be(3) to print the time stamp associated |
d233b485 CR |
1214 | with each history entry displayed by the h\bhi\bis\bst\bto\bor\bry\by builtin. If |
1215 | this variable is set, time stamps are written to the history | |
1216 | file so they may be preserved across shell sessions. This uses | |
1217 | the history comment character to distinguish timestamps from | |
17345e5a JA |
1218 | other history lines. |
1219 | H\bHO\bOM\bME\bE The home directory of the current user; the default argument for | |
1220 | the c\bcd\bd builtin command. The value of this variable is also used | |
1221 | when performing tilde expansion. | |
1222 | H\bHO\bOS\bST\bTF\bFI\bIL\bLE\bE | |
d233b485 | 1223 | Contains the name of a file in the same format as _\b/_\be_\bt_\bc_\b/_\bh_\bo_\bs_\bt_\bs |
17345e5a | 1224 | that should be read when the shell needs to complete a hostname. |
d233b485 | 1225 | The list of possible hostname completions may be changed while |
712f80b0 CR |
1226 | the shell is running; the next time hostname completion is at- |
1227 | tempted after the value is changed, b\bba\bas\bsh\bh adds the contents of | |
d233b485 CR |
1228 | the new file to the existing list. If H\bHO\bOS\bST\bTF\bFI\bIL\bLE\bE is set, but has |
1229 | no value, or does not name a readable file, b\bba\bas\bsh\bh attempts to | |
1230 | read _\b/_\be_\bt_\bc_\b/_\bh_\bo_\bs_\bt_\bs to obtain the list of possible hostname comple- | |
0001803f | 1231 | tions. When H\bHO\bOS\bST\bTF\bFI\bIL\bLE\bE is unset, the hostname list is cleared. |
712f80b0 CR |
1232 | 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- |
1233 | ter expansion and to split lines into words with the r\bre\bea\bad\bd | |
17345e5a JA |
1234 | builtin command. The default value is ``<space><tab><new- |
1235 | line>''. | |
1236 | I\bIG\bGN\bNO\bOR\bRE\bEE\bEO\bOF\bF | |
1237 | Controls the action of an interactive shell on receipt of an E\bEO\bOF\bF | |
1238 | character as the sole input. If set, the value is the number of | |
d233b485 CR |
1239 | consecutive E\bEO\bOF\bF characters which must be typed as the first |
1240 | characters on an input line before b\bba\bas\bsh\bh exits. If the variable | |
1241 | exists but does not have a numeric value, or has no value, the | |
1242 | default value is 10. If it does not exist, E\bEO\bOF\bF signifies the | |
17345e5a JA |
1243 | end of input to the shell. |
1244 | I\bIN\bNP\bPU\bUT\bTR\bRC\bC | |
712f80b0 CR |
1245 | The filename for the r\bre\bea\bad\bdl\bli\bin\bne\be startup file, overriding the de- |
1246 | 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 |
1247 | I\bIN\bNS\bSI\bID\bDE\bE_\b_E\bEM\bMA\bAC\bCS\bS |
1248 | If this variable appears in the environment when the shell | |
1249 | starts, b\bba\bas\bsh\bh assumes that it is running inside an Emacs shell | |
1250 | buffer and may disable line editing, depending on the value of | |
1251 | T\bTE\bER\bRM\bM. | |
a0c0a00f | 1252 | L\bLA\bAN\bNG\bG Used to determine the locale category for any category not |
17345e5a | 1253 | specifically selected with a variable starting with L\bLC\bC_\b_. |
a0c0a00f | 1254 | 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 |
1255 | variable specifying a locale category. |
1256 | L\bLC\bC_\b_C\bCO\bOL\bLL\bLA\bAT\bTE\bE | |
a0c0a00f CR |
1257 | This variable determines the collation order used when sorting |
1258 | the results of pathname expansion, and determines the behavior | |
712f80b0 CR |
1259 | of range expressions, equivalence classes, and collating se- |
1260 | quences within pathname expansion and pattern matching. | |
17345e5a | 1261 | L\bLC\bC_\b_C\bCT\bTY\bYP\bPE\bE |
a0c0a00f CR |
1262 | This variable determines the interpretation of characters and |
1263 | the behavior of character classes within pathname expansion and | |
17345e5a JA |
1264 | pattern matching. |
1265 | L\bLC\bC_\b_M\bME\bES\bSS\bSA\bAG\bGE\bES\bS | |
a0c0a00f | 1266 | This variable determines the locale used to translate double- |
17345e5a JA |
1267 | quoted strings preceded by a $\b$. |
1268 | L\bLC\bC_\b_N\bNU\bUM\bME\bER\bRI\bIC\bC | |
a0c0a00f | 1269 | This variable determines the locale category used for number |
17345e5a | 1270 | formatting. |
a0c0a00f CR |
1271 | L\bLC\bC_\b_T\bTI\bIM\bME\bE |
1272 | This variable determines the locale category used for data and | |
1273 | time formatting. | |
495aee44 | 1274 | L\bLI\bIN\bNE\bES\bS Used by the s\bse\bel\ble\bec\bct\bt compound command to determine the column |
ac50fbac CR |
1275 | length for printing selection lists. Automatically set if the |
1276 | c\bch\bhe\bec\bck\bkw\bwi\bin\bns\bsi\biz\bze\be option is enabled or in an interactive shell upon | |
0001803f | 1277 | receipt of a S\bSI\bIG\bGW\bWI\bIN\bNC\bCH\bH. |
ac50fbac | 1278 | M\bMA\bAI\bIL\bL If this parameter is set to a file or directory name and the |
712f80b0 CR |
1279 | M\bMA\bAI\bIL\bLP\bPA\bAT\bTH\bH variable is not set, b\bba\bas\bsh\bh informs the user of the ar- |
1280 | rival of mail in the specified file or Maildir-format directory. | |
17345e5a | 1281 | M\bMA\bAI\bIL\bLC\bCH\bHE\bEC\bCK\bK |
712f80b0 CR |
1282 | Specifies how often (in seconds) b\bba\bas\bsh\bh checks for mail. The de- |
1283 | fault is 60 seconds. When it is time to check for mail, the | |
1284 | shell does so before displaying the primary prompt. If this | |
1285 | variable is unset, or set to a value that is not a number | |
17345e5a JA |
1286 | greater than or equal to zero, the shell disables mail checking. |
1287 | M\bMA\bAI\bIL\bLP\bPA\bAT\bTH\bH | |
ac50fbac CR |
1288 | A colon-separated list of filenames to be checked for mail. The |
1289 | message to be printed when mail arrives in a particular file may | |
712f80b0 CR |
1290 | be specified by separating the filename from the message with a |
1291 | `?'. When used in the text of the message, $\b$_\b_ expands to the | |
ac50fbac | 1292 | name of the current mailfile. Example: |
17345e5a JA |
1293 | M\bMA\bAI\bIL\bLP\bPA\bAT\bTH\bH='/var/mail/bfox?"You have mail":~/shell-mail?"$_ has |
1294 | mail!"' | |
712f80b0 CR |
1295 | B\bBa\bas\bsh\bh can be configured to supply a default value for this vari- |
1296 | able (there is no value by default), but the location of the | |
a0c0a00f CR |
1297 | user mail files that it uses is system dependent (e.g., |
1298 | /var/mail/$\b$U\bUS\bSE\bER\bR). | |
17345e5a | 1299 | O\bOP\bPT\bTE\bER\bRR\bR If set to the value 1, b\bba\bas\bsh\bh displays error messages generated by |
712f80b0 CR |
1300 | 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). |
1301 | O\bOP\bPT\bTE\bER\bRR\bR is initialized to 1 each time the shell is invoked or a | |
17345e5a | 1302 | shell script is executed. |
712f80b0 CR |
1303 | P\bPA\bAT\bTH\bH The search path for commands. It is a colon-separated list of |
1304 | directories in which the shell looks for commands (see C\bCO\bOM\bMM\bMA\bAN\bND\bD | |
1305 | E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN below). A zero-length (null) directory name in the | |
17345e5a | 1306 | value of P\bPA\bAT\bTH\bH indicates the current directory. A null directory |
712f80b0 CR |
1307 | name may appear as two adjacent colons, or as an initial or |
1308 | trailing colon. The default path is system-dependent, and is | |
a0c0a00f | 1309 | set by the administrator who installs b\bba\bas\bsh\bh. A common value is |
712f80b0 CR |
1310 | ``/usr/local/bin:/usr/lo- |
1311 | cal/sbin:/usr/bin:/usr/sbin:/bin:/sbin''. | |
17345e5a | 1312 | P\bPO\bOS\bSI\bIX\bXL\bLY\bY_\b_C\bCO\bOR\bRR\bRE\bEC\bCT\bT |
712f80b0 CR |
1313 | If this variable is in the environment when b\bba\bas\bsh\bh starts, the |
1314 | shell enters _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be before reading the startup files, as if | |
1315 | the -\b--\b-p\bpo\bos\bsi\bix\bx invocation option had been supplied. If it is set | |
1316 | while the shell is running, b\bba\bas\bsh\bh enables _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, as if the | |
1317 | command _\bs_\be_\bt _\b-_\bo _\bp_\bo_\bs_\bi_\bx had been executed. When the shell enters | |
d233b485 | 1318 | _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, it sets this variable if it was not already set. |
3eb0018e CR |
1319 | P\bPR\bRO\bOM\bMP\bPT\bT_\b_C\bCO\bOM\bMM\bMA\bAN\bND\bD |
1320 | If this variable is set, and is an array, the value of each set | |
1321 | element is executed as a command prior to issuing each primary | |
1322 | prompt. If this is set but not an array variable, its value is | |
1323 | used as a command to execute instead. | |
17345e5a | 1324 | P\bPR\bRO\bOM\bMP\bPT\bT_\b_D\bDI\bIR\bRT\bTR\bRI\bIM\bM |
712f80b0 | 1325 | If set to a number greater than zero, the value is used as the |
17345e5a | 1326 | number of trailing directory components to retain when expanding |
712f80b0 | 1327 | the \\b\w\bw and \\b\W\bW prompt string escapes (see P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG below). |
17345e5a | 1328 | Characters removed are replaced with an ellipsis. |
712f80b0 CR |
1329 | P\bPS\bS0\b0 The value of this parameter is expanded (see P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG below) |
1330 | and displayed by interactive shells after reading a command and | |
a0c0a00f | 1331 | before the command is executed. |
712f80b0 CR |
1332 | P\bPS\bS1\b1 The value of this parameter is expanded (see P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG below) |
1333 | and used as the primary prompt string. The default value is | |
17345e5a | 1334 | ``\\b\s\bs-\b-\\b\v\bv\\b\$\b$ ''. |
712f80b0 | 1335 | P\bPS\bS2\b2 The value of this parameter is expanded as with P\bPS\bS1\b1 and used as |
17345e5a JA |
1336 | the secondary prompt string. The default is ``>\b> ''. |
1337 | P\bPS\bS3\b3 The value of this parameter is used as the prompt for the s\bse\bel\ble\bec\bct\bt | |
1338 | command (see S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR above). | |
712f80b0 CR |
1339 | P\bPS\bS4\b4 The value of this parameter is expanded as with P\bPS\bS1\b1 and the |
1340 | value is printed before each command b\bba\bas\bsh\bh displays during an ex- | |
1341 | ecution trace. The first character of the expanded value of P\bPS\bS4\b4 | |
1342 | is replicated multiple times, as necessary, to indicate multiple | |
1343 | levels of indirection. The default is ``+\b+ ''. | |
1344 | S\bSH\bHE\bEL\bLL\bL This variable expands to the full pathname to the shell. If it | |
1345 | is not set when the shell starts, b\bba\bas\bsh\bh assigns to it the full | |
1346 | pathname of the current user's login shell. | |
17345e5a | 1347 | T\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT |
712f80b0 CR |
1348 | The value of this parameter is used as a format string specify- |
1349 | ing how the timing information for pipelines prefixed with the | |
1350 | t\bti\bim\bme\be reserved word should be displayed. The %\b% character intro- | |
1351 | duces an escape sequence that is expanded to a time value or | |
1352 | other information. The escape sequences and their meanings are | |
17345e5a JA |
1353 | as follows; the braces denote optional portions. |
1354 | %\b%%\b% A literal %\b%. | |
1355 | %\b%[\b[_\bp]\b][\b[l\bl]\b]R\bR The elapsed time in seconds. | |
1356 | %\b%[\b[_\bp]\b][\b[l\bl]\b]U\bU The number of CPU seconds spent in user mode. | |
1357 | %\b%[\b[_\bp]\b][\b[l\bl]\b]S\bS The number of CPU seconds spent in system mode. | |
1358 | %\b%P\bP The CPU percentage, computed as (%U + %S) / %R. | |
1359 | ||
712f80b0 | 1360 | The optional _\bp is a digit specifying the _\bp_\br_\be_\bc_\bi_\bs_\bi_\bo_\bn, the number |
17345e5a JA |
1361 | of fractional digits after a decimal point. A value of 0 causes |
1362 | no decimal point or fraction to be output. At most three places | |
712f80b0 CR |
1363 | after the decimal point may be specified; values of _\bp greater |
1364 | than 3 are changed to 3. If _\bp is not specified, the value 3 is | |
17345e5a JA |
1365 | used. |
1366 | ||
712f80b0 CR |
1367 | The optional l\bl specifies a longer format, including minutes, of |
1368 | the form _\bM_\bMm_\bS_\bS._\bF_\bFs. The value of _\bp determines whether or not | |
17345e5a JA |
1369 | the fraction is included. |
1370 | ||
712f80b0 CR |
1371 | If this variable is not set, b\bba\bas\bsh\bh acts as if it had the value |
1372 | $\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 | 1373 | no timing information is displayed. A trailing newline is added |
17345e5a | 1374 | when the format string is displayed. |
712f80b0 CR |
1375 | 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- |
1376 | fault timeout for the r\bre\bea\bad\bd builtin. The s\bse\bel\ble\bec\bct\bt command termi- | |
17345e5a | 1377 | nates if input does not arrive after T\bTM\bMO\bOU\bUT\bT seconds when input is |
712f80b0 | 1378 | coming from a terminal. In an interactive shell, the value is |
ac50fbac CR |
1379 | interpreted as the number of seconds to wait for a line of input |
1380 | after issuing the primary prompt. B\bBa\bas\bsh\bh terminates after waiting | |
712f80b0 | 1381 | for that number of seconds if a complete line of input does not |
ac50fbac | 1382 | arrive. |
712f80b0 | 1383 | 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 | 1384 | b\bba\bas\bsh\bh creates temporary files for the shell's use. |
17345e5a JA |
1385 | a\bau\but\bto\bo_\b_r\bre\bes\bsu\bum\bme\be |
1386 | This variable controls how the shell interacts with the user and | |
712f80b0 | 1387 | job control. If this variable is set, single word simple com- |
17345e5a JA |
1388 | mands without redirections are treated as candidates for resump- |
1389 | tion of an existing stopped job. There is no ambiguity allowed; | |
712f80b0 CR |
1390 | if there is more than one job beginning with the string typed, |
1391 | the job most recently accessed is selected. The _\bn_\ba_\bm_\be of a | |
1392 | stopped job, in this context, is the command line used to start | |
1393 | it. If set to the value _\be_\bx_\ba_\bc_\bt, the string supplied must match | |
1394 | the name of a stopped job exactly; if set to _\bs_\bu_\bb_\bs_\bt_\br_\bi_\bn_\bg, the | |
1395 | string supplied needs to match a substring of the name of a | |
1396 | stopped job. The _\bs_\bu_\bb_\bs_\bt_\br_\bi_\bn_\bg value provides functionality analo- | |
1397 | gous to the %\b%?\b? job identifier (see J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL below). If set | |
1398 | to any other value, the supplied string must be a prefix of a | |
17345e5a JA |
1399 | stopped job's name; this provides functionality analogous to the |
1400 | %\b%_\bs_\bt_\br_\bi_\bn_\bg job identifier. | |
17345e5a | 1401 | h\bhi\bis\bst\btc\bch\bha\bar\brs\bs |
712f80b0 | 1402 | The two or three characters which control history expansion and |
17345e5a | 1403 | tokenization (see H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN below). The first character |
712f80b0 CR |
1404 | is the _\bh_\bi_\bs_\bt_\bo_\br_\by _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn character, the character which signals |
1405 | the start of a history expansion, normally `!\b!'. The second | |
1406 | 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 | |
1407 | shorthand for re-running the previous command entered, substi- | |
1408 | tuting one string for another in the command. The default is | |
1409 | `^\b^'. The optional third character is the character which indi- | |
1410 | cates that the remainder of the line is a comment when found as | |
1411 | the first character of a word, normally `#\b#'. The history com- | |
17345e5a | 1412 | ment character causes history substitution to be skipped for the |
712f80b0 | 1413 | remaining words on the line. It does not necessarily cause the |
17345e5a JA |
1414 | shell parser to treat the rest of the line as a comment. |
1415 | ||
1416 | A\bAr\brr\bra\bay\bys\bs | |
712f80b0 CR |
1417 | B\bBa\bas\bsh\bh provides one-dimensional indexed and associative array variables. |
1418 | Any variable may be used as an indexed array; the d\bde\bec\bcl\bla\bar\bre\be builtin will | |
1419 | explicitly declare an array. There is no maximum limit on the size of | |
1420 | an array, nor any requirement that members be indexed or assigned con- | |
1421 | tiguously. Indexed arrays are referenced using integers (including | |
a0c0a00f CR |
1422 | arithmetic expressions) and are zero-based; associative arrays are ref- |
1423 | erenced using arbitrary strings. Unless otherwise noted, indexed array | |
1424 | indices must be non-negative integers. | |
17345e5a | 1425 | |
712f80b0 | 1426 | An indexed array is created automatically if any variable is assigned |
17345e5a | 1427 | 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 | 1428 | an arithmetic expression that must evaluate to a number. To explicitly |
712f80b0 CR |
1429 | 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- |
1430 | 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 | 1431 | _\bs_\bc_\br_\bi_\bp_\bt is ignored. |
17345e5a JA |
1432 | |
1433 | Associative arrays are created using d\bde\bec\bcl\bla\bar\bre\be -\b-A\bA _\bn_\ba_\bm_\be. | |
1434 | ||
1435 | Attributes may be specified for an array variable using the d\bde\bec\bcl\bla\bar\bre\be and | |
a0c0a00f | 1436 | r\bre\bea\bad\bdo\bon\bnl\bly\by builtins. Each attribute applies to all members of an array. |
17345e5a | 1437 | |
712f80b0 CR |
1438 | Arrays are assigned to using compound assignments of the form |
1439 | _\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- | |
1440 | _\bs_\bc_\br_\bi_\bp_\bt]=_\bs_\bt_\br_\bi_\bn_\bg. Indexed array assignments do not require anything but | |
1441 | _\bs_\bt_\br_\bi_\bn_\bg. Each _\bv_\ba_\bl_\bu_\be in the list is expanded using all the shell expan- | |
1442 | sions described below under E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN. When assigning to indexed ar- | |
1443 | rays, if the optional brackets and subscript are supplied, that index | |
1444 | is assigned to; otherwise the index of the element assigned is the last | |
1445 | index assigned to by the statement plus one. Indexing starts at zero. | |
1446 | ||
1447 | When assigning to an associative array, the words in a compound assign- | |
1448 | ment may be either assignment statements, for which the subscript is | |
1449 | required, or a list of words that is interpreted as a sequence of al- | |
1450 | 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 | |
1451 | 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). | |
1452 | The first word in the list determines how the remaining words are in- | |
1453 | terpreted; all assignments in a list must be of the same type. When | |
1454 | using key/value pairs, the keys may not be missing or empty; a final | |
1455 | missing value is treated like the empty string. | |
17345e5a | 1456 | |
d233b485 | 1457 | This syntax is also accepted by the d\bde\bec\bcl\bla\bar\bre\be builtin. Individual array |
712f80b0 CR |
1458 | 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- |
1459 | troduced above. When assigning to an indexed array, if _\bn_\ba_\bm_\be is sub- | |
d233b485 CR |
1460 | scripted by a negative number, that number is interpreted as relative |
1461 | to one greater than the maximum index of _\bn_\ba_\bm_\be, so negative indices | |
ac50fbac CR |
1462 | count back from the end of the array, and an index of -1 references the |
1463 | last element. | |
17345e5a | 1464 | |
d233b485 | 1465 | Any element of an array may be referenced using ${_\bn_\ba_\bm_\be[_\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt]}. |
17345e5a | 1466 | The braces are required to avoid conflicts with pathname expansion. If |
d233b485 CR |
1467 | _\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 |
1468 | subscripts differ only when the word appears within double quotes. If | |
17345e5a | 1469 | the word is double-quoted, ${_\bn_\ba_\bm_\be[*]} expands to a single word with the |
d233b485 | 1470 | value of each array member separated by the first character of the I\bIF\bFS\bS |
17345e5a | 1471 | special variable, and ${_\bn_\ba_\bm_\be[@]} expands each element of _\bn_\ba_\bm_\be to a sep- |
d233b485 | 1472 | arate word. When there are no array members, ${_\bn_\ba_\bm_\be[@]} expands to |
712f80b0 CR |
1473 | nothing. If the double-quoted expansion occurs within a word, the ex- |
1474 | pansion of the first parameter is joined with the beginning part of the | |
1475 | original word, and the expansion of the last parameter is joined with | |
1476 | the last part of the original word. This is analogous to the expansion | |
1477 | 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). | |
1478 | ${#_\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 | |
1479 | _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt is *\b* or @\b@, the expansion is the number of elements in the ar- | |
1480 | ray. If the _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt used to reference an element of an indexed array | |
1481 | evaluates to a number less than zero, it is interpreted as relative to | |
1482 | one greater than the maximum index of the array, so negative indices | |
1483 | count back from the end of the array, and an index of -1 references the | |
1484 | last element. | |
a0c0a00f CR |
1485 | |
1486 | Referencing an array variable without a subscript is equivalent to ref- | |
d233b485 | 1487 | erencing the array with a subscript of 0. Any reference to a variable |
a0c0a00f CR |
1488 | using a valid subscript is legal, and b\bba\bas\bsh\bh will create an array if nec- |
1489 | essary. | |
17345e5a | 1490 | |
d233b485 | 1491 | An array variable is considered set if a subscript has been assigned a |
0001803f CR |
1492 | value. The null string is a valid value. |
1493 | ||
d233b485 CR |
1494 | It is possible to obtain the keys (indices) of an array as well as the |
1495 | values. ${!\b!_\bn_\ba_\bm_\be[_\b@]} and ${!\b!_\bn_\ba_\bm_\be[_\b*]} expand to the indices assigned in | |
ac50fbac CR |
1496 | array variable _\bn_\ba_\bm_\be. The treatment when in double quotes is similar to |
1497 | the expansion of the special parameters _\b@ and _\b* within double quotes. | |
1498 | ||
712f80b0 CR |
1499 | 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- |
1500 | stroys the array element at index _\bs_\bu_\bb_\bs_\bc_\br_\bi_\bp_\bt, for both indexed and asso- | |
1501 | ciative arrays. Negative subscripts to indexed arrays are interpreted | |
1502 | as described above. Unsetting the last element of an array variable | |
1503 | does not unset the variable. u\bun\bns\bse\bet\bt _\bn_\ba_\bm_\be, where _\bn_\ba_\bm_\be is an array, or | |
1504 | 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 @\b@, removes the entire | |
1505 | array. | |
d233b485 CR |
1506 | |
1507 | When using a variable name with a subscript as an argument to a com- | |
712f80b0 CR |
1508 | mand, such as with u\bun\bns\bse\bet\bt, without using the word expansion syntax de- |
1509 | scribed above, the argument is subject to pathname expansion. If path- | |
1510 | name expansion is not desired, the argument should be quoted. | |
d233b485 CR |
1511 | |
1512 | 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 | |
712f80b0 CR |
1513 | specify an indexed array and a -\b-A\bA option to specify an associative ar- |
1514 | ray. If both options are supplied, -\b-A\bA takes precedence. The r\bre\bea\bad\bd | |
d233b485 | 1515 | builtin accepts a -\b-a\ba option to assign a list of words read from the |
ac50fbac CR |
1516 | standard input to an array. The s\bse\bet\bt and d\bde\bec\bcl\bla\bar\bre\be builtins display array |
1517 | values in a way that allows them to be reused as assignments. | |
17345e5a JA |
1518 | |
1519 | E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
1520 | Expansion is performed on the command line after it has been split into | |
d233b485 CR |
1521 | words. There are seven kinds of expansion performed: _\bb_\br_\ba_\bc_\be _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn, |
1522 | _\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 |
1523 | _\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. |
1524 | ||
ac50fbac | 1525 | The order of expansions is: brace expansion; tilde expansion, parameter |
d233b485 CR |
1526 | and variable expansion, arithmetic expansion, and command substitution |
1527 | (done in a left-to-right fashion); word splitting; and pathname expan- | |
ac50fbac | 1528 | sion. |
17345e5a JA |
1529 | |
1530 | On systems that can support it, there is an additional expansion avail- | |
d233b485 CR |
1531 | 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 |
1532 | tilde, parameter, variable, and arithmetic expansion and command sub- | |
ac50fbac | 1533 | stitution. |
17345e5a | 1534 | |
d233b485 CR |
1535 | After these expansions are performed, quote characters present in the |
1536 | original word are removed unless they have been quoted themselves | |
a0c0a00f CR |
1537 | (_\bq_\bu_\bo_\bt_\be _\br_\be_\bm_\bo_\bv_\ba_\bl). |
1538 | ||
712f80b0 CR |
1539 | Only brace expansion, word splitting, and pathname expansion can in- |
1540 | crease the number of words of the expansion; other expansions expand a | |
1541 | single word to a single word. The only exceptions to this are the ex- | |
1542 | pansions of "$\b$@\b@" and "$\b${\b{_\bn_\ba_\bm_\be[\b[@\b@]\b]}\b}", and, in most cases, $\b$*\b* and | |
d233b485 | 1543 | $\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 |
1544 | |
1545 | B\bBr\bra\bac\bce\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
1546 | _\bB_\br_\ba_\bc_\be _\be_\bx_\bp_\ba_\bn_\bs_\bi_\bo_\bn is a mechanism by which arbitrary strings may be gener- | |
1547 | 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- | |
1548 | names generated need not exist. Patterns to be brace expanded take the | |
1549 | form of an optional _\bp_\br_\be_\ba_\bm_\bb_\bl_\be, followed by either a series of comma-sep- | |
1550 | arated strings or a sequence expression between a pair of braces, fol- | |
1551 | lowed by an optional _\bp_\bo_\bs_\bt_\bs_\bc_\br_\bi_\bp_\bt. The preamble is prefixed to each | |
1552 | string contained within the braces, and the postscript is then appended | |
1553 | to each resulting string, expanding left to right. | |
1554 | ||
1555 | Brace expansions may be nested. The results of each expanded string | |
1556 | are not sorted; left to right order is preserved. For example, | |
1557 | a{\b{d,c,b}\b}e expands into `ade ace abe'. | |
1558 | ||
1559 | 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 | |
1560 | either integers or single characters, and _\bi_\bn_\bc_\br, an optional increment, | |
1561 | is an integer. When integers are supplied, the expression expands to | |
1562 | each number between _\bx and _\by, inclusive. Supplied integers may be pre- | |
1563 | fixed with _\b0 to force each term to have the same width. When either _\bx | |
1564 | or _\by begins with a zero, the shell attempts to force all generated | |
1565 | terms to contain the same number of digits, zero-padding where neces- | |
1566 | sary. When characters are supplied, the expression expands to each | |
712f80b0 CR |
1567 | character lexicographically between _\bx and _\by, inclusive, using the de- |
1568 | fault C locale. Note that both _\bx and _\by must be of the same type. When | |
1569 | the increment is supplied, it is used as the difference between each | |
1570 | term. The default increment is 1 or -1 as appropriate. | |
17345e5a JA |
1571 | |
1572 | Brace expansion is performed before any other expansions, and any char- | |
1573 | acters special to other expansions are preserved in the result. It is | |
1574 | strictly textual. B\bBa\bas\bsh\bh does not apply any syntactic interpretation to | |
1575 | the context of the expansion or the text between the braces. | |
1576 | ||
1577 | A correctly-formed brace expansion must contain unquoted opening and | |
712f80b0 CR |
1578 | closing braces, and at least one unquoted comma or a valid sequence ex- |
1579 | pression. Any incorrectly formed brace expansion is left unchanged. A | |
1580 | {\b{ or ,\b, may be quoted with a backslash to prevent its being considered | |
17345e5a | 1581 | part of a brace expression. To avoid conflicts with parameter expan- |
d233b485 CR |
1582 | sion, the string $\b${\b{ is not considered eligible for brace expansion, and |
1583 | inhibits brace expansion until the closing }\b}. | |
17345e5a JA |
1584 | |
1585 | This construct is typically used as shorthand when the common prefix of | |
1586 | the strings to be generated is longer than in the above example: | |
1587 | ||
1588 | mkdir /usr/local/src/bash/{old,new,dist,bugs} | |
1589 | or | |
1590 | chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} | |
1591 | ||
d233b485 CR |
1592 | Brace expansion introduces a slight incompatibility with historical |
1593 | versions of s\bsh\bh. s\bsh\bh does not treat opening or closing braces specially | |
1594 | when they appear as part of a word, and preserves them in the output. | |
1595 | B\bBa\bas\bsh\bh removes braces from words as a consequence of brace expansion. | |
1596 | For example, a word entered to s\bsh\bh as _\bf_\bi_\bl_\be_\b{_\b1_\b,_\b2_\b} appears identically in | |
1597 | the output. The same word is output as _\bf_\bi_\bl_\be_\b1 _\bf_\bi_\bl_\be_\b2 after expansion by | |
1598 | b\bba\bas\bsh\bh. If strict compatibility with s\bsh\bh is desired, start b\bba\bas\bsh\bh with the | |
17345e5a JA |
1599 | +\b+B\bB option or disable brace expansion with the +\b+B\bB option to the s\bse\bet\bt com- |
1600 | 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). | |
1601 | ||
1602 | T\bTi\bil\bld\bde\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
d233b485 CR |
1603 | If a word begins with an unquoted tilde character (`~\b~'), all of the |
1604 | characters preceding the first unquoted slash (or all characters, if | |
1605 | there is no unquoted slash) are considered a _\bt_\bi_\bl_\bd_\be_\b-_\bp_\br_\be_\bf_\bi_\bx. If none of | |
1606 | the characters in the tilde-prefix are quoted, the characters in the | |
1607 | tilde-prefix following the tilde are treated as a possible _\bl_\bo_\bg_\bi_\bn _\bn_\ba_\bm_\be. | |
1608 | If this login name is the null string, the tilde is replaced with the | |
1609 | value of the shell parameter H\bHO\bOM\bME\bE. If H\bHO\bOM\bME\bE is unset, the home direc- | |
1610 | tory of the user executing the shell is substituted instead. Other- | |
1611 | wise, the tilde-prefix is replaced with the home directory associated | |
17345e5a JA |
1612 | with the specified login name. |
1613 | ||
712f80b0 CR |
1614 | If the tilde-prefix is a `~+', the value of the shell variable P\bPW\bWD\bD re- |
1615 | places the tilde-prefix. If the tilde-prefix is a `~-', the value of | |
d233b485 CR |
1616 | the shell variable O\bOL\bLD\bDP\bPW\bWD\bD, if it is set, is substituted. If the char- |
1617 | acters following the tilde in the tilde-prefix consist of a number _\bN, | |
1618 | optionally prefixed by a `+' or a `-', the tilde-prefix is replaced | |
17345e5a JA |
1619 | with the corresponding element from the directory stack, as it would be |
1620 | displayed by the d\bdi\bir\brs\bs builtin invoked with the tilde-prefix as an argu- | |
d233b485 | 1621 | ment. If the characters following the tilde in the tilde-prefix con- |
17345e5a JA |
1622 | sist of a number without a leading `+' or `-', `+' is assumed. |
1623 | ||
1624 | If the login name is invalid, or the tilde expansion fails, the word is | |
1625 | unchanged. | |
1626 | ||
1627 | Each variable assignment is checked for unquoted tilde-prefixes immedi- | |
1628 | ately following a :\b: or the first =\b=. In these cases, tilde expansion is | |
712f80b0 CR |
1629 | also performed. Consequently, one may use filenames with tildes in as- |
1630 | 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- | |
1631 | panded value. | |
17345e5a | 1632 | |
d233b485 CR |
1633 | Bash also performs tilde expansion on words satisfying the conditions |
1634 | of variable assignments (as described above under P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS) when they | |
1635 | appear as arguments to simple commands. Bash does not do this, except | |
1636 | 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. | |
1637 | ||
17345e5a JA |
1638 | P\bPa\bar\bra\bam\bme\bet\bte\ber\br E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn |
1639 | The `$\b$' character introduces parameter expansion, command substitution, | |
1640 | or arithmetic expansion. The parameter name or symbol to be expanded | |
1641 | may be enclosed in braces, which are optional but serve to protect the | |
1642 | variable to be expanded from characters immediately following it which | |
1643 | could be interpreted as part of the name. | |
1644 | ||
1645 | When braces are used, the matching ending brace is the first `}\b}' not | |
712f80b0 CR |
1646 | escaped by a backslash or within a quoted string, and not within an em- |
1647 | bedded arithmetic expansion, command substitution, or parameter expan- | |
1648 | sion. | |
17345e5a JA |
1649 | |
1650 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br} | |
1651 | The value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is substituted. The braces are required | |
1652 | when _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is a positional parameter with more than one | |
1653 | digit, or when _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is followed by a character which is not | |
ac50fbac CR |
1654 | to be interpreted as part of its name. The _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is a shell |
1655 | parameter as described above P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS) or an array reference | |
1656 | (A\bAr\brr\bra\bay\bys\bs). | |
1657 | ||
a0c0a00f | 1658 | If the first character of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an exclamation point (!\b!), and |
d233b485 | 1659 | _\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 |
712f80b0 CR |
1660 | uses the value formed by expanding the rest of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br as the new _\bp_\ba_\b- |
1661 | _\br_\ba_\bm_\be_\bt_\be_\br; this is then expanded and that value is used in the rest of | |
d233b485 | 1662 | the expansion, rather than the expansion of the original _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br. |
712f80b0 CR |
1663 | 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- |
1664 | pansion, parameter expansion, command substitution, and arithmetic ex- | |
1665 | pansion. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is a nameref, this expands to the name of the | |
d233b485 CR |
1666 | parameter referenced by _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br instead of performing the complete |
1667 | indirect expansion. The exceptions to this are the expansions of | |
1668 | ${!\b!_\bp_\br_\be_\bf_\bi_\bx*\b*} and ${!\b!_\bn_\ba_\bm_\be[_\b@]} described below. The exclamation point | |
1669 | must immediately follow the left brace in order to introduce indirec- | |
1670 | tion. | |
17345e5a JA |
1671 | |
1672 | In each of the cases below, _\bw_\bo_\br_\bd is subject to tilde expansion, parame- | |
1673 | ter expansion, command substitution, and arithmetic expansion. | |
1674 | ||
712f80b0 CR |
1675 | When not performing substring expansion, using the forms documented be- |
1676 | low (e.g., :\b:-\b-), b\bba\bas\bsh\bh tests for a parameter that is unset or null. | |
1677 | Omitting the colon results in a test only for a parameter that is un- | |
1678 | set. | |
17345e5a JA |
1679 | |
1680 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:-\b-_\bw_\bo_\br_\bd} | |
ac50fbac CR |
1681 | 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- |
1682 | sion of _\bw_\bo_\br_\bd is substituted. Otherwise, the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br | |
17345e5a JA |
1683 | is substituted. |
1684 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:=\b=_\bw_\bo_\br_\bd} | |
712f80b0 CR |
1685 | 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- |
1686 | 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- | |
1687 | _\bt_\be_\br is then substituted. Positional parameters and special pa- | |
1688 | rameters may not be assigned to in this way. | |
17345e5a | 1689 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:?\b?_\bw_\bo_\br_\bd} |
ac50fbac CR |
1690 | 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, |
1691 | the expansion of _\bw_\bo_\br_\bd (or a message to that effect if _\bw_\bo_\br_\bd is | |
1692 | not present) is written to the standard error and the shell, if | |
17345e5a JA |
1693 | it is not interactive, exits. Otherwise, the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
1694 | is substituted. | |
1695 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:+\b+_\bw_\bo_\br_\bd} | |
ac50fbac | 1696 | 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 |
1697 | substituted, otherwise the expansion of _\bw_\bo_\br_\bd is substituted. |
1698 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br:\b:_\bo_\bf_\bf_\bs_\be_\bt} | |
1699 | ${_\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 |
1700 | 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 |
1701 | value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br starting at the character specified by _\bo_\bf_\bf_\b- | |
1702 | _\bs_\be_\bt. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@, an indexed array subscripted by @\b@ or *\b*, | |
1703 | or an associative array name, the results differ as described | |
1704 | below. If _\bl_\be_\bn_\bg_\bt_\bh is omitted, expands to the substring of the | |
1705 | value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br starting at the character specified by _\bo_\bf_\bf_\bs_\be_\bt | |
1706 | and extending to the end of the value. _\bl_\be_\bn_\bg_\bt_\bh and _\bo_\bf_\bf_\bs_\be_\bt are | |
1707 | 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). | |
1708 | ||
1709 | If _\bo_\bf_\bf_\bs_\be_\bt evaluates to a number less than zero, the value is | |
712f80b0 CR |
1710 | used as an offset in characters from the end of the value of _\bp_\ba_\b- |
1711 | _\br_\ba_\bm_\be_\bt_\be_\br. If _\bl_\be_\bn_\bg_\bt_\bh evaluates to a number less than zero, it is | |
1712 | interpreted as an offset in characters from the end of the value | |
1713 | of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br rather than a number of characters, and the expan- | |
1714 | sion is the characters between _\bo_\bf_\bf_\bs_\be_\bt and that result. Note | |
1715 | that a negative offset must be separated from the colon by at | |
1716 | least one space to avoid being confused with the :\b:-\b- expansion. | |
1717 | ||
1718 | If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@, the result is _\bl_\be_\bn_\bg_\bt_\bh positional parameters | |
ac50fbac | 1719 | beginning at _\bo_\bf_\bf_\bs_\be_\bt. A negative _\bo_\bf_\bf_\bs_\be_\bt is taken relative to one |
712f80b0 CR |
1720 | greater than the greatest positional parameter, so an offset of |
1721 | -1 evaluates to the last positional parameter. It is an expan- | |
ac50fbac CR |
1722 | sion error if _\bl_\be_\bn_\bg_\bt_\bh evaluates to a number less than zero. |
1723 | ||
1724 | If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an indexed array name subscripted by @ or *, the | |
712f80b0 CR |
1725 | result is the _\bl_\be_\bn_\bg_\bt_\bh members of the array beginning with ${_\bp_\ba_\b- |
1726 | _\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 | |
1727 | greater than the maximum index of the specified array. It is an | |
1728 | expansion error if _\bl_\be_\bn_\bg_\bt_\bh evaluates to a number less than zero. | |
ac50fbac | 1729 | |
712f80b0 CR |
1730 | Substring expansion applied to an associative array produces un- |
1731 | defined results. | |
ac50fbac CR |
1732 | |
1733 | Substring indexing is zero-based unless the positional parame- | |
712f80b0 CR |
1734 | ters are used, in which case the indexing starts at 1 by de- |
1735 | fault. If _\bo_\bf_\bf_\bs_\be_\bt is 0, and the positional parameters are used, | |
1736 | $\b$0\b0 is prefixed to the list. | |
17345e5a JA |
1737 | |
1738 | ${!\b!_\bp_\br_\be_\bf_\bi_\bx*\b*} | |
1739 | ${!\b!_\bp_\br_\be_\bf_\bi_\bx@\b@} | |
495aee44 | 1740 | 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 | 1741 | names begin with _\bp_\br_\be_\bf_\bi_\bx, separated by the first character of the |
495aee44 CR |
1742 | I\bIF\bFS\bS special variable. When _\b@ is used and the expansion appears |
1743 | within double quotes, each variable name expands to a separate | |
17345e5a JA |
1744 | word. |
1745 | ||
1746 | ${!\b!_\bn_\ba_\bm_\be[_\b@]} | |
1747 | ${!\b!_\bn_\ba_\bm_\be[_\b*]} | |
495aee44 CR |
1748 | 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 |
1749 | the list of array indices (keys) assigned in _\bn_\ba_\bm_\be. If _\bn_\ba_\bm_\be is | |
1750 | not an array, expands to 0 if _\bn_\ba_\bm_\be is set and null otherwise. | |
1751 | When _\b@ is used and the expansion appears within double quotes, | |
17345e5a JA |
1752 | each key expands to a separate word. |
1753 | ||
1754 | ${#\b#_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br} | |
712f80b0 CR |
1755 | 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- |
1756 | _\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- | |
1757 | stituted is the number of positional parameters. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br | |
1758 | is an array name subscripted by *\b* or @\b@, the value substituted is | |
1759 | the number of elements in the array. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an indexed | |
1760 | array name subscripted by a negative number, that number is in- | |
1761 | terpreted as relative to one greater than the maximum index of | |
1762 | _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br, so negative indices count back from the end of the | |
1763 | array, and an index of -1 references the last element. | |
17345e5a JA |
1764 | |
1765 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br#\b#_\bw_\bo_\br_\bd} | |
1766 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br#\b##\b#_\bw_\bo_\br_\bd} | |
495aee44 | 1767 | 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 |
1768 | a pattern just as in pathname expansion, and matched against the |
1769 | expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br using the rules described under P\bPa\bat\bt-\b- | |
712f80b0 CR |
1770 | t\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg below. If the pattern matches the beginning of |
1771 | the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br, then the result of the expansion is the | |
1772 | expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br with the shortest matching pattern | |
1773 | (the ``#\b#'' case) or the longest matching pattern (the ``#\b##\b#'' | |
1774 | case) deleted. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the pattern removal op- | |
1775 | eration is applied to each positional parameter in turn, and the | |
1776 | expansion is the resultant list. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an array vari- | |
1777 | able subscripted with @\b@ or *\b*, the pattern removal operation is | |
1778 | applied to each member of the array in turn, and the expansion | |
1779 | is the resultant list. | |
d233b485 CR |
1780 | |
1781 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br%\b%_\bw_\bo_\br_\bd} | |
1782 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br%\b%%\b%_\bw_\bo_\br_\bd} | |
1783 | 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 | |
1784 | a pattern just as in pathname expansion, and matched against the | |
1785 | expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br using the rules described under P\bPa\bat\bt-\b- | |
712f80b0 CR |
1786 | t\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg below. If the pattern matches a trailing portion |
1787 | of the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br, then the result of the ex- | |
1788 | pansion is the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br with the shortest | |
1789 | matching pattern (the ``%\b%'' case) or the longest matching pat- | |
1790 | tern (the ``%\b%%\b%'' case) deleted. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the | |
1791 | pattern removal operation is applied to each positional parame- | |
17345e5a | 1792 | ter in turn, and the expansion is the resultant list. If _\bp_\ba_\br_\ba_\bm_\b- |
712f80b0 CR |
1793 | _\be_\bt_\be_\br is an array variable subscripted with @\b@ or *\b*, the pattern |
1794 | removal operation is applied to each member of the array in | |
17345e5a JA |
1795 | turn, and the expansion is the resultant list. |
1796 | ||
17345e5a | 1797 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br/\b/_\bp_\ba_\bt_\bt_\be_\br_\bn/\b/_\bs_\bt_\br_\bi_\bn_\bg} |
495aee44 | 1798 | 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- |
712f80b0 CR |
1799 | tern just as in pathname expansion, _\bP_\ba_\br_\ba_\bm_\be_\bt_\be_\br is expanded and |
1800 | the longest match of _\bp_\ba_\bt_\bt_\be_\br_\bn against its value is replaced with | |
1801 | _\bs_\bt_\br_\bi_\bn_\bg. The match is performed using the rules described under | |
1802 | P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg below. If _\bp_\ba_\bt_\bt_\be_\br_\bn begins with /\b/, all matches | |
1803 | of _\bp_\ba_\bt_\bt_\be_\br_\bn are replaced with _\bs_\bt_\br_\bi_\bn_\bg. Normally only the first | |
1804 | match is replaced. If _\bp_\ba_\bt_\bt_\be_\br_\bn begins with #\b#, it must match at | |
1805 | the beginning of the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br. If _\bp_\ba_\bt_\bt_\be_\br_\bn | |
d233b485 | 1806 | begins with %\b%, it must match at the end of the expanded value of |
712f80b0 CR |
1807 | _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br. If _\bs_\bt_\br_\bi_\bn_\bg is null, matches of _\bp_\ba_\bt_\bt_\be_\br_\bn are deleted |
1808 | and the /\b/ following _\bp_\ba_\bt_\bt_\be_\br_\bn may be omitted. If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh | |
1809 | shell option is enabled, the match is performed without regard | |
1810 | to the case of alphabetic characters. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, | |
d233b485 CR |
1811 | the substitution operation is applied to each positional parame- |
1812 | ter in turn, and the expansion is the resultant list. If _\bp_\ba_\br_\ba_\bm_\b- | |
1813 | _\be_\bt_\be_\br is an array variable subscripted with @\b@ or *\b*, the substitu- | |
712f80b0 | 1814 | tion operation is applied to each member of the array in turn, |
d233b485 | 1815 | and the expansion is the resultant list. |
17345e5a JA |
1816 | |
1817 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br^\b^_\bp_\ba_\bt_\bt_\be_\br_\bn} | |
1818 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br^\b^^\b^_\bp_\ba_\bt_\bt_\be_\br_\bn} | |
1819 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br,\b,_\bp_\ba_\bt_\bt_\be_\br_\bn} | |
1820 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br,\b,,\b,_\bp_\ba_\bt_\bt_\be_\br_\bn} | |
712f80b0 CR |
1821 | 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- |
1822 | 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 | 1823 | duce a pattern just as in pathname expansion. Each character in |
712f80b0 CR |
1824 | the expanded value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is tested against _\bp_\ba_\bt_\bt_\be_\br_\bn, and, |
1825 | if it matches the pattern, its case is converted. The pattern | |
1826 | should not attempt to match more than one character. The ^\b^ op- | |
1827 | erator converts lowercase letters matching _\bp_\ba_\bt_\bt_\be_\br_\bn to uppercase; | |
1828 | the ,\b, operator converts matching uppercase letters to lowercase. | |
1829 | The ^\b^^\b^ and ,\b,,\b, expansions convert each matched character in the | |
1830 | expanded value; the ^\b^ and ,\b, expansions match and convert only | |
1831 | the first character in the expanded value. If _\bp_\ba_\bt_\bt_\be_\br_\bn is omit- | |
1832 | ted, it is treated like a ?\b?, which matches every character. If | |
1833 | _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the case modification operation is applied | |
1834 | to each positional parameter in turn, and the expansion is the | |
1835 | resultant list. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an array variable subscripted | |
1836 | with @\b@ or *\b*, the case modification operation is applied to each | |
1837 | member of the array in turn, and the expansion is the resultant | |
1838 | list. | |
17345e5a | 1839 | |
a0c0a00f CR |
1840 | ${_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br@\b@_\bo_\bp_\be_\br_\ba_\bt_\bo_\br} |
1841 | 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- | |
712f80b0 CR |
1842 | 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 |
1843 | 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 |
1844 | single letter: |
1845 | ||
712f80b0 CR |
1846 | U\bU The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
1847 | with lowercase alphabetic characters converted to upper- | |
1848 | case. | |
1849 | u\bu The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br | |
1850 | with the first character converted to uppercase, if it is | |
1851 | alphabetic. | |
1852 | L\bL The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br | |
1853 | with uppercase alphabetic characters converted to lower- | |
1854 | case. | |
1855 | Q\bQ The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br | |
a0c0a00f | 1856 | quoted in a format that can be reused as input. |
712f80b0 CR |
1857 | E\bE The expansion is a string that is the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br |
1858 | with backslash escape sequences expanded as with the | |
d233b485 | 1859 | $\b$'\b'.\b..\b..\b.'\b' quoting mechanism. |
a0c0a00f CR |
1860 | P\bP The expansion is a string that is the result of expanding |
1861 | the value of _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br as if it were a prompt string (see | |
1862 | P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG below). | |
712f80b0 CR |
1863 | A\bA The expansion is a string in the form of an assignment |
1864 | statement or d\bde\bec\bcl\bla\bar\bre\be command that, if evaluated, will | |
a0c0a00f | 1865 | recreate _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br with its attributes and value. |
712f80b0 CR |
1866 | K\bK Produces a possibly-quoted version of the value of _\bp_\ba_\br_\ba_\bm_\b- |
1867 | _\be_\bt_\be_\br, except that it prints the values of indexed and as- | |
1868 | sociative arrays as a sequence of quoted key-value pairs | |
1869 | (see A\bAr\brr\bra\bay\bys\bs above). | |
d233b485 | 1870 | a\ba The expansion is a string consisting of flag values rep- |
a0c0a00f CR |
1871 | resenting _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br's attributes. |
1872 | ||
d233b485 CR |
1873 | If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is @\b@ or *\b*, the operation is applied to each posi- |
1874 | tional parameter in turn, and the expansion is the resultant | |
1875 | list. If _\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br is an array variable subscripted with @\b@ or | |
1876 | *\b*, the operation is applied to each member of the array in turn, | |
1877 | and the expansion is the resultant list. | |
a0c0a00f | 1878 | |
d233b485 | 1879 | The result of the expansion is subject to word splitting and |
a0c0a00f CR |
1880 | pathname expansion as described below. |
1881 | ||
17345e5a JA |
1882 | C\bCo\bom\bmm\bma\ban\bnd\bd S\bSu\bub\bbs\bst\bti\bit\btu\but\bti\bio\bon\bn |
1883 | _\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- | |
1884 | mand name. There are two forms: | |
1885 | ||
17345e5a JA |
1886 | $\b$(\b(_\bc_\bo_\bm_\bm_\ba_\bn_\bd)\b) |
1887 | or | |
1888 | `\b`_\bc_\bo_\bm_\bm_\ba_\bn_\bd`\b` | |
1889 | ||
a0c0a00f CR |
1890 | B\bBa\bas\bsh\bh performs the expansion by executing _\bc_\bo_\bm_\bm_\ba_\bn_\bd in a subshell environ- |
1891 | ment and replacing the command substitution with the standard output of | |
1892 | the command, with any trailing newlines deleted. Embedded newlines are | |
d233b485 CR |
1893 | not deleted, but they may be removed during word splitting. The com- |
1894 | mand substitution $\b$(\b(c\bca\bat\bt _\bf_\bi_\bl_\be)\b) can be replaced by the equivalent but | |
a0c0a00f | 1895 | faster $\b$(\b(<\b< _\bf_\bi_\bl_\be)\b). |
17345e5a | 1896 | |
d233b485 CR |
1897 | When the old-style backquote form of substitution is used, backslash |
1898 | retains its literal meaning except when followed by $\b$, `\b`, or \\b\. The | |
17345e5a | 1899 | first backquote not preceded by a backslash terminates the command sub- |
d233b485 | 1900 | stitution. When using the $(_\bc_\bo_\bm_\bm_\ba_\bn_\bd) form, all characters between the |
17345e5a JA |
1901 | parentheses make up the command; none are treated specially. |
1902 | ||
1903 | Command substitutions may be nested. To nest when using the backquoted | |
1904 | form, escape the inner backquotes with backslashes. | |
1905 | ||
d233b485 | 1906 | If the substitution appears within double quotes, word splitting and |
17345e5a JA |
1907 | pathname expansion are not performed on the results. |
1908 | ||
1909 | A\bAr\bri\bit\bth\bhm\bme\bet\bti\bic\bc E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
d233b485 CR |
1910 | Arithmetic expansion allows the evaluation of an arithmetic expression |
1911 | and the substitution of the result. The format for arithmetic expan- | |
17345e5a JA |
1912 | sion is: |
1913 | ||
1914 | $\b$(\b((\b(_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn)\b))\b) | |
1915 | ||
d233b485 | 1916 | The _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn is treated as if it were within double quotes, but a |
712f80b0 CR |
1917 | double quote inside the parentheses is not treated specially. All to- |
1918 | kens in the expression undergo parameter and variable expansion, com- | |
d233b485 CR |
1919 | mand substitution, and quote removal. The result is treated as the |
1920 | arithmetic expression to be evaluated. Arithmetic expansions may be | |
17345e5a JA |
1921 | nested. |
1922 | ||
d233b485 | 1923 | The evaluation is performed according to the rules listed below under |
17345e5a JA |
1924 | 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 |
1925 | indicating failure and no substitution occurs. | |
1926 | ||
1927 | P\bPr\bro\boc\bce\bes\bss\bs S\bSu\bub\bbs\bst\bti\bit\btu\but\bti\bio\bon\bn | |
d233b485 CR |
1928 | _\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 |
1929 | 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 | |
1930 | process _\bl_\bi_\bs_\bt is run asynchronously, and its input or output appears as | |
a0c0a00f | 1931 | a filename. This filename is passed as an argument to the current com- |
d233b485 CR |
1932 | mand as the result of the expansion. If the >\b>(\b(_\bl_\bi_\bs_\bt)\b) form is used, |
1933 | writing to the file will provide input for _\bl_\bi_\bs_\bt. If the <\b<(\b(_\bl_\bi_\bs_\bt)\b) form | |
1934 | is used, the file passed as an argument should be read to obtain the | |
a0c0a00f CR |
1935 | output of _\bl_\bi_\bs_\bt. Process substitution is supported on systems that sup- |
1936 | 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 | 1937 | |
d233b485 CR |
1938 | When available, process substitution is performed simultaneously with |
1939 | parameter and variable expansion, command substitution, and arithmetic | |
17345e5a JA |
1940 | expansion. |
1941 | ||
1942 | W\bWo\bor\brd\bd S\bSp\bpl\bli\bit\btt\bti\bin\bng\bg | |
d233b485 CR |
1943 | The shell scans the results of parameter expansion, command substitu- |
1944 | tion, and arithmetic expansion that did not occur within double quotes | |
17345e5a JA |
1945 | for _\bw_\bo_\br_\bd _\bs_\bp_\bl_\bi_\bt_\bt_\bi_\bn_\bg. |
1946 | ||
d233b485 CR |
1947 | The shell treats each character of I\bIF\bFS\bS as a delimiter, and splits the |
1948 | results of the other expansions into words using these characters as | |
1949 | field terminators. If I\bIF\bFS\bS is unset, or its value is exactly | |
1950 | <\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>, | |
1951 | and <\b<n\bne\bew\bwl\bli\bin\bne\be>\b> at the beginning and end of the results of the previous | |
1952 | expansions are ignored, and any sequence of I\bIF\bFS\bS characters not at the | |
1953 | beginning or end serves to delimit words. If I\bIF\bFS\bS has a value other | |
1954 | than the default, then sequences of the whitespace characters s\bsp\bpa\bac\bce\be, | |
1955 | t\bta\bab\bb, and n\bne\bew\bwl\bli\bin\bne\be are ignored at the beginning and end of the word, as | |
1956 | long as the whitespace character is in the value of I\bIF\bFS\bS (an I\bIF\bFS\bS white- | |
1957 | space character). Any character in I\bIF\bFS\bS that is not I\bIF\bFS\bS whitespace, | |
a0c0a00f | 1958 | along with any adjacent I\bIF\bFS\bS whitespace characters, delimits a field. A |
d233b485 | 1959 | sequence of I\bIF\bFS\bS whitespace characters is also treated as a delimiter. |
a0c0a00f CR |
1960 | If the value of I\bIF\bFS\bS is null, no word splitting occurs. |
1961 | ||
d233b485 | 1962 | Explicit null arguments ("\b""\b" or '\b''\b') are retained and passed to commands |
a0c0a00f CR |
1963 | as empty strings. Unquoted implicit null arguments, resulting from the |
1964 | expansion of parameters that have no values, are removed. If a parame- | |
712f80b0 CR |
1965 | ter with no value is expanded within double quotes, a null argument re- |
1966 | sults and is retained and passed to a command as an empty string. When | |
1967 | a quoted null argument appears as part of a word whose expansion is | |
1968 | non-null, the null argument is removed. That is, the word -d'' becomes | |
1969 | -d after word splitting and null argument removal. | |
17345e5a JA |
1970 | |
1971 | Note that if no expansion occurs, no splitting is performed. | |
1972 | ||
1973 | P\bPa\bat\bth\bhn\bna\bam\bme\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn | |
d233b485 CR |
1974 | After word splitting, unless the -\b-f\bf option has been set, b\bba\bas\bsh\bh scans |
1975 | each word for the characters *\b*, ?\b?, and [\b[. If one of these characters | |
712f80b0 CR |
1976 | appears, and is not quoted, then the word is regarded as a _\bp_\ba_\bt_\bt_\be_\br_\bn, and |
1977 | replaced with an alphabetically sorted list of filenames matching the | |
1978 | 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 | |
1979 | found, and the shell option n\bnu\bul\bll\blg\bgl\blo\bob\bb is not enabled, the word is left | |
1980 | unchanged. If the n\bnu\bul\bll\blg\bgl\blo\bob\bb option is set, and no matches are found, | |
1981 | the word is removed. If the f\bfa\bai\bil\blg\bgl\blo\bob\bb shell option is set, and no | |
1982 | matches are found, an error message is printed and the command is not | |
1983 | executed. If the shell option n\bno\boc\bca\bas\bse\beg\bgl\blo\bob\bb is enabled, the match is per- | |
1984 | formed without regard to the case of alphabetic characters. When a | |
1985 | pattern is used for pathname expansion, the character `\b``\b`.\b.'\b''\b' at the | |
1986 | start of a name or immediately following a slash must be matched ex- | |
1987 | plicitly, unless the shell option d\bdo\bot\btg\bgl\blo\bob\bb is set. The filenames `\b``\b`.\b.'\b''\b' | |
1988 | and `\b``\b`.\b..\b.'\b''\b' must always be matched explicitly, even if d\bdo\bot\btg\bgl\blo\bob\bb is set. | |
1989 | In other cases, the `\b``\b`.\b.'\b''\b' character is not treated specially. When | |
1990 | matching a pathname, the slash character must always be matched explic- | |
1991 | itly by a slash in the pattern, but in other matching contexts it can | |
1992 | be matched by a special pattern character as described below under P\bPa\bat\bt-\b- | |
1993 | t\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg. 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 | |
1994 | C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS for a description of the n\bno\boc\bca\bas\bse\beg\bgl\blo\bob\bb, n\bnu\bul\bll\blg\bgl\blo\bob\bb, f\bfa\bai\bil\blg\bgl\blo\bob\bb, and | |
1995 | d\bdo\bot\btg\bgl\blo\bob\bb shell options. | |
d233b485 CR |
1996 | |
1997 | The G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE shell variable may be used to restrict the set of file | |
1998 | 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 | |
1999 | name that also matches one of the patterns in G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE is removed | |
2000 | from the list of matches. If the n\bno\boc\bca\bas\bse\beg\bgl\blo\bob\bb option is set, the match- | |
2001 | ing against the patterns in G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE is performed without regard to | |
2002 | 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- | |
2003 | 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 | |
2004 | value has the effect of enabling the d\bdo\bot\btg\bgl\blo\bob\bb shell option, so all other | |
2005 | filenames beginning with a `\b``\b`.\b.'\b''\b' will match. To get the old behavior | |
2006 | of ignoring filenames beginning with a `\b``\b`.\b.'\b''\b', make `\b``\b`.\b.*\b*'\b''\b' one of the | |
2007 | 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 | |
2008 | is unset. The pattern matching honors the setting of the e\bex\bxt\btg\bgl\blo\bob\bb shell | |
a0c0a00f | 2009 | option. |
17345e5a JA |
2010 | |
2011 | P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg | |
2012 | ||
2013 | Any character that appears in a pattern, other than the special pattern | |
d233b485 CR |
2014 | characters described below, matches itself. The NUL character may not |
2015 | occur in a pattern. A backslash escapes the following character; the | |
2016 | escaping backslash is discarded when matching. The special pattern | |
17345e5a JA |
2017 | characters must be quoted if they are to be matched literally. |
2018 | ||
2019 | The special pattern characters have the following meanings: | |
2020 | ||
d233b485 CR |
2021 | *\b* Matches any string, including the null string. When the |
2022 | g\bgl\blo\bob\bbs\bst\bta\bar\br shell option is enabled, and *\b* is used in a | |
2023 | pathname expansion context, two adjacent *\b*s used as a | |
712f80b0 CR |
2024 | single pattern will match all files and zero or more di- |
2025 | rectories and subdirectories. If followed by a /\b/, two | |
d233b485 | 2026 | adjacent *\b*s will match only directories and subdirecto- |
495aee44 CR |
2027 | ries. |
2028 | ?\b? Matches any single character. | |
d233b485 CR |
2029 | [\b[.\b..\b..\b.]\b] Matches any one of the enclosed characters. A pair of |
2030 | characters separated by a hyphen denotes a _\br_\ba_\bn_\bg_\be _\be_\bx_\bp_\br_\be_\bs_\b- | |
2031 | _\bs_\bi_\bo_\bn; any character that falls between those two charac- | |
712f80b0 CR |
2032 | ters, inclusive, using the current locale's collating se- |
2033 | quence and character set, is matched. If the first char- | |
2034 | acter following the [\b[ is a !\b! or a ^\b^ then any character | |
2035 | not enclosed is matched. The sorting order of characters | |
2036 | in range expressions is determined by the current locale | |
2037 | and the values of the L\bLC\bC_\b_C\bCO\bOL\bLL\bLA\bAT\bTE\bE or L\bLC\bC_\b_A\bAL\bLL\bL shell vari- | |
2038 | ables, if set. To obtain the traditional interpretation | |
2039 | of range expressions, where [\b[a\ba-\b-d\bd]\b] is equivalent to | |
d233b485 CR |
2040 | [\b[a\bab\bbc\bcd\bd]\b], set value of the L\bLC\bC_\b_A\bAL\bLL\bL shell variable to C\bC, or |
2041 | enable the g\bgl\blo\bob\bba\bas\bsc\bci\bii\bir\bra\ban\bng\bge\bes\bs shell option. A -\b- may be | |
ac50fbac CR |
2042 | matched by including it as the first or last character in |
2043 | the set. A ]\b] may be matched by including it as the first | |
2044 | character in the set. | |
2045 | ||
d233b485 | 2046 | 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 |
2047 | the syntax [\b[:\b:_\bc_\bl_\ba_\bs_\bs:\b:]\b], where _\bc_\bl_\ba_\bs_\bs is one of the following |
2048 | classes defined in the POSIX standard: | |
d233b485 | 2049 | 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 |
2050 | 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 |
2051 | A character class matches any character belonging to that | |
2052 | class. The w\bwo\bor\brd\bd character class matches letters, digits, | |
2053 | and the character _. | |
2054 | ||
712f80b0 CR |
2055 | 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- |
2056 | ing the syntax [\b[=\b=_\bc=\b=]\b], which matches all characters with | |
2057 | the same collation weight (as defined by the current lo- | |
2058 | cale) as the character _\bc. | |
495aee44 CR |
2059 | |
2060 | Within [\b[ and ]\b], the syntax [\b[.\b._\bs_\by_\bm_\bb_\bo_\bl.\b.]\b] matches the collat- | |
2061 | ing symbol _\bs_\by_\bm_\bb_\bo_\bl. | |
17345e5a JA |
2062 | |
2063 | If the e\bex\bxt\btg\bgl\blo\bob\bb shell option is enabled using the s\bsh\bho\bop\bpt\bt builtin, several | |
d233b485 | 2064 | extended pattern matching operators are recognized. In the following |
17345e5a JA |
2065 | description, a _\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt is a list of one or more patterns separated |
2066 | by a |\b|. Composite patterns may be formed using one or more of the fol- | |
2067 | lowing sub-patterns: | |
2068 | ||
2069 | ?\b?(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2070 | Matches zero or one occurrence of the given patterns | |
2071 | *\b*(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2072 | Matches zero or more occurrences of the given patterns | |
2073 | +\b+(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2074 | Matches one or more occurrences of the given patterns | |
2075 | @\b@(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2076 | Matches one of the given patterns | |
2077 | !\b!(\b(_\bp_\ba_\bt_\bt_\be_\br_\bn_\b-_\bl_\bi_\bs_\bt)\b) | |
2078 | Matches anything except one of the given patterns | |
2079 | ||
712f80b0 CR |
2080 | Complicated extended pattern matching against long strings is slow, es- |
2081 | pecially when the patterns contain alternations and the strings contain | |
2082 | multiple matches. Using separate matches against shorter strings, or | |
2083 | using arrays of strings instead of a single long string, may be faster. | |
d233b485 | 2084 | |
17345e5a JA |
2085 | Q\bQu\buo\bot\bte\be R\bRe\bem\bmo\bov\bva\bal\bl |
2086 | After the preceding expansions, all unquoted occurrences of the charac- | |
712f80b0 | 2087 | ters \\b\, '\b', and "\b" that did not result from one of the above expansions |
17345e5a JA |
2088 | are removed. |
2089 | ||
2090 | R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN | |
712f80b0 CR |
2091 | Before a command is executed, its input and output may be _\br_\be_\bd_\bi_\br_\be_\bc_\bt_\be_\bd |
2092 | using a special notation interpreted by the shell. Redirection allows | |
2093 | commands' file handles to be duplicated, opened, closed, made to refer | |
ac50fbac | 2094 | to different files, and can change the files the command reads from and |
712f80b0 CR |
2095 | writes to. Redirection may also be used to modify file handles in the |
2096 | current shell execution environment. The following redirection opera- | |
ac50fbac | 2097 | tors may precede or appear anywhere within a _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd or may fol- |
712f80b0 | 2098 | low a _\bc_\bo_\bm_\bm_\ba_\bn_\bd. Redirections are processed in the order they appear, |
ac50fbac | 2099 | from left to right. |
17345e5a | 2100 | |
712f80b0 | 2101 | Each redirection that may be preceded by a file descriptor number may |
0001803f CR |
2102 | instead be preceded by a word of the form {_\bv_\ba_\br_\bn_\ba_\bm_\be}. In this case, for |
2103 | each redirection operator except >&- and <&-, the shell will allocate a | |
712f80b0 CR |
2104 | file descriptor greater than or equal to 10 and assign it to _\bv_\ba_\br_\bn_\ba_\bm_\be. |
2105 | If >&- or <&- is preceded by {_\bv_\ba_\br_\bn_\ba_\bm_\be}, the value of _\bv_\ba_\br_\bn_\ba_\bm_\be defines | |
2106 | the file descriptor to close. If {_\bv_\ba_\br_\bn_\ba_\bm_\be} is supplied, the redirect- | |
2107 | ion persists beyond the scope of the command, allowing the shell pro- | |
d233b485 CR |
2108 | grammer to manage the file descriptor himself. |
2109 | ||
712f80b0 CR |
2110 | In the following descriptions, if the file descriptor number is omit- |
2111 | ted, and the first character of the redirection operator is <\b<, the re- | |
2112 | direction refers to the standard input (file descriptor 0). If the | |
2113 | first character of the redirection operator is >\b>, the redirection | |
17345e5a JA |
2114 | refers to the standard output (file descriptor 1). |
2115 | ||
712f80b0 CR |
2116 | The word following the redirection operator in the following descrip- |
2117 | tions, unless otherwise noted, is subjected to brace expansion, tilde | |
2118 | expansion, parameter and variable expansion, command substitution, | |
2119 | arithmetic expansion, quote removal, pathname expansion, and word | |
ac50fbac | 2120 | splitting. If it expands to more than one word, b\bba\bas\bsh\bh reports an error. |
17345e5a | 2121 | |
712f80b0 | 2122 | Note that the order of redirections is significant. For example, the |
17345e5a JA |
2123 | command |
2124 | ||
2125 | ls >\b> dirlist 2>\b>&\b&1 | |
2126 | ||
712f80b0 | 2127 | directs both standard output and standard error to the file _\bd_\bi_\br_\bl_\bi_\bs_\bt, |
17345e5a JA |
2128 | while the command |
2129 | ||
2130 | ls 2>\b>&\b&1 >\b> dirlist | |
2131 | ||
712f80b0 CR |
2132 | directs only the standard output to file _\bd_\bi_\br_\bl_\bi_\bs_\bt, because the standard |
2133 | error was duplicated from the standard output before the standard out- | |
0001803f | 2134 | put was redirected to _\bd_\bi_\br_\bl_\bi_\bs_\bt. |
17345e5a JA |
2135 | |
2136 | B\bBa\bas\bsh\bh handles several filenames specially when they are used in redirec- | |
a0c0a00f CR |
2137 | tions, as described in the following table. If the operating system on |
2138 | which b\bba\bas\bsh\bh is running provides these special files, bash will use them; | |
712f80b0 | 2139 | otherwise it will emulate them internally with the behavior described |
a0c0a00f | 2140 | below. |
17345e5a JA |
2141 | |
2142 | /\b/d\bde\bev\bv/\b/f\bfd\bd/\b/_\bf_\bd | |
712f80b0 | 2143 | If _\bf_\bd is a valid integer, file descriptor _\bf_\bd is dupli- |
17345e5a JA |
2144 | cated. |
2145 | /\b/d\bde\bev\bv/\b/s\bst\btd\bdi\bin\bn | |
2146 | File descriptor 0 is duplicated. | |
2147 | /\b/d\bde\bev\bv/\b/s\bst\btd\bdo\bou\but\bt | |
2148 | File descriptor 1 is duplicated. | |
2149 | /\b/d\bde\bev\bv/\b/s\bst\btd\bde\ber\brr\br | |
2150 | File descriptor 2 is duplicated. | |
2151 | /\b/d\bde\bev\bv/\b/t\btc\bcp\bp/\b/_\bh_\bo_\bs_\bt/\b/_\bp_\bo_\br_\bt | |
2152 | If _\bh_\bo_\bs_\bt is a valid hostname or Internet address, and _\bp_\bo_\br_\bt | |
712f80b0 | 2153 | is an integer port number or service name, b\bba\bas\bsh\bh attempts |
ac50fbac | 2154 | to open the corresponding TCP socket. |
17345e5a JA |
2155 | /\b/d\bde\bev\bv/\b/u\bud\bdp\bp/\b/_\bh_\bo_\bs_\bt/\b/_\bp_\bo_\br_\bt |
2156 | If _\bh_\bo_\bs_\bt is a valid hostname or Internet address, and _\bp_\bo_\br_\bt | |
712f80b0 | 2157 | is an integer port number or service name, b\bba\bas\bsh\bh attempts |
ac50fbac | 2158 | to open the corresponding UDP socket. |
17345e5a JA |
2159 | |
2160 | A failure to open or create a file causes the redirection to fail. | |
2161 | ||
712f80b0 CR |
2162 | Redirections using file descriptors greater than 9 should be used with |
2163 | care, as they may conflict with file descriptors the shell uses inter- | |
17345e5a JA |
2164 | nally. |
2165 | ||
2166 | R\bRe\bed\bdi\bir\bre\bec\bct\bti\bin\bng\bg I\bIn\bnp\bpu\but\bt | |
2167 | Redirection of input causes the file whose name results from the expan- | |
712f80b0 | 2168 | sion of _\bw_\bo_\br_\bd to be opened for reading on file descriptor _\bn, or the |
17345e5a JA |
2169 | standard input (file descriptor 0) if _\bn is not specified. |
2170 | ||
2171 | The general format for redirecting input is: | |
2172 | ||
2173 | [_\bn]<\b<_\bw_\bo_\br_\bd | |
2174 | ||
2175 | R\bRe\bed\bdi\bir\bre\bec\bct\bti\bin\bng\bg O\bOu\but\btp\bpu\but\bt | |
712f80b0 CR |
2176 | Redirection of output causes the file whose name results from the ex- |
2177 | pansion of _\bw_\bo_\br_\bd to be opened for writing on file descriptor _\bn, or the | |
17345e5a | 2178 | standard output (file descriptor 1) if _\bn is not specified. If the file |
712f80b0 | 2179 | does not exist it is created; if it does exist it is truncated to zero |
17345e5a JA |
2180 | size. |
2181 | ||
2182 | The general format for redirecting output is: | |
2183 | ||
2184 | [_\bn]>\b>_\bw_\bo_\br_\bd | |
2185 | ||
712f80b0 CR |
2186 | 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 |
2187 | builtin has been enabled, the redirection will fail if the file whose | |
2188 | name results from the expansion of _\bw_\bo_\br_\bd exists and is a regular file. | |
17345e5a JA |
2189 | If the redirection operator is >\b>|\b|, or the redirection operator is >\b> and |
2190 | 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- | |
2191 | direction is attempted even if the file named by _\bw_\bo_\br_\bd exists. | |
2192 | ||
2193 | 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 | |
712f80b0 CR |
2194 | Redirection of output in this fashion causes the file whose name re- |
2195 | sults from the expansion of _\bw_\bo_\br_\bd to be opened for appending on file de- | |
2196 | scriptor _\bn, or the standard output (file descriptor 1) if _\bn is not | |
17345e5a JA |
2197 | specified. If the file does not exist it is created. |
2198 | ||
2199 | The general format for appending output is: | |
2200 | ||
2201 | [_\bn]>\b>>\b>_\bw_\bo_\br_\bd | |
2202 | ||
17345e5a | 2203 | 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 |
712f80b0 CR |
2204 | This construct allows both the standard output (file descriptor 1) and |
2205 | the standard error output (file descriptor 2) to be redirected to the | |
17345e5a JA |
2206 | file whose name is the expansion of _\bw_\bo_\br_\bd. |
2207 | ||
712f80b0 CR |
2208 | There are two formats for redirecting standard output and standard er- |
2209 | ror: | |
17345e5a JA |
2210 | |
2211 | &\b&>\b>_\bw_\bo_\br_\bd | |
2212 | and | |
2213 | >\b>&\b&_\bw_\bo_\br_\bd | |
2214 | ||
2215 | Of the two forms, the first is preferred. This is semantically equiva- | |
2216 | lent to | |
2217 | ||
2218 | >\b>_\bw_\bo_\br_\bd 2>\b>&\b&1 | |
2219 | ||
712f80b0 CR |
2220 | When using the second form, _\bw_\bo_\br_\bd may not expand to a number or -\b-. If |
2221 | 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- | |
2222 | s\bsc\bcr\bri\bip\bpt\bto\bor\brs\bs below) for compatibility reasons. | |
17345e5a JA |
2223 | |
2224 | 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 | |
712f80b0 CR |
2225 | This construct allows both the standard output (file descriptor 1) and |
2226 | the standard error output (file descriptor 2) to be appended to the | |
17345e5a JA |
2227 | file whose name is the expansion of _\bw_\bo_\br_\bd. |
2228 | ||
2229 | The format for appending standard output and standard error is: | |
2230 | ||
2231 | &\b&>\b>>\b>_\bw_\bo_\br_\bd | |
2232 | ||
2233 | This is semantically equivalent to | |
2234 | ||
2235 | >\b>>\b>_\bw_\bo_\br_\bd 2>\b>&\b&1 | |
2236 | ||
ac50fbac CR |
2237 | (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). |
2238 | ||
17345e5a | 2239 | H\bHe\ber\bre\be D\bDo\boc\bcu\bum\bme\ben\bnt\bts\bs |
712f80b0 | 2240 | This type of redirection instructs the shell to read input from the |
17345e5a | 2241 | current source until a line containing only _\bd_\be_\bl_\bi_\bm_\bi_\bt_\be_\br (with no trailing |
712f80b0 CR |
2242 | blanks) is seen. All of the lines read up to that point are then used |
2243 | as the standard input (or file descriptor _\bn if _\bn is specified) for a | |
a0c0a00f | 2244 | command. |
17345e5a JA |
2245 | |
2246 | The format of here-documents is: | |
2247 | ||
a0c0a00f | 2248 | [_\bn]<\b<<\b<[-\b-]_\bw_\bo_\br_\bd |
17345e5a JA |
2249 | _\bh_\be_\br_\be_\b-_\bd_\bo_\bc_\bu_\bm_\be_\bn_\bt |
2250 | _\bd_\be_\bl_\bi_\bm_\bi_\bt_\be_\br | |
2251 | ||
712f80b0 CR |
2252 | No parameter and variable expansion, command substitution, arithmetic |
2253 | expansion, or pathname expansion is performed on _\bw_\bo_\br_\bd. If any part of | |
2254 | _\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, | |
2255 | and the lines in the here-document are not expanded. If _\bw_\bo_\br_\bd is un- | |
2256 | quoted, all lines of the here-document are subjected to parameter ex- | |
2257 | pansion, command substitution, and arithmetic expansion, the character | |
2258 | sequence \\b\<\b<n\bne\bew\bwl\bli\bin\bne\be>\b> is ignored, and \\b\ must be used to quote the charac- | |
2259 | ters \\b\, $\b$, and `\b`. | |
17345e5a JA |
2260 | |
2261 | If the redirection operator is <\b<<\b<-\b-, then all leading tab characters are | |
712f80b0 CR |
2262 | stripped from input lines and the line containing _\bd_\be_\bl_\bi_\bm_\bi_\bt_\be_\br. This al- |
2263 | lows here-documents within shell scripts to be indented in a natural | |
17345e5a JA |
2264 | fashion. |
2265 | ||
2266 | H\bHe\ber\bre\be S\bSt\btr\bri\bin\bng\bgs\bs | |
2267 | A variant of here documents, the format is: | |
2268 | ||
a0c0a00f | 2269 | [_\bn]<\b<<\b<<\b<_\bw_\bo_\br_\bd |
17345e5a | 2270 | |
712f80b0 CR |
2271 | The _\bw_\bo_\br_\bd undergoes tilde expansion, parameter and variable expansion, |
2272 | command substitution, arithmetic expansion, and quote removal. Path- | |
2273 | name expansion and word splitting are not performed. The result is | |
d233b485 CR |
2274 | supplied as a single string, with a newline appended, to the command on |
2275 | its standard input (or file descriptor _\bn if _\bn is specified). | |
17345e5a JA |
2276 | |
2277 | 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 | |
2278 | The redirection operator | |
2279 | ||
2280 | [_\bn]<\b<&\b&_\bw_\bo_\br_\bd | |
2281 | ||
2282 | is used to duplicate input file descriptors. If _\bw_\bo_\br_\bd expands to one or | |
712f80b0 CR |
2283 | more digits, the file descriptor denoted by _\bn is made to be a copy of |
2284 | that file descriptor. If the digits in _\bw_\bo_\br_\bd do not specify a file de- | |
2285 | scriptor open for input, a redirection error occurs. If _\bw_\bo_\br_\bd evaluates | |
2286 | to -\b-, file descriptor _\bn is closed. If _\bn is not specified, the standard | |
2287 | input (file descriptor 0) is used. | |
17345e5a JA |
2288 | |
2289 | The operator | |
2290 | ||
2291 | [_\bn]>\b>&\b&_\bw_\bo_\br_\bd | |
2292 | ||
712f80b0 CR |
2293 | is used similarly to duplicate output file descriptors. If _\bn is not |
2294 | specified, the standard output (file descriptor 1) is used. If the | |
2295 | digits in _\bw_\bo_\br_\bd do not specify a file descriptor open for output, a re- | |
2296 | direction error occurs. If _\bw_\bo_\br_\bd evaluates to -\b-, file descriptor _\bn is | |
2297 | closed. As a special case, if _\bn is omitted, and _\bw_\bo_\br_\bd does not expand | |
2298 | to one or more digits or -\b-, the standard output and standard error are | |
ac50fbac | 2299 | redirected as described previously. |
17345e5a JA |
2300 | |
2301 | M\bMo\bov\bvi\bin\bng\bg F\bFi\bil\ble\be D\bDe\bes\bsc\bcr\bri\bip\bpt\bto\bor\brs\bs | |
2302 | The redirection operator | |
2303 | ||
2304 | [_\bn]<\b<&\b&_\bd_\bi_\bg_\bi_\bt-\b- | |
2305 | ||
712f80b0 | 2306 | moves the file descriptor _\bd_\bi_\bg_\bi_\bt to file descriptor _\bn, or the standard |
17345e5a JA |
2307 | input (file descriptor 0) if _\bn is not specified. _\bd_\bi_\bg_\bi_\bt is closed after |
2308 | being duplicated to _\bn. | |
2309 | ||
2310 | Similarly, the redirection operator | |
2311 | ||
2312 | [_\bn]>\b>&\b&_\bd_\bi_\bg_\bi_\bt-\b- | |
2313 | ||
712f80b0 | 2314 | moves the file descriptor _\bd_\bi_\bg_\bi_\bt to file descriptor _\bn, or the standard |
17345e5a JA |
2315 | output (file descriptor 1) if _\bn is not specified. |
2316 | ||
2317 | 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 | |
2318 | The redirection operator | |
2319 | ||
2320 | [_\bn]<\b<>\b>_\bw_\bo_\br_\bd | |
2321 | ||
712f80b0 CR |
2322 | causes the file whose name is the expansion of _\bw_\bo_\br_\bd to be opened for |
2323 | both reading and writing on file descriptor _\bn, or on file descriptor 0 | |
17345e5a JA |
2324 | if _\bn is not specified. If the file does not exist, it is created. |
2325 | ||
2326 | A\bAL\bLI\bIA\bAS\bSE\bES\bS | |
712f80b0 CR |
2327 | _\bA_\bl_\bi_\ba_\bs_\be_\bs allow a string to be substituted for a word when it is used as |
2328 | the first word of a simple command. The shell maintains a list of | |
2329 | 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 | |
2330 | 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 | |
2331 | simple command, if unquoted, is checked to see if it has an alias. If | |
2332 | so, that word is replaced by the text of the alias. The characters /\b/, | |
2333 | $\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 | 2334 | listed above may not appear in an alias name. The replacement text may |
712f80b0 CR |
2335 | contain any valid shell input, including shell metacharacters. The |
2336 | first word of the replacement text is tested for aliases, but a word | |
2337 | that is identical to an alias being expanded is not expanded a second | |
2338 | time. This means that one may alias l\bls\bs to l\bls\bs -\b-F\bF, for instance, and | |
2339 | b\bba\bas\bsh\bh does not try to recursively expand the replacement text. If the | |
2340 | last character of the alias value is a _\bb_\bl_\ba_\bn_\bk, then the next command | |
17345e5a JA |
2341 | word following the alias is also checked for alias expansion. |
2342 | ||
2343 | Aliases are created and listed with the a\bal\bli\bia\bas\bs command, and removed with | |
2344 | the u\bun\bna\bal\bli\bia\bas\bs command. | |
2345 | ||
712f80b0 CR |
2346 | There is no mechanism for using arguments in the replacement text. If |
2347 | arguments are needed, a shell function should be used (see F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS | |
17345e5a JA |
2348 | below). |
2349 | ||
712f80b0 CR |
2350 | Aliases are not expanded when the shell is not interactive, unless the |
2351 | 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 |
2352 | 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). |
2353 | ||
712f80b0 CR |
2354 | The rules concerning the definition and use of aliases are somewhat |
2355 | confusing. B\bBa\bas\bsh\bh always reads at least one complete line of input, and | |
2356 | all lines that make up a compound command, before executing any of the | |
2357 | commands on that line or the compound command. Aliases are expanded | |
2358 | when a command is read, not when it is executed. Therefore, an alias | |
2359 | definition appearing on the same line as another command does not take | |
2360 | effect until the next line of input is read. The commands following | |
2361 | the alias definition on that line are not affected by the new alias. | |
2362 | This behavior is also an issue when functions are executed. Aliases | |
2363 | are expanded when a function definition is read, not when the function | |
2364 | is executed, because a function definition is itself a command. As a | |
2365 | consequence, aliases defined in a function are not available until af- | |
2366 | ter that function is executed. To be safe, always put alias defini- | |
d233b485 | 2367 | tions on a separate line, and do not use a\bal\bli\bia\bas\bs in compound commands. |
17345e5a JA |
2368 | |
2369 | For almost every purpose, aliases are superseded by shell functions. | |
2370 | ||
2371 | F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS | |
712f80b0 CR |
2372 | A shell function, defined as described above under S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR, |
2373 | stores a series of commands for later execution. When the name of a | |
2374 | shell function is used as a simple command name, the list of commands | |
17345e5a | 2375 | associated with that function name is executed. Functions are executed |
712f80b0 CR |
2376 | in the context of the current shell; no new process is created to in- |
2377 | terpret them (contrast this with the execution of a shell script). | |
2378 | When a function is executed, the arguments to the function become the | |
17345e5a | 2379 | positional parameters during its execution. The special parameter #\b# is |
712f80b0 CR |
2380 | updated to reflect the change. Special parameter 0\b0 is unchanged. The |
2381 | first element of the F\bFU\bUN\bNC\bCN\bNA\bAM\bME\bE variable is set to the name of the func- | |
0001803f CR |
2382 | tion while the function is executing. |
2383 | ||
712f80b0 CR |
2384 | All other aspects of the shell execution environment are identical be- |
2385 | tween a function and its caller with these exceptions: the D\bDE\bEB\bBU\bUG\bG and | |
2386 | 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 | |
2387 | 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 | |
2388 | given the t\btr\bra\bac\bce\be attribute (see the description of the d\bde\bec\bcl\bla\bar\bre\be builtin | |
2389 | 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 | |
2390 | builtin (in which case all functions inherit the D\bDE\bEB\bBU\bUG\bG and R\bRE\bET\bTU\bUR\bRN\bN | |
2391 | 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 | 2392 | option has been enabled. |
17345e5a | 2393 | |
712f80b0 | 2394 | Variables local to the function may be declared with the l\blo\boc\bca\bal\bl builtin |
17345e5a | 2395 | command. Ordinarily, variables and their values are shared between the |
712f80b0 CR |
2396 | function and its caller. If a variable is declared l\blo\boc\bca\bal\bl, the vari- |
2397 | able's visible scope is restricted to that function and its children | |
d233b485 | 2398 | (including the functions it calls). Local variables "shadow" variables |
712f80b0 CR |
2399 | with the same name declared at previous scopes. For instance, a local |
2400 | variable declared in a function hides a global variable of the same | |
2401 | name: references and assignments refer to the local variable, leaving | |
2402 | the global variable unmodified. When the function returns, the global | |
d233b485 CR |
2403 | variable is once again visible. |
2404 | ||
712f80b0 CR |
2405 | The shell uses _\bd_\by_\bn_\ba_\bm_\bi_\bc _\bs_\bc_\bo_\bp_\bi_\bn_\bg to control a variable's visibility |
2406 | within functions. With dynamic scoping, visible variables and their | |
2407 | values are a result of the sequence of function calls that caused exe- | |
2408 | cution to reach the current function. The value of a variable that a | |
2409 | function sees depends on its value within its caller, if any, whether | |
2410 | that caller is the "global" scope or another shell function. This is | |
2411 | also the value that a local variable declaration "shadows", and the | |
d233b485 CR |
2412 | value that is restored when the function returns. |
2413 | ||
712f80b0 CR |
2414 | For example, if a variable _\bv_\ba_\br is declared as local in function _\bf_\bu_\bn_\bc_\b1, |
2415 | and _\bf_\bu_\bn_\bc_\b1 calls another function _\bf_\bu_\bn_\bc_\b2, references to _\bv_\ba_\br made from | |
d233b485 CR |
2416 | within _\bf_\bu_\bn_\bc_\b2 will resolve to the local variable _\bv_\ba_\br from _\bf_\bu_\bn_\bc_\b1, shadow- |
2417 | ing any global variable named _\bv_\ba_\br. | |
2418 | ||
2419 | The u\bun\bns\bse\bet\bt builtin also acts using the same dynamic scope: if a variable | |
2420 | is local to the current scope, u\bun\bns\bse\bet\bt will unset it; otherwise the unset | |
712f80b0 CR |
2421 | will refer to the variable found in any calling scope as described |
2422 | above. If a variable at the current local scope is unset, it will re- | |
2423 | main so until it is reset in that scope or until the function returns. | |
2424 | Once the function returns, any instance of the variable at a previous | |
2425 | scope will become visible. If the unset acts on a variable at a previ- | |
2426 | ous scope, any instance of a variable with that name that had been | |
2427 | shadowed will become visible. | |
2428 | ||
2429 | The F\bFU\bUN\bNC\bCN\bNE\bES\bST\bT variable, if set to a numeric value greater than 0, de- | |
2430 | fines a maximum function nesting level. Function invocations that ex- | |
2431 | ceed the limit cause the entire command to abort. | |
2432 | ||
2433 | If the builtin command r\bre\bet\btu\bur\brn\bn is executed in a function, the function | |
2434 | completes and execution resumes with the next command after the func- | |
2435 | tion call. Any command associated with the R\bRE\bET\bTU\bUR\bRN\bN trap is executed be- | |
2436 | fore execution resumes. When a function completes, the values of the | |
2437 | positional parameters and the special parameter #\b# are restored to the | |
17345e5a JA |
2438 | values they had prior to the function's execution. |
2439 | ||
712f80b0 | 2440 | Function names and definitions may be listed with the -\b-f\bf option to the |
17345e5a | 2441 | 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- |
712f80b0 CR |
2442 | s\bse\bet\bt will list the function names only (and optionally the source file |
2443 | and line number, if the e\bex\bxt\btd\bde\beb\bbu\bug\bg shell option is enabled). Functions | |
2444 | may be exported so that subshells automatically have them defined with | |
2445 | the -\b-f\bf option to the e\bex\bxp\bpo\bor\brt\bt builtin. A function definition may be | |
d233b485 | 2446 | deleted using the -\b-f\bf option to the u\bun\bns\bse\bet\bt builtin. |
17345e5a | 2447 | |
495aee44 | 2448 | Functions may be recursive. The F\bFU\bUN\bNC\bCN\bNE\bES\bST\bT variable may be used to limit |
712f80b0 CR |
2449 | the depth of the function call stack and restrict the number of func- |
2450 | tion invocations. By default, no limit is imposed on the number of re- | |
2451 | cursive calls. | |
17345e5a JA |
2452 | |
2453 | A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN | |
712f80b0 CR |
2454 | The shell allows arithmetic expressions to be evaluated, under certain |
2455 | circumstances (see the l\ble\bet\bt and d\bde\bec\bcl\bla\bar\bre\be builtin commands, the (\b((\b( com- | |
a0c0a00f | 2456 | 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- |
712f80b0 CR |
2457 | width integers with no check for overflow, though division by 0 is |
2458 | trapped and flagged as an error. The operators and their precedence, | |
2459 | associativity, and values are the same as in the C language. The fol- | |
2460 | lowing list of operators is grouped into levels of equal-precedence op- | |
2461 | erators. The levels are listed in order of decreasing precedence. | |
17345e5a JA |
2462 | |
2463 | _\bi_\bd+\b++\b+ _\bi_\bd-\b--\b- | |
2464 | variable post-increment and post-decrement | |
d233b485 | 2465 | -\b- +\b+ unary minus and plus |
17345e5a JA |
2466 | +\b++\b+_\bi_\bd -\b--\b-_\bi_\bd |
2467 | variable pre-increment and pre-decrement | |
17345e5a JA |
2468 | !\b! ~\b~ logical and bitwise negation |
2469 | *\b**\b* exponentiation | |
2470 | *\b* /\b/ %\b% multiplication, division, remainder | |
2471 | +\b+ -\b- addition, subtraction | |
2472 | <\b<<\b< >\b>>\b> left and right bitwise shifts | |
2473 | <\b<=\b= >\b>=\b= <\b< >\b> | |
2474 | comparison | |
2475 | =\b==\b= !\b!=\b= equality and inequality | |
2476 | &\b& bitwise AND | |
2477 | ^\b^ bitwise exclusive OR | |
2478 | |\b| bitwise OR | |
2479 | &\b&&\b& logical AND | |
2480 | |\b||\b| logical OR | |
2481 | _\be_\bx_\bp_\br?\b?_\be_\bx_\bp_\br:\b:_\be_\bx_\bp_\br | |
2482 | conditional operator | |
2483 | =\b= *\b*=\b= /\b/=\b= %\b%=\b= +\b+=\b= -\b-=\b= <\b<<\b<=\b= >\b>>\b>=\b= &\b&=\b= ^\b^=\b= |\b|=\b= | |
2484 | assignment | |
2485 | _\be_\bx_\bp_\br_\b1 ,\b, _\be_\bx_\bp_\br_\b2 | |
2486 | comma | |
2487 | ||
712f80b0 | 2488 | Shell variables are allowed as operands; parameter expansion is per- |
17345e5a | 2489 | formed before the expression is evaluated. Within an expression, shell |
712f80b0 CR |
2490 | variables may also be referenced by name without using the parameter |
2491 | expansion syntax. A shell variable that is null or unset evaluates to | |
17345e5a | 2492 | 0 when referenced by name without using the parameter expansion syntax. |
712f80b0 CR |
2493 | The value of a variable is evaluated as an arithmetic expression when |
2494 | it is referenced, or when a variable which has been given the _\bi_\bn_\bt_\be_\bg_\be_\br | |
17345e5a | 2495 | attribute using d\bde\bec\bcl\bla\bar\bre\be -\b-i\bi is assigned a value. A null value evaluates |
712f80b0 | 2496 | to 0. A shell variable need not have its _\bi_\bn_\bt_\be_\bg_\be_\br attribute turned on |
17345e5a JA |
2497 | to be used in an expression. |
2498 | ||
712f80b0 CR |
2499 | Integer constants follow the C language definition, without suffixes or |
2500 | character constants. Constants with a leading 0 are interpreted as oc- | |
2501 | tal numbers. A leading 0x or 0X denotes hexadecimal. Otherwise, num- | |
2502 | bers take the form [_\bb_\ba_\bs_\be_\b#]n, where the optional _\bb_\ba_\bs_\be is a decimal num- | |
2503 | ber between 2 and 64 representing the arithmetic base, and _\bn is a num- | |
2504 | ber in that base. If _\bb_\ba_\bs_\be_\b# is omitted, then base 10 is used. When | |
2505 | specifying _\bn, if a non-digit is required, the digits greater than 9 are | |
2506 | represented by the lowercase letters, the uppercase letters, @, and _, | |
2507 | in that order. If _\bb_\ba_\bs_\be is less than or equal to 36, lowercase and up- | |
2508 | percase letters may be used interchangeably to represent numbers be- | |
2509 | tween 10 and 35. | |
2510 | ||
2511 | Operators are evaluated in order of precedence. Sub-expressions in | |
2512 | parentheses are evaluated first and may override the precedence rules | |
17345e5a JA |
2513 | above. |
2514 | ||
2515 | C\bCO\bON\bND\bDI\bIT\bTI\bIO\bON\bNA\bAL\bL E\bEX\bXP\bPR\bRE\bES\bSS\bSI\bIO\bON\bNS\bS | |
712f80b0 CR |
2516 | Conditional expressions are used by the [\b[[\b[ compound command and the |
2517 | t\bte\bes\bst\bt and [\b[ builtin commands to test file attributes and perform string | |
2518 | and arithmetic comparisons. The t\bte\bes\bst\bt and [\b[ commands determine their | |
2519 | behavior based on the number of arguments; see the descriptions of | |
d233b485 CR |
2520 | those commands for any other command-specific actions. |
2521 | ||
712f80b0 CR |
2522 | Expressions are formed from the following unary or binary primaries. |
2523 | B\bBa\bas\bsh\bh handles several filenames specially when they are used in expres- | |
d233b485 | 2524 | sions. If the operating system on which b\bba\bas\bsh\bh is running provides these |
712f80b0 CR |
2525 | special files, bash will use them; otherwise it will emulate them in- |
2526 | ternally with this behavior: If any _\bf_\bi_\bl_\be argument to one of the pri- | |
d233b485 | 2527 | maries is of the form _\b/_\bd_\be_\bv_\b/_\bf_\bd_\b/_\bn, then file descriptor _\bn is checked. If |
712f80b0 CR |
2528 | the _\bf_\bi_\bl_\be argument to one of the primaries is one of _\b/_\bd_\be_\bv_\b/_\bs_\bt_\bd_\bi_\bn, |
2529 | _\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 | 2530 | is checked. |
17345e5a JA |
2531 | |
2532 | Unless otherwise specified, primaries that operate on files follow sym- | |
2533 | bolic links and operate on the target of the link, rather than the link | |
2534 | itself. | |
2535 | ||
712f80b0 | 2536 | When used with [\b[[\b[, the <\b< and >\b> operators sort lexicographically using |
495aee44 | 2537 | the current locale. The t\bte\bes\bst\bt command sorts using ASCII ordering. |
0001803f | 2538 | |
17345e5a JA |
2539 | -\b-a\ba _\bf_\bi_\bl_\be |
2540 | True if _\bf_\bi_\bl_\be exists. | |
2541 | -\b-b\bb _\bf_\bi_\bl_\be | |
2542 | True if _\bf_\bi_\bl_\be exists and is a block special file. | |
2543 | -\b-c\bc _\bf_\bi_\bl_\be | |
2544 | True if _\bf_\bi_\bl_\be exists and is a character special file. | |
2545 | -\b-d\bd _\bf_\bi_\bl_\be | |
2546 | True if _\bf_\bi_\bl_\be exists and is a directory. | |
2547 | -\b-e\be _\bf_\bi_\bl_\be | |
2548 | True if _\bf_\bi_\bl_\be exists. | |
2549 | -\b-f\bf _\bf_\bi_\bl_\be | |
2550 | True if _\bf_\bi_\bl_\be exists and is a regular file. | |
2551 | -\b-g\bg _\bf_\bi_\bl_\be | |
2552 | True if _\bf_\bi_\bl_\be exists and is set-group-id. | |
2553 | -\b-h\bh _\bf_\bi_\bl_\be | |
2554 | True if _\bf_\bi_\bl_\be exists and is a symbolic link. | |
2555 | -\b-k\bk _\bf_\bi_\bl_\be | |
2556 | True if _\bf_\bi_\bl_\be exists and its ``sticky'' bit is set. | |
2557 | -\b-p\bp _\bf_\bi_\bl_\be | |
2558 | True if _\bf_\bi_\bl_\be exists and is a named pipe (FIFO). | |
2559 | -\b-r\br _\bf_\bi_\bl_\be | |
2560 | True if _\bf_\bi_\bl_\be exists and is readable. | |
2561 | -\b-s\bs _\bf_\bi_\bl_\be | |
2562 | True if _\bf_\bi_\bl_\be exists and has a size greater than zero. | |
2563 | -\b-t\bt _\bf_\bd True if file descriptor _\bf_\bd is open and refers to a terminal. | |
2564 | -\b-u\bu _\bf_\bi_\bl_\be | |
2565 | True if _\bf_\bi_\bl_\be exists and its set-user-id bit is set. | |
2566 | -\b-w\bw _\bf_\bi_\bl_\be | |
2567 | True if _\bf_\bi_\bl_\be exists and is writable. | |
2568 | -\b-x\bx _\bf_\bi_\bl_\be | |
2569 | True if _\bf_\bi_\bl_\be exists and is executable. | |
17345e5a JA |
2570 | -\b-G\bG _\bf_\bi_\bl_\be |
2571 | True if _\bf_\bi_\bl_\be exists and is owned by the effective group id. | |
2572 | -\b-L\bL _\bf_\bi_\bl_\be | |
2573 | True if _\bf_\bi_\bl_\be exists and is a symbolic link. | |
17345e5a | 2574 | -\b-N\bN _\bf_\bi_\bl_\be |
712f80b0 | 2575 | True if _\bf_\bi_\bl_\be exists and has been modified since it was last |
17345e5a | 2576 | read. |
495aee44 CR |
2577 | -\b-O\bO _\bf_\bi_\bl_\be |
2578 | True if _\bf_\bi_\bl_\be exists and is owned by the effective user id. | |
2579 | -\b-S\bS _\bf_\bi_\bl_\be | |
2580 | True if _\bf_\bi_\bl_\be exists and is a socket. | |
2581 | _\bf_\bi_\bl_\be_\b1 -\b-e\bef\bf _\bf_\bi_\bl_\be_\b2 | |
712f80b0 | 2582 | True if _\bf_\bi_\bl_\be_\b1 and _\bf_\bi_\bl_\be_\b2 refer to the same device and inode num- |
495aee44 | 2583 | bers. |
17345e5a | 2584 | _\bf_\bi_\bl_\be_\b1 -n\bnt\bt _\bf_\bi_\bl_\be_\b2 |
712f80b0 | 2585 | True if _\bf_\bi_\bl_\be_\b1 is newer (according to modification date) than |
17345e5a JA |
2586 | _\bf_\bi_\bl_\be_\b2, or if _\bf_\bi_\bl_\be_\b1 exists and _\bf_\bi_\bl_\be_\b2 does not. |
2587 | _\bf_\bi_\bl_\be_\b1 -o\bot\bt _\bf_\bi_\bl_\be_\b2 | |
712f80b0 | 2588 | 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 | 2589 | does not. |
17345e5a | 2590 | -\b-o\bo _\bo_\bp_\bt_\bn_\ba_\bm_\be |
712f80b0 CR |
2591 | True if the shell option _\bo_\bp_\bt_\bn_\ba_\bm_\be is enabled. See the list of |
2592 | options under the description of the -\b-o\bo option to the s\bse\bet\bt | |
17345e5a | 2593 | builtin below. |
495aee44 | 2594 | -\b-v\bv _\bv_\ba_\br_\bn_\ba_\bm_\be |
712f80b0 | 2595 | True if the shell variable _\bv_\ba_\br_\bn_\ba_\bm_\be is set (has been assigned a |
495aee44 | 2596 | value). |
ac50fbac | 2597 | -\b-R\bR _\bv_\ba_\br_\bn_\ba_\bm_\be |
712f80b0 | 2598 | True if the shell variable _\bv_\ba_\br_\bn_\ba_\bm_\be is set and is a name refer- |
ac50fbac | 2599 | ence. |
17345e5a JA |
2600 | -\b-z\bz _\bs_\bt_\br_\bi_\bn_\bg |
2601 | True if the length of _\bs_\bt_\br_\bi_\bn_\bg is zero. | |
2602 | _\bs_\bt_\br_\bi_\bn_\bg | |
2603 | -\b-n\bn _\bs_\bt_\br_\bi_\bn_\bg | |
2604 | True if the length of _\bs_\bt_\br_\bi_\bn_\bg is non-zero. | |
2605 | ||
2606 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 =\b==\b= _\bs_\bt_\br_\bi_\bn_\bg_\b2 | |
0001803f | 2607 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 =\b= _\bs_\bt_\br_\bi_\bn_\bg_\b2 |
712f80b0 CR |
2608 | True if the strings are equal. =\b= should be used with the t\bte\bes\bst\bt |
2609 | command for POSIX conformance. When used with the [\b[[\b[ command, | |
ac50fbac CR |
2610 | this performs pattern matching as described above (C\bCo\bom\bmp\bpo\bou\bun\bnd\bd C\bCo\bom\bm-\b- |
2611 | m\bma\ban\bnd\bds\bs). | |
17345e5a JA |
2612 | |
2613 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 !\b!=\b= _\bs_\bt_\br_\bi_\bn_\bg_\b2 | |
2614 | True if the strings are not equal. | |
2615 | ||
2616 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 <\b< _\bs_\bt_\br_\bi_\bn_\bg_\b2 | |
0001803f | 2617 | True if _\bs_\bt_\br_\bi_\bn_\bg_\b1 sorts before _\bs_\bt_\br_\bi_\bn_\bg_\b2 lexicographically. |
17345e5a JA |
2618 | |
2619 | _\bs_\bt_\br_\bi_\bn_\bg_\b1 >\b> _\bs_\bt_\br_\bi_\bn_\bg_\b2 | |
0001803f | 2620 | True if _\bs_\bt_\br_\bi_\bn_\bg_\b1 sorts after _\bs_\bt_\br_\bi_\bn_\bg_\b2 lexicographically. |
17345e5a JA |
2621 | |
2622 | _\ba_\br_\bg_\b1 O\bOP\bP _\ba_\br_\bg_\b2 | |
712f80b0 CR |
2623 | 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 |
2624 | binary operators return true if _\ba_\br_\bg_\b1 is equal to, not equal to, | |
2625 | less than, less than or equal to, greater than, or greater than | |
2626 | or equal to _\ba_\br_\bg_\b2, respectively. _\bA_\br_\bg_\b1 and _\ba_\br_\bg_\b2 may be positive | |
2627 | or negative integers. When used with the [\b[[\b[ command, _\bA_\br_\bg_\b1 and | |
2628 | _\bA_\br_\bg_\b2 are evaluated as arithmetic expressions (see A\bAR\bRI\bIT\bTH\bHM\bME\bET\bTI\bIC\bC | |
d233b485 | 2629 | E\bEV\bVA\bAL\bLU\bUA\bAT\bTI\bIO\bON\bN above). |
17345e5a JA |
2630 | |
2631 | 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 | |
712f80b0 CR |
2632 | When a simple command is executed, the shell performs the following ex- |
2633 | pansions, assignments, and redirections, from left to right, in the | |
2634 | following order. | |
17345e5a | 2635 | |
0001803f CR |
2636 | 1. The words that the parser has marked as variable assignments |
2637 | (those preceding the command name) and redirections are saved | |
17345e5a JA |
2638 | for later processing. |
2639 | ||
0001803f CR |
2640 | 2. The words that are not variable assignments or redirections are |
2641 | expanded. If any words remain after expansion, the first word | |
2642 | is taken to be the name of the command and the remaining words | |
17345e5a JA |
2643 | are the arguments. |
2644 | ||
2645 | 3. Redirections are performed as described above under R\bRE\bED\bDI\bIR\bRE\bEC\bCT\bTI\bIO\bON\bN. | |
2646 | ||
2647 | 4. The text after the =\b= in each variable assignment undergoes tilde | |
2648 | expansion, parameter expansion, command substitution, arithmetic | |
a0c0a00f | 2649 | expansion, and quote removal before being assigned to the vari- |
17345e5a JA |
2650 | able. |
2651 | ||
2652 | If no command name results, the variable assignments affect the current | |
a0c0a00f CR |
2653 | shell environment. Otherwise, the variables are added to the environ- |
2654 | ment of the executed command and do not affect the current shell envi- | |
2655 | ronment. If any of the assignments attempts to assign a value to a | |
2656 | readonly variable, an error occurs, and the command exits with a non- | |
17345e5a JA |
2657 | zero status. |
2658 | ||
712f80b0 CR |
2659 | If no command name results, redirections are performed, but do not af- |
2660 | fect the current shell environment. A redirection error causes the | |
17345e5a JA |
2661 | command to exit with a non-zero status. |
2662 | ||
a0c0a00f CR |
2663 | If there is a command name left after expansion, execution proceeds as |
2664 | described below. Otherwise, the command exits. If one of the expan- | |
2665 | sions contained a command substitution, the exit status of the command | |
2666 | is the exit status of the last command substitution performed. If | |
17345e5a JA |
2667 | there were no command substitutions, the command exits with a status of |
2668 | zero. | |
2669 | ||
2670 | C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN | |
a0c0a00f CR |
2671 | After a command has been split into words, if it results in a simple |
2672 | command and an optional list of arguments, the following actions are | |
17345e5a JA |
2673 | taken. |
2674 | ||
a0c0a00f CR |
2675 | If the command name contains no slashes, the shell attempts to locate |
2676 | it. If there exists a shell function by that name, that function is | |
2677 | invoked as described above in F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS. If the name does not match a | |
2678 | function, the shell searches for it in the list of shell builtins. If | |
17345e5a JA |
2679 | a match is found, that builtin is invoked. |
2680 | ||
a0c0a00f CR |
2681 | If the name is neither a shell function nor a builtin, and contains no |
2682 | slashes, b\bba\bas\bsh\bh searches each element of the P\bPA\bAT\bTH\bH for a directory con- | |
712f80b0 CR |
2683 | taining an executable file by that name. B\bBa\bas\bsh\bh uses a hash table to re- |
2684 | member the full pathnames of executable files (see h\bha\bas\bsh\bh under S\bSH\bHE\bEL\bLL\bL | |
a0c0a00f CR |
2685 | 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 |
2686 | performed only if the command is not found in the hash table. If the | |
17345e5a JA |
2687 | search is unsuccessful, the shell searches for a defined shell function |
2688 | 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 | |
d233b485 CR |
2689 | in a separate execution environment with the original command and the |
2690 | original command's arguments as its arguments, and the function's exit | |
2691 | status becomes the exit status of that subshell. If that function is | |
2692 | not defined, the shell prints an error message and returns an exit sta- | |
2693 | tus of 127. | |
17345e5a | 2694 | |
d233b485 | 2695 | If the search is successful, or if the command name contains one or |
17345e5a JA |
2696 | more slashes, the shell executes the named program in a separate execu- |
2697 | tion environment. Argument 0 is set to the name given, and the remain- | |
2698 | ing arguments to the command are set to the arguments given, if any. | |
2699 | ||
d233b485 CR |
2700 | If this execution fails because the file is not in executable format, |
2701 | 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 | |
2702 | file containing shell commands. A subshell is spawned to execute it. | |
2703 | This subshell reinitializes itself, so that the effect is as if a new | |
2704 | shell had been invoked to handle the script, with the exception that | |
712f80b0 CR |
2705 | the locations of commands remembered by the parent (see h\bha\bas\bsh\bh below un- |
2706 | der 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 child. | |
17345e5a | 2707 | |
d233b485 CR |
2708 | If the program is a file beginning with #\b#!\b!, the remainder of the first |
2709 | line specifies an interpreter for the program. The shell executes the | |
17345e5a JA |
2710 | specified interpreter on operating systems that do not handle this exe- |
2711 | cutable format themselves. The arguments to the interpreter consist of | |
d233b485 CR |
2712 | a single optional argument following the interpreter name on the first |
2713 | line of the program, followed by the name of the program, followed by | |
17345e5a JA |
2714 | the command arguments, if any. |
2715 | ||
2716 | 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 | 2717 | 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 |
2718 | ing: |
2719 | ||
d233b485 | 2720 | +\bo open files inherited by the shell at invocation, as modified by |
17345e5a JA |
2721 | redirections supplied to the e\bex\bxe\bec\bc builtin |
2722 | ||
d233b485 | 2723 | +\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 |
2724 | inherited by the shell at invocation |
2725 | ||
d233b485 | 2726 | +\bo the file creation mode mask as set by u\bum\bma\bas\bsk\bk or inherited from |
17345e5a JA |
2727 | the shell's parent |
2728 | ||
2729 | +\bo current traps set by t\btr\bra\bap\bp | |
2730 | ||
2731 | +\bo shell parameters that are set by variable assignment or with s\bse\bet\bt | |
2732 | or inherited from the shell's parent in the environment | |
2733 | ||
d233b485 | 2734 | +\bo shell functions defined during execution or inherited from the |
17345e5a JA |
2735 | shell's parent in the environment |
2736 | ||
d233b485 | 2737 | +\bo options enabled at invocation (either by default or with com- |
17345e5a JA |
2738 | mand-line arguments) or by s\bse\bet\bt |
2739 | ||
2740 | +\bo options enabled by s\bsh\bho\bop\bpt\bt | |
2741 | ||
2742 | +\bo shell aliases defined with a\bal\bli\bia\bas\bs | |
2743 | ||
d233b485 | 2744 | +\bo various process IDs, including those of background jobs, the |
0001803f | 2745 | value of $\b$$\b$, and the value of P\bPP\bPI\bID\bD |
17345e5a | 2746 | |
d233b485 CR |
2747 | When a simple command other than a builtin or shell function is to be |
2748 | executed, it is invoked in a separate execution environment that con- | |
2749 | sists of the following. Unless otherwise noted, the values are inher- | |
17345e5a JA |
2750 | ited from the shell. |
2751 | ||
2752 | ||
d233b485 | 2753 | +\bo the shell's open files, plus any modifications and additions |
17345e5a JA |
2754 | specified by redirections to the command |
2755 | ||
2756 | +\bo the current working directory | |
2757 | ||
2758 | +\bo the file creation mode mask | |
2759 | ||
d233b485 | 2760 | +\bo shell variables and functions marked for export, along with |
17345e5a JA |
2761 | variables exported for the command, passed in the environment |
2762 | ||
2763 | +\bo traps caught by the shell are reset to the values inherited from | |
2764 | the shell's parent, and traps ignored by the shell are ignored | |
2765 | ||
d233b485 | 2766 | A command invoked in this separate environment cannot affect the |
17345e5a JA |
2767 | shell's execution environment. |
2768 | ||
d233b485 | 2769 | Command substitution, commands grouped with parentheses, and asynchro- |
17345e5a | 2770 | nous commands are invoked in a subshell environment that is a duplicate |
712f80b0 CR |
2771 | of the shell environment, except that traps caught by the shell are re- |
2772 | set to the values that the shell inherited from its parent at invoca- | |
17345e5a JA |
2773 | tion. Builtin commands that are invoked as part of a pipeline are also |
2774 | executed in a subshell environment. Changes made to the subshell envi- | |
2775 | ronment cannot affect the shell's execution environment. | |
2776 | ||
2777 | Subshells spawned to execute command substitutions inherit the value of | |
d233b485 | 2778 | 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 |
2779 | clears the -\b-e\be option in such subshells. |
2780 | ||
712f80b0 CR |
2781 | If a command is followed by a &\b& and job control is not active, the de- |
2782 | fault standard input for the command is the empty file _\b/_\bd_\be_\bv_\b/_\bn_\bu_\bl_\bl. Oth- | |
2783 | erwise, the invoked command inherits the file descriptors of the call- | |
2784 | ing shell as modified by redirections. | |
17345e5a JA |
2785 | |
2786 | E\bEN\bNV\bVI\bIR\bRO\bON\bNM\bME\bEN\bNT\bT | |
d233b485 | 2787 | When a program is invoked it is given an array of strings called the |
17345e5a JA |
2788 | _\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 |
2789 | _\bn_\ba_\bm_\be=_\bv_\ba_\bl_\bu_\be. | |
2790 | ||
712f80b0 CR |
2791 | The shell provides several ways to manipulate the environment. On in- |
2792 | vocation, the shell scans its own environment and creates a parameter | |
d233b485 | 2793 | for each name found, automatically marking it for _\be_\bx_\bp_\bo_\br_\bt to child pro- |
712f80b0 CR |
2794 | cesses. Executed commands inherit the environment. The e\bex\bxp\bpo\bor\brt\bt and d\bde\be-\b- |
2795 | c\bcl\bla\bar\bre\be -\b-x\bx commands allow parameters and functions to be added to and | |
17345e5a | 2796 | deleted from the environment. If the value of a parameter in the envi- |
712f80b0 CR |
2797 | ronment is modified, the new value becomes part of the environment, re- |
2798 | placing the old. The environment inherited by any executed command | |
d233b485 CR |
2799 | consists of the shell's initial environment, whose values may be modi- |
2800 | fied in the shell, less any pairs removed by the u\bun\bns\bse\bet\bt command, plus | |
17345e5a JA |
2801 | any additions via the e\bex\bxp\bpo\bor\brt\bt and d\bde\bec\bcl\bla\bar\bre\be -\b-x\bx commands. |
2802 | ||
d233b485 CR |
2803 | The environment for any _\bs_\bi_\bm_\bp_\bl_\be _\bc_\bo_\bm_\bm_\ba_\bn_\bd or function may be augmented |
2804 | temporarily by prefixing it with parameter assignments, as described | |
17345e5a JA |
2805 | above in P\bPA\bAR\bRA\bAM\bME\bET\bTE\bER\bRS\bS. These assignment statements affect only the envi- |
2806 | ronment seen by that command. | |
2807 | ||
d233b485 CR |
2808 | If the -\b-k\bk option is set (see the s\bse\bet\bt builtin command below), then _\ba_\bl_\bl |
2809 | parameter assignments are placed in the environment for a command, not | |
17345e5a JA |
2810 | just those that precede the command name. |
2811 | ||
d233b485 | 2812 | When b\bba\bas\bsh\bh invokes an external command, the variable _\b_ is set to the |
ac50fbac CR |
2813 | full filename of the command and passed to that command in its environ- |
2814 | ment. | |
17345e5a JA |
2815 | |
2816 | E\bEX\bXI\bIT\bT S\bST\bTA\bAT\bTU\bUS\bS | |
d233b485 | 2817 | The exit status of an executed command is the value returned by the |
17345e5a | 2818 | _\bw_\ba_\bi_\bt_\bp_\bi_\bd system call or equivalent function. Exit statuses fall between |
d233b485 | 2819 | 0 and 255, though, as explained below, the shell may use values above |
17345e5a | 2820 | 125 specially. Exit statuses from shell builtins and compound commands |
a0c0a00f | 2821 | are also limited to this range. Under certain circumstances, the shell |
17345e5a JA |
2822 | will use special values to indicate specific failure modes. |
2823 | ||
2824 | For the shell's purposes, a command which exits with a zero exit status | |
d233b485 CR |
2825 | has succeeded. An exit status of zero indicates success. A non-zero |
2826 | exit status indicates failure. When a command terminates on a fatal | |
17345e5a JA |
2827 | signal _\bN, b\bba\bas\bsh\bh uses the value of 128+_\bN as the exit status. |
2828 | ||
712f80b0 CR |
2829 | If a command is not found, the child process created to execute it re- |
2830 | turns a status of 127. If a command is found but is not executable, | |
17345e5a JA |
2831 | the return status is 126. |
2832 | ||
2833 | If a command fails because of an error during expansion or redirection, | |
2834 | the exit status is greater than zero. | |
2835 | ||
d233b485 CR |
2836 | Shell builtin commands return a status of 0 (_\bt_\br_\bu_\be) if successful, and |
2837 | non-zero (_\bf_\ba_\bl_\bs_\be) if an error occurs while they execute. All builtins | |
712f80b0 CR |
2838 | return an exit status of 2 to indicate incorrect usage, generally in- |
2839 | valid options or missing arguments. | |
17345e5a | 2840 | |
712f80b0 CR |
2841 | B\bBa\bas\bsh\bh itself returns the exit status of the last command executed, un- |
2842 | less a syntax error occurs, in which case it exits with a non-zero | |
17345e5a JA |
2843 | value. See also the e\bex\bxi\bit\bt builtin command below. |
2844 | ||
2845 | S\bSI\bIG\bGN\bNA\bAL\bLS\bS | |
d233b485 | 2846 | When b\bba\bas\bsh\bh is interactive, in the absence of any traps, it ignores |
17345e5a | 2847 | 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 |
d233b485 | 2848 | is caught and handled (so that the w\bwa\bai\bit\bt builtin is interruptible). In |
712f80b0 CR |
2849 | 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- |
2850 | 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 |
2851 | |
2852 | Non-builtin commands run by b\bba\bas\bsh\bh have signal handlers set to the values | |
712f80b0 CR |
2853 | inherited by the shell from its parent. When job control is not in ef- |
2854 | fect, asynchronous commands ignore S\bSI\bIG\bGI\bIN\bNT\bT and S\bSI\bIG\bGQ\bQU\bUI\bIT\bT in addition to | |
d233b485 | 2855 | these inherited handlers. Commands run as a result of command substi- |
17345e5a JA |
2856 | tution ignore the keyboard-generated job control signals S\bSI\bIG\bGT\bTT\bTI\bIN\bN, S\bSI\bIG\bGT\bT-\b- |
2857 | T\bTO\bOU\bU, and S\bSI\bIG\bGT\bTS\bST\bTP\bP. | |
2858 | ||
d233b485 CR |
2859 | The shell exits by default upon receipt of a S\bSI\bIG\bGH\bHU\bUP\bP. Before exiting, |
2860 | an interactive shell resends the S\bSI\bIG\bGH\bHU\bUP\bP to all jobs, running or | |
17345e5a | 2861 | stopped. Stopped jobs are sent S\bSI\bIG\bGC\bCO\bON\bNT\bT to ensure that they receive the |
d233b485 CR |
2862 | S\bSI\bIG\bGH\bHU\bUP\bP. To prevent the shell from sending the signal to a particular |
2863 | job, it should be removed from the jobs table with the d\bdi\bis\bso\bow\bwn\bn builtin | |
712f80b0 CR |
2864 | (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- |
2865 | ing d\bdi\bis\bso\bow\bwn\bn -\b-h\bh. | |
17345e5a | 2866 | |
d233b485 | 2867 | 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 |
2868 | S\bSI\bIG\bGH\bHU\bUP\bP to all jobs when an interactive login shell exits. |
2869 | ||
d233b485 | 2870 | If b\bba\bas\bsh\bh is waiting for a command to complete and receives a signal for |
17345e5a | 2871 | which a trap has been set, the trap will not be executed until the com- |
d233b485 CR |
2872 | mand completes. When b\bba\bas\bsh\bh is waiting for an asynchronous command via |
2873 | the w\bwa\bai\bit\bt builtin, the reception of a signal for which a trap has been | |
17345e5a JA |
2874 | set will cause the w\bwa\bai\bit\bt builtin to return immediately with an exit sta- |
2875 | tus greater than 128, immediately after which the trap is executed. | |
2876 | ||
2877 | J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL | |
712f80b0 CR |
2878 | _\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- |
2879 | ecution of processes and continue (_\br_\be_\bs_\bu_\bm_\be) their execution at a later | |
2880 | point. A user typically employs this facility via an interactive in- | |
2881 | terface supplied jointly by the operating system kernel's terminal | |
0001803f | 2882 | driver and b\bba\bas\bsh\bh. |
17345e5a | 2883 | |
d233b485 CR |
2884 | The shell associates a _\bj_\bo_\bb with each pipeline. It keeps a table of |
2885 | currently executing jobs, which may be listed with the j\bjo\bob\bbs\bs command. | |
2886 | 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 |
2887 | line that looks like: |
2888 | ||
2889 | [1] 25647 | |
2890 | ||
2891 | indicating that this job is job number 1 and that the process ID of the | |
2892 | last process in the pipeline associated with this job is 25647. All of | |
d233b485 | 2893 | the processes in a single pipeline are members of the same job. B\bBa\bas\bsh\bh |
17345e5a JA |
2894 | uses the _\bj_\bo_\bb abstraction as the basis for job control. |
2895 | ||
d233b485 | 2896 | To facilitate the implementation of the user interface to job control, |
17345e5a JA |
2897 | 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 |
2898 | _\bg_\br_\bo_\bu_\bp _\bI_\bD. Members of this process group (processes whose process group | |
2899 | ID is equal to the current terminal process group ID) receive keyboard- | |
d233b485 CR |
2900 | generated signals such as S\bSI\bIG\bGI\bIN\bNT\bT. These processes are said to be in |
2901 | 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 | 2902 | differs from the terminal's; such processes are immune to keyboard-gen- |
0001803f | 2903 | erated signals. Only foreground processes are allowed to read from or, |
d233b485 CR |
2904 | if the user so specifies with stty tostop, write to the terminal. |
2905 | Background processes which attempt to read from (write to when stty | |
2906 | 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 | |
2907 | by the kernel's terminal driver, which, unless caught, suspends the | |
0001803f | 2908 | process. |
17345e5a | 2909 | |
d233b485 | 2910 | If the operating system on which b\bba\bas\bsh\bh is running supports job control, |
17345e5a JA |
2911 | b\bba\bas\bsh\bh contains facilities to use it. Typing the _\bs_\bu_\bs_\bp_\be_\bn_\bd character (typ- |
2912 | ically ^\b^Z\bZ, Control-Z) while a process is running causes that process to | |
d233b485 CR |
2913 | 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 |
2914 | character (typically ^\b^Y\bY, Control-Y) causes the process to be stopped | |
712f80b0 CR |
2915 | when it attempts to read input from the terminal, and control to be re- |
2916 | turned to b\bba\bas\bsh\bh. The user may then manipulate the state of this job, | |
d233b485 | 2917 | using the b\bbg\bg command to continue it in the background, the f\bfg\bg command |
17345e5a JA |
2918 | to continue it in the foreground, or the k\bki\bil\bll\bl command to kill it. A ^\b^Z\bZ |
2919 | takes effect immediately, and has the additional side effect of causing | |
2920 | pending output and typeahead to be discarded. | |
2921 | ||
2922 | There are a number of ways to refer to a job in the shell. The charac- | |
d233b485 | 2923 | ter %\b% introduces a job specification (_\bj_\bo_\bb_\bs_\bp_\be_\bc). Job number _\bn may be |
17345e5a JA |
2924 | referred to as %\b%n\bn. A job may also be referred to using a prefix of the |
2925 | name used to start it, or using a substring that appears in its command | |
712f80b0 CR |
2926 | line. For example, %\b%c\bce\be refers to a stopped job whose command name be- |
2927 | gins with c\bce\be. If a prefix matches more than one job, b\bba\bas\bsh\bh reports an | |
2928 | error. Using %\b%?\b?c\bce\be, on the other hand, refers to any job containing the | |
2929 | string c\bce\be in its command line. If the substring matches more than one | |
2930 | job, b\bba\bas\bsh\bh reports an error. The symbols %\b%%\b% and %\b%+\b+ refer to the shell's | |
2931 | notion of the _\bc_\bu_\br_\br_\be_\bn_\bt _\bj_\bo_\bb, which is the last job stopped while it was | |
2932 | in the foreground or started in the background. The _\bp_\br_\be_\bv_\bi_\bo_\bu_\bs _\bj_\bo_\bb may | |
2933 | be referenced using %\b%-\b-. If there is only a single job, %\b%+\b+ and %\b%-\b- can | |
2934 | both be used to refer to that job. In output pertaining to jobs (e.g., | |
2935 | the output of the j\bjo\bob\bbs\bs command), the current job is always flagged with | |
2936 | a +\b+, and the previous job with a -\b-. A single % (with no accompanying | |
2937 | job specification) also refers to the current job. | |
17345e5a | 2938 | |
d233b485 CR |
2939 | Simply naming a job can be used to bring it into the foreground: %\b%1\b1 is |
2940 | a synonym for `\b``\b`f\bfg\bg %\b%1\b1'\b''\b', bringing job 1 from the background into the | |
2941 | foreground. Similarly, `\b``\b`%\b%1\b1 &\b&'\b''\b' resumes job 1 in the background, | |
17345e5a JA |
2942 | equivalent to `\b``\b`b\bbg\bg %\b%1\b1'\b''\b'. |
2943 | ||
d233b485 | 2944 | The shell learns immediately whenever a job changes state. Normally, |
17345e5a | 2945 | b\bba\bas\bsh\bh waits until it is about to print a prompt before reporting changes |
d233b485 | 2946 | in a job's status so as to not interrupt any other output. If the -\b-b\bb |
17345e5a | 2947 | option to the s\bse\bet\bt builtin command is enabled, b\bba\bas\bsh\bh reports such changes |
712f80b0 CR |
2948 | immediately. Any trap on S\bSI\bIG\bGC\bCH\bHL\bLD\bD is executed for each child that ex- |
2949 | its. | |
17345e5a | 2950 | |
d233b485 CR |
2951 | If an attempt to exit b\bba\bas\bsh\bh is made while jobs are stopped (or, if the |
2952 | 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 | 2953 | ning), the shell prints a warning message, and, if the c\bch\bhe\bec\bck\bkj\bjo\bob\bbs\bs option |
d233b485 CR |
2954 | is enabled, lists the jobs and their statuses. The j\bjo\bob\bbs\bs command may |
2955 | then be used to inspect their status. If a second attempt to exit is | |
2956 | made without an intervening command, the shell does not print another | |
17345e5a JA |
2957 | warning, and any stopped jobs are terminated. |
2958 | ||
d233b485 CR |
2959 | When the shell is waiting for a job or process using the w\bwa\bai\bit\bt builtin, |
2960 | and job control is enabled, w\bwa\bai\bit\bt will return when the job changes | |
712f80b0 CR |
2961 | state. The -\b-f\bf option causes w\bwa\bai\bit\bt to wait until the job or process ter- |
2962 | minates before returning. | |
d233b485 | 2963 | |
17345e5a JA |
2964 | P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG |
2965 | When executing interactively, b\bba\bas\bsh\bh displays the primary prompt P\bPS\bS1\b1 when | |
2966 | it is ready to read a command, and the secondary prompt P\bPS\bS2\b2 when it | |
a0c0a00f | 2967 | needs more input to complete a command. B\bBa\bas\bsh\bh displays P\bPS\bS0\b0 after it |
712f80b0 CR |
2968 | reads a command but before executing it. B\bBa\bas\bsh\bh displays P\bPS\bS4\b4 as de- |
2969 | scribed above before tracing each command when the -\b-x\bx option is en- | |
2970 | abled. B\bBa\bas\bsh\bh allows these prompt strings to be customized by inserting | |
2971 | a number of backslash-escaped special characters that are decoded as | |
2972 | follows: | |
17345e5a | 2973 | \\b\a\ba an ASCII bell character (07) |
a0c0a00f | 2974 | \\b\d\bd the date in "Weekday Month Date" format (e.g., "Tue May |
17345e5a JA |
2975 | 26") |
2976 | \\b\D\bD{\b{_\bf_\bo_\br_\bm_\ba_\bt}\b} | |
712f80b0 CR |
2977 | the _\bf_\bo_\br_\bm_\ba_\bt is passed to _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be(3) and the result is in- |
2978 | serted into the prompt string; an empty _\bf_\bo_\br_\bm_\ba_\bt results in | |
2979 | a locale-specific time representation. The braces are | |
17345e5a JA |
2980 | required |
2981 | \\b\e\be an ASCII escape character (033) | |
2982 | \\b\h\bh the hostname up to the first `.' | |
2983 | \\b\H\bH the hostname | |
2984 | \\b\j\bj the number of jobs currently managed by the shell | |
2985 | \\b\l\bl the basename of the shell's terminal device name | |
2986 | \\b\n\bn newline | |
2987 | \\b\r\br carriage return | |
a0c0a00f | 2988 | \\b\s\bs the name of the shell, the basename of $\b$0\b0 (the portion |
17345e5a JA |
2989 | following the final slash) |
2990 | \\b\t\bt the current time in 24-hour HH:MM:SS format | |
2991 | \\b\T\bT the current time in 12-hour HH:MM:SS format | |
2992 | \\b\@\b@ the current time in 12-hour am/pm format | |
2993 | \\b\A\bA the current time in 24-hour HH:MM format | |
2994 | \\b\u\bu the username of the current user | |
2995 | \\b\v\bv the version of b\bba\bas\bsh\bh (e.g., 2.00) | |
2996 | \\b\V\bV the release of b\bba\bas\bsh\bh, version + patch level (e.g., 2.00.0) | |
2997 | \\b\w\bw the current working directory, with $\b$H\bHO\bOM\bME\bE abbreviated | |
0001803f CR |
2998 | with a tilde (uses the value of the P\bPR\bRO\bOM\bMP\bPT\bT_\b_D\bDI\bIR\bRT\bTR\bRI\bIM\bM vari- |
2999 | able) | |
17345e5a JA |
3000 | \\b\W\bW the basename of the current working directory, with $\b$H\bHO\bOM\bME\bE |
3001 | abbreviated with a tilde | |
3002 | \\b\!\b! the history number of this command | |
3003 | \\b\#\b# the command number of this command | |
3004 | \\b\$\b$ if the effective UID is 0, a #\b#, otherwise a $\b$ | |
3005 | \\b\_\bn_\bn_\bn the character corresponding to the octal number _\bn_\bn_\bn | |
3006 | \\b\\\b\ a backslash | |
0001803f CR |
3007 | \\b\[\b[ begin a sequence of non-printing characters, which could |
3008 | be used to embed a terminal control sequence into the | |
17345e5a JA |
3009 | prompt |
3010 | \\b\]\b] end a sequence of non-printing characters | |
3011 | ||
0001803f CR |
3012 | The command number and the history number are usually different: the |
3013 | history number of a command is its position in the history list, which | |
712f80b0 CR |
3014 | may include commands restored from the history file (see H\bHI\bIS\bST\bTO\bOR\bRY\bY be- |
3015 | low), while the command number is the position in the sequence of com- | |
3016 | mands executed during the current shell session. After the string is | |
3017 | decoded, it is expanded via parameter expansion, command substitution, | |
3018 | arithmetic expansion, and quote removal, subject to the value of the | |
3019 | 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 | |
3020 | 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 | |
3021 | escaped portions of the string appear within command substitution or | |
3022 | contain characters special to word expansion. | |
17345e5a JA |
3023 | |
3024 | R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE | |
0001803f | 3025 | This is the library that handles reading input when using an interac- |
17345e5a JA |
3026 | tive shell, unless the -\b--\b-n\bno\boe\bed\bdi\bit\bti\bin\bng\bg option is given at shell invocation. |
3027 | Line editing is also used when using the -\b-e\be option to the r\bre\bea\bad\bd builtin. | |
495aee44 | 3028 | By default, the line editing commands are similar to those of Emacs. A |
17345e5a | 3029 | vi-style line editing interface is also available. Line editing can be |
0001803f CR |
3030 | 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 |
3031 | 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 | |
3032 | 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 |
3033 | s\bse\bet\bt builtin. |
3034 | ||
3035 | R\bRe\bea\bad\bdl\bli\bin\bne\be N\bNo\bot\bta\bat\bti\bio\bon\bn | |
495aee44 | 3036 | In this section, the Emacs-style notation is used to denote keystrokes. |
0001803f CR |
3037 | Control keys are denoted by C-_\bk_\be_\by, e.g., C-n means Control-N. Simi- |
3038 | larly, _\bm_\be_\bt_\ba keys are denoted by M-_\bk_\be_\by, so M-x means Meta-X. (On key- | |
3039 | boards without a _\bm_\be_\bt_\ba key, M-_\bx means ESC _\bx, i.e., press the Escape key | |
17345e5a | 3040 | then the _\bx key. This makes ESC the _\bm_\be_\bt_\ba _\bp_\br_\be_\bf_\bi_\bx. The combination M-C-_\bx |
0001803f | 3041 | means ESC-Control-_\bx, or press the Escape key then hold the Control key |
17345e5a JA |
3042 | while pressing the _\bx key.) |
3043 | ||
3044 | Readline commands may be given numeric _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs, which normally act as | |
0001803f CR |
3045 | a repeat count. Sometimes, however, it is the sign of the argument |
3046 | that is significant. Passing a negative argument to a command that | |
3047 | acts in the forward direction (e.g., k\bki\bil\bll\bl-\b-l\bli\bin\bne\be) causes that command to | |
3048 | act in a backward direction. Commands whose behavior with arguments | |
17345e5a JA |
3049 | deviates from this are noted below. |
3050 | ||
0001803f | 3051 | When a command is described as _\bk_\bi_\bl_\bl_\bi_\bn_\bg text, the text deleted is saved |
17345e5a JA |
3052 | for possible future retrieval (_\by_\ba_\bn_\bk_\bi_\bn_\bg). The killed text is saved in a |
3053 | _\bk_\bi_\bl_\bl _\br_\bi_\bn_\bg. Consecutive kills cause the text to be accumulated into one | |
3054 | unit, which can be yanked all at once. Commands which do not kill text | |
3055 | separate the chunks of text on the kill ring. | |
3056 | ||
3057 | R\bRe\bea\bad\bdl\bli\bin\bne\be I\bIn\bni\bit\bti\bia\bal\bli\biz\bza\bat\bti\bio\bon\bn | |
0001803f CR |
3058 | Readline is customized by putting commands in an initialization file |
3059 | (the _\bi_\bn_\bp_\bu_\bt_\br_\bc file). The name of this file is taken from the value of | |
712f80b0 CR |
3060 | the I\bIN\bNP\bPU\bUT\bTR\bRC\bC variable. If that variable is unset, the default is _\b~_\b/_\b._\bi_\bn_\b- |
3061 | _\bp_\bu_\bt_\br_\bc. If that file does not exist or cannot be read, the ultimate | |
3062 | default is _\b/_\be_\bt_\bc_\b/_\bi_\bn_\bp_\bu_\bt_\br_\bc. When a program which uses the readline li- | |
3063 | brary starts up, the initialization file is read, and the key bindings | |
3064 | and variables are set. There are only a few basic constructs allowed | |
3065 | in the readline initialization file. Blank lines are ignored. Lines | |
3066 | beginning with a #\b# are comments. Lines beginning with a $\b$ indicate | |
3067 | conditional constructs. Other lines denote key bindings and variable | |
3068 | settings. | |
17345e5a | 3069 | |
0001803f | 3070 | The default key-bindings may be changed with an _\bi_\bn_\bp_\bu_\bt_\br_\bc file. Other |
17345e5a JA |
3071 | programs that use this library may add their own commands and bindings. |
3072 | ||
3073 | For example, placing | |
3074 | ||
3075 | M-Control-u: universal-argument | |
3076 | or | |
3077 | C-Meta-u: universal-argument | |
a0c0a00f | 3078 | 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 |
3079 | _\bs_\ba_\bl_\b-_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt. |
3080 | ||
a0c0a00f | 3081 | The following symbolic character names are recognized: _\bR_\bU_\bB_\bO_\bU_\bT, _\bD_\bE_\bL, |
17345e5a JA |
3082 | _\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. |
3083 | ||
a0c0a00f | 3084 | In addition to command names, readline allows keys to be bound to a |
17345e5a JA |
3085 | string that is inserted when the key is pressed (a _\bm_\ba_\bc_\br_\bo). |
3086 | ||
3087 | R\bRe\bea\bad\bdl\bli\bin\bne\be K\bKe\bey\by B\bBi\bin\bnd\bdi\bin\bng\bgs\bs | |
a0c0a00f CR |
3088 | The syntax for controlling key bindings in the _\bi_\bn_\bp_\bu_\bt_\br_\bc file is simple. |
3089 | All that is required is the name of the command or the text of a macro | |
3090 | and a key sequence to which it should be bound. The name may be speci- | |
17345e5a JA |
3091 | fied in one of two ways: as a symbolic key name, possibly with _\bM_\be_\bt_\ba_\b- or |
3092 | _\bC_\bo_\bn_\bt_\br_\bo_\bl_\b- prefixes, or as a key sequence. | |
3093 | ||
3094 | 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 | |
3095 | of a key spelled out in English. For example: | |
3096 | ||
3097 | Control-u: universal-argument | |
3098 | Meta-Rubout: backward-kill-word | |
3099 | Control-o: "> output" | |
3100 | ||
a0c0a00f CR |
3101 | 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, |
3102 | _\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 | |
3103 | run the macro expressed on the right hand side (that is, to insert the | |
17345e5a JA |
3104 | text ``> output'' into the line). |
3105 | ||
a0c0a00f CR |
3106 | 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 |
3107 | from k\bke\bey\byn\bna\bam\bme\be above in that strings denoting an entire key sequence may | |
3108 | be specified by placing the sequence within double quotes. Some GNU | |
3109 | Emacs style key escapes can be used, as in the following example, but | |
17345e5a JA |
3110 | the symbolic character names are not recognized. |
3111 | ||
3112 | "\C-u": universal-argument | |
3113 | "\C-x\C-r": re-read-init-file | |
3114 | "\e[11~": "Function Key 1" | |
3115 | ||
3116 | 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. | |
a0c0a00f | 3117 | _\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 |
3118 | bound to insert the text ``Function Key 1''. |
3119 | ||
3120 | The full set of GNU Emacs style escape sequences is | |
3121 | \\b\C\bC-\b- control prefix | |
3122 | \\b\M\bM-\b- meta prefix | |
3123 | \\b\e\be an escape character | |
3124 | \\b\\\b\ backslash | |
3125 | \\b\"\b" literal " | |
3126 | \\b\'\b' literal ' | |
3127 | ||
a0c0a00f | 3128 | In addition to the GNU Emacs style escape sequences, a second set of |
17345e5a JA |
3129 | backslash escapes is available: |
3130 | \\b\a\ba alert (bell) | |
3131 | \\b\b\bb backspace | |
3132 | \\b\d\bd delete | |
3133 | \\b\f\bf form feed | |
3134 | \\b\n\bn newline | |
3135 | \\b\r\br carriage return | |
3136 | \\b\t\bt horizontal tab | |
3137 | \\b\v\bv vertical tab | |
a0c0a00f | 3138 | \\b\_\bn_\bn_\bn the eight-bit character whose value is the octal value |
17345e5a | 3139 | _\bn_\bn_\bn (one to three digits) |
a0c0a00f | 3140 | \\b\x\bx_\bH_\bH the eight-bit character whose value is the hexadecimal |
17345e5a JA |
3141 | value _\bH_\bH (one or two hex digits) |
3142 | ||
3143 | When entering the text of a macro, single or double quotes must be used | |
3144 | to indicate a macro definition. Unquoted text is assumed to be a func- | |
a0c0a00f CR |
3145 | tion name. In the macro body, the backslash escapes described above |
3146 | are expanded. Backslash will quote any other character in the macro | |
17345e5a JA |
3147 | text, including " and '. |
3148 | ||
a0c0a00f CR |
3149 | B\bBa\bas\bsh\bh allows the current readline key bindings to be displayed or modi- |
3150 | fied with the b\bbi\bin\bnd\bd builtin command. The editing mode may be switched | |
3151 | during interactive use by using the -\b-o\bo option to the s\bse\bet\bt builtin com- | |
17345e5a JA |
3152 | 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). |
3153 | ||
3154 | R\bRe\bea\bad\bdl\bli\bin\bne\be V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs | |
3155 | Readline has variables that can be used to further customize its behav- | |
3156 | ior. A variable may be set in the _\bi_\bn_\bp_\bu_\bt_\br_\bc file with a statement of the | |
3157 | form | |
3158 | ||
3159 | s\bse\bet\bt _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be_\b-_\bn_\ba_\bm_\be _\bv_\ba_\bl_\bu_\be | |
712f80b0 | 3160 | 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 | 3161 | |
a0c0a00f CR |
3162 | Except where noted, readline variables can take the values O\bOn\bn or O\bOf\bff\bf |
3163 | (without regard to case). Unrecognized variable names are ignored. | |
3164 | When a variable value is read, empty or null values, "on" (case-insen- | |
17345e5a JA |
3165 | sitive), and "1" are equivalent to O\bOn\bn. All other values are equivalent |
3166 | to O\bOf\bff\bf. The variables and their default values are: | |
3167 | ||
3168 | b\bbe\bel\bll\bl-\b-s\bst\bty\byl\ble\be (\b(a\bau\bud\bdi\bib\bbl\ble\be)\b) | |
a0c0a00f | 3169 | Controls what happens when readline wants to ring the terminal |
17345e5a | 3170 | bell. If set to n\bno\bon\bne\be, readline never rings the bell. If set to |
a0c0a00f | 3171 | v\bvi\bis\bsi\bib\bbl\ble\be, readline uses a visible bell if one is available. If |
17345e5a JA |
3172 | set to a\bau\bud\bdi\bib\bbl\ble\be, readline attempts to ring the terminal's bell. |
3173 | 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 | 3174 | If set to O\bOn\bn, readline attempts to bind the control characters |
17345e5a JA |
3175 | treated specially by the kernel's terminal driver to their read- |
3176 | line equivalents. | |
a0c0a00f CR |
3177 | 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) |
3178 | If set to O\bOn\bn, readline attempts to briefly move the cursor to an | |
3179 | opening parenthesis when a closing parenthesis is inserted. | |
3180 | 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) | |
3181 | If set to O\bOn\bn, when listing completions, readline displays the | |
3182 | common prefix of the set of possible completions using a differ- | |
3183 | ent color. The color definitions are taken from the value of | |
3184 | the L\bLS\bS_\b_C\bCO\bOL\bLO\bOR\bRS\bS environment variable. | |
ac50fbac | 3185 | c\bco\bol\blo\bor\bre\bed\bd-\b-s\bst\bta\bat\bts\bs (\b(O\bOf\bff\bf)\b) |
a0c0a00f CR |
3186 | If set to O\bOn\bn, readline displays possible completions using dif- |
3187 | ferent colors to indicate their file type. The color defini- | |
3188 | tions are taken from the value of the L\bLS\bS_\b_C\bCO\bOL\bLO\bOR\bRS\bS environment | |
ac50fbac | 3189 | variable. |
17345e5a | 3190 | c\bco\bom\bmm\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn (\b(`\b``\b`#\b#'\b''\b')\b) |
a0c0a00f | 3191 | 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 |
3192 | command is executed. This command is bound to M\bM-\b-#\b# in emacs mode |
3193 | and to #\b# in vi command mode. | |
a0c0a00f CR |
3194 | 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) |
3195 | The number of screen columns used to display possible matches | |
3196 | when performing completion. The value is ignored if it is less | |
3197 | than 0 or greater than the terminal screen width. A value of 0 | |
3198 | will cause matches to be displayed one per line. The default | |
3199 | value is -1. | |
17345e5a JA |
3200 | 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) |
3201 | If set to O\bOn\bn, readline performs filename matching and completion | |
3202 | in a case-insensitive fashion. | |
a0c0a00f CR |
3203 | 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) |
3204 | 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 | |
3205 | treats hyphens (_\b-) and underscores (_\b_) as equivalent when per- | |
3206 | forming case-insensitive filename matching and completion. | |
17345e5a | 3207 | 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) |
a0c0a00f CR |
3208 | The length in characters of the common prefix of a list of pos- |
3209 | sible completions that is displayed without modification. When | |
3210 | set to a value greater than zero, common prefixes longer than | |
3211 | this value are replaced with an ellipsis when displaying possi- | |
17345e5a JA |
3212 | ble completions. |
3213 | 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) | |
a0c0a00f CR |
3214 | This determines when the user is queried about viewing the num- |
3215 | 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- | |
3216 | t\bti\bio\bon\bns\bs command. It may be set to any integer value greater than | |
3217 | or equal to zero. If the number of possible completions is | |
3eb0018e CR |
3218 | greater than or equal to the value of this variable, readline |
3219 | will ask whether or not the user wishes to view them; otherwise | |
3220 | they are simply listed on the terminal. | |
17345e5a | 3221 | c\bco\bon\bnv\bve\ber\brt\bt-\b-m\bme\bet\bta\ba (\b(O\bOn\bn)\b) |
a0c0a00f | 3222 | If set to O\bOn\bn, readline will convert characters with the eighth |
17345e5a | 3223 | bit set to an ASCII key sequence by stripping the eighth bit and |
a0c0a00f CR |
3224 | prefixing an escape character (in effect, using escape as the |
3225 | _\bm_\be_\bt_\ba _\bp_\br_\be_\bf_\bi_\bx). The default is _\bO_\bn, but readline will set it to | |
3226 | _\bO_\bf_\bf if the locale contains eight-bit characters. | |
17345e5a JA |
3227 | 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) |
3228 | If set to O\bOn\bn, readline will inhibit word completion. Completion | |
ac50fbac | 3229 | characters will be inserted into the line as if they had been |
17345e5a | 3230 | mapped to s\bse\bel\blf\bf-\b-i\bin\bns\bse\ber\brt\bt. |
0001803f | 3231 | 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 | 3232 | When set to O\bOn\bn, on operating systems that indicate they support |
0001803f CR |
3233 | it, readline echoes a character corresponding to a signal gener- |
3234 | ated from the keyboard. | |
a0c0a00f CR |
3235 | e\bed\bdi\bit\bti\bin\bng\bg-\b-m\bmo\bod\bde\be (\b(e\bem\bma\bac\bcs\bs)\b) |
3236 | Controls whether readline begins with a set of key bindings sim- | |
3237 | 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 | |
3238 | v\bvi\bi. | |
d233b485 CR |
3239 | e\bem\bma\bac\bcs\bs-\b-m\bmo\bod\bde\be-\b-s\bst\btr\bri\bin\bng\bg (\b(@\b@)\b) |
3240 | 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 | |
3241 | displayed immediately before the last line of the primary prompt | |
3242 | when emacs editing mode is active. The value is expanded like a | |
3243 | key binding, so the standard set of meta- and control prefixes | |
3244 | and backslash escape sequences is available. Use the \1 and \2 | |
3245 | escapes to begin and end sequences of non-printing characters, | |
3246 | which can be used to embed a terminal control sequence into the | |
3247 | mode string. | |
a0c0a00f | 3248 | 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\bOf\bff\bf)\b) |
d233b485 | 3249 | When set to O\bOn\bn, readline will configure the terminal in a way |
a0c0a00f CR |
3250 | that will enable it to insert each paste into the editing buffer |
3251 | as a single string of characters, instead of treating each char- | |
d233b485 CR |
3252 | acter as if it had been read from the keyboard. This can pre- |
3253 | vent pasted characters from being interpreted as editing com- | |
a0c0a00f | 3254 | mands. |
17345e5a JA |
3255 | e\ben\bna\bab\bbl\ble\be-\b-k\bke\bey\byp\bpa\bad\bd (\b(O\bOf\bff\bf)\b) |
3256 | When set to O\bOn\bn, readline will try to enable the application key- | |
712f80b0 CR |
3257 | pad when it is called. Some systems need this to enable the ar- |
3258 | row keys. | |
0001803f | 3259 | 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 |
3260 | When set to O\bOn\bn, readline will try to enable any meta modifier |
3261 | key the terminal claims to support when it is called. On many | |
0001803f | 3262 | terminals, the meta key is used to send eight-bit characters. |
17345e5a | 3263 | e\bex\bxp\bpa\ban\bnd\bd-\b-t\bti\bil\bld\bde\be (\b(O\bOf\bff\bf)\b) |
712f80b0 CR |
3264 | If set to O\bOn\bn, tilde expansion is performed when readline at- |
3265 | tempts word completion. | |
17345e5a | 3266 | 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 |
3267 | If set to O\bOn\bn, the history code attempts to place point at the |
3268 | same location on each history line retrieved with p\bpr\bre\bev\bvi\bio\bou\bus\bs-\b-h\bhi\bis\bs-\b- | |
17345e5a | 3269 | t\bto\bor\bry\by or n\bne\bex\bxt\bt-\b-h\bhi\bis\bst\bto\bor\bry\by. |
a0c0a00f | 3270 | h\bhi\bis\bst\bto\bor\bry\by-\b-s\bsi\biz\bze\be (\b(u\bun\bns\bse\bet\bt)\b) |
d233b485 CR |
3271 | Set the maximum number of history entries saved in the history |
3272 | list. If set to zero, any existing history entries are deleted | |
ac50fbac | 3273 | and no new entries are saved. If set to a value less than zero, |
d233b485 CR |
3274 | the number of history entries is not limited. By default, the |
3275 | number of history entries is set to the value of the H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE | |
3276 | 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 |
3277 | non-numeric value, the maximum number of history entries will be |
3278 | set to 500. | |
17345e5a | 3279 | 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 | 3280 | When set to O\bOn\bn, makes readline use a single line for display, |
17345e5a | 3281 | scrolling the input horizontally on a single screen line when it |
d233b485 | 3282 | becomes longer than the screen width rather than wrapping to a |
712f80b0 CR |
3283 | new line. This setting is automatically enabled for terminals |
3284 | of height 1. | |
17345e5a | 3285 | i\bin\bnp\bpu\but\bt-\b-m\bme\bet\bta\ba (\b(O\bOf\bff\bf)\b) |
712f80b0 CR |
3286 | If set to O\bOn\bn, readline will enable eight-bit input (that is, it |
3287 | will not strip the eighth bit from the characters it reads), re- | |
3288 | gardless of what the terminal claims it can support. The name | |
3289 | m\bme\bet\bta\ba-\b-f\bfl\bla\bag\bg is a synonym for this variable. The default is _\bO_\bf_\bf, | |
3290 | but readline will set it to _\bO_\bn if the locale contains eight-bit | |
a0c0a00f | 3291 | characters. |
17345e5a | 3292 | 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) |
712f80b0 CR |
3293 | The string of characters that should terminate an incremental |
3294 | search without subsequently executing the character as a com- | |
3295 | mand. If this variable has not been given a value, the charac- | |
17345e5a JA |
3296 | ters _\bE_\bS_\bC and _\bC_\b-_\bJ will terminate an incremental search. |
3297 | k\bke\bey\bym\bma\bap\bp (\b(e\bem\bma\bac\bcs\bs)\b) | |
712f80b0 CR |
3298 | Set the current readline keymap. The set of valid keymap names |
3299 | 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- | |
3300 | _\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 | |
3301 | 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 | 3302 | value of e\bed\bdi\bit\bti\bin\bng\bg-\b-m\bmo\bod\bde\be also affects the default keymap. |
ac50fbac | 3303 | k\bke\bey\bys\bse\beq\bq-\b-t\bti\bim\bme\beo\bou\but\bt (\b(5\b50\b00\b0)\b) |
712f80b0 CR |
3304 | Specifies the duration _\br_\be_\ba_\bd_\bl_\bi_\bn_\be will wait for a character when |
3305 | reading an ambiguous key sequence (one that can form a complete | |
ac50fbac | 3306 | key sequence using the input read so far, or can take additional |
712f80b0 CR |
3307 | input to complete a longer key sequence). If no input is re- |
3308 | ceived within the timeout, _\br_\be_\ba_\bd_\bl_\bi_\bn_\be will use the shorter but | |
3309 | complete key sequence. The value is specified in milliseconds, | |
3310 | so a value of 1000 means that _\br_\be_\ba_\bd_\bl_\bi_\bn_\be will wait one second for | |
3311 | additional input. If this variable is set to a value less than | |
3312 | or equal to zero, or to a non-numeric value, _\br_\be_\ba_\bd_\bl_\bi_\bn_\be will wait | |
3313 | until another key is pressed to decide which key sequence to | |
ac50fbac | 3314 | complete. |
17345e5a JA |
3315 | m\bma\bar\brk\bk-\b-d\bdi\bir\bre\bec\bct\bto\bor\bri\bie\bes\bs (\b(O\bOn\bn)\b) |
3316 | If set to O\bOn\bn, completed directory names have a slash appended. | |
3317 | 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) | |
712f80b0 | 3318 | If set to O\bOn\bn, history lines that have been modified are dis- |
17345e5a JA |
3319 | played with a preceding asterisk (*\b*). |
3320 | 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) | |
3321 | If set to O\bOn\bn, completed names which are symbolic links to direc- | |
712f80b0 CR |
3322 | tories have a slash appended (subject to the value of m\bma\bar\brk\bk-\b-d\bdi\bi-\b- |
3323 | r\bre\bec\bct\bto\bor\bri\bie\bes\bs). | |
17345e5a | 3324 | 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) |
712f80b0 CR |
3325 | This variable, when set to O\bOn\bn, causes readline to match files |
3326 | whose names begin with a `.' (hidden files) when performing | |
3327 | filename completion. If set to O\bOf\bff\bf, the leading `.' must be | |
495aee44 CR |
3328 | supplied by the user in the filename to be completed. |
3329 | 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) | |
712f80b0 | 3330 | If set to O\bOn\bn, menu completion displays the common prefix of the |
495aee44 CR |
3331 | list of possible completions (which may be empty) before cycling |
3332 | through the list. | |
17345e5a | 3333 | o\bou\but\btp\bpu\but\bt-\b-m\bme\bet\bta\ba (\b(O\bOf\bff\bf)\b) |
712f80b0 | 3334 | If set to O\bOn\bn, readline will display characters with the eighth |
17345e5a | 3335 | bit set directly rather than as a meta-prefixed escape sequence. |
a0c0a00f CR |
3336 | The default is _\bO_\bf_\bf, but readline will set it to _\bO_\bn if the locale |
3337 | contains eight-bit characters. | |
17345e5a | 3338 | p\bpa\bag\bge\be-\b-c\bco\bom\bmp\bpl\ble\bet\bti\bio\bon\bns\bs (\b(O\bOn\bn)\b) |
712f80b0 | 3339 | If set to O\bOn\bn, readline uses an internal _\bm_\bo_\br_\be-like pager to dis- |
17345e5a JA |
3340 | play a screenful of possible completions at a time. |
3341 | 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) | |
712f80b0 CR |
3342 | If set to O\bOn\bn, readline will display completions with matches |
3343 | sorted horizontally in alphabetical order, rather than down the | |
17345e5a JA |
3344 | screen. |
3345 | 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) | |
712f80b0 | 3346 | If set to O\bOn\bn, readline will undo all changes to history lines |
17345e5a | 3347 | before returning when a\bac\bcc\bce\bep\bpt\bt-\b-l\bli\bin\bne\be is executed. By default, his- |
712f80b0 | 3348 | tory lines may be modified and retain individual undo lists |
17345e5a JA |
3349 | across calls to r\bre\bea\bad\bdl\bli\bin\bne\be. |
3350 | 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) | |
712f80b0 | 3351 | This alters the default behavior of the completion functions. |
495aee44 | 3352 | If set to O\bOn\bn, words which have more than one possible completion |
712f80b0 | 3353 | cause the matches to be listed immediately instead of ringing |
17345e5a JA |
3354 | the bell. |
3355 | 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) | |
712f80b0 | 3356 | This alters the default behavior of the completion functions in |
495aee44 | 3357 | 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 |
712f80b0 CR |
3358 | which have more than one possible completion without any possi- |
3359 | ble partial completion (the possible completions don't share a | |
3360 | common prefix) cause the matches to be listed immediately in- | |
3361 | stead of ringing the bell. | |
ac50fbac | 3362 | 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) |
712f80b0 CR |
3363 | If set to O\bOn\bn, add a string to the beginning of the prompt indi- |
3364 | cating the editing mode: emacs, vi command, or vi insertion. | |
d233b485 | 3365 | 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 | 3366 | 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) |
712f80b0 CR |
3367 | If set to O\bOn\bn, this alters the default completion behavior when |
3368 | inserting a single match into the line. It's only active when | |
3369 | performing completion in the middle of a word. If enabled, | |
3370 | readline does not insert characters from the completion that | |
3371 | match characters after point in the word being completed, so | |
0001803f | 3372 | portions of the word following the cursor are not duplicated. |
a0c0a00f | 3373 | 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) |
712f80b0 | 3374 | 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 | 3375 | displayed immediately before the last line of the primary prompt |
712f80b0 | 3376 | when vi editing mode is active and in command mode. The value |
d233b485 | 3377 | is expanded like a key binding, so the standard set of meta- and |
712f80b0 CR |
3378 | control prefixes and backslash escape sequences is available. |
3379 | Use the \1 and \2 escapes to begin and end sequences of non- | |
3380 | printing characters, which can be used to embed a terminal con- | |
d233b485 | 3381 | trol sequence into the mode string. |
a0c0a00f | 3382 | 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) |
712f80b0 | 3383 | 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 |
3384 | displayed immediately before the last line of the primary prompt |
3385 | when vi editing mode is active and in insertion mode. The value | |
3386 | is expanded like a key binding, so the standard set of meta- and | |
712f80b0 CR |
3387 | control prefixes and backslash escape sequences is available. |
3388 | Use the \1 and \2 escapes to begin and end sequences of non- | |
3389 | printing characters, which can be used to embed a terminal con- | |
d233b485 | 3390 | trol sequence into the mode string. |
17345e5a | 3391 | v\bvi\bis\bsi\bib\bbl\ble\be-\b-s\bst\bta\bat\bts\bs (\b(O\bOf\bff\bf)\b) |
712f80b0 CR |
3392 | If set to O\bOn\bn, a character denoting a file's type as reported by |
3393 | _\bs_\bt_\ba_\bt(2) is appended to the filename when listing possible com- | |
17345e5a JA |
3394 | pletions. |
3395 | ||
3396 | 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 | |
712f80b0 CR |
3397 | Readline implements a facility similar in spirit to the conditional |
3398 | compilation features of the C preprocessor which allows key bindings | |
3399 | and variable settings to be performed as the result of tests. There | |
17345e5a JA |
3400 | are four parser directives used. |
3401 | ||
712f80b0 CR |
3402 | $\b$i\bif\bf The $\b$i\bif\bf construct allows bindings to be made based on the edit- |
3403 | ing mode, the terminal being used, or the application using | |
d233b485 | 3404 | readline. The text of the test, after any comparison operator, |
712f80b0 | 3405 | extends to the end of the line; unless otherwise noted, no |
d233b485 CR |
3406 | characters are required to isolate it. |
3407 | ||
712f80b0 CR |
3408 | m\bmo\bod\bde\be The m\bmo\bod\bde\be=\b= form of the $\b$i\bif\bf directive is used to test |
3409 | whether readline is in emacs or vi mode. This may be | |
3410 | used in conjunction with the s\bse\bet\bt k\bke\bey\bym\bma\bap\bp command, for in- | |
3411 | stance, to set bindings in the _\be_\bm_\ba_\bc_\bs_\b-_\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd and | |
3412 | _\be_\bm_\ba_\bc_\bs_\b-_\bc_\bt_\bl_\bx keymaps only if readline is starting out in | |
17345e5a JA |
3413 | emacs mode. |
3414 | ||
712f80b0 | 3415 | t\bte\ber\brm\bm The t\bte\ber\brm\bm=\b= form may be used to include terminal-specific |
17345e5a JA |
3416 | key bindings, perhaps to bind the key sequences output by |
3417 | the terminal's function keys. The word on the right side | |
a0c0a00f | 3418 | of the =\b= is tested against both the full name of the ter- |
712f80b0 CR |
3419 | minal and the portion of the terminal name before the |
3420 | first -\b-. This allows _\bs_\bu_\bn to match both _\bs_\bu_\bn and _\bs_\bu_\bn_\b-_\bc_\bm_\bd, | |
17345e5a JA |
3421 | for instance. |
3422 | ||
d233b485 | 3423 | v\bve\ber\brs\bsi\bio\bon\bn |
712f80b0 CR |
3424 | The v\bve\ber\brs\bsi\bio\bon\bn test may be used to perform comparisons |
3425 | against specific readline versions. The v\bve\ber\brs\bsi\bio\bon\bn expands | |
3426 | to the current readline version. The set of comparison | |
3427 | operators includes =\b=, (and =\b==\b=), !\b!=\b=, <\b<=\b=, >\b>=\b=, <\b<, and >\b>. | |
3428 | The version number supplied on the right side of the op- | |
3429 | erator consists of a major version number, an optional | |
d233b485 | 3430 | decimal point, and an optional minor version (e.g., 7\b7.\b.1\b1). |
712f80b0 | 3431 | If the minor version is omitted, it is assumed to be 0\b0. |
d233b485 CR |
3432 | The operator may be separated from the string v\bve\ber\brs\bsi\bio\bon\bn and |
3433 | from the version number argument by whitespace. | |
3434 | ||
17345e5a JA |
3435 | a\bap\bpp\bpl\bli\bic\bca\bat\bti\bio\bon\bn |
3436 | The a\bap\bpp\bpl\bli\bic\bca\bat\bti\bio\bon\bn construct is used to include application- | |
712f80b0 CR |
3437 | specific settings. Each program using the readline li- |
3438 | brary sets the _\ba_\bp_\bp_\bl_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\bn_\ba_\bm_\be, and an initialization | |
17345e5a | 3439 | file can test for a particular value. This could be used |
712f80b0 CR |
3440 | to bind key sequences to functions useful for a specific |
3441 | program. For instance, the following command adds a key | |
3442 | sequence that quotes the current or previous word in | |
495aee44 | 3443 | b\bba\bas\bsh\bh: |
17345e5a JA |
3444 | |
3445 | $\b$i\bif\bf Bash | |
3446 | # Quote the current or previous word | |
3447 | "\C-xq": "\eb\"\ef\"" | |
3448 | $\b$e\ben\bnd\bdi\bif\bf | |
3449 | ||
d233b485 CR |
3450 | _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be |
3451 | The _\bv_\ba_\br_\bi_\ba_\bb_\bl_\be construct provides simple equality tests for | |
712f80b0 CR |
3452 | readline variables and values. The permitted comparison |
3453 | operators are _\b=, _\b=_\b=, and _\b!_\b=. The variable name must be | |
d233b485 | 3454 | separated from the comparison operator by whitespace; the |
712f80b0 CR |
3455 | operator may be separated from the value on the right |
3456 | hand side by whitespace. Both string and boolean vari- | |
3457 | ables may be tested. Boolean variables must be tested | |
d233b485 CR |
3458 | against the values _\bo_\bn and _\bo_\bf_\bf. |
3459 | ||
17345e5a JA |
3460 | $\b$e\ben\bnd\bdi\bif\bf This command, as seen in the previous example, terminates an $\b$i\bif\bf |
3461 | command. | |
3462 | ||
3463 | $\b$e\bel\bls\bse\be Commands in this branch of the $\b$i\bif\bf directive are executed if the | |
3464 | test fails. | |
3465 | ||
3466 | $\b$i\bin\bnc\bcl\blu\bud\bde\be | |
712f80b0 CR |
3467 | This directive takes a single filename as an argument and reads |
3468 | commands and bindings from that file. For example, the follow- | |
17345e5a JA |
3469 | ing directive would read _\b/_\be_\bt_\bc_\b/_\bi_\bn_\bp_\bu_\bt_\br_\bc: |
3470 | ||
3471 | $\b$i\bin\bnc\bcl\blu\bud\bde\be _\b/_\be_\bt_\bc_\b/_\bi_\bn_\bp_\bu_\bt_\br_\bc | |
3472 | ||
3473 | S\bSe\bea\bar\brc\bch\bhi\bin\bng\bg | |
712f80b0 | 3474 | Readline provides commands for searching through the command history |
17345e5a JA |
3475 | (see H\bHI\bIS\bST\bTO\bOR\bRY\bY below) for lines containing a specified string. There are |
3476 | 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. | |
3477 | ||
712f80b0 CR |
3478 | Incremental searches begin before the user has finished typing the |
3479 | search string. As each character of the search string is typed, read- | |
17345e5a | 3480 | line displays the next entry from the history matching the string typed |
712f80b0 CR |
3481 | so far. An incremental search requires only as many characters as |
3482 | needed to find the desired history entry. The characters present in | |
3483 | 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 | 3484 | incremental search. If that variable has not been assigned a value the |
712f80b0 CR |
3485 | Escape and Control-J characters will terminate an incremental search. |
3486 | Control-G will abort an incremental search and restore the original | |
3487 | line. When the search is terminated, the history entry containing the | |
17345e5a JA |
3488 | search string becomes the current line. |
3489 | ||
712f80b0 CR |
3490 | To find other matching entries in the history list, type Control-S or |
3491 | Control-R as appropriate. This will search backward or forward in the | |
3492 | history for the next entry matching the search string typed so far. | |
3493 | Any other key sequence bound to a readline command will terminate the | |
3494 | search and execute that command. For instance, a _\bn_\be_\bw_\bl_\bi_\bn_\be will termi- | |
17345e5a JA |
3495 | nate the search and accept the line, thereby executing the command from |
3496 | the history list. | |
3497 | ||
3498 | Readline remembers the last incremental search string. If two Control- | |
712f80b0 | 3499 | Rs are typed without any intervening characters defining a new search |
17345e5a JA |
3500 | string, any remembered search string is used. |
3501 | ||
712f80b0 CR |
3502 | Non-incremental searches read the entire search string before starting |
3503 | to search for matching history lines. The search string may be typed | |
17345e5a JA |
3504 | by the user or be part of the contents of the current line. |
3505 | ||
3506 | R\bRe\bea\bad\bdl\bli\bin\bne\be C\bCo\bom\bmm\bma\ban\bnd\bd N\bNa\bam\bme\bes\bs | |
712f80b0 | 3507 | The following is a list of the names of the commands and the default |
17345e5a JA |
3508 | key sequences to which they are bound. Command names without an accom- |
3509 | panying key sequence are unbound by default. In the following descrip- | |
712f80b0 CR |
3510 | tions, _\bp_\bo_\bi_\bn_\bt refers to the current cursor position, and _\bm_\ba_\br_\bk refers to |
3511 | a cursor position saved by the s\bse\bet\bt-\b-m\bma\bar\brk\bk command. The text between the | |
17345e5a JA |
3512 | point and mark is referred to as the _\br_\be_\bg_\bi_\bo_\bn. |
3513 | ||
3514 | C\bCo\bom\bmm\bma\ban\bnd\bds\bs f\bfo\bor\br M\bMo\bov\bvi\bin\bng\bg | |
3515 | 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) | |
3516 | Move to the start of the current line. | |
3517 | e\ben\bnd\bd-\b-o\bof\bf-\b-l\bli\bin\bne\be (\b(C\bC-\b-e\be)\b) | |
3518 | Move to the end of the line. | |
3519 | f\bfo\bor\brw\bwa\bar\brd\bd-\b-c\bch\bha\bar\br (\b(C\bC-\b-f\bf)\b) | |
3520 | Move forward a character. | |
3521 | b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-c\bch\bha\bar\br (\b(C\bC-\b-b\bb)\b) | |
3522 | Move back a character. | |
3523 | f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-f\bf)\b) | |
3524 | Move forward to the end of the next word. Words are composed of | |
3525 | alphanumeric characters (letters and digits). | |
3526 | b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-b\bb)\b) | |
712f80b0 | 3527 | Move back to the start of the current or previous word. Words |
17345e5a JA |
3528 | are composed of alphanumeric characters (letters and digits). |
3529 | s\bsh\bhe\bel\bll\bl-\b-f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd | |
712f80b0 | 3530 | Move forward to the end of the next word. Words are delimited |
17345e5a JA |
3531 | by non-quoted shell metacharacters. |
3532 | s\bsh\bhe\bel\bll\bl-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd | |
712f80b0 | 3533 | Move back to the start of the current or previous word. Words |
17345e5a | 3534 | are delimited by non-quoted shell metacharacters. |
d233b485 | 3535 | p\bpr\bre\bev\bvi\bio\bou\bus\bs-\b-s\bsc\bcr\bre\bee\ben\bn-\b-l\bli\bin\bne\be |
712f80b0 CR |
3536 | Attempt to move point to the same physical screen column on the |
3537 | previous physical screen line. This will not have the desired | |
3538 | effect if the current Readline line does not take up more than | |
3539 | one physical line or if point is not greater than the length of | |
d233b485 CR |
3540 | the prompt plus the screen width. |
3541 | n\bne\bex\bxt\bt-\b-s\bsc\bcr\bre\bee\ben\bn-\b-l\bli\bin\bne\be | |
712f80b0 | 3542 | Attempt to move point to the same physical screen column on the |
d233b485 | 3543 | next physical screen line. This will not have the desired effect |
712f80b0 CR |
3544 | if the current Readline line does not take up more than one |
3545 | physical line or if the length of the current Readline line is | |
d233b485 | 3546 | not greater than the length of the prompt plus the screen width. |
712f80b0 CR |
3547 | 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) |
3548 | Clear the screen and, if possible, the terminal's scrollback | |
3549 | buffer, then redraw the current line, leaving the current line | |
3550 | at the top of the screen. | |
17345e5a | 3551 | c\bcl\ble\bea\bar\br-\b-s\bsc\bcr\bre\bee\ben\bn (\b(C\bC-\b-l\bl)\b) |
712f80b0 CR |
3552 | Clear the screen, then redraw the current line, leaving the cur- |
3553 | rent line at the top of the screen. With an argument, refresh | |
3554 | the current line without clearing the screen. | |
17345e5a JA |
3555 | r\bre\bed\bdr\bra\baw\bw-\b-c\bcu\bur\brr\bre\ben\bnt\bt-\b-l\bli\bin\bne\be |
3556 | Refresh the current line. | |
3557 | ||
3558 | 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 | |
3559 | 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) | |
3560 | Accept the line regardless of where the cursor is. If this line | |
712f80b0 CR |
3561 | is non-empty, add it to the history list according to the state |
3562 | of the H\bHI\bIS\bST\bTC\bCO\bON\bNT\bTR\bRO\bOL\bL variable. If the line is a modified history | |
17345e5a JA |
3563 | line, then restore the history line to its original state. |
3564 | 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) | |
3565 | Fetch the previous command from the history list, moving back in | |
3566 | the list. | |
3567 | n\bne\bex\bxt\bt-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(C\bC-\b-n\bn)\b) | |
712f80b0 | 3568 | Fetch the next command from the history list, moving forward in |
17345e5a JA |
3569 | the list. |
3570 | 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) | |
3571 | Move to the first line in the history. | |
3572 | e\ben\bnd\bd-\b-o\bof\bf-\b-h\bhi\bis\bst\bto\bor\bry\by (\b(M\bM-\b->\b>)\b) | |
712f80b0 | 3573 | Move to the end of the input history, i.e., the line currently |
17345e5a JA |
3574 | being entered. |
3575 | 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) | |
712f80b0 CR |
3576 | Search backward starting at the current line and moving `up' |
3577 | through the history as necessary. This is an incremental | |
17345e5a JA |
3578 | search. |
3579 | 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) | |
712f80b0 CR |
3580 | Search forward starting at the current line and moving `down' |
3581 | through the history as necessary. This is an incremental | |
17345e5a JA |
3582 | search. |
3583 | 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) | |
3584 | Search backward through the history starting at the current line | |
712f80b0 | 3585 | using a non-incremental search for a string supplied by the |
17345e5a JA |
3586 | user. |
3587 | 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) | |
712f80b0 | 3588 | Search forward through the history using a non-incremental |
17345e5a JA |
3589 | search for a string supplied by the user. |
3590 | 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 | |
712f80b0 CR |
3591 | Search forward through the history for the string of characters |
3592 | between the start of the current line and the point. This is a | |
17345e5a JA |
3593 | non-incremental search. |
3594 | 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 | |
3595 | Search backward through the history for the string of characters | |
712f80b0 | 3596 | between the start of the current line and the point. This is a |
17345e5a | 3597 | non-incremental search. |
d233b485 CR |
3598 | 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 |
3599 | Search backward through the history for the string of characters | |
712f80b0 CR |
3600 | between the start of the current line and the current cursor po- |
3601 | sition (the _\bp_\bo_\bi_\bn_\bt). The search string may match anywhere in a | |
d233b485 CR |
3602 | history line. This is a non-incremental search. |
3603 | 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 | |
712f80b0 | 3604 | Search forward through the history for the string of characters |
d233b485 | 3605 | between the start of the current line and the point. The search |
712f80b0 CR |
3606 | string may match anywhere in a history line. This is a non-in- |
3607 | cremental search. | |
17345e5a | 3608 | 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) |
712f80b0 | 3609 | Insert the first argument to the previous command (usually the |
17345e5a | 3610 | second word on the previous line) at point. With an argument _\bn, |
712f80b0 CR |
3611 | insert the _\bnth word from the previous command (the words in the |
3612 | previous command begin with word 0). A negative argument in- | |
3613 | serts the _\bnth word from the end of the previous command. Once | |
3614 | the argument _\bn is computed, the argument is extracted as if the | |
17345e5a JA |
3615 | "!_\bn" history expansion had been specified. |
3616 | 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) | |
712f80b0 | 3617 | Insert the last argument to the previous command (the last word |
495aee44 | 3618 | of the previous history entry). With a numeric argument, behave |
712f80b0 CR |
3619 | 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 |
3620 | move back through the history list, inserting the last word (or | |
3621 | the word specified by the argument to the first call) of each | |
495aee44 | 3622 | line in turn. Any numeric argument supplied to these successive |
712f80b0 CR |
3623 | calls determines the direction to move through the history. A |
3624 | negative argument switches the direction through the history | |
495aee44 | 3625 | (back or forward). The history expansion facilities are used to |
ac50fbac CR |
3626 | extract the last word, as if the "!$" history expansion had been |
3627 | specified. | |
17345e5a JA |
3628 | 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) |
3629 | Expand the line as the shell does. This performs alias and his- | |
3630 | tory expansion as well as all of the shell word expansions. See | |
a0c0a00f | 3631 | 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 | 3632 | 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) |
712f80b0 CR |
3633 | Perform history expansion on the current line. See H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bX-\b- |
3634 | P\bPA\bAN\bNS\bSI\bIO\bON\bN below for a description of history expansion. | |
17345e5a | 3635 | m\bma\bag\bgi\bic\bc-\b-s\bsp\bpa\bac\bce\be |
712f80b0 | 3636 | Perform history expansion on the current line and insert a |
17345e5a JA |
3637 | 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 |
3638 | expansion. | |
3639 | a\bal\bli\bia\bas\bs-\b-e\bex\bxp\bpa\ban\bnd\bd-\b-l\bli\bin\bne\be | |
712f80b0 | 3640 | Perform alias expansion on the current line. See A\bAL\bLI\bIA\bAS\bSE\bES\bS above |
17345e5a JA |
3641 | for a description of alias expansion. |
3642 | 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 | |
3643 | Perform history and alias expansion on the current line. | |
3644 | 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) | |
3645 | A synonym for y\bya\ban\bnk\bk-\b-l\bla\bas\bst\bt-\b-a\bar\brg\bg. | |
3646 | 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) | |
712f80b0 CR |
3647 | Accept the current line for execution and fetch the next line |
3648 | relative to the current line from the history for editing. A | |
3649 | numeric argument, if supplied, specifies the history entry to | |
d233b485 CR |
3650 | use instead of the current line. |
3651 | 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) | |
712f80b0 CR |
3652 | Invoke an editor on the current command line, and execute the |
3653 | 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- | |
3654 | I\bIT\bTO\bOR\bR, and _\be_\bm_\ba_\bc_\bs as the editor, in that order. | |
17345e5a JA |
3655 | |
3656 | 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 | 3657 | _\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) |
712f80b0 CR |
3658 | The character indicating end-of-file as set, for example, by |
3659 | ``stty''. If this character is read when there are no charac- | |
3660 | ters on the line, and point is at the beginning of the line, | |
ac50fbac | 3661 | Readline interprets it as the end of input and returns E\bEO\bOF\bF. |
17345e5a | 3662 | d\bde\bel\ble\bet\bte\be-\b-c\bch\bha\bar\br (\b(C\bC-\b-d\bd)\b) |
ac50fbac CR |
3663 | Delete the character at point. If this function is bound to the |
3664 | same character as the tty E\bEO\bOF\bF character, as C\bC-\b-d\bd commonly is, see | |
3665 | above for the effects. | |
17345e5a | 3666 | 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) |
712f80b0 | 3667 | Delete the character behind the cursor. When given a numeric |
17345e5a JA |
3668 | argument, save the deleted text on the kill ring. |
3669 | 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 | |
712f80b0 | 3670 | Delete the character under the cursor, unless the cursor is at |
17345e5a JA |
3671 | the end of the line, in which case the character behind the cur- |
3672 | sor is deleted. | |
3673 | 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) | |
712f80b0 | 3674 | Add the next character typed to the line verbatim. This is how |
17345e5a JA |
3675 | to insert characters like C\bC-\b-q\bq, for example. |
3676 | t\bta\bab\bb-\b-i\bin\bns\bse\ber\brt\bt (\b(C\bC-\b-v\bv T\bTA\bAB\bB)\b) | |
3677 | Insert a tab character. | |
3678 | 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) | |
3679 | Insert the character typed. | |
3680 | t\btr\bra\ban\bns\bsp\bpo\bos\bse\be-\b-c\bch\bha\bar\brs\bs (\b(C\bC-\b-t\bt)\b) | |
712f80b0 CR |
3681 | Drag the character before point forward over the character at |
3682 | point, moving point forward as well. If point is at the end of | |
3683 | the line, then this transposes the two characters before point. | |
17345e5a JA |
3684 | Negative arguments have no effect. |
3685 | t\btr\bra\ban\bns\bsp\bpo\bos\bse\be-\b-w\bwo\bor\brd\bds\bs (\b(M\bM-\b-t\bt)\b) | |
712f80b0 CR |
3686 | Drag the word before point past the word after point, moving |
3687 | point over that word as well. If point is at the end of the | |
17345e5a JA |
3688 | line, this transposes the last two words on the line. |
3689 | u\bup\bpc\bca\bas\bse\be-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-u\bu)\b) | |
712f80b0 CR |
3690 | Uppercase the current (or following) word. With a negative ar- |
3691 | gument, uppercase the previous word, but do not move point. | |
17345e5a | 3692 | d\bdo\bow\bwn\bnc\bca\bas\bse\be-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-l\bl)\b) |
712f80b0 CR |
3693 | Lowercase the current (or following) word. With a negative ar- |
3694 | gument, lowercase the previous word, but do not move point. | |
17345e5a | 3695 | c\bca\bap\bpi\bit\bta\bal\bli\biz\bze\be-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-c\bc)\b) |
712f80b0 CR |
3696 | Capitalize the current (or following) word. With a negative ar- |
3697 | gument, capitalize the previous word, but do not move point. | |
17345e5a | 3698 | o\bov\bve\ber\brw\bwr\bri\bit\bte\be-\b-m\bmo\bod\bde\be |
712f80b0 | 3699 | Toggle overwrite mode. With an explicit positive numeric argu- |
17345e5a JA |
3700 | ment, switches to overwrite mode. With an explicit non-positive |
3701 | numeric argument, switches to insert mode. This command affects | |
712f80b0 | 3702 | only e\bem\bma\bac\bcs\bs mode; v\bvi\bi mode does overwrite differently. Each call |
17345e5a | 3703 | to _\br_\be_\ba_\bd_\bl_\bi_\bn_\be_\b(_\b) starts in insert mode. In overwrite mode, charac- |
712f80b0 CR |
3704 | ters bound to s\bse\bel\blf\bf-\b-i\bin\bns\bse\ber\brt\bt replace the text at point rather than |
3705 | pushing the text to the right. Characters bound to b\bba\bac\bck\bk-\b- | |
3706 | 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 |
3707 | space. By default, this command is unbound. |
3708 | ||
3709 | K\bKi\bil\bll\bli\bin\bng\bg a\ban\bnd\bd Y\bYa\ban\bnk\bki\bin\bng\bg | |
3710 | k\bki\bil\bll\bl-\b-l\bli\bin\bne\be (\b(C\bC-\b-k\bk)\b) | |
3711 | Kill the text from point to the end of the line. | |
3712 | 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) | |
3713 | Kill backward to the beginning of the line. | |
3714 | 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) | |
712f80b0 | 3715 | Kill backward from point to the beginning of the line. The |
17345e5a JA |
3716 | killed text is saved on the kill-ring. |
3717 | k\bki\bil\bll\bl-\b-w\bwh\bho\bol\ble\be-\b-l\bli\bin\bne\be | |
712f80b0 | 3718 | Kill all characters on the current line, no matter where point |
17345e5a JA |
3719 | is. |
3720 | k\bki\bil\bll\bl-\b-w\bwo\bor\brd\bd (\b(M\bM-\b-d\bd)\b) | |
712f80b0 CR |
3721 | Kill from point to the end of the current word, or if between |
3722 | words, to the end of the next word. Word boundaries are the | |
17345e5a JA |
3723 | same as those used by f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
3724 | 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) | |
712f80b0 | 3725 | Kill the word behind point. Word boundaries are the same as |
17345e5a | 3726 | those used by b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
a0c0a00f | 3727 | s\bsh\bhe\bel\bll\bl-\b-k\bki\bil\bll\bl-\b-w\bwo\bor\brd\bd |
712f80b0 CR |
3728 | Kill from point to the end of the current word, or if between |
3729 | words, to the end of the next word. Word boundaries are the | |
17345e5a | 3730 | 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 | 3731 | 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 |
712f80b0 | 3732 | Kill the word behind point. Word boundaries are the same as |
17345e5a JA |
3733 | 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. |
3734 | 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) | |
712f80b0 | 3735 | Kill the word behind point, using white space as a word bound- |
17345e5a JA |
3736 | ary. The killed text is saved on the kill-ring. |
3737 | u\bun\bni\bix\bx-\b-f\bfi\bil\ble\ben\bna\bam\bme\be-\b-r\bru\bub\bbo\bou\but\bt | |
712f80b0 CR |
3738 | Kill the word behind point, using white space and the slash |
3739 | character as the word boundaries. The killed text is saved on | |
17345e5a JA |
3740 | the kill-ring. |
3741 | 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) | |
3742 | Delete all spaces and tabs around point. | |
3743 | k\bki\bil\bll\bl-\b-r\bre\beg\bgi\bio\bon\bn | |
3744 | Kill the text in the current region. | |
3745 | c\bco\bop\bpy\by-\b-r\bre\beg\bgi\bio\bon\bn-\b-a\bas\bs-\b-k\bki\bil\bll\bl | |
3746 | Copy the text in the region to the kill buffer. | |
3747 | c\bco\bop\bpy\by-\b-b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd | |
712f80b0 | 3748 | Copy the word before point to the kill buffer. The word bound- |
17345e5a JA |
3749 | aries are the same as b\bba\bac\bck\bkw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
3750 | c\bco\bop\bpy\by-\b-f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd | |
712f80b0 | 3751 | Copy the word following point to the kill buffer. The word |
17345e5a JA |
3752 | boundaries are the same as f\bfo\bor\brw\bwa\bar\brd\bd-\b-w\bwo\bor\brd\bd. |
3753 | y\bya\ban\bnk\bk (\b(C\bC-\b-y\by)\b) | |
3754 | Yank the top of the kill ring into the buffer at point. | |
3755 | y\bya\ban\bnk\bk-\b-p\bpo\bop\bp (\b(M\bM-\b-y\by)\b) | |
712f80b0 | 3756 | Rotate the kill ring, and yank the new top. Only works follow- |
17345e5a JA |
3757 | ing y\bya\ban\bnk\bk or y\bya\ban\bnk\bk-\b-p\bpo\bop\bp. |
3758 | ||
3759 | N\bNu\bum\bme\ber\bri\bic\bc A\bAr\brg\bgu\bum\bme\ben\bnt\bts\bs | |
3760 | 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) | |
712f80b0 | 3761 | Add this digit to the argument already accumulating, or start a |
17345e5a JA |
3762 | new argument. M-- starts a negative argument. |
3763 | u\bun\bni\biv\bve\ber\brs\bsa\bal\bl-\b-a\bar\brg\bgu\bum\bme\ben\bnt\bt | |
712f80b0 CR |
3764 | This is another way to specify an argument. If this command is |
3765 | followed by one or more digits, optionally with a leading minus | |
3766 | sign, those digits define the argument. If the command is fol- | |
3767 | 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- | |
3768 | meric argument, but is otherwise ignored. As a special case, if | |
3769 | this command is immediately followed by a character that is nei- | |
3770 | ther a digit nor minus sign, the argument count for the next | |
3771 | command is multiplied by four. The argument count is initially | |
3772 | one, so executing this function the first time makes the argu- | |
17345e5a JA |
3773 | ment count four, a second time makes the argument count sixteen, |
3774 | and so on. | |
3775 | ||
3776 | C\bCo\bom\bmp\bpl\ble\bet\bti\bin\bng\bg | |
3777 | c\bco\bom\bmp\bpl\ble\bet\bte\be (\b(T\bTA\bAB\bB)\b) | |
712f80b0 | 3778 | Attempt to perform completion on the text before point. B\bBa\bas\bsh\bh |
17345e5a | 3779 | attempts completion treating the text as a variable (if the text |
712f80b0 CR |
3780 | begins with $\b$), username (if the text begins with ~\b~), hostname |
3781 | (if the text begins with @\b@), or command (including aliases and | |
17345e5a JA |
3782 | functions) in turn. If none of these produces a match, filename |
3783 | completion is attempted. | |
3784 | 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) | |
3785 | List the possible completions of the text before point. | |
3786 | 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) | |
712f80b0 | 3787 | Insert all completions of the text before point that would have |
17345e5a JA |
3788 | 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. |
3789 | m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be | |
712f80b0 CR |
3790 | Similar to c\bco\bom\bmp\bpl\ble\bet\bte\be, but replaces the word to be completed with |
3791 | a single match from the list of possible completions. Repeated | |
3792 | execution of m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be steps through the list of possible | |
3793 | completions, inserting each match in turn. At the end of the | |
17345e5a JA |
3794 | list of completions, the bell is rung (subject to the setting of |
3795 | b\bbe\bel\bll\bl-\b-s\bst\bty\byl\ble\be) and the original text is restored. An argument of _\bn | |
712f80b0 CR |
3796 | moves _\bn positions forward in the list of matches; a negative ar- |
3797 | gument may be used to move backward through the list. This com- | |
3798 | mand is intended to be bound to T\bTA\bAB\bB, but is unbound by default. | |
495aee44 CR |
3799 | 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 |
3800 | Identical to m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be, but moves backward through the list | |
0001803f CR |
3801 | of possible completions, as if m\bme\ben\bnu\bu-\b-c\bco\bom\bmp\bpl\ble\bet\bte\be had been given a |
3802 | negative argument. This command is unbound by default. | |
17345e5a JA |
3803 | d\bde\bel\ble\bet\bte\be-\b-c\bch\bha\bar\br-\b-o\bor\br-\b-l\bli\bis\bst\bt |
3804 | Deletes the character under the cursor if not at the beginning | |
3805 | 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 | |
3806 | 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 | |
3807 | is unbound by default. | |
3808 | 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) | |
3809 | Attempt filename completion on the text before point. | |
3810 | 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) | |
3811 | List the possible completions of the text before point, treating | |
3812 | it as a filename. | |
3813 | 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) | |
3814 | Attempt completion on the text before point, treating it as a | |
3815 | username. | |
3816 | 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) | |
3817 | List the possible completions of the text before point, treating | |
3818 | it as a username. | |
3819 | 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) | |
3820 | Attempt completion on the text before point, treating it as a | |
3821 | shell variable. | |
3822 | 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) | |
3823 | List the possible completions of the text before point, treating | |
3824 | it as a shell variable. | |
3825 | 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) | |
3826 | Attempt completion on the text before point, treating it as a | |
3827 | hostname. | |
3828 | 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) | |
3829 | List the possible completions of the text before point, treating | |
3830 | it as a hostname. | |
3831 | c\bco\bom\bmp\bpl\ble\bet\bte\be-\b-c\bco\bom\bmm\bma\ban\bnd\bd (\b(M\bM-\b-!\b!)\b) | |
3832 | Attempt completion on the text before point, treating it as a | |
3833 | command name. Command completion attempts to match the text | |
3834 | against aliases, reserved words, shell functions, shell | |
3835 | builtins, and finally executable filenames, in that order. | |
3836 | 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) | |
3837 | List the possible completions of the text before point, treating | |
3838 | it as a command name. | |
3839 | 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) | |
3840 | Attempt completion on the text before point, comparing the text | |
3841 | against lines from the history list for possible completion | |
3842 | matches. | |
3843 | d\bda\bab\bbb\bbr\bre\bev\bv-\b-e\bex\bxp\bpa\ban\bnd\bd | |
3844 | Attempt menu completion on the text before point, comparing the | |
3845 | text against lines from the history list for possible completion | |
3846 | matches. | |
3847 | 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) | |
3848 | Perform filename completion and insert the list of possible com- | |
3849 | pletions enclosed within braces so the list is available to the | |
3850 | shell (see B\bBr\bra\bac\bce\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn above). | |
3851 | ||
3852 | K\bKe\bey\byb\bbo\boa\bar\brd\bd M\bMa\bac\bcr\bro\bos\bs | |
3853 | 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) | |
3854 | Begin saving the characters typed into the current keyboard | |
3855 | macro. | |
3856 | e\ben\bnd\bd-\b-k\bkb\bbd\bd-\b-m\bma\bac\bcr\bro\bo (\b(C\bC-\b-x\bx )\b))\b) | |
3857 | Stop saving the characters typed into the current keyboard macro | |
3858 | and store the definition. | |
3859 | 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) | |
3860 | Re-execute the last keyboard macro defined, by making the char- | |
3861 | acters in the macro appear as if typed at the keyboard. | |
ac50fbac CR |
3862 | 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) |
3863 | Print the last keyboard macro defined in a format suitable for | |
3864 | the _\bi_\bn_\bp_\bu_\bt_\br_\bc file. | |
17345e5a JA |
3865 | |
3866 | M\bMi\bis\bsc\bce\bel\bll\bla\ban\bne\beo\bou\bus\bs | |
3867 | 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) | |
ac50fbac | 3868 | Read in the contents of the _\bi_\bn_\bp_\bu_\bt_\br_\bc file, and incorporate any |
17345e5a JA |
3869 | bindings or variable assignments found there. |
3870 | a\bab\bbo\bor\brt\bt (\b(C\bC-\b-g\bg)\b) | |
ac50fbac | 3871 | Abort the current editing command and ring the terminal's bell |
17345e5a | 3872 | (subject to the setting of b\bbe\bel\bll\bl-\b-s\bst\bty\byl\ble\be). |
d233b485 CR |
3873 | 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) |
3874 | If the metafied character _\bx is uppercase, run the command that | |
3875 | is bound to the corresponding metafied lowercase character. The | |
3876 | behavior is undefined if _\bx is already lowercase. | |
17345e5a JA |
3877 | p\bpr\bre\bef\bfi\bix\bx-\b-m\bme\bet\bta\ba (\b(E\bES\bSC\bC)\b) |
3878 | Metafy the next character typed. E\bES\bSC\bC f\bf is equivalent to M\bMe\bet\bta\ba-\b-f\bf. | |
3879 | u\bun\bnd\bdo\bo (\b(C\bC-\b-_\b_,\b, C\bC-\b-x\bx C\bC-\b-u\bu)\b) | |
3880 | Incremental undo, separately remembered for each line. | |
3881 | r\bre\bev\bve\ber\brt\bt-\b-l\bli\bin\bne\be (\b(M\bM-\b-r\br)\b) | |
d233b485 CR |
3882 | Undo all changes made to this line. This is like executing the |
3883 | u\bun\bnd\bdo\bo command enough times to return the line to its initial | |
17345e5a JA |
3884 | state. |
3885 | t\bti\bil\bld\bde\be-\b-e\bex\bxp\bpa\ban\bnd\bd (\b(M\bM-\b-&\b&)\b) | |
3886 | Perform tilde expansion on the current word. | |
3887 | 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) | |
d233b485 | 3888 | Set the mark to the point. If a numeric argument is supplied, |
17345e5a JA |
3889 | the mark is set to that position. |
3890 | 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) | |
d233b485 CR |
3891 | Swap the point with the mark. The current cursor position is |
3892 | set to the saved position, and the old cursor position is saved | |
17345e5a JA |
3893 | as the mark. |
3894 | c\bch\bha\bar\bra\bac\bct\bte\ber\br-\b-s\bse\bea\bar\brc\bch\bh (\b(C\bC-\b-]\b])\b) | |
3895 | A character is read and point is moved to the next occurrence of | |
d233b485 | 3896 | that character. A negative count searches for previous occur- |
17345e5a JA |
3897 | rences. |
3898 | 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) | |
d233b485 CR |
3899 | A character is read and point is moved to the previous occur- |
3900 | rence of that character. A negative count searches for subse- | |
17345e5a | 3901 | quent occurrences. |
495aee44 | 3902 | s\bsk\bki\bip\bp-\b-c\bcs\bsi\bi-\b-s\bse\beq\bqu\bue\ben\bnc\bce\be |
d233b485 CR |
3903 | Read enough characters to consume a multi-key sequence such as |
3904 | those defined for keys like Home and End. Such sequences begin | |
0001803f | 3905 | with a Control Sequence Indicator (CSI), usually ESC-[. If this |
d233b485 CR |
3906 | sequence is bound to "\[", keys producing such sequences will |
3907 | have no effect unless explicitly bound to a readline command, | |
3908 | instead of inserting stray characters into the editing buffer. | |
0001803f | 3909 | This is unbound by default, but usually bound to ESC-[. |
17345e5a | 3910 | i\bin\bns\bse\ber\brt\bt-\b-c\bco\bom\bmm\bme\ben\bnt\bt (\b(M\bM-\b-#\b#)\b) |
d233b485 CR |
3911 | Without a numeric argument, the value of the readline c\bco\bom\bm-\b- |
3912 | m\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn variable is inserted at the beginning of the current | |
17345e5a | 3913 | line. If a numeric argument is supplied, this command acts as a |
d233b485 CR |
3914 | toggle: if the characters at the beginning of the line do not |
3915 | 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 | 3916 | wise the characters in c\bco\bom\bmm\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn are deleted from the begin- |
d233b485 CR |
3917 | ning of the line. In either case, the line is accepted as if a |
3918 | newline had been typed. The default value of c\bco\bom\bmm\bme\ben\bnt\bt-\b-b\bbe\beg\bgi\bin\bn | |
3919 | causes this command to make the current line a shell comment. | |
712f80b0 CR |
3920 | If a numeric argument causes the comment character to be re- |
3921 | moved, the line will be executed by the shell. | |
17345e5a | 3922 | 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) |
712f80b0 CR |
3923 | The word before point is treated as a pattern for pathname ex- |
3924 | pansion, with an asterisk implicitly appended. This pattern is | |
3925 | used to generate a list of matching filenames for possible com- | |
3926 | pletions. | |
17345e5a | 3927 | 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) |
712f80b0 CR |
3928 | The word before point is treated as a pattern for pathname ex- |
3929 | pansion, and the list of matching filenames is inserted, replac- | |
3930 | ing the word. If a numeric argument is supplied, an asterisk is | |
3931 | appended before pathname expansion. | |
17345e5a | 3932 | 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 |
3933 | The list of expansions that would have been generated by |
3934 | 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 | |
3935 | numeric argument is supplied, an asterisk is appended before | |
17345e5a JA |
3936 | pathname expansion. |
3937 | d\bdu\bum\bmp\bp-\b-f\bfu\bun\bnc\bct\bti\bio\bon\bns\bs | |
d233b485 | 3938 | Print all of the functions and their key bindings to the read- |
17345e5a | 3939 | line output stream. If a numeric argument is supplied, the out- |
d233b485 | 3940 | put is formatted in such a way that it can be made part of an |
17345e5a JA |
3941 | _\bi_\bn_\bp_\bu_\bt_\br_\bc file. |
3942 | d\bdu\bum\bmp\bp-\b-v\bva\bar\bri\bia\bab\bbl\ble\bes\bs | |
3943 | Print all of the settable readline variables and their values to | |
d233b485 CR |
3944 | the readline output stream. If a numeric argument is supplied, |
3945 | the output is formatted in such a way that it can be made part | |
17345e5a JA |
3946 | of an _\bi_\bn_\bp_\bu_\bt_\br_\bc file. |
3947 | d\bdu\bum\bmp\bp-\b-m\bma\bac\bcr\bro\bos\bs | |
d233b485 CR |
3948 | Print all of the readline key sequences bound to macros and the |
3949 | strings they output. If a numeric argument is supplied, the | |
17345e5a JA |
3950 | output is formatted in such a way that it can be made part of an |
3951 | _\bi_\bn_\bp_\bu_\bt_\br_\bc file. | |
3952 | 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 | 3953 | Display version information about the current instance of b\bba\bas\bsh\bh. |
17345e5a JA |
3954 | |
3955 | 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 |
3956 | When word completion is attempted for an argument to a command for |
3957 | which a completion specification (a _\bc_\bo_\bm_\bp_\bs_\bp_\be_\bc) has been defined using | |
3958 | 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 | 3959 | mable completion facilities are invoked. |
17345e5a | 3960 | |
d233b485 CR |
3961 | First, the command name is identified. If the command word is the |
3962 | empty string (completion attempted at the beginning of an empty line), | |
3963 | any compspec defined with the -\b-E\bE option to c\bco\bom\bmp\bpl\ble\bet\bte\be is used. If a | |
3964 | compspec has been defined for that command, the compspec is used to | |
0001803f | 3965 | generate the list of possible completions for the word. If the command |
d233b485 CR |
3966 | word is a full pathname, a compspec for the full pathname is searched |
3967 | for first. If no compspec is found for the full pathname, an attempt | |
3968 | is made to find a compspec for the portion following the final slash. | |
3969 | If those searches do not result in a compspec, any compspec defined | |
3970 | 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 | |
3971 | default compspec, b\bba\bas\bsh\bh attempts alias expansion on the command word as | |
3972 | a final resort, and attempts to find a compspec for the command word | |
3973 | from any successful expansion. | |
17345e5a | 3974 | |
ac50fbac CR |
3975 | Once a compspec has been found, it is used to generate the list of |
3976 | matching words. If a compspec is not found, the default b\bba\bas\bsh\bh comple- | |
17345e5a JA |
3977 | tion as described above under C\bCo\bom\bmp\bpl\ble\bet\bti\bin\bng\bg is performed. |
3978 | ||
ac50fbac CR |
3979 | First, the actions specified by the compspec are used. Only matches |
3980 | which are prefixed by the word being completed are returned. When the | |
3981 | -\b-f\bf or -\b-d\bd option is used for filename or directory name completion, the | |
17345e5a JA |
3982 | shell variable F\bFI\bIG\bGN\bNO\bOR\bRE\bE is used to filter the matches. |
3983 | ||
712f80b0 CR |
3984 | Any completions specified by a pathname expansion pattern to the -\b-G\bG op- |
3985 | tion are generated next. The words generated by the pattern need not | |
ac50fbac | 3986 | match the word being completed. The G\bGL\bLO\bOB\bBI\bIG\bGN\bNO\bOR\bRE\bE shell variable is not |
17345e5a JA |
3987 | used to filter the matches, but the F\bFI\bIG\bGN\bNO\bOR\bRE\bE variable is used. |
3988 | ||
ac50fbac CR |
3989 | Next, the string specified as the argument to the -\b-W\bW option is consid- |
3990 | ered. The string is first split using the characters in the I\bIF\bFS\bS spe- | |
3991 | cial variable as delimiters. Shell quoting is honored. Each word is | |
3992 | then expanded using brace expansion, tilde expansion, parameter and | |
3993 | variable expansion, command substitution, and arithmetic expansion, as | |
17345e5a JA |
3994 | described above under E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN. The results are split using the rules |
3995 | described above under W\bWo\bor\brd\bd S\bSp\bpl\bli\bit\btt\bti\bin\bng\bg. The results of the expansion are | |
3996 | prefix-matched against the word being completed, and the matching words | |
3997 | become the possible completions. | |
3998 | ||
ac50fbac CR |
3999 | After these matches have been generated, any shell function or command |
4000 | specified with the -\b-F\bF and -\b-C\bC options is invoked. When the command or | |
17345e5a JA |
4001 | 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 |
4002 | 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 |
4003 | 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 |
4004 | variables are also set. When the function or command is invoked, the | |
712f80b0 CR |
4005 | first argument ($\b$1\b1) is the name of the command whose arguments are be- |
4006 | ing completed, the second argument ($\b$2\b2) is the word being completed, | |
ac50fbac CR |
4007 | and the third argument ($\b$3\b3) is the word preceding the word being com- |
4008 | pleted on the current command line. No filtering of the generated com- | |
4009 | pletions against the word being completed is performed; the function or | |
4010 | command has complete freedom in generating the matches. | |
4011 | ||
4012 | Any function specified with -\b-F\bF is invoked first. The function may use | |
4013 | any of the shell facilities, including the c\bco\bom\bmp\bpg\bge\ben\bn builtin described | |
4014 | below, to generate the matches. It must put the possible completions | |
4015 | in the C\bCO\bOM\bMP\bPR\bRE\bEP\bPL\bLY\bY array variable, one per array element. | |
4016 | ||
4017 | Next, any command specified with the -\b-C\bC option is invoked in an envi- | |
4018 | ronment equivalent to command substitution. It should print a list of | |
4019 | completions, one per line, to the standard output. Backslash may be | |
17345e5a JA |
4020 | used to escape a newline, if necessary. |
4021 | ||
ac50fbac CR |
4022 | After all of the possible completions are generated, any filter speci- |
4023 | fied with the -\b-X\bX option is applied to the list. The filter is a pat- | |
4024 | tern as used for pathname expansion; a &\b& in the pattern is replaced | |
4025 | with the text of the word being completed. A literal &\b& may be escaped | |
4026 | with a backslash; the backslash is removed before attempting a match. | |
4027 | Any completion that matches the pattern will be removed from the list. | |
17345e5a | 4028 | A leading !\b! negates the pattern; in this case any completion not match- |
a0c0a00f CR |
4029 | ing the pattern will be removed. If the n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh shell option is |
4030 | enabled, the match is performed without regard to the case of alpha- | |
4031 | betic characters. | |
17345e5a JA |
4032 | |
4033 | Finally, any prefix and suffix specified with the -\b-P\bP and -\b-S\bS options are | |
4034 | added to each member of the completion list, and the result is returned | |
4035 | to the readline completion code as the list of possible completions. | |
4036 | ||
ac50fbac | 4037 | If the previously-applied actions do not generate any matches, and the |
712f80b0 CR |
4038 | -\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- |
4039 | fined, directory name completion is attempted. | |
17345e5a | 4040 | |
ac50fbac | 4041 | 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 |
4042 | was defined, directory name completion is attempted and any matches are |
4043 | added to the results of the other actions. | |
4044 | ||
ac50fbac CR |
4045 | By default, if a compspec is found, whatever it generates is returned |
4046 | to the completion code as the full set of possible completions. The | |
17345e5a JA |
4047 | default b\bba\bas\bsh\bh completions are not attempted, and the readline default of |
4048 | 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 | 4049 | 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 | 4050 | pletions are attempted if the compspec generates no matches. If the -\b-o\bo |
ac50fbac CR |
4051 | 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, |
4052 | readline's default completion will be performed if the compspec (and, | |
17345e5a JA |
4053 | if attempted, the default b\bba\bas\bsh\bh completions) generate no matches. |
4054 | ||
ac50fbac CR |
4055 | When a compspec indicates that directory name completion is desired, |
4056 | the programmable completion functions force readline to append a slash | |
4057 | to completed names which are symbolic links to directories, subject to | |
4058 | 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 |
4059 | 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. |
4060 | ||
ac50fbac CR |
4061 | There is some support for dynamically modifying completions. This is |
4062 | most useful when used in combination with a default completion speci- | |
4063 | fied with c\bco\bom\bmp\bpl\ble\bet\bte\be -\b-D\bD. It's possible for shell functions executed as | |
4064 | completion handlers to indicate that completion should be retried by | |
4065 | returning an exit status of 124. If a shell function returns 124, and | |
0001803f | 4066 | changes the compspec associated with the command on which completion is |
ac50fbac | 4067 | being attempted (supplied as the first argument when the function is |
0001803f | 4068 | executed), programmable completion restarts from the beginning, with an |
ac50fbac CR |
4069 | attempt to find a new compspec for that command. This allows a set of |
4070 | completions to be built dynamically as completion is attempted, rather | |
0001803f CR |
4071 | than being loaded all at once. |
4072 | ||
ac50fbac | 4073 | For instance, assuming that there is a library of compspecs, each kept |
712f80b0 CR |
4074 | in a file corresponding to the name of the command, the following de- |
4075 | fault completion function would load completions dynamically: | |
0001803f CR |
4076 | |
4077 | _completion_loader() | |
4078 | { | |
4079 | . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 | |
4080 | } | |
ac50fbac | 4081 | complete -D -F _completion_loader -o bashdefault -o default |
0001803f CR |
4082 | |
4083 | ||
17345e5a | 4084 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
ac50fbac | 4085 | 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 | 4086 | provides access to the _\bc_\bo_\bm_\bm_\ba_\bn_\bd _\bh_\bi_\bs_\bt_\bo_\br_\by, the list of commands previously |
ac50fbac | 4087 | typed. The value of the H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE variable is used as the number of |
17345e5a | 4088 | commands to save in a history list. The text of the last H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE com- |
ac50fbac CR |
4089 | mands (default 500) is saved. The shell stores each command in the |
4090 | history list prior to parameter and variable expansion (see E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
4091 | above) but after history expansion is performed, subject to the values | |
17345e5a JA |
4092 | 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. |
4093 | ||
4094 | On startup, the history is initialized from the file named by the vari- | |
ac50fbac CR |
4095 | 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 |
4096 | of H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE is truncated, if necessary, to contain no more than the | |
4097 | 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- | |
4098 | S\bSI\bIZ\bZE\bE is unset, or set to null, a non-numeric value, or a numeric value | |
4099 | less than zero, the history file is not truncated. When the history | |
4100 | file is read, lines beginning with the history comment character fol- | |
d233b485 CR |
4101 | lowed immediately by a digit are interpreted as timestamps for the fol- |
4102 | lowing history line. These timestamps are optionally displayed depend- | |
ac50fbac CR |
4103 | 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 |
4104 | history enabled exits, the last $\b$H\bHI\bIS\bST\bTS\bSI\bIZ\bZE\bE lines are copied from the | |
4105 | 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 | |
4106 | (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 | |
4107 | lines are appended to the history file, otherwise the history file is | |
712f80b0 CR |
4108 | overwritten. If H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE is unset, or if the history file is un- |
4109 | 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 | |
4110 | set, time stamps are written to the history file, marked with the his- | |
4111 | tory comment character, so they may be preserved across shell sessions. | |
4112 | This uses the history comment character to distinguish timestamps from | |
4113 | other history lines. After saving the history, the history file is | |
4114 | 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 | |
4115 | is unset, or set to null, a non-numeric value, or a numeric value less | |
4116 | than zero, the history file is not truncated. | |
17345e5a JA |
4117 | |
4118 | 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 | |
4119 | to list or edit and re-execute a portion of the history list. The h\bhi\bis\bs-\b- | |
712f80b0 CR |
4120 | t\bto\bor\bry\by builtin may be used to display or modify the history list and ma- |
4121 | nipulate the history file. When using command-line editing, search | |
17345e5a JA |
4122 | commands are available in each editing mode that provide access to the |
4123 | history list. | |
4124 | ||
4125 | The shell allows control over which commands are saved on the history | |
4126 | 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 | |
4127 | shell to save only a subset of the commands entered. The c\bcm\bmd\bdh\bhi\bis\bst\bt shell | |
4128 | option, if enabled, causes the shell to attempt to save each line of a | |
4129 | multi-line command in the same history entry, adding semicolons where | |
4130 | necessary to preserve syntactic correctness. The l\bli\bit\bth\bhi\bis\bst\bt shell option | |
4131 | causes the shell to save the command with embedded newlines instead of | |
4132 | semicolons. See the description of the s\bsh\bho\bop\bpt\bt builtin below under S\bSH\bHE\bEL\bLL\bL | |
712f80b0 CR |
4133 | 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- |
4134 | tions. | |
17345e5a JA |
4135 | |
4136 | H\bHI\bIS\bST\bTO\bOR\bRY\bY E\bEX\bXP\bPA\bAN\bNS\bSI\bIO\bON\bN | |
4137 | The shell supports a history expansion feature that is similar to the | |
d233b485 | 4138 | history expansion in c\bcs\bsh\bh. This section describes what syntax features |
17345e5a JA |
4139 | are available. This feature is enabled by default for interactive |
4140 | shells, and can be disabled using the +\b+H\bH option to the s\bse\bet\bt builtin com- | |
4141 | 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 | |
4142 | perform history expansion by default. | |
4143 | ||
4144 | History expansions introduce words from the history list into the input | |
4145 | stream, making it easy to repeat commands, insert the arguments to a | |
4146 | previous command into the current input line, or fix errors in previous | |
4147 | commands quickly. | |
4148 | ||
4149 | History expansion is performed immediately after a complete line is | |
d233b485 | 4150 | read, before the shell breaks it into words, and is performed on each |
712f80b0 CR |
4151 | line individually without taking quoting on previous lines into ac- |
4152 | count. It takes place in two parts. The first is to determine which | |
d233b485 CR |
4153 | line from the history list to use during substitution. The second is |
4154 | to select portions of that line for inclusion into the current one. | |
4155 | The line selected from the history is the _\be_\bv_\be_\bn_\bt, and the portions of | |
4156 | that line that are acted upon are _\bw_\bo_\br_\bd_\bs. Various _\bm_\bo_\bd_\bi_\bf_\bi_\be_\br_\bs are avail- | |
4157 | able to manipulate the selected words. The line is broken into words | |
4158 | in the same fashion as when reading input, so that several _\bm_\be_\bt_\ba_\bc_\bh_\ba_\br_\ba_\bc_\b- | |
4159 | _\bt_\be_\br-separated words surrounded by quotes are considered one word. His- | |
4160 | tory expansions are introduced by the appearance of the history expan- | |
4161 | sion character, which is !\b! by default. Only backslash (\\b\) and single | |
712f80b0 CR |
4162 | quotes can quote the history expansion character, but the history ex- |
4163 | pansion character is also treated as quoted if it immediately precedes | |
4164 | the closing double quote in a double-quoted string. | |
d233b485 CR |
4165 | |
4166 | Several characters inhibit history expansion if found immediately fol- | |
4167 | lowing the history expansion character, even if it is unquoted: space, | |
4168 | tab, newline, carriage return, and =\b=. If the e\bex\bxt\btg\bgl\blo\bob\bb shell option is | |
17345e5a JA |
4169 | enabled, (\b( will also inhibit expansion. |
4170 | ||
d233b485 | 4171 | Several shell options settable with the s\bsh\bho\bop\bpt\bt builtin may be used to |
712f80b0 CR |
4172 | tailor the behavior of history expansion. If the h\bhi\bis\bst\btv\bve\ber\bri\bif\bfy\by shell op- |
4173 | tion is enabled (see the description of the s\bsh\bho\bop\bpt\bt builtin below), and | |
d233b485 CR |
4174 | r\bre\bea\bad\bdl\bli\bin\bne\be is being used, history substitutions are not immediately |
4175 | passed to the shell parser. Instead, the expanded line is reloaded | |
0001803f | 4176 | 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 |
4177 | is being used, and the h\bhi\bis\bst\btr\bre\bee\bed\bdi\bit\bt shell option is enabled, a failed |
4178 | history substitution will be reloaded into the r\bre\bea\bad\bdl\bli\bin\bne\be editing buffer | |
4179 | for correction. The -\b-p\bp option to the h\bhi\bis\bst\bto\bor\bry\by builtin command may be | |
4180 | used to see what a history expansion will do before using it. The -\b-s\bs | |
0001803f | 4181 | option to the h\bhi\bis\bst\bto\bor\bry\by builtin may be used to add commands to the end of |
d233b485 | 4182 | the history list without actually executing them, so that they are |
0001803f | 4183 | available for subsequent recall. |
17345e5a | 4184 | |
d233b485 | 4185 | The shell allows control of the various characters used by the history |
17345e5a | 4186 | 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 | 4187 | V\bVa\bar\bri\bia\bab\bbl\ble\bes\bs). The shell uses the history comment character to mark his- |
17345e5a JA |
4188 | tory timestamps when writing the history file. |
4189 | ||
4190 | E\bEv\bve\ben\bnt\bt D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs | |
d233b485 CR |
4191 | An event designator is a reference to a command line entry in the his- |
4192 | tory list. Unless the reference is absolute, events are relative to | |
495aee44 | 4193 | the current position in the history list. |
17345e5a | 4194 | |
d233b485 CR |
4195 | !\b! Start a history substitution, except when followed by a b\bbl\bla\ban\bnk\bk, |
4196 | newline, carriage return, = or ( (when the e\bex\bxt\btg\bgl\blo\bob\bb shell option | |
17345e5a JA |
4197 | is enabled using the s\bsh\bho\bop\bpt\bt builtin). |
4198 | !\b!_\bn Refer to command line _\bn. | |
495aee44 | 4199 | !\b!-\b-_\bn Refer to the current command minus _\bn. |
17345e5a JA |
4200 | !\b!!\b! Refer to the previous command. This is a synonym for `!-1'. |
4201 | !\b!_\bs_\bt_\br_\bi_\bn_\bg | |
d233b485 | 4202 | Refer to the most recent command preceding the current position |
495aee44 | 4203 | in the history list starting with _\bs_\bt_\br_\bi_\bn_\bg. |
17345e5a | 4204 | !\b!?\b?_\bs_\bt_\br_\bi_\bn_\bg[\b[?\b?]\b] |
d233b485 CR |
4205 | Refer to the most recent command preceding the current position |
4206 | in the history list containing _\bs_\bt_\br_\bi_\bn_\bg. The trailing ?\b? may be | |
712f80b0 CR |
4207 | omitted if _\bs_\bt_\br_\bi_\bn_\bg is followed immediately by a newline. If |
4208 | _\bs_\bt_\br_\bi_\bn_\bg is missing, the string from the most recent search is | |
4209 | used; it is an error if there is no previous search string. | |
17345e5a | 4210 | ^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b1^\b^_\bs_\bt_\br_\bi_\bn_\bg_\b2^\b^ |
d233b485 | 4211 | Quick substitution. Repeat the previous command, replacing |
712f80b0 | 4212 | _\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 | 4213 | (see M\bMo\bod\bdi\bif\bfi\bie\ber\brs\bs below). |
17345e5a JA |
4214 | !\b!#\b# The entire command line typed so far. |
4215 | ||
4216 | W\bWo\bor\brd\bd D\bDe\bes\bsi\big\bgn\bna\bat\bto\bor\brs\bs | |
d233b485 CR |
4217 | Word designators are used to select desired words from the event. A :\b: |
4218 | separates the event specification from the word designator. It may be | |
4219 | omitted if the word designator begins with a ^\b^, $\b$, *\b*, -\b-, or %\b%. Words | |
4220 | are numbered from the beginning of the line, with the first word being | |
4221 | denoted by 0 (zero). Words are inserted into the current line sepa- | |
17345e5a JA |
4222 | rated by single spaces. |
4223 | ||
4224 | 0\b0 (\b(z\bze\ber\bro\bo)\b) | |
4225 | The zeroth word. For the shell, this is the command word. | |
4226 | _\bn The _\bnth word. | |
4227 | ^\b^ The first argument. That is, word 1. | |
712f80b0 CR |
4228 | $\b$ The last word. This is usually the last argument, but will ex- |
4229 | pand to the zeroth word if there is only one word in the line. | |
4230 | %\b% The first word matched by the most recent `?_\bs_\bt_\br_\bi_\bn_\bg?' search, if | |
4231 | the search string begins with a character that is part of a | |
4232 | word. | |
17345e5a | 4233 | _\bx-\b-_\by A range of words; `-_\by' abbreviates `0-_\by'. |
d233b485 CR |
4234 | *\b* All of the words but the zeroth. This is a synonym for `_\b1_\b-_\b$'. |
4235 | It is not an error to use *\b* if there is just one word in the | |
17345e5a JA |
4236 | event; the empty string is returned in that case. |
4237 | x\bx*\b* Abbreviates _\bx_\b-_\b$. | |
712f80b0 CR |
4238 | x\bx-\b- Abbreviates _\bx_\b-_\b$ like x\bx*\b*, but omits the last word. If x\bx is miss- |
4239 | ing, it defaults to 0. | |
17345e5a | 4240 | |
712f80b0 | 4241 | If a word designator is supplied without an event specification, the |
17345e5a JA |
4242 | previous command is used as the event. |
4243 | ||
4244 | M\bMo\bod\bdi\bif\bfi\bie\ber\brs\bs | |
712f80b0 CR |
4245 | After the optional word designator, there may appear a sequence of one |
4246 | or more of the following modifiers, each preceded by a `:'. These mod- | |
4247 | ify, or edit, the word or words selected from the history event. | |
17345e5a | 4248 | |
ac50fbac CR |
4249 | h\bh Remove a trailing filename component, leaving only the head. |
4250 | t\bt Remove all leading filename components, leaving the tail. | |
17345e5a JA |
4251 | r\br Remove a trailing suffix of the form _\b._\bx_\bx_\bx, leaving the basename. |
4252 | e\be Remove all but the trailing suffix. | |
4253 | p\bp Print the new command but do not execute it. | |
4254 | q\bq Quote the substituted words, escaping further substitutions. | |
d233b485 | 4255 | x\bx Quote the substituted words as with q\bq, but break into words at |
712f80b0 CR |
4256 | b\bbl\bla\ban\bnk\bks\bs and newlines. The q\bq and x\bx modifiers are mutually exclu- |
4257 | sive; the last one supplied is used. | |
17345e5a | 4258 | s\bs/\b/_\bo_\bl_\bd/\b/_\bn_\be_\bw/\b/ |
712f80b0 CR |
4259 | Substitute _\bn_\be_\bw for the first occurrence of _\bo_\bl_\bd in the event |
4260 | line. Any character may be used as the delimiter in place of /. | |
4261 | The final delimiter is optional if it is the last character of | |
4262 | the event line. The delimiter may be quoted in _\bo_\bl_\bd and _\bn_\be_\bw with | |
4263 | a single backslash. If & appears in _\bn_\be_\bw, it is replaced by _\bo_\bl_\bd. | |
4264 | A single backslash will quote the &. If _\bo_\bl_\bd is null, it is set | |
4265 | to the last _\bo_\bl_\bd substituted, or, if no previous history substi- | |
4266 | 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. | |
4267 | If _\bn_\be_\bw is null, each matching _\bo_\bl_\bd is deleted. | |
17345e5a JA |
4268 | &\b& Repeat the previous substitution. |
4269 | g\bg Cause changes to be applied over the entire event line. This is | |
d233b485 CR |
4270 | 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&'. |
4271 | If used with `:\b:s\bs', any delimiter can be used in place of /, and | |
4272 | the final delimiter is optional if it is the last character of | |
17345e5a | 4273 | the event line. An a\ba may be used as a synonym for g\bg. |
712f80b0 CR |
4274 | G\bG Apply the following `s\bs' or `&\b&' modifier once to each word in the |
4275 | event line. | |
17345e5a JA |
4276 | |
4277 | S\bSH\bHE\bEL\bLL\bL B\bBU\bUI\bIL\bLT\bTI\bIN\bN C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS | |
4278 | Unless otherwise noted, each builtin command documented in this section | |
4279 | as accepting options preceded by -\b- accepts -\b--\b- to signify the end of the | |
d233b485 CR |
4280 | 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 |
4281 | 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- | |
4282 | t\bti\bin\bnu\bue\be, l\ble\bet\bt, and s\bsh\bhi\bif\bft\bt builtins accept and process arguments beginning | |
4283 | with -\b- without requiring -\b--\b-. Other builtins that accept arguments but | |
4284 | are not specified as accepting options interpret arguments beginning | |
4285 | with -\b- as invalid options and require -\b--\b- to prevent this interpreta- | |
a0c0a00f | 4286 | tion. |
17345e5a | 4287 | :\b: [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs] |
d233b485 | 4288 | No effect; the command does nothing beyond expanding _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs |
a0c0a00f CR |
4289 | and performing any specified redirections. The return status is |
4290 | zero. | |
17345e5a JA |
4291 | |
4292 | .\b. _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs] | |
4293 | s\bso\bou\bur\brc\bce\be _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be [_\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs] | |
712f80b0 CR |
4294 | Read and execute commands from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be in the current shell en- |
4295 | vironment and return the exit status of the last command exe- | |
d233b485 CR |
4296 | cuted from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be does not contain a slash, |
4297 | filenames in P\bPA\bAT\bTH\bH are used to find the directory containing | |
ac50fbac | 4298 | _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be. The file searched for in P\bPA\bAT\bTH\bH need not be executable. |
d233b485 CR |
4299 | When b\bba\bas\bsh\bh is not in _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, the current directory is |
4300 | searched if no file is found in P\bPA\bAT\bTH\bH. If the s\bso\bou\bur\brc\bce\bep\bpa\bat\bth\bh option | |
4301 | to the s\bsh\bho\bop\bpt\bt builtin command is turned off, the P\bPA\bAT\bTH\bH is not | |
4302 | searched. If any _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs are supplied, they become the posi- | |
712f80b0 CR |
4303 | tional parameters when _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is executed. Otherwise the po- |
4304 | sitional parameters are unchanged. If the -\b-T\bT option is enabled, | |
4305 | s\bso\bou\bur\brc\bce\be inherits any trap on D\bDE\bEB\bBU\bUG\bG; if it is not, any D\bDE\bEB\bBU\bUG\bG trap | |
4306 | string is saved and restored around the call to s\bso\bou\bur\brc\bce\be, and | |
4307 | s\bso\bou\bur\brc\bce\be unsets the D\bDE\bEB\bBU\bUG\bG trap while it executes. If -\b-T\bT is not | |
4308 | set, and the sourced file changes the D\bDE\bEB\bBU\bUG\bG trap, the new value | |
4309 | is retained when s\bso\bou\bur\brc\bce\be completes. The return status is the | |
4310 | status of the last command exited within the script (0 if no | |
4311 | commands are executed), and false if _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is not found or | |
17345e5a JA |
4312 | cannot be read. |
4313 | ||
4314 | a\bal\bli\bia\bas\bs [-\b-p\bp] [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be] ...] | |
4315 | A\bAl\bli\bia\bas\bs with no arguments or with the -\b-p\bp option prints the list of | |
d233b485 CR |
4316 | aliases in the form a\bal\bli\bia\bas\bs _\bn_\ba_\bm_\be=_\bv_\ba_\bl_\bu_\be on standard output. When |
4317 | arguments are supplied, an alias is defined for each _\bn_\ba_\bm_\be whose | |
4318 | _\bv_\ba_\bl_\bu_\be is given. A trailing space in _\bv_\ba_\bl_\bu_\be causes the next word | |
17345e5a | 4319 | to be checked for alias substitution when the alias is expanded. |
d233b485 | 4320 | For each _\bn_\ba_\bm_\be in the argument list for which no _\bv_\ba_\bl_\bu_\be is sup- |
712f80b0 CR |
4321 | plied, the name and value of the alias is printed. A\bAl\bli\bia\bas\bs re- |
4322 | turns true unless a _\bn_\ba_\bm_\be is given for which no alias has been | |
17345e5a JA |
4323 | defined. |
4324 | ||
4325 | b\bbg\bg [_\bj_\bo_\bb_\bs_\bp_\be_\bc ...] | |
d233b485 | 4326 | Resume each suspended job _\bj_\bo_\bb_\bs_\bp_\be_\bc in the background, as if it |
17345e5a | 4327 | had been started with &\b&. If _\bj_\bo_\bb_\bs_\bp_\be_\bc is not present, the shell's |
d233b485 CR |
4328 | 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 |
4329 | run when job control is disabled or, when run with job control | |
4330 | enabled, any specified _\bj_\bo_\bb_\bs_\bp_\be_\bc was not found or was started | |
17345e5a JA |
4331 | without job control. |
4332 | ||
ac50fbac | 4333 | 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 |
4334 | 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] |
4335 | 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 | |
4336 | 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 | |
4337 | 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 | 4338 | 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 |
d233b485 CR |
4339 | Display current r\bre\bea\bad\bdl\bli\bin\bne\be key and function bindings, bind a key |
4340 | 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 | |
712f80b0 CR |
4341 | variable. Each non-option argument is a command as it would ap- |
4342 | pear in _\b._\bi_\bn_\bp_\bu_\bt_\br_\bc, but each binding or command must be passed as | |
4343 | a separate argument; e.g., '"\C-x\C-r": re-read-init-file'. Op- | |
4344 | tions, if supplied, have the following meanings: | |
17345e5a JA |
4345 | -\b-m\bm _\bk_\be_\by_\bm_\ba_\bp |
4346 | Use _\bk_\be_\by_\bm_\ba_\bp as the keymap to be affected by the subsequent | |
4347 | 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- | |
d233b485 CR |
4348 | _\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, |
4349 | 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 | |
4350 | is also a synonym); _\be_\bm_\ba_\bc_\bs is equivalent to _\be_\bm_\ba_\bc_\bs_\b-_\bs_\bt_\ba_\bn_\b- | |
a0c0a00f | 4351 | _\bd_\ba_\br_\bd. |
17345e5a | 4352 | -\b-l\bl List the names of all r\bre\bea\bad\bdl\bli\bin\bne\be functions. |
d233b485 | 4353 | -\b-p\bp Display r\bre\bea\bad\bdl\bli\bin\bne\be function names and bindings in such a |
17345e5a JA |
4354 | way that they can be re-read. |
4355 | -\b-P\bP List current r\bre\bea\bad\bdl\bli\bin\bne\be function names and bindings. | |
d233b485 CR |
4356 | -\b-s\bs Display r\bre\bea\bad\bdl\bli\bin\bne\be key sequences bound to macros and the |
4357 | strings they output in such a way that they can be re- | |
17345e5a | 4358 | read. |
d233b485 | 4359 | -\b-S\bS Display r\bre\bea\bad\bdl\bli\bin\bne\be key sequences bound to macros and the |
17345e5a | 4360 | strings they output. |
d233b485 | 4361 | -\b-v\bv Display r\bre\bea\bad\bdl\bli\bin\bne\be variable names and values in such a way |
17345e5a JA |
4362 | that they can be re-read. |
4363 | -\b-V\bV List current r\bre\bea\bad\bdl\bli\bin\bne\be variable names and values. | |
4364 | -\b-f\bf _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be | |
4365 | Read key bindings from _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be. | |
4366 | -\b-q\bq _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn | |
4367 | Query about which keys invoke the named _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn. | |
4368 | -\b-u\bu _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn | |
4369 | Unbind all keys bound to the named _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn. | |
4370 | -\b-r\br _\bk_\be_\by_\bs_\be_\bq | |
4371 | Remove any current binding for _\bk_\be_\by_\bs_\be_\bq. | |
4372 | -\b-x\bx _\bk_\be_\by_\bs_\be_\bq:\b:_\bs_\bh_\be_\bl_\bl_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd | |
712f80b0 CR |
4373 | 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- |
4374 | tered. When _\bs_\bh_\be_\bl_\bl_\b-_\bc_\bo_\bm_\bm_\ba_\bn_\bd is executed, the shell sets | |
d233b485 | 4375 | 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- |
712f80b0 CR |
4376 | 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 |
4377 | variables to the current location of the insertion point | |
4378 | and the saved insertion point (the mark), respectively. | |
4379 | If the executed command changes the value of any of R\bRE\bEA\bAD\bD-\b- | |
4380 | L\bLI\bIN\bNE\bE_\b_L\bLI\bIN\bNE\bE, R\bRE\bEA\bAD\bDL\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 | |
4381 | values will be reflected in the editing state. | |
4382 | -\b-X\bX List all key sequences bound to shell commands and the | |
4383 | associated commands in a format that can be reused as in- | |
4384 | put. | |
4385 | ||
4386 | The return value is 0 unless an unrecognized option is given or | |
17345e5a JA |
4387 | an error occurred. |
4388 | ||
4389 | b\bbr\bre\bea\bak\bk [_\bn] | |
712f80b0 CR |
4390 | 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 |
4391 | specified, break _\bn levels. _\bn must be >= 1. If _\bn is greater | |
4392 | than the number of enclosing loops, all enclosing loops are ex- | |
4393 | ited. The return value is 0 unless _\bn is not greater than or | |
17345e5a JA |
4394 | equal to 1. |
4395 | ||
4396 | 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] | |
712f80b0 | 4397 | Execute the specified shell builtin, passing it _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs, and |
17345e5a | 4398 | return its exit status. This is useful when defining a function |
712f80b0 | 4399 | whose name is the same as a shell builtin, retaining the func- |
17345e5a | 4400 | tionality of the builtin within the function. The c\bcd\bd builtin is |
712f80b0 | 4401 | commonly redefined this way. The return status is false if |
17345e5a JA |
4402 | _\bs_\bh_\be_\bl_\bl_\b-_\bb_\bu_\bi_\bl_\bt_\bi_\bn is not a shell builtin command. |
4403 | ||
4404 | c\bca\bal\bll\ble\ber\br [_\be_\bx_\bp_\br] | |
4405 | Returns the context of any active subroutine call (a shell func- | |
495aee44 | 4406 | tion or a script executed with the .\b. or s\bso\bou\bur\brc\bce\be builtins). With- |
17345e5a | 4407 | out _\be_\bx_\bp_\br, c\bca\bal\bll\ble\ber\br displays the line number and source filename of |
712f80b0 | 4408 | the current subroutine call. If a non-negative integer is sup- |
17345e5a | 4409 | plied as _\be_\bx_\bp_\br, c\bca\bal\bll\ble\ber\br displays the line number, subroutine name, |
712f80b0 CR |
4410 | and source file corresponding to that position in the current |
4411 | execution call stack. This extra information may be used, for | |
4412 | example, to print a stack trace. The current frame is frame 0. | |
4413 | The return value is 0 unless the shell is not executing a sub- | |
4414 | routine call or _\be_\bx_\bp_\br does not correspond to a valid position in | |
17345e5a JA |
4415 | the call stack. |
4416 | ||
ac50fbac | 4417 | c\bcd\bd [-\b-L\bL|[-\b-P\bP [-\b-e\be]] [-@]] [_\bd_\bi_\br] |
712f80b0 CR |
4418 | Change the current directory to _\bd_\bi_\br. if _\bd_\bi_\br is not supplied, |
4419 | the value of the H\bHO\bOM\bME\bE shell variable is the default. Any addi- | |
ac50fbac | 4420 | tional arguments following _\bd_\bi_\br are ignored. The variable C\bCD\bDP\bPA\bAT\bTH\bH |
712f80b0 CR |
4421 | defines the search path for the directory containing _\bd_\bi_\br: each |
4422 | directory name in C\bCD\bDP\bPA\bAT\bTH\bH is searched for _\bd_\bi_\br. Alternative di- | |
4423 | rectory names in C\bCD\bDP\bPA\bAT\bTH\bH are separated by a colon (:). A null | |
4424 | directory name in C\bCD\bDP\bPA\bAT\bTH\bH is the same as the current directory, | |
ac50fbac | 4425 | i.e., ``.\b.''. If _\bd_\bi_\br begins with a slash (/), then C\bCD\bDP\bPA\bAT\bTH\bH is not |
712f80b0 CR |
4426 | used. The -\b-P\bP option causes c\bcd\bd to use the physical directory |
4427 | structure by resolving symbolic links while traversing _\bd_\bi_\br and | |
ac50fbac CR |
4428 | before processing instances of _\b._\b. in _\bd_\bi_\br (see also the -\b-P\bP option |
4429 | to the s\bse\bet\bt builtin command); the -\b-L\bL option forces symbolic links | |
712f80b0 | 4430 | to be followed by resolving the link after processing instances |
ac50fbac | 4431 | of _\b._\b. in _\bd_\bi_\br. If _\b._\b. appears in _\bd_\bi_\br, it is processed by removing |
712f80b0 CR |
4432 | the immediately previous pathname component from _\bd_\bi_\br, back to a |
4433 | slash or the beginning of _\bd_\bi_\br. If the -\b-e\be option is supplied | |
4434 | with -\b-P\bP, and the current working directory cannot be success- | |
4435 | fully determined after a successful directory change, c\bcd\bd will | |
4436 | return an unsuccessful status. On systems that support it, the | |
4437 | -\b-@\b@ option presents the extended attributes associated with a | |
4438 | file as a directory. An argument of -\b- is converted to $\b$O\bOL\bLD\bDP\bPW\bWD\bD | |
ac50fbac | 4439 | before the directory change is attempted. If a non-empty direc- |
712f80b0 | 4440 | tory name from C\bCD\bDP\bPA\bAT\bTH\bH is used, or if -\b- is the first argument, |
ac50fbac | 4441 | and the directory change is successful, the absolute pathname of |
712f80b0 CR |
4442 | the new working directory is written to the standard output. |
4443 | The return value is true if the directory was successfully | |
ac50fbac | 4444 | changed; false otherwise. |
17345e5a JA |
4445 | |
4446 | c\bco\bom\bmm\bma\ban\bnd\bd [-\b-p\bpV\bVv\bv] _\bc_\bo_\bm_\bm_\ba_\bn_\bd [_\ba_\br_\bg ...] | |
712f80b0 | 4447 | Run _\bc_\bo_\bm_\bm_\ba_\bn_\bd with _\ba_\br_\bg_\bs suppressing the normal shell function |
a0c0a00f | 4448 | lookup. Only builtin commands or commands found in the P\bPA\bAT\bTH\bH are |
712f80b0 CR |
4449 | executed. If the -\b-p\bp option is given, the search for _\bc_\bo_\bm_\bm_\ba_\bn_\bd is |
4450 | performed using a default value for P\bPA\bAT\bTH\bH that is guaranteed to | |
4451 | find all of the standard utilities. If either the -\b-V\bV or -\b-v\bv op- | |
4452 | tion is supplied, a description of _\bc_\bo_\bm_\bm_\ba_\bn_\bd is printed. The -\b-v\bv | |
4453 | option causes a single word indicating the command or filename | |
17345e5a | 4454 | used to invoke _\bc_\bo_\bm_\bm_\ba_\bn_\bd to be displayed; the -\b-V\bV option produces a |
712f80b0 CR |
4455 | more verbose description. If the -\b-V\bV or -\b-v\bv option is supplied, |
4456 | the exit status is 0 if _\bc_\bo_\bm_\bm_\ba_\bn_\bd was found, and 1 if not. If | |
17345e5a | 4457 | neither option is supplied and an error occurred or _\bc_\bo_\bm_\bm_\ba_\bn_\bd can- |
712f80b0 | 4458 | not be found, the exit status is 127. Otherwise, the exit sta- |
17345e5a JA |
4459 | tus of the c\bco\bom\bmm\bma\ban\bnd\bd builtin is the exit status of _\bc_\bo_\bm_\bm_\ba_\bn_\bd. |
4460 | ||
4461 | c\bco\bom\bmp\bpg\bge\ben\bn [_\bo_\bp_\bt_\bi_\bo_\bn] [_\bw_\bo_\br_\bd] | |
712f80b0 CR |
4462 | Generate possible completion matches for _\bw_\bo_\br_\bd according to the |
4463 | _\bo_\bp_\bt_\bi_\bo_\bns, which may be any option accepted by the c\bco\bom\bmp\bpl\ble\bet\bte\be | |
4464 | builtin with the exception of -\b-p\bp and -\b-r\br, and write the matches | |
4465 | to the standard output. When using the -\b-F\bF or -\b-C\bC options, the | |
4466 | various shell variables set by the programmable completion fa- | |
4467 | cilities, while available, will not have useful values. | |
17345e5a | 4468 | |
a0c0a00f CR |
4469 | The matches will be generated in the same way as if the program- |
4470 | mable completion code had generated them directly from a comple- | |
712f80b0 | 4471 | tion specification with the same flags. If _\bw_\bo_\br_\bd is specified, |
a0c0a00f | 4472 | only those completions matching _\bw_\bo_\br_\bd will be displayed. |
17345e5a | 4473 | |
712f80b0 | 4474 | The return value is true unless an invalid option is supplied, |
17345e5a JA |
4475 | or no matches were generated. |
4476 | ||
712f80b0 CR |
4477 | 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- |
4478 | _\bp_\ba_\bt] [-\b-W\bW _\bw_\bo_\br_\bd_\bl_\bi_\bs_\bt] | |
4479 | [-\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- | |
4480 | _\bf_\bi_\bx] _\bn_\ba_\bm_\be [_\bn_\ba_\bm_\be _\b._\b._\b.] | |
d233b485 CR |
4481 | c\bco\bom\bmp\bpl\ble\bet\bte\be -\b-p\bpr\br [-\b-D\bDE\bEI\bI] [_\bn_\ba_\bm_\be ...] |
4482 | Specify how arguments to each _\bn_\ba_\bm_\be should be completed. If the | |
4483 | -\b-p\bp option is supplied, or if no options are supplied, existing | |
4484 | completion specifications are printed in a way that allows them | |
17345e5a | 4485 | to be reused as input. The -\b-r\br option removes a completion spec- |
d233b485 CR |
4486 | ification for each _\bn_\ba_\bm_\be, or, if no _\bn_\ba_\bm_\bes are supplied, all com- |
4487 | pletion specifications. The -\b-D\bD option indicates that other sup- | |
4488 | plied options and actions should apply to the ``default'' com- | |
4489 | mand completion; that is, completion attempted on a command for | |
4490 | which no completion has previously been defined. The -\b-E\bE option | |
4491 | indicates that other supplied options and actions should apply | |
4492 | to ``empty'' command completion; that is, completion attempted | |
4493 | on a blank line. The -\b-I\bI option indicates that other supplied | |
712f80b0 | 4494 | options and actions should apply to completion on the initial |
d233b485 CR |
4495 | non-assignment word on the line, or after a command delimiter |
4496 | such as ;\b; or |\b|, which is usually command name completion. If | |
4497 | multiple options are supplied, the -\b-D\bD option takes precedence | |
4498 | over -\b-E\bE, and both take precedence over -\b-I\bI. If any of -\b-D\bD, -\b-E\bE, or | |
4499 | -\b-I\bI are supplied, any other _\bn_\ba_\bm_\be arguments are ignored; these | |
4500 | completions only apply to the case specified by the option. | |
17345e5a | 4501 | |
ac50fbac | 4502 | The process of applying these completion specifications when |
a0c0a00f CR |
4503 | word completion is attempted is described above under P\bPr\bro\bog\bgr\bra\bam\bm-\b- |
4504 | m\bma\bab\bbl\ble\be C\bCo\bom\bmp\bpl\ble\bet\bti\bio\bon\bn. | |
17345e5a | 4505 | |
ac50fbac CR |
4506 | Other options, if specified, have the following meanings. The |
4507 | arguments to the -\b-G\bG, -\b-W\bW, and -\b-X\bX options (and, if necessary, the | |
4508 | -\b-P\bP and -\b-S\bS options) should be quoted to protect them from expan- | |
17345e5a JA |
4509 | sion before the c\bco\bom\bmp\bpl\ble\bet\bte\be builtin is invoked. |
4510 | -\b-o\bo _\bc_\bo_\bm_\bp_\b-_\bo_\bp_\bt_\bi_\bo_\bn | |
ac50fbac CR |
4511 | The _\bc_\bo_\bm_\bp_\b-_\bo_\bp_\bt_\bi_\bo_\bn controls several aspects of the comp- |
4512 | spec's behavior beyond the simple generation of comple- | |
17345e5a JA |
4513 | tions. _\bc_\bo_\bm_\bp_\b-_\bo_\bp_\bt_\bi_\bo_\bn may be one of: |
4514 | b\bba\bas\bsh\bhd\bde\bef\bfa\bau\bul\blt\bt | |
4515 | Perform the rest of the default b\bba\bas\bsh\bh completions | |
4516 | if the compspec generates no matches. | |
ac50fbac | 4517 | d\bde\bef\bfa\bau\bul\blt\bt Use readline's default filename completion if |
17345e5a JA |
4518 | the compspec generates no matches. |
4519 | d\bdi\bir\brn\bna\bam\bme\bes\bs | |
ac50fbac | 4520 | Perform directory name completion if the comp- |
17345e5a JA |
4521 | spec generates no matches. |
4522 | f\bfi\bil\ble\ben\bna\bam\bme\bes\bs | |
ac50fbac CR |
4523 | Tell readline that the compspec generates file- |
4524 | names, so it can perform any filename-specific | |
4525 | processing (like adding a slash to directory | |
4526 | names, quoting special characters, or suppress- | |
4527 | ing trailing spaces). Intended to be used with | |
17345e5a | 4528 | shell functions. |
ac50fbac CR |
4529 | n\bno\boq\bqu\buo\bot\bte\be Tell readline not to quote the completed words |
4530 | if they are filenames (quoting filenames is the | |
4531 | default). | |
a0c0a00f CR |
4532 | n\bno\bos\bso\bor\brt\bt Tell readline not to sort the list of possible |
4533 | completions alphabetically. | |
712f80b0 CR |
4534 | n\bno\bos\bsp\bpa\bac\bce\be Tell readline not to append a space (the de- |
4535 | fault) to words completed at the end of the | |
17345e5a JA |
4536 | line. |
4537 | p\bpl\blu\bus\bsd\bdi\bir\brs\bs | |
a0c0a00f | 4538 | After any matches defined by the compspec are |
712f80b0 CR |
4539 | generated, directory name completion is at- |
4540 | tempted and any matches are added to the results | |
4541 | of the other actions. | |
17345e5a | 4542 | -\b-A\bA _\ba_\bc_\bt_\bi_\bo_\bn |
a0c0a00f | 4543 | The _\ba_\bc_\bt_\bi_\bo_\bn may be one of the following to generate a |
17345e5a JA |
4544 | list of possible completions: |
4545 | a\bal\bli\bia\bas\bs Alias names. May also be specified as -\b-a\ba. | |
4546 | a\bar\brr\bra\bay\byv\bva\bar\br | |
4547 | Array variable names. | |
4548 | b\bbi\bin\bnd\bdi\bin\bng\bg R\bRe\bea\bad\bdl\bli\bin\bne\be key binding names. | |
a0c0a00f | 4549 | b\bbu\bui\bil\blt\bti\bin\bn Names of shell builtin commands. May also be |
17345e5a JA |
4550 | specified as -\b-b\bb. |
4551 | c\bco\bom\bmm\bma\ban\bnd\bd Command names. May also be specified as -\b-c\bc. | |
4552 | d\bdi\bir\bre\bec\bct\bto\bor\bry\by | |
4553 | Directory names. May also be specified as -\b-d\bd. | |
4554 | d\bdi\bis\bsa\bab\bbl\ble\bed\bd | |
4555 | Names of disabled shell builtins. | |
4556 | e\ben\bna\bab\bbl\ble\bed\bd Names of enabled shell builtins. | |
a0c0a00f | 4557 | e\bex\bxp\bpo\bor\brt\bt Names of exported shell variables. May also be |
17345e5a JA |
4558 | specified as -\b-e\be. |
4559 | f\bfi\bil\ble\be File names. May also be specified as -\b-f\bf. | |
4560 | f\bfu\bun\bnc\bct\bti\bio\bon\bn | |
4561 | Names of shell functions. | |
4562 | g\bgr\bro\bou\bup\bp Group names. May also be specified as -\b-g\bg. | |
4563 | h\bhe\bel\blp\bpt\bto\bop\bpi\bic\bc | |
4564 | Help topics as accepted by the h\bhe\bel\blp\bp builtin. | |
4565 | h\bho\bos\bst\btn\bna\bam\bme\be | |
a0c0a00f | 4566 | Hostnames, as taken from the file specified by |
17345e5a | 4567 | the H\bHO\bOS\bST\bTF\bFI\bIL\bLE\bE shell variable. |
a0c0a00f | 4568 | j\bjo\bob\bb Job names, if job control is active. May also |
17345e5a | 4569 | be specified as -\b-j\bj. |
a0c0a00f | 4570 | k\bke\bey\byw\bwo\bor\brd\bd Shell reserved words. May also be specified as |
17345e5a JA |
4571 | -\b-k\bk. |
4572 | r\bru\bun\bnn\bni\bin\bng\bg Names of running jobs, if job control is active. | |
4573 | s\bse\ber\brv\bvi\bic\bce\be Service names. May also be specified as -\b-s\bs. | |
ac50fbac | 4574 | s\bse\bet\bto\bop\bpt\bt Valid arguments for the -\b-o\bo option to the s\bse\bet\bt |
17345e5a | 4575 | builtin. |
ac50fbac | 4576 | s\bsh\bho\bop\bpt\bt Shell option names as accepted by the s\bsh\bho\bop\bpt\bt |
17345e5a JA |
4577 | builtin. |
4578 | s\bsi\big\bgn\bna\bal\bl Signal names. | |
4579 | s\bst\bto\bop\bpp\bpe\bed\bd Names of stopped jobs, if job control is active. | |
4580 | u\bus\bse\ber\br User names. May also be specified as -\b-u\bu. | |
4581 | v\bva\bar\bri\bia\bab\bbl\ble\be | |
4582 | Names of all shell variables. May also be spec- | |
4583 | ified as -\b-v\bv. | |
17345e5a | 4584 | -\b-C\bC _\bc_\bo_\bm_\bm_\ba_\bn_\bd |
a0c0a00f | 4585 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd is executed in a subshell environment, and its |
17345e5a JA |
4586 | output is used as the possible completions. |
4587 | -\b-F\bF _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn | |
a0c0a00f CR |
4588 | The shell function _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn is executed in the current |
4589 | shell environment. When the function is executed, the | |
712f80b0 CR |
4590 | first argument ($\b$1\b1) is the name of the command whose ar- |
4591 | guments are being completed, the second argument ($\b$2\b2) is | |
4592 | the word being completed, and the third argument ($\b$3\b3) is | |
4593 | the word preceding the word being completed on the cur- | |
4594 | rent command line. When it finishes, the possible com- | |
4595 | pletions are retrieved from the value of the C\bCO\bOM\bMP\bPR\bRE\bEP\bPL\bLY\bY | |
4596 | array variable. | |
495aee44 | 4597 | -\b-G\bG _\bg_\bl_\bo_\bb_\bp_\ba_\bt |
a0c0a00f | 4598 | The pathname expansion pattern _\bg_\bl_\bo_\bb_\bp_\ba_\bt is expanded to |
495aee44 | 4599 | generate the possible completions. |
17345e5a | 4600 | -\b-P\bP _\bp_\br_\be_\bf_\bi_\bx |
a0c0a00f | 4601 | _\bp_\br_\be_\bf_\bi_\bx is added at the beginning of each possible com- |
17345e5a JA |
4602 | pletion after all other options have been applied. |
4603 | -\b-S\bS _\bs_\bu_\bf_\bf_\bi_\bx | |
4604 | _\bs_\bu_\bf_\bf_\bi_\bx is appended to each possible completion after all | |
4605 | other options have been applied. | |
495aee44 | 4606 | -\b-W\bW _\bw_\bo_\br_\bd_\bl_\bi_\bs_\bt |
a0c0a00f CR |
4607 | The _\bw_\bo_\br_\bd_\bl_\bi_\bs_\bt is split using the characters in the I\bIF\bFS\bS |
4608 | special variable as delimiters, and each resultant word | |
d233b485 CR |
4609 | is expanded. Shell quoting is honored within _\bw_\bo_\br_\bd_\bl_\bi_\bs_\bt, |
4610 | in order to provide a mechanism for the words to contain | |
4611 | shell metacharacters or characters in the value of I\bIF\bFS\bS. | |
4612 | The possible completions are the members of the resul- | |
4613 | tant list which match the word being completed. | |
495aee44 | 4614 | -\b-X\bX _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt |
a0c0a00f | 4615 | _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt is a pattern as used for pathname expansion. |
495aee44 | 4616 | It is applied to the list of possible completions gener- |
a0c0a00f CR |
4617 | ated by the preceding options and arguments, and each |
4618 | completion matching _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt is removed from the list. | |
4619 | A leading !\b! in _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt negates the pattern; in this | |
4620 | case, any completion not matching _\bf_\bi_\bl_\bt_\be_\br_\bp_\ba_\bt is removed. | |
495aee44 CR |
4621 | |
4622 | The return value is true unless an invalid option is supplied, | |
4623 | an option other than -\b-p\bp or -\b-r\br is supplied without a _\bn_\ba_\bm_\be argu- | |
4624 | ment, an attempt is made to remove a completion specification | |
17345e5a JA |
4625 | for a _\bn_\ba_\bm_\be for which no specification exists, or an error occurs |
4626 | adding a completion specification. | |
4627 | ||
d233b485 | 4628 | 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] |
712f80b0 CR |
4629 | Modify completion options for each _\bn_\ba_\bm_\be according to the _\bo_\bp_\b- |
4630 | _\bt_\bi_\bo_\bns, or for the currently-executing completion if no _\bn_\ba_\bm_\bes are | |
4631 | supplied. If no _\bo_\bp_\bt_\bi_\bo_\bns are given, display the completion op- | |
4632 | tions for each _\bn_\ba_\bm_\be or the current completion. The possible | |
4633 | values of _\bo_\bp_\bt_\bi_\bo_\bn are those valid for the c\bco\bom\bmp\bpl\ble\bet\bte\be builtin de- | |
4634 | scribed above. The -\b-D\bD option indicates that other supplied op- | |
4635 | tions should apply to the ``default'' command completion; that | |
495aee44 | 4636 | is, completion attempted on a command for which no completion |
d233b485 CR |
4637 | has previously been defined. The -\b-E\bE option indicates that other |
4638 | supplied options should apply to ``empty'' command completion; | |
4639 | that is, completion attempted on a blank line. The -\b-I\bI option | |
4640 | indicates that other supplied options should apply to completion | |
712f80b0 | 4641 | on the initial non-assignment word on the line, or after a com- |
d233b485 CR |
4642 | mand delimiter such as ;\b; or |\b|, which is usually command name |
4643 | completion. | |
0001803f | 4644 | |
495aee44 CR |
4645 | The return value is true unless an invalid option is supplied, |
4646 | an attempt is made to modify the options for a _\bn_\ba_\bm_\be for which no | |
4647 | completion specification exists, or an output error occurs. | |
17345e5a JA |
4648 | |
4649 | c\bco\bon\bnt\bti\bin\bnu\bue\be [_\bn] | |
4650 | 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 | 4651 | s\bse\bel\ble\bec\bct\bt loop. If _\bn is specified, resume at the _\bnth enclosing |
712f80b0 CR |
4652 | loop. _\bn must be >= 1. If _\bn is greater than the number of en- |
4653 | closing loops, the last enclosing loop (the ``top-level'' loop) | |
4654 | is resumed. The return value is 0 unless _\bn is not greater than | |
4655 | or equal to 1. | |
17345e5a | 4656 | |
712f80b0 CR |
4657 | 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] ...] |
4658 | 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 |
4659 | Declare variables and/or give them attributes. If no _\bn_\ba_\bm_\bes are |
4660 | given then display the values of variables. The -\b-p\bp option will | |
17345e5a | 4661 | display the attributes and values of each _\bn_\ba_\bm_\be. When -\b-p\bp is used |
ac50fbac CR |
4662 | with _\bn_\ba_\bm_\be arguments, additional options, other than -\b-f\bf and -\b-F\bF, |
4663 | are ignored. When -\b-p\bp is supplied without _\bn_\ba_\bm_\be arguments, it | |
4664 | will display the attributes and values of all variables having | |
4665 | the attributes specified by the additional options. If no other | |
712f80b0 CR |
4666 | options are supplied with -\b-p\bp, d\bde\bec\bcl\bla\bar\bre\be will display the at- |
4667 | tributes and values of all shell variables. The -\b-f\bf option will | |
4668 | restrict the display to shell functions. The -\b-F\bF option inhibits | |
4669 | the display of function definitions; only the function name and | |
4670 | attributes are printed. If the e\bex\bxt\btd\bde\beb\bbu\bug\bg shell option is enabled | |
4671 | using s\bsh\bho\bop\bpt\bt, the source file name and line number where each | |
4672 | _\bn_\ba_\bm_\be is defined are displayed as well. The -\b-F\bF option implies | |
4673 | -\b-f\bf. The -\b-g\bg option forces variables to be created or modified at | |
4674 | the global scope, even when d\bde\bec\bcl\bla\bar\bre\be is executed in a shell func- | |
4675 | tion. It is ignored in all other cases. The -\b-I\bI option causes | |
4676 | local variables to inherit the attributes (except the _\bn_\ba_\bm_\be_\br_\be_\bf | |
4677 | attribute) and value of any existing variable with the same _\bn_\ba_\bm_\be | |
4678 | at a surrounding scope. If there is no existing variable, the | |
4679 | local variable is initially unset. The following options can be | |
4680 | used to restrict output to variables with the specified attri- | |
4681 | bute or to give variables attributes: | |
0001803f | 4682 | -\b-a\ba Each _\bn_\ba_\bm_\be is an indexed array variable (see A\bAr\brr\bra\bay\bys\bs |
17345e5a | 4683 | above). |
0001803f | 4684 | -\b-A\bA Each _\bn_\ba_\bm_\be is an associative array variable (see A\bAr\brr\bra\bay\bys\bs |
17345e5a JA |
4685 | above). |
4686 | -\b-f\bf Use function names only. | |
4687 | -\b-i\bi The variable is treated as an integer; arithmetic evalua- | |
0001803f CR |
4688 | 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 |
4689 | the variable is assigned a value. | |
4690 | -\b-l\bl When the variable is assigned a value, all upper-case | |
4691 | characters are converted to lower-case. The upper-case | |
17345e5a | 4692 | attribute is disabled. |
ac50fbac CR |
4693 | -\b-n\bn Give each _\bn_\ba_\bm_\be the _\bn_\ba_\bm_\be_\br_\be_\bf attribute, making it a name |
4694 | reference to another variable. That other variable is | |
a0c0a00f CR |
4695 | defined by the value of _\bn_\ba_\bm_\be. All references, assign- |
4696 | ments, and attribute modifications to _\bn_\ba_\bm_\be, except those | |
4697 | using or changing the -\b-n\bn attribute itself, are performed | |
4698 | on the variable referenced by _\bn_\ba_\bm_\be's value. The nameref | |
4699 | attribute cannot be applied to array variables. | |
17345e5a JA |
4700 | -\b-r\br Make _\bn_\ba_\bm_\bes readonly. These names cannot then be assigned |
4701 | values by subsequent assignment statements or unset. | |
712f80b0 CR |
4702 | -\b-t\bt Give each _\bn_\ba_\bm_\be the _\bt_\br_\ba_\bc_\be attribute. Traced functions in- |
4703 | herit the D\bDE\bEB\bBU\bUG\bG and R\bRE\bET\bTU\bUR\bRN\bN traps from the calling shell. | |
4704 | The trace attribute has no special meaning for variables. | |
4705 | -\b-u\bu When the variable is assigned a value, all lower-case | |
4706 | characters are converted to upper-case. The lower-case | |
17345e5a | 4707 | attribute is disabled. |
712f80b0 CR |
4708 | -\b-x\bx Mark _\bn_\ba_\bm_\bes for export to subsequent commands via the en- |
4709 | vironment. | |
17345e5a | 4710 | |
712f80b0 CR |
4711 | Using `+' instead of `-' turns off the attribute instead, with |
4712 | the exceptions that +\b+a\ba and +\b+A\bA may not be used to destroy array | |
4713 | variables and +\b+r\br will not remove the readonly attribute. When | |
d233b485 | 4714 | 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 |
712f80b0 CR |
4715 | with the l\blo\boc\bca\bal\bl command, unless the -\b-g\bg option is supplied. If a |
4716 | variable name is followed by =_\bv_\ba_\bl_\bu_\be, the value of the variable | |
4717 | is set to _\bv_\ba_\bl_\bu_\be. When using -\b-a\ba or -\b-A\bA and the compound assign- | |
4718 | ment syntax to create array variables, additional attributes do | |
4719 | not take effect until subsequent assignments. The return value | |
d233b485 CR |
4720 | is 0 unless an invalid option is encountered, an attempt is made |
4721 | to define a function using ``-f foo=bar'', an attempt is made to | |
712f80b0 CR |
4722 | assign a value to a readonly variable, an attempt is made to as- |
4723 | sign a value to an array variable without using the compound as- | |
4724 | signment syntax (see A\bAr\brr\bra\bay\bys\bs above), one of the _\bn_\ba_\bm_\be_\bs is not a | |
4725 | valid shell variable name, an attempt is made to turn off read- | |
4726 | only status for a readonly variable, an attempt is made to turn | |
ac50fbac CR |
4727 | off array status for an array variable, or an attempt is made to |
4728 | display a non-existent function with -\b-f\bf. | |
4729 | ||
4730 | d\bdi\bir\brs\bs [\b[-\b-c\bcl\blp\bpv\bv]\b] [\b[+\b+_\bn]\b] [\b[-\b-_\bn]\b] | |
712f80b0 CR |
4731 | Without options, displays the list of currently remembered di- |
4732 | rectories. The default display is on a single line with direc- | |
4733 | tory names separated by spaces. Directories are added to the | |
4734 | list with the p\bpu\bus\bsh\bhd\bd command; the p\bpo\bop\bpd\bd command removes entries | |
4735 | from the list. The current directory is always the first direc- | |
4736 | tory in the stack. | |
4737 | -\b-c\bc Clears the directory stack by deleting all of the en- | |
4738 | tries. | |
4739 | -\b-l\bl Produces a listing using full pathnames; the default | |
ac50fbac | 4740 | listing format uses a tilde to denote the home directory. |
17345e5a | 4741 | -\b-p\bp Print the directory stack with one entry per line. |
712f80b0 | 4742 | -\b-v\bv Print the directory stack with one entry per line, pre- |
17345e5a | 4743 | fixing each entry with its index in the stack. |
ac50fbac CR |
4744 | +\b+_\bn Displays the _\bnth entry counting from the left of the list |
4745 | shown by d\bdi\bir\brs\bs when invoked without options, starting with | |
4746 | zero. | |
712f80b0 | 4747 | -\b-_\bn Displays the _\bnth entry counting from the right of the |
ac50fbac CR |
4748 | list shown by d\bdi\bir\brs\bs when invoked without options, starting |
4749 | with zero. | |
17345e5a | 4750 | |
712f80b0 | 4751 | The return value is 0 unless an invalid option is supplied or _\bn |
17345e5a JA |
4752 | indexes beyond the end of the directory stack. |
4753 | ||
a0c0a00f | 4754 | d\bdi\bis\bso\bow\bwn\bn [-\b-a\bar\br] [-\b-h\bh] [_\bj_\bo_\bb_\bs_\bp_\be_\bc ... | _\bp_\bi_\bd ... ] |
712f80b0 CR |
4755 | Without options, remove each _\bj_\bo_\bb_\bs_\bp_\be_\bc from the table of active |
4756 | jobs. If _\bj_\bo_\bb_\bs_\bp_\be_\bc is not present, and neither the -\b-a\ba nor the -\b-r\br | |
4757 | option is supplied, the _\bc_\bu_\br_\br_\be_\bn_\bt _\bj_\bo_\bb is used. If the -\b-h\bh option | |
4758 | is given, each _\bj_\bo_\bb_\bs_\bp_\be_\bc is not removed from the table, but is | |
4759 | marked so that S\bSI\bIG\bGH\bHU\bUP\bP is not sent to the job if the shell re- | |
4760 | 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 | |
4761 | to remove or mark all jobs; the -\b-r\br option without a _\bj_\bo_\bb_\bs_\bp_\be_\bc ar- | |
4762 | gument restricts operation to running jobs. The return value is | |
4763 | 0 unless a _\bj_\bo_\bb_\bs_\bp_\be_\bc does not specify a valid job. | |
17345e5a JA |
4764 | |
4765 | e\bec\bch\bho\bo [-\b-n\bne\beE\bE] [_\ba_\br_\bg ...] | |
712f80b0 CR |
4766 | Output the _\ba_\br_\bgs, separated by spaces, followed by a newline. |
4767 | The return status is 0 unless a write error occurs. If -\b-n\bn is | |
ac50fbac | 4768 | specified, the trailing newline is suppressed. If the -\b-e\be option |
712f80b0 CR |
4769 | is given, interpretation of the following backslash-escaped |
4770 | characters is enabled. The -\b-E\bE option disables the interpreta- | |
4771 | tion of these escape characters, even on systems where they are | |
4772 | interpreted by default. The x\bxp\bpg\bg_\b_e\bec\bch\bho\bo shell option may be used | |
4773 | to dynamically determine whether or not e\bec\bch\bho\bo expands these es- | |
4774 | cape characters by default. e\bec\bch\bho\bo does not interpret -\b--\b- to mean | |
4775 | the end of options. e\bec\bch\bho\bo interprets the following escape se- | |
4776 | quences: | |
17345e5a JA |
4777 | \\b\a\ba alert (bell) |
4778 | \\b\b\bb backspace | |
4779 | \\b\c\bc suppress further output | |
495aee44 CR |
4780 | \\b\e\be |
4781 | \\b\E\bE an escape character | |
17345e5a JA |
4782 | \\b\f\bf form feed |
4783 | \\b\n\bn new line | |
4784 | \\b\r\br carriage return | |
4785 | \\b\t\bt horizontal tab | |
4786 | \\b\v\bv vertical tab | |
4787 | \\b\\\b\ backslash | |
712f80b0 | 4788 | \\b\0\b0_\bn_\bn_\bn the eight-bit character whose value is the octal value |
17345e5a | 4789 | _\bn_\bn_\bn (zero to three octal digits) |
712f80b0 | 4790 | \\b\x\bx_\bH_\bH the eight-bit character whose value is the hexadecimal |
17345e5a | 4791 | value _\bH_\bH (one or two hex digits) |
712f80b0 | 4792 | \\b\u\bu_\bH_\bH_\bH_\bH the Unicode (ISO/IEC 10646) character whose value is the |
495aee44 CR |
4793 | hexadecimal value _\bH_\bH_\bH_\bH (one to four hex digits) |
4794 | \\b\U\bU_\bH_\bH_\bH_\bH_\bH_\bH_\bH_\bH | |
712f80b0 | 4795 | the Unicode (ISO/IEC 10646) character whose value is the |
495aee44 | 4796 | hexadecimal value _\bH_\bH_\bH_\bH_\bH_\bH_\bH_\bH (one to eight hex digits) |
17345e5a JA |
4797 | |
4798 | 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 ...] | |
712f80b0 | 4799 | Enable and disable builtin shell commands. Disabling a builtin |
17345e5a | 4800 | allows a disk command which has the same name as a shell builtin |
712f80b0 CR |
4801 | to be executed without specifying a full pathname, even though |
4802 | the shell normally searches for builtins before disk commands. | |
4803 | If -\b-n\bn is used, each _\bn_\ba_\bm_\be is disabled; otherwise, _\bn_\ba_\bm_\be_\bs are en- | |
4804 | abled. For example, to use the t\bte\bes\bst\bt binary found via the P\bPA\bAT\bTH\bH | |
4805 | instead of the shell builtin version, run ``enable -n test''. | |
4806 | The -\b-f\bf option means to load the new builtin command _\bn_\ba_\bm_\be from | |
17345e5a | 4807 | shared object _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, on systems that support dynamic loading. |
712f80b0 | 4808 | The -\b-d\bd option will delete a builtin previously loaded with -\b-f\bf. |
17345e5a JA |
4809 | If no _\bn_\ba_\bm_\be arguments are given, or if the -\b-p\bp option is supplied, |
4810 | a list of shell builtins is printed. With no other option argu- | |
712f80b0 CR |
4811 | ments, the list consists of all enabled shell builtins. If -\b-n\bn |
4812 | is supplied, only disabled builtins are printed. If -\b-a\ba is sup- | |
4813 | plied, the list printed includes all builtins, with an indica- | |
4814 | tion of whether or not each is enabled. If -\b-s\bs is supplied, the | |
4815 | output is restricted to the POSIX _\bs_\bp_\be_\bc_\bi_\ba_\bl builtins. The return | |
4816 | value is 0 unless a _\bn_\ba_\bm_\be is not a shell builtin or there is an | |
17345e5a JA |
4817 | error loading a new builtin from a shared object. |
4818 | ||
4819 | e\bev\bva\bal\bl [_\ba_\br_\bg ...] | |
712f80b0 CR |
4820 | The _\ba_\br_\bgs are read and concatenated together into a single com- |
4821 | mand. This command is then read and executed by the shell, and | |
4822 | its exit status is returned as the value of e\bev\bva\bal\bl. If there are | |
17345e5a JA |
4823 | no _\ba_\br_\bg_\bs, or only null arguments, e\bev\bva\bal\bl returns 0. |
4824 | ||
4825 | 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]] | |
712f80b0 CR |
4826 | If _\bc_\bo_\bm_\bm_\ba_\bn_\bd is specified, it replaces the shell. No new process |
4827 | 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 | 4828 | the -\b-l\bl option is supplied, the shell places a dash at the begin- |
712f80b0 CR |
4829 | ning of the zeroth argument passed to _\bc_\bo_\bm_\bm_\ba_\bn_\bd. This is what _\bl_\bo_\b- |
4830 | _\bg_\bi_\bn(1) does. The -\b-c\bc option causes _\bc_\bo_\bm_\bm_\ba_\bn_\bd to be executed with | |
4831 | an empty environment. If -\b-a\ba is supplied, the shell passes _\bn_\ba_\bm_\be | |
17345e5a | 4832 | as the zeroth argument to the executed command. If _\bc_\bo_\bm_\bm_\ba_\bn_\bd can- |
712f80b0 CR |
4833 | not be executed for some reason, a non-interactive shell exits, |
4834 | unless the e\bex\bxe\bec\bcf\bfa\bai\bil\bl shell option is enabled. In that case, it | |
4835 | returns failure. An interactive shell returns failure if the | |
4836 | file cannot be executed. A subshell exits unconditionally if | |
4837 | e\bex\bxe\bec\bc fails. If _\bc_\bo_\bm_\bm_\ba_\bn_\bd is not specified, any redirections take | |
4838 | effect in the current shell, and the return status is 0. If | |
d233b485 | 4839 | there is a redirection error, the return status is 1. |
17345e5a JA |
4840 | |
4841 | e\bex\bxi\bit\bt [_\bn] | |
712f80b0 | 4842 | Cause the shell to exit with a status of _\bn. If _\bn is omitted, |
17345e5a JA |
4843 | the exit status is that of the last command executed. A trap on |
4844 | E\bEX\bXI\bIT\bT is executed before the shell terminates. | |
4845 | ||
4846 | e\bex\bxp\bpo\bor\brt\bt [-\b-f\bfn\bn] [_\bn_\ba_\bm_\be[=_\bw_\bo_\br_\bd]] ... | |
4847 | e\bex\bxp\bpo\bor\brt\bt -\b-p\bp | |
712f80b0 CR |
4848 | The supplied _\bn_\ba_\bm_\be_\bs are marked for automatic export to the envi- |
4849 | ronment of subsequently executed commands. If the -\b-f\bf option is | |
4850 | given, the _\bn_\ba_\bm_\be_\bs refer to functions. If no _\bn_\ba_\bm_\be_\bs are given, or | |
4851 | if the -\b-p\bp option is supplied, a list of names of all exported | |
4852 | variables is printed. The -\b-n\bn option causes the export property | |
ac50fbac CR |
4853 | to be removed from each _\bn_\ba_\bm_\be. If a variable name is followed by |
4854 | =_\bw_\bo_\br_\bd, the value of the variable is set to _\bw_\bo_\br_\bd. e\bex\bxp\bpo\bor\brt\bt returns | |
4855 | an exit status of 0 unless an invalid option is encountered, one | |
712f80b0 | 4856 | of the _\bn_\ba_\bm_\be_\bs is not a valid shell variable name, or -\b-f\bf is sup- |
ac50fbac | 4857 | plied with a _\bn_\ba_\bm_\be that is not a function. |
17345e5a JA |
4858 | |
4859 | 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] | |
4860 | f\bfc\bc -\b-s\bs [_\bp_\ba_\bt=_\br_\be_\bp] [_\bc_\bm_\bd] | |
712f80b0 CR |
4861 | The first form selects a range of commands from _\bf_\bi_\br_\bs_\bt to _\bl_\ba_\bs_\bt |
4862 | from the history list and displays or edits and re-executes | |
4863 | them. _\bF_\bi_\br_\bs_\bt and _\bl_\ba_\bs_\bt may be specified as a string (to locate | |
4864 | the last command beginning with that string) or as a number (an | |
4865 | index into the history list, where a negative number is used as | |
4866 | an offset from the current command number). When listing, a | |
4867 | _\bf_\bi_\br_\bs_\bt or _\bl_\ba_\bs_\bt of 0 is equivalent to -1 and -0 is equivalent to | |
4868 | the current command (usually the f\bfc\bc command); otherwise 0 is | |
4869 | equivalent to -1 and -0 is invalid. If _\bl_\ba_\bs_\bt is not specified, | |
4870 | it is set to the current command for listing (so that ``fc -l | |
4871 | -10'' prints the last 10 commands) and to _\bf_\bi_\br_\bs_\bt otherwise. If | |
4872 | _\bf_\bi_\br_\bs_\bt is not specified, it is set to the previous command for | |
4873 | editing and -16 for listing. | |
17345e5a | 4874 | |
d233b485 CR |
4875 | The -\b-n\bn option suppresses the command numbers when listing. The |
4876 | -\b-r\br option reverses the order of the commands. If the -\b-l\bl option | |
4877 | is given, the commands are listed on standard output. Other- | |
4878 | wise, the editor given by _\be_\bn_\ba_\bm_\be is invoked on a file containing | |
4879 | those commands. If _\be_\bn_\ba_\bm_\be is not given, the value of the F\bFC\bCE\bED\bDI\bIT\bT | |
4880 | 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. | |
4881 | If neither variable is set, _\bv_\bi is used. When editing is com- | |
17345e5a JA |
4882 | plete, the edited commands are echoed and executed. |
4883 | ||
d233b485 CR |
4884 | In the second form, _\bc_\bo_\bm_\bm_\ba_\bn_\bd is re-executed after each instance |
4885 | of _\bp_\ba_\bt is replaced by _\br_\be_\bp. _\bC_\bo_\bm_\bm_\ba_\bn_\bd is interpreted the same as | |
4886 | _\bf_\bi_\br_\bs_\bt above. A useful alias to use with this is ``r="fc -s"'', | |
4887 | so that typing ``r cc'' runs the last command beginning with | |
ac50fbac | 4888 | ``cc'' and typing ``r'' re-executes the last command. |
17345e5a | 4889 | |
712f80b0 CR |
4890 | If the first form is used, the return value is 0 unless an in- |
4891 | valid option is encountered or _\bf_\bi_\br_\bs_\bt or _\bl_\ba_\bs_\bt specify history | |
d233b485 | 4892 | lines out of range. If the -\b-e\be option is supplied, the return |
17345e5a JA |
4893 | value is the value of the last command executed or failure if an |
4894 | error occurs with the temporary file of commands. If the second | |
d233b485 CR |
4895 | form is used, the return status is that of the command re-exe- |
4896 | cuted, unless _\bc_\bm_\bd does not specify a valid history line, in | |
17345e5a JA |
4897 | which case f\bfc\bc returns failure. |
4898 | ||
4899 | f\bfg\bg [_\bj_\bo_\bb_\bs_\bp_\be_\bc] | |
d233b485 | 4900 | Resume _\bj_\bo_\bb_\bs_\bp_\be_\bc in the foreground, and make it the current job. |
17345e5a | 4901 | 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 |
4902 | is used. The return value is that of the command placed into |
4903 | the foreground, or failure if run when job control is disabled | |
17345e5a | 4904 | or, when run with job control enabled, if _\bj_\bo_\bb_\bs_\bp_\be_\bc does not spec- |
d233b485 | 4905 | ify a valid job or _\bj_\bo_\bb_\bs_\bp_\be_\bc specifies a job that was started |
17345e5a JA |
4906 | without job control. |
4907 | ||
712f80b0 | 4908 | 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 |
4909 | g\bge\bet\bto\bop\bpt\bts\bs is used by shell procedures to parse positional parame- |
4910 | ters. _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg contains the option characters to be recog- | |
712f80b0 CR |
4911 | nized; if a character is followed by a colon, the option is ex- |
4912 | pected to have an argument, which should be separated from it by | |
4913 | white space. The colon and question mark characters may not be | |
4914 | used as option characters. Each time it is invoked, g\bge\bet\bto\bop\bpt\bts\bs | |
d233b485 | 4915 | places the next option in the shell variable _\bn_\ba_\bm_\be, initializing |
17345e5a JA |
4916 | _\bn_\ba_\bm_\be if it does not exist, and the index of the next argument to |
4917 | be processed into the variable O\bOP\bPT\bTI\bIN\bND\bD. O\bOP\bPT\bTI\bIN\bND\bD is initialized to | |
712f80b0 CR |
4918 | 1 each time the shell or a shell script is invoked. When an op- |
4919 | tion requires an argument, g\bge\bet\bto\bop\bpt\bts\bs places that argument into the | |
4920 | variable O\bOP\bPT\bTA\bAR\bRG\bG. The shell does not reset O\bOP\bPT\bTI\bIN\bND\bD automatically; | |
4921 | it must be manually reset between multiple calls to g\bge\bet\bto\bop\bpt\bts\bs | |
4922 | within the same shell invocation if a new set of parameters is | |
4923 | to be used. | |
17345e5a | 4924 | |
712f80b0 CR |
4925 | When the end of options is encountered, g\bge\bet\bto\bop\bpt\bts\bs exits with a re- |
4926 | turn value greater than zero. O\bOP\bPT\bTI\bIN\bND\bD is set to the index of the | |
4927 | first non-option argument, and _\bn_\ba_\bm_\be is set to ?. | |
17345e5a | 4928 | |
d233b485 | 4929 | g\bge\bet\bto\bop\bpt\bts\bs normally parses the positional parameters, but if more |
712f80b0 CR |
4930 | arguments are supplied as _\ba_\br_\bg values, g\bge\bet\bto\bop\bpt\bts\bs parses those in- |
4931 | stead. | |
4932 | ||
4933 | g\bge\bet\bto\bop\bpt\bts\bs can report errors in two ways. If the first character | |
4934 | of _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg is a colon, _\bs_\bi_\bl_\be_\bn_\bt error reporting is used. In | |
4935 | normal operation, diagnostic messages are printed when invalid | |
4936 | options or missing option arguments are encountered. If the | |
4937 | variable O\bOP\bPT\bTE\bER\bRR\bR is set to 0, no error messages will be dis- | |
17345e5a JA |
4938 | played, even if the first character of _\bo_\bp_\bt_\bs_\bt_\br_\bi_\bn_\bg is not a colon. |
4939 | ||
4940 | If an invalid option is seen, g\bge\bet\bto\bop\bpt\bts\bs places ? into _\bn_\ba_\bm_\be and, if | |
712f80b0 CR |
4941 | not silent, prints an error message and unsets O\bOP\bPT\bTA\bAR\bRG\bG. If |
4942 | g\bge\bet\bto\bop\bpt\bts\bs is silent, the option character found is placed in O\bOP\bP-\b- | |
4943 | T\bTA\bAR\bRG\bG and no diagnostic message is printed. | |
4944 | ||
4945 | If a required argument is not found, and g\bge\bet\bto\bop\bpt\bts\bs is not silent, | |
4946 | a question mark (?\b?) is placed in _\bn_\ba_\bm_\be, O\bOP\bPT\bTA\bAR\bRG\bG is unset, and a | |
4947 | diagnostic message is printed. If g\bge\bet\bto\bop\bpt\bts\bs is silent, then a | |
4948 | colon (:\b:) is placed in _\bn_\ba_\bm_\be and O\bOP\bPT\bTA\bAR\bRG\bG is set to the option | |
17345e5a JA |
4949 | character found. |
4950 | ||
712f80b0 | 4951 | g\bge\bet\bto\bop\bpt\bts\bs returns true if an option, specified or unspecified, is |
17345e5a JA |
4952 | found. It returns false if the end of options is encountered or |
4953 | an error occurs. | |
4954 | ||
4955 | 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 | 4956 | Each time h\bha\bas\bsh\bh is invoked, the full pathname of the command _\bn_\ba_\bm_\be |
712f80b0 | 4957 | is determined by searching the directories in $\b$P\bPA\bAT\bTH\bH and remem- |
495aee44 CR |
4958 | bered. Any previously-remembered pathname is discarded. If the |
4959 | -\b-p\bp option is supplied, no path search is performed, and _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be | |
712f80b0 CR |
4960 | is used as the full filename of the command. The -\b-r\br option |
4961 | causes the shell to forget all remembered locations. The -\b-d\bd op- | |
4962 | tion causes the shell to forget the remembered location of each | |
4963 | _\bn_\ba_\bm_\be. If the -\b-t\bt option is supplied, the full pathname to which | |
4964 | each _\bn_\ba_\bm_\be corresponds is printed. If multiple _\bn_\ba_\bm_\be arguments | |
4965 | are supplied with -\b-t\bt, the _\bn_\ba_\bm_\be is printed before the hashed full | |
4966 | pathname. The -\b-l\bl option causes output to be displayed in a for- | |
4967 | mat that may be reused as input. If no arguments are given, or | |
4968 | if only -\b-l\bl is supplied, information about remembered commands is | |
4969 | printed. The return status is true unless a _\bn_\ba_\bm_\be is not found | |
4970 | or an invalid option is supplied. | |
17345e5a JA |
4971 | |
4972 | h\bhe\bel\blp\bp [-\b-d\bdm\bms\bs] [_\bp_\ba_\bt_\bt_\be_\br_\bn] | |
712f80b0 CR |
4973 | Display helpful information about builtin commands. If _\bp_\ba_\bt_\bt_\be_\br_\bn |
4974 | is specified, h\bhe\bel\blp\bp gives detailed help on all commands matching | |
4975 | _\bp_\ba_\bt_\bt_\be_\br_\bn; otherwise help for all the builtins and shell control | |
17345e5a JA |
4976 | structures is printed. |
4977 | -\b-d\bd Display a short description of each _\bp_\ba_\bt_\bt_\be_\br_\bn | |
0001803f | 4978 | -\b-m\bm Display the description of each _\bp_\ba_\bt_\bt_\be_\br_\bn in a manpage-like |
17345e5a JA |
4979 | format |
4980 | -\b-s\bs Display only a short usage synopsis for each _\bp_\ba_\bt_\bt_\be_\br_\bn | |
ac50fbac CR |
4981 | |
4982 | The return status is 0 unless no command matches _\bp_\ba_\bt_\bt_\be_\br_\bn. | |
17345e5a JA |
4983 | |
4984 | h\bhi\bis\bst\bto\bor\bry\by [\b[_\bn]\b] | |
4985 | h\bhi\bis\bst\bto\bor\bry\by -\b-c\bc | |
4986 | h\bhi\bis\bst\bto\bor\bry\by -\b-d\bd _\bo_\bf_\bf_\bs_\be_\bt | |
d233b485 | 4987 | h\bhi\bis\bst\bto\bor\bry\by -\b-d\bd _\bs_\bt_\ba_\br_\bt-_\be_\bn_\bd |
17345e5a JA |
4988 | h\bhi\bis\bst\bto\bor\bry\by -\b-a\ban\bnr\brw\bw [_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be] |
4989 | h\bhi\bis\bst\bto\bor\bry\by -\b-p\bp _\ba_\br_\bg [_\ba_\br_\bg _\b._\b._\b.] | |
4990 | h\bhi\bis\bst\bto\bor\bry\by -\b-s\bs _\ba_\br_\bg [_\ba_\br_\bg _\b._\b._\b.] | |
4991 | With no options, display the command history list with line num- | |
4992 | bers. Lines listed with a *\b* have been modified. An argument of | |
712f80b0 CR |
4993 | _\bn lists only the last _\bn lines. If the shell variable H\bHI\bIS\bST\bTT\bTI\bIM\bME\bE-\b- |
4994 | F\bFO\bOR\bRM\bMA\bAT\bT is set and not null, it is used as a format string for | |
4995 | _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be(3) to display the time stamp associated with each dis- | |
4996 | played history entry. No intervening blank is printed between | |
4997 | the formatted time stamp and the history line. If _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be is | |
4998 | supplied, it is used as the name of the history file; if not, | |
4999 | the value of H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE is used. Options, if supplied, have the | |
17345e5a JA |
5000 | following meanings: |
5001 | -\b-c\bc Clear the history list by deleting all the entries. | |
5002 | -\b-d\bd _\bo_\bf_\bf_\bs_\be_\bt | |
712f80b0 | 5003 | Delete the history entry at position _\bo_\bf_\bf_\bs_\be_\bt. If _\bo_\bf_\bf_\bs_\be_\bt |
d233b485 CR |
5004 | is negative, it is interpreted as relative to one greater |
5005 | than the last history position, so negative indices count | |
712f80b0 | 5006 | back from the end of the history, and an index of -1 |
d233b485 CR |
5007 | refers to the current h\bhi\bis\bst\bto\bor\bry\by -\b-d\bd command. |
5008 | -\b-d\bd _\bs_\bt_\ba_\br_\bt-_\be_\bn_\bd | |
712f80b0 CR |
5009 | Delete the history entries between positions _\bs_\bt_\ba_\br_\bt and |
5010 | _\be_\bn_\bd, inclusive. Positive and negative values for _\bs_\bt_\ba_\br_\bt | |
d233b485 | 5011 | and _\be_\bn_\bd are interpreted as described above. |
712f80b0 CR |
5012 | -\b-a\ba Append the ``new'' history lines to the history file. |
5013 | These are history lines entered since the beginning of | |
a0c0a00f | 5014 | the current b\bba\bas\bsh\bh session, but not already appended to the |
17345e5a | 5015 | history file. |
712f80b0 CR |
5016 | -\b-n\bn Read the history lines not already read from the history |
5017 | file into the current history list. These are lines ap- | |
5018 | pended to the history file since the beginning of the | |
17345e5a | 5019 | current b\bba\bas\bsh\bh session. |
712f80b0 | 5020 | -\b-r\br Read the contents of the history file and append them to |
ac50fbac CR |
5021 | the current history list. |
5022 | -\b-w\bw Write the current history list to the history file, over- | |
5023 | writing the history file's contents. | |
712f80b0 CR |
5024 | -\b-p\bp Perform history substitution on the following _\ba_\br_\bg_\bs and |
5025 | display the result on the standard output. Does not | |
5026 | store the results in the history list. Each _\ba_\br_\bg must be | |
17345e5a | 5027 | quoted to disable normal history expansion. |
712f80b0 CR |
5028 | -\b-s\bs Store the _\ba_\br_\bg_\bs in the history list as a single entry. |
5029 | The last command in the history list is removed before | |
17345e5a JA |
5030 | the _\ba_\br_\bg_\bs are added. |
5031 | ||
712f80b0 CR |
5032 | If the H\bHI\bIS\bST\bTT\bTI\bIM\bME\bEF\bFO\bOR\bRM\bMA\bAT\bT variable is set, the time stamp informa- |
5033 | tion associated with each history entry is written to the his- | |
5034 | tory file, marked with the history comment character. When the | |
5035 | history file is read, lines beginning with the history comment | |
5036 | character followed immediately by a digit are interpreted as | |
a0c0a00f CR |
5037 | timestamps for the following history entry. The return value is |
5038 | 0 unless an invalid option is encountered, an error occurs while | |
712f80b0 | 5039 | reading or writing the history file, an invalid _\bo_\bf_\bf_\bs_\be_\bt is sup- |
0001803f CR |
5040 | plied as an argument to -\b-d\bd, or the history expansion supplied as |
5041 | an argument to -\b-p\bp fails. | |
17345e5a JA |
5042 | |
5043 | j\bjo\bob\bbs\bs [-\b-l\bln\bnp\bpr\brs\bs] [ _\bj_\bo_\bb_\bs_\bp_\be_\bc ... ] | |
5044 | j\bjo\bob\bbs\bs -\b-x\bx _\bc_\bo_\bm_\bm_\ba_\bn_\bd [ _\ba_\br_\bg_\bs ... ] | |
5045 | The first form lists the active jobs. The options have the fol- | |
5046 | lowing meanings: | |
5047 | -\b-l\bl List process IDs in addition to the normal information. | |
712f80b0 | 5048 | -\b-n\bn Display information only about jobs that have changed |
a0c0a00f | 5049 | status since the user was last notified of their status. |
712f80b0 | 5050 | -\b-p\bp List only the process ID of the job's process group |
495aee44 | 5051 | leader. |
ac50fbac CR |
5052 | -\b-r\br Display only running jobs. |
5053 | -\b-s\bs Display only stopped jobs. | |
17345e5a | 5054 | |
712f80b0 CR |
5055 | If _\bj_\bo_\bb_\bs_\bp_\be_\bc is given, output is restricted to information about |
5056 | that job. The return status is 0 unless an invalid option is | |
17345e5a JA |
5057 | encountered or an invalid _\bj_\bo_\bb_\bs_\bp_\be_\bc is supplied. |
5058 | ||
5059 | If the -\b-x\bx option is supplied, j\bjo\bob\bbs\bs replaces any _\bj_\bo_\bb_\bs_\bp_\be_\bc found in | |
712f80b0 CR |
5060 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd or _\ba_\br_\bg_\bs with the corresponding process group ID, and ex- |
5061 | ecutes _\bc_\bo_\bm_\bm_\ba_\bn_\bd passing it _\ba_\br_\bg_\bs, returning its exit status. | |
17345e5a JA |
5062 | |
5063 | 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 | 5064 | 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] |
712f80b0 CR |
5065 | Send the signal named by _\bs_\bi_\bg_\bs_\bp_\be_\bc or _\bs_\bi_\bg_\bn_\bu_\bm to the processes |
5066 | 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 | |
5067 | signal name such as S\bSI\bIG\bGK\bKI\bIL\bLL\bL (with or without the S\bSI\bIG\bG prefix) or | |
5068 | a signal number; _\bs_\bi_\bg_\bn_\bu_\bm is a signal number. If _\bs_\bi_\bg_\bs_\bp_\be_\bc is not | |
5069 | present, then S\bSI\bIG\bGT\bTE\bER\bRM\bM is assumed. An argument of -\b-l\bl lists the | |
5070 | signal names. If any arguments are supplied when -\b-l\bl is given, | |
5071 | the names of the signals corresponding to the arguments are | |
17345e5a | 5072 | listed, and the return status is 0. The _\be_\bx_\bi_\bt_\b__\bs_\bt_\ba_\bt_\bu_\bs argument to |
712f80b0 CR |
5073 | -\b-l\bl is a number specifying either a signal number or the exit |
5074 | status of a process terminated by a signal. The -\b-L\bL option is | |
5075 | equivalent to -\b-l\bl. k\bki\bil\bll\bl returns true if at least one signal was | |
5076 | successfully sent, or false if an error occurs or an invalid op- | |
5077 | tion is encountered. | |
17345e5a JA |
5078 | |
5079 | l\ble\bet\bt _\ba_\br_\bg [_\ba_\br_\bg ...] | |
5080 | Each _\ba_\br_\bg is an arithmetic expression to be evaluated (see A\bAR\bRI\bIT\bTH\bH-\b- | |
712f80b0 | 5081 | 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 | 5082 | returns 1; 0 is returned otherwise. |
17345e5a | 5083 | |
a0c0a00f | 5084 | l\blo\boc\bca\bal\bl [_\bo_\bp_\bt_\bi_\bo_\bn] [_\bn_\ba_\bm_\be[=_\bv_\ba_\bl_\bu_\be] ... | - ] |
712f80b0 CR |
5085 | For each argument, a local variable named _\bn_\ba_\bm_\be is created, and |
5086 | assigned _\bv_\ba_\bl_\bu_\be. The _\bo_\bp_\bt_\bi_\bo_\bn can be any of the options accepted | |
17345e5a | 5087 | by d\bde\bec\bcl\bla\bar\bre\be. When l\blo\boc\bca\bal\bl is used within a function, it causes the |
712f80b0 CR |
5088 | variable _\bn_\ba_\bm_\be to have a visible scope restricted to that func- |
5089 | tion and its children. If _\bn_\ba_\bm_\be is -, the set of shell options | |
5090 | is made local to the function in which l\blo\boc\bca\bal\bl is invoked: shell | |
5091 | options changed using the s\bse\bet\bt builtin inside the function are | |
5092 | restored to their original values when the function returns. | |
3eb0018e CR |
5093 | The restore is effected as if a series of s\bse\bet\bt commands were exe- |
5094 | cuted to restore the values that were in place before the func- | |
5095 | tion. With no operands, l\blo\boc\bca\bal\bl writes a list of local variables | |
5096 | to the standard output. It is an error to use l\blo\boc\bca\bal\bl when not | |
5097 | within a function. The return status is 0 unless l\blo\boc\bca\bal\bl is used | |
5098 | outside a function, an invalid _\bn_\ba_\bm_\be is supplied, or _\bn_\ba_\bm_\be is a | |
5099 | readonly variable. | |
17345e5a JA |
5100 | |
5101 | l\blo\bog\bgo\bou\but\bt Exit a login shell. | |
5102 | ||
712f80b0 | 5103 | 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 |
5104 | _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk] [-\b-c\bc _\bq_\bu_\ba_\bn_\bt_\bu_\bm] [_\ba_\br_\br_\ba_\by] |
5105 | 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 | |
5106 | _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk] [-\b-c\bc _\bq_\bu_\ba_\bn_\bt_\bu_\bm] [_\ba_\br_\br_\ba_\by] | |
712f80b0 CR |
5107 | Read lines from the standard input into the indexed array vari- |
5108 | able _\ba_\br_\br_\ba_\by, or from file descriptor _\bf_\bd if the -\b-u\bu option is sup- | |
5109 | plied. The variable M\bMA\bAP\bPF\bFI\bIL\bLE\bE is the default _\ba_\br_\br_\ba_\by. Options, if | |
0001803f | 5110 | supplied, have the following meanings: |
712f80b0 CR |
5111 | -\b-d\bd The first character of _\bd_\be_\bl_\bi_\bm is used to terminate each |
5112 | input line, rather than newline. If _\bd_\be_\bl_\bi_\bm is the empty | |
d233b485 CR |
5113 | string, m\bma\bap\bpf\bfi\bil\ble\be will terminate a line when it reads a NUL |
5114 | character. | |
712f80b0 | 5115 | -\b-n\bn Copy at most _\bc_\bo_\bu_\bn_\bt lines. If _\bc_\bo_\bu_\bn_\bt is 0, all lines are |
17345e5a | 5116 | copied. |
712f80b0 | 5117 | -\b-O\bO Begin assigning to _\ba_\br_\br_\ba_\by at index _\bo_\br_\bi_\bg_\bi_\bn. The default |
17345e5a JA |
5118 | index is 0. |
5119 | -\b-s\bs Discard the first _\bc_\bo_\bu_\bn_\bt lines read. | |
712f80b0 | 5120 | -\b-t\bt Remove a trailing _\bd_\be_\bl_\bi_\bm (default newline) from each line |
a0c0a00f | 5121 | read. |
712f80b0 | 5122 | -\b-u\bu Read lines from file descriptor _\bf_\bd instead of the stan- |
17345e5a | 5123 | dard input. |
712f80b0 | 5124 | -\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 | 5125 | -\b-c\bc option specifies _\bq_\bu_\ba_\bn_\bt_\bu_\bm. |
712f80b0 | 5126 | -\b-c\bc Specify the number of lines read between each call to |
17345e5a JA |
5127 | _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk. |
5128 | ||
712f80b0 | 5129 | If -\b-C\bC is specified without -\b-c\bc, the default quantum is 5000. |
17345e5a | 5130 | When _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk is evaluated, it is supplied the index of the next |
495aee44 | 5131 | array element to be assigned and the line to be assigned to that |
712f80b0 | 5132 | element as additional arguments. _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk is evaluated after |
495aee44 | 5133 | the line is read but before the array element is assigned. |
17345e5a | 5134 | |
712f80b0 CR |
5135 | If not supplied with an explicit origin, m\bma\bap\bpf\bfi\bil\ble\be will clear _\ba_\br_\b- |
5136 | _\br_\ba_\by before assigning to it. | |
17345e5a | 5137 | |
712f80b0 CR |
5138 | m\bma\bap\bpf\bfi\bil\ble\be returns successfully unless an invalid option or option |
5139 | argument is supplied, _\ba_\br_\br_\ba_\by is invalid or unassignable, or if | |
0001803f | 5140 | _\ba_\br_\br_\ba_\by is not an indexed array. |
17345e5a JA |
5141 | |
5142 | p\bpo\bop\bpd\bd [-n\bn] [+_\bn] [-_\bn] | |
712f80b0 CR |
5143 | Removes entries from the directory stack. With no arguments, |
5144 | removes the top directory from the stack, and performs a c\bcd\bd to | |
17345e5a JA |
5145 | the new top directory. Arguments, if supplied, have the follow- |
5146 | ing meanings: | |
712f80b0 CR |
5147 | -\b-n\bn Suppresses the normal change of directory when removing |
5148 | directories from the stack, so that only the stack is ma- | |
5149 | nipulated. | |
5150 | +\b+_\bn Removes the _\bnth entry counting from the left of the list | |
5151 | shown by d\bdi\bir\brs\bs, starting with zero. For example: ``popd | |
17345e5a JA |
5152 | +0'' removes the first directory, ``popd +1'' the second. |
5153 | -\b-_\bn Removes the _\bnth entry counting from the right of the list | |
712f80b0 CR |
5154 | shown by d\bdi\bir\brs\bs, starting with zero. For example: ``popd |
5155 | -0'' removes the last directory, ``popd -1'' the next to | |
17345e5a JA |
5156 | last. |
5157 | ||
712f80b0 CR |
5158 | If the p\bpo\bop\bpd\bd command is successful, a d\bdi\bir\brs\bs is performed as well, |
5159 | and the return status is 0. p\bpo\bop\bpd\bd returns false if an invalid | |
17345e5a JA |
5160 | option is encountered, the directory stack is empty, a non-exis- |
5161 | tent directory stack entry is specified, or the directory change | |
5162 | fails. | |
5163 | ||
5164 | 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] | |
712f80b0 CR |
5165 | Write the formatted _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs to the standard output under the |
5166 | control of the _\bf_\bo_\br_\bm_\ba_\bt. The -\b-v\bv option causes the output to be | |
5167 | assigned to the variable _\bv_\ba_\br rather than being printed to the | |
495aee44 CR |
5168 | standard output. |
5169 | ||
712f80b0 CR |
5170 | The _\bf_\bo_\br_\bm_\ba_\bt is a character string which contains three types of |
5171 | objects: plain characters, which are simply copied to standard | |
5172 | output, character escape sequences, which are converted and | |
5173 | copied to the standard output, and format specifications, each | |
5174 | of which causes printing of the next successive _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt. In | |
495aee44 CR |
5175 | addition to the standard _\bp_\br_\bi_\bn_\bt_\bf(1) format specifications, p\bpr\bri\bin\bnt\btf\bf |
5176 | interprets the following extensions: | |
5177 | %\b%b\bb causes p\bpr\bri\bin\bnt\btf\bf to expand backslash escape sequences in the | |
a0c0a00f | 5178 | corresponding _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt in the same way as e\bec\bch\bho\bo -\b-e\be. |
712f80b0 | 5179 | %\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 CR |
5180 | format that can be reused as shell input. |
5181 | %\b%(\b(_\bd_\ba_\bt_\be_\bf_\bm_\bt)\b)T\bT | |
712f80b0 CR |
5182 | causes p\bpr\bri\bin\bnt\btf\bf to output the date-time string resulting |
5183 | from using _\bd_\ba_\bt_\be_\bf_\bm_\bt as a format string for _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be(3). | |
495aee44 | 5184 | The corresponding _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt is an integer representing the |
712f80b0 CR |
5185 | number of seconds since the epoch. Two special argument |
5186 | values may be used: -1 represents the current time, and | |
5187 | -2 represents the time the shell was invoked. If no ar- | |
5188 | gument is specified, conversion behaves as if -1 had been | |
5189 | given. This is an exception to the usual p\bpr\bri\bin\bnt\btf\bf behav- | |
5190 | ior. | |
5191 | ||
5192 | The %b, %q, and %T directives all use the field width and preci- | |
5193 | sion arguments from the format specification and write that many | |
5194 | bytes from (or use that wide a field for) the expanded argument, | |
5195 | which usually contains more characters than the original. | |
495aee44 | 5196 | |
d233b485 | 5197 | Arguments to non-string format specifiers are treated as C con- |
495aee44 | 5198 | stants, except that a leading plus or minus sign is allowed, and |
d233b485 | 5199 | if the leading character is a single or double quote, the value |
495aee44 | 5200 | is the ASCII value of the following character. |
17345e5a | 5201 | |
d233b485 | 5202 | The _\bf_\bo_\br_\bm_\ba_\bt is reused as necessary to consume all of the _\ba_\br_\bg_\bu_\b- |
17345e5a | 5203 | _\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 |
5204 | the extra format specifications behave as if a zero value or |
5205 | null string, as appropriate, had been supplied. The return | |
17345e5a JA |
5206 | value is zero on success, non-zero on failure. |
5207 | ||
5208 | p\bpu\bus\bsh\bhd\bd [-\b-n\bn] [+_\bn] [-_\bn] | |
5209 | p\bpu\bus\bsh\bhd\bd [-\b-n\bn] [_\bd_\bi_\br] | |
d233b485 CR |
5210 | Adds a directory to the top of the directory stack, or rotates |
5211 | the stack, making the new top of the stack the current working | |
712f80b0 CR |
5212 | directory. With no arguments, p\bpu\bus\bsh\bhd\bd exchanges the top two di- |
5213 | rectories and returns 0, unless the directory stack is empty. | |
a0c0a00f | 5214 | Arguments, if supplied, have the following meanings: |
d233b485 CR |
5215 | -\b-n\bn Suppresses the normal change of directory when rotating |
5216 | or adding directories to the stack, so that only the | |
a0c0a00f | 5217 | stack is manipulated. |
d233b485 CR |
5218 | +\b+_\bn Rotates the stack so that the _\bnth directory (counting |
5219 | from the left of the list shown by d\bdi\bir\brs\bs, starting with | |
17345e5a | 5220 | zero) is at the top. |
d233b485 CR |
5221 | -\b-_\bn Rotates the stack so that the _\bnth directory (counting |
5222 | from the right of the list shown by d\bdi\bir\brs\bs, starting with | |
17345e5a JA |
5223 | zero) is at the top. |
5224 | _\bd_\bi_\br Adds _\bd_\bi_\br to the directory stack at the top, making it the | |
d233b485 | 5225 | new current working directory as if it had been supplied |
ac50fbac | 5226 | as the argument to the c\bcd\bd builtin. |
17345e5a JA |
5227 | |
5228 | If the p\bpu\bus\bsh\bhd\bd command is successful, a d\bdi\bir\brs\bs is performed as well. | |
d233b485 CR |
5229 | If the first form is used, p\bpu\bus\bsh\bhd\bd returns 0 unless the cd to _\bd_\bi_\br |
5230 | fails. With the second form, p\bpu\bus\bsh\bhd\bd returns 0 unless the direc- | |
5231 | tory stack is empty, a non-existent directory stack element is | |
5232 | specified, or the directory change to the specified new current | |
17345e5a JA |
5233 | directory fails. |
5234 | ||
5235 | p\bpw\bwd\bd [-\b-L\bLP\bP] | |
d233b485 | 5236 | Print the absolute pathname of the current working directory. |
17345e5a JA |
5237 | The pathname printed contains no symbolic links if the -\b-P\bP option |
5238 | 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 |
5239 | is enabled. If the -\b-L\bL option is used, the pathname printed may |
5240 | contain symbolic links. The return status is 0 unless an error | |
712f80b0 CR |
5241 | occurs while reading the name of the current directory or an in- |
5242 | valid option is supplied. | |
17345e5a | 5243 | |
0001803f CR |
5244 | 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 |
5245 | _\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 ...] | |
712f80b0 CR |
5246 | One line is read from the standard input, or from the file de- |
5247 | scriptor _\bf_\bd supplied as an argument to the -\b-u\bu option, split into | |
5248 | words as described above under W\bWo\bor\brd\bd S\bSp\bpl\bli\bit\btt\bti\bin\bng\bg, and the first | |
5249 | word is assigned to the first _\bn_\ba_\bm_\be, the second word to the sec- | |
5250 | ond _\bn_\ba_\bm_\be, and so on. If there are more words than names, the | |
a0c0a00f | 5251 | remaining words and their intervening delimiters are assigned to |
d233b485 CR |
5252 | the last _\bn_\ba_\bm_\be. If there are fewer words read from the input |
5253 | stream than names, the remaining names are assigned empty val- | |
5254 | ues. The characters in I\bIF\bFS\bS are used to split the line into | |
712f80b0 CR |
5255 | words using the same rules the shell uses for expansion (de- |
5256 | scribed above under W\bWo\bor\brd\bd S\bSp\bpl\bli\bit\btt\bti\bin\bng\bg). The backslash character | |
a0c0a00f | 5257 | (\\b\) may be used to remove any special meaning for the next char- |
d233b485 | 5258 | acter read and for line continuation. Options, if supplied, |
a0c0a00f | 5259 | have the following meanings: |
17345e5a JA |
5260 | -\b-a\ba _\ba_\bn_\ba_\bm_\be |
5261 | The words are assigned to sequential indices of the array | |
5262 | variable _\ba_\bn_\ba_\bm_\be, starting at 0. _\ba_\bn_\ba_\bm_\be is unset before any | |
712f80b0 CR |
5263 | new values are assigned. Other _\bn_\ba_\bm_\be arguments are ig- |
5264 | nored. | |
17345e5a | 5265 | -\b-d\bd _\bd_\be_\bl_\bi_\bm |
712f80b0 CR |
5266 | The first character of _\bd_\be_\bl_\bi_\bm is used to terminate the in- |
5267 | put line, rather than newline. If _\bd_\be_\bl_\bi_\bm is the empty | |
d233b485 CR |
5268 | string, r\bre\bea\bad\bd will terminate a line when it reads a NUL |
5269 | character. | |
17345e5a | 5270 | -\b-e\be If the standard input is coming from a terminal, r\bre\bea\bad\bdl\bli\bin\bne\be |
d233b485 CR |
5271 | (see R\bRE\bEA\bAD\bDL\bLI\bIN\bNE\bE above) is used to obtain the line. Read- |
5272 | line uses the current (or default, if line editing was | |
5273 | not previously active) editing settings, but uses Read- | |
5274 | line's default filename completion. | |
17345e5a | 5275 | -\b-i\bi _\bt_\be_\bx_\bt |
ac50fbac | 5276 | If r\bre\bea\bad\bdl\bli\bin\bne\be is being used to read the line, _\bt_\be_\bx_\bt is |
17345e5a JA |
5277 | placed into the editing buffer before editing begins. |
5278 | -\b-n\bn _\bn_\bc_\bh_\ba_\br_\bs | |
ac50fbac | 5279 | r\bre\bea\bad\bd returns after reading _\bn_\bc_\bh_\ba_\br_\bs characters rather than |
a0c0a00f | 5280 | waiting for a complete line of input, but honors a delim- |
ac50fbac | 5281 | iter if fewer than _\bn_\bc_\bh_\ba_\br_\bs characters are read before the |
0001803f CR |
5282 | delimiter. |
5283 | -\b-N\bN _\bn_\bc_\bh_\ba_\br_\bs | |
ac50fbac CR |
5284 | r\bre\bea\bad\bd returns after reading exactly _\bn_\bc_\bh_\ba_\br_\bs characters |
5285 | rather than waiting for a complete line of input, unless | |
5286 | EOF is encountered or r\bre\bea\bad\bd times out. Delimiter charac- | |
5287 | ters encountered in the input are not treated specially | |
5288 | and do not cause r\bre\bea\bad\bd to return until _\bn_\bc_\bh_\ba_\br_\bs characters | |
a0c0a00f CR |
5289 | are read. The result is not split on the characters in |
5290 | I\bIF\bFS\bS; the intent is that the variable is assigned exactly | |
5291 | the characters read (with the exception of backslash; see | |
5292 | the -\b-r\br option below). | |
17345e5a JA |
5293 | -\b-p\bp _\bp_\br_\bo_\bm_\bp_\bt |
5294 | Display _\bp_\br_\bo_\bm_\bp_\bt on standard error, without a trailing new- | |
5295 | line, before attempting to read any input. The prompt is | |
5296 | displayed only if input is coming from a terminal. | |
5297 | -\b-r\br Backslash does not act as an escape character. The back- | |
a0c0a00f | 5298 | slash is considered to be part of the line. In particu- |
d233b485 CR |
5299 | lar, a backslash-newline pair may not then be used as a |
5300 | line continuation. | |
17345e5a JA |
5301 | -\b-s\bs Silent mode. If input is coming from a terminal, charac- |
5302 | ters are not echoed. | |
5303 | -\b-t\bt _\bt_\bi_\bm_\be_\bo_\bu_\bt | |
a0c0a00f CR |
5304 | Cause r\bre\bea\bad\bd to time out and return failure if a complete |
5305 | line of input (or a specified number of characters) is | |
5306 | not read within _\bt_\bi_\bm_\be_\bo_\bu_\bt seconds. _\bt_\bi_\bm_\be_\bo_\bu_\bt may be a deci- | |
5307 | mal number with a fractional portion following the deci- | |
5308 | mal point. This option is only effective if r\bre\bea\bad\bd is | |
5309 | reading input from a terminal, pipe, or other special | |
5310 | file; it has no effect when reading from regular files. | |
ac50fbac | 5311 | If r\bre\bea\bad\bd times out, r\bre\bea\bad\bd saves any partial input read into |
712f80b0 CR |
5312 | the specified variable _\bn_\ba_\bm_\be. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is 0, r\bre\bea\bad\bd re- |
5313 | turns immediately, without trying to read any data. The | |
5314 | exit status is 0 if input is available on the specified | |
5315 | file descriptor, non-zero otherwise. The exit status is | |
5316 | greater than 128 if the timeout is exceeded. | |
17345e5a JA |
5317 | -\b-u\bu _\bf_\bd Read input from file descriptor _\bf_\bd. |
5318 | ||
3eb0018e CR |
5319 | If no _\bn_\ba_\bm_\be_\bs are supplied, the line read, without the ending de- |
5320 | limiter but otherwise unmodified, is assigned to the variable | |
5321 | R\bRE\bEP\bPL\bLY\bY. The exit status is zero, unless end-of-file is encoun- | |
5322 | tered, r\bre\bea\bad\bd times out (in which case the status is greater than | |
5323 | 128), a variable assignment error (such as assigning to a read- | |
5324 | only variable) occurs, or an invalid file descriptor is supplied | |
5325 | as the argument to -\b-u\bu. | |
ac50fbac CR |
5326 | |
5327 | 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] ...] | |
3eb0018e CR |
5328 | The given _\bn_\ba_\bm_\be_\bs are marked readonly; the values of these _\bn_\ba_\bm_\be_\bs |
5329 | may not be changed by subsequent assignment. If the -\b-f\bf option | |
5330 | is supplied, the functions corresponding to the _\bn_\ba_\bm_\be_\bs are so | |
5331 | marked. The -\b-a\ba option restricts the variables to indexed ar- | |
5332 | rays; the -\b-A\bA option restricts the variables to associative ar- | |
712f80b0 | 5333 | rays. If both options are supplied, -\b-A\bA takes precedence. If no |
3eb0018e | 5334 | _\bn_\ba_\bm_\be arguments are given, or if the -\b-p\bp option is supplied, a |
ac50fbac | 5335 | list of all readonly names is printed. The other options may be |
3eb0018e CR |
5336 | used to restrict the output to a subset of the set of readonly |
5337 | names. The -\b-p\bp option causes output to be displayed in a format | |
5338 | that may be reused as input. If a variable name is followed by | |
5339 | =_\bw_\bo_\br_\bd, the value of the variable is set to _\bw_\bo_\br_\bd. The return | |
5340 | status is 0 unless an invalid option is encountered, one of the | |
ac50fbac CR |
5341 | _\bn_\ba_\bm_\be_\bs is not a valid shell variable name, or -\b-f\bf is supplied with |
5342 | a _\bn_\ba_\bm_\be that is not a function. | |
17345e5a JA |
5343 | |
5344 | r\bre\bet\btu\bur\brn\bn [_\bn] | |
3eb0018e CR |
5345 | Causes a function to stop executing and return the value speci- |
5346 | fied by _\bn to its caller. If _\bn is omitted, the return status is | |
5347 | that of the last command executed in the function body. If r\bre\be-\b- | |
712f80b0 | 5348 | t\btu\bur\brn\bn is executed by a trap handler, the last command used to de- |
3eb0018e CR |
5349 | termine the status is the last command executed before the trap |
5350 | handler. If r\bre\bet\btu\bur\brn\bn is executed during a D\bDE\bEB\bBU\bUG\bG trap, the last | |
5351 | command used to determine the status is the last command exe- | |
5352 | cuted by the trap handler before r\bre\bet\btu\bur\brn\bn was invoked. If r\bre\bet\btu\bur\brn\bn | |
5353 | is used outside a function, but during execution of a script by | |
5354 | the .\b. (s\bso\bou\bur\brc\bce\be) command, it causes the shell to stop executing | |
5355 | that script and return either _\bn or the exit status of the last | |
5356 | command executed within the script as the exit status of the | |
712f80b0 | 5357 | script. If _\bn is supplied, the return value is its least signif- |
3eb0018e CR |
5358 | icant 8 bits. The return status is non-zero if r\bre\bet\btu\bur\brn\bn is sup- |
5359 | plied a non-numeric argument, or is used outside a function and | |
5360 | not during execution of a script by .\b. or s\bso\bou\bur\brc\bce\be. Any command | |
712f80b0 CR |
5361 | associated with the R\bRE\bET\bTU\bUR\bRN\bN trap is executed before execution re- |
5362 | sumes after the function or script. | |
17345e5a | 5363 | |
495aee44 CR |
5364 | s\bse\bet\bt [-\b--\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] [_\ba_\br_\bg ...] |
5365 | 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] [_\ba_\br_\bg ...] | |
3eb0018e | 5366 | Without options, the name and value of each shell variable are |
17345e5a JA |
5367 | displayed in a format that can be reused as input for setting or |
5368 | resetting the currently-set variables. Read-only variables can- | |
3eb0018e CR |
5369 | not be reset. In _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be, only shell variables are listed. |
5370 | The output is sorted according to the current locale. When op- | |
5371 | tions are specified, they set or unset shell attributes. Any | |
5372 | arguments remaining after option processing are treated as val- | |
17345e5a | 5373 | ues for the positional parameters and are assigned, in order, to |
3eb0018e | 5374 | $\b$1\b1, $\b$2\b2, .\b..\b..\b. $\b$_\bn. Options, if specified, have the following |
17345e5a | 5375 | meanings: |
a0c0a00f | 5376 | -\b-a\ba Each variable or function that is created or modified is |
3eb0018e | 5377 | given the export attribute and marked for export to the |
a0c0a00f | 5378 | environment of subsequent commands. |
3eb0018e | 5379 | -\b-b\bb Report the status of terminated background jobs immedi- |
17345e5a JA |
5380 | ately, rather than before the next primary prompt. This |
5381 | is effective only when job control is enabled. | |
3eb0018e CR |
5382 | -\b-e\be Exit immediately if a _\bp_\bi_\bp_\be_\bl_\bi_\bn_\be (which may consist of a |
5383 | 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 | 5384 | (see S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR above), exits with a non-zero status. |
3eb0018e CR |
5385 | The shell does not exit if the command that fails is |
5386 | part of the command list immediately following a w\bwh\bhi\bil\ble\be | |
5387 | or u\bun\bnt\bti\bil\bl keyword, part of the test following the i\bif\bf or | |
5388 | e\bel\bli\bif\bf reserved words, part of any command executed in a | |
5389 | &\b&&\b& or |\b||\b| list except the command following the final &\b&&\b& | |
a0c0a00f | 5390 | or |\b||\b|, any command in a pipeline but the last, or if the |
3eb0018e CR |
5391 | command's return value is being inverted with !\b!. If a |
5392 | compound command other than a subshell returns a non- | |
5393 | zero status because a command failed while -\b-e\be was being | |
5394 | ignored, the shell does not exit. A trap on E\bER\bRR\bR, if | |
5395 | set, is executed before the shell exits. This option | |
0001803f | 5396 | applies to the shell environment and each subshell envi- |
3eb0018e | 5397 | 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 |
5398 | above), and may cause subshells to exit before executing |
5399 | all the commands in the subshell. | |
ac50fbac | 5400 | |
3eb0018e CR |
5401 | If a compound command or shell function executes in a |
5402 | context where -\b-e\be is being ignored, none of the commands | |
5403 | executed within the compound command or function body | |
5404 | will be affected by the -\b-e\be setting, even if -\b-e\be is set | |
5405 | and a command returns a failure status. If a compound | |
5406 | command or shell function sets -\b-e\be while executing in a | |
5407 | context where -\b-e\be is ignored, that setting will not have | |
5408 | any effect until the compound command or the command | |
ac50fbac | 5409 | containing the function call completes. |
17345e5a | 5410 | -\b-f\bf Disable pathname expansion. |
3eb0018e | 5411 | -\b-h\bh Remember the location of commands as they are looked up |
17345e5a | 5412 | for execution. This is enabled by default. |
3eb0018e CR |
5413 | -\b-k\bk All arguments in the form of assignment statements are |
5414 | placed in the environment for a command, not just those | |
17345e5a | 5415 | that precede the command name. |
3eb0018e CR |
5416 | -\b-m\bm Monitor mode. Job control is enabled. This option is |
5417 | on by default for interactive shells on systems that | |
5418 | support it (see J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL above). All processes run | |
ac50fbac CR |
5419 | in a separate process group. When a background job com- |
5420 | pletes, the shell prints a line containing its exit sta- | |
5421 | tus. | |
17345e5a | 5422 | -\b-n\bn Read commands but do not execute them. This may be used |
3eb0018e | 5423 | to check a shell script for syntax errors. This is ig- |
712f80b0 | 5424 | nored by interactive shells. |
17345e5a JA |
5425 | -\b-o\bo _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be |
5426 | The _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be can be one of the following: | |
5427 | a\bal\bll\ble\bex\bxp\bpo\bor\brt\bt | |
5428 | Same as -\b-a\ba. | |
5429 | b\bbr\bra\bac\bce\bee\bex\bxp\bpa\ban\bnd\bd | |
5430 | Same as -\b-B\bB. | |
3eb0018e | 5431 | e\bem\bma\bac\bcs\bs Use an emacs-style command line editing inter- |
17345e5a JA |
5432 | face. This is enabled by default when the shell |
5433 | is interactive, unless the shell is started with | |
3eb0018e | 5434 | the -\b--\b-n\bno\boe\bed\bdi\bit\bti\bin\bng\bg option. This also affects the |
17345e5a | 5435 | editing interface used for r\bre\bea\bad\bd -\b-e\be. |
0001803f | 5436 | e\ber\brr\bre\bex\bxi\bit\bt Same as -\b-e\be. |
17345e5a JA |
5437 | e\ber\brr\brt\btr\bra\bac\bce\be |
5438 | Same as -\b-E\bE. | |
5439 | f\bfu\bun\bnc\bct\btr\bra\bac\bce\be | |
5440 | Same as -\b-T\bT. | |
17345e5a JA |
5441 | h\bha\bas\bsh\bha\bal\bll\bl Same as -\b-h\bh. |
5442 | h\bhi\bis\bst\bte\bex\bxp\bpa\ban\bnd\bd | |
5443 | Same as -\b-H\bH. | |
5444 | h\bhi\bis\bst\bto\bor\bry\by Enable command history, as described above under | |
5445 | H\bHI\bIS\bST\bTO\bOR\bRY\bY. This option is on by default in inter- | |
5446 | active shells. | |
5447 | i\big\bgn\bno\bor\bre\bee\beo\bof\bf | |
3eb0018e CR |
5448 | The effect is as if the shell command ``IG- |
5449 | NOREEOF=10'' had been executed (see S\bSh\bhe\bel\bll\bl V\bVa\bar\bri\bi-\b- | |
712f80b0 | 5450 | a\bab\bbl\ble\bes\bs above). |
17345e5a JA |
5451 | k\bke\bey\byw\bwo\bor\brd\bd Same as -\b-k\bk. |
5452 | m\bmo\bon\bni\bit\bto\bor\br Same as -\b-m\bm. | |
5453 | n\bno\boc\bcl\blo\bob\bbb\bbe\ber\br | |
5454 | Same as -\b-C\bC. | |
5455 | n\bno\boe\bex\bxe\bec\bc Same as -\b-n\bn. | |
5456 | n\bno\bog\bgl\blo\bob\bb Same as -\b-f\bf. | |
5457 | n\bno\bol\blo\bog\bg Currently ignored. | |
5458 | n\bno\bot\bti\bif\bfy\by Same as -\b-b\bb. | |
5459 | n\bno\bou\bun\bns\bse\bet\bt Same as -\b-u\bu. | |
5460 | o\bon\bne\bec\bcm\bmd\bd Same as -\b-t\bt. | |
5461 | p\bph\bhy\bys\bsi\bic\bca\bal\bl | |
5462 | Same as -\b-P\bP. | |
5463 | p\bpi\bip\bpe\bef\bfa\bai\bil\bl | |
3eb0018e CR |
5464 | If set, the return value of a pipeline is the |
5465 | value of the last (rightmost) command to exit | |
5466 | with a non-zero status, or zero if all commands | |
5467 | in the pipeline exit successfully. This option | |
17345e5a | 5468 | is disabled by default. |
3eb0018e CR |
5469 | p\bpo\bos\bsi\bix\bx Change the behavior of b\bba\bas\bsh\bh where the default |
5470 | operation differs from the POSIX standard to | |
5471 | match the standard (_\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be). See S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
ac50fbac CR |
5472 | below for a reference to a document that details |
5473 | how posix mode affects bash's behavior. | |
17345e5a JA |
5474 | p\bpr\bri\biv\bvi\bil\ble\beg\bge\bed\bd |
5475 | Same as -\b-p\bp. | |
5476 | v\bve\ber\brb\bbo\bos\bse\be Same as -\b-v\bv. | |
3eb0018e | 5477 | v\bvi\bi Use a vi-style command line editing interface. |
17345e5a JA |
5478 | This also affects the editing interface used for |
5479 | r\bre\bea\bad\bd -\b-e\be. | |
5480 | x\bxt\btr\bra\bac\bce\be Same as -\b-x\bx. | |
5481 | If -\b-o\bo is supplied with no _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be, the values of the | |
3eb0018e CR |
5482 | current options are printed. If +\b+o\bo is supplied with no |
5483 | _\bo_\bp_\bt_\bi_\bo_\bn_\b-_\bn_\ba_\bm_\be, a series of s\bse\bet\bt commands to recreate the | |
5484 | current option settings is displayed on the standard | |
17345e5a | 5485 | output. |
3eb0018e CR |
5486 | -\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 |
5487 | $\b$B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV files are not processed, shell functions are | |
5488 | not inherited from the environment, and the S\bSH\bHE\bEL\bLL\bLO\bOP\bPT\bTS\bS, | |
5489 | 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- | |
5490 | pear in the environment, are ignored. If the shell is | |
5491 | started with the effective user (group) id not equal to | |
5492 | the real user (group) id, and the -\b-p\bp option is not sup- | |
0001803f | 5493 | plied, these actions are taken and the effective user id |
3eb0018e CR |
5494 | is set to the real user id. If the -\b-p\bp option is sup- |
5495 | plied at startup, the effective user id is not reset. | |
5496 | Turning this option off causes the effective user and | |
0001803f | 5497 | group ids to be set to the real user and group ids. |
17345e5a | 5498 | -\b-t\bt Exit after reading and executing one command. |
0001803f | 5499 | -\b-u\bu Treat unset variables and parameters other than the spe- |
3eb0018e CR |
5500 | cial parameters "@" and "*" as an error when performing |
5501 | parameter expansion. If expansion is attempted on an | |
5502 | unset variable or parameter, the shell prints an error | |
5503 | message, and, if not interactive, exits with a non-zero | |
0001803f | 5504 | status. |
17345e5a | 5505 | -\b-v\bv Print shell input lines as they are read. |
3eb0018e | 5506 | -\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 | 5507 | command, s\bse\bel\ble\bec\bct\bt command, or arithmetic f\bfo\bor\br command, dis- |
3eb0018e | 5508 | play the expanded value of P\bPS\bS4\b4, followed by the command |
17345e5a | 5509 | and its expanded arguments or associated word list. |
3eb0018e | 5510 | -\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 | 5511 | above). This is on by default. |
3eb0018e CR |
5512 | -\b-C\bC If set, b\bba\bas\bsh\bh does not overwrite an existing file with |
5513 | the >\b>, >\b>&\b&, and <\b<>\b> redirection operators. This may be | |
17345e5a JA |
5514 | overridden when creating output files by using the redi- |
5515 | rection operator >\b>|\b| instead of >\b>. | |
5516 | -\b-E\bE If set, any trap on E\bER\bRR\bR is inherited by shell functions, | |
3eb0018e CR |
5517 | command substitutions, and commands executed in a sub- |
5518 | shell environment. The E\bER\bRR\bR trap is normally not inher- | |
17345e5a JA |
5519 | ited in such cases. |
5520 | -\b-H\bH Enable !\b! style history substitution. This option is on | |
5521 | by default when the shell is interactive. | |
3eb0018e CR |
5522 | -\b-P\bP If set, the shell does not resolve symbolic links when |
5523 | executing commands such as c\bcd\bd that change the current | |
17345e5a JA |
5524 | working directory. It uses the physical directory |
5525 | structure instead. By default, b\bba\bas\bsh\bh follows the logical | |
3eb0018e | 5526 | chain of directories when performing commands which |
17345e5a | 5527 | change the current directory. |
3eb0018e | 5528 | -\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 |
712f80b0 | 5529 | shell functions, command substitutions, and commands ex- |
3eb0018e | 5530 | ecuted in a subshell environment. The D\bDE\bEB\bBU\bUG\bG and R\bRE\bET\bTU\bUR\bRN\bN |
712f80b0 | 5531 | traps are normally not inherited in such cases. |
3eb0018e | 5532 | -\b--\b- If no arguments follow this option, then the positional |
17345e5a | 5533 | parameters are unset. Otherwise, the positional parame- |
3eb0018e | 5534 | ters are set to the _\ba_\br_\bgs, even if some of them begin |
17345e5a | 5535 | with a -\b-. |
3eb0018e | 5536 | -\b- Signal the end of options, cause all remaining _\ba_\br_\bgs to |
17345e5a JA |
5537 | be assigned to the positional parameters. The -\b-x\bx and -\b-v\bv |
5538 | options are turned off. If there are no _\ba_\br_\bgs, the posi- | |
5539 | tional parameters remain unchanged. | |
5540 | ||
3eb0018e CR |
5541 | The options are off by default unless otherwise noted. Using + |
5542 | rather than - causes these options to be turned off. The op- | |
712f80b0 | 5543 | tions can also be specified as arguments to an invocation of the |
3eb0018e CR |
5544 | shell. The current set of options may be found in $\b$-\b-. The re- |
5545 | turn status is always true unless an invalid option is encoun- | |
17345e5a JA |
5546 | tered. |
5547 | ||
5548 | s\bsh\bhi\bif\bft\bt [_\bn] | |
3eb0018e CR |
5549 | The positional parameters from _\bn+1 ... are renamed to $\b$1\b1 .\b..\b..\b..\b. |
5550 | Parameters represented by the numbers $\b$#\b# down to $\b$#\b#-_\bn+1 are un- | |
5551 | set. _\bn must be a non-negative number less than or equal to $\b$#\b#. | |
5552 | If _\bn is 0, no parameters are changed. If _\bn is not given, it is | |
712f80b0 | 5553 | assumed to be 1. If _\bn is greater than $\b$#\b#, the positional param- |
3eb0018e | 5554 | eters are not changed. The return status is greater than zero |
712f80b0 | 5555 | if _\bn is greater than $\b$#\b# or less than zero; otherwise 0. |
17345e5a JA |
5556 | |
5557 | s\bsh\bho\bop\bpt\bt [-\b-p\bpq\bqs\bsu\bu] [-\b-o\bo] [_\bo_\bp_\bt_\bn_\ba_\bm_\be ...] | |
3eb0018e CR |
5558 | Toggle the values of settings controlling optional shell behav- |
5559 | ior. The settings can be either those listed below, or, if the | |
ac50fbac CR |
5560 | -\b-o\bo option is used, those available with the -\b-o\bo option to the s\bse\bet\bt |
5561 | builtin command. With no options, or with the -\b-p\bp option, a list | |
3eb0018e | 5562 | of all settable options is displayed, with an indication of |
d233b485 | 5563 | whether or not each is set; if _\bo_\bp_\bt_\bn_\ba_\bm_\be_\bs are supplied, the output |
3eb0018e CR |
5564 | is restricted to those options. The -\b-p\bp option causes output to |
5565 | be displayed in a form that may be reused as input. Other op- | |
712f80b0 | 5566 | tions have the following meanings: |
17345e5a JA |
5567 | -\b-s\bs Enable (set) each _\bo_\bp_\bt_\bn_\ba_\bm_\be. |
5568 | -\b-u\bu Disable (unset) each _\bo_\bp_\bt_\bn_\ba_\bm_\be. | |
3eb0018e | 5569 | -\b-q\bq Suppresses normal output (quiet mode); the return status |
17345e5a | 5570 | indicates whether the _\bo_\bp_\bt_\bn_\ba_\bm_\be is set or unset. If multi- |
3eb0018e CR |
5571 | ple _\bo_\bp_\bt_\bn_\ba_\bm_\be arguments are given with -\b-q\bq, the return sta- |
5572 | tus is zero if all _\bo_\bp_\bt_\bn_\ba_\bm_\be_\bs are enabled; non-zero other- | |
17345e5a | 5573 | wise. |
3eb0018e | 5574 | -\b-o\bo Restricts the values of _\bo_\bp_\bt_\bn_\ba_\bm_\be to be those defined for |
17345e5a JA |
5575 | the -\b-o\bo option to the s\bse\bet\bt builtin. |
5576 | ||
3eb0018e CR |
5577 | 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 |
5578 | shows only those options which are set or unset, respectively. | |
5579 | Unless otherwise noted, the s\bsh\bho\bop\bpt\bt options are disabled (unset) | |
ac50fbac | 5580 | by default. |
17345e5a | 5581 | |
3eb0018e CR |
5582 | The return status when listing options is zero if all _\bo_\bp_\bt_\bn_\ba_\bm_\be_\bs |
5583 | are enabled, non-zero otherwise. When setting or unsetting op- | |
5584 | tions, the return status is zero unless an _\bo_\bp_\bt_\bn_\ba_\bm_\be is not a | |
17345e5a JA |
5585 | valid shell option. |
5586 | ||
5587 | The list of s\bsh\bho\bop\bpt\bt options is: | |
5588 | ||
d233b485 | 5589 | a\bas\bss\bso\boc\bc_\b_e\bex\bxp\bpa\ban\bnd\bd_\b_o\bon\bnc\bce\be |
3eb0018e CR |
5590 | If set, the shell suppresses multiple evaluation of as- |
5591 | sociative array subscripts during arithmetic expression | |
5592 | evaluation, while executing builtins that can perform | |
5593 | variable assignments, and while executing builtins that | |
712f80b0 | 5594 | perform array dereferencing. |
3eb0018e CR |
5595 | a\bau\but\bto\boc\bcd\bd If set, a command name that is the name of a directory |
5596 | is executed as if it were the argument to the c\bcd\bd com- | |
17345e5a JA |
5597 | mand. This option is only used by interactive shells. |
5598 | c\bcd\bda\bab\bbl\ble\be_\b_v\bva\bar\brs\bs | |
3eb0018e CR |
5599 | If set, an argument to the c\bcd\bd builtin command that is |
5600 | not a directory is assumed to be the name of a variable | |
17345e5a JA |
5601 | whose value is the directory to change to. |
5602 | c\bcd\bds\bsp\bpe\bel\bll\bl If set, minor errors in the spelling of a directory com- | |
3eb0018e | 5603 | ponent in a c\bcd\bd command will be corrected. The errors |
17345e5a | 5604 | checked for are transposed characters, a missing charac- |
3eb0018e CR |
5605 | ter, and one character too many. If a correction is |
5606 | found, the corrected filename is printed, and the com- | |
5607 | mand proceeds. This option is only used by interactive | |
17345e5a JA |
5608 | shells. |
5609 | c\bch\bhe\bec\bck\bkh\bha\bas\bsh\bh | |
5610 | If set, b\bba\bas\bsh\bh checks that a command found in the hash ta- | |
3eb0018e CR |
5611 | ble exists before trying to execute it. If a hashed |
5612 | command no longer exists, a normal path search is per- | |
17345e5a JA |
5613 | formed. |
5614 | c\bch\bhe\bec\bck\bkj\bjo\bob\bbs\bs | |
5615 | If set, b\bba\bas\bsh\bh lists the status of any stopped and running | |
3eb0018e | 5616 | jobs before exiting an interactive shell. If any jobs |
17345e5a | 5617 | are running, this causes the exit to be deferred until a |
3eb0018e | 5618 | second exit is attempted without an intervening command |
712f80b0 CR |
5619 | (see J\bJO\bOB\bB C\bCO\bON\bNT\bTR\bRO\bOL\bL above). The shell always postpones ex- |
5620 | iting if any jobs are stopped. | |
17345e5a | 5621 | c\bch\bhe\bec\bck\bkw\bwi\bin\bns\bsi\biz\bze\be |
3eb0018e CR |
5622 | If set, b\bba\bas\bsh\bh checks the window size after each external |
5623 | (non-builtin) command and, if necessary, updates the | |
5624 | values of L\bLI\bIN\bNE\bES\bS and C\bCO\bOL\bLU\bUM\bMN\bNS\bS. This option is enabled by | |
d233b485 | 5625 | default. |
3eb0018e CR |
5626 | c\bcm\bmd\bdh\bhi\bis\bst\bt If set, b\bba\bas\bsh\bh attempts to save all lines of a multiple- |
5627 | line command in the same history entry. This allows | |
5628 | easy re-editing of multi-line commands. This option is | |
5629 | enabled by default, but only has an effect if command | |
d233b485 | 5630 | history is enabled, as described above under H\bHI\bIS\bST\bTO\bOR\bRY\bY. |
17345e5a | 5631 | c\bco\bom\bmp\bpa\bat\bt3\b31\b1 |
0001803f | 5632 | c\bco\bom\bmp\bpa\bat\bt3\b32\b2 |
0001803f | 5633 | c\bco\bom\bmp\bpa\bat\bt4\b40\b0 |
495aee44 | 5634 | c\bco\bom\bmp\bpa\bat\bt4\b41\b1 |
ac50fbac | 5635 | c\bco\bom\bmp\bpa\bat\bt4\b42\b2 |
a0c0a00f | 5636 | c\bco\bom\bmp\bpa\bat\bt4\b43\b3 |
d233b485 | 5637 | c\bco\bom\bmp\bpa\bat\bt4\b44\b4 |
3eb0018e | 5638 | These control aspects of the shell's compatibility mode |
712f80b0 CR |
5639 | (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). |
5640 | ||
ac50fbac | 5641 | c\bco\bom\bmp\bpl\ble\bet\bte\be_\b_f\bfu\bul\bll\blq\bqu\buo\bot\bte\be |
3eb0018e CR |
5642 | If set, b\bba\bas\bsh\bh quotes all shell metacharacters in file- |
5643 | names and directory names when performing completion. | |
ac50fbac | 5644 | If not set, b\bba\bas\bsh\bh removes metacharacters such as the dol- |
3eb0018e CR |
5645 | lar sign from the set of characters that will be quoted |
5646 | in completed filenames when these metacharacters appear | |
5647 | in shell variable references in words to be completed. | |
5648 | This means that dollar signs in variable names that ex- | |
5649 | pand to directories will not be quoted; however, any | |
5650 | dollar signs appearing in filenames will not be quoted, | |
5651 | either. This is active only when bash is using back- | |
5652 | slashes to quote completed filenames. This variable is | |
5653 | set by default, which is the default bash behavior in | |
ac50fbac | 5654 | versions through 4.2. |
712f80b0 | 5655 | |
ac50fbac | 5656 | d\bdi\bir\bre\bex\bxp\bpa\ban\bnd\bd |
3eb0018e CR |
5657 | If set, b\bba\bas\bsh\bh replaces directory names with the results |
5658 | of word expansion when performing filename completion. | |
5659 | This changes the contents of the readline editing buf- | |
5660 | fer. If not set, b\bba\bas\bsh\bh attempts to preserve what the | |
ac50fbac | 5661 | user typed. |
712f80b0 | 5662 | |
17345e5a | 5663 | d\bdi\bir\brs\bsp\bpe\bel\bll\bl |
3eb0018e CR |
5664 | If set, b\bba\bas\bsh\bh attempts spelling correction on directory |
5665 | names during word completion if the directory name ini- | |
17345e5a | 5666 | tially supplied does not exist. |
712f80b0 | 5667 | |
3eb0018e CR |
5668 | d\bdo\bot\btg\bgl\blo\bob\bb If set, b\bba\bas\bsh\bh includes filenames beginning with a `.' in |
5669 | the results of pathname expansion. The filenames `\b``\b`.\b.'\b''\b' | |
5670 | and `\b``\b`.\b..\b.'\b''\b' must always be matched explicitly, even if | |
d233b485 | 5671 | d\bdo\bot\btg\bgl\blo\bob\bb is set. |
712f80b0 | 5672 | |
17345e5a JA |
5673 | e\bex\bxe\bec\bcf\bfa\bai\bil\bl |
5674 | If set, a non-interactive shell will not exit if it can- | |
3eb0018e CR |
5675 | not execute the file specified as an argument to the |
5676 | e\bex\bxe\bec\bc builtin command. An interactive shell does not | |
17345e5a | 5677 | exit if e\bex\bxe\bec\bc fails. |
712f80b0 | 5678 | |
17345e5a | 5679 | e\bex\bxp\bpa\ban\bnd\bd_\b_a\bal\bli\bia\bas\bse\bes\bs |
3eb0018e | 5680 | If set, aliases are expanded as described above under |
17345e5a JA |
5681 | A\bAL\bLI\bIA\bAS\bSE\bES\bS. This option is enabled by default for interac- |
5682 | tive shells. | |
712f80b0 | 5683 | |
17345e5a | 5684 | e\bex\bxt\btd\bde\beb\bbu\bug\bg |
3eb0018e | 5685 | If set at shell invocation, or in a shell startup file, |
712f80b0 | 5686 | arrange to execute the debugger profile before the shell |
3eb0018e CR |
5687 | starts, identical to the -\b--\b-d\bde\beb\bbu\bug\bgg\bge\ber\br option. If set af- |
5688 | ter invocation, behavior intended for use by debuggers | |
712f80b0 CR |
5689 | is enabled: |
5690 | ||
17345e5a JA |
5691 | 1\b1.\b. The -\b-F\bF option to the d\bde\bec\bcl\bla\bar\bre\be builtin displays the |
5692 | source file name and line number corresponding to | |
5693 | each function name supplied as an argument. | |
712f80b0 | 5694 | |
3eb0018e CR |
5695 | 2\b2.\b. If the command run by the D\bDE\bEB\bBU\bUG\bG trap returns a |
5696 | non-zero value, the next command is skipped and | |
17345e5a | 5697 | not executed. |
712f80b0 | 5698 | |
3eb0018e CR |
5699 | 3\b3.\b. If the command run by the D\bDE\bEB\bBU\bUG\bG trap returns a |
5700 | value of 2, and the shell is executing in a sub- | |
5701 | routine (a shell function or a shell script exe- | |
5702 | cuted by the .\b. or s\bso\bou\bur\brc\bce\be builtins), the shell | |
a0c0a00f | 5703 | simulates a call to r\bre\bet\btu\bur\brn\bn. |
712f80b0 | 5704 | |
3eb0018e | 5705 | 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 |
17345e5a | 5706 | in their descriptions above. |
712f80b0 | 5707 | |
3eb0018e | 5708 | 5\b5.\b. Function tracing is enabled: command substitu- |
17345e5a JA |
5709 | tion, shell functions, and subshells invoked with |
5710 | (\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. | |
712f80b0 | 5711 | |
3eb0018e CR |
5712 | 6\b6.\b. Error tracing is enabled: command substitution, |
5713 | shell functions, and subshells invoked with (\b( | |
495aee44 | 5714 | _\bc_\bo_\bm_\bm_\ba_\bn_\bd )\b) inherit the E\bER\bRR\bR trap. |
712f80b0 | 5715 | |
17345e5a JA |
5716 | e\bex\bxt\btg\bgl\blo\bob\bb If set, the extended pattern matching features described |
5717 | above under P\bPa\bat\bth\bhn\bna\bam\bme\be E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn are enabled. | |
712f80b0 | 5718 | |
17345e5a | 5719 | e\bex\bxt\btq\bqu\buo\bot\bte\be |
3eb0018e CR |
5720 | If set, $\b$'_\bs_\bt_\br_\bi_\bn_\bg' and $\b$"_\bs_\bt_\br_\bi_\bn_\bg" quoting is performed |
5721 | within $\b${\b{_\bp_\ba_\br_\ba_\bm_\be_\bt_\be_\br}\b} expansions enclosed in double | |
17345e5a | 5722 | quotes. This option is enabled by default. |
712f80b0 | 5723 | |
17345e5a | 5724 | f\bfa\bai\bil\blg\bgl\blo\bob\bb |
3eb0018e | 5725 | If set, patterns which fail to match filenames during |
17345e5a | 5726 | pathname expansion result in an expansion error. |
712f80b0 | 5727 | |
17345e5a | 5728 | f\bfo\bor\brc\bce\be_\b_f\bfi\big\bgn\bno\bor\bre\be |
3eb0018e CR |
5729 | If set, the suffixes specified by the F\bFI\bIG\bGN\bNO\bOR\bRE\bE shell |
5730 | variable cause words to be ignored when performing word | |
17345e5a | 5731 | completion even if the ignored words are the only possi- |
3eb0018e CR |
5732 | ble completions. See S\bSH\bHE\bEL\bLL\bL V\bVA\bAR\bRI\bIA\bAB\bBL\bLE\bES\bS above for a de- |
5733 | scription of F\bFI\bIG\bGN\bNO\bOR\bRE\bE. This option is enabled by de- | |
712f80b0 CR |
5734 | fault. |
5735 | ||
ac50fbac | 5736 | g\bgl\blo\bob\bba\bas\bsc\bci\bii\bir\bra\ban\bng\bge\bes\bs |
3eb0018e CR |
5737 | If set, range expressions used in pattern matching |
5738 | bracket expressions (see P\bPa\bat\btt\bte\ber\brn\bn M\bMa\bat\btc\bch\bhi\bin\bng\bg above) behave | |
5739 | as if in the traditional C locale when performing com- | |
5740 | parisons. That is, the current locale's collating se- | |
5741 | quence is not taken into account, so b\bb will not collate | |
5742 | between A\bA and B\bB, and upper-case and lower-case ASCII | |
712f80b0 CR |
5743 | characters will collate together. |
5744 | ||
17345e5a | 5745 | g\bgl\blo\bob\bbs\bst\bta\bar\br |
0001803f | 5746 | If set, the pattern *\b**\b* used in a pathname expansion con- |
3eb0018e CR |
5747 | text will match all files and zero or more directories |
5748 | and subdirectories. If the pattern is followed by a /\b/, | |
ac50fbac | 5749 | only directories and subdirectories match. |
712f80b0 | 5750 | |
17345e5a JA |
5751 | g\bgn\bnu\bu_\b_e\ber\brr\brf\bfm\bmt\bt |
5752 | If set, shell error messages are written in the standard | |
5753 | GNU error message format. | |
712f80b0 | 5754 | |
17345e5a | 5755 | h\bhi\bis\bst\bta\bap\bpp\bpe\ben\bnd\bd |
3eb0018e | 5756 | If set, the history list is appended to the file named |
712f80b0 CR |
5757 | by the value of the H\bHI\bIS\bST\bTF\bFI\bIL\bLE\bE variable when the shell ex- |
5758 | its, rather than overwriting the file. | |
5759 | ||
17345e5a | 5760 | h\bhi\bis\bst\btr\bre\bee\bed\bdi\bit\bt |
3eb0018e | 5761 | If set, and r\bre\bea\bad\bdl\bli\bin\bne\be is being used, a user is given the |
17345e5a | 5762 | opportunity to re-edit a failed history substitution. |
712f80b0 | 5763 | |
17345e5a | 5764 | h\bhi\bis\bst\btv\bve\ber\bri\bif\bfy\by |
3eb0018e CR |
5765 | If set, and r\bre\bea\bad\bdl\bli\bin\bne\be is being used, the results of his- |
5766 | tory substitution are not immediately passed to the | |
5767 | shell parser. Instead, the resulting line is loaded | |
17345e5a JA |
5768 | into the r\bre\bea\bad\bdl\bli\bin\bne\be editing buffer, allowing further modi- |
5769 | fication. | |
712f80b0 | 5770 | |
17345e5a JA |
5771 | h\bho\bos\bst\btc\bco\bom\bmp\bpl\ble\bet\bte\be |
5772 | If set, and r\bre\bea\bad\bdl\bli\bin\bne\be is being used, b\bba\bas\bsh\bh will attempt to | |
3eb0018e CR |
5773 | perform hostname completion when a word containing a @\b@ |
5774 | 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 | 5775 | above). This is enabled by default. |
712f80b0 | 5776 | |
17345e5a JA |
5777 | h\bhu\bup\bpo\bon\bne\bex\bxi\bit\bt |
5778 | If set, b\bba\bas\bsh\bh will send S\bSI\bIG\bGH\bHU\bUP\bP to all jobs when an inter- | |
5779 | active login shell exits. | |
712f80b0 | 5780 | |
a0c0a00f | 5781 | i\bin\bnh\bhe\ber\bri\bit\bt_\b_e\ber\brr\bre\bex\bxi\bit\bt |
3eb0018e CR |
5782 | If set, command substitution inherits the value of the |
5783 | e\ber\brr\bre\bex\bxi\bit\bt option, instead of unsetting it in the subshell | |
5784 | environment. This option is enabled when _\bp_\bo_\bs_\bi_\bx _\bm_\bo_\bd_\be is | |
a0c0a00f | 5785 | enabled. |
712f80b0 | 5786 | |
17345e5a JA |
5787 | i\bin\bnt\bte\ber\bra\bac\bct\bti\biv\bve\be_\b_c\bco\bom\bmm\bme\ben\bnt\bts\bs |
5788 | If set, allow a word beginning with #\b# to cause that word | |
3eb0018e CR |
5789 | and all remaining characters on that line to be ignored |
5790 | in an interactive shell (see C\bCO\bOM\bMM\bME\bEN\bNT\bTS\bS above). This op- | |
712f80b0 CR |
5791 | tion is enabled by default. |
5792 | ||
495aee44 | 5793 | l\bla\bas\bst\btp\bpi\bip\bpe\be |
3eb0018e | 5794 | If set, and job control is not active, the shell runs |
495aee44 CR |
5795 | the last command of a pipeline not executed in the back- |
5796 | ground in the current shell environment. | |
712f80b0 | 5797 | |
3eb0018e | 5798 | 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 |
5799 | commands are saved to the history with embedded newlines |
5800 | rather than using semicolon separators where possible. | |
712f80b0 | 5801 | |
d233b485 CR |
5802 | l\blo\boc\bca\bal\blv\bva\bar\br_\b_i\bin\bnh\bhe\ber\bri\bit\bt |
5803 | If set, local variables inherit the value and attributes | |
5804 | of a variable of the same name that exists at a previous | |
712f80b0 CR |
5805 | scope before any new value is assigned. The nameref at- |
5806 | tribute is not inherited. | |
5807 | ||
d233b485 | 5808 | l\blo\boc\bca\bal\blv\bva\bar\br_\b_u\bun\bns\bse\bet\bt |
3eb0018e CR |
5809 | If set, calling u\bun\bns\bse\bet\bt on local variables in previous |
5810 | function scopes marks them so subsequent lookups find | |
5811 | them unset until that function returns. This is identi- | |
5812 | cal to the behavior of unsetting local variables at the | |
d233b485 | 5813 | current function scope. |
712f80b0 | 5814 | |
17345e5a | 5815 | l\blo\bog\bgi\bin\bn_\b_s\bsh\bhe\bel\bll\bl |
3eb0018e CR |
5816 | The shell sets this option if it is started as a login |
5817 | shell (see I\bIN\bNV\bVO\bOC\bCA\bAT\bTI\bIO\bON\bN above). The value may not be | |
17345e5a | 5818 | changed. |
712f80b0 | 5819 | |
17345e5a | 5820 | m\bma\bai\bil\blw\bwa\bar\brn\bn |
3eb0018e CR |
5821 | If set, and a file that b\bba\bas\bsh\bh is checking for mail has |
5822 | been accessed since the last time it was checked, the | |
5823 | message ``The mail in _\bm_\ba_\bi_\bl_\bf_\bi_\bl_\be has been read'' is dis- | |
17345e5a | 5824 | played. |
712f80b0 | 5825 | |
17345e5a | 5826 | 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 |
3eb0018e CR |
5827 | If set, and r\bre\bea\bad\bdl\bli\bin\bne\be is being used, b\bba\bas\bsh\bh will not at- |
5828 | tempt to search the P\bPA\bAT\bTH\bH for possible completions when | |
17345e5a | 5829 | completion is attempted on an empty line. |
712f80b0 | 5830 | |
17345e5a | 5831 | n\bno\boc\bca\bas\bse\beg\bgl\blo\bob\bb |
3eb0018e | 5832 | If set, b\bba\bas\bsh\bh matches filenames in a case-insensitive |
17345e5a JA |
5833 | fashion when performing pathname expansion (see P\bPa\bat\bth\bhn\bna\bam\bme\be |
5834 | E\bEx\bxp\bpa\ban\bns\bsi\bio\bon\bn above). | |
712f80b0 | 5835 | |
17345e5a | 5836 | n\bno\boc\bca\bas\bse\bem\bma\bat\btc\bch\bh |
3eb0018e | 5837 | If set, b\bba\bas\bsh\bh matches patterns in a case-insensitive |
17345e5a | 5838 | fashion when performing matching while executing c\bca\bas\bse\be or |
a0c0a00f | 5839 | [\b[[\b[ conditional commands, when performing pattern substi- |
3eb0018e | 5840 | tution word expansions, or when filtering possible com- |
a0c0a00f | 5841 | pletions as part of programmable completion. |
712f80b0 | 5842 | |
17345e5a | 5843 | n\bnu\bul\bll\blg\bgl\blo\bob\bb |
3eb0018e CR |
5844 | If set, b\bba\bas\bsh\bh allows patterns which match no files (see |
5845 | 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 | 5846 | rather than themselves. |
712f80b0 | 5847 | |
17345e5a JA |
5848 | p\bpr\bro\bog\bgc\bco\bom\bmp\bp |
5849 | If set, the programmable completion facilities (see P\bPr\bro\bo-\b- | |
5850 | 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 | |
5851 | enabled by default. | |
712f80b0 | 5852 | |
d233b485 | 5853 | p\bpr\bro\bog\bgc\bco\bom\bmp\bp_\b_a\bal\bli\bia\bas\bs |
3eb0018e CR |
5854 | If set, and programmable completion is enabled, b\bba\bas\bsh\bh |
5855 | treats a command name that doesn't have any completions | |
5856 | as a possible alias and attempts alias expansion. If it | |
5857 | has an alias, b\bba\bas\bsh\bh attempts programmable completion us- | |
712f80b0 CR |
5858 | ing the command word resulting from the expanded alias. |
5859 | ||
17345e5a JA |
5860 | p\bpr\bro\bom\bmp\bpt\btv\bva\bar\brs\bs |
5861 | If set, prompt strings undergo parameter expansion, com- | |
3eb0018e CR |
5862 | mand substitution, arithmetic expansion, and quote re- |
5863 | moval after being expanded as described in P\bPR\bRO\bOM\bMP\bPT\bTI\bIN\bNG\bG | |
17345e5a | 5864 | above. This option is enabled by default. |
712f80b0 | 5865 | |
17345e5a | 5866 | r\bre\bes\bst\btr\bri\bic\bct\bte\bed\bd_\b_s\bsh\bhe\bel\bll\bl |
3eb0018e CR |
5867 | The shell sets this option if it is started in re- |
5868 | stricted mode (see R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTE\bED\bD S\bSH\bHE\bEL\bLL\bL below). The value | |
5869 | may not be changed. This is not reset when the startup | |
5870 | files are executed, allowing the startup files to dis- | |
17345e5a | 5871 | cover whether or not a shell is restricted. |
712f80b0 | 5872 | |
17345e5a | 5873 | s\bsh\bhi\bif\bft\bt_\b_v\bve\ber\brb\bbo\bos\bse\be |
3eb0018e | 5874 | If set, the s\bsh\bhi\bif\bft\bt builtin prints an error message when |
17345e5a JA |
5875 | the shift count exceeds the number of positional parame- |
5876 | ters. | |
712f80b0 | 5877 | |
17345e5a JA |
5878 | s\bso\bou\bur\brc\bce\bep\bpa\bat\bth\bh |
5879 | If set, the s\bso\bou\bur\brc\bce\be (.\b.) builtin uses the value of P\bPA\bAT\bTH\bH to | |
3eb0018e | 5880 | find the directory containing the file supplied as an |
17345e5a | 5881 | argument. This option is enabled by default. |
712f80b0 | 5882 | |
17345e5a | 5883 | x\bxp\bpg\bg_\b_e\bec\bch\bho\bo |
3eb0018e | 5884 | If set, the e\bec\bch\bho\bo builtin expands backslash-escape se- |
712f80b0 | 5885 | quences by default. |
ac50fbac | 5886 | |
17345e5a | 5887 | s\bsu\bus\bsp\bpe\ben\bnd\bd [-\b-f\bf] |
3eb0018e | 5888 | Suspend the execution of this shell until it receives a S\bSI\bIG\bGC\bCO\bON\bNT\bT |
17345e5a JA |
5889 | signal. A login shell cannot be suspended; the -\b-f\bf option can be |
5890 | used to override this and force the suspension. The return sta- | |
3eb0018e | 5891 | tus is 0 unless the shell is a login shell and -\b-f\bf is not sup- |
17345e5a | 5892 | plied, or if job control is not enabled. |
ac50fbac | 5893 | |
17345e5a JA |
5894 | t\bte\bes\bst\bt _\be_\bx_\bp_\br |
5895 | [\b[ _\be_\bx_\bp_\br ]\b] | |
ac50fbac CR |
5896 | Return a status of 0 (true) or 1 (false) depending on the evalu- |
5897 | ation of the conditional expression _\be_\bx_\bp_\br. Each operator and op- | |
3eb0018e CR |
5898 | erand must be a separate argument. Expressions are composed of |
5899 | 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. | |
5900 | t\bte\bes\bst\bt does not accept any options, nor does it accept and ignore | |
ac50fbac CR |
5901 | an argument of -\b--\b- as signifying the end of options. |
5902 | ||
3eb0018e CR |
5903 | Expressions may be combined using the following operators, |
5904 | listed in decreasing order of precedence. The evaluation de- | |
5905 | pends on the number of arguments; see below. Operator prece- | |
495aee44 | 5906 | dence is used when there are five or more arguments. |
17345e5a JA |
5907 | !\b! _\be_\bx_\bp_\br True if _\be_\bx_\bp_\br is false. |
5908 | (\b( _\be_\bx_\bp_\br )\b) | |
3eb0018e | 5909 | Returns the value of _\be_\bx_\bp_\br. This may be used to override |
17345e5a JA |
5910 | the normal precedence of operators. |
5911 | _\be_\bx_\bp_\br_\b1 -a\ba _\be_\bx_\bp_\br_\b2 | |
5912 | True if both _\be_\bx_\bp_\br_\b1 and _\be_\bx_\bp_\br_\b2 are true. | |
5913 | _\be_\bx_\bp_\br_\b1 -o\bo _\be_\bx_\bp_\br_\b2 | |
5914 | True if either _\be_\bx_\bp_\br_\b1 or _\be_\bx_\bp_\br_\b2 is true. | |
5915 | ||
5916 | t\bte\bes\bst\bt and [\b[ evaluate conditional expressions using a set of rules | |
5917 | based on the number of arguments. | |
5918 | ||
5919 | 0 arguments | |
5920 | The expression is false. | |
5921 | 1 argument | |
5922 | The expression is true if and only if the argument is not | |
5923 | null. | |
5924 | 2 arguments | |
5925 | If the first argument is !\b!, the expression is true if and | |
3eb0018e CR |
5926 | only if the second argument is null. If the first argu- |
5927 | ment is one of the unary conditional operators listed | |
5928 | 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 |
5929 | true if the unary test is true. If the first argument is |
5930 | not a valid unary conditional operator, the expression is | |
5931 | false. | |
5932 | 3 arguments | |
495aee44 | 5933 | The following conditions are applied in the order listed. |
3eb0018e | 5934 | If the second argument is one of the binary conditional |
17345e5a JA |
5935 | 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 |
5936 | result of the expression is the result of the binary test | |
3eb0018e CR |
5937 | using the first and third arguments as operands. The -\b-a\ba |
5938 | and -\b-o\bo operators are considered binary operators when | |
5939 | there are three arguments. If the first argument is !\b!, | |
5940 | the value is the negation of the two-argument test using | |
17345e5a JA |
5941 | the second and third arguments. If the first argument is |
5942 | exactly (\b( and the third argument is exactly )\b), the result | |
3eb0018e | 5943 | is the one-argument test of the second argument. Other- |
17345e5a JA |
5944 | wise, the expression is false. |
5945 | 4 arguments | |
5946 | If the first argument is !\b!, the result is the negation of | |
3eb0018e | 5947 | the three-argument expression composed of the remaining |
17345e5a | 5948 | arguments. Otherwise, the expression is parsed and eval- |
3eb0018e | 5949 | uated according to precedence using the rules listed |
17345e5a JA |
5950 | above. |
5951 | 5 or more arguments | |
3eb0018e | 5952 | The expression is parsed and evaluated according to |
17345e5a JA |
5953 | precedence using the rules listed above. |
5954 | ||
3eb0018e | 5955 | When used with t\bte\bes\bst\bt or [\b[, the <\b< and >\b> operators sort lexico- |
495aee44 CR |
5956 | graphically using ASCII ordering. |
5957 | ||
3eb0018e | 5958 | t\bti\bim\bme\bes\bs Print the accumulated user and system times for the shell and |
17345e5a JA |
5959 | for processes run from the shell. The return status is 0. |
5960 | ||
5961 | t\btr\bra\bap\bp [-\b-l\blp\bp] [[_\ba_\br_\bg] _\bs_\bi_\bg_\bs_\bp_\be_\bc ...] | |
3eb0018e | 5962 | The command _\ba_\br_\bg is to be read and executed when the shell re- |
712f80b0 | 5963 | ceives signal(s) _\bs_\bi_\bg_\bs_\bp_\be_\bc. If _\ba_\br_\bg is absent (and there is a sin- |
3eb0018e CR |
5964 | gle _\bs_\bi_\bg_\bs_\bp_\be_\bc) or -\b-, each specified signal is reset to its origi- |
5965 | nal disposition (the value it had upon entrance to the shell). | |
5966 | If _\ba_\br_\bg is the null string the signal specified by each _\bs_\bi_\bg_\bs_\bp_\be_\bc | |
5967 | is ignored by the shell and by the commands it invokes. If _\ba_\br_\bg | |
5968 | is not present and -\b-p\bp has been supplied, then the trap commands | |
712f80b0 | 5969 | associated with each _\bs_\bi_\bg_\bs_\bp_\be_\bc are displayed. If no arguments are |
3eb0018e CR |
5970 | supplied or if only -\b-p\bp is given, t\btr\bra\bap\bp prints the list of com- |
5971 | mands associated with each signal. The -\b-l\bl option causes the | |
5972 | shell to print a list of signal names and their corresponding | |
5973 | numbers. Each _\bs_\bi_\bg_\bs_\bp_\be_\bc is either a signal name defined in <_\bs_\bi_\bg_\b- | |
5974 | _\bn_\ba_\bl_\b._\bh>, or a signal number. Signal names are case insensitive | |
712f80b0 | 5975 | and the S\bSI\bIG\bG prefix is optional. |
495aee44 | 5976 | |
3eb0018e CR |
5977 | 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 |
5978 | 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- | |
5979 | 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, | |
5980 | _\bs_\be_\bl_\be_\bc_\bt command, every arithmetic _\bf_\bo_\br command, and before the | |
5981 | first command executes in a shell function (see S\bSH\bHE\bEL\bLL\bL G\bGR\bRA\bAM\bMM\bMA\bAR\bR | |
5982 | above). Refer to the description of the e\bex\bxt\btd\bde\beb\bbu\bug\bg option to the | |
0001803f CR |
5983 | s\bsh\bho\bop\bpt\bt builtin for details of its effect on the D\bDE\bEB\bBU\bUG\bG trap. If a |
5984 | _\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 | |
5985 | function or a script executed with the .\b. or s\bso\bou\bur\brc\bce\be builtins fin- | |
5986 | ishes executing. | |
5987 | ||
3eb0018e | 5988 | 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 |
5989 | pipeline (which may consist of a single simple command), a list, |
5990 | or a compound command returns a non-zero exit status, subject to | |
3eb0018e | 5991 | the following conditions. The E\bER\bRR\bR trap is not executed if the |
ac50fbac | 5992 | failed command is part of the command list immediately following |
3eb0018e | 5993 | 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 | 5994 | part of a command executed in a &\b&&\b& or |\b||\b| list except the command |
3eb0018e CR |
5995 | following the final &\b&&\b& or |\b||\b|, any command in a pipeline but the |
5996 | last, or if the command's return value is being inverted using | |
712f80b0 CR |
5997 | !\b!. These are the same conditions obeyed by the e\ber\brr\bre\bex\bxi\bit\bt (-\b-e\be) op- |
5998 | tion. | |
0001803f | 5999 | |
712f80b0 | 6000 | Signals ignored upon entry to the shell cannot be trapped or re- |
3eb0018e | 6001 | set. Trapped signals that are not being ignored are reset to |
0001803f | 6002 | their original values in a subshell or subshell environment when |
3eb0018e | 6003 | one is created. The return status is false if any _\bs_\bi_\bg_\bs_\bp_\be_\bc is |
0001803f | 6004 | invalid; otherwise t\btr\bra\bap\bp returns true. |
17345e5a JA |
6005 | |
6006 | t\bty\byp\bpe\be [-\b-a\baf\bft\btp\bpP\bP] _\bn_\ba_\bm_\be [_\bn_\ba_\bm_\be ...] | |
3eb0018e | 6007 | With no options, indicate how each _\bn_\ba_\bm_\be would be interpreted if |
17345e5a | 6008 | used as a command name. If the -\b-t\bt option is used, t\bty\byp\bpe\be prints a |
3eb0018e CR |
6009 | 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 |
6010 | _\bf_\bi_\bl_\be if _\bn_\ba_\bm_\be is an alias, shell reserved word, function, | |
6011 | builtin, or disk file, respectively. If the _\bn_\ba_\bm_\be is not found, | |
6012 | then nothing is printed, and an exit status of false is re- | |
6013 | turned. If the -\b-p\bp option is used, t\bty\byp\bpe\be either returns the name | |
6014 | of the disk file that would be executed if _\bn_\ba_\bm_\be were specified | |
6015 | as a command name, or nothing if ``type -t name'' would not re- | |
6016 | 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 | 6017 | even if ``type -t name'' would not return _\bf_\bi_\bl_\be. If a command is |
ac50fbac | 6018 | hashed, -\b-p\bp and -\b-P\bP print the hashed value, which is not necessar- |
3eb0018e CR |
6019 | ily the file that appears first in P\bPA\bAT\bTH\bH. If the -\b-a\ba option is |
6020 | used, t\bty\byp\bpe\be prints all of the places that contain an executable | |
ac50fbac CR |
6021 | named _\bn_\ba_\bm_\be. This includes aliases and functions, if and only if |
6022 | the -\b-p\bp option is not also used. The table of hashed commands is | |
3eb0018e | 6023 | not consulted when using -\b-a\ba. The -\b-f\bf option suppresses shell |
ac50fbac CR |
6024 | function lookup, as with the c\bco\bom\bmm\bma\ban\bnd\bd builtin. t\bty\byp\bpe\be returns true |
6025 | if all of the arguments are found, false if any are not found. | |
17345e5a | 6026 | |
712f80b0 | 6027 | u\bul\bli\bim\bmi\bit\bt [-\b-H\bHS\bSa\bab\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]] |
3eb0018e CR |
6028 | Provides control over the resources available to the shell and |
6029 | to processes started by it, on systems that allow such control. | |
17345e5a | 6030 | The -\b-H\bH and -\b-S\bS options specify that the hard or soft limit is set |
3eb0018e CR |
6031 | for the given resource. A hard limit cannot be increased by a |
6032 | non-root user once it is set; a soft limit may be increased up | |
6033 | to the value of the hard limit. If neither -\b-H\bH nor -\b-S\bS is speci- | |
17345e5a JA |
6034 | fied, both the soft and hard limits are set. The value of _\bl_\bi_\bm_\bi_\bt |
6035 | can be a number in the unit specified for the resource or one of | |
6036 | 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 | |
3eb0018e CR |
6037 | current hard limit, the current soft limit, and no limit, re- |
6038 | spectively. If _\bl_\bi_\bm_\bi_\bt is omitted, the current value of the soft | |
712f80b0 | 6039 | limit of the resource is printed, unless the -\b-H\bH option is given. |
3eb0018e CR |
6040 | When more than one resource is specified, the limit name and |
6041 | unit are printed before the value. Other options are inter- | |
17345e5a JA |
6042 | preted as follows: |
6043 | -\b-a\ba All current limits are reported | |
6044 | -\b-b\bb The maximum socket buffer size | |
6045 | -\b-c\bc The maximum size of core files created | |
6046 | -\b-d\bd The maximum size of a process's data segment | |
6047 | -\b-e\be The maximum scheduling priority ("nice") | |
3eb0018e | 6048 | -\b-f\bf The maximum size of files written by the shell and its |
17345e5a JA |
6049 | children |
6050 | -\b-i\bi The maximum number of pending signals | |
a0c0a00f | 6051 | -\b-k\bk The maximum number of kqueues that may be allocated |
17345e5a | 6052 | -\b-l\bl The maximum size that may be locked into memory |
3eb0018e | 6053 | -\b-m\bm The maximum resident set size (many systems do not honor |
0001803f | 6054 | this limit) |
17345e5a JA |
6055 | -\b-n\bn The maximum number of open file descriptors (most systems |
6056 | do not allow this value to be set) | |
6057 | -\b-p\bp The pipe size in 512-byte blocks (this may not be set) | |
6058 | -\b-q\bq The maximum number of bytes in POSIX message queues | |
6059 | -\b-r\br The maximum real-time scheduling priority | |
6060 | -\b-s\bs The maximum stack size | |
6061 | -\b-t\bt The maximum amount of cpu time in seconds | |
3eb0018e | 6062 | -\b-u\bu The maximum number of processes available to a single |
17345e5a | 6063 | user |
3eb0018e | 6064 | -\b-v\bv The maximum amount of virtual memory available to the |
495aee44 | 6065 | shell and, on some systems, to its children |
17345e5a | 6066 | -\b-x\bx The maximum number of file locks |
a0c0a00f | 6067 | -\b-P\bP The maximum number of pseudoterminals |
3eb0018e | 6068 | -\b-R\bR The maximum time a real-time process can run before |
712f80b0 | 6069 | blocking, in microseconds |
17345e5a JA |
6070 | -\b-T\bT The maximum number of threads |
6071 | ||
3eb0018e CR |
6072 | If _\bl_\bi_\bm_\bi_\bt is given, and the -\b-a\ba option is not used, _\bl_\bi_\bm_\bi_\bt is the |
6073 | new value of the specified resource. If no option is given, | |
6074 | then -\b-f\bf is assumed. Values are in 1024-byte increments, except | |
6075 | for -\b-t\bt, which is in seconds; -\b-R\bR, which is in microseconds; -\b-p\bp, | |
6076 | which is in units of 512-byte blocks; -\b-P\bP, -\b-T\bT, -\b-b\bb, -\b-k\bk, -\b-n\bn, and | |
6077 | -\b-u\bu, which are unscaled values; and, when in posix mode, -\b-c\bc and | |
6078 | -\b-f\bf, which are in 512-byte increments. The return status is 0 | |
6079 | unless an invalid option or argument is supplied, or an error | |
712f80b0 | 6080 | occurs while setting a new limit. |
17345e5a JA |
6081 | |
6082 | u\bum\bma\bas\bsk\bk [-\b-p\bp] [-\b-S\bS] [_\bm_\bo_\bd_\be] | |
6083 | The user file-creation mask is set to _\bm_\bo_\bd_\be. If _\bm_\bo_\bd_\be begins with | |
3eb0018e CR |
6084 | a digit, it is interpreted as an octal number; otherwise it is |
6085 | interpreted as a symbolic mode mask similar to that accepted by | |
6086 | _\bc_\bh_\bm_\bo_\bd(1). If _\bm_\bo_\bd_\be is omitted, the current value of the mask is | |
6087 | printed. The -\b-S\bS option causes the mask to be printed in sym- | |
6088 | bolic form; the default output is an octal number. If the -\b-p\bp | |
17345e5a JA |
6089 | option is supplied, and _\bm_\bo_\bd_\be is omitted, the output is in a form |
6090 | that may be reused as input. The return status is 0 if the mode | |
3eb0018e | 6091 | was successfully changed or if no _\bm_\bo_\bd_\be argument was supplied, |
17345e5a JA |
6092 | and false otherwise. |
6093 | ||
6094 | u\bun\bna\bal\bli\bia\bas\bs [-a\ba] [_\bn_\ba_\bm_\be ...] | |
3eb0018e CR |
6095 | Remove each _\bn_\ba_\bm_\be from the list of defined aliases. If -\b-a\ba is |
6096 | supplied, all alias definitions are removed. The return value | |
17345e5a JA |
6097 | is true unless a supplied _\bn_\ba_\bm_\be is not a defined alias. |
6098 | ||
ac50fbac | 6099 | u\bun\bns\bse\bet\bt [-f\bfv\bv] [-n\bn] [_\bn_\ba_\bm_\be ...] |
3eb0018e | 6100 | For each _\bn_\ba_\bm_\be, remove the corresponding variable or function. |
ac50fbac | 6101 | If the -\b-v\bv option is given, each _\bn_\ba_\bm_\be refers to a shell variable, |
3eb0018e CR |
6102 | and that variable is removed. Read-only variables may not be |
6103 | unset. If -\b-f\bf is specified, each _\bn_\ba_\bm_\be refers to a shell func- | |
6104 | tion, and the function definition is removed. If the -\b-n\bn option | |
6105 | is supplied, and _\bn_\ba_\bm_\be is a variable with the _\bn_\ba_\bm_\be_\br_\be_\bf attribute, | |
6106 | _\bn_\ba_\bm_\be will be unset rather than the variable it references. -\b-n\bn | |
6107 | has no effect if the -\b-f\bf option is supplied. If no options are | |
6108 | supplied, each _\bn_\ba_\bm_\be refers to a variable; if there is no vari- | |
6109 | able by that name, a function with that name, if any, is unset. | |
6110 | Each unset variable or function is removed from the environment | |
6111 | passed to subsequent commands. If any of B\bBA\bAS\bSH\bH_\b_A\bAL\bLI\bIA\bAS\bSE\bES\bS, | |
712f80b0 | 6112 | 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, |
3eb0018e CR |
6113 | 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- |
6114 | 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 |
6115 | unset, they lose their special properties, even if they are sub- |
6116 | sequently reset. The exit status is true unless a _\bn_\ba_\bm_\be is read- | |
6117 | only. | |
6118 | ||
712f80b0 | 6119 | 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 | 6120 | Wait for each specified child process and return its termination |
3eb0018e CR |
6121 | status. Each _\bi_\bd may be a process ID or a job specification; if |
6122 | a job spec is given, all processes in that job's pipeline are | |
6123 | waited for. If _\bi_\bd is not given, w\bwa\bai\bit\bt waits for all running | |
6124 | background jobs and the last-executed process substitution, if | |
712f80b0 | 6125 | its process id is the same as $\b$!\b!, and the return status is zero. |
3eb0018e | 6126 | If the -\b-n\bn option is supplied, w\bwa\bai\bit\bt waits for a single job from |
712f80b0 | 6127 | the list of _\bi_\bds or, if no _\bi_\bds are supplied, any job, to complete |
3eb0018e | 6128 | and returns its exit status. If none of the supplied arguments |
712f80b0 | 6129 | is a child of the shell, or if no arguments are supplied and the |
3eb0018e CR |
6130 | shell has no unwaited-for children, the exit status is 127. If |
6131 | the -\b-p\bp option is supplied, the process or job identifier of the | |
6132 | job for which the exit status is returned is assigned to the | |
6133 | variable _\bv_\ba_\br_\bn_\ba_\bm_\be named by the option argument. The variable | |
6134 | will be unset initially, before any assignment. This is useful | |
6135 | only when the -\b-n\bn option is supplied. Supplying the -\b-f\bf option, | |
6136 | when job control is enabled, forces w\bwa\bai\bit\bt to wait for _\bi_\bd to ter- | |
712f80b0 | 6137 | minate before returning its status, instead of returning when it |
3eb0018e CR |
6138 | changes status. If _\bi_\bd specifies a non-existent process or job, |
6139 | the return status is 127. Otherwise, the return status is the | |
712f80b0 CR |
6140 | exit status of the last process or job waited for. |
6141 | ||
6142 | 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 | |
6143 | Bash-4.0 introduced the concept of a `shell compatibility level', spec- | |
6144 | ified 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, c\bco\bom\bm-\b- | |
3eb0018e | 6145 | p\bpa\bat\bt4\b40\b0, c\bco\bom\bmp\bpa\bat\bt4\b41\b1, and so on). There is only one current compatibility |
712f80b0 | 6146 | level -- each option is mutually exclusive. The compatibility level is |
3eb0018e CR |
6147 | intended to allow users to select behavior from previous versions that |
6148 | is incompatible with newer versions while they migrate scripts to use | |
6149 | current features and behavior. It's intended to be a temporary solu- | |
712f80b0 CR |
6150 | tion. |
6151 | ||
3eb0018e CR |
6152 | This section does not mention behavior that is standard for a particu- |
6153 | lar version (e.g., setting c\bco\bom\bmp\bpa\bat\bt3\b32\b2 means that quoting the rhs of the | |
6154 | regexp matching operator quotes special regexp characters in the word, | |
712f80b0 CR |
6155 | which is default behavior in bash-3.2 and above). |
6156 | ||
3eb0018e CR |
6157 | If a user enables, say, c\bco\bom\bmp\bpa\bat\bt3\b32\b2, it may affect the behavior of other |
6158 | compatibility levels up to and including the current compatibility | |
6159 | level. The idea is that each compatibility level controls behavior | |
6160 | that changed in that version of b\bba\bas\bsh\bh, but that behavior may have been | |
6161 | present in earlier versions. For instance, the change to use locale- | |
6162 | based comparisons with the [\b[[\b[ command came in bash-4.1, and earlier | |
712f80b0 | 6163 | versions used ASCII-based comparisons, so enabling c\bco\bom\bmp\bpa\bat\bt3\b32\b2 will enable |
3eb0018e CR |
6164 | ASCII-based comparisons as well. That granularity may not be suffi- |
6165 | cient for all uses, and as a result users should employ compatibility | |
6166 | levels carefully. Read the documentation for a particular feature to | |
712f80b0 CR |
6167 | find out the current behavior. |
6168 | ||
3eb0018e | 6169 | Bash-4.3 introduced a new shell variable: B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT. The value as- |
712f80b0 | 6170 | signed to this variable (a decimal version number like 4.2, or an inte- |
3eb0018e | 6171 | ger corresponding to the c\bco\bom\bmp\bpa\bat\bt_\bN_\bN option, like 42) determines the com- |
712f80b0 CR |
6172 | patibility level. |
6173 | ||
3eb0018e CR |
6174 | Starting with bash-4.4, Bash has begun deprecating older compatibility |
6175 | levels. Eventually, the options will be removed in favor of B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bM-\b- | |
712f80b0 CR |
6176 | P\bPA\bAT\bT. |
6177 | ||
3eb0018e CR |
6178 | Bash-5.0 is the final version for which there will be an individual |
6179 | shopt option for the previous version. Users should use B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT on | |
712f80b0 CR |
6180 | bash-5.0 and later versions. |
6181 | ||
3eb0018e | 6182 | The following table describes the behavior changes controlled by each |
712f80b0 CR |
6183 | compatibility level setting. The c\bco\bom\bmp\bpa\bat\bt_\bN_\bN tag is used as shorthand for |
6184 | setting the compatibility level to _\bN_\bN using one of the following mecha- | |
3eb0018e CR |
6185 | nisms. For versions prior to bash-5.0, the compatibility level may be |
6186 | set using the corresponding c\bco\bom\bmp\bpa\bat\bt_\bN_\bN shopt option. For bash-4.3 and | |
6187 | later versions, the B\bBA\bAS\bSH\bH_\b_C\bCO\bOM\bMP\bPA\bAT\bT variable is preferred, and it is re- | |
712f80b0 CR |
6188 | quired for bash-5.1 and later versions. |
6189 | ||
6190 | c\bco\bom\bmp\bpa\bat\bt3\b31\b1 | |
6191 | +\bo quoting the rhs of the [\b[[\b[ command's regexp matching oper- | |
6192 | ator (=~) has no special effect | |
6193 | ||
6194 | c\bco\bom\bmp\bpa\bat\bt3\b32\b2 | |
3eb0018e CR |
6195 | +\bo interrupting a command list such as "a ; b ; c" causes |
6196 | the execution of the next command in the list (in | |
6197 | bash-4.0 and later versions, the shell acts as if it re- | |
6198 | ceived the interrupt, so interrupting one command in a | |
712f80b0 CR |
6199 | list aborts the execution of the entire list) |
6200 | ||
6201 | c\bco\bom\bmp\bpa\bat\bt4\b40\b0 | |
3eb0018e | 6202 | +\bo the <\b< and >\b> operators to the [\b[[\b[ command do not consider |
712f80b0 CR |
6203 | the current locale when comparing strings; they use ASCII |
6204 | ordering. Bash versions prior to bash-4.1 use ASCII col- | |
3eb0018e | 6205 | lation and _\bs_\bt_\br_\bc_\bm_\bp(3); bash-4.1 and later use the current |
712f80b0 CR |
6206 | locale's collation sequence and _\bs_\bt_\br_\bc_\bo_\bl_\bl(3). |
6207 | ||
6208 | c\bco\bom\bmp\bpa\bat\bt4\b41\b1 | |
3eb0018e | 6209 | +\bo in _\bp_\bo_\bs_\bi_\bx mode, t\bti\bim\bme\be may be followed by options and still |
712f80b0 CR |
6210 | be recognized as a reserved word (this is POSIX interpre- |
6211 | tation 267) | |
6212 | +\bo in _\bp_\bo_\bs_\bi_\bx mode, the parser requires that an even number of | |
3eb0018e CR |
6213 | single quotes occur in the _\bw_\bo_\br_\bd portion of a double- |
6214 | quoted parameter expansion and treats them specially, so | |
6215 | that characters within the single quotes are considered | |
712f80b0 CR |
6216 | quoted (this is POSIX interpretation 221) |
6217 | ||
6218 | c\bco\bom\bmp\bpa\bat\bt4\b42\b2 | |
6219 | +\bo the replacement string in double-quoted pattern substitu- | |
3eb0018e | 6220 | tion does not undergo quote removal, as it does in ver- |
712f80b0 | 6221 | sions after bash-4.2 |
3eb0018e CR |
6222 | +\bo in posix mode, single quotes are considered special when |
6223 | expanding the _\bw_\bo_\br_\bd portion of a double-quoted parameter | |
6224 | expansion and can be used to quote a closing brace or | |
6225 | other special character (this is part of POSIX interpre- | |
6226 | tation 221); in later versions, single quotes are not | |
712f80b0 CR |
6227 | special within double-quoted word expansions |
6228 | ||
6229 | c\bco\bom\bmp\bpa\bat\bt4\b43\b3 | |
3eb0018e CR |
6230 | +\bo the shell does not print a warning message if an attempt |
6231 | is made to use a quoted compound assignment as an argu- | |
6232 | ment to declare (declare -a foo='(1 2)'). Later versions | |
712f80b0 | 6233 | warn that this usage is deprecated |
3eb0018e CR |
6234 | +\bo word expansion errors are considered non-fatal errors |
6235 | that cause the current command to fail, even in posix | |
6236 | mode (the default behavior is to make them fatal errors | |
712f80b0 | 6237 | that cause the shell to exit) |
3eb0018e | 6238 | +\bo when executing a shell function, the loop state |
712f80b0 CR |
6239 | (while/until/etc.) is not reset, so b\bbr\bre\bea\bak\bk or c\bco\bon\bnt\bti\bin\bnu\bue\be in |
6240 | that function will break or continue loops in the calling | |
3eb0018e | 6241 | context. Bash-4.4 and later reset the loop state to pre- |
712f80b0 CR |
6242 | vent this |
6243 | ||
6244 | c\bco\bom\bmp\bpa\bat\bt4\b44\b4 | |
3eb0018e CR |
6245 | +\bo the shell sets up the values used by B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGV\bV and |
6246 | B\bBA\bAS\bSH\bH_\b_A\bAR\bRG\bGC\bC so they can expand to the shell's positional | |
712f80b0 | 6247 | parameters even if extended debugging mode is not enabled |
3eb0018e CR |
6248 | +\bo a subshell inherits loops from its parent context, so |
6249 | b\bbr\bre\bea\bak\bk or c\bco\bon\bnt\bti\bin\bnu\bue\be will cause the subshell to exit. | |
6250 | Bash-5.0 and later reset the loop state to prevent the | |
712f80b0 | 6251 | exit |
3eb0018e | 6252 | +\bo variable assignments preceding builtins like e\bex\bxp\bpo\bor\brt\bt and |
712f80b0 CR |
6253 | r\bre\bea\bad\bdo\bon\bnl\bly\by that set attributes continue to affect variables |
6254 | with the same name in the calling environment even if the | |
6255 | shell is not in posix mode | |
6256 | ||
6257 | c\bco\bom\bmp\bpa\bat\bt5\b50\b0 | |
3eb0018e | 6258 | +\bo Bash-5.1 changed the way $\b$R\bRA\bAN\bND\bDO\bOM\bM is generated to intro- |
712f80b0 | 6259 | duce slightly more randomness. If the shell compatibility |
3eb0018e CR |
6260 | level is set to 50 or lower, it reverts to the method |
6261 | from bash-5.0 and previous versions, so seeding the ran- | |
6262 | dom number generator by assigning a value to R\bRA\bAN\bND\bDO\bOM\bM will | |
712f80b0 | 6263 | produce the same sequence as in bash-5.0 |
3eb0018e CR |
6264 | +\bo If the command hash table is empty, bash versions prior |
6265 | to bash-5.1 printed an informational message to that ef- | |
6266 | fect, even when producing output that can be reused as | |
6267 | input. Bash-5.1 suppresses that message when the -\b-l\bl op- | |
6268 | tion is supplied. | |
17345e5a JA |
6269 | |
6270 | R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTE\bED\bD S\bSH\bHE\bEL\bLL\bL | |
6271 | 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 | |
3eb0018e CR |
6272 | invocation, the shell becomes restricted. A restricted shell is used |
6273 | to set up an environment more controlled than the standard shell. It | |
6274 | behaves identically to b\bba\bas\bsh\bh with the exception that the following are | |
17345e5a JA |
6275 | disallowed or not performed: |
6276 | ||
6277 | +\bo changing directories with c\bcd\bd | |
6278 | ||
3eb0018e | 6279 | +\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, |
712f80b0 | 6280 | or B\bBA\bAS\bSH\bH_\b_E\bEN\bNV\bV |
17345e5a JA |
6281 | |
6282 | +\bo specifying command names containing /\b/ | |
6283 | ||
3eb0018e | 6284 | +\bo specifying a filename containing a /\b/ as an argument to the .\b. |
17345e5a JA |
6285 | builtin command |
6286 | ||
3eb0018e | 6287 | +\bo specifying a filename containing a slash as an argument to the |
712f80b0 CR |
6288 | h\bhi\bis\bst\bto\bor\bry\by builtin command |
6289 | ||
3eb0018e | 6290 | +\bo specifying a filename containing a slash as an argument to the |
17345e5a JA |
6291 | -\b-p\bp option to the h\bha\bas\bsh\bh builtin command |
6292 | ||
3eb0018e | 6293 | +\bo importing function definitions from the shell environment at |
17345e5a JA |
6294 | startup |
6295 | ||
3eb0018e | 6296 | +\bo parsing the value of S\bSH\bHE\bEL\bLL\bLO\bOP\bPT\bTS\bS from the shell environment at |
17345e5a JA |
6297 | startup |
6298 | ||
6299 | +\bo redirecting output using the >, >|, <>, >&, &>, and >> redirect- | |
6300 | ion operators | |
6301 | ||
6302 | +\bo using the e\bex\bxe\bec\bc builtin command to replace the shell with another | |
6303 | command | |
6304 | ||
3eb0018e | 6305 | +\bo adding or deleting builtin commands with the -\b-f\bf and -\b-d\bd options |
17345e5a JA |
6306 | to the e\ben\bna\bab\bbl\ble\be builtin command |
6307 | ||
3eb0018e | 6308 | +\bo using the e\ben\bna\bab\bbl\ble\be builtin command to enable disabled shell |
17345e5a JA |
6309 | builtins |
6310 | ||
6311 | +\bo specifying the -\b-p\bp option to the c\bco\bom\bmm\bma\ban\bnd\bd builtin command | |
6312 | ||
6313 | +\bo turning off restricted mode with s\bse\bet\bt +\b+r\br or s\bse\bet\bt +\b+o\bo r\bre\bes\bst\btr\bri\bic\bct\bte\bed\bd. | |
6314 | ||
6315 | These restrictions are enforced after any startup files are read. | |
6316 | ||
6317 | When a command that is found to be a shell script is executed (see C\bCO\bOM\bM-\b- | |
3eb0018e | 6318 | 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 |
6319 | spawned to execute the script. |
6320 | ||
6321 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
6322 | _\bB_\ba_\bs_\bh _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl, Brian Fox and Chet Ramey | |
6323 | _\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 | |
6324 | _\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 | |
3eb0018e | 6325 | _\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 |
6326 | _\bt_\bi_\be_\bs, IEEE -- |
6327 | http://pubs.opengroup.org/onlinepubs/9699919799/ | |
6328 | http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode | |
17345e5a JA |
6329 | _\bs_\bh(1), _\bk_\bs_\bh(1), _\bc_\bs_\bh(1) |
6330 | _\be_\bm_\ba_\bc_\bs(1), _\bv_\bi(1) | |
6331 | _\br_\be_\ba_\bd_\bl_\bi_\bn_\be(3) | |
6332 | ||
6333 | F\bFI\bIL\bLE\bES\bS | |
6334 | _\b/_\bb_\bi_\bn_\b/_\bb_\ba_\bs_\bh | |
6335 | The b\bba\bas\bsh\bh executable | |
6336 | _\b/_\be_\bt_\bc_\b/_\bp_\br_\bo_\bf_\bi_\bl_\be | |
6337 | The systemwide initialization file, executed for login shells | |
6338 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bp_\br_\bo_\bf_\bi_\bl_\be | |
6339 | The personal initialization file, executed for login shells | |
6340 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\br_\bc | |
6341 | The individual per-interactive-shell startup file | |
6342 | _\b~_\b/_\b._\bb_\ba_\bs_\bh_\b__\bl_\bo_\bg_\bo_\bu_\bt | |
3eb0018e | 6343 | The individual login shell cleanup file, executed when a login |
17345e5a JA |
6344 | shell exits |
6345 | _\b~_\b/_\b._\bi_\bn_\bp_\bu_\bt_\br_\bc | |
6346 | Individual _\br_\be_\ba_\bd_\bl_\bi_\bn_\be initialization file | |
6347 | ||
6348 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS | |
6349 | Brian Fox, Free Software Foundation | |
6350 | bfox@gnu.org | |
6351 | ||
6352 | Chet Ramey, Case Western Reserve University | |
0001803f | 6353 | chet.ramey@case.edu |
17345e5a JA |
6354 | |
6355 | B\bBU\bUG\bG R\bRE\bEP\bPO\bOR\bRT\bTS\bS | |
6356 | If you find a bug in b\bba\bas\bsh\bh,\b, you should report it. But first, you should | |
3eb0018e CR |
6357 | make sure that it really is a bug, and that it appears in the latest |
6358 | version of b\bba\bas\bsh\bh. The latest version is always available from | |
495aee44 CR |
6359 | _\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/. |
6360 | ||
3eb0018e CR |
6361 | Once you have determined that a bug actually exists, use the _\bb_\ba_\bs_\bh_\bb_\bu_\bg |
6362 | command to submit a bug report. If you have a fix, you are encouraged | |
6363 | to mail that as well! Suggestions and `philosophical' bug reports may | |
6364 | 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 |
6365 | g\bgn\bnu\bu.\b.b\bba\bas\bsh\bh.\b.b\bbu\bug\bg. |
6366 | ||
6367 | ALL bug reports should include: | |
6368 | ||
6369 | The version number of b\bba\bas\bsh\bh | |
6370 | The hardware and operating system | |
6371 | The compiler used to compile | |
6372 | A description of the bug behaviour | |
6373 | A short script or `recipe' which exercises the bug | |
6374 | ||
3eb0018e | 6375 | _\bb_\ba_\bs_\bh_\bb_\bu_\bg inserts the first three items automatically into the template |
17345e5a JA |
6376 | it provides for filing a bug report. |
6377 | ||
6378 | Comments and bug reports concerning this manual page should be directed | |
ac50fbac | 6379 | to _\bc_\bh_\be_\bt_\b._\br_\ba_\bm_\be_\by_\b@_\bc_\ba_\bs_\be_\b._\be_\bd_\bu. |
17345e5a JA |
6380 | |
6381 | B\bBU\bUG\bGS\bS | |
6382 | It's too big and too slow. | |
6383 | ||
6384 | There are some subtle differences between b\bba\bas\bsh\bh and traditional versions | |
6385 | of s\bsh\bh, mostly because of the P\bPO\bOS\bSI\bIX\bX specification. | |
6386 | ||
6387 | Aliases are confusing in some uses. | |
6388 | ||
6389 | Shell builtin commands and functions are not stoppable/restartable. | |
6390 | ||
6391 | Compound commands and command sequences of the form `a ; b ; c' are not | |
3eb0018e CR |
6392 | handled gracefully when process suspension is attempted. When a |
6393 | process is stopped, the shell immediately executes the next command in | |
6394 | the sequence. It suffices to place the sequence of commands between | |
6395 | parentheses to force it into a subshell, which may be stopped as a | |
17345e5a JA |
6396 | unit. |
6397 | ||
6398 | Array variables may not (yet) be exported. | |
6399 | ||
6400 | There may be only one active coprocess at a time. | |
6401 | ||
6402 | ||
6403 | ||
3eb0018e | 6404 | GNU Bash 5.1 2020 August 25 BASH(1) |