| @@ -1,2122 +1,2122 @@ | | | @@ -1,2122 +1,2122 @@ |
1 | .\" $NetBSD: sh.1,v 1.178 2018/03/13 19:43:52 uwe Exp $ | | 1 | .\" $NetBSD: sh.1,v 1.179 2018/03/13 20:08:11 uwe Exp $ |
2 | .\" Copyright (c) 1991, 1993 | | 2 | .\" Copyright (c) 1991, 1993 |
3 | .\" The Regents of the University of California. All rights reserved. | | 3 | .\" The Regents of the University of California. All rights reserved. |
4 | .\" | | 4 | .\" |
5 | .\" This code is derived from software contributed to Berkeley by | | 5 | .\" This code is derived from software contributed to Berkeley by |
6 | .\" Kenneth Almquist. | | 6 | .\" Kenneth Almquist. |
7 | .\" | | 7 | .\" |
8 | .\" Redistribution and use in source and binary forms, with or without | | 8 | .\" Redistribution and use in source and binary forms, with or without |
9 | .\" modification, are permitted provided that the following conditions | | 9 | .\" modification, are permitted provided that the following conditions |
10 | .\" are met: | | 10 | .\" are met: |
11 | .\" 1. Redistributions of source code must retain the above copyright | | 11 | .\" 1. Redistributions of source code must retain the above copyright |
12 | .\" notice, this list of conditions and the following disclaimer. | | 12 | .\" notice, this list of conditions and the following disclaimer. |
13 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 13 | .\" 2. Redistributions in binary form must reproduce the above copyright |
14 | .\" notice, this list of conditions and the following disclaimer in the | | 14 | .\" notice, this list of conditions and the following disclaimer in the |
15 | .\" documentation and/or other materials provided with the distribution. | | 15 | .\" documentation and/or other materials provided with the distribution. |
16 | .\" 3. Neither the name of the University nor the names of its contributors | | 16 | .\" 3. Neither the name of the University nor the names of its contributors |
17 | .\" may be used to endorse or promote products derived from this software | | 17 | .\" may be used to endorse or promote products derived from this software |
18 | .\" without specific prior written permission. | | 18 | .\" without specific prior written permission. |
19 | .\" | | 19 | .\" |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | | 20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | | 21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | | 23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | | 27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | | 28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | | 29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
30 | .\" SUCH DAMAGE. | | 30 | .\" SUCH DAMAGE. |
31 | .\" | | 31 | .\" |
32 | .\" @(#)sh.1 8.6 (Berkeley) 5/4/95 | | 32 | .\" @(#)sh.1 8.6 (Berkeley) 5/4/95 |
33 | .\" | | 33 | .\" |
34 | .Dd October 24, 2017 | | 34 | .Dd October 24, 2017 |
35 | .Dt SH 1 | | 35 | .Dt SH 1 |
36 | .\" everything except c o and s (keep them ordered) | | 36 | .\" everything except c o and s (keep them ordered) |
37 | .ds flags abCEeFfhIiLmnpquVvXx | | 37 | .ds flags abCEeFfhIiLmnpquVvXx |
38 | .Os | | 38 | .Os |
39 | .Sh NAME | | 39 | .Sh NAME |
40 | .Nm sh | | 40 | .Nm sh |
41 | .Nd command interpreter (shell) | | 41 | .Nd command interpreter (shell) |
42 | .Sh SYNOPSIS | | 42 | .Sh SYNOPSIS |
43 | .Nm | | 43 | .Nm |
44 | .Bk -words | | 44 | .Bk -words |
45 | .Op Fl \*[flags] | | 45 | .Op Fl \*[flags] |
46 | .Op Cm +\*[flags] | | 46 | .Op Cm +\*[flags] |
47 | .Ek | | 47 | .Ek |
48 | .Bk -words | | 48 | .Bk -words |
49 | .Op Fl o Ar option_name | | 49 | .Op Fl o Ar option_name |
50 | .Op Cm +o Ar option_name | | 50 | .Op Cm +o Ar option_name |
51 | .Ek | | 51 | .Ek |
52 | .Bk -words | | 52 | .Bk -words |
53 | .Op Ar command_file Oo Ar argument ... Oc | | 53 | .Op Ar command_file Oo Ar argument ... Oc |
54 | .Ek | | 54 | .Ek |
55 | .Nm | | 55 | .Nm |
56 | .Fl c | | 56 | .Fl c |
57 | .Bk -words | | 57 | .Bk -words |
58 | .Op Fl s | | 58 | .Op Fl s |
59 | .Op Fl \*[flags] | | 59 | .Op Fl \*[flags] |
60 | .Op Cm +\*[flags] | | 60 | .Op Cm +\*[flags] |
61 | .Ek | | 61 | .Ek |
62 | .Bk -words | | 62 | .Bk -words |
63 | .Op Fl o Ar option_name | | 63 | .Op Fl o Ar option_name |
64 | .Op Cm +o Ar option_name | | 64 | .Op Cm +o Ar option_name |
65 | .Ek | | 65 | .Ek |
66 | .Bk -words | | 66 | .Bk -words |
67 | .Ar command_string | | 67 | .Ar command_string |
68 | .Op Ar command_name Oo Ar argument ... Oc | | 68 | .Op Ar command_name Oo Ar argument ... Oc |
69 | .Ek | | 69 | .Ek |
70 | .Nm | | 70 | .Nm |
71 | .Fl s | | 71 | .Fl s |
72 | .Bk -words | | 72 | .Bk -words |
73 | .Op Fl \*[flags] | | 73 | .Op Fl \*[flags] |
74 | .Op Cm +\*[flags] | | 74 | .Op Cm +\*[flags] |
75 | .Ek | | 75 | .Ek |
76 | .Bk -words | | 76 | .Bk -words |
77 | .Op Fl o Ar option_name | | 77 | .Op Fl o Ar option_name |
78 | .Op Cm +o Ar option_name | | 78 | .Op Cm +o Ar option_name |
79 | .Ek | | 79 | .Ek |
80 | .Bk -words | | 80 | .Bk -words |
81 | .Op Ar argument ... | | 81 | .Op Ar argument ... |
82 | .Ek | | 82 | .Ek |
83 | .Sh DESCRIPTION | | 83 | .Sh DESCRIPTION |
84 | .Nm | | 84 | .Nm |
85 | is the standard command interpreter for the system. | | 85 | is the standard command interpreter for the system. |
86 | The current version of | | 86 | The current version of |
87 | .Nm | | 87 | .Nm |
88 | is in the process of being changed to conform more closely to the | | 88 | is in the process of being changed to conform more closely to the |
89 | POSIX 1003.2 and 1003.2a specifications for the shell. | | 89 | POSIX 1003.2 and 1003.2a specifications for the shell. |
90 | This version has many | | 90 | This version has many |
91 | features which make it appear similar in some respects to the Korn shell, | | 91 | features which make it appear similar in some respects to the Korn shell, |
92 | but it is not a Korn shell clone (see | | 92 | but it is not a Korn shell clone (see |
93 | .Xr ksh 1 ) . | | 93 | .Xr ksh 1 ) . |
94 | This man page is not intended | | 94 | This man page is not intended |
95 | to be a tutorial or a complete specification of the shell. | | 95 | to be a tutorial or a complete specification of the shell. |
96 | .Ss Overview | | 96 | .Ss Overview |
97 | The shell is a command that reads lines from either a file or the | | 97 | The shell is a command that reads lines from either a file or the |
98 | terminal, interprets them, and generally executes other commands. | | 98 | terminal, interprets them, and generally executes other commands. |
99 | A shell is the program that is running when a user logs into the system. | | 99 | A shell is the program that is running when a user logs into the system. |
100 | (Users can select which shell is executed for them at login with the | | 100 | (Users can select which shell is executed for them at login with the |
101 | .Xr chsh 1 | | 101 | .Xr chsh 1 |
102 | command). | | 102 | command). |
103 | The shell implements a language that has flow control | | 103 | The shell implements a language that has flow control |
104 | constructs, a macro facility that provides a variety of features in | | 104 | constructs, a macro facility that provides a variety of features in |
105 | addition to data storage, along with built in history and line editing | | 105 | addition to data storage, along with built in history and line editing |
106 | capabilities. | | 106 | capabilities. |
107 | It incorporates many features to aid interactive use and | | 107 | It incorporates many features to aid interactive use and |
108 | has the advantage that the interpretative language is common to both | | 108 | has the advantage that the interpretative language is common to both |
109 | interactive and non-interactive use (shell scripts). | | 109 | interactive and non-interactive use (shell scripts). |
110 | That is, commands | | 110 | That is, commands |
111 | can be typed directly to the running shell or can be put into a file and | | 111 | can be typed directly to the running shell or can be put into a file and |
112 | the file can be executed directly by the shell. | | 112 | the file can be executed directly by the shell. |
113 | .Ss Invocation | | 113 | .Ss Invocation |
114 | If no arguments are present and if the standard input, | | 114 | If no arguments are present and if the standard input, |
115 | and standard error output, of the shell | | 115 | and standard error output, of the shell |
116 | are connected to a terminal (or terminals, or if the | | 116 | are connected to a terminal (or terminals, or if the |
117 | .Fl i | | 117 | .Fl i |
118 | flag is set), | | 118 | flag is set), |
119 | and the | | 119 | and the |
120 | .Fl c | | 120 | .Fl c |
121 | option is not present, the shell is considered an interactive shell. | | 121 | option is not present, the shell is considered an interactive shell. |
122 | An interactive shell generally prompts before each command and handles | | 122 | An interactive shell generally prompts before each command and handles |
123 | programming and command errors differently (as described below). | | 123 | programming and command errors differently (as described below). |
124 | When first starting, | | 124 | When first starting, |
125 | the shell inspects argument 0, and if it begins with a dash | | 125 | the shell inspects argument 0, and if it begins with a dash |
126 | .Sq - , | | 126 | .Sq - , |
127 | the shell is also considered | | 127 | the shell is also considered |
128 | a login shell. | | 128 | a login shell. |
129 | This is normally done automatically by the system | | 129 | This is normally done automatically by the system |
130 | when the user first logs in. | | 130 | when the user first logs in. |
131 | A login shell first reads commands | | 131 | A login shell first reads commands |
132 | from the files | | 132 | from the files |
133 | .Pa /etc/profile | | 133 | .Pa /etc/profile |
134 | and | | 134 | and |
135 | .Pa .profile | | 135 | .Pa .profile |
136 | if they exist. | | 136 | if they exist. |
137 | If the environment variable | | 137 | If the environment variable |
138 | .Ev ENV | | 138 | .Ev ENV |
139 | is set on entry to a shell, | | 139 | is set on entry to a shell, |
140 | or is set in the | | 140 | or is set in the |
141 | .Pa .profile | | 141 | .Pa .profile |
142 | of a login shell, | | 142 | of a login shell, |
143 | and either the shell is interactive, or the | | 143 | and either the shell is interactive, or the |
144 | .Cm posix | | 144 | .Cm posix |
145 | option is not set, | | 145 | option is not set, |
146 | the shell next reads | | 146 | the shell next reads |
147 | commands from the file named in | | 147 | commands from the file named in |
148 | .Ev ENV . | | 148 | .Ev ENV . |
149 | Therefore, a user should place commands that are to be executed only at | | 149 | Therefore, a user should place commands that are to be executed only at |
150 | login time in the | | 150 | login time in the |
151 | .Pa .profile | | 151 | .Pa .profile |
152 | file, and commands that are executed for every shell inside the | | 152 | file, and commands that are executed for every shell inside the |
153 | .Ev ENV | | 153 | .Ev ENV |
154 | file. | | 154 | file. |
155 | To set the | | 155 | To set the |
156 | .Ev ENV | | 156 | .Ev ENV |
157 | variable to some file, place the following line in your | | 157 | variable to some file, place the following line in your |
158 | .Pa .profile | | 158 | .Pa .profile |
159 | of your home directory | | 159 | of your home directory |
160 | .Pp | | 160 | .Pp |
161 | .Dl ENV=$HOME/.shinit; export ENV | | 161 | .Dl ENV=$HOME/.shinit; export ENV |
162 | .Pp | | 162 | .Pp |
163 | substituting for | | 163 | substituting for |
164 | .Dq .shinit | | 164 | .Dq .shinit |
165 | any filename you wish. | | 165 | any filename you wish. |
166 | Since the | | 166 | Since the |
167 | .Ev ENV | | 167 | .Ev ENV |
168 | file can be read for every invocation of the shell, including shell scripts | | 168 | file can be read for every invocation of the shell, including shell scripts |
169 | and non-interactive shells, the following paradigm is useful for | | 169 | and non-interactive shells, the following paradigm is useful for |
170 | restricting commands in the | | 170 | restricting commands in the |
171 | .Ev ENV | | 171 | .Ev ENV |
172 | file to interactive invocations. | | 172 | file to interactive invocations. |
173 | Place commands within the | | 173 | Place commands within the |
174 | .Dq Ic case | | 174 | .Dq Ic case |
175 | and | | 175 | and |
176 | .Dq Ic esac | | 176 | .Dq Ic esac |
177 | below (these commands are described later): | | 177 | below (these commands are described later): |
178 | .Pp | | 178 | .Pp |
179 | .Bl -item -compact -offset indent | | 179 | .Bl -item -compact -offset indent |
180 | .It | | 180 | .It |
181 | .Li case $- in *i*) | | 181 | .Li case $- in *i*) |
182 | .Bl -item -compact -offset indent | | 182 | .Bl -item -compact -offset indent |
183 | .It | | 183 | .It |
184 | .Li # commands for interactive use only | | 184 | .Li # commands for interactive use only |
185 | .It | | 185 | .It |
186 | .Li ... | | 186 | .Li ... |
187 | .El | | 187 | .El |
188 | .It | | 188 | .It |
189 | .Li esac | | 189 | .Li esac |
190 | .El | | 190 | .El |
191 | .Pp | | 191 | .Pp |
192 | If command line arguments besides the options have been specified, and | | 192 | If command line arguments besides the options have been specified, and |
193 | neither | | 193 | neither |
194 | .Fl c | | 194 | .Fl c |
195 | nor | | 195 | nor |
196 | .Fl s | | 196 | .Fl s |
197 | was given, then the shell treats the first argument | | 197 | was given, then the shell treats the first argument |
198 | as the name of a file from which to read commands (a shell script). | | 198 | as the name of a file from which to read commands (a shell script). |
199 | This also becomes $0 and the remaining arguments are set as the | | 199 | This also becomes $0 and the remaining arguments are set as the |
200 | positional parameters of the shell ($1, $2, etc). | | 200 | positional parameters of the shell ($1, $2, etc). |
201 | Otherwise, if | | 201 | Otherwise, if |
202 | .Fl c | | 202 | .Fl c |
203 | was given, then the first argument, which must exist, | | 203 | was given, then the first argument, which must exist, |
204 | is taken to be a string of | | 204 | is taken to be a string of |
205 | .Nm | | 205 | .Nm |
206 | commands to execute. | | 206 | commands to execute. |
207 | Then if any additional arguments follow the command string, | | 207 | Then if any additional arguments follow the command string, |
208 | those arguments become $0, $1, ... | | 208 | those arguments become $0, $1, ... |
209 | Otherwise, if additional arguments were given | | 209 | Otherwise, if additional arguments were given |
210 | (which implies that | | 210 | (which implies that |
211 | .Fl s | | 211 | .Fl s |
212 | was set) | | 212 | was set) |
213 | those arguments become $1, $2, ... | | 213 | those arguments become $1, $2, ... |
214 | If $0 has not been set by the preceding processing, it | | 214 | If $0 has not been set by the preceding processing, it |
215 | will be set to argv[0] as passed to the shell, which will | | 215 | will be set to argv[0] as passed to the shell, which will |
216 | usually be the name of the shell itself. | | 216 | usually be the name of the shell itself. |
217 | If | | 217 | If |
218 | .Fl s | | 218 | .Fl s |
219 | was given, or if neither | | 219 | was given, or if neither |
220 | .Fl c | | 220 | .Fl c |
221 | nor any additional (non-option) arguments were present, | | 221 | nor any additional (non-option) arguments were present, |
222 | the shell reads commands from its standard input. | | 222 | the shell reads commands from its standard input. |
223 | .Ss Argument List Processing | | 223 | .Ss Argument List Processing |
224 | Currently, all of the single letter options that can meaningfully | | 224 | Currently, all of the single letter options that can meaningfully |
225 | be set using the | | 225 | be set using the |
226 | .Ic set | | 226 | .Ic set |
227 | built-in, have a corresponding name | | 227 | built-in, have a corresponding name |
228 | that can be used as an argument to the | | 228 | that can be used as an argument to the |
229 | .Fl o | | 229 | .Fl o |
230 | option. | | 230 | option. |
231 | The set | | 231 | The set |
232 | .Fl o | | 232 | .Fl o |
233 | name is provided next to the single letter option in | | 233 | name is provided next to the single letter option in |
234 | the description below. | | 234 | the description below. |
235 | Some options have only a long name, they are described after | | 235 | Some options have only a long name, they are described after |
236 | the flag options, they are used with | | 236 | the flag options, they are used with |
237 | .Fl o | | 237 | .Fl o |
238 | or | | 238 | or |
239 | .Cm +o | | 239 | .Cm +o |
240 | only, either on the command line, or with the | | 240 | only, either on the command line, or with the |
241 | .Ic set | | 241 | .Ic set |
242 | built-in command. | | 242 | built-in command. |
243 | Other options described are for the command line only. | | 243 | Other options described are for the command line only. |
244 | Specifying a dash | | 244 | Specifying a dash |
245 | .Dq - | | 245 | .Dq - |
246 | turns the option on, while using a plus | | 246 | turns the option on, while using a plus |
247 | .Dq + | | 247 | .Dq + |
248 | disables the option. | | 248 | disables the option. |
249 | The following options can be set from the command line and, | | 249 | The following options can be set from the command line and, |
250 | unless otherwise stated, with the | | 250 | unless otherwise stated, with the |
251 | .Ic set | | 251 | .Ic set |
252 | built-in (described later). | | 252 | built-in (described later). |
253 | .\" | | 253 | .\" |
254 | .\" strlen("quietprofile") == strlen("local_lineno"): pick the latter | | 254 | .\" strlen("quietprofile") == strlen("local_lineno"): pick the latter |
255 | .\" to give the indent as the _ in local_lineno, and the fi ligature in | | 255 | .\" to give the indent as the _ in local_lineno, and the fi ligature in |
256 | .\" quietprofile combine to make "local_lineno' slightly wider when printed | | 256 | .\" quietprofile combine to make "local_lineno' slightly wider when printed |
257 | .\" (in italics) in a variable width font. Probably should test the actual | | 257 | .\" (in italics) in a variable width font. Probably should test the actual |
258 | .\" widths and use the wider, but I am not sure if mandoc is up to that... | | 258 | .\" widths and use the wider, but I am not sure if mandoc is up to that... |
259 | .\" (and I don't know how to get at the font that will be used easily anyway!) | | 259 | .\" (and I don't know how to get at the font that will be used easily anyway!) |
260 | .\" The X's just provide a little extra space. | | 260 | .\" The X's just provide a little extra space. |
261 | .Bl -tag -width \-WXXlocal_linenoXX -offset indent | | 261 | .Bl -tag -width \-WXXlocal_linenoXX -offset indent |
262 | .\" | | 262 | .\" |
263 | .It Fl a Em allexport | | 263 | .It Fl a Em allexport |
264 | Automatically export any variable to which a value is assigned | | 264 | Automatically export any variable to which a value is assigned |
265 | while this flag is set. | | 265 | while this flag is set. |
266 | .It Fl b Em notify | | 266 | .It Fl b Em notify |
267 | Enable asynchronous notification of background job completion. | | 267 | Enable asynchronous notification of background job completion. |
268 | (Not implemented.) | | 268 | (Not implemented.) |
269 | .It Fl C Em noclobber | | 269 | .It Fl C Em noclobber |
270 | Don't overwrite existing files with | | 270 | Don't overwrite existing files with |
271 | .Dq > . | | 271 | .Dq > . |
272 | .It Fl c | | 272 | .It Fl c |
273 | Read commands from the | | 273 | Read commands from the |
274 | .Ar command_string | | 274 | .Ar command_string |
275 | operand instead of, or in addition to, from the standard input. | | 275 | operand instead of, or in addition to, from the standard input. |
276 | Special parameter 0 will be set from the | | 276 | Special parameter 0 will be set from the |
277 | .Ar command_name | | 277 | .Ar command_name |
278 | operand if given, and the positional parameters ($1, $2, etc.) | | 278 | operand if given, and the positional parameters ($1, $2, etc.) |
279 | set from the remaining argument operands, if any. | | 279 | set from the remaining argument operands, if any. |
280 | .Fl c | | 280 | .Fl c |
281 | is only available at invocation, it cannot be | | 281 | is only available at invocation, it cannot be |
282 | .Ic set , | | 282 | .Ic set , |
283 | and there is no form using | | 283 | and there is no form using |
284 | .Dq \&+ . | | 284 | .Dq \&+ . |
285 | .It Fl E Em emacs | | 285 | .It Fl E Em emacs |
286 | Enable the built-in emacs style | | 286 | Enable the built-in emacs style |
287 | command line editor (disables | | 287 | command line editor (disables |
288 | .Fl V | | 288 | .Fl V |
289 | if it has been set). | | 289 | if it has been set). |
290 | (See the | | 290 | (See the |
291 | .Sx Command Line Editing | | 291 | .Sx Command Line Editing |
292 | section below.) | | 292 | section below.) |
293 | .It Fl e Em errexit | | 293 | .It Fl e Em errexit |
294 | If not interactive, exit immediately if any untested command fails. | | 294 | If not interactive, exit immediately if any untested command fails. |
295 | If interactive, and an untested command fails, | | 295 | If interactive, and an untested command fails, |
296 | cease all processing of the current command and return to | | 296 | cease all processing of the current command and return to |
297 | prompt for a new command. | | 297 | prompt for a new command. |
298 | The exit status of a command is considered to be | | 298 | The exit status of a command is considered to be |
299 | explicitly tested if the command is used to control an | | 299 | explicitly tested if the command is used to control an |
300 | .Ic if , | | 300 | .Ic if , |
301 | .Ic elif , | | 301 | .Ic elif , |
302 | .Ic while , | | 302 | .Ic while , |
303 | or | | 303 | or |
304 | .Ic until , | | 304 | .Ic until , |
305 | or if the command is the left hand operand of an | | 305 | or if the command is the left hand operand of an |
306 | .Dq && | | 306 | .Dq && |
307 | or | | 307 | or |
308 | .Dq || | | 308 | .Dq || |
309 | operator, | | 309 | operator, |
310 | or if it is a pipeline (or simple command) preceded by the | | 310 | or if it is a pipeline (or simple command) preceded by the |
311 | .Dq \&! | | 311 | .Dq \&! |
312 | operator. | | 312 | operator. |
313 | With pipelines, only the status of the entire pipeline | | 313 | With pipelines, only the status of the entire pipeline |
314 | (indicated by the last command it contains) | | 314 | (indicated by the last command it contains) |
315 | is tested when | | 315 | is tested when |
316 | .Fl e | | 316 | .Fl e |
317 | is set to determine if the shell should exit. | | 317 | is set to determine if the shell should exit. |
318 | .It Fl F Em fork | | 318 | .It Fl F Em fork |
319 | Cause the shell to always use | | 319 | Cause the shell to always use |
320 | .Xr fork 2 | | 320 | .Xr fork 2 |
321 | instead of attempting | | 321 | instead of attempting |
322 | .Xr vfork 2 | | 322 | .Xr vfork 2 |
323 | when it needs to create a new process. | | 323 | when it needs to create a new process. |
324 | This should normally have no visible effect, | | 324 | This should normally have no visible effect, |
325 | but can slow execution. | | 325 | but can slow execution. |
326 | The | | 326 | The |
327 | .Nm | | 327 | .Nm |
328 | can be compiled to always use | | 328 | can be compiled to always use |
329 | .Xr fork 2 | | 329 | .Xr fork 2 |
330 | in which case altering the | | 330 | in which case altering the |
331 | .Fl F | | 331 | .Fl F |
332 | flag has no effect. | | 332 | flag has no effect. |
333 | .It Fl f Em noglob | | 333 | .It Fl f Em noglob |
334 | Disable pathname expansion. | | 334 | Disable pathname expansion. |
335 | .It Fl h Em trackall | | 335 | .It Fl h Em trackall |
336 | Functions defined while this option is set will have paths bound to | | 336 | Functions defined while this option is set will have paths bound to |
337 | commands to be executed by the function at the time of the definition. | | 337 | commands to be executed by the function at the time of the definition. |
338 | When off when a function is defined, | | 338 | When off when a function is defined, |
339 | the file system is searched for commands each time the function is invoked. | | 339 | the file system is searched for commands each time the function is invoked. |
340 | (Not implemented.) | | 340 | (Not implemented.) |
341 | .It Fl I Em ignoreeof | | 341 | .It Fl I Em ignoreeof |
342 | Ignore EOFs from input when interactive. | | 342 | Ignore EOFs from input when interactive. |
343 | (After a large number of consecutive EOFs the shell will exit anyway.) | | 343 | (After a large number of consecutive EOFs the shell will exit anyway.) |
344 | .It Fl i Em interactive | | 344 | .It Fl i Em interactive |
345 | Force the shell to behave interactively. | | 345 | Force the shell to behave interactively. |
346 | .It Fl L Em local_lineno | | 346 | .It Fl L Em local_lineno |
347 | When set, before a function is defined, | | 347 | When set, before a function is defined, |
348 | causes the variable | | 348 | causes the variable |
349 | .Ev LINENO | | 349 | .Ev LINENO |
350 | when used within the function, | | 350 | when used within the function, |
351 | to refer to the line number defined such that | | 351 | to refer to the line number defined such that |
352 | first line of the function is line 1. | | 352 | first line of the function is line 1. |
353 | When reset, | | 353 | When reset, |
354 | .Ev LINENO | | 354 | .Ev LINENO |
355 | in a function refers to the line number within the file | | 355 | in a function refers to the line number within the file |
356 | within which the definition of the function occurs. | | 356 | within which the definition of the function occurs. |
357 | This option defaults to | | 357 | This option defaults to |
358 | .Dq on | | 358 | .Dq on |
359 | in this shell. | | 359 | in this shell. |
360 | For more details see the section | | 360 | For more details see the section |
361 | .Sx LINENO | | 361 | .Sx LINENO |
362 | below. | | 362 | below. |
363 | .It Fl m Em monitor | | 363 | .It Fl m Em monitor |
364 | Turn on job control (set automatically when interactive). | | 364 | Turn on job control (set automatically when interactive). |
365 | .It Fl n Em noexec | | 365 | .It Fl n Em noexec |
366 | Read and parse commands, but do not execute them. | | 366 | Read and parse commands, but do not execute them. |
367 | This is useful for checking the syntax of shell scripts. | | 367 | This is useful for checking the syntax of shell scripts. |
368 | If | | 368 | If |
369 | .Fl n | | 369 | .Fl n |
370 | becomes set in an interactive shell, it will automatically be | | 370 | becomes set in an interactive shell, it will automatically be |
371 | cleared just before the next time the command line prompt | | 371 | cleared just before the next time the command line prompt |
372 | .Pq Ev PS1 | | 372 | .Pq Ev PS1 |
373 | is written. | | 373 | is written. |
374 | .It Fl p Em nopriv | | 374 | .It Fl p Em nopriv |
375 | Do not attempt to reset effective UID if it does not match UID. | | 375 | Do not attempt to reset effective UID if it does not match UID. |
376 | This is not set by default to help avoid incorrect usage by setuid | | 376 | This is not set by default to help avoid incorrect usage by setuid |
377 | root programs via | | 377 | root programs via |
378 | .Xr system 3 | | 378 | .Xr system 3 |
379 | or | | 379 | or |
380 | .Xr popen 3 . | | 380 | .Xr popen 3 . |
381 | .It Fl q Em quietprofile | | 381 | .It Fl q Em quietprofile |
382 | If the | | 382 | If the |
383 | .Fl v | | 383 | .Fl v |
384 | or | | 384 | or |
385 | .Fl x | | 385 | .Fl x |
386 | options have been set, do not apply them when reading | | 386 | options have been set, do not apply them when reading |
387 | initialization files, these being | | 387 | initialization files, these being |
388 | .Pa /etc/profile , | | 388 | .Pa /etc/profile , |
389 | .Pa .profile , | | 389 | .Pa .profile , |
390 | and the file specified by the | | 390 | and the file specified by the |
391 | .Ev ENV | | 391 | .Ev ENV |
392 | environment variable. | | 392 | environment variable. |
393 | .It Fl s Em stdin | | 393 | .It Fl s Em stdin |
394 | Read commands from standard input (set automatically if | | 394 | Read commands from standard input (set automatically if |
395 | neither | | 395 | neither |
396 | .Fl c | | 396 | .Fl c |
397 | nor file arguments are present). | | 397 | nor file arguments are present). |
398 | If after processing a command_string with the | | 398 | If after processing a command_string with the |
399 | .Fl c | | 399 | .Fl c |
400 | option, the shell has not exited, and the | | 400 | option, the shell has not exited, and the |
401 | .Fl s | | 401 | .Fl s |
402 | option is set, it will continue reading more commands from standard input. | | 402 | option is set, it will continue reading more commands from standard input. |
403 | This option has no effect when set or reset after the shell has | | 403 | This option has no effect when set or reset after the shell has |
404 | already started reading from the command_file, or from standard input. | | 404 | already started reading from the command_file, or from standard input. |
405 | Note that the | | 405 | Note that the |
406 | .Fl s | | 406 | .Fl s |
407 | flag being set does not cause the shell to be interactive. | | 407 | flag being set does not cause the shell to be interactive. |
408 | .It Fl u Em nounset | | 408 | .It Fl u Em nounset |
409 | Write a message to standard error when attempting to obtain a | | 409 | Write a message to standard error when attempting to obtain a |
410 | value from a variable that is not set, | | 410 | value from a variable that is not set, |
411 | and if the shell is not interactive, exit immediately. | | 411 | and if the shell is not interactive, exit immediately. |
412 | For interactive shells, instead return immediately to the command prompt | | 412 | For interactive shells, instead return immediately to the command prompt |
413 | and read the next command. | | 413 | and read the next command. |
414 | Note that expansions (described later, see | | 414 | Note that expansions (described later, see |
415 | .Sx Word Expansions | | 415 | .Sx Word Expansions |
416 | below) using the | | 416 | below) using the |
417 | .Sq \&+ , | | 417 | .Sq \&+ , |
418 | .Sq \&\- , | | 418 | .Sq \&\- , |
419 | .Sq \&= , | | 419 | .Sq \&= , |
420 | or | | 420 | or |
421 | .Sq \&? | | 421 | .Sq \&? |
422 | operators test if the variable is set, before attempting to | | 422 | operators test if the variable is set, before attempting to |
423 | obtain its value, and hence are unaffected by | | 423 | obtain its value, and hence are unaffected by |
424 | .Fl u . | | 424 | .Fl u . |
425 | .It Fl V Em vi | | 425 | .It Fl V Em vi |
426 | Enable the built-in | | 426 | Enable the built-in |
427 | .Xr vi 1 | | 427 | .Xr vi 1 |
428 | command line editor (disables | | 428 | command line editor (disables |
429 | .Fl E | | 429 | .Fl E |
430 | if it has been set). | | 430 | if it has been set). |
431 | (See the | | 431 | (See the |
432 | .Sx Command Line Editing | | 432 | .Sx Command Line Editing |
433 | section below.) | | 433 | section below.) |
434 | .It Fl v Em verbose | | 434 | .It Fl v Em verbose |
435 | The shell writes its input to standard error as it is read. | | 435 | The shell writes its input to standard error as it is read. |
436 | Useful for debugging. | | 436 | Useful for debugging. |
437 | .It Fl X Em Xtrace | | 437 | .It Fl X Em Xtrace |
438 | Cause output from the | | 438 | Cause output from the |
439 | .Ic xtrace | | 439 | .Ic xtrace |
440 | .Pq Fl x | | 440 | .Pq Fl x |
441 | option to be sent to standard error as it exists when the | | 441 | option to be sent to standard error as it exists when the |
442 | .Fl X | | 442 | .Fl X |
443 | option is enabled (regardless of its previous state.) | | 443 | option is enabled (regardless of its previous state.) |
444 | For example: | | 444 | For example: |
445 | .Bd -literal -compact | | 445 | .Bd -literal -compact |
446 | set -X 2>/tmp/trace-file | | 446 | set -X 2>/tmp/trace-file |
447 | .Ed | | 447 | .Ed |
448 | will arrange for tracing output to be sent to the file named, | | 448 | will arrange for tracing output to be sent to the file named, |
449 | instead of wherever it was previously being sent, | | 449 | instead of wherever it was previously being sent, |
450 | until the X option is set again, or cleared. | | 450 | until the X option is set again, or cleared. |
451 | .Pp | | 451 | .Pp |
452 | Each change (set or clear) to | | 452 | Each change (set or clear) to |
453 | .Fl X | | 453 | .Fl X |
454 | is also performed upon | | 454 | is also performed upon |
455 | .Fl x , | | 455 | .Fl x , |
456 | but not the converse. | | 456 | but not the converse. |
457 | .It Fl x Em xtrace | | 457 | .It Fl x Em xtrace |
458 | Write each command to standard error (preceded by the expanded value of | | 458 | Write each command to standard error (preceded by the expanded value of |
459 | .Dq $PS4 ) | | 459 | .Dq $PS4 ) |
460 | before it is executed. | | 460 | before it is executed. |
461 | Unless | | 461 | Unless |
462 | .Fl X | | 462 | .Fl X |
463 | is set, | | 463 | is set, |
464 | .Dq "standard error" | | 464 | .Dq "standard error" |
465 | means that which existed immediately before any redirections to | | 465 | means that which existed immediately before any redirections to |
466 | be applied to the command are performed. | | 466 | be applied to the command are performed. |
467 | Useful for debugging. | | 467 | Useful for debugging. |
468 | .It "\ \ " Em cdprint | | 468 | .It "\ \ " Em cdprint |
469 | Make an interactive shell always print the new directory name when | | 469 | Make an interactive shell always print the new directory name when |
470 | changed by the | | 470 | changed by the |
471 | .Ic cd | | 471 | .Ic cd |
472 | command. | | 472 | command. |
473 | In a non-interactive shell this option has no effect. | | 473 | In a non-interactive shell this option has no effect. |
474 | .It "\ \ " Em nolog | | 474 | .It "\ \ " Em nolog |
475 | Prevent the entry of function definitions into the command history (see | | 475 | Prevent the entry of function definitions into the command history (see |
476 | .Ic fc | | 476 | .Ic fc |
477 | in the | | 477 | in the |
478 | .Sx Built-ins | | 478 | .Sx Built-ins |
479 | section.) | | 479 | section.) |
480 | (Not implemented.) | | 480 | (Not implemented.) |
481 | .It "\ \ " Em pipefail | | 481 | .It "\ \ " Em pipefail |
482 | If set, the way the exit status of a pipeline is determined | | 482 | If set, the way the exit status of a pipeline is determined |
483 | is altered. | | 483 | is altered. |
484 | See | | 484 | See |
485 | .Sx Pipelines | | 485 | .Sx Pipelines |
486 | below for the details. | | 486 | below for the details. |
487 | .It "\ \ " Em posix | | 487 | .It "\ \ " Em posix |
488 | Enables closer adherence to the POSIX shell standard. | | 488 | Enables closer adherence to the POSIX shell standard. |
489 | This option will default set at shell startup if the | | 489 | This option will default set at shell startup if the |
490 | environment variable | | 490 | environment variable |
491 | .Ev POSIXLY_CORRECT | | 491 | .Ev POSIXLY_CORRECT |
492 | is present. | | 492 | is present. |
493 | That can be overridden (set or reset) by the | | 493 | That can be overridden (set or reset) by the |
494 | .Fl o | | 494 | .Fl o |
495 | option on the command line. | | 495 | option on the command line. |
496 | Currently this option controls whether (!posix) or not (posix) | | 496 | Currently this option controls whether (!posix) or not (posix) |
497 | the file given by the | | 497 | the file given by the |
498 | .Ev ENV | | 498 | .Ev ENV |
499 | variable is read at startup by a non-interactive shell. | | 499 | variable is read at startup by a non-interactive shell. |
500 | It also controls whether file descriptors greater than 2 | | 500 | It also controls whether file descriptors greater than 2 |
501 | opened using the | | 501 | opened using the |
502 | .Ic exec | | 502 | .Ic exec |
503 | built-in command are passed on to utilities executed | | 503 | built-in command are passed on to utilities executed |
504 | .Dq ( yes | | 504 | .Dq ( yes |
505 | in posix mode), | | 505 | in posix mode), |
506 | whether a colon (:) terminates the user name in tilde (~) expansions | | 506 | whether a colon (:) terminates the user name in tilde (~) expansions |
507 | other than in assignment statements | | 507 | other than in assignment statements |
508 | .Dq ( no | | 508 | .Dq ( no |
509 | in posix mode), | | 509 | in posix mode), |
510 | and whether the shell treats | | 510 | and whether the shell treats |
511 | an empty brace-list compound statement as a syntax error | | 511 | an empty brace-list compound statement as a syntax error |
512 | (expected by POSIX) or permits it. | | 512 | (expected by POSIX) or permits it. |
513 | Such statements | | 513 | Such statements |
514 | .Dq "{ }" | | 514 | .Dq "{ }" |
515 | can be useful when defining dummy functions. | | 515 | can be useful when defining dummy functions. |
516 | Lastly, in posix mode, only one | | 516 | Lastly, in posix mode, only one |
517 | .Dq \&! | | 517 | .Dq \&! |
518 | is permitted before a pipeline. | | 518 | is permitted before a pipeline. |
519 | .It "\ \ " Em promptcmds | | 519 | .It "\ \ " Em promptcmds |
520 | Allows command substitutions (as well as parameter | | 520 | Allows command substitutions (as well as parameter |
521 | and arithmetic expansions, which are always performed) | | 521 | and arithmetic expansions, which are always performed) |
522 | upon the prompt strings | | 522 | upon the prompt strings |
523 | .Ev PS1 , | | 523 | .Ev PS1 , |
524 | .Ev PS2 , | | 524 | .Ev PS2 , |
525 | and | | 525 | and |
526 | .Ev PS4 | | 526 | .Ev PS4 |
527 | each time, before they are output. | | 527 | each time, before they are output. |
528 | This option should not be set until after the prompts | | 528 | This option should not be set until after the prompts |
529 | have been set (or verified) to avoid accidentally importing | | 529 | have been set (or verified) to avoid accidentally importing |
530 | unwanted command substitutions from the environment. | | 530 | unwanted command substitutions from the environment. |
531 | .It "\ \ " Em tabcomplete | | 531 | .It "\ \ " Em tabcomplete |
532 | Enables filename completion in the command line editor. | | 532 | Enables filename completion in the command line editor. |
533 | Typing a tab character will extend the current input word to match a | | 533 | Typing a tab character will extend the current input word to match a |
534 | filename. | | 534 | filename. |
535 | If more than one filename matches it is only extended to be the common prefix. | | 535 | If more than one filename matches it is only extended to be the common prefix. |
536 | Typing a second tab character will list all the matching names. | | 536 | Typing a second tab character will list all the matching names. |
537 | One of the editing modes, either | | 537 | One of the editing modes, either |
538 | .Fl E | | 538 | .Fl E |
539 | or | | 539 | or |
540 | .Fl V , | | 540 | .Fl V , |
541 | must be enabled for this to work. | | 541 | must be enabled for this to work. |
542 | .El | | 542 | .El |
543 | .Ss Lexical Structure | | 543 | .Ss Lexical Structure |
544 | The shell reads input in terms of lines from a file and breaks it up into | | 544 | The shell reads input in terms of lines from a file and breaks it up into |
545 | words at whitespace (blanks and tabs), and at certain sequences of | | 545 | words at whitespace (blanks and tabs), and at certain sequences of |
546 | characters that are special to the shell called | | 546 | characters that are special to the shell called |
547 | .Dq operators . | | 547 | .Dq operators . |
548 | There are two types of operators: control operators and redirection | | 548 | There are two types of operators: control operators and redirection |
549 | operators (their meaning is discussed later). | | 549 | operators (their meaning is discussed later). |
550 | The following is a list of operators: | | 550 | The following is a list of operators: |
551 | .Bl -ohang -offset indent | | 551 | .Bl -ohang -offset indent |
552 | .It "Control operators:" | | 552 | .It "Control operators:" |
553 | .Dl & && \&( \&) \&; ;; ;& | || <newline> | | 553 | .Dl & && \&( \&) \&; ;; ;& \&| || <newline> |
554 | .It "Redirection operators:" | | 554 | .It "Redirection operators:" |
555 | .Dl < > >| << >> <& >& <<- <> | | 555 | .Dl < > >| << >> <& >& <<- <> |
556 | .El | | 556 | .El |
557 | .Ss Quoting | | 557 | .Ss Quoting |
558 | Quoting is used to remove the special meaning of certain characters or | | 558 | Quoting is used to remove the special meaning of certain characters or |
559 | words to the shell, such as operators, whitespace, or keywords. | | 559 | words to the shell, such as operators, whitespace, or keywords. |
560 | There are four types of quoting: | | 560 | There are four types of quoting: |
561 | matched single quotes, | | 561 | matched single quotes, |
562 | matched double quotes, | | 562 | matched double quotes, |
563 | backslash, | | 563 | backslash, |
564 | and | | 564 | and |
565 | dollar preceding matched single quotes (enhanced C style strings.) | | 565 | dollar preceding matched single quotes (enhanced C style strings.) |
566 | .Ss Backslash | | 566 | .Ss Backslash |
567 | An unquoted backslash preserves the literal meaning of the following | | 567 | An unquoted backslash preserves the literal meaning of the following |
568 | character, with the exception of | | 568 | character, with the exception of |
569 | .Aq newline . | | 569 | .Aq newline . |
570 | An unquoted backslash preceding a | | 570 | An unquoted backslash preceding a |
571 | .Aq newline | | 571 | .Aq newline |
572 | is treated as a line continuation, the two characters are simply removed. | | 572 | is treated as a line continuation, the two characters are simply removed. |
573 | .Ss Single Quotes | | 573 | .Ss Single Quotes |
574 | Enclosing characters in single quotes preserves the literal meaning of all | | 574 | Enclosing characters in single quotes preserves the literal meaning of all |
575 | the characters (except single quotes, making it impossible to put | | 575 | the characters (except single quotes, making it impossible to put |
576 | single quotes in a single-quoted string). | | 576 | single quotes in a single-quoted string). |
577 | .Ss Double Quotes | | 577 | .Ss Double Quotes |
578 | Enclosing characters within double quotes preserves the literal | | 578 | Enclosing characters within double quotes preserves the literal |
579 | meaning of all characters except dollar sign | | 579 | meaning of all characters except dollar sign |
580 | .Pq $ , | | 580 | .Pq $ , |
581 | backquote | | 581 | backquote |
582 | .Pq ` , | | 582 | .Pq ` , |
583 | and backslash | | 583 | and backslash |
584 | .Pq \e . | | 584 | .Pq \e . |
585 | The backslash inside double quotes is historically weird, and serves to | | 585 | The backslash inside double quotes is historically weird, and serves to |
586 | quote only the following characters (and these not in all contexts): | | 586 | quote only the following characters (and these not in all contexts): |
587 | .Dl $ ` \*q \e <newline> , | | 587 | .Dl $ ` \*q \e <newline> , |
588 | where a backslash newline is a line continuation as above. | | 588 | where a backslash newline is a line continuation as above. |
589 | Otherwise it remains literal. | | 589 | Otherwise it remains literal. |
590 | .Ss Dollar Single Quotes (\&$'...') | | 590 | .Ss Dollar Single Quotes (\&$'...') |
591 | .Bd -filled -offset indent | | 591 | .Bd -filled -offset indent |
592 | .Bf Em | | 592 | .Bf Em |
593 | Note: this form of quoting is still somewhat experimental, | | 593 | Note: this form of quoting is still somewhat experimental, |
594 | and yet to be included in the POSIX standard. | | 594 | and yet to be included in the POSIX standard. |
595 | This implementation is based upon the current proposals for | | 595 | This implementation is based upon the current proposals for |
596 | standardization, and is subject to change should the eventual | | 596 | standardization, and is subject to change should the eventual |
597 | adopted text differ. | | 597 | adopted text differ. |
598 | .Ef | | 598 | .Ef |
599 | .Ed | | 599 | .Ed |
600 | .Pp | | 600 | .Pp |
601 | Enclosing characters in a matched pair of single quotes, with the | | 601 | Enclosing characters in a matched pair of single quotes, with the |
602 | first immediately preceded by an unquoted dollar sign | | 602 | first immediately preceded by an unquoted dollar sign |
603 | .Pq \&$ | | 603 | .Pq \&$ |
604 | provides a quoting mechanism similar to single quotes, except | | 604 | provides a quoting mechanism similar to single quotes, except |
605 | that within the sequence of characters, any backslash | | 605 | that within the sequence of characters, any backslash |
606 | .Pq \e , | | 606 | .Pq \e , |
607 | is an escape character, which causes the following character to | | 607 | is an escape character, which causes the following character to |
608 | be treated specially. | | 608 | be treated specially. |
609 | Only a subset of the characters that can occur in the string | | 609 | Only a subset of the characters that can occur in the string |
610 | are defined after a backslash, others are reserved for future | | 610 | are defined after a backslash, others are reserved for future |
611 | definition, and currently generate a syntax error if used. | | 611 | definition, and currently generate a syntax error if used. |
612 | The escape sequences are modeled after the similar sequences | | 612 | The escape sequences are modeled after the similar sequences |
613 | in strings in the C programming language, with some extensions. | | 613 | in strings in the C programming language, with some extensions. |
614 | .Pp | | 614 | .Pp |
615 | The following characters are treated literally when following | | 615 | The following characters are treated literally when following |
616 | the escape character (backslash): | | 616 | the escape character (backslash): |
617 | .Dl \e \&' \&" | | 617 | .Dl \e \&' \&" |
618 | The sequence | | 618 | The sequence |
619 | .Dq \e\e | | 619 | .Dq \e\e |
620 | allows the escape character (backslash) to appear in the string literally. | | 620 | allows the escape character (backslash) to appear in the string literally. |
621 | .Dq \e' | | 621 | .Dq \e' |
622 | allows a single quote character into the string, such an | | 622 | allows a single quote character into the string, such an |
623 | escaped single quote does not terminate the quoted string. | | 623 | escaped single quote does not terminate the quoted string. |
624 | .Dq \e" | | 624 | .Dq \e" |
625 | is for compatibility with C strings, the double quote has | | 625 | is for compatibility with C strings, the double quote has |
626 | no special meaning in a shell C-style string, | | 626 | no special meaning in a shell C-style string, |
627 | and does not need to be escaped, but may be. | | 627 | and does not need to be escaped, but may be. |
628 | .Pp | | 628 | .Pp |
629 | A newline following the escape character is treated as a line continuation, | | 629 | A newline following the escape character is treated as a line continuation, |
630 | like the same sequence in a double quoted string, | | 630 | like the same sequence in a double quoted string, |
631 | or when not quoted \(en | | 631 | or when not quoted \(en |
632 | the two characters, escape and newline, are removed from the input string. | | 632 | the two characters, escape and newline, are removed from the input string. |
633 | .Pp | | 633 | .Pp |
634 | The following characters, when escaped, are converted in a | | 634 | The following characters, when escaped, are converted in a |
635 | manner similar to the way they would be in a string in the C language: | | 635 | manner similar to the way they would be in a string in the C language: |
636 | .Dl a b e f n r t v | | 636 | .Dl a b e f n r t v |
637 | An escaped | | 637 | An escaped |
638 | .Sq a | | 638 | .Sq a |
639 | generates an alert (or | | 639 | generates an alert (or |
640 | .Sq BEL ) | | 640 | .Sq BEL ) |
641 | character, that is, control-G, or 0x07. | | 641 | character, that is, control-G, or 0x07. |
642 | In a similar way, | | 642 | In a similar way, |
643 | .Sq b | | 643 | .Sq b |
644 | is backspace (0x08), | | 644 | is backspace (0x08), |
645 | .Sq e | | 645 | .Sq e |
646 | (an extension to C) is escape (0x1B), | | 646 | (an extension to C) is escape (0x1B), |
647 | .Sq f | | 647 | .Sq f |
648 | is form feed (0x0C), | | 648 | is form feed (0x0C), |
649 | .Sq n | | 649 | .Sq n |
650 | is newline (or line feed, 0x0A), | | 650 | is newline (or line feed, 0x0A), |
651 | .Sq r | | 651 | .Sq r |
652 | is return (0x0D), | | 652 | is return (0x0D), |
653 | .Sq t | | 653 | .Sq t |
654 | is horizontal tab (0x09), | | 654 | is horizontal tab (0x09), |
655 | and | | 655 | and |
656 | .Sq v | | 656 | .Sq v |
657 | is vertical tab (0x13). | | 657 | is vertical tab (0x13). |
658 | .Pp | | 658 | .Pp |
659 | In addition to those there are 5 forms that need additional | | 659 | In addition to those there are 5 forms that need additional |
660 | data, which is obtained from the subsequent characters. | | 660 | data, which is obtained from the subsequent characters. |
661 | An escape | | 661 | An escape |
662 | .Pq \e | | 662 | .Pq \e |
663 | followed by one, two or three, octal digits | | 663 | followed by one, two or three, octal digits |
664 | .Po So 0 Sc Ns \&.. Ns So 7 Sc Ns Pc | | 664 | .Po So 0 Sc Ns \&.. Ns So 7 Sc Ns Pc |
665 | is processed to form an 8 bit character value. | | 665 | is processed to form an 8 bit character value. |
666 | If only one or two digits are present, the following | | 666 | If only one or two digits are present, the following |
667 | character must be something other than an octal digit. | | 667 | character must be something other than an octal digit. |
668 | It is safest to always use all 3 digits, with leading | | 668 | It is safest to always use all 3 digits, with leading |
669 | zeros if needed. | | 669 | zeros if needed. |
670 | If all three digits are present, the first must be one of | | 670 | If all three digits are present, the first must be one of |
671 | .So 0 Sc Ns \&.. Ns So 3 Sc . | | 671 | .So 0 Sc Ns \&.. Ns So 3 Sc . |
672 | .Pp | | 672 | .Pp |
673 | An escape followed by | | 673 | An escape followed by |
674 | .Sq x | | 674 | .Sq x |
675 | (lower case only) can be followed by one or two | | 675 | (lower case only) can be followed by one or two |
676 | hexadecimal digits | | 676 | hexadecimal digits |
677 | .Po So 0 Sc Ns \&.. Ns So 9 Sc , So A Sc Ns \&.. Ns So F Sc , or So a Sc Ns \&.. Ns So f Sc . Pc | | 677 | .Po So 0 Sc Ns \&.. Ns So 9 Sc , So A Sc Ns \&.. Ns So F Sc , or So a Sc Ns \&.. Ns So f Sc . Pc |
678 | As with octal, if only one hex digit is present, the following | | 678 | As with octal, if only one hex digit is present, the following |
679 | character must be something other than a hex digit, | | 679 | character must be something other than a hex digit, |
680 | so always giving 2 hex digits is best. | | 680 | so always giving 2 hex digits is best. |
681 | However, unlike octal, it is unspecified in the standard | | 681 | However, unlike octal, it is unspecified in the standard |
682 | how many hex digits can be consumed. | | 682 | how many hex digits can be consumed. |
683 | This | | 683 | This |
684 | .Nm | | 684 | .Nm |
685 | takes at most two, but other shells will continue consuming | | 685 | takes at most two, but other shells will continue consuming |
686 | characters as long as they remain valid hex digits. | | 686 | characters as long as they remain valid hex digits. |
687 | Consequently, users should ensure that the character | | 687 | Consequently, users should ensure that the character |
688 | following the hex escape sequence is something other than | | 688 | following the hex escape sequence is something other than |
689 | a hex digit. | | 689 | a hex digit. |
690 | One way to achieve this is to end the $'...' string immediately | | 690 | One way to achieve this is to end the $'...' string immediately |
691 | after the final hex digit, and then, immediately start | | 691 | after the final hex digit, and then, immediately start |
692 | another, so | | 692 | another, so |
693 | .Dl \&$'\ex33'$'4...' | | 693 | .Dl \&$'\ex33'$'4...' |
694 | always gives the character with value 0x33 | | 694 | always gives the character with value 0x33 |
695 | .Pq Sq 3 , | | 695 | .Pq Sq 3 , |
696 | followed by the character | | 696 | followed by the character |
697 | .Sq 4 , | | 697 | .Sq 4 , |
698 | whereas | | 698 | whereas |
699 | .Dl \&$'\ex334' | | 699 | .Dl \&$'\ex334' |
700 | in some other shells would be the hex value 0x334 (10, or more, bits). | | 700 | in some other shells would be the hex value 0x334 (10, or more, bits). |
701 | .Pp | | 701 | .Pp |
702 | There are two escape sequences beginning with | | 702 | There are two escape sequences beginning with |
703 | .Sq \eu | | 703 | .Sq \eu |
704 | or | | 704 | or |
705 | .Sq \eU . | | 705 | .Sq \eU . |
706 | The former is followed by from 1 to 4 hex digits, the latter by | | 706 | The former is followed by from 1 to 4 hex digits, the latter by |
707 | from 1 to 8 hex digits. | | 707 | from 1 to 8 hex digits. |
708 | Leading zeros can be used to pad the sequences to the maximum | | 708 | Leading zeros can be used to pad the sequences to the maximum |
709 | permitted length, to avoid any possible ambiguity problem with | | 709 | permitted length, to avoid any possible ambiguity problem with |
710 | the following character, and because there are some shells that | | 710 | the following character, and because there are some shells that |
711 | insist on exactly 4 (or 8) hex digits. | | 711 | insist on exactly 4 (or 8) hex digits. |
712 | These sequences are evaluated to form the value of a Unicode code | | 712 | These sequences are evaluated to form the value of a Unicode code |
713 | point, which is then encoded into UTF-8 form, and entered into the | | 713 | point, which is then encoded into UTF-8 form, and entered into the |
714 | string. | | 714 | string. |
715 | (The code point should be converted to the appropriate | | 715 | (The code point should be converted to the appropriate |
716 | code point value for the corresponding character in the character | | 716 | code point value for the corresponding character in the character |
717 | set given by the current locale, or perhaps the locale in use | | 717 | set given by the current locale, or perhaps the locale in use |
718 | when the shell was started, but is not... currently.) | | 718 | when the shell was started, but is not... currently.) |
719 | Not all values that are possible to write are valid, values that | | 719 | Not all values that are possible to write are valid, values that |
720 | specify (known) invalid Unicode code points will be rejected, or | | 720 | specify (known) invalid Unicode code points will be rejected, or |
721 | simply produce | | 721 | simply produce |
722 | .Sq \&? . | | 722 | .Sq \&? . |
723 | .Pp | | 723 | .Pp |
724 | Lastly, as another addition to what is available in C, the escape | | 724 | Lastly, as another addition to what is available in C, the escape |
725 | character (backslash), followed by | | 725 | character (backslash), followed by |
726 | .Sq c | | 726 | .Sq c |
727 | (lower case only) followed by one additional character, which must | | 727 | (lower case only) followed by one additional character, which must |
728 | be an alphabetic character (a letter), or one of the following: | | 728 | be an alphabetic character (a letter), or one of the following: |
729 | .Dl \&@ \&[ \&\e \&] \&^ \&_ \&? | | 729 | .Dl \&@ \&[ \&\e \&] \&^ \&_ \&? |
730 | Other than | | 730 | Other than |
731 | .Sq \ec? | | 731 | .Sq \ec? |
732 | the value obtained is the least significant 5 bits of the | | 732 | the value obtained is the least significant 5 bits of the |
733 | ASCII value of the character following the | | 733 | ASCII value of the character following the |
734 | .Sq \ec | | 734 | .Sq \ec |
735 | escape sequence. | | 735 | escape sequence. |
736 | That is what is commonly known as the | | 736 | That is what is commonly known as the |
737 | .Dq control | | 737 | .Dq control |
738 | character obtained from the given character. | | 738 | character obtained from the given character. |
739 | The escape sequence | | 739 | The escape sequence |
740 | .Sq \ec? | | 740 | .Sq \ec? |
741 | yields the ASCII DEL character (0x7F). | | 741 | yields the ASCII DEL character (0x7F). |
742 | Note that to obtain the ASCII FS character (0x1C) this way, | | 742 | Note that to obtain the ASCII FS character (0x1C) this way, |
743 | .Pq "that is control-\e" | | 743 | .Pq "that is control-\e" |
744 | the trailing | | 744 | the trailing |
745 | .Sq \e | | 745 | .Sq \e |
746 | must be escaped itself, and so for this one case, the full | | 746 | must be escaped itself, and so for this one case, the full |
747 | escape sequence is | | 747 | escape sequence is |
748 | .Dq \ec\e\e . | | 748 | .Dq \ec\e\e . |
749 | The sequence | | 749 | The sequence |
750 | .Dq \ec\eX | | 750 | .Dq \ec\eX |
751 | where | | 751 | where |
752 | .Sq X | | 752 | .Sq X |
753 | is some character other than | | 753 | is some character other than |
754 | .Sq \e | | 754 | .Sq \e |
755 | is reserved for future use, its meaning is unspecified. | | 755 | is reserved for future use, its meaning is unspecified. |
756 | In this | | 756 | In this |
757 | .Nm | | 757 | .Nm |
758 | an error is generated. | | 758 | an error is generated. |
759 | .Pp | | 759 | .Pp |
760 | If any of the preceding escape sequences generate the value | | 760 | If any of the preceding escape sequences generate the value |
761 | .Sq \e0 | | 761 | .Sq \e0 |
762 | (a NUL character) that character, and all that follow in the | | 762 | (a NUL character) that character, and all that follow in the |
763 | same $'...' string, are omitted from the resulting word. | | 763 | same $'...' string, are omitted from the resulting word. |
764 | .Pp | | 764 | .Pp |
765 | After the $'...' string has had any included escape sequences | | 765 | After the $'...' string has had any included escape sequences |
766 | converted, it is treated as if it had been a single quoted string. | | 766 | converted, it is treated as if it had been a single quoted string. |
767 | .Ss Reserved Words | | 767 | .Ss Reserved Words |
768 | Reserved words are words that have special meaning to the | | 768 | Reserved words are words that have special meaning to the |
769 | shell and are recognized at the beginning of a line and | | 769 | shell and are recognized at the beginning of a line and |
770 | after a control operator. | | 770 | after a control operator. |
771 | The following are reserved words: | | 771 | The following are reserved words: |
772 | .Bl -column while while while while -offset indent | | 772 | .Bl -column while while while while -offset indent |
773 | .It Ic \&! Ta Ic \&{ Ta Ic \&} Ta Ic case | | 773 | .It Ic \&! Ta Ic \&{ Ta Ic \&} Ta Ic case |
774 | .It Ic do Ta Ic done Ta Ic elif Ta Ic else | | 774 | .It Ic do Ta Ic done Ta Ic elif Ta Ic else |
775 | .It Ic esac Ta Ic fi Ta Ic for Ta Ic if | | 775 | .It Ic esac Ta Ic fi Ta Ic for Ta Ic if |
776 | .It Ic in Ta Ic then Ta Ic until Ta Ic while | | 776 | .It Ic in Ta Ic then Ta Ic until Ta Ic while |
777 | .El | | 777 | .El |
778 | .Pp | | 778 | .Pp |
779 | Their meanings are discussed later. | | 779 | Their meanings are discussed later. |
780 | .Ss Aliases | | 780 | .Ss Aliases |
781 | An alias is a name and corresponding value set using the | | 781 | An alias is a name and corresponding value set using the |
782 | .Ic alias | | 782 | .Ic alias |
783 | built-in command. | | 783 | built-in command. |
784 | Whenever a reserved word (see above) may occur, | | 784 | Whenever a reserved word (see above) may occur, |
785 | and after checking for reserved words, the shell | | 785 | and after checking for reserved words, the shell |
786 | checks the word to see if it matches an alias. | | 786 | checks the word to see if it matches an alias. |
787 | If it does, it replaces it in the input stream with its value. | | 787 | If it does, it replaces it in the input stream with its value. |
788 | For example, if there is an alias called | | 788 | For example, if there is an alias called |
789 | .Dq lf | | 789 | .Dq lf |
790 | with the value | | 790 | with the value |
791 | .Dq "ls -F" , | | 791 | .Dq "ls -F" , |
792 | then the input: | | 792 | then the input: |
793 | .Pp | | 793 | .Pp |
794 | .Dl lf foobar Aq return | | 794 | .Dl lf foobar Aq return |
795 | .Pp | | 795 | .Pp |
796 | would become | | 796 | would become |
797 | .Pp | | 797 | .Pp |
798 | .Dl ls -F foobar Aq return | | 798 | .Dl ls -F foobar Aq return |
799 | .Pp | | 799 | .Pp |
800 | Aliases provide a convenient way for naive users to create shorthands for | | 800 | Aliases provide a convenient way for naive users to create shorthands for |
801 | commands without having to learn how to create functions with arguments. | | 801 | commands without having to learn how to create functions with arguments. |
802 | They can also be used to create lexically obscure code. | | 802 | They can also be used to create lexically obscure code. |
803 | This use is strongly discouraged. | | 803 | This use is strongly discouraged. |
804 | .Ss Commands | | 804 | .Ss Commands |
805 | The shell interprets the words it reads according to a language, the | | 805 | The shell interprets the words it reads according to a language, the |
806 | specification of which is outside the scope of this man page (refer to the | | 806 | specification of which is outside the scope of this man page (refer to the |
807 | BNF in the POSIX 1003.2 document). | | 807 | BNF in the POSIX 1003.2 document). |
808 | Essentially though, a line is read and if the first | | 808 | Essentially though, a line is read and if the first |
809 | word of the line (or after a control operator) is not a reserved word, | | 809 | word of the line (or after a control operator) is not a reserved word, |
810 | then the shell has recognized a simple command. | | 810 | then the shell has recognized a simple command. |
811 | Otherwise, a complex | | 811 | Otherwise, a complex |
812 | command or some other special construct may have been recognized. | | 812 | command or some other special construct may have been recognized. |
813 | .Ss Simple Commands | | 813 | .Ss Simple Commands |
814 | If a simple command has been recognized, the shell performs | | 814 | If a simple command has been recognized, the shell performs |
815 | the following actions: | | 815 | the following actions: |
816 | .Bl -enum -offset indent | | 816 | .Bl -enum -offset indent |
817 | .It | | 817 | .It |
818 | Leading words of the form | | 818 | Leading words of the form |
819 | .Dq name=value | | 819 | .Dq name=value |
820 | are stripped off, the value is expanded, as described below, | | 820 | are stripped off, the value is expanded, as described below, |
821 | and the results are assigned to the environment of the simple command. | | 821 | and the results are assigned to the environment of the simple command. |
822 | Redirection operators and their arguments (as described below) are | | 822 | Redirection operators and their arguments (as described below) are |
823 | stripped off and saved for processing in step 3 below. | | 823 | stripped off and saved for processing in step 3 below. |
824 | .It | | 824 | .It |
825 | The remaining words are expanded as described in the | | 825 | The remaining words are expanded as described in the |
826 | .Sx Word Expansions | | 826 | .Sx Word Expansions |
827 | section below. | | 827 | section below. |
828 | The first remaining word is considered the command name and the | | 828 | The first remaining word is considered the command name and the |
829 | command is located. | | 829 | command is located. |
830 | Any remaining words are considered the arguments of the command. | | 830 | Any remaining words are considered the arguments of the command. |
831 | If no command name resulted, then the | | 831 | If no command name resulted, then the |
832 | .Dq name=value | | 832 | .Dq name=value |
833 | variable assignments recognized in item 1 affect the current shell. | | 833 | variable assignments recognized in item 1 affect the current shell. |
834 | .It | | 834 | .It |
835 | Redirections are performed, from first to last, in the order given, | | 835 | Redirections are performed, from first to last, in the order given, |
836 | as described in the next section. | | 836 | as described in the next section. |
837 | .El | | 837 | .El |
838 | .Ss Redirections | | 838 | .Ss Redirections |
839 | Redirections are used to change where a command reads its input or sends | | 839 | Redirections are used to change where a command reads its input or sends |
840 | its output. | | 840 | its output. |
841 | In general, redirections open, close, or duplicate an | | 841 | In general, redirections open, close, or duplicate an |
842 | existing reference to a file. | | 842 | existing reference to a file. |
843 | The overall format used for redirection is: | | 843 | The overall format used for redirection is: |
844 | .Pp | | 844 | .Pp |
845 | .Dl [n] Ns Va redir-op Ar file | | 845 | .Dl [n] Ns Va redir-op Ar file |
846 | .Pp | | 846 | .Pp |
847 | where | | 847 | where |
848 | .Va redir-op | | 848 | .Va redir-op |
849 | is one of the redirection operators mentioned previously. | | 849 | is one of the redirection operators mentioned previously. |
850 | The following is a list of the possible redirections. | | 850 | The following is a list of the possible redirections. |
851 | The | | 851 | The |
852 | .Bq n | | 852 | .Bq n |
853 | is an optional number, as in | | 853 | is an optional number, as in |
854 | .Sq 3 | | 854 | .Sq 3 |
855 | (not | | 855 | (not |
856 | .Sq Bq 3 ) , | | 856 | .Sq Bq 3 ) , |
857 | that refers to a file descriptor. | | 857 | that refers to a file descriptor. |
858 | If present it must occur immediately before the redirection | | 858 | If present it must occur immediately before the redirection |
859 | operator, with no intervening white space, and becomes a | | 859 | operator, with no intervening white space, and becomes a |
860 | part of that operator. | | 860 | part of that operator. |
861 | .Bl -tag -width aaabsfiles -offset indent | | 861 | .Bl -tag -width aaabsfiles -offset indent |
862 | .It Oo Ar n Oc Ns > Ar file | | 862 | .It Oo Ar n Oc Ns > Ar file |
863 | Redirect standard output (or n) to | | 863 | Redirect standard output (or n) to |
864 | .Ar file . | | 864 | .Ar file . |
865 | .It Oo Ar n Oc Ns >| file | | 865 | .It Oo Ar n Oc Ns >| file |
866 | The same, but override the | | 866 | The same, but override the |
867 | .Fl C | | 867 | .Fl C |
868 | option. | | 868 | option. |
869 | .It Oo Ar n Oc Ns >> Ar file | | 869 | .It Oo Ar n Oc Ns >> Ar file |
870 | Append standard output (or n) to | | 870 | Append standard output (or n) to |
871 | .Ar file . | | 871 | .Ar file . |
872 | .It Oo Ar n Oc Ns < Ar file | | 872 | .It Oo Ar n Oc Ns < Ar file |
873 | Redirect standard input (or | | 873 | Redirect standard input (or |
874 | .Ar n ) | | 874 | .Ar n ) |
875 | from | | 875 | from |
876 | .Ar file . | | 876 | .Ar file . |
877 | .It Oo Ar n1 Oc Ns <& Ns Ar n2 | | 877 | .It Oo Ar n1 Oc Ns <& Ns Ar n2 |
878 | Duplicate standard input (or | | 878 | Duplicate standard input (or |
879 | .Ar n1 ) | | 879 | .Ar n1 ) |
880 | from file descriptor | | 880 | from file descriptor |
881 | .Ar n2 . | | 881 | .Ar n2 . |
882 | .Ar n2 | | 882 | .Ar n2 |
883 | is expanded if not a digit string, the result must be a number. | | 883 | is expanded if not a digit string, the result must be a number. |
884 | .It Oo Ar n Oc Ns <&- | | 884 | .It Oo Ar n Oc Ns <&- |
885 | Close standard input (or | | 885 | Close standard input (or |
886 | .Ar n ) . | | 886 | .Ar n ) . |
887 | .It Oo Ar n1 Oc Ns >& Ns Ar n2 | | 887 | .It Oo Ar n1 Oc Ns >& Ns Ar n2 |
888 | Duplicate standard output (or | | 888 | Duplicate standard output (or |
889 | .Ar n1 ) | | 889 | .Ar n1 ) |
890 | to | | 890 | to |
891 | .Ar n2 . | | 891 | .Ar n2 . |
892 | .It Oo Ar n Oc Ns >&- | | 892 | .It Oo Ar n Oc Ns >&- |
893 | Close standard output (or n). | | 893 | Close standard output (or n). |
894 | .It Oo Ar n Oc Ns <> Ar file | | 894 | .It Oo Ar n Oc Ns <> Ar file |
895 | Open | | 895 | Open |
896 | .Ar file | | 896 | .Ar file |
897 | for reading and writing on standard input (or | | 897 | for reading and writing on standard input (or |
898 | .Ar n ) . | | 898 | .Ar n ) . |
899 | .El | | 899 | .El |
900 | .Pp | | 900 | .Pp |
901 | The following redirection is often called a | | 901 | The following redirection is often called a |
902 | .Dq here-document . | | 902 | .Dq here-document . |
903 | .Bl -item -offset indent | | 903 | .Bl -item -offset indent |
904 | .It | | 904 | .It |
905 | .Li [n]<< delimiter | | 905 | .Li [n]<< delimiter |
906 | .Dl here-doc-text ... | | 906 | .Dl here-doc-text ... |
907 | .Li delimiter | | 907 | .Li delimiter |
908 | .El | | 908 | .El |
909 | .Pp | | 909 | .Pp |
910 | The | | 910 | The |
911 | .Dq here-doc-text | | 911 | .Dq here-doc-text |
912 | starts immediately after the next unquoted newline character following | | 912 | starts immediately after the next unquoted newline character following |
913 | the here-doc redirection operator. | | 913 | the here-doc redirection operator. |
914 | If there is more than one here-document redirection on the same | | 914 | If there is more than one here-document redirection on the same |
915 | line, then the text for the first (from left to right) is read | | 915 | line, then the text for the first (from left to right) is read |
916 | first, and subsequent here-doc-text for later here-doc redirections | | 916 | first, and subsequent here-doc-text for later here-doc redirections |
917 | follows immediately after, until all such redirections have been | | 917 | follows immediately after, until all such redirections have been |
918 | processed. | | 918 | processed. |
919 | .Pp | | 919 | .Pp |
920 | All the text on successive lines up to the delimiter, | | 920 | All the text on successive lines up to the delimiter, |
921 | which must appear on a line by itself, with nothing other | | 921 | which must appear on a line by itself, with nothing other |
922 | than an immediately following newline, is | | 922 | than an immediately following newline, is |
923 | saved away and made available to the command on standard input, or file | | 923 | saved away and made available to the command on standard input, or file |
924 | descriptor n if it is specified. | | 924 | descriptor n if it is specified. |
925 | If the delimiter as specified on the initial line is | | 925 | If the delimiter as specified on the initial line is |
926 | quoted, then the here-doc-text is treated literally; otherwise, the text is | | 926 | quoted, then the here-doc-text is treated literally; otherwise, the text is |
927 | treated much like a double quoted string, except that | | 927 | treated much like a double quoted string, except that |
928 | .Sq \&" | | 928 | .Sq \&" |
929 | characters have no special meaning, and are not escaped by | | 929 | characters have no special meaning, and are not escaped by |
930 | .Sq \&\e , | | 930 | .Sq \&\e , |
931 | and is subjected to parameter expansion, command substitution, and arithmetic | | 931 | and is subjected to parameter expansion, command substitution, and arithmetic |
932 | expansion as described in the | | 932 | expansion as described in the |
933 | .Sx Word Expansions | | 933 | .Sx Word Expansions |
934 | section below. | | 934 | section below. |
935 | If the operator is | | 935 | If the operator is |
936 | .Dq <<\(mi | | 936 | .Dq <<\(mi |
937 | instead of | | 937 | instead of |
938 | .Dq << , | | 938 | .Dq << , |
939 | then leading tabs in all lines in the here-doc-text, including before the | | 939 | then leading tabs in all lines in the here-doc-text, including before the |
940 | end delimiter, are stripped. | | 940 | end delimiter, are stripped. |
941 | If the delimiter is not quoted, lines in here-doc-text that end with | | 941 | If the delimiter is not quoted, lines in here-doc-text that end with |
942 | an unquoted \e are joined to the following line, the \e and following | | 942 | an unquoted \e are joined to the following line, the \e and following |
943 | newline are simply removed while reading the here-doc, which thus guarantees | | 943 | newline are simply removed while reading the here-doc, which thus guarantees |
944 | that neither of those lines can be the end delimiter. | | 944 | that neither of those lines can be the end delimiter. |
945 | .Pp | | 945 | .Pp |
946 | It is a syntax error for the end of the input file (or string) to be | | 946 | It is a syntax error for the end of the input file (or string) to be |
947 | reached before the delimiter is encountered. | | 947 | reached before the delimiter is encountered. |
948 | .Ss Search and Execution | | 948 | .Ss Search and Execution |
949 | There are three types of commands: shell functions, built-in commands, and | | 949 | There are three types of commands: shell functions, built-in commands, and |
950 | normal programs -- and the command is searched for (by name) in that order. | | 950 | normal programs -- and the command is searched for (by name) in that order. |
951 | A command that contains a slash | | 951 | A command that contains a slash |
952 | .Sq \&/ | | 952 | .Sq \&/ |
953 | in its name is always a normal program. | | 953 | in its name is always a normal program. |
954 | They each are executed in a different way. | | 954 | They each are executed in a different way. |
955 | .Pp | | 955 | .Pp |
956 | When a shell function is executed, all of the shell positional parameters | | 956 | When a shell function is executed, all of the shell positional parameters |
957 | (except $0, which remains unchanged) are set to the arguments of the shell | | 957 | (except $0, which remains unchanged) are set to the arguments of the shell |
958 | function. | | 958 | function. |
959 | The variables which are explicitly placed in the environment of | | 959 | The variables which are explicitly placed in the environment of |
960 | the command (by placing assignments to them before the function name) are | | 960 | the command (by placing assignments to them before the function name) are |
961 | made local to the function and are set to the values given, | | 961 | made local to the function and are set to the values given, |
962 | and exported for the benefit of programs executed with the function. | | 962 | and exported for the benefit of programs executed with the function. |
963 | Then the command given in the function definition is executed. | | 963 | Then the command given in the function definition is executed. |
964 | The positional parameters, and local variables, are restored to | | 964 | The positional parameters, and local variables, are restored to |
965 | their original values when the command completes. | | 965 | their original values when the command completes. |
966 | This all occurs within the current shell, and the function | | 966 | This all occurs within the current shell, and the function |
967 | can alter variables, or other settings, of the shell. | | 967 | can alter variables, or other settings, of the shell. |
968 | .Pp | | 968 | .Pp |
969 | Shell built-ins are executed internally to the shell, without spawning a | | 969 | Shell built-ins are executed internally to the shell, without spawning a |
970 | new process. | | 970 | new process. |
971 | .Pp | | 971 | .Pp |
972 | Otherwise, if the command name doesn't match a function or built-in, the | | 972 | Otherwise, if the command name doesn't match a function or built-in, the |
973 | command is searched for as a normal program in the file system (as | | 973 | command is searched for as a normal program in the file system (as |
974 | described in the next section). | | 974 | described in the next section). |
975 | When a normal program is executed, the shell runs the program, | | 975 | When a normal program is executed, the shell runs the program, |
976 | passing the arguments and the environment to the program. | | 976 | passing the arguments and the environment to the program. |
977 | If the program is not a normal executable file, and if it does | | 977 | If the program is not a normal executable file, and if it does |
978 | not begin with the "magic number" whose ASCII representation is "#!", so | | 978 | not begin with the "magic number" whose ASCII representation is "#!", so |
979 | .Xr execve 2 | | 979 | .Xr execve 2 |
980 | returns | | 980 | returns |
981 | .Er ENOEXEC | | 981 | .Er ENOEXEC |
982 | then) the shell will interpret the program in a sub-shell. | | 982 | then) the shell will interpret the program in a sub-shell. |
983 | The child shell will reinitialize itself in this case, | | 983 | The child shell will reinitialize itself in this case, |
984 | so that the effect will be as if a | | 984 | so that the effect will be as if a |
985 | new shell had been invoked to handle the ad-hoc shell script, except that | | 985 | new shell had been invoked to handle the ad-hoc shell script, except that |
986 | the location of hashed commands located in the parent shell will be | | 986 | the location of hashed commands located in the parent shell will be |
987 | remembered by the child. | | 987 | remembered by the child. |
988 | .Pp | | 988 | .Pp |
989 | Note that previous versions of this document and the source code itself | | 989 | Note that previous versions of this document and the source code itself |
990 | misleadingly and sporadically refer to a shell script without a magic | | 990 | misleadingly and sporadically refer to a shell script without a magic |
991 | number as a "shell procedure". | | 991 | number as a "shell procedure". |
992 | .Ss Path Search | | 992 | .Ss Path Search |
993 | When locating a command, the shell first looks to see if it has a shell | | 993 | When locating a command, the shell first looks to see if it has a shell |
994 | function by that name. | | 994 | function by that name. |
995 | Then it looks for a built-in command by that name. | | 995 | Then it looks for a built-in command by that name. |
996 | If a built-in command is not found, one of two things happen: | | 996 | If a built-in command is not found, one of two things happen: |
997 | .Bl -enum | | 997 | .Bl -enum |
998 | .It | | 998 | .It |
999 | Command names containing a slash are simply executed without performing | | 999 | Command names containing a slash are simply executed without performing |
1000 | any searches. | | 1000 | any searches. |
1001 | .It | | 1001 | .It |
1002 | Otherwise, the shell searches each entry in | | 1002 | Otherwise, the shell searches each entry in |
1003 | .Ev PATH | | 1003 | .Ev PATH |
1004 | in turn for the command. | | 1004 | in turn for the command. |
1005 | The value of the | | 1005 | The value of the |
1006 | .Ev PATH | | 1006 | .Ev PATH |
1007 | variable should be a series of entries separated by colons. | | 1007 | variable should be a series of entries separated by colons. |
1008 | Each entry consists of a directory name. | | 1008 | Each entry consists of a directory name. |
1009 | The current directory may be indicated | | 1009 | The current directory may be indicated |
1010 | implicitly by an empty directory name, or explicitly by a single period. | | 1010 | implicitly by an empty directory name, or explicitly by a single period. |
1011 | If a directory searched contains an executable file with the same | | 1011 | If a directory searched contains an executable file with the same |
1012 | name as the command given, | | 1012 | name as the command given, |
1013 | the search terminates, and that program is executed. | | 1013 | the search terminates, and that program is executed. |
1014 | .El | | 1014 | .El |
1015 | .Ss Command Exit Status | | 1015 | .Ss Command Exit Status |
1016 | Each command has an exit status that can influence the behavior | | 1016 | Each command has an exit status that can influence the behavior |
1017 | of other shell commands. | | 1017 | of other shell commands. |
1018 | The paradigm is that a command exits | | 1018 | The paradigm is that a command exits |
1019 | with zero in normal cases, or to indicate success, | | 1019 | with zero in normal cases, or to indicate success, |
1020 | and non-zero for failure, | | 1020 | and non-zero for failure, |
1021 | error, or a false indication. | | 1021 | error, or a false indication. |
1022 | The man page for each command | | 1022 | The man page for each command |
1023 | should indicate the various exit codes and what they mean. | | 1023 | should indicate the various exit codes and what they mean. |
1024 | Additionally, the built-in commands return exit codes, as does | | 1024 | Additionally, the built-in commands return exit codes, as does |
1025 | an executed shell function. | | 1025 | an executed shell function. |
1026 | .Pp | | 1026 | .Pp |
1027 | If a command consists entirely of variable assignments then the | | 1027 | If a command consists entirely of variable assignments then the |
1028 | exit status of the command is that of the last command substitution | | 1028 | exit status of the command is that of the last command substitution |
1029 | if any, otherwise 0. | | 1029 | if any, otherwise 0. |
1030 | .Pp | | 1030 | .Pp |
1031 | If redirections are present, and any fail to be correctly performed, | | 1031 | If redirections are present, and any fail to be correctly performed, |
1032 | any command present is not executed, and an exit status of 2 | | 1032 | any command present is not executed, and an exit status of 2 |
1033 | is returned. | | 1033 | is returned. |
1034 | .Ss Complex Commands | | 1034 | .Ss Complex Commands |
1035 | Complex commands are combinations of simple commands with control | | 1035 | Complex commands are combinations of simple commands with control |
1036 | operators or reserved words, together creating a larger complex command. | | 1036 | operators or reserved words, together creating a larger complex command. |
1037 | Overall, a shell program is a: | | 1037 | Overall, a shell program is a: |
1038 | .Bl -tag -width XpipelineX | | 1038 | .Bl -tag -width XpipelineX |
1039 | .It list | | 1039 | .It list |
1040 | Which is a sequence of one or more AND-OR lists. | | 1040 | Which is a sequence of one or more AND-OR lists. |
1041 | .It "AND-OR list" | | 1041 | .It "AND-OR list" |
1042 | is a sequence of one or more pipelines. | | 1042 | is a sequence of one or more pipelines. |
1043 | .It pipeline | | 1043 | .It pipeline |
1044 | is a sequence of one or more commands. | | 1044 | is a sequence of one or more commands. |
1045 | .It command | | 1045 | .It command |
1046 | is one of a simple command, a compound command, or a function definition. | | 1046 | is one of a simple command, a compound command, or a function definition. |
1047 | .It "simple command" | | 1047 | .It "simple command" |
1048 | has been explained above, and is the basic building block. | | 1048 | has been explained above, and is the basic building block. |
1049 | .It "compound command" | | 1049 | .It "compound command" |
1050 | provides mechanisms to group lists to achieve different effects. | | 1050 | provides mechanisms to group lists to achieve different effects. |
1051 | .It "function definition" | | 1051 | .It "function definition" |
1052 | allows new simple commands to be created as groupings of existing commands. | | 1052 | allows new simple commands to be created as groupings of existing commands. |
1053 | .El | | 1053 | .El |
1054 | .Pp | | 1054 | .Pp |
1055 | Unless otherwise stated, the exit status of a list | | 1055 | Unless otherwise stated, the exit status of a list |
1056 | is that of the last simple command executed by the list. | | 1056 | is that of the last simple command executed by the list. |
1057 | .Ss Pipelines | | 1057 | .Ss Pipelines |
1058 | A pipeline is a sequence of one or more commands separated | | 1058 | A pipeline is a sequence of one or more commands separated |
1059 | by the control operator | | 1059 | by the control operator |
1060 | .Sq \&| , | | 1060 | .Sq \&| , |
1061 | and optionally preceded by the | | 1061 | and optionally preceded by the |
1062 | .Dq \&! | | 1062 | .Dq \&! |
1063 | reserved word. | | 1063 | reserved word. |
1064 | Note that | | 1064 | Note that |
1065 | .Sq \&| | | 1065 | .Sq \&| |
1066 | is an operator, and so is recognized anywhere it appears unquoted, | | 1066 | is an operator, and so is recognized anywhere it appears unquoted, |
1067 | it does not require surrounding white space or other syntax elements. | | 1067 | it does not require surrounding white space or other syntax elements. |
1068 | On the other hand | | 1068 | On the other hand |
1069 | .Dq \&! | | 1069 | .Dq \&! |
1070 | being a reserved word, must be separated from adjacent words by | | 1070 | being a reserved word, must be separated from adjacent words by |
1071 | white space (or other operators, perhaps redirects) and is only | | 1071 | white space (or other operators, perhaps redirects) and is only |
1072 | recognized as the reserved word when it appears in a command word | | 1072 | recognized as the reserved word when it appears in a command word |
1073 | position (such as at the beginning of a pipeline.) | | 1073 | position (such as at the beginning of a pipeline.) |
1074 | .Pp | | 1074 | .Pp |
1075 | The standard output of all but | | 1075 | The standard output of all but |
1076 | the last command in the sequence is connected to the standard input | | 1076 | the last command in the sequence is connected to the standard input |
1077 | of the next command. | | 1077 | of the next command. |
1078 | The standard output of the last | | 1078 | The standard output of the last |
1079 | command is inherited from the shell, as usual, | | 1079 | command is inherited from the shell, as usual, |
1080 | as is the standard input of the first command. | | 1080 | as is the standard input of the first command. |
1081 | .Pp | | 1081 | .Pp |
1082 | The format for a pipeline is: | | 1082 | The format for a pipeline is: |
1083 | .Pp | | 1083 | .Pp |
1084 | .Dl [!] command1 [ | command2 ...] | | 1084 | .Dl [!] command1 [ \&| command2 ...] |
1085 | .Pp | | 1085 | .Pp |
1086 | The standard output of command1 is connected to the standard input of | | 1086 | The standard output of command1 is connected to the standard input of |
1087 | command2. | | 1087 | command2. |
1088 | The standard input, standard output, or both of each command is | | 1088 | The standard input, standard output, or both of each command is |
1089 | considered to be assigned by the pipeline before any redirection specified | | 1089 | considered to be assigned by the pipeline before any redirection specified |
1090 | by redirection operators that are part of the command are performed. | | 1090 | by redirection operators that are part of the command are performed. |
1091 | .Pp | | 1091 | .Pp |
1092 | If the pipeline is not in the background (discussed later), the shell | | 1092 | If the pipeline is not in the background (discussed later), the shell |
1093 | waits for all commands to complete. | | 1093 | waits for all commands to complete. |
1094 | .Pp | | 1094 | .Pp |
1095 | The commands in a pipeline can either be simple commands, | | 1095 | The commands in a pipeline can either be simple commands, |
1096 | or one of the compound commands described below. | | 1096 | or one of the compound commands described below. |
1097 | The simplest case of a pipeline is a single simple command. | | 1097 | The simplest case of a pipeline is a single simple command. |
1098 | .Pp | | 1098 | .Pp |
1099 | If the | | 1099 | If the |
1100 | .Ic pipefail | | 1100 | .Ic pipefail |
1101 | option is set when the pipeline completes and its status is | | 1101 | option is set when the pipeline completes and its status is |
1102 | collected, the pipeline status is the status of | | 1102 | collected, the pipeline status is the status of |
1103 | the last (rightmost) command in the pipeline to exit with non-zero exit | | 1103 | the last (rightmost) command in the pipeline to exit with non-zero exit |
1104 | status, or zero, if, and only if, all commands in the pipeline | | 1104 | status, or zero, if, and only if, all commands in the pipeline |
1105 | exited with a status of zero. | | 1105 | exited with a status of zero. |
1106 | If the | | 1106 | If the |
1107 | .Ic pipefail | | 1107 | .Ic pipefail |
1108 | option is not set, which is the default state, | | 1108 | option is not set, which is the default state, |
1109 | the pipeline status is the exit | | 1109 | the pipeline status is the exit |
1110 | status of the last command in the pipeline, | | 1110 | status of the last command in the pipeline, |
1111 | and the exit status of any other commands in the pipeline is ignored. | | 1111 | and the exit status of any other commands in the pipeline is ignored. |
1112 | .Pp | | 1112 | .Pp |
1113 | If the reserved word ! precedes the pipeline, the exit status | | 1113 | If the reserved word ! precedes the pipeline, the exit status |
1114 | becomes the logical NOT of the pipeline status as determined above. | | 1114 | becomes the logical NOT of the pipeline status as determined above. |
1115 | That is, if the pipeline status is zero, the exit status is 1; | | 1115 | That is, if the pipeline status is zero, the exit status is 1; |
1116 | if the pipeline status is other than zero, the exit status is zero. | | 1116 | if the pipeline status is other than zero, the exit status is zero. |
1117 | If there is no ! reserved word, the pipeline status becomes the exit status. | | 1117 | If there is no ! reserved word, the pipeline status becomes the exit status. |
1118 | .Pp | | 1118 | .Pp |
1119 | Because pipeline assignment of standard input or standard output or both | | 1119 | Because pipeline assignment of standard input or standard output or both |
1120 | takes place before redirection, it can be modified by redirection. | | 1120 | takes place before redirection, it can be modified by redirection. |
1121 | For example: | | 1121 | For example: |
1122 | .Pp | | 1122 | .Pp |
1123 | .Dl $ command1 2>&1 | command2 | | 1123 | .Dl $ command1 2>&1 \&| command2 |
1124 | .Pp | | 1124 | .Pp |
1125 | sends both the standard output and standard error of command1 | | 1125 | sends both the standard output and standard error of command1 |
1126 | to the standard input of command2. | | 1126 | to the standard input of command2. |
1127 | .Pp | | 1127 | .Pp |
1128 | Note that unlike some other shells, each process in the pipeline is a | | 1128 | Note that unlike some other shells, each process in the pipeline is a |
1129 | child of the invoking shell (unless it is a shell built-in, in which case | | 1129 | child of the invoking shell (unless it is a shell built-in, in which case |
1130 | it executes in the current shell -- but any effect it has on the | | 1130 | it executes in the current shell -- but any effect it has on the |
1131 | environment is wiped). | | 1131 | environment is wiped). |
1132 | .Pp | | 1132 | .Pp |
1133 | A pipeline is a simple case of an AND-OR-list (described below.) | | 1133 | A pipeline is a simple case of an AND-OR-list (described below.) |
1134 | A ; or | | 1134 | A ; or |
1135 | .Aq newline | | 1135 | .Aq newline |
1136 | terminator causes the preceding pipeline, or more generally, | | 1136 | terminator causes the preceding pipeline, or more generally, |
1137 | the preceding AND-OR-list to be executed sequentially; | | 1137 | the preceding AND-OR-list to be executed sequentially; |
1138 | that is, the shell executes the commands, and waits for them | | 1138 | that is, the shell executes the commands, and waits for them |
1139 | to finish before proceeding to following commands. | | 1139 | to finish before proceeding to following commands. |
1140 | An & terminator causes asynchronous (background) execution | | 1140 | An & terminator causes asynchronous (background) execution |
1141 | of the preceding AND-OR-list (see the next paragraph below). | | 1141 | of the preceding AND-OR-list (see the next paragraph below). |
1142 | The exit status of an asynchronous AND-OR-list is zero. | | 1142 | The exit status of an asynchronous AND-OR-list is zero. |
1143 | The actual status of the commands, | | 1143 | The actual status of the commands, |
1144 | after they have completed, | | 1144 | after they have completed, |
1145 | can be obtained using the | | 1145 | can be obtained using the |
1146 | .Ic wait | | 1146 | .Ic wait |
1147 | built-in command described later. | | 1147 | built-in command described later. |
1148 | .Ss Background Commands -- & | | 1148 | .Ss Background Commands -- & |
1149 | If a command, pipeline, or AND-OR-list | | 1149 | If a command, pipeline, or AND-OR-list |
1150 | is terminated by the control operator ampersand (&), the | | 1150 | is terminated by the control operator ampersand (&), the |
1151 | shell executes the command asynchronously -- that is, the shell does not | | 1151 | shell executes the command asynchronously -- that is, the shell does not |
1152 | wait for the command to finish before executing the next command. | | 1152 | wait for the command to finish before executing the next command. |
1153 | .Pp | | 1153 | .Pp |
1154 | The format for running a command in background is: | | 1154 | The format for running a command in background is: |
1155 | .Pp | | 1155 | .Pp |
1156 | .Dl command1 & [command2 & ...] | | 1156 | .Dl command1 & [command2 & ...] |
1157 | .Pp | | 1157 | .Pp |
1158 | If the shell is not interactive, the standard input of an asynchronous | | 1158 | If the shell is not interactive, the standard input of an asynchronous |
1159 | command is set to | | 1159 | command is set to |
1160 | .Pa /dev/null . | | 1160 | .Pa /dev/null . |
1161 | The process identifier of the most recent command started in the | | 1161 | The process identifier of the most recent command started in the |
1162 | background can be obtained from the value of the special parameter | | 1162 | background can be obtained from the value of the special parameter |
1163 | .Dq \&! | | 1163 | .Dq \&! |
1164 | (see | | 1164 | (see |
1165 | .Sx Special Parameters ) | | 1165 | .Sx Special Parameters ) |
1166 | provided it is accessed before the next asynchronous command is started. | | 1166 | provided it is accessed before the next asynchronous command is started. |
1167 | .Ss Lists -- Generally Speaking | | 1167 | .Ss Lists -- Generally Speaking |
1168 | A list is a sequence of one or more commands separated by newlines, | | 1168 | A list is a sequence of one or more commands separated by newlines, |
1169 | semicolons, or ampersands, and optionally terminated by one of these three | | 1169 | semicolons, or ampersands, and optionally terminated by one of these three |
1170 | characters. | | 1170 | characters. |
1171 | A shell program, which includes the commands given to an | | 1171 | A shell program, which includes the commands given to an |
1172 | interactive shell, is a list. | | 1172 | interactive shell, is a list. |
1173 | Each command in such a list is executed when it is fully parsed. | | 1173 | Each command in such a list is executed when it is fully parsed. |
1174 | Another use of a list is as a complete-command, | | 1174 | Another use of a list is as a complete-command, |
1175 | which is parsed in its entirety, and then later the commands in | | 1175 | which is parsed in its entirety, and then later the commands in |
1176 | the list are executed only if there were no parsing errors. | | 1176 | the list are executed only if there were no parsing errors. |
1177 | .Pp | | 1177 | .Pp |
1178 | The commands in a list are executed in the order they are written. | | 1178 | The commands in a list are executed in the order they are written. |
1179 | If command is followed by an ampersand, the shell starts the | | 1179 | If command is followed by an ampersand, the shell starts the |
1180 | command and immediately proceeds to the next command; otherwise it waits | | 1180 | command and immediately proceeds to the next command; otherwise it waits |
1181 | for the command to terminate before proceeding to the next one. | | 1181 | for the command to terminate before proceeding to the next one. |
1182 | A newline is equivalent to a | | 1182 | A newline is equivalent to a |
1183 | .Sq \&; | | 1183 | .Sq \&; |
1184 | when no other operator is present, and the command being input | | 1184 | when no other operator is present, and the command being input |
1185 | could syntactically correctly be terminated at the point where | | 1185 | could syntactically correctly be terminated at the point where |
1186 | the newline is encountered, otherwise it is just whitespace. | | 1186 | the newline is encountered, otherwise it is just whitespace. |
1187 | .Ss AND-OR Lists (Short-Circuit List Operators) | | 1187 | .Ss AND-OR Lists (Short-Circuit List Operators) |
1188 | .Dq && | | 1188 | .Dq && |
1189 | and | | 1189 | and |
1190 | .Dq || | | 1190 | .Dq || |
1191 | are AND-OR list operators. | | 1191 | are AND-OR list operators. |
1192 | After executing the commands that precede the | | 1192 | After executing the commands that precede the |
1193 | .Dq && | | 1193 | .Dq && |
1194 | the subsequent command is executed | | 1194 | the subsequent command is executed |
1195 | if and only if the exit status of the preceding command(s) is zero. | | 1195 | if and only if the exit status of the preceding command(s) is zero. |
1196 | .Dq || | | 1196 | .Dq || |
1197 | is similar, but executes the subsequent command if and only if the exit status | | 1197 | is similar, but executes the subsequent command if and only if the exit status |
1198 | of the preceding command is nonzero. | | 1198 | of the preceding command is nonzero. |
1199 | If a command is not executed, the exit status remains unchanged | | 1199 | If a command is not executed, the exit status remains unchanged |
1200 | and the following AND-OR list operator (if any) uses that status. | | 1200 | and the following AND-OR list operator (if any) uses that status. |
1201 | .Dq && | | 1201 | .Dq && |
1202 | and | | 1202 | and |
1203 | .Dq || | | 1203 | .Dq || |
1204 | both have the same priority. | | 1204 | both have the same priority. |
1205 | Note that these operators are left-associative, so | | 1205 | Note that these operators are left-associative, so |
1206 | .Dl true || echo bar && echo baz | | 1206 | .Dl true || echo bar && echo baz |
1207 | writes | | 1207 | writes |
1208 | .Dq baz | | 1208 | .Dq baz |
1209 | and nothing else. | | 1209 | and nothing else. |
1210 | This is not the way it works in C. | | 1210 | This is not the way it works in C. |
1211 | .Ss Flow-Control Constructs -- if, while, until, for, case | | 1211 | .Ss Flow-Control Constructs -- if, while, until, for, case |
1212 | These commands are instances of compound commands. | | 1212 | These commands are instances of compound commands. |
1213 | The syntax of the | | 1213 | The syntax of the |
1214 | .Ic if | | 1214 | .Ic if |
1215 | command is | | 1215 | command is |
1216 | .Bd -literal -offset indent | | 1216 | .Bd -literal -offset indent |
1217 | if list | | 1217 | if list |
1218 | then list | | 1218 | then list |
1219 | [ elif list | | 1219 | [ elif list |
1220 | then list ] ... | | 1220 | then list ] ... |
1221 | [ else list ] | | 1221 | [ else list ] |
1222 | fi | | 1222 | fi |
1223 | .Ed | | 1223 | .Ed |
1224 | The first list is executed, and if the exit status of that list is zero, | | 1224 | The first list is executed, and if the exit status of that list is zero, |
1225 | the list following the | | 1225 | the list following the |
1226 | .Ic then | | 1226 | .Ic then |
1227 | is executed. | | 1227 | is executed. |
1228 | Otherwise the list after an | | 1228 | Otherwise the list after an |
1229 | .Ic elif | | 1229 | .Ic elif |
1230 | (if any) is executed and the process repeats. | | 1230 | (if any) is executed and the process repeats. |
1231 | When no more | | 1231 | When no more |
1232 | .Ic elif | | 1232 | .Ic elif |
1233 | reserved words, and accompanying lists, appear, | | 1233 | reserved words, and accompanying lists, appear, |
1234 | the list after the | | 1234 | the list after the |
1235 | .Ic else | | 1235 | .Ic else |
1236 | reserved word, if any, is executed. | | 1236 | reserved word, if any, is executed. |
1237 | .Pp | | 1237 | .Pp |
1238 | The syntax of the | | 1238 | The syntax of the |
1239 | .Ic while | | 1239 | .Ic while |
1240 | command is | | 1240 | command is |
1241 | .Bd -literal -offset indent | | 1241 | .Bd -literal -offset indent |
1242 | while list | | 1242 | while list |
1243 | do list | | 1243 | do list |
1244 | done | | 1244 | done |
1245 | .Ed | | 1245 | .Ed |
1246 | .Pp | | 1246 | .Pp |
1247 | The two lists are executed repeatedly while the exit status of the | | 1247 | The two lists are executed repeatedly while the exit status of the |
1248 | first list is zero. | | 1248 | first list is zero. |
1249 | The | | 1249 | The |
1250 | .Ic until | | 1250 | .Ic until |
1251 | command is similar, but has the word | | 1251 | command is similar, but has the word |
1252 | .Ic until | | 1252 | .Ic until |
1253 | in place of | | 1253 | in place of |
1254 | .Ic while , | | 1254 | .Ic while , |
1255 | which causes it to repeat until the exit status of the first list is zero. | | 1255 | which causes it to repeat until the exit status of the first list is zero. |
1256 | .Pp | | 1256 | .Pp |
1257 | The syntax of the | | 1257 | The syntax of the |
1258 | .Ic for | | 1258 | .Ic for |
1259 | command is | | 1259 | command is |
1260 | .Bd -literal -offset indent | | 1260 | .Bd -literal -offset indent |
1261 | for variable [ in word ... ] | | 1261 | for variable [ in word ... ] |
1262 | do list | | 1262 | do list |
1263 | done | | 1263 | done |
1264 | .Ed | | 1264 | .Ed |
1265 | .Pp | | 1265 | .Pp |
1266 | The words are expanded, or "$@" if | | 1266 | The words are expanded, or "$@" if |
1267 | .Dq in | | 1267 | .Dq in |
1268 | (and the following words) is not present, | | 1268 | (and the following words) is not present, |
1269 | and then the list is executed repeatedly with the | | 1269 | and then the list is executed repeatedly with the |
1270 | variable set to each word in turn. | | 1270 | variable set to each word in turn. |
1271 | If | | 1271 | If |
1272 | .Dq in | | 1272 | .Dq in |
1273 | appears after the variable, but no words are | | 1273 | appears after the variable, but no words are |
1274 | present, the list is not executed, and the exit status is zero. | | 1274 | present, the list is not executed, and the exit status is zero. |
1275 | .Ic do | | 1275 | .Ic do |
1276 | and | | 1276 | and |
1277 | .Ic done | | 1277 | .Ic done |
1278 | may be replaced with | | 1278 | may be replaced with |
1279 | .Sq Ic \&{ | | 1279 | .Sq Ic \&{ |
1280 | and | | 1280 | and |
1281 | .Sq Ic \&} , | | 1281 | .Sq Ic \&} , |
1282 | but doing so is non-standard and not recommended. | | 1282 | but doing so is non-standard and not recommended. |
1283 | .Pp | | 1283 | .Pp |
1284 | The syntax of the | | 1284 | The syntax of the |
1285 | .Ic break | | 1285 | .Ic break |
1286 | and | | 1286 | and |
1287 | .Ic continue | | 1287 | .Ic continue |
1288 | commands is | | 1288 | commands is |
1289 | .Bd -literal -offset indent | | 1289 | .Bd -literal -offset indent |
1290 | break [ num ] | | 1290 | break [ num ] |
1291 | continue [ num ] | | 1291 | continue [ num ] |
1292 | .Ed | | 1292 | .Ed |
1293 | .Pp | | 1293 | .Pp |
1294 | .Ic break | | 1294 | .Ic break |
1295 | terminates the | | 1295 | terminates the |
1296 | .Ar num | | 1296 | .Ar num |
1297 | innermost | | 1297 | innermost |
1298 | .Ic for , while , | | 1298 | .Ic for , while , |
1299 | or | | 1299 | or |
1300 | .Ic until | | 1300 | .Ic until |
1301 | loops. | | 1301 | loops. |
1302 | .Ic continue | | 1302 | .Ic continue |
1303 | breaks execution of the | | 1303 | breaks execution of the |
1304 | .Ar num\-1 | | 1304 | .Ar num\-1 |
1305 | innermost | | 1305 | innermost |
1306 | .Ic for , while , | | 1306 | .Ic for , while , |
1307 | or | | 1307 | or |
1308 | .Ic until | | 1308 | .Ic until |
1309 | loops, and then continues with the next iteration of the enclosing loop. | | 1309 | loops, and then continues with the next iteration of the enclosing loop. |
1310 | These are implemented as special built-in commands. | | 1310 | These are implemented as special built-in commands. |
1311 | The parameter | | 1311 | The parameter |
1312 | .Ar num , | | 1312 | .Ar num , |
1313 | if given, must be an unsigned positive integer (greater than zero). | | 1313 | if given, must be an unsigned positive integer (greater than zero). |
1314 | If not given, 1 is used. | | 1314 | If not given, 1 is used. |
1315 | .Pp | | 1315 | .Pp |
1316 | The syntax of the | | 1316 | The syntax of the |
1317 | .Ic case | | 1317 | .Ic case |
1318 | command is | | 1318 | command is |
1319 | .Bd -literal -offset indent | | 1319 | .Bd -literal -offset indent |
1320 | case word in | | 1320 | case word in |
1321 | [(] pattern ) [ list ] ;& | | 1321 | [(] pattern ) [ list ] ;& |
1322 | [(] pattern ) [ list ] ;; | | 1322 | [(] pattern ) [ list ] ;; |
1323 | \&... | | 1323 | \&... |
1324 | esac | | 1324 | esac |
1325 | .Ed | | 1325 | .Ed |
1326 | .Pp | | 1326 | .Pp |
1327 | The pattern can actually be one or more patterns (see | | 1327 | The pattern can actually be one or more patterns (see |
1328 | .Sx Shell Patterns | | 1328 | .Sx Shell Patterns |
1329 | described later), separated by | | 1329 | described later), separated by |
1330 | .Dq \*(Ba | | 1330 | .Dq \*(Ba |
1331 | characters. | | 1331 | characters. |
1332 | .Pp | | 1332 | .Pp |
1333 | Word is expanded and matched against each pattern in turn, | | 1333 | Word is expanded and matched against each pattern in turn, |
1334 | from first to last, | | 1334 | from first to last, |
1335 | with each pattern being expanded just before the match is attempted. | | 1335 | with each pattern being expanded just before the match is attempted. |
1336 | When a match is found, pattern comparisons cease, and the associated | | 1336 | When a match is found, pattern comparisons cease, and the associated |
1337 | .Dq list , | | 1337 | .Dq list , |
1338 | if given, | | 1338 | if given, |
1339 | is evaluated. | | 1339 | is evaluated. |
1340 | If the list is terminated with | | 1340 | If the list is terminated with |
1341 | .Dq \&;& | | 1341 | .Dq \&;& |
1342 | execution then falls through to the following list, if any, | | 1342 | execution then falls through to the following list, if any, |
1343 | without evaluating its pattern, or attempting a match. | | 1343 | without evaluating its pattern, or attempting a match. |
1344 | When a list terminated with | | 1344 | When a list terminated with |
1345 | .Dq \&;; | | 1345 | .Dq \&;; |
1346 | has been executed, or when | | 1346 | has been executed, or when |
1347 | .Ic esac | | 1347 | .Ic esac |
1348 | is reached, execution of the | | 1348 | is reached, execution of the |
1349 | .Ic case | | 1349 | .Ic case |
1350 | statement is complete. | | 1350 | statement is complete. |
1351 | The exit status is that of the last command executed | | 1351 | The exit status is that of the last command executed |
1352 | from the last list evaluated, if any, or zero otherwise. | | 1352 | from the last list evaluated, if any, or zero otherwise. |
1353 | .Ss Grouping Commands Together | | 1353 | .Ss Grouping Commands Together |
1354 | Commands may be grouped by writing either | | 1354 | Commands may be grouped by writing either |
1355 | .Dl (list) | | 1355 | .Dl (list) |
1356 | or | | 1356 | or |
1357 | .Dl { list; } | | 1357 | .Dl { list; } |
1358 | These also form compound commands. | | 1358 | These also form compound commands. |
1359 | .Pp | | 1359 | .Pp |
1360 | Note that while parentheses are operators, and do not require | | 1360 | Note that while parentheses are operators, and do not require |
1361 | any extra syntax, braces are reserved words, so the opening brace | | 1361 | any extra syntax, braces are reserved words, so the opening brace |
1362 | must be followed by white space (or some other operator), and the | | 1362 | must be followed by white space (or some other operator), and the |
1363 | closing brace must occur in a position where a new command word might | | 1363 | closing brace must occur in a position where a new command word might |
1364 | otherwise appear. | | 1364 | otherwise appear. |
1365 | .Pp | | 1365 | .Pp |
1366 | The first of these executes the commands in a sub-shell. | | 1366 | The first of these executes the commands in a sub-shell. |
1367 | Built-in commands grouped into a (list) will not affect the current shell. | | 1367 | Built-in commands grouped into a (list) will not affect the current shell. |
1368 | The second form does not fork another shell so is slightly more efficient, | | 1368 | The second form does not fork another shell so is slightly more efficient, |
1369 | and allows for commands which do affect the current shell. | | 1369 | and allows for commands which do affect the current shell. |
1370 | Grouping commands together this way allows you to redirect | | 1370 | Grouping commands together this way allows you to redirect |
1371 | their output as though they were one program: | | 1371 | their output as though they were one program: |
1372 | .Bd -literal -offset indent | | 1372 | .Bd -literal -offset indent |
1373 | { echo -n \*qhello \*q ; echo \*qworld\*q ; } > greeting | | 1373 | { echo -n \*qhello \*q ; echo \*qworld\*q ; } > greeting |
1374 | .Ed | | 1374 | .Ed |
1375 | .Pp | | 1375 | .Pp |
1376 | Note that | | 1376 | Note that |
1377 | .Dq } | | 1377 | .Dq } |
1378 | must follow a control operator (here, | | 1378 | must follow a control operator (here, |
1379 | .Dq \&; ) | | 1379 | .Dq \&; ) |
1380 | so that it is recognized as a reserved word and not as another command argument. | | 1380 | so that it is recognized as a reserved word and not as another command argument. |
1381 | .Ss Functions | | 1381 | .Ss Functions |
1382 | The syntax of a function definition is | | 1382 | The syntax of a function definition is |
1383 | .Pp | | 1383 | .Pp |
1384 | .Dl name ( ) command [ redirect... ] | | 1384 | .Dl name ( ) command [ redirect... ] |
1385 | .Pp | | 1385 | .Pp |
1386 | A function definition is an executable statement; when executed it | | 1386 | A function definition is an executable statement; when executed it |
1387 | installs a function named name and returns an exit status of zero. | | 1387 | installs a function named name and returns an exit status of zero. |
1388 | The command is normally a list enclosed between | | 1388 | The command is normally a list enclosed between |
1389 | .Dq { | | 1389 | .Dq { |
1390 | and | | 1390 | and |
1391 | .Dq } . | | 1391 | .Dq } . |
1392 | The standard syntax also allows the command to be any of the other | | 1392 | The standard syntax also allows the command to be any of the other |
1393 | compound commands, including a sub-shell, all of which are supported. | | 1393 | compound commands, including a sub-shell, all of which are supported. |
1394 | As an extension, this shell also allows a simple command | | 1394 | As an extension, this shell also allows a simple command |
1395 | (or even another function definition) to be | | 1395 | (or even another function definition) to be |
1396 | used, though users should be aware this is non-standard syntax. | | 1396 | used, though users should be aware this is non-standard syntax. |
1397 | This means that | | 1397 | This means that |
1398 | .Dl l() ls "$@" | | 1398 | .Dl l() ls "$@" |
1399 | works to make | | 1399 | works to make |
1400 | .Dq l | | 1400 | .Dq l |
1401 | an alternative name for the | | 1401 | an alternative name for the |
1402 | .Ic ls | | 1402 | .Ic ls |
1403 | command. | | 1403 | command. |
1404 | .Pp | | 1404 | .Pp |
1405 | If the optional redirect, (see | | 1405 | If the optional redirect, (see |
1406 | .Sx Redirections ) , | | 1406 | .Sx Redirections ) , |
1407 | which may be of any of the normal forms, | | 1407 | which may be of any of the normal forms, |
1408 | is given, it is applied each time the | | 1408 | is given, it is applied each time the |
1409 | function is called. | | 1409 | function is called. |
1410 | This means that a simple | | 1410 | This means that a simple |
1411 | .Dq Hello World | | 1411 | .Dq Hello World |
1412 | function might be written (in the extended syntax) as: | | 1412 | function might be written (in the extended syntax) as: |
1413 | .Bd -literal -offset indent | | 1413 | .Bd -literal -offset indent |
1414 | hello() cat <<EOF | | 1414 | hello() cat <<EOF |
1415 | Hello World! | | 1415 | Hello World! |
1416 | EOF | | 1416 | EOF |
1417 | .Ed | | 1417 | .Ed |
1418 | .Pp | | 1418 | .Pp |
1419 | To be correctly standards conforming this should be re-written as: | | 1419 | To be correctly standards conforming this should be re-written as: |
1420 | .Bd -literal -offset indent | | 1420 | .Bd -literal -offset indent |
1421 | hello() { cat; } <<EOF | | 1421 | hello() { cat; } <<EOF |
1422 | Hello World! | | 1422 | Hello World! |
1423 | EOF | | 1423 | EOF |
1424 | .Ed | | 1424 | .Ed |
1425 | .Pp | | 1425 | .Pp |
1426 | Note the distinction between those forms, and | | 1426 | Note the distinction between those forms, and |
1427 | .Bd -literal -offset indent | | 1427 | .Bd -literal -offset indent |
1428 | hello() { cat <<EOF | | 1428 | hello() { cat <<EOF |
1429 | Hello World! | | 1429 | Hello World! |
1430 | EOF | | 1430 | EOF |
1431 | \&} | | 1431 | \&} |
1432 | .Ed | | 1432 | .Ed |
1433 | .Pp | | 1433 | .Pp |
1434 | which reads and processes the | | 1434 | which reads and processes the |
1435 | .Ic here document | | 1435 | .Ic here document |
1436 | each time the shell executes the function, and which applies | | 1436 | each time the shell executes the function, and which applies |
1437 | that input only to the cat command, not to any other commands | | 1437 | that input only to the cat command, not to any other commands |
1438 | that might appear in the function. | | 1438 | that might appear in the function. |
1439 | .Pp | | 1439 | .Pp |
1440 | Variables may be declared to be local to a function by using the | | 1440 | Variables may be declared to be local to a function by using the |
1441 | .Ic local | | 1441 | .Ic local |
1442 | command. | | 1442 | command. |
1443 | This should usually appear as the first statement of a function, | | 1443 | This should usually appear as the first statement of a function, |
1444 | though | | 1444 | though |
1445 | .Ic local | | 1445 | .Ic local |
1446 | is an executable command which can be used anywhere in a function. | | 1446 | is an executable command which can be used anywhere in a function. |
1447 | See | | 1447 | See |
1448 | .Sx Built-ins | | 1448 | .Sx Built-ins |
1449 | below for its definition. | | 1449 | below for its definition. |
1450 | .Pp | | 1450 | .Pp |
1451 | The function completes after having executed | | 1451 | The function completes after having executed |
1452 | .Ar command | | 1452 | .Ar command |
1453 | with exit status set to the status returned by | | 1453 | with exit status set to the status returned by |
1454 | .Ar command . | | 1454 | .Ar command . |
1455 | If | | 1455 | If |
1456 | .Ar command | | 1456 | .Ar command |
1457 | is a compound-command | | 1457 | is a compound-command |
1458 | it can use the | | 1458 | it can use the |
1459 | .Ic return | | 1459 | .Ic return |
1460 | command (see | | 1460 | command (see |
1461 | .Sx Built-ins | | 1461 | .Sx Built-ins |
1462 | below) | | 1462 | below) |
1463 | to finish before completing all of | | 1463 | to finish before completing all of |
1464 | .Ar command . | | 1464 | .Ar command . |
1465 | .Ss Variables and Parameters | | 1465 | .Ss Variables and Parameters |
1466 | The shell maintains a set of parameters. | | 1466 | The shell maintains a set of parameters. |
1467 | A parameter denoted by a name is called a variable. | | 1467 | A parameter denoted by a name is called a variable. |
1468 | When starting up, the shell turns all the environment | | 1468 | When starting up, the shell turns all the environment |
1469 | variables into shell variables, and exports them. | | 1469 | variables into shell variables, and exports them. |
1470 | New variables can be set using the form | | 1470 | New variables can be set using the form |
1471 | .Pp | | 1471 | .Pp |
1472 | .Dl name=value | | 1472 | .Dl name=value |
1473 | .Pp | | 1473 | .Pp |
1474 | Variables set by the user must have a name consisting solely of | | 1474 | Variables set by the user must have a name consisting solely of |
1475 | alphabetics, numerics, and underscores - the first of which must not be | | 1475 | alphabetics, numerics, and underscores - the first of which must not be |
1476 | numeric. | | 1476 | numeric. |
1477 | A parameter can also be denoted by a number or a special | | 1477 | A parameter can also be denoted by a number or a special |
1478 | character as explained below. | | 1478 | character as explained below. |
1479 | .Ss Positional Parameters | | 1479 | .Ss Positional Parameters |
1480 | A positional parameter is a parameter denoted by a number (n > 0). | | 1480 | A positional parameter is a parameter denoted by a number (n > 0). |
1481 | The shell sets these initially to the values of its command line arguments | | 1481 | The shell sets these initially to the values of its command line arguments |
1482 | that follow the name of the shell script. | | 1482 | that follow the name of the shell script. |
1483 | The | | 1483 | The |
1484 | .Ic set | | 1484 | .Ic set |
1485 | built-in can also be used to set or reset them, and | | 1485 | built-in can also be used to set or reset them, and |
1486 | .Ic shift | | 1486 | .Ic shift |
1487 | can be used to manipulate the list. | | 1487 | can be used to manipulate the list. |
1488 | .Pp | | 1488 | .Pp |
1489 | To refer to the 10th (and later) positional parameters, | | 1489 | To refer to the 10th (and later) positional parameters, |
1490 | the form ${n} must be used. | | 1490 | the form ${n} must be used. |
1491 | Without the braces, a digit following | | 1491 | Without the braces, a digit following |
1492 | .Dq $ | | 1492 | .Dq $ |
1493 | can only refer to one of the first 9 positional parameters, | | 1493 | can only refer to one of the first 9 positional parameters, |
1494 | or the special parameter | | 1494 | or the special parameter |
1495 | .Dq 0 . | | 1495 | .Dq 0 . |
1496 | The word | | 1496 | The word |
1497 | .Dq $10 | | 1497 | .Dq $10 |
1498 | is treated identically to | | 1498 | is treated identically to |
1499 | .Dq ${1}0 . | | 1499 | .Dq ${1}0 . |
1500 | .Ss Special Parameters | | 1500 | .Ss Special Parameters |
1501 | A special parameter is a parameter denoted by one of the following special | | 1501 | A special parameter is a parameter denoted by one of the following special |
1502 | characters. | | 1502 | characters. |
1503 | The value of the parameter is listed next to its character. | | 1503 | The value of the parameter is listed next to its character. |
1504 | .Bl -tag -width thinhyphena | | 1504 | .Bl -tag -width thinhyphena |
1505 | .It * | | 1505 | .It * |
1506 | Expands to the positional parameters, starting from one. | | 1506 | Expands to the positional parameters, starting from one. |
1507 | When the | | 1507 | When the |
1508 | expansion occurs within a double-quoted string it expands to a single | | 1508 | expansion occurs within a double-quoted string it expands to a single |
1509 | field with the value of each parameter separated by the first character of | | 1509 | field with the value of each parameter separated by the first character of |
1510 | the | | 1510 | the |
1511 | .Ev IFS | | 1511 | .Ev IFS |
1512 | variable, or by a | | 1512 | variable, or by a |
1513 | .Aq space | | 1513 | .Aq space |
1514 | if | | 1514 | if |
1515 | .Ev IFS | | 1515 | .Ev IFS |
1516 | is unset. | | 1516 | is unset. |
1517 | .It @ | | 1517 | .It @ |
1518 | Expands to the positional parameters, starting from one. | | 1518 | Expands to the positional parameters, starting from one. |
1519 | When the expansion occurs within double quotes, each positional | | 1519 | When the expansion occurs within double quotes, each positional |
1520 | parameter expands as a separate argument. | | 1520 | parameter expands as a separate argument. |
1521 | If there are no positional parameters, the | | 1521 | If there are no positional parameters, the |
1522 | expansion of @ generates zero arguments, even when @ is | | 1522 | expansion of @ generates zero arguments, even when @ is |
1523 | double-quoted. | | 1523 | double-quoted. |
1524 | What this basically means, for example, is | | 1524 | What this basically means, for example, is |
1525 | if $1 is | | 1525 | if $1 is |
1526 | .Dq abc | | 1526 | .Dq abc |
1527 | and $2 is | | 1527 | and $2 is |
1528 | .Dq def ghi , | | 1528 | .Dq def ghi , |
1529 | then | | 1529 | then |
1530 | .Qq $@ | | 1530 | .Qq $@ |
1531 | expands to | | 1531 | expands to |
1532 | the two arguments: | | 1532 | the two arguments: |
1533 | .Pp | | 1533 | .Pp |
1534 | .Sm off | | 1534 | .Sm off |
1535 | .Dl \*q abc \*q \ \*q def\ ghi \*q | | 1535 | .Dl \*q abc \*q \ \*q def\ ghi \*q |
1536 | .Sm on | | 1536 | .Sm on |
1537 | .It # | | 1537 | .It # |
1538 | Expands to the number of positional parameters. | | 1538 | Expands to the number of positional parameters. |
1539 | .It \&? | | 1539 | .It \&? |
1540 | Expands to the exit status of the most recent pipeline. | | 1540 | Expands to the exit status of the most recent pipeline. |
1541 | .It \- (Hyphen, or minus.) | | 1541 | .It \- (Hyphen, or minus.) |
1542 | Expands to the current option flags (the single-letter | | 1542 | Expands to the current option flags (the single-letter |
1543 | option names concatenated into a string) as specified on | | 1543 | option names concatenated into a string) as specified on |
1544 | invocation, by the set built-in command, or implicitly | | 1544 | invocation, by the set built-in command, or implicitly |
1545 | by the shell. | | 1545 | by the shell. |
1546 | .It $ | | 1546 | .It $ |
1547 | Expands to the process ID of the invoked shell. | | 1547 | Expands to the process ID of the invoked shell. |
1548 | A sub-shell retains the same value of $ as its parent. | | 1548 | A sub-shell retains the same value of $ as its parent. |
1549 | .It \&! | | 1549 | .It \&! |
1550 | Expands to the process ID of the most recent background | | 1550 | Expands to the process ID of the most recent background |
1551 | command executed from the current shell. | | 1551 | command executed from the current shell. |
1552 | For a pipeline, the process ID is that of the last command in the pipeline. | | 1552 | For a pipeline, the process ID is that of the last command in the pipeline. |
1553 | If no background commands have yet been started by the shell, then | | 1553 | If no background commands have yet been started by the shell, then |
1554 | .Dq \&! | | 1554 | .Dq \&! |
1555 | will be unset. | | 1555 | will be unset. |
1556 | Once set, the value of | | 1556 | Once set, the value of |
1557 | .Dq \&! | | 1557 | .Dq \&! |
1558 | will be retained until another background command is started. | | 1558 | will be retained until another background command is started. |
1559 | .It 0 (Zero.) | | 1559 | .It 0 (Zero.) |
1560 | Expands to the name of the shell or shell script. | | 1560 | Expands to the name of the shell or shell script. |
1561 | .El | | 1561 | .El |
1562 | .Ss Word Expansions | | 1562 | .Ss Word Expansions |
1563 | This section describes the various expansions that are performed on words. | | 1563 | This section describes the various expansions that are performed on words. |
1564 | Not all expansions are performed on every word, as explained later. | | 1564 | Not all expansions are performed on every word, as explained later. |
1565 | .Pp | | 1565 | .Pp |
1566 | Tilde expansions, parameter expansions, command substitutions, arithmetic | | 1566 | Tilde expansions, parameter expansions, command substitutions, arithmetic |
1567 | expansions, and quote removals that occur within a single word expand to a | | 1567 | expansions, and quote removals that occur within a single word expand to a |
1568 | single field. | | 1568 | single field. |
1569 | It is only field splitting or pathname expansion that can | | 1569 | It is only field splitting or pathname expansion that can |
1570 | create multiple fields from a single word. | | 1570 | create multiple fields from a single word. |
1571 | The single exception to this | | 1571 | The single exception to this |
1572 | rule is the expansion of the special parameter @ within double quotes, as | | 1572 | rule is the expansion of the special parameter @ within double quotes, as |
1573 | was described above. | | 1573 | was described above. |
1574 | .Pp | | 1574 | .Pp |
1575 | The order of word expansion is: | | 1575 | The order of word expansion is: |
1576 | .Bl -enum | | 1576 | .Bl -enum |
1577 | .It | | 1577 | .It |
1578 | Tilde Expansion, Parameter Expansion, Command Substitution, | | 1578 | Tilde Expansion, Parameter Expansion, Command Substitution, |
1579 | Arithmetic Expansion (these all occur at the same time). | | 1579 | Arithmetic Expansion (these all occur at the same time). |
1580 | .It | | 1580 | .It |
1581 | Field Splitting is performed on fields | | 1581 | Field Splitting is performed on fields |
1582 | generated by step (1) unless the | | 1582 | generated by step (1) unless the |
1583 | .Ev IFS | | 1583 | .Ev IFS |
1584 | variable is null. | | 1584 | variable is null. |
1585 | .It | | 1585 | .It |
1586 | Pathname Expansion (unless set | | 1586 | Pathname Expansion (unless set |
1587 | .Fl f | | 1587 | .Fl f |
1588 | is in effect). | | 1588 | is in effect). |
1589 | .It | | 1589 | .It |
1590 | Quote Removal. | | 1590 | Quote Removal. |
1591 | .El | | 1591 | .El |
1592 | .Pp | | 1592 | .Pp |
1593 | The $ character is used to introduce parameter expansion, command | | 1593 | The $ character is used to introduce parameter expansion, command |
1594 | substitution, or arithmetic evaluation. | | 1594 | substitution, or arithmetic evaluation. |
1595 | .Ss Tilde Expansion (substituting a user's home directory) | | 1595 | .Ss Tilde Expansion (substituting a user's home directory) |
1596 | A word beginning with an unquoted tilde character (~) is | | 1596 | A word beginning with an unquoted tilde character (~) is |
1597 | subjected to tilde expansion. | | 1597 | subjected to tilde expansion. |
1598 | Provided all of the subsequent characters in the word are unquoted | | 1598 | Provided all of the subsequent characters in the word are unquoted |
1599 | up to an unquoted slash (/) | | 1599 | up to an unquoted slash (/) |
1600 | or when in an assignment or not in posix mode, an unquoted colon (:), | | 1600 | or when in an assignment or not in posix mode, an unquoted colon (:), |
1601 | or if neither of those appear, the end of the word, | | 1601 | or if neither of those appear, the end of the word, |
1602 | they are treated as a user name | | 1602 | they are treated as a user name |
1603 | and are replaced with the pathname of the named user's home directory. | | 1603 | and are replaced with the pathname of the named user's home directory. |
1604 | If the user name is missing (as in | | 1604 | If the user name is missing (as in |
1605 | .Pa ~/foobar ) , | | 1605 | .Pa ~/foobar ) , |
1606 | the tilde is replaced with the value of the | | 1606 | the tilde is replaced with the value of the |
1607 | .Va HOME | | 1607 | .Va HOME |
1608 | variable (the current user's home directory). | | 1608 | variable (the current user's home directory). |
1609 | .Pp | | 1609 | .Pp |
1610 | In variable assignments, | | 1610 | In variable assignments, |
1611 | an unquoted tilde immediately after the assignment operator (=), and | | 1611 | an unquoted tilde immediately after the assignment operator (=), and |
1612 | each unquoted tilde immediately after an unquoted colon in the value | | 1612 | each unquoted tilde immediately after an unquoted colon in the value |
1613 | to be assigned is also subject to tilde expansion as just stated. | | 1613 | to be assigned is also subject to tilde expansion as just stated. |
1614 | .Ss Parameter Expansion | | 1614 | .Ss Parameter Expansion |
1615 | The format for parameter expansion is as follows: | | 1615 | The format for parameter expansion is as follows: |
1616 | .Pp | | 1616 | .Pp |
1617 | .Dl ${expression} | | 1617 | .Dl ${expression} |
1618 | .Pp | | 1618 | .Pp |
1619 | where expression consists of all characters until the matching | | 1619 | where expression consists of all characters until the matching |
1620 | .Dq } . | | 1620 | .Dq } . |
1621 | Any | | 1621 | Any |
1622 | .Dq } | | 1622 | .Dq } |
1623 | escaped by a backslash or within a quoted string, and characters in | | 1623 | escaped by a backslash or within a quoted string, and characters in |
1624 | embedded arithmetic expansions, command substitutions, and variable | | 1624 | embedded arithmetic expansions, command substitutions, and variable |
1625 | expansions, are not examined in determining the matching | | 1625 | expansions, are not examined in determining the matching |
1626 | .Dq } . | | 1626 | .Dq } . |
1627 | .Pp | | 1627 | .Pp |
1628 | The simplest form for parameter expansion is: | | 1628 | The simplest form for parameter expansion is: |
1629 | .Pp | | 1629 | .Pp |
1630 | .Dl ${parameter} | | 1630 | .Dl ${parameter} |
1631 | .Pp | | 1631 | .Pp |
1632 | The value, if any, of parameter is substituted. | | 1632 | The value, if any, of parameter is substituted. |
1633 | .Pp | | 1633 | .Pp |
1634 | The parameter name or symbol can be enclosed in braces, | | 1634 | The parameter name or symbol can be enclosed in braces, |
1635 | which are optional in this simple case, | | 1635 | which are optional in this simple case, |
1636 | except for positional parameters with more than one digit or | | 1636 | except for positional parameters with more than one digit or |
1637 | when parameter is followed by a character that could be interpreted as | | 1637 | when parameter is followed by a character that could be interpreted as |
1638 | part of the name. | | 1638 | part of the name. |
1639 | If a parameter expansion occurs inside double quotes: | | 1639 | If a parameter expansion occurs inside double quotes: |
1640 | .Bl -enum | | 1640 | .Bl -enum |
1641 | .It | | 1641 | .It |
1642 | Pathname expansion is not performed on the results of the expansion. | | 1642 | Pathname expansion is not performed on the results of the expansion. |
1643 | .It | | 1643 | .It |
1644 | Field splitting is not performed on the results of the | | 1644 | Field splitting is not performed on the results of the |
1645 | expansion, with the exception of the special rules for @. | | 1645 | expansion, with the exception of the special rules for @. |
1646 | .El | | 1646 | .El |
1647 | .Pp | | 1647 | .Pp |
1648 | In addition, a parameter expansion where braces are used, | | 1648 | In addition, a parameter expansion where braces are used, |
1649 | can be modified by using one of the following formats. | | 1649 | can be modified by using one of the following formats. |
1650 | If the | | 1650 | If the |
1651 | .Dq Dv \&: | | 1651 | .Dq Dv \&: |
1652 | is omitted in the following modifiers, then the test in the expansion | | 1652 | is omitted in the following modifiers, then the test in the expansion |
1653 | applies only to unset parameters, not null ones. | | 1653 | applies only to unset parameters, not null ones. |
1654 | .Bl -tag -width aaparameterwordaaaaa | | 1654 | .Bl -tag -width aaparameterwordaaaaa |
1655 | .It ${parameter:\(miword} | | 1655 | .It ${parameter:\(miword} |
1656 | Use Default Values. | | 1656 | Use Default Values. |
1657 | If parameter is unset or null, the expansion of word | | 1657 | If parameter is unset or null, the expansion of word |
1658 | is substituted; otherwise, the value of parameter is substituted. | | 1658 | is substituted; otherwise, the value of parameter is substituted. |
1659 | .It ${parameter:=word} | | 1659 | .It ${parameter:=word} |
1660 | Assign Default Values. | | 1660 | Assign Default Values. |
1661 | If parameter is unset or null, the expansion of | | 1661 | If parameter is unset or null, the expansion of |
1662 | word is assigned to parameter. | | 1662 | word is assigned to parameter. |
1663 | In all cases, the final value of parameter is substituted. | | 1663 | In all cases, the final value of parameter is substituted. |
1664 | Only variables, not positional parameters or special | | 1664 | Only variables, not positional parameters or special |
1665 | parameters, can be assigned in this way. | | 1665 | parameters, can be assigned in this way. |
1666 | .It ${parameter:?[word]} | | 1666 | .It ${parameter:?[word]} |
1667 | Indicate Error if Null or Unset. | | 1667 | Indicate Error if Null or Unset. |
1668 | If parameter is unset or null, the | | 1668 | If parameter is unset or null, the |
1669 | expansion of word (or a message indicating it is unset if word is omitted) | | 1669 | expansion of word (or a message indicating it is unset if word is omitted) |
1670 | is written to standard error and a non-interactive shell exits with | | 1670 | is written to standard error and a non-interactive shell exits with |
1671 | a nonzero exit status. | | 1671 | a nonzero exit status. |
1672 | An interactive shell will not exit, but any associated command(s) will | | 1672 | An interactive shell will not exit, but any associated command(s) will |
1673 | not be executed. | | 1673 | not be executed. |
1674 | If the parameter is set, its value is substituted. | | 1674 | If the parameter is set, its value is substituted. |
1675 | .It ${parameter:+word} | | 1675 | .It ${parameter:+word} |
1676 | Use Alternative Value. | | 1676 | Use Alternative Value. |
1677 | If parameter is unset or null, null is | | 1677 | If parameter is unset or null, null is |
1678 | substituted; otherwise, the expansion of word is substituted. | | 1678 | substituted; otherwise, the expansion of word is substituted. |
1679 | The value of parameter is not used in this expansion. | | 1679 | The value of parameter is not used in this expansion. |
1680 | .It ${#parameter} | | 1680 | .It ${#parameter} |
1681 | String Length. | | 1681 | String Length. |
1682 | The length in characters of the value of parameter. | | 1682 | The length in characters of the value of parameter. |
1683 | .El | | 1683 | .El |
1684 | .Pp | | 1684 | .Pp |
1685 | The following four varieties of parameter expansion provide for substring | | 1685 | The following four varieties of parameter expansion provide for substring |
1686 | processing. | | 1686 | processing. |
1687 | In each case, pattern matching notation (see | | 1687 | In each case, pattern matching notation (see |
1688 | .Sx Shell Patterns ) , | | 1688 | .Sx Shell Patterns ) , |
1689 | rather than regular expression notation, is used to evaluate the patterns. | | 1689 | rather than regular expression notation, is used to evaluate the patterns. |
1690 | If parameter is * or @, the result of the expansion is unspecified. | | 1690 | If parameter is * or @, the result of the expansion is unspecified. |
1691 | Enclosing the full parameter expansion string in double quotes does not | | 1691 | Enclosing the full parameter expansion string in double quotes does not |
1692 | cause the following four varieties of pattern characters to be quoted, | | 1692 | cause the following four varieties of pattern characters to be quoted, |
1693 | whereas quoting characters within the braces has this effect. | | 1693 | whereas quoting characters within the braces has this effect. |
1694 | .Bl -tag -width aaparameterwordaaaaa | | 1694 | .Bl -tag -width aaparameterwordaaaaa |
1695 | .It ${parameter%word} | | 1695 | .It ${parameter%word} |
1696 | Remove Smallest Suffix Pattern. | | 1696 | Remove Smallest Suffix Pattern. |
1697 | The word is expanded to produce a pattern. | | 1697 | The word is expanded to produce a pattern. |
1698 | The parameter expansion then results in parameter, with the | | 1698 | The parameter expansion then results in parameter, with the |
1699 | smallest portion of the suffix matched by the pattern deleted. | | 1699 | smallest portion of the suffix matched by the pattern deleted. |
1700 | If the word is to start with a | | 1700 | If the word is to start with a |
1701 | .Sq \&% | | 1701 | .Sq \&% |
1702 | character, it must be quoted. | | 1702 | character, it must be quoted. |
1703 | .It ${parameter%%word} | | 1703 | .It ${parameter%%word} |
1704 | Remove Largest Suffix Pattern. | | 1704 | Remove Largest Suffix Pattern. |
1705 | The word is expanded to produce a pattern. | | 1705 | The word is expanded to produce a pattern. |
1706 | The parameter expansion then results in parameter, with the largest | | 1706 | The parameter expansion then results in parameter, with the largest |
1707 | portion of the suffix matched by the pattern deleted. | | 1707 | portion of the suffix matched by the pattern deleted. |
1708 | The | | 1708 | The |
1709 | .Dq %% | | 1709 | .Dq %% |
1710 | pattern operator only produces different results from the | | 1710 | pattern operator only produces different results from the |
1711 | .Dq \&% | | 1711 | .Dq \&% |
1712 | operator when the pattern contains at least one unquoted | | 1712 | operator when the pattern contains at least one unquoted |
1713 | .Sq \&* . | | 1713 | .Sq \&* . |
1714 | .It ${parameter#word} | | 1714 | .It ${parameter#word} |
1715 | Remove Smallest Prefix Pattern. | | 1715 | Remove Smallest Prefix Pattern. |
1716 | The word is expanded to produce a pattern. | | 1716 | The word is expanded to produce a pattern. |
1717 | The parameter expansion then results in parameter, with the | | 1717 | The parameter expansion then results in parameter, with the |
1718 | smallest portion of the prefix matched by the pattern deleted. | | 1718 | smallest portion of the prefix matched by the pattern deleted. |
1719 | If the word is to start with a | | 1719 | If the word is to start with a |
1720 | .Sq \&# | | 1720 | .Sq \&# |
1721 | character, it must be quoted. | | 1721 | character, it must be quoted. |
1722 | .It ${parameter##word} | | 1722 | .It ${parameter##word} |
1723 | Remove Largest Prefix Pattern. | | 1723 | Remove Largest Prefix Pattern. |
1724 | The word is expanded to produce a pattern. | | 1724 | The word is expanded to produce a pattern. |
1725 | The parameter expansion then results in parameter, with the largest | | 1725 | The parameter expansion then results in parameter, with the largest |
1726 | portion of the prefix matched by the pattern deleted. | | 1726 | portion of the prefix matched by the pattern deleted. |
1727 | This has the same relationship with the | | 1727 | This has the same relationship with the |
1728 | .Sq \&# | | 1728 | .Sq \&# |
1729 | pattern operator as | | 1729 | pattern operator as |
1730 | .Dq %% | | 1730 | .Dq %% |
1731 | has with | | 1731 | has with |
1732 | .Dq \&% . | | 1732 | .Dq \&% . |
1733 | .El | | 1733 | .El |
1734 | .Ss Command Substitution | | 1734 | .Ss Command Substitution |
1735 | Command substitution allows the output of a command to be substituted in | | 1735 | Command substitution allows the output of a command to be substituted in |
1736 | place of the command (and surrounding syntax). | | 1736 | place of the command (and surrounding syntax). |
1737 | Command substitution occurs when the command is enclosed as follows: | | 1737 | Command substitution occurs when the command is enclosed as follows: |
1738 | .Pp | | 1738 | .Pp |
1739 | .Dl $(command) | | 1739 | .Dl $(command) |
1740 | .Pp | | 1740 | .Pp |
1741 | or | | 1741 | or |
1742 | .Po | | 1742 | .Po |
1743 | .Dq backquoted | | 1743 | .Dq backquoted |
1744 | version | | 1744 | version |
1745 | .Pc : | | 1745 | .Pc : |
1746 | .Pp | | 1746 | .Pp |
1747 | .Dl `command` | | 1747 | .Dl `command` |
1748 | .Pp | | 1748 | .Pp |
1749 | The shell expands the command substitution by executing command in a | | 1749 | The shell expands the command substitution by executing command in a |
1750 | sub-shell environment and replacing the command substitution with the | | 1750 | sub-shell environment and replacing the command substitution with the |
1751 | standard output of the command, removing sequences of one or more | | 1751 | standard output of the command, removing sequences of one or more |
1752 | .Ao newline Ac Ns s | | 1752 | .Ao newline Ac Ns s |
1753 | at the end of the substitution. | | 1753 | at the end of the substitution. |
1754 | (Embedded | | 1754 | (Embedded |
1755 | .Ao newline Ac Ns s | | 1755 | .Ao newline Ac Ns s |
1756 | before | | 1756 | before |
1757 | the end of the output are not removed; however, during field splitting, | | 1757 | the end of the output are not removed; however, during field splitting, |
1758 | they may be translated into | | 1758 | they may be translated into |
1759 | .Ao space Ac Ns s , | | 1759 | .Ao space Ac Ns s , |
1760 | depending on the value of | | 1760 | depending on the value of |
1761 | .Ev IFS | | 1761 | .Ev IFS |
1762 | and any quoting that is in effect.) | | 1762 | and any quoting that is in effect.) |
1763 | .Ss Arithmetic Expansion | | 1763 | .Ss Arithmetic Expansion |
1764 | Arithmetic expansion provides a mechanism for evaluating an arithmetic | | 1764 | Arithmetic expansion provides a mechanism for evaluating an arithmetic |
1765 | expression and substituting its value. | | 1765 | expression and substituting its value. |
1766 | The format for arithmetic expansion is as follows: | | 1766 | The format for arithmetic expansion is as follows: |
1767 | .Pp | | 1767 | .Pp |
1768 | .Dl $((expression)) | | 1768 | .Dl $((expression)) |
1769 | .Pp | | 1769 | .Pp |
1770 | The expression in an arithmetic expansion is treated as if it were in | | 1770 | The expression in an arithmetic expansion is treated as if it were in |
1771 | double quotes, except that a double quote character inside the expression | | 1771 | double quotes, except that a double quote character inside the expression |
1772 | is just a normal character (it quotes nothing.) | | 1772 | is just a normal character (it quotes nothing.) |
1773 | The shell expands all tokens in the expression for parameter expansion, | | 1773 | The shell expands all tokens in the expression for parameter expansion, |
1774 | command substitution, and quote removal (the only quoting character is | | 1774 | command substitution, and quote removal (the only quoting character is |
1775 | the backslash | | 1775 | the backslash |
1776 | .Sq \&\e , | | 1776 | .Sq \&\e , |
1777 | and only when followed by another | | 1777 | and only when followed by another |
1778 | .Sq \&\e , | | 1778 | .Sq \&\e , |
1779 | a dollar sign | | 1779 | a dollar sign |
1780 | .Sq \&$ , | | 1780 | .Sq \&$ , |
1781 | a backquote | | 1781 | a backquote |
1782 | .Sq \&` | | 1782 | .Sq \&` |
1783 | or a newline.) | | 1783 | or a newline.) |
1784 | .Pp | | 1784 | .Pp |
1785 | Next, the shell evaluates the expanded result as an arithmetic expression | | 1785 | Next, the shell evaluates the expanded result as an arithmetic expression |
1786 | and substitutes the calculated value of that expression. | | 1786 | and substitutes the calculated value of that expression. |
1787 | .Pp | | 1787 | .Pp |
1788 | Arithmetic expressions use a syntax similar to that | | 1788 | Arithmetic expressions use a syntax similar to that |
1789 | of the C language, and are evaluated using the | | 1789 | of the C language, and are evaluated using the |
1790 | .Ql intmax_t | | 1790 | .Ql intmax_t |
1791 | data type (this is an extension to POSIX, which requires only | | 1791 | data type (this is an extension to POSIX, which requires only |
1792 | .Ql long | | 1792 | .Ql long |
1793 | arithmetic.) | | 1793 | arithmetic.) |
1794 | Shell variables may be referenced by name inside an arithmetic | | 1794 | Shell variables may be referenced by name inside an arithmetic |
1795 | expression, without needing a | | 1795 | expression, without needing a |
1796 | .Dq \&$ | | 1796 | .Dq \&$ |
1797 | sign. | | 1797 | sign. |
1798 | Variables that are not set, or which have an empty (null string) value, | | 1798 | Variables that are not set, or which have an empty (null string) value, |
1799 | used this way evaluate as zero (that is, | | 1799 | used this way evaluate as zero (that is, |
1800 | .Dq x | | 1800 | .Dq x |
1801 | in arithmetic, as an R-Value, is evaluated as | | 1801 | in arithmetic, as an R-Value, is evaluated as |
1802 | .Dq ${x:-0} ) | | 1802 | .Dq ${x:-0} ) |
1803 | unless the | | 1803 | unless the |
1804 | .Nm | | 1804 | .Nm |
1805 | .Fl u | | 1805 | .Fl u |
1806 | flag is set, in which case a reference to an unset variable is an error. | | 1806 | flag is set, in which case a reference to an unset variable is an error. |
1807 | Note that unset variables used in the ${var} form expand to a null | | 1807 | Note that unset variables used in the ${var} form expand to a null |
1808 | string, which might result in syntax errors. | | 1808 | string, which might result in syntax errors. |
1809 | Referencing the value of a variable which is not numeric is an error. | | 1809 | Referencing the value of a variable which is not numeric is an error. |
1810 | .Pp | | 1810 | .Pp |
1811 | All of the C expression operators applicable to integers are supported, | | 1811 | All of the C expression operators applicable to integers are supported, |
1812 | and operate as they would in a C expression. | | 1812 | and operate as they would in a C expression. |
1813 | Use white space, or parentheses, to disambiguate confusing syntax, | | 1813 | Use white space, or parentheses, to disambiguate confusing syntax, |
1814 | otherwise, as in C, the longest sequence of consecutive characters | | 1814 | otherwise, as in C, the longest sequence of consecutive characters |
1815 | which make a valid token (operator, variable name, or number) is taken | | 1815 | which make a valid token (operator, variable name, or number) is taken |
1816 | to be that token, even if the token designated cannot be used | | 1816 | to be that token, even if the token designated cannot be used |
1817 | and a different interpretation could produce a successful parse. | | 1817 | and a different interpretation could produce a successful parse. |
1818 | This means, as an example, that | | 1818 | This means, as an example, that |
1819 | .Dq a+++++b | | 1819 | .Dq a+++++b |
1820 | is parsed as the gibberish sequence | | 1820 | is parsed as the gibberish sequence |
1821 | .Dq "a ++ ++ + b" , | | 1821 | .Dq "a ++ ++ + b" , |
1822 | rather than as the valid alternative | | 1822 | rather than as the valid alternative |
1823 | .Dq "a ++ + ++ b" . | | 1823 | .Dq "a ++ + ++ b" . |
1824 | Similarly, separate the | | 1824 | Similarly, separate the |
1825 | .Sq \&, | | 1825 | .Sq \&, |
1826 | operator from numbers with white space to avoid the possibility | | 1826 | operator from numbers with white space to avoid the possibility |
1827 | of confusion with the decimal indicator in some locales (though | | 1827 | of confusion with the decimal indicator in some locales (though |
1828 | fractional, or floating-point, numbers are not supported in this | | 1828 | fractional, or floating-point, numbers are not supported in this |
1829 | implementation.) | | 1829 | implementation.) |
1830 | .Pp | | 1830 | .Pp |
1831 | It should not be necessary to state that the C operators which | | 1831 | It should not be necessary to state that the C operators which |
1832 | operate on, or produce, pointer types, are not supported. | | 1832 | operate on, or produce, pointer types, are not supported. |
1833 | Those include unary | | 1833 | Those include unary |
1834 | .Dq \&* | | 1834 | .Dq \&* |
1835 | and | | 1835 | and |
1836 | .Dq \&& | | 1836 | .Dq \&& |
1837 | and the struct and array referencing binary operators: | | 1837 | and the struct and array referencing binary operators: |
1838 | .Dq \&. , | | 1838 | .Dq \&. , |
1839 | .Dq \&-> | | 1839 | .Dq \&-> |
1840 | and | | 1840 | and |
1841 | .Dq \&[ . | | 1841 | .Dq \&[ . |
1842 | .Ss White Space Splitting (Field Splitting) | | 1842 | .Ss White Space Splitting (Field Splitting) |
1843 | After parameter expansion, command substitution, and | | 1843 | After parameter expansion, command substitution, and |
1844 | arithmetic expansion the shell scans the results of | | 1844 | arithmetic expansion the shell scans the results of |
1845 | expansions and substitutions that did not occur in double quotes, | | 1845 | expansions and substitutions that did not occur in double quotes, |
1846 | and | | 1846 | and |
1847 | .Dq $@ | | 1847 | .Dq $@ |
1848 | even if it did, | | 1848 | even if it did, |
1849 | for field splitting and multiple fields can result. | | 1849 | for field splitting and multiple fields can result. |
1850 | .Pp | | 1850 | .Pp |
1851 | The shell treats each character of the | | 1851 | The shell treats each character of the |
1852 | .Ev IFS | | 1852 | .Ev IFS |
1853 | as a delimiter and uses the delimiters to split the results of parameter | | 1853 | as a delimiter and uses the delimiters to split the results of parameter |
1854 | expansion and command substitution into fields. | | 1854 | expansion and command substitution into fields. |
1855 | .Pp | | 1855 | .Pp |
1856 | Non-whitespace characters in | | 1856 | Non-whitespace characters in |
1857 | .Ev IFS | | 1857 | .Ev IFS |
1858 | are treated strictly as parameter separators. | | 1858 | are treated strictly as parameter separators. |
1859 | So adjacent non-whitespace | | 1859 | So adjacent non-whitespace |
1860 | .Ev IFS | | 1860 | .Ev IFS |
1861 | characters will produce empty parameters. | | 1861 | characters will produce empty parameters. |
1862 | On the other hand, any sequence of whitespace | | 1862 | On the other hand, any sequence of whitespace |
1863 | characters that occur in | | 1863 | characters that occur in |
1864 | .Ev IFS | | 1864 | .Ev IFS |
1865 | (known as | | 1865 | (known as |
1866 | .Ev IFS | | 1866 | .Ev IFS |
1867 | whitespace) | | 1867 | whitespace) |
1868 | can occur, leading and trailing | | 1868 | can occur, leading and trailing |
1869 | .Ev IFS | | 1869 | .Ev IFS |
1870 | whitespace, and any | | 1870 | whitespace, and any |
1871 | .Ev IFS | | 1871 | .Ev IFS |
1872 | whitespace surrounding a non whitespace | | 1872 | whitespace surrounding a non whitespace |
1873 | .Ev IFS | | 1873 | .Ev IFS |
1874 | delimiter, is removed. | | 1874 | delimiter, is removed. |
1875 | Any sequence of | | 1875 | Any sequence of |
1876 | .Ev IFS | | 1876 | .Ev IFS |
1877 | whitespace characters without a non-whitespace | | 1877 | whitespace characters without a non-whitespace |
1878 | .Ev IFS | | 1878 | .Ev IFS |
1879 | delimiter acts as a single field separator. | | 1879 | delimiter acts as a single field separator. |
1880 | .Pp | | 1880 | .Pp |
1881 | If | | 1881 | If |
1882 | .Ev IFS | | 1882 | .Ev IFS |
1883 | is unset it is assumed to contain space, tab, and newline, | | 1883 | is unset it is assumed to contain space, tab, and newline, |
1884 | all of which are | | 1884 | all of which are |
1885 | .Ev IFS | | 1885 | .Ev IFS |
1886 | whitespace characters. | | 1886 | whitespace characters. |
1887 | If | | 1887 | If |
1888 | .Ev IFS | | 1888 | .Ev IFS |
1889 | is set to a null string, there are no delimiters, | | 1889 | is set to a null string, there are no delimiters, |
1890 | and no field splitting occurs. | | 1890 | and no field splitting occurs. |
1891 | .Ss Pathname Expansion (File Name Generation) | | 1891 | .Ss Pathname Expansion (File Name Generation) |
1892 | Unless the | | 1892 | Unless the |
1893 | .Fl f | | 1893 | .Fl f |
1894 | flag is set, file name generation is performed after word splitting is | | 1894 | flag is set, file name generation is performed after word splitting is |
1895 | complete. | | 1895 | complete. |
1896 | Each word is viewed as a series of patterns, separated by slashes. | | 1896 | Each word is viewed as a series of patterns, separated by slashes. |
1897 | The process of expansion replaces the word with the names of all | | 1897 | The process of expansion replaces the word with the names of all |
1898 | existing files whose names can be formed by replacing each pattern with a | | 1898 | existing files whose names can be formed by replacing each pattern with a |
1899 | string that matches the specified pattern. | | 1899 | string that matches the specified pattern. |
1900 | There are two restrictions on | | 1900 | There are two restrictions on |
1901 | this: first, a pattern cannot match a string containing a slash, and | | 1901 | this: first, a pattern cannot match a string containing a slash, and |
1902 | second, a pattern cannot match a string starting with a period unless the | | 1902 | second, a pattern cannot match a string starting with a period unless the |
1903 | first character of the pattern is a period. | | 1903 | first character of the pattern is a period. |
1904 | The next section describes the | | 1904 | The next section describes the |
1905 | patterns used for both Pathname Expansion and the | | 1905 | patterns used for both Pathname Expansion and the |
1906 | .Ic case | | 1906 | .Ic case |
1907 | command. | | 1907 | command. |
1908 | .Ss Shell Patterns | | 1908 | .Ss Shell Patterns |
1909 | A pattern consists of normal characters, which match themselves, | | 1909 | A pattern consists of normal characters, which match themselves, |
1910 | and meta-characters. | | 1910 | and meta-characters. |
1911 | The meta-characters are | | 1911 | The meta-characters are |
1912 | .Dq \&! , | | 1912 | .Dq \&! , |
1913 | .Dq * , | | 1913 | .Dq * , |
1914 | .Dq \&? , | | 1914 | .Dq \&? , |
1915 | and | | 1915 | and |
1916 | .Dq \&[ . | | 1916 | .Dq \&[ . |
1917 | These characters lose their special meanings if they are quoted. | | 1917 | These characters lose their special meanings if they are quoted. |
1918 | When command or variable substitution is performed | | 1918 | When command or variable substitution is performed |
1919 | and the dollar sign or backquotes are not double-quoted, | | 1919 | and the dollar sign or backquotes are not double-quoted, |
1920 | the value of the variable or the output of | | 1920 | the value of the variable or the output of |
1921 | the command is scanned for these characters and they are turned into | | 1921 | the command is scanned for these characters and they are turned into |
1922 | meta-characters. | | 1922 | meta-characters. |
1923 | .Pp | | 1923 | .Pp |
1924 | An asterisk | | 1924 | An asterisk |
1925 | .Pq Dq * | | 1925 | .Pq Dq * |
1926 | matches any string of characters. | | 1926 | matches any string of characters. |
1927 | A question mark | | 1927 | A question mark |
1928 | .Pq Dq \&? | | 1928 | .Pq Dq \&? |
1929 | matches any single character. | | 1929 | matches any single character. |
1930 | A left bracket | | 1930 | A left bracket |
1931 | .Pq Dq \&[ | | 1931 | .Pq Dq \&[ |
1932 | introduces a character class. | | 1932 | introduces a character class. |
1933 | The end of the character class is indicated by a right bracket | | 1933 | The end of the character class is indicated by a right bracket |
1934 | .Pq Dq \&] ; | | 1934 | .Pq Dq \&] ; |
1935 | if this | | 1935 | if this |
1936 | .Dq \&] | | 1936 | .Dq \&] |
1937 | is missing then the | | 1937 | is missing then the |
1938 | .Dq \&[ | | 1938 | .Dq \&[ |
1939 | matches a | | 1939 | matches a |
1940 | .Dq \&[ | | 1940 | .Dq \&[ |
1941 | rather than introducing a character class. | | 1941 | rather than introducing a character class. |
1942 | A character class matches any of the characters between the square brackets. | | 1942 | A character class matches any of the characters between the square brackets. |
1943 | A named class of characters (see | | 1943 | A named class of characters (see |
1944 | .Xr wctype 3 ) | | 1944 | .Xr wctype 3 ) |
1945 | may be specified by surrounding the name with | | 1945 | may be specified by surrounding the name with |
1946 | .Pq Dq [: | | 1946 | .Pq Dq [: |
1947 | and | | 1947 | and |
1948 | .Pq Dq :] . | | 1948 | .Pq Dq :] . |
1949 | For example, | | 1949 | For example, |
1950 | .Pq Dq [[:alpha:]] | | 1950 | .Pq Dq [[:alpha:]] |
1951 | is a shell pattern that matches a single letter. | | 1951 | is a shell pattern that matches a single letter. |
1952 | A range of characters may be specified using a minus sign | | 1952 | A range of characters may be specified using a minus sign |
1953 | .Pq Dq \(mi . | | 1953 | .Pq Dq \(mi . |
1954 | The character class may be complemented | | 1954 | The character class may be complemented |
1955 | by making an exclamation mark | | 1955 | by making an exclamation mark |
1956 | .Pq Dq \&! | | 1956 | .Pq Dq \&! |
1957 | the first character of the character class. | | 1957 | the first character of the character class. |
1958 | .Pp | | 1958 | .Pp |
1959 | To include a | | 1959 | To include a |
1960 | .Dq \&] | | 1960 | .Dq \&] |
1961 | in a character class, make it the first character listed (after the | | 1961 | in a character class, make it the first character listed (after the |
1962 | .Dq \&! , | | 1962 | .Dq \&! , |
1963 | if any). | | 1963 | if any). |
1964 | To include a | | 1964 | To include a |
1965 | .Dq \(mi , | | 1965 | .Dq \(mi , |
1966 | make it the first (after !) or last character listed. | | 1966 | make it the first (after !) or last character listed. |
1967 | If both | | 1967 | If both |
1968 | .Dq \&] | | 1968 | .Dq \&] |
1969 | and | | 1969 | and |
1970 | .Dq \(mi | | 1970 | .Dq \(mi |
1971 | are to be included, the | | 1971 | are to be included, the |
1972 | .Dq \&] | | 1972 | .Dq \&] |
1973 | must be first (after !) | | 1973 | must be first (after !) |
1974 | and the | | 1974 | and the |
1975 | .Dq \(mi | | 1975 | .Dq \(mi |
1976 | last, in the character class. | | 1976 | last, in the character class. |
1977 | .Ss Built-ins | | 1977 | .Ss Built-ins |
1978 | This section lists the built-in commands which are built-in because they | | 1978 | This section lists the built-in commands which are built-in because they |
1979 | need to perform some operation that can't be performed by a separate | | 1979 | need to perform some operation that can't be performed by a separate |
1980 | process. | | 1980 | process. |
1981 | Or just because they traditionally are. | | 1981 | Or just because they traditionally are. |
1982 | In addition to these, there are several other commands that may | | 1982 | In addition to these, there are several other commands that may |
1983 | be built in for efficiency (e.g. | | 1983 | be built in for efficiency (e.g. |
1984 | .Xr printf 1 , | | 1984 | .Xr printf 1 , |
1985 | .Xr echo 1 , | | 1985 | .Xr echo 1 , |
1986 | .Xr test 1 , | | 1986 | .Xr test 1 , |
1987 | etc). | | 1987 | etc). |
1988 | .Bl -tag -width 5n | | 1988 | .Bl -tag -width 5n |
1989 | .It : [ Ar arg ... ] | | 1989 | .It : [ Ar arg ... ] |
1990 | A null command that returns a 0 (true) exit value. | | 1990 | A null command that returns a 0 (true) exit value. |
1991 | Any arguments or redirects are evaluated, then ignored. | | 1991 | Any arguments or redirects are evaluated, then ignored. |
1992 | .It \&. file | | 1992 | .It \&. file |
1993 | The dot command reads and executes the commands from the specified | | 1993 | The dot command reads and executes the commands from the specified |
1994 | .Ar file | | 1994 | .Ar file |
1995 | in the current shell environment. | | 1995 | in the current shell environment. |
1996 | The file does not need to be executable and is looked up from the directories | | 1996 | The file does not need to be executable and is looked up from the directories |
1997 | listed in the | | 1997 | listed in the |
1998 | .Ev PATH | | 1998 | .Ev PATH |
1999 | variable if its name does not contain a directory separator | | 1999 | variable if its name does not contain a directory separator |
2000 | .Pq Sq / . | | 2000 | .Pq Sq / . |
2001 | The return command | | 2001 | The return command |
2002 | (see | | 2002 | (see |
2003 | .Sx Built-ins | | 2003 | .Sx Built-ins |
2004 | below) | | 2004 | below) |
2005 | can be used for a premature return from the sourced file. | | 2005 | can be used for a premature return from the sourced file. |
2006 | .Pp | | 2006 | .Pp |
2007 | The POSIX standard has been unclear on how loop control keywords (break | | 2007 | The POSIX standard has been unclear on how loop control keywords (break |
2008 | and continue) behave across a dot command boundary. | | 2008 | and continue) behave across a dot command boundary. |
2009 | This implementation allows them to control loops surrounding the dot command, | | 2009 | This implementation allows them to control loops surrounding the dot command, |
2010 | but obviously such behavior should not be relied on. | | 2010 | but obviously such behavior should not be relied on. |
2011 | It is now permitted by the standard, but not required. | | 2011 | It is now permitted by the standard, but not required. |
2012 | .It alias Op Ar name Ns Op Ar "=string ..." | | 2012 | .It alias Op Ar name Ns Op Ar "=string ..." |
2013 | If | | 2013 | If |
2014 | .Ar name=string | | 2014 | .Ar name=string |
2015 | is specified, the shell defines the alias | | 2015 | is specified, the shell defines the alias |
2016 | .Ar name | | 2016 | .Ar name |
2017 | with value | | 2017 | with value |
2018 | .Ar string . | | 2018 | .Ar string . |
2019 | If just | | 2019 | If just |
2020 | .Ar name | | 2020 | .Ar name |
2021 | is specified, the value of the alias | | 2021 | is specified, the value of the alias |
2022 | .Ar name | | 2022 | .Ar name |
2023 | is printed. | | 2023 | is printed. |
2024 | With no arguments, the | | 2024 | With no arguments, the |
2025 | .Ic alias | | 2025 | .Ic alias |
2026 | built-in prints the | | 2026 | built-in prints the |
2027 | names and values of all defined aliases (see | | 2027 | names and values of all defined aliases (see |
2028 | .Ic unalias ) . | | 2028 | .Ic unalias ) . |
2029 | .It bg [ Ar job ] ... | | 2029 | .It bg [ Ar job ] ... |
2030 | Continue the specified jobs (or the current job if no | | 2030 | Continue the specified jobs (or the current job if no |
2031 | jobs are given) in the background. | | 2031 | jobs are given) in the background. |
2032 | .It command Oo Fl p Oc Oo Fl v Oc Oo Fl V Oc Ar command Oo Ar arg ... Oc | | 2032 | .It command Oo Fl p Oc Oo Fl v Oc Oo Fl V Oc Ar command Oo Ar arg ... Oc |
2033 | Execute the specified command but ignore shell functions when searching | | 2033 | Execute the specified command but ignore shell functions when searching |
2034 | for it. | | 2034 | for it. |
2035 | (This is useful when you | | 2035 | (This is useful when you |
2036 | have a shell function with the same name as a command.) | | 2036 | have a shell function with the same name as a command.) |
2037 | .Bl -tag -width 5n | | 2037 | .Bl -tag -width 5n |
2038 | .It Fl p | | 2038 | .It Fl p |
2039 | search for command using a | | 2039 | search for command using a |
2040 | .Ev PATH | | 2040 | .Ev PATH |
2041 | that guarantees to find all the standard utilities. | | 2041 | that guarantees to find all the standard utilities. |
2042 | .It Fl V | | 2042 | .It Fl V |
2043 | Do not execute the command but | | 2043 | Do not execute the command but |
2044 | search for the command and print the resolution of the | | 2044 | search for the command and print the resolution of the |
2045 | command search. | | 2045 | command search. |
2046 | This is the same as the | | 2046 | This is the same as the |
2047 | .Ic type | | 2047 | .Ic type |
2048 | built-in. | | 2048 | built-in. |
2049 | .It Fl v | | 2049 | .It Fl v |
2050 | Do not execute the command but | | 2050 | Do not execute the command but |
2051 | search for the command and print the absolute pathname | | 2051 | search for the command and print the absolute pathname |
2052 | of utilities, the name for built-ins or the expansion of aliases. | | 2052 | of utilities, the name for built-ins or the expansion of aliases. |
2053 | .El | | 2053 | .El |
2054 | .It cd Oo Fl P Oc Op Ar directory Op Ar replace | | 2054 | .It cd Oo Fl P Oc Op Ar directory Op Ar replace |
2055 | Switch to the specified directory (default | | 2055 | Switch to the specified directory (default |
2056 | .Ev $HOME ) . | | 2056 | .Ev $HOME ) . |
2057 | If | | 2057 | If |
2058 | .Ar replace | | 2058 | .Ar replace |
2059 | is specified, then the new directory name is generated by replacing | | 2059 | is specified, then the new directory name is generated by replacing |
2060 | the first occurrence of the string | | 2060 | the first occurrence of the string |
2061 | .Ar directory | | 2061 | .Ar directory |
2062 | in the current directory name with | | 2062 | in the current directory name with |
2063 | .Ar replace . | | 2063 | .Ar replace . |
2064 | Otherwise if | | 2064 | Otherwise if |
2065 | .Ar directory | | 2065 | .Ar directory |
2066 | is | | 2066 | is |
2067 | .Sq - , | | 2067 | .Sq - , |
2068 | then the current working directory is changed to the previous current | | 2068 | then the current working directory is changed to the previous current |
2069 | working directory as set in | | 2069 | working directory as set in |
2070 | .Ev OLDPWD . | | 2070 | .Ev OLDPWD . |
2071 | Otherwise if an entry for | | 2071 | Otherwise if an entry for |
2072 | .Ev CDPATH | | 2072 | .Ev CDPATH |
2073 | appears in the environment of the | | 2073 | appears in the environment of the |
2074 | .Ic cd | | 2074 | .Ic cd |
2075 | command or the shell variable | | 2075 | command or the shell variable |
2076 | .Ev CDPATH | | 2076 | .Ev CDPATH |
2077 | is set and the directory name does not begin with a slash, | | 2077 | is set and the directory name does not begin with a slash, |
2078 | and its first (or only) component isn't dot or dot dot, | | 2078 | and its first (or only) component isn't dot or dot dot, |
2079 | then the directories listed in | | 2079 | then the directories listed in |
2080 | .Ev CDPATH | | 2080 | .Ev CDPATH |
2081 | will be searched for the specified directory. | | 2081 | will be searched for the specified directory. |
2082 | The format of | | 2082 | The format of |
2083 | .Ev CDPATH | | 2083 | .Ev CDPATH |
2084 | is the same as that of | | 2084 | is the same as that of |
2085 | .Ev PATH . | | 2085 | .Ev PATH . |
2086 | .Pp | | 2086 | .Pp |
2087 | The | | 2087 | The |
2088 | .Fl P | | 2088 | .Fl P |
2089 | option instructs the shell to update | | 2089 | option instructs the shell to update |
2090 | .Ev PWD | | 2090 | .Ev PWD |
2091 | with the specified physical directory path and change to that directory. | | 2091 | with the specified physical directory path and change to that directory. |
2092 | This is the default. | | 2092 | This is the default. |
2093 | .Pp | | 2093 | .Pp |
2094 | When the directory changes, the variable | | 2094 | When the directory changes, the variable |
2095 | .Ev OLDPWD | | 2095 | .Ev OLDPWD |
2096 | is set to the working directory before the change. | | 2096 | is set to the working directory before the change. |
2097 | .Pp | | 2097 | .Pp |
2098 | Some shells also support a | | 2098 | Some shells also support a |
2099 | .Fl L | | 2099 | .Fl L |
2100 | option, which instructs the shell to update | | 2100 | option, which instructs the shell to update |
2101 | .Ev PWD | | 2101 | .Ev PWD |
2102 | with the logical path and to change the current directory | | 2102 | with the logical path and to change the current directory |
2103 | accordingly. | | 2103 | accordingly. |
2104 | This is not supported. | | 2104 | This is not supported. |
2105 | .Pp | | 2105 | .Pp |
2106 | In an interactive shell, the | | 2106 | In an interactive shell, the |
2107 | .Ic cd | | 2107 | .Ic cd |
2108 | command will print out the name of the | | 2108 | command will print out the name of the |
2109 | directory that it actually switched to if this is different from the name | | 2109 | directory that it actually switched to if this is different from the name |
2110 | that the user gave, | | 2110 | that the user gave, |
2111 | or always if the | | 2111 | or always if the |
2112 | .Ic cdprint | | 2112 | .Ic cdprint |
2113 | option is set. | | 2113 | option is set. |
2114 | The destination may be different either because the | | 2114 | The destination may be different either because the |
2115 | .Ev CDPATH | | 2115 | .Ev CDPATH |
2116 | mechanism was used | | 2116 | mechanism was used |
2117 | .\" or because a symbolic link was crossed. | | 2117 | .\" or because a symbolic link was crossed. |
2118 | or if the | | 2118 | or if the |
2119 | .Ar replace | | 2119 | .Ar replace |
2120 | argument was used. | | 2120 | argument was used. |
2121 | .It eval Ar string ... | | 2121 | .It eval Ar string ... |
2122 | Concatenate all the arguments with spaces. | | 2122 | Concatenate all the arguments with spaces. |