| @@ -1,1444 +1,1444 @@ | | | @@ -1,1444 +1,1444 @@ |
1 | .\" $NetBSD: sh.1,v 1.176 2018/03/13 19:18:53 uwe Exp $ | | 1 | .\" $NetBSD: sh.1,v 1.177 2018/03/13 19:35:46 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 -compact -literal | | 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 | .Dl hello() cat <<EOF | | 1413 | .Dl hello() cat <<EOF |
1414 | .Dl Hello World! | | 1414 | .Dl Hello World! |
1415 | .Dl EOF | | 1415 | .Dl EOF |
1416 | To be correctly standards conforming this should be re-written as: | | 1416 | To be correctly standards conforming this should be re-written as: |
1417 | .Dl hello() { cat; } <<EOF | | 1417 | .Dl hello() { cat; } <<EOF |
1418 | .Dl Hello World! | | 1418 | .Dl Hello World! |
1419 | .Dl EOF | | 1419 | .Dl EOF |
1420 | Note the distinction between those forms, and | | 1420 | Note the distinction between those forms, and |
1421 | .Dl hello() { cat <<EOF | | 1421 | .Dl hello() { cat <<EOF |
1422 | .Dl Hello World! | | 1422 | .Dl Hello World! |
1423 | .Dl EOF | | 1423 | .Dl EOF |
1424 | .Dl \&} | | 1424 | .Dl \&} |
1425 | which reads and processes the | | 1425 | which reads and processes the |
1426 | .Ic here document | | 1426 | .Ic here document |
1427 | each time the shell executes the function, and which applies | | 1427 | each time the shell executes the function, and which applies |
1428 | that input only to the cat command, not to any other commands | | 1428 | that input only to the cat command, not to any other commands |
1429 | that might appear in the function. | | 1429 | that might appear in the function. |
1430 | .Pp | | 1430 | .Pp |
1431 | Variables may be declared to be local to a function by using the | | 1431 | Variables may be declared to be local to a function by using the |
1432 | .Ic local | | 1432 | .Ic local |
1433 | command. | | 1433 | command. |
1434 | This should usually appear as the first statement of a function, | | 1434 | This should usually appear as the first statement of a function, |
1435 | though | | 1435 | though |
1436 | .Ic local | | 1436 | .Ic local |
1437 | is an executable command which can be used anywhere in a function. | | 1437 | is an executable command which can be used anywhere in a function. |
1438 | See | | 1438 | See |
1439 | .Sx Built-ins | | 1439 | .Sx Built-ins |
1440 | below for its definition. | | 1440 | below for its definition. |
1441 | .Pp | | 1441 | .Pp |
1442 | The function completes after having executed | | 1442 | The function completes after having executed |
1443 | .Ar command | | 1443 | .Ar command |
1444 | with exit status set to the status returned by | | 1444 | with exit status set to the status returned by |
| @@ -2531,1501 +2531,1501 @@ With the | | | @@ -2531,1501 +2531,1501 @@ With the |
2531 | .Fl p | | 2531 | .Fl p |
2532 | flag, the output contains only the process identifier of the lead | | 2532 | flag, the output contains only the process identifier of the lead |
2533 | process. | | 2533 | process. |
2534 | .Pp | | 2534 | .Pp |
2535 | In an interactive shell, each job shown as completed in the output | | 2535 | In an interactive shell, each job shown as completed in the output |
2536 | from the jobs command is implicitly waited for, and is removed from | | 2536 | from the jobs command is implicitly waited for, and is removed from |
2537 | the jobs table, never to be seen again. | | 2537 | the jobs table, never to be seen again. |
2538 | In an interactive shell, when a background job terminates, the | | 2538 | In an interactive shell, when a background job terminates, the |
2539 | .Ic jobs | | 2539 | .Ic jobs |
2540 | command (with that job as an argument) is implicitly run just | | 2540 | command (with that job as an argument) is implicitly run just |
2541 | before outputting the next PS1 command prompt, after the job | | 2541 | before outputting the next PS1 command prompt, after the job |
2542 | terminated. | | 2542 | terminated. |
2543 | This indicates that the job finished, shows its status, | | 2543 | This indicates that the job finished, shows its status, |
2544 | and cleans up the job table entry for that job. | | 2544 | and cleans up the job table entry for that job. |
2545 | Non-interactive shells need to execute | | 2545 | Non-interactive shells need to execute |
2546 | .Ic wait | | 2546 | .Ic wait |
2547 | commands to clean up terminated background jobs. | | 2547 | commands to clean up terminated background jobs. |
2548 | .It local Oo Fl INx Oc Oo Ar variable | \- Oc ... | | 2548 | .It local Oo Fl INx Oc Oo Ar variable | \- Oc ... |
2549 | Define local variables for a function. | | 2549 | Define local variables for a function. |
2550 | Local variables have their attributes, and values, | | 2550 | Local variables have their attributes, and values, |
2551 | as they were before the | | 2551 | as they were before the |
2552 | .Ic local | | 2552 | .Ic local |
2553 | declaration, restored when the function terminates. | | 2553 | declaration, restored when the function terminates. |
2554 | .Pp | | 2554 | .Pp |
2555 | With the | | 2555 | With the |
2556 | .Fl N | | 2556 | .Fl N |
2557 | flag, variables made local, are unset initially inside | | 2557 | flag, variables made local, are unset initially inside |
2558 | the function. | | 2558 | the function. |
2559 | Unless the | | 2559 | Unless the |
2560 | .Fl x | | 2560 | .Fl x |
2561 | flag is also given, such variables are also unexported. | | 2561 | flag is also given, such variables are also unexported. |
2562 | The | | 2562 | The |
2563 | .Fl I | | 2563 | .Fl I |
2564 | flag, which is the default in this shell, causes | | 2564 | flag, which is the default in this shell, causes |
2565 | the initial value and exported attribute | | 2565 | the initial value and exported attribute |
2566 | of local variables | | 2566 | of local variables |
2567 | to be inherited from the variable | | 2567 | to be inherited from the variable |
2568 | with the same name in the surrounding | | 2568 | with the same name in the surrounding |
2569 | scope, if there is one. | | 2569 | scope, if there is one. |
2570 | If there is not, the variable is initially unset, | | 2570 | If there is not, the variable is initially unset, |
2571 | and not exported. | | 2571 | and not exported. |
2572 | The | | 2572 | The |
2573 | .Fl N | | 2573 | .Fl N |
2574 | and | | 2574 | and |
2575 | .Fl I | | 2575 | .Fl I |
2576 | flags are mutually exclusive, if both are given, the last specified applies. | | 2576 | flags are mutually exclusive, if both are given, the last specified applies. |
2577 | The read-only and unexportable attributes are always | | 2577 | The read-only and unexportable attributes are always |
2578 | inherited, if a variable with the same name already exists. | | 2578 | inherited, if a variable with the same name already exists. |
2579 | .Pp | | 2579 | .Pp |
2580 | The | | 2580 | The |
2581 | .Fl x | | 2581 | .Fl x |
2582 | flag (lower case) causes the local variable to be exported, | | 2582 | flag (lower case) causes the local variable to be exported, |
2583 | while the function runs, unless it has the unexportable attribute. | | 2583 | while the function runs, unless it has the unexportable attribute. |
2584 | This can also be accomplished by using the | | 2584 | This can also be accomplished by using the |
2585 | .Ic export | | 2585 | .Ic export |
2586 | command, giving the same | | 2586 | command, giving the same |
2587 | .Ar variable | | 2587 | .Ar variable |
2588 | names, after the | | 2588 | names, after the |
2589 | .Ic local | | 2589 | .Ic local |
2590 | command. | | 2590 | command. |
2591 | .Pp | | 2591 | .Pp |
2592 | Making an existing read-only variable local is possible, | | 2592 | Making an existing read-only variable local is possible, |
2593 | but pointless. | | 2593 | but pointless. |
2594 | If an attempt is made to assign an initial value to such | | 2594 | If an attempt is made to assign an initial value to such |
2595 | a variable, the | | 2595 | a variable, the |
2596 | .Ic local | | 2596 | .Ic local |
2597 | command fails, as does any later attempted assignment. | | 2597 | command fails, as does any later attempted assignment. |
2598 | If the | | 2598 | If the |
2599 | .Ic readonly | | 2599 | .Ic readonly |
2600 | command is applied to a variable that has been declared local, | | 2600 | command is applied to a variable that has been declared local, |
2601 | the variable cannot be (further) modified within the function, | | 2601 | the variable cannot be (further) modified within the function, |
2602 | or any other functions it calls, however when the function returns, | | 2602 | or any other functions it calls, however when the function returns, |
2603 | the previous status (and value) of the variable is returned. | | 2603 | the previous status (and value) of the variable is returned. |
2604 | .Pp | | 2604 | .Pp |
2605 | Values may be given to local variables on the | | 2605 | Values may be given to local variables on the |
2606 | .Ic local | | 2606 | .Ic local |
2607 | command line in a similar fashion as used for | | 2607 | command line in a similar fashion as used for |
2608 | .Ic export | | 2608 | .Ic export |
2609 | and | | 2609 | and |
2610 | .Ic readonly . | | 2610 | .Ic readonly . |
2611 | These values are assigned immediately after the initialization | | 2611 | These values are assigned immediately after the initialization |
2612 | described above. | | 2612 | described above. |
2613 | Note that any variable references on the command line will have | | 2613 | Note that any variable references on the command line will have |
2614 | been expanded before | | 2614 | been expanded before |
2615 | .Ic local | | 2615 | .Ic local |
2616 | is executed, so expressions like | | 2616 | is executed, so expressions like |
2617 | .Dl "local -N X=${X}" | | 2617 | .Dl "local -N X=${X}" |
2618 | are well defined, first $X is expanded, and then the command run is | | 2618 | are well defined, first $X is expanded, and then the command run is |
2619 | .Dl "local -N X=old-value-of-X" | | 2619 | .Dl "local -N X=old-value-of-X" |
2620 | After arranging to preserve the old value and attributes, of X | | 2620 | After arranging to preserve the old value and attributes, of X |
2621 | .Dq ( old-value-of X ) | | 2621 | .Dq ( old-value-of X ) |
2622 | .Ic local | | 2622 | .Ic local |
2623 | unsets | | 2623 | unsets |
2624 | .Ev X , | | 2624 | .Ev X , |
2625 | unexports it, and then assigns the | | 2625 | unexports it, and then assigns the |
2626 | .Dq old-value-of-X | | 2626 | .Dq old-value-of-X |
2627 | to | | 2627 | to |
2628 | .Ev X . | | 2628 | .Ev X . |
2629 | .Pp | | 2629 | .Pp |
2630 | The shell uses dynamic scoping, so that if you make the variable x local to | | 2630 | The shell uses dynamic scoping, so that if you make the variable x local to |
2631 | function f, which then calls function g, references to the variable x made | | 2631 | function f, which then calls function g, references to the variable x made |
2632 | inside g will refer to the variable x declared inside f, not to the global | | 2632 | inside g will refer to the variable x declared inside f, not to the global |
2633 | variable named x. | | 2633 | variable named x. |
2634 | .Pp | | 2634 | .Pp |
2635 | Another way to view this, is as if the shell just has one flat, global, | | 2635 | Another way to view this, is as if the shell just has one flat, global, |
2636 | namespace, in which all variables exist. | | 2636 | namespace, in which all variables exist. |
2637 | The | | 2637 | The |
2638 | .Ic local | | 2638 | .Ic local |
2639 | command conceptually copies the variable(s) named to unnamed temporary | | 2639 | command conceptually copies the variable(s) named to unnamed temporary |
2640 | variables, and when the function ends, copies them back again. | | 2640 | variables, and when the function ends, copies them back again. |
2641 | All references to the variables reference the same global variables, | | 2641 | All references to the variables reference the same global variables, |
2642 | but while the function is active, after the | | 2642 | but while the function is active, after the |
2643 | .Ic local | | 2643 | .Ic local |
2644 | command has run, the values and attributes of the variables might | | 2644 | command has run, the values and attributes of the variables might |
2645 | be altered, and later, when the function completes, be restored. | | 2645 | be altered, and later, when the function completes, be restored. |
2646 | .Pp | | 2646 | .Pp |
2647 | Note that the parameters $1, $2, ... (see | | 2647 | Note that the parameters $1, $2, ... (see |
2648 | .Sx Positional Parameters ) , | | 2648 | .Sx Positional Parameters ) , |
2649 | and $#, $* and $@ (see | | 2649 | and $#, $* and $@ (see |
2650 | .Sx Special Parameters ) , | | 2650 | .Sx Special Parameters ) , |
2651 | are always made local in all functions, and are reset inside the | | 2651 | are always made local in all functions, and are reset inside the |
2652 | function to represent the options and arguments passed to the function. | | 2652 | function to represent the options and arguments passed to the function. |
2653 | Note that $0 however retains the value it had outside the function, | | 2653 | Note that $0 however retains the value it had outside the function, |
2654 | as do all the other special parameters. | | 2654 | as do all the other special parameters. |
2655 | .Pp | | 2655 | .Pp |
2656 | The only other special parameter that can be made local is | | 2656 | The only other special parameter that can be made local is |
2657 | .Dq \- . | | 2657 | .Dq \- . |
2658 | Making | | 2658 | Making |
2659 | .Dq \- | | 2659 | .Dq \- |
2660 | local causes any shell options that are changed via the set command inside the | | 2660 | local causes any shell options that are changed via the set command inside the |
2661 | function to be restored to their original values when the function | | 2661 | function to be restored to their original values when the function |
2662 | returns. | | 2662 | returns. |
2663 | If | | 2663 | If |
2664 | .Fl X | | 2664 | .Fl X |
2665 | option is altered after | | 2665 | option is altered after |
2666 | .Dq \- | | 2666 | .Dq \- |
2667 | has been made local, then when the function returns, the previous | | 2667 | has been made local, then when the function returns, the previous |
2668 | destination for | | 2668 | destination for |
2669 | .Ic xtrace | | 2669 | .Ic xtrace |
2670 | output (as of the time of the | | 2670 | output (as of the time of the |
2671 | .Ic local | | 2671 | .Ic local |
2672 | command) will also be restored. | | 2672 | command) will also be restored. |
2673 | .Pp | | 2673 | .Pp |
2674 | It is an error to use | | 2674 | It is an error to use |
2675 | .Ic local | | 2675 | .Ic local |
2676 | outside the scope of a function definition. | | 2676 | outside the scope of a function definition. |
2677 | When used inside a function, it exits with status 0, | | 2677 | When used inside a function, it exits with status 0, |
2678 | unless an undefined option is used, or an attempt is made to | | 2678 | unless an undefined option is used, or an attempt is made to |
2679 | assign a value to a read-only variable. | | 2679 | assign a value to a read-only variable. |
2680 | .Pp | | 2680 | .Pp |
2681 | Note that either | | 2681 | Note that either |
2682 | .Fl I | | 2682 | .Fl I |
2683 | or | | 2683 | or |
2684 | .Fl N | | 2684 | .Fl N |
2685 | should always be used, or variables made local should always | | 2685 | should always be used, or variables made local should always |
2686 | be given a value, or explicitly unset, as the default behavior | | 2686 | be given a value, or explicitly unset, as the default behavior |
2687 | (inheriting the earlier value, or starting unset after | | 2687 | (inheriting the earlier value, or starting unset after |
2688 | .Ic local ) | | 2688 | .Ic local ) |
2689 | differs amongst shell implementations. | | 2689 | differs amongst shell implementations. |
2690 | Using | | 2690 | Using |
2691 | .Dq local \&\- | | 2691 | .Dq local \&\- |
2692 | is an extension not implemented by most shells. | | 2692 | is an extension not implemented by most shells. |
2693 | .Pp | | 2693 | .Pp |
2694 | See the section | | 2694 | See the section |
2695 | .Sx LINENO | | 2695 | .Sx LINENO |
2696 | below for details of the effects of making the variable | | 2696 | below for details of the effects of making the variable |
2697 | .Ev LINENO | | 2697 | .Ev LINENO |
2698 | local. | | 2698 | local. |
2699 | .It pwd Op Fl \&LP | | 2699 | .It pwd Op Fl \&LP |
2700 | Print the current directory. | | 2700 | Print the current directory. |
2701 | If | | 2701 | If |
2702 | .Fl L | | 2702 | .Fl L |
2703 | is specified the cached value (initially set from | | 2703 | is specified the cached value (initially set from |
2704 | .Ev PWD ) | | 2704 | .Ev PWD ) |
2705 | is checked to see if it refers to the current directory; if it does | | 2705 | is checked to see if it refers to the current directory; if it does |
2706 | the value is printed. | | 2706 | the value is printed. |
2707 | Otherwise the current directory name is found using | | 2707 | Otherwise the current directory name is found using |
2708 | .Xr getcwd 3 . | | 2708 | .Xr getcwd 3 . |
2709 | The environment variable | | 2709 | The environment variable |
2710 | .Ev PWD | | 2710 | .Ev PWD |
2711 | is set to the printed value. | | 2711 | is set to the printed value. |
2712 | .Pp | | 2712 | .Pp |
2713 | The default is | | 2713 | The default is |
2714 | .Ic pwd | | 2714 | .Ic pwd |
2715 | .Fl L , | | 2715 | .Fl L , |
2716 | but note that the built-in | | 2716 | but note that the built-in |
2717 | .Ic cd | | 2717 | .Ic cd |
2718 | command doesn't support the | | 2718 | command doesn't support the |
2719 | .Fl L | | 2719 | .Fl L |
2720 | option and will cache (almost) the absolute path. | | 2720 | option and will cache (almost) the absolute path. |
2721 | If | | 2721 | If |
2722 | .Ic cd | | 2722 | .Ic cd |
2723 | is changed (as unlikely as that is), | | 2723 | is changed (as unlikely as that is), |
2724 | .Ic pwd | | 2724 | .Ic pwd |
2725 | may be changed to default to | | 2725 | may be changed to default to |
2726 | .Ic pwd | | 2726 | .Ic pwd |
2727 | .Fl P . | | 2727 | .Fl P . |
2728 | .Pp | | 2728 | .Pp |
2729 | If the current directory is renamed and replaced by a symlink to the | | 2729 | If the current directory is renamed and replaced by a symlink to the |
2730 | same directory, or the initial | | 2730 | same directory, or the initial |
2731 | .Ev PWD | | 2731 | .Ev PWD |
2732 | value followed a symbolic link, then the cached value may not | | 2732 | value followed a symbolic link, then the cached value may not |
2733 | be the absolute path. | | 2733 | be the absolute path. |
2734 | .Pp | | 2734 | .Pp |
2735 | The built-in command may differ from the program of the same name because | | 2735 | The built-in command may differ from the program of the same name because |
2736 | the program will use | | 2736 | the program will use |
2737 | .Ev PWD | | 2737 | .Ev PWD |
2738 | and the built-in uses a separately cached value. | | 2738 | and the built-in uses a separately cached value. |
2739 | .It read Oo Fl p Ar prompt Oc Oo Fl r Oc Ar variable Oo Ar ... Oc | | 2739 | .It read Oo Fl p Ar prompt Oc Oo Fl r Oc Ar variable Oo Ar ... Oc |
2740 | The prompt is printed if the | | 2740 | The prompt is printed if the |
2741 | .Fl p | | 2741 | .Fl p |
2742 | option is specified and the standard input is a terminal. | | 2742 | option is specified and the standard input is a terminal. |
2743 | Then a line is read from the standard input. | | 2743 | Then a line is read from the standard input. |
2744 | The trailing newline is deleted from the | | 2744 | The trailing newline is deleted from the |
2745 | line and the line is split as described in the field splitting section of the | | 2745 | line and the line is split as described in the field splitting section of the |
2746 | .Sx Word Expansions | | 2746 | .Sx Word Expansions |
2747 | section above, and the pieces are assigned to the variables in order. | | 2747 | section above, and the pieces are assigned to the variables in order. |
2748 | If there are more pieces than variables, the remaining pieces | | 2748 | If there are more pieces than variables, the remaining pieces |
2749 | (along with the characters in | | 2749 | (along with the characters in |
2750 | .Ev IFS | | 2750 | .Ev IFS |
2751 | that separated them) are assigned to the last variable. | | 2751 | that separated them) are assigned to the last variable. |
2752 | If there are more variables than pieces, | | 2752 | If there are more variables than pieces, |
2753 | the remaining variables are assigned the null string. | | 2753 | the remaining variables are assigned the null string. |
2754 | The | | 2754 | The |
2755 | .Ic read | | 2755 | .Ic read |
2756 | built-in will indicate success unless EOF is encountered on input, in | | 2756 | built-in will indicate success unless EOF is encountered on input, in |
2757 | which case failure is returned. | | 2757 | which case failure is returned. |
2758 | .Pp | | 2758 | .Pp |
2759 | By default, unless the | | 2759 | By default, unless the |
2760 | .Fl r | | 2760 | .Fl r |
2761 | option is specified, the backslash | | 2761 | option is specified, the backslash |
2762 | .Dq \e | | 2762 | .Dq \e |
2763 | acts as an escape character, causing the following character to be treated | | 2763 | acts as an escape character, causing the following character to be treated |
2764 | literally. | | 2764 | literally. |
2765 | If a backslash is followed by a newline, the backslash and the | | 2765 | If a backslash is followed by a newline, the backslash and the |
2766 | newline will be deleted. | | 2766 | newline will be deleted. |
2767 | .It readonly Ar name ... | | 2767 | .It readonly Ar name ... |
2768 | .It readonly Oo Fl p Oc | | 2768 | .It readonly Oo Fl p Oc |
2769 | The specified names are marked as read only, so that they cannot be | | 2769 | The specified names are marked as read only, so that they cannot be |
2770 | subsequently modified or unset. | | 2770 | subsequently modified or unset. |
2771 | The shell allows the value of a variable | | 2771 | The shell allows the value of a variable |
2772 | to be set at the same time it is marked read only by writing | | 2772 | to be set at the same time it is marked read only by writing |
2773 | .Pp | | 2773 | .Pp |
2774 | .Dl readonly name=value | | 2774 | .Dl readonly name=value |
2775 | .Pp | | 2775 | .Pp |
2776 | With no arguments the readonly command lists the names of all read only | | 2776 | With no arguments the readonly command lists the names of all read only |
2777 | variables. | | 2777 | variables. |
2778 | With the | | 2778 | With the |
2779 | .Fl p | | 2779 | .Fl p |
2780 | option specified the output will be formatted suitably for non-interactive use. | | 2780 | option specified the output will be formatted suitably for non-interactive use. |
2781 | .It return Op Ar n | | 2781 | .It return Op Ar n |
2782 | Stop executing the current function or a dot command with return value of | | 2782 | Stop executing the current function or a dot command with return value of |
2783 | .Ar n | | 2783 | .Ar n |
2784 | or the value of the last executed command, if not specified. | | 2784 | or the value of the last executed command, if not specified. |
2785 | For portability, | | 2785 | For portability, |
2786 | .Ar n | | 2786 | .Ar n |
2787 | should be in the range from 0 to 255. | | 2787 | should be in the range from 0 to 255. |
2788 | .Pp | | 2788 | .Pp |
2789 | The POSIX standard says that the results of | | 2789 | The POSIX standard says that the results of |
2790 | .Sq return | | 2790 | .Sq return |
2791 | outside a function or a dot command are unspecified. | | 2791 | outside a function or a dot command are unspecified. |
2792 | This implementation treats such a return as a no-op with a return value of 0 | | 2792 | This implementation treats such a return as a no-op with a return value of 0 |
2793 | (success, true). | | 2793 | (success, true). |
2794 | Use the exit command instead, if you want to return from a script or exit | | 2794 | Use the exit command instead, if you want to return from a script or exit |
2795 | your shell. | | 2795 | your shell. |
2796 | .It set Oo { Fl options | Cm +options | Cm \-- } Oc Ar arg ... | | 2796 | .It set Oo { Fl options | Cm +options | Cm \-- } Oc Ar arg ... |
2797 | The | | 2797 | The |
2798 | .Ic set | | 2798 | .Ic set |
2799 | command performs four different functions. | | 2799 | command performs four different functions. |
2800 | .Pp | | 2800 | .Pp |
2801 | With no arguments, it lists the values of all shell variables. | | 2801 | With no arguments, it lists the values of all shell variables. |
2802 | .Pp | | 2802 | .Pp |
2803 | With a single option of either | | 2803 | With a single option of either |
2804 | .Sq Fl o | | 2804 | .Sq Fl o |
2805 | or | | 2805 | or |
2806 | .Sq Cm +o | | 2806 | .Sq Cm +o |
2807 | .Ic set | | 2807 | .Ic set |
2808 | outputs the current values of the options. | | 2808 | outputs the current values of the options. |
2809 | In the | | 2809 | In the |
2810 | .Fl o | | 2810 | .Fl o |
2811 | form, all options are listed, with their current values. | | 2811 | form, all options are listed, with their current values. |
2812 | In the | | 2812 | In the |
2813 | .Cm +o | | 2813 | .Cm +o |
2814 | form, the shell outputs a string that can later be used | | 2814 | form, the shell outputs a string that can later be used |
2815 | as a command to reset all options to their current values. | | 2815 | as a command to reset all options to their current values. |
2816 | .Pp | | 2816 | .Pp |
2817 | If options are given, it sets the specified option | | 2817 | If options are given, it sets the specified option |
2818 | flags, or clears them as described in the | | 2818 | flags, or clears them as described in the |
2819 | .Sx Argument List Processing | | 2819 | .Sx Argument List Processing |
2820 | section. | | 2820 | section. |
2821 | In addition to the options listed there, | | 2821 | In addition to the options listed there, |
2822 | when the | | 2822 | when the |
2823 | .Dq "option name" | | 2823 | .Dq "option name" |
2824 | given to | | 2824 | given to |
2825 | .Ic set Fl o | | 2825 | .Ic set Fl o |
2826 | is | | 2826 | is |
2827 | .Cm default | | 2827 | .Cm default |
2828 | all of the options are reset to the values they had immediately | | 2828 | all of the options are reset to the values they had immediately |
2829 | after | | 2829 | after |
2830 | .Nm | | 2830 | .Nm |
2831 | initialization, before any startup scripts, or other input, had been processed. | | 2831 | initialization, before any startup scripts, or other input, had been processed. |
2832 | While this may be of use to users or scripts, its primary purpose | | 2832 | While this may be of use to users or scripts, its primary purpose |
2833 | is for use in the output of | | 2833 | is for use in the output of |
2834 | .Dq Ic set Cm +o , | | 2834 | .Dq Ic set Cm +o , |
2835 | to avoid that command needing to list every available option. | | 2835 | to avoid that command needing to list every available option. |
2836 | There is no | | 2836 | There is no |
2837 | .Cm +o default . | | 2837 | .Cm +o default . |
2838 | .Pp | | 2838 | .Pp |
2839 | The fourth use of the set command is to set the values of the shell's | | 2839 | The fourth use of the set command is to set the values of the shell's |
2840 | positional parameters to the specified arguments. | | 2840 | positional parameters to the specified arguments. |
2841 | To change the positional | | 2841 | To change the positional |
2842 | parameters without changing any options, use | | 2842 | parameters without changing any options, use |
2843 | .Dq -\|- | | 2843 | .Dq -\|- |
2844 | as the first argument to set. | | 2844 | as the first argument to set. |
2845 | If no following arguments are present, the set command | | 2845 | If no following arguments are present, the set command |
2846 | will clear all the positional parameters (equivalent to executing | | 2846 | will clear all the positional parameters (equivalent to executing |
2847 | .Dq shift $# . ) | | 2847 | .Dq shift $# . ) |
2848 | Otherwise the following arguments become | | 2848 | Otherwise the following arguments become |
2849 | .Dq \&$1 , | | 2849 | .Dq \&$1 , |
2850 | .Dq \&$2 , | | 2850 | .Dq \&$2 , |
2851 | \&..., | | 2851 | \&..., |
2852 | and | | 2852 | and |
2853 | .Dq \&$# | | 2853 | .Dq \&$# |
2854 | is set to the number of arguments present. | | 2854 | is set to the number of arguments present. |
2855 | .It setvar Ar variable Ar value | | 2855 | .It setvar Ar variable Ar value |
2856 | Assigns value to variable. | | 2856 | Assigns value to variable. |
2857 | (In general it is better to write | | 2857 | (In general it is better to write |
2858 | variable=value rather than using | | 2858 | variable=value rather than using |
2859 | .Ic setvar . | | 2859 | .Ic setvar . |
2860 | .Ic setvar | | 2860 | .Ic setvar |
2861 | is intended to be used in | | 2861 | is intended to be used in |
2862 | functions that assign values to variables whose names are passed as | | 2862 | functions that assign values to variables whose names are passed as |
2863 | parameters.) | | 2863 | parameters.) |
2864 | .It shift Op Ar n | | 2864 | .It shift Op Ar n |
2865 | Shift the positional parameters n times. | | 2865 | Shift the positional parameters n times. |
2866 | If n is omitted, 1 is assumed. | | 2866 | If n is omitted, 1 is assumed. |
2867 | Each | | 2867 | Each |
2868 | .Ic shift | | 2868 | .Ic shift |
2869 | sets the value of | | 2869 | sets the value of |
2870 | .Va $1 | | 2870 | .Va $1 |
2871 | to the previous value of | | 2871 | to the previous value of |
2872 | .Va $2 , | | 2872 | .Va $2 , |
2873 | the value of | | 2873 | the value of |
2874 | .Va $2 | | 2874 | .Va $2 |
2875 | to the previous value of | | 2875 | to the previous value of |
2876 | .Va $3 , | | 2876 | .Va $3 , |
2877 | and so on, decreasing | | 2877 | and so on, decreasing |
2878 | the value of | | 2878 | the value of |
2879 | .Va $# | | 2879 | .Va $# |
2880 | by one. | | 2880 | by one. |
2881 | The shift count must be less than or equal to the number of | | 2881 | The shift count must be less than or equal to the number of |
2882 | positional parameters ( | | 2882 | positional parameters ( |
2883 | .Dq $# ) | | 2883 | .Dq $# ) |
2884 | before the shift. | | 2884 | before the shift. |
2885 | .It times | | 2885 | .It times |
2886 | Prints two lines to standard output. | | 2886 | Prints two lines to standard output. |
2887 | Each line contains two accumulated time values, expressed | | 2887 | Each line contains two accumulated time values, expressed |
2888 | in minutes and seconds (including fractions of a second.) | | 2888 | in minutes and seconds (including fractions of a second.) |
2889 | The first value gives the user time consumed, the second the system time. | | 2889 | The first value gives the user time consumed, the second the system time. |
2890 | .Pp | | 2890 | .Pp |
2891 | The first output line gives the CPU and system times consumed by the | | 2891 | The first output line gives the CPU and system times consumed by the |
2892 | shell itself. | | 2892 | shell itself. |
2893 | The second line gives the accumulated times for children of this | | 2893 | The second line gives the accumulated times for children of this |
2894 | shell (and their descendants) which have exited, and then been | | 2894 | shell (and their descendants) which have exited, and then been |
2895 | successfully waited for by the relevant parent. | | 2895 | successfully waited for by the relevant parent. |
2896 | See | | 2896 | See |
2897 | .Xr times 3 | | 2897 | .Xr times 3 |
2898 | for more information. | | 2898 | for more information. |
2899 | .Pp | | 2899 | .Pp |
2900 | .Ic times | | 2900 | .Ic times |
2901 | has no parameters, and exits with an exit status of 0 unless | | 2901 | has no parameters, and exits with an exit status of 0 unless |
2902 | an attempt is made to give it an option. | | 2902 | an attempt is made to give it an option. |
2903 | .It trap Ar action signal ... | | 2903 | .It trap Ar action signal ... |
2904 | .It trap \- | | 2904 | .It trap \- |
2905 | .It trap Oo Fl l Oc | | 2905 | .It trap Oo Fl l Oc |
2906 | .It trap Oo Fl p Oc signal ... | | 2906 | .It trap Oo Fl p Oc signal ... |
2907 | .It trap Ar N signal ... | | 2907 | .It trap Ar N signal ... |
2908 | .Pp | | 2908 | .Pp |
2909 | Cause the shell to parse and execute action when any of the specified | | 2909 | Cause the shell to parse and execute action when any of the specified |
2910 | signals are received. | | 2910 | signals are received. |
2911 | The signals are specified by signal number or as the name of the signal. | | 2911 | The signals are specified by signal number or as the name of the signal. |
2912 | If | | 2912 | If |
2913 | .Ar signal | | 2913 | .Ar signal |
2914 | is | | 2914 | is |
2915 | .Li 0 | | 2915 | .Li 0 |
2916 | or its equivalent, EXIT, | | 2916 | or its equivalent, EXIT, |
2917 | the action is executed when the shell exits. | | 2917 | the action is executed when the shell exits. |
2918 | The | | 2918 | The |
2919 | .Ar action | | 2919 | .Ar action |
2920 | may be a null (empty) string, | | 2920 | may be a null (empty) string, |
2921 | which causes the specified signals to be ignored. | | 2921 | which causes the specified signals to be ignored. |
2922 | With | | 2922 | With |
2923 | .Ar action | | 2923 | .Ar action |
2924 | set to | | 2924 | set to |
2925 | .Sq - | | 2925 | .Sq - |
2926 | the specified signals are set to their default actions. | | 2926 | the specified signals are set to their default actions. |
2927 | If the first | | 2927 | If the first |
2928 | .Ar signal | | 2928 | .Ar signal |
2929 | is specified in its numeric form, then | | 2929 | is specified in its numeric form, then |
2930 | .Ar action | | 2930 | .Ar action |
2931 | can be omitted to achieve the same effect. | | 2931 | can be omitted to achieve the same effect. |
2932 | This archaic, | | 2932 | This archaic, |
2933 | but still standard, | | 2933 | but still standard, |
2934 | form should not be relied upon, use the explicit | | 2934 | form should not be relied upon, use the explicit |
2935 | .Sq - | | 2935 | .Sq - |
2936 | action. | | 2936 | action. |
2937 | If no signals are specified with an action of | | 2937 | If no signals are specified with an action of |
2938 | .Sq - , | | 2938 | .Sq - , |
2939 | all signals are reset. | | 2939 | all signals are reset. |
2940 | .Pp | | 2940 | .Pp |
2941 | When the shell forks off a sub-shell, it resets trapped (but not ignored) | | 2941 | When the shell forks off a sub-shell, it resets trapped (but not ignored) |
2942 | signals to the default action. | | 2942 | signals to the default action. |
2943 | On non-interactive shells, the | | 2943 | On non-interactive shells, the |
2944 | .Ic trap | | 2944 | .Ic trap |
2945 | command has no effect on signals that were | | 2945 | command has no effect on signals that were |
2946 | ignored on entry to the shell. | | 2946 | ignored on entry to the shell. |
2947 | On interactive shells, the | | 2947 | On interactive shells, the |
2948 | .Ic trap | | 2948 | .Ic trap |
2949 | command will catch or reset signals ignored on entry. | | 2949 | command will catch or reset signals ignored on entry. |
2950 | .Pp | | 2950 | .Pp |
2951 | Issuing | | 2951 | Issuing |
2952 | .Ic trap | | 2952 | .Ic trap |
2953 | with option | | 2953 | with option |
2954 | .Fl l | | 2954 | .Fl l |
2955 | will print a list of valid signal names. | | 2955 | will print a list of valid signal names. |
2956 | .Ic trap | | 2956 | .Ic trap |
2957 | without any arguments causes it to write a list of signals and their | | 2957 | without any arguments causes it to write a list of signals and their |
2958 | associated non-default actions to the standard output in a format | | 2958 | associated non-default actions to the standard output in a format |
2959 | that is suitable as an input to the shell that achieves the same | | 2959 | that is suitable as an input to the shell that achieves the same |
2960 | trapping results. | | 2960 | trapping results. |
2961 | With the | | 2961 | With the |
2962 | .Fl p | | 2962 | .Fl p |
2963 | flag, trap prints the same information for the signals specified, | | 2963 | flag, trap prints the same information for the signals specified, |
2964 | or if none are given, for all signals, including those where the | | 2964 | or if none are given, for all signals, including those where the |
2965 | action is the default. | | 2965 | action is the default. |
2966 | .Pp | | 2966 | .Pp |
2967 | Examples: | | 2967 | Examples: |
2968 | .Pp | | 2968 | .Pp |
2969 | .Dl trap | | 2969 | .Dl trap |
2970 | .Pp | | 2970 | .Pp |
2971 | List trapped signals and their corresponding actions. | | 2971 | List trapped signals and their corresponding actions. |
2972 | .Pp | | 2972 | .Pp |
2973 | .Dl trap -l | | 2973 | .Dl trap -l |
2974 | .Pp | | 2974 | .Pp |
2975 | Print a list of valid signals. | | 2975 | Print a list of valid signals. |
2976 | .Pp | | 2976 | .Pp |
2977 | .Dl trap '' INT QUIT tstp 30 | | 2977 | .Dl trap '' INT QUIT tstp 30 |
2978 | .Pp | | 2978 | .Pp |
2979 | Ignore signals INT QUIT TSTP USR1. | | 2979 | Ignore signals INT QUIT TSTP USR1. |
2980 | .Pp | | 2980 | .Pp |
2981 | .Dl trap date INT | | 2981 | .Dl trap date INT |
2982 | .Pp | | 2982 | .Pp |
2983 | Run the | | 2983 | Run the |
2984 | .Dq date | | 2984 | .Dq date |
2985 | command (print the date) upon receiving signal INT. | | 2985 | command (print the date) upon receiving signal INT. |
2986 | .Pp | | 2986 | .Pp |
2987 | .Dl trap HUP INT | | 2987 | .Dl trap HUP INT |
2988 | .Pp | | 2988 | .Pp |
2989 | Run the | | 2989 | Run the |
2990 | .Dq HUP | | 2990 | .Dq HUP |
2991 | command, or function, upon receiving signal INT. | | 2991 | command, or function, upon receiving signal INT. |
2992 | .Pp | | 2992 | .Pp |
2993 | .Dl trap 1 2 | | 2993 | .Dl trap 1 2 |
2994 | .Pp | | 2994 | .Pp |
2995 | Reset the actions for signals 1 (HUP) and 2 (INT) to their defaults. | | 2995 | Reset the actions for signals 1 (HUP) and 2 (INT) to their defaults. |
2996 | .Bd -literal -offset indent | | 2996 | .Bd -literal -offset indent |
2997 | traps=$(trap -p) | | 2997 | traps=$(trap -p) |
2998 | # more commands ... | | 2998 | # more commands ... |
2999 | trap 'action' SIG | | 2999 | trap 'action' SIG |
3000 | # more commands ... | | 3000 | # more commands ... |
3001 | eval "$traps" | | 3001 | eval "$traps" |
3002 | .Ed | | 3002 | .Ed |
3003 | .Pp | | 3003 | .Pp |
3004 | Save the trap status, execute commands, changing some traps, | | 3004 | Save the trap status, execute commands, changing some traps, |
3005 | and then reset all traps to their values at the start of the sequence. | | 3005 | and then reset all traps to their values at the start of the sequence. |
3006 | The | | 3006 | The |
3007 | .Fl p | | 3007 | .Fl p |
3008 | option is required in the first command here, | | 3008 | option is required in the first command here, |
3009 | or any signals that were previously | | 3009 | or any signals that were previously |
3010 | untrapped (in their default states) | | 3010 | untrapped (in their default states) |
3011 | and which were altered during the intermediate code, | | 3011 | and which were altered during the intermediate code, |
3012 | would not be reset by the final | | 3012 | would not be reset by the final |
3013 | .Dq eval . | | 3013 | .Dq eval . |
3014 | .It type Op Ar name ... | | 3014 | .It type Op Ar name ... |
3015 | Interpret each name as a command and print the resolution of the command | | 3015 | Interpret each name as a command and print the resolution of the command |
3016 | search. | | 3016 | search. |
3017 | Possible resolutions are: | | 3017 | Possible resolutions are: |
3018 | shell keyword, alias, shell built-in, | | 3018 | shell keyword, alias, shell built-in, |
3019 | command, tracked alias and not found. | | 3019 | command, tracked alias and not found. |
3020 | For aliases the alias expansion is | | 3020 | For aliases the alias expansion is |
3021 | printed; for commands and tracked aliases the complete pathname of the | | 3021 | printed; for commands and tracked aliases the complete pathname of the |
3022 | command is printed. | | 3022 | command is printed. |
3023 | .It ulimit Oo Fl H \*(Ba Fl S Oc Oo Fl a \*(Ba Fl btfdscmlrpnv Oo Ar value Oc Oc | | 3023 | .It ulimit Oo Fl H \*(Ba Fl S Oc Oo Fl a \*(Ba Fl btfdscmlrpnv Oo Ar value Oc Oc |
3024 | Inquire about or set the hard or soft limits on processes or set new | | 3024 | Inquire about or set the hard or soft limits on processes or set new |
3025 | limits. | | 3025 | limits. |
3026 | The choice between hard limit (which no process is allowed to | | 3026 | The choice between hard limit (which no process is allowed to |
3027 | violate, and which may not be raised once it has been lowered) and soft | | 3027 | violate, and which may not be raised once it has been lowered) and soft |
3028 | limit (which causes processes to be signaled but not necessarily killed, | | 3028 | limit (which causes processes to be signaled but not necessarily killed, |
3029 | and which may be raised) is made with these flags: | | 3029 | and which may be raised) is made with these flags: |
3030 | .Bl -tag -width Fl | | 3030 | .Bl -tag -width Fl |
3031 | .It Fl H | | 3031 | .It Fl H |
3032 | set or inquire about hard limits | | 3032 | set or inquire about hard limits |
3033 | .It Fl S | | 3033 | .It Fl S |
3034 | set or inquire about soft limits. | | 3034 | set or inquire about soft limits. |
3035 | If neither | | 3035 | If neither |
3036 | .Fl H | | 3036 | .Fl H |
3037 | nor | | 3037 | nor |
3038 | .Fl S | | 3038 | .Fl S |
3039 | is specified, the soft limit is displayed or both limits are set. | | 3039 | is specified, the soft limit is displayed or both limits are set. |
3040 | If both are specified, the last one wins. | | 3040 | If both are specified, the last one wins. |
3041 | .El | | 3041 | .El |
3042 | .Pp | | 3042 | .Pp |
3043 | The limit to be interrogated or set, then, is chosen by specifying | | 3043 | The limit to be interrogated or set, then, is chosen by specifying |
3044 | any one of these flags: | | 3044 | any one of these flags: |
3045 | .Bl -tag -width Fl | | 3045 | .Bl -tag -width Fl |
3046 | .It Fl a | | 3046 | .It Fl a |
3047 | show all the current limits | | 3047 | show all the current limits |
3048 | .It Fl b | | 3048 | .It Fl b |
3049 | show or set the limit on the socket buffer size of a process (in bytes) | | 3049 | show or set the limit on the socket buffer size of a process (in bytes) |
3050 | .It Fl c | | 3050 | .It Fl c |
3051 | show or set the limit on the largest core dump size that can be produced | | 3051 | show or set the limit on the largest core dump size that can be produced |
3052 | (in 512-byte blocks) | | 3052 | (in 512-byte blocks) |
3053 | .It Fl d | | 3053 | .It Fl d |
3054 | show or set the limit on the data segment size of a process (in kilobytes) | | 3054 | show or set the limit on the data segment size of a process (in kilobytes) |
3055 | .It Fl f | | 3055 | .It Fl f |
3056 | show or set the limit on the largest file that can be created | | 3056 | show or set the limit on the largest file that can be created |
3057 | (in 512-byte blocks) | | 3057 | (in 512-byte blocks) |
3058 | .It Fl l | | 3058 | .It Fl l |
3059 | show or set the limit on how much memory a process can lock with | | 3059 | show or set the limit on how much memory a process can lock with |
3060 | .Xr mlock 2 | | 3060 | .Xr mlock 2 |
3061 | (in kilobytes) | | 3061 | (in kilobytes) |
3062 | .It Fl m | | 3062 | .It Fl m |
3063 | show or set the limit on the total physical memory that can be | | 3063 | show or set the limit on the total physical memory that can be |
3064 | in use by a process (in kilobytes) | | 3064 | in use by a process (in kilobytes) |
3065 | .It Fl n | | 3065 | .It Fl n |
3066 | show or set the limit on the number of files a process can have open at once | | 3066 | show or set the limit on the number of files a process can have open at once |
3067 | .It Fl p | | 3067 | .It Fl p |
3068 | show or set the limit on the number of processes this user can | | 3068 | show or set the limit on the number of processes this user can |
3069 | have at one time | | 3069 | have at one time |
3070 | .It Fl r | | 3070 | .It Fl r |
3071 | show or set the limit on the number of threads this user can | | 3071 | show or set the limit on the number of threads this user can |
3072 | have at one time | | 3072 | have at one time |
3073 | .It Fl s | | 3073 | .It Fl s |
3074 | show or set the limit on the stack size of a process (in kilobytes) | | 3074 | show or set the limit on the stack size of a process (in kilobytes) |
3075 | .It Fl t | | 3075 | .It Fl t |
3076 | show or set the limit on CPU time (in seconds) | | 3076 | show or set the limit on CPU time (in seconds) |
3077 | .It Fl v | | 3077 | .It Fl v |
3078 | show or set the limit on how large a process address space can be | | 3078 | show or set the limit on how large a process address space can be |
3079 | .El | | 3079 | .El |
3080 | .Pp | | 3080 | .Pp |
3081 | If none of these is specified, it is the limit on file size that is shown | | 3081 | If none of these is specified, it is the limit on file size that is shown |
3082 | or set. | | 3082 | or set. |
3083 | If value is specified, the limit is set to that number; otherwise | | 3083 | If value is specified, the limit is set to that number; otherwise |
3084 | the current limit is displayed. | | 3084 | the current limit is displayed. |
3085 | .Pp | | 3085 | .Pp |
3086 | Limits of an arbitrary process can be displayed or set using the | | 3086 | Limits of an arbitrary process can be displayed or set using the |
3087 | .Xr sysctl 8 | | 3087 | .Xr sysctl 8 |
3088 | utility. | | 3088 | utility. |
3089 | .It umask Oo Fl S Oc Op Ar mask | | 3089 | .It umask Oo Fl S Oc Op Ar mask |
3090 | Set the value of umask (see | | 3090 | Set the value of umask (see |
3091 | .Xr umask 2 ) | | 3091 | .Xr umask 2 ) |
3092 | to the specified octal value. | | 3092 | to the specified octal value. |
3093 | If the argument is omitted, the umask value is printed. | | 3093 | If the argument is omitted, the umask value is printed. |
3094 | With | | 3094 | With |
3095 | .Fl S | | 3095 | .Fl S |
3096 | a symbolic form is used instead of an octal number. | | 3096 | a symbolic form is used instead of an octal number. |
3097 | .It unalias Oo Fl a Oc Oo Ar name Oc | | 3097 | .It unalias Oo Fl a Oc Oo Ar name Oc |
3098 | If | | 3098 | If |
3099 | .Ar name | | 3099 | .Ar name |
3100 | is specified, the shell removes that alias. | | 3100 | is specified, the shell removes that alias. |
3101 | If | | 3101 | If |
3102 | .Fl a | | 3102 | .Fl a |
3103 | is specified, all aliases are removed. | | 3103 | is specified, all aliases are removed. |
3104 | .It unset Oo Fl efvx Oc Ar name ... | | 3104 | .It unset Oo Fl efvx Oc Ar name ... |
3105 | If | | 3105 | If |
3106 | .Fl v | | 3106 | .Fl v |
3107 | is specified, the specified variables are unset and unexported. | | 3107 | is specified, the specified variables are unset and unexported. |
3108 | Readonly variables cannot be unset. | | 3108 | Readonly variables cannot be unset. |
3109 | If | | 3109 | If |
3110 | .Fl f | | 3110 | .Fl f |
3111 | is specified, the specified functions are undefined. | | 3111 | is specified, the specified functions are undefined. |
3112 | If | | 3112 | If |
3113 | .Fl e | | 3113 | .Fl e |
3114 | is given, the specified variables are unexported, but otherwise unchanged, | | 3114 | is given, the specified variables are unexported, but otherwise unchanged, |
3115 | alternatively, if | | 3115 | alternatively, if |
3116 | .Fl x | | 3116 | .Fl x |
3117 | is given, the exported status of the variable will be retained, | | 3117 | is given, the exported status of the variable will be retained, |
3118 | even after it is unset. | | 3118 | even after it is unset. |
3119 | .Pp | | 3119 | .Pp |
3120 | If no flags are provided | | 3120 | If no flags are provided |
3121 | .Fl v | | 3121 | .Fl v |
3122 | is assumed. | | 3122 | is assumed. |
3123 | If | | 3123 | If |
3124 | .Fl f | | 3124 | .Fl f |
3125 | is given with one of the other flags, | | 3125 | is given with one of the other flags, |
3126 | then the named variables will be unset, or unexported, and functions | | 3126 | then the named variables will be unset, or unexported, and functions |
3127 | of the same names will be undefined. | | 3127 | of the same names will be undefined. |
3128 | The | | 3128 | The |
3129 | .Fl e | | 3129 | .Fl e |
3130 | and | | 3130 | and |
3131 | .Fl x | | 3131 | .Fl x |
3132 | flags both imply | | 3132 | flags both imply |
3133 | .Fl v . | | 3133 | .Fl v . |
3134 | If | | 3134 | If |
3135 | .Fl e | | 3135 | .Fl e |
3136 | is given, the | | 3136 | is given, the |
3137 | .Fl x | | 3137 | .Fl x |
3138 | flag is ignored. | | 3138 | flag is ignored. |
3139 | .Pp | | 3139 | .Pp |
3140 | The exit status is 0, unless an attempt was made to unset | | 3140 | The exit status is 0, unless an attempt was made to unset |
3141 | a readonly variable, in which case the exit status is 1. | | 3141 | a readonly variable, in which case the exit status is 1. |
3142 | It is not an error to unset (or undefine) a variable (or function) | | 3142 | It is not an error to unset (or undefine) a variable (or function) |
3143 | that is not currently set (or defined.) | | 3143 | that is not currently set (or defined.) |
3144 | .It wait Oo Fl n Oc Oo Fl p Ar var Oc Op Ar job ... | | 3144 | .It wait Oo Fl n Oc Oo Fl p Ar var Oc Op Ar job ... |
3145 | Wait for the specified jobs to complete | | 3145 | Wait for the specified jobs to complete |
3146 | and return the exit status of the last job in the parameter list, | | 3146 | and return the exit status of the last job in the parameter list, |
3147 | or 127 if that job is not a current child of the shell. | | 3147 | or 127 if that job is not a current child of the shell. |
3148 | .Pp | | 3148 | .Pp |
3149 | If no | | 3149 | If no |
3150 | .Ar job | | 3150 | .Ar job |
3151 | arguments are given, wait for all jobs to | | 3151 | arguments are given, wait for all jobs to |
3152 | complete and then return an exit status of zero | | 3152 | complete and then return an exit status of zero |
3153 | (including when there were no jobs, and so nothing exited.) | | 3153 | (including when there were no jobs, and so nothing exited.) |
3154 | .Pp | | 3154 | .Pp |
3155 | With the | | 3155 | With the |
3156 | .Fl n | | 3156 | .Fl n |
3157 | option, wait instead for any one of the given | | 3157 | option, wait instead for any one of the given |
3158 | .Ar job Ns s, | | 3158 | .Ar job Ns s, |
3159 | or if none are given, any job, to complete, and | | 3159 | or if none are given, any job, to complete, and |
3160 | return the exit status of that job. | | 3160 | return the exit status of that job. |
3161 | If none of the given | | 3161 | If none of the given |
3162 | .Ar job | | 3162 | .Ar job |
3163 | arguments is a current child of the shell, | | 3163 | arguments is a current child of the shell, |
3164 | or if no | | 3164 | or if no |
3165 | .Ar job | | 3165 | .Ar job |
3166 | arguments are given and the shell has no unwaited for children, | | 3166 | arguments are given and the shell has no unwaited for children, |
3167 | then the exit status will be 127. | | 3167 | then the exit status will be 127. |
3168 | .Pp | | 3168 | .Pp |
3169 | The | | 3169 | The |
3170 | .Fl p Ar var | | 3170 | .Fl p Ar var |
3171 | option allows the process (or job) identifier of the | | 3171 | option allows the process (or job) identifier of the |
3172 | job for which the exit status is returned to be obtained. | | 3172 | job for which the exit status is returned to be obtained. |
3173 | The variable named (which must not be readonly) will be | | 3173 | The variable named (which must not be readonly) will be |
3174 | unset initially, then if a job has exited and its status is | | 3174 | unset initially, then if a job has exited and its status is |
3175 | being returned, set to the identifier from the | | 3175 | being returned, set to the identifier from the |
3176 | arg list (if given) of that job, | | 3176 | arg list (if given) of that job, |
3177 | or the lead process identifier of the job to exit when used with | | 3177 | or the lead process identifier of the job to exit when used with |
3178 | .Fl n | | 3178 | .Fl n |
3179 | and no job arguments. | | 3179 | and no job arguments. |
3180 | Note that | | 3180 | Note that |
3181 | .Fl p | | 3181 | .Fl p |
3182 | with neither | | 3182 | with neither |
3183 | .Fl n | | 3183 | .Fl n |
3184 | nor | | 3184 | nor |
3185 | .Ar job | | 3185 | .Ar job |
3186 | arguments is useless, as in that case no job status is | | 3186 | arguments is useless, as in that case no job status is |
3187 | returned, the variable named is simply unset. | | 3187 | returned, the variable named is simply unset. |
3188 | .Pp | | 3188 | .Pp |
3189 | If the wait is interrupted by a signal, | | 3189 | If the wait is interrupted by a signal, |
3190 | its exit status will be greater than 128, | | 3190 | its exit status will be greater than 128, |
3191 | and | | 3191 | and |
3192 | .Ar var , | | 3192 | .Ar var , |
3193 | if given, will remain unset. | | 3193 | if given, will remain unset. |
3194 | .Pp | | 3194 | .Pp |
3195 | Once waited upon, by specific process number or job-id, | | 3195 | Once waited upon, by specific process number or job-id, |
3196 | or by a | | 3196 | or by a |
3197 | .Ic wait | | 3197 | .Ic wait |
3198 | with no arguments, | | 3198 | with no arguments, |
3199 | knowledge of the child is removed from the system, | | 3199 | knowledge of the child is removed from the system, |
3200 | and it cannot be waited upon again. | | 3200 | and it cannot be waited upon again. |
3201 | .Pp | | 3201 | .Pp |
3202 | Note than when a list of jobs are given, more that | | 3202 | Note than when a list of jobs are given, more that |
3203 | one argument might refer to the same job. | | 3203 | one argument might refer to the same job. |
3204 | In that case, if the final argument represents a job | | 3204 | In that case, if the final argument represents a job |
3205 | that is also given earlier in the list, it is not | | 3205 | that is also given earlier in the list, it is not |
3206 | defined whether the status returned will be the | | 3206 | defined whether the status returned will be the |
3207 | exit status of the job, or 127 indicating that | | 3207 | exit status of the job, or 127 indicating that |
3208 | the child no longer existed when the wait command | | 3208 | the child no longer existed when the wait command |
3209 | reached the later argument in the list. | | 3209 | reached the later argument in the list. |
3210 | In this | | 3210 | In this |
3211 | .Nm | | 3211 | .Nm |
3212 | the exit status will be that from the job. | | 3212 | the exit status will be that from the job. |
3213 | .Nm | | 3213 | .Nm |
3214 | waits for each job exactly once, regardless of | | 3214 | waits for each job exactly once, regardless of |
3215 | how many times (or how many different ways) it | | 3215 | how many times (or how many different ways) it |
3216 | is listed in the arguments to | | 3216 | is listed in the arguments to |
3217 | .Ic wait . | | 3217 | .Ic wait . |
3218 | That is | | 3218 | That is |
3219 | .Bd -literal -compact | | 3219 | .Bd -literal -compact |
3220 | wait 100 100 100 | | 3220 | wait 100 100 100 |
3221 | .Ed | | 3221 | .Ed |
3222 | is identical to | | 3222 | is identical to |
3223 | .Bd -literal -compact | | 3223 | .Bd -literal -compact |
3224 | wait 100 | | 3224 | wait 100 |
3225 | .Ed | | 3225 | .Ed |
3226 | .El | | 3226 | .El |
3227 | .Ss Job Control | | 3227 | .Ss Job Control |
3228 | Each process (or set of processes) started by | | 3228 | Each process (or set of processes) started by |
3229 | .Nm | | 3229 | .Nm |
3230 | is created as a | | 3230 | is created as a |
3231 | .Dq job | | 3231 | .Dq job |
3232 | and added to the jobs table. | | 3232 | and added to the jobs table. |
3233 | When enabled by the | | 3233 | When enabled by the |
3234 | .Fl m | | 3234 | .Fl m |
3235 | option | | 3235 | option |
3236 | .Pq aka Fl o Ar monitor | | 3236 | .Pq aka Fl o Ar monitor |
3237 | when the job is created, | | 3237 | when the job is created, |
3238 | .Nm | | 3238 | .Nm |
3239 | places each job (if run from the top level shell) | | 3239 | places each job (if run from the top level shell) |
3240 | into a process group of its own, which allows control | | 3240 | into a process group of its own, which allows control |
3241 | of the process(es), and its/their descendants, as a unit. | | 3241 | of the process(es), and its/their descendants, as a unit. |
3242 | When the | | 3242 | When the |
3243 | .Fl m | | 3243 | .Fl m |
3244 | option is off, or when started from a sub-shell environment, | | 3244 | option is off, or when started from a sub-shell environment, |
3245 | jobs share the same process group as the parent shell. | | 3245 | jobs share the same process group as the parent shell. |
3246 | The | | 3246 | The |
3247 | .Fl m | | 3247 | .Fl m |
3248 | option is enabled by default in interactive shells with | | 3248 | option is enabled by default in interactive shells with |
3249 | a terminal as standard input and standard error. | | 3249 | a terminal as standard input and standard error. |
3250 | .Pp | | 3250 | .Pp |
3251 | Jobs with separate process groups may be stopped, and then later | | 3251 | Jobs with separate process groups may be stopped, and then later |
3252 | resumed in the foreground (with access to the terminal) | | 3252 | resumed in the foreground (with access to the terminal) |
3253 | or in the background (where attempting to read from the | | 3253 | or in the background (where attempting to read from the |
3254 | terminal will result in the job stopping.) | | 3254 | terminal will result in the job stopping.) |
3255 | A list of current jobs can be obtained using the | | 3255 | A list of current jobs can be obtained using the |
3256 | .Ic jobs | | 3256 | .Ic jobs |
3257 | built-in command. | | 3257 | built-in command. |
3258 | Jobs are identified using either the process identifier | | 3258 | Jobs are identified using either the process identifier |
3259 | of the lead process of the job (the value available in | | 3259 | of the lead process of the job (the value available in |
3260 | the special parameter | | 3260 | the special parameter |
3261 | .Sq \&$! | | 3261 | .Sq \&$! |
3262 | if the job is started in the background), or using percent | | 3262 | if the job is started in the background), or using percent |
3263 | notation. | | 3263 | notation. |
3264 | Each job is given a | | 3264 | Each job is given a |
3265 | .Dq job number | | 3265 | .Dq job number |
3266 | which is a small integer, starting from 1, and can be | | 3266 | which is a small integer, starting from 1, and can be |
3267 | referenced as | | 3267 | referenced as |
3268 | .Sq \&%n | | 3268 | .Sq \&%n |
3269 | where n is that number. | | 3269 | where n is that number. |
3270 | Note that this applies to jobs both with and without their own process groups. | | 3270 | Note that this applies to jobs both with and without their own process groups. |
3271 | Job numbers are shown in the output from the | | 3271 | Job numbers are shown in the output from the |
3272 | .Ic jobs | | 3272 | .Ic jobs |
3273 | command enclosed in brackets | | 3273 | command enclosed in brackets |
3274 | .Po | | 3274 | .Po |
3275 | .Sq \&[ | | 3275 | .Sq \&[ |
3276 | and | | 3276 | and |
3277 | .Sq \&] | | 3277 | .Sq \&] |
3278 | .Pc . | | 3278 | .Pc . |
3279 | Whenever the job table becomes empty, the numbers begin at one again. | | 3279 | Whenever the job table becomes empty, the numbers begin at one again. |
3280 | In addition, there is the concept of a current, and a previous job, | | 3280 | In addition, there is the concept of a current, and a previous job, |
3281 | identified by | | 3281 | identified by |
3282 | .Sq \&%+ | | 3282 | .Sq \&%+ |
3283 | .Po | | 3283 | .Po |
3284 | or | | 3284 | or |
3285 | .Sq \&%% | | 3285 | .Sq \&%% |
3286 | or even just | | 3286 | or even just |
3287 | .Sq \&% | | 3287 | .Sq \&% |
3288 | .Pc , | | 3288 | .Pc , |
3289 | and a previous job, identified by | | 3289 | and a previous job, identified by |
3290 | .Sq \&%\- . | | 3290 | .Sq \&%\- . |
3291 | Whenever a background job is started, | | 3291 | Whenever a background job is started, |
3292 | or a job is resumed in the background, | | 3292 | or a job is resumed in the background, |
3293 | it becomes the current job. | | 3293 | it becomes the current job. |
3294 | The job that was the current job | | 3294 | The job that was the current job |
3295 | (prepare for a big surprise here, drum roll..., wait for it...\&) | | 3295 | (prepare for a big surprise here, drum roll..., wait for it...\&) |
3296 | becomes the previous job. | | 3296 | becomes the previous job. |
3297 | When the current job terminates, the previous job is | | 3297 | When the current job terminates, the previous job is |
3298 | promoted to be the current job. | | 3298 | promoted to be the current job. |
3299 | In addition the form | | 3299 | In addition the form |
3300 | .Dq %string | | 3300 | .Dq %string |
3301 | finds the job for which the command starts with | | 3301 | finds the job for which the command starts with |
3302 | .Dq string | | 3302 | .Dq string |
3303 | and the form | | 3303 | and the form |
3304 | .Dq %?string | | 3304 | .Dq %?string |
3305 | finds the job which contains the | | 3305 | finds the job which contains the |
3306 | .Dq string | | 3306 | .Dq string |
3307 | in its command somewhere. | | 3307 | in its command somewhere. |
3308 | Both forms require the result to be unambiguous. | | 3308 | Both forms require the result to be unambiguous. |
3309 | For this purpose the | | 3309 | For this purpose the |
3310 | .Dq command | | 3310 | .Dq command |
3311 | is that shown in the output from the | | 3311 | is that shown in the output from the |
3312 | .Ic jobs | | 3312 | .Ic jobs |
3313 | command, not the original command line. | | 3313 | command, not the original command line. |
3314 | .Pp | | 3314 | .Pp |
3315 | The | | 3315 | The |
3316 | .Ic bg , | | 3316 | .Ic bg , |
3317 | .Ic fg , | | 3317 | .Ic fg , |
3318 | .Ic jobid , | | 3318 | .Ic jobid , |
3319 | .Ic jobs , | | 3319 | .Ic jobs , |
3320 | .Ic kill , | | 3320 | .Ic kill , |
3321 | and | | 3321 | and |
3322 | .Ic wait | | 3322 | .Ic wait |
3323 | commands all accept job identifiers as arguments, in addition to | | 3323 | commands all accept job identifiers as arguments, in addition to |
3324 | process identifiers (larger integers). | | 3324 | process identifiers (larger integers). |
3325 | See the | | 3325 | See the |
3326 | .Sx Built-ins | | 3326 | .Sx Built-ins |
3327 | section above, and | | 3327 | section above, and |
3328 | .Xr kill 1 , | | 3328 | .Xr kill 1 , |
3329 | for more details of those commands. | | 3329 | for more details of those commands. |
3330 | In addition, a job identifier | | 3330 | In addition, a job identifier |
3331 | .Pq using one of the Sq \&% forms | | 3331 | .Pq using one of the Sq \&% forms |
3332 | issued as a command, without arguments, is interpreted as | | 3332 | issued as a command, without arguments, is interpreted as |
3333 | if it had been given as the argument to the | | 3333 | if it had been given as the argument to the |
3334 | .Ic fg | | 3334 | .Ic fg |
3335 | command. | | 3335 | command. |
3336 | .Pp | | 3336 | .Pp |
3337 | To cause a foreground process to stop, enter the terminal's | | 3337 | To cause a foreground process to stop, enter the terminal's |
3338 | .Ic stop | | 3338 | .Ic stop |
3339 | character (usually control-Z). | | 3339 | character (usually control-Z). |
3340 | To cause a background process to stop, send it a | | 3340 | To cause a background process to stop, send it a |
3341 | .Dv STOP | | 3341 | .Dv STOP |
3342 | signal, using the kill command. | | 3342 | signal, using the kill command. |
3343 | A useful function to define is | | 3343 | A useful function to define is |
3344 | .Bd -literal -compact | | 3344 | .Bd -literal -compact |
3345 | stop() { kill -s STOP "${@:-%%}"; } | | 3345 | stop() { kill -s STOP "${@:-%%}"; } |
3346 | .Ed | | 3346 | .Ed |
3347 | .Pp | | 3347 | .Pp |
3348 | The | | 3348 | The |
3349 | .Ic fg | | 3349 | .Ic fg |
3350 | command resumes a stopped job, placing it in the foreground, | | 3350 | command resumes a stopped job, placing it in the foreground, |
3351 | and | | 3351 | and |
3352 | .Ic bg | | 3352 | .Ic bg |
3353 | resumes a stopped job in the background. | | 3353 | resumes a stopped job in the background. |
3354 | The | | 3354 | The |
3355 | .Ic jobid | | 3355 | .Ic jobid |
3356 | command provides information about process identifiers, job identifiers, | | 3356 | command provides information about process identifiers, job identifiers, |
3357 | and the process group identifier, for a job. | | 3357 | and the process group identifier, for a job. |
3358 | .Pp | | 3358 | .Pp |
3359 | Whenever a sub-shell is created, the jobs table becomes invalid | | 3359 | Whenever a sub-shell is created, the jobs table becomes invalid |
3360 | (the sub-shell has no children.) | | 3360 | (the sub-shell has no children.) |
3361 | However, to enable uses like | | 3361 | However, to enable uses like |
3362 | .Bd -literal -compact | | 3362 | .Bd -literal -compact |
3363 | PID=$(jobid -p %1) | | 3363 | PID=$(jobid -p %1) |
3364 | .Ed | | 3364 | .Ed |
3365 | the table is only actually cleared in a sub-shell when needed to | | 3365 | the table is only actually cleared in a sub-shell when needed to |
3366 | create the first job there (built-in commands run in the foreground | | 3366 | create the first job there (built-in commands run in the foreground |
3367 | do not create jobs.) | | 3367 | do not create jobs.) |
3368 | Note that in this environment, there is no useful current job | | 3368 | Note that in this environment, there is no useful current job |
3369 | (%% actually refers to the sub-shell itself, but is not accessible) | | 3369 | (%% actually refers to the sub-shell itself, but is not accessible) |
3370 | but the job which is the current job in the parent can be accessed as %\-. | | 3370 | but the job which is the current job in the parent can be accessed as %\-. |
3371 | .Ss Command Line Editing | | 3371 | .Ss Command Line Editing |
3372 | When | | 3372 | When |
3373 | .Nm | | 3373 | .Nm |
3374 | is being used interactively from a terminal, the current command | | 3374 | is being used interactively from a terminal, the current command |
3375 | and the command history (see | | 3375 | and the command history (see |
3376 | .Ic fc | | 3376 | .Ic fc |
3377 | in the | | 3377 | in the |
3378 | .Sx Built-ins | | 3378 | .Sx Built-ins |
3379 | section) | | 3379 | section) |
3380 | can be edited using emacs-mode or vi-mode command-line editing. | | 3380 | can be edited using emacs-mode or vi-mode command-line editing. |
3381 | The command | | 3381 | The command |
3382 | .Ql set -o emacs | | 3382 | .Ql set -o emacs |
3383 | enables emacs-mode editing. | | 3383 | enables emacs-mode editing. |
3384 | The command | | 3384 | The command |
3385 | .Ql set -o vi | | 3385 | .Ql set -o vi |
3386 | enables vi-mode editing and places the current shell process into | | 3386 | enables vi-mode editing and places the current shell process into |
3387 | .Ar vi | | 3387 | .Ar vi |
3388 | insert mode. | | 3388 | insert mode. |
3389 | (See the | | 3389 | (See the |
3390 | .Sx Argument List Processing | | 3390 | .Sx Argument List Processing |
3391 | section above.) | | 3391 | section above.) |
3392 | .Pp | | 3392 | .Pp |
3393 | The | | 3393 | The |
3394 | .Ar vi | | 3394 | .Ar vi |
3395 | mode uses commands similar to a subset of those described in the | | 3395 | mode uses commands similar to a subset of those described in the |
3396 | .Xr vi 1 | | 3396 | .Xr vi 1 |
3397 | man page. | | 3397 | man page. |
3398 | With vi-mode | | 3398 | With vi-mode |
3399 | enabled, | | 3399 | enabled, |
3400 | .Nm sh | | 3400 | .Nm sh |
3401 | can be switched between insert mode and command mode. | | 3401 | can be switched between insert mode and command mode. |
3402 | It's similar to | | 3402 | It's similar to |
3403 | .Xr vi 1 : | | 3403 | .Xr vi 1 : |
3404 | pressing the | | 3404 | pressing the |
3405 | .Aq ESC | | 3405 | .Aq ESC |
3406 | key will throw you into command VI command mode. | | 3406 | key will throw you into command VI command mode. |
3407 | Pressing the | | 3407 | Pressing the |
3408 | .Aq return | | 3408 | .Aq return |
3409 | key while in command mode will pass the line to the shell. | | 3409 | key while in command mode will pass the line to the shell. |
3410 | .Pp | | 3410 | .Pp |
3411 | The | | 3411 | The |
3412 | .Ar emacs | | 3412 | .Ar emacs |
3413 | mode uses commands similar to a subset available in the | | 3413 | mode uses commands similar to a subset available in the |
3414 | .Ic emacs | | 3414 | .Ic emacs |
3415 | editor. | | 3415 | editor. |
3416 | With emacs-mode enabled, special keys can be used to modify the text | | 3416 | With emacs-mode enabled, special keys can be used to modify the text |
3417 | in the buffer using the control key. | | 3417 | in the buffer using the control key. |
3418 | .Pp | | 3418 | .Pp |
3419 | .Nm | | 3419 | .Nm |
3420 | uses the | | 3420 | uses the |
3421 | .Xr editline 3 | | 3421 | .Xr editline 3 |
3422 | library. | | 3422 | library. |
3423 | See | | 3423 | See |
3424 | .Xr editline 7 | | 3424 | .Xr editline 7 |
3425 | for a list of the possible command bindings, | | 3425 | for a list of the possible command bindings, |
3426 | and the default settings in | | 3426 | and the default settings in |
3427 | .Ar emacs | | 3427 | .Ar emacs |
3428 | and | | 3428 | and |
3429 | .Ar vi | | 3429 | .Ar vi |
3430 | modes. | | 3430 | modes. |
3431 | Also see | | 3431 | Also see |
3432 | .Xr editrc 5 | | 3432 | .Xr editrc 5 |
3433 | for the commands that can be given to configure | | 3433 | for the commands that can be given to configure |
3434 | .Xr editline 7 | | 3434 | .Xr editline 7 |
3435 | in the file named by the | | 3435 | in the file named by the |
3436 | .Ev EDITRC | | 3436 | .Ev EDITRC |
3437 | parameter, | | 3437 | parameter, |
3438 | or a file used with the | | 3438 | or a file used with the |
3439 | .Ic inputrc | | 3439 | .Ic inputrc |
3440 | built-in command, | | 3440 | built-in command, |
3441 | or using | | 3441 | or using |
3442 | .Xr editline 7 Ap s | | 3442 | .Xr editline 7 Ap s |
3443 | configuration command line. | | 3443 | configuration command line. |
3444 | .Pp | | 3444 | .Pp |
3445 | When command line editing is enabled, the | | 3445 | When command line editing is enabled, the |
3446 | .Xr editline 7 | | 3446 | .Xr editline 7 |
3447 | functions control printing of the | | 3447 | functions control printing of the |
3448 | .Ev PS1 | | 3448 | .Ev PS1 |
3449 | and | | 3449 | and |
3450 | .Ev PS2 | | 3450 | .Ev PS2 |
3451 | prompts when required. | | 3451 | prompts when required. |
3452 | As, in this mode, the command line editor needs to | | 3452 | As, in this mode, the command line editor needs to |
3453 | keep track of what characters are in what position on | | 3453 | keep track of what characters are in what position on |
3454 | the command line, care needs to be taken when setting | | 3454 | the command line, care needs to be taken when setting |
3455 | the prompts. | | 3455 | the prompts. |
3456 | Normal printing characters are handled automatically, | | 3456 | Normal printing characters are handled automatically, |
3457 | however mode setting sequences, which do not actually display | | 3457 | however mode setting sequences, which do not actually display |
3458 | on the terminal, need to be identified to | | 3458 | on the terminal, need to be identified to |
3459 | .Xr editline 7 . | | 3459 | .Xr editline 7 . |
3460 | This is done, when needed, by choosing a character that | | 3460 | This is done, when needed, by choosing a character that |
3461 | is not needed anywhere in the prompt, including in the mode | | 3461 | is not needed anywhere in the prompt, including in the mode |
3462 | setting sequences, any single character is acceptable, | | 3462 | setting sequences, any single character is acceptable, |
3463 | and assigning it to the shell parameter | | 3463 | and assigning it to the shell parameter |
3464 | .Ev PSlit . | | 3464 | .Ev PSlit . |
3465 | Then that character should be used, in pairs, in the | | 3465 | Then that character should be used, in pairs, in the |
3466 | prompt string. | | 3466 | prompt string. |
3467 | Between each pair of | | 3467 | Between each pair of |
3468 | .Ev PSlit | | 3468 | .Ev PSlit |
3469 | characters are mode setting sequences, which affect the printing | | 3469 | characters are mode setting sequences, which affect the printing |
3470 | attributes of the following (normal) characters of the prompt, | | 3470 | attributes of the following (normal) characters of the prompt, |
3471 | but do not themselves appear visibly, nor change the terminal's | | 3471 | but do not themselves appear visibly, nor change the terminal's |
3472 | cursor position. | | 3472 | cursor position. |
3473 | .Pp | | 3473 | .Pp |
3474 | Each such sequence, that is | | 3474 | Each such sequence, that is |
3475 | .Ev PSlit | | 3475 | .Ev PSlit |
3476 | character, mode setting character sequence, and another | | 3476 | character, mode setting character sequence, and another |
3477 | .Ev PSlit | | 3477 | .Ev PSlit |
3478 | character, must currently be followed by at least one following | | 3478 | character, must currently be followed by at least one following |
3479 | normal prompt character, or it will be ignored. | | 3479 | normal prompt character, or it will be ignored. |
3480 | That is, a | | 3480 | That is, a |
3481 | .Ev PSlit | | 3481 | .Ev PSlit |
3482 | character cannot be the final character of | | 3482 | character cannot be the final character of |
3483 | .Ev PS1 | | 3483 | .Ev PS1 |
3484 | or | | 3484 | or |
3485 | .Ev PS2 , | | 3485 | .Ev PS2 , |
3486 | nor may two | | 3486 | nor may two |
3487 | .Ev PSlit | | 3487 | .Ev PSlit |
3488 | delimited sequences appear adjacent to each other. | | 3488 | delimited sequences appear adjacent to each other. |
3489 | Each sequence can contain as many mode altering sequences as are | | 3489 | Each sequence can contain as many mode altering sequences as are |
3490 | required however. | | 3490 | required however. |
3491 | Only the first character from | | 3491 | Only the first character from |
3492 | .Ev PSlit | | 3492 | .Ev PSlit |
3493 | will be used. | | 3493 | will be used. |
3494 | When set | | 3494 | When set |
3495 | .Ev PSlit | | 3495 | .Ev PSlit |
3496 | should usually be set to a string containing just one | | 3496 | should usually be set to a string containing just one |
3497 | character, then it can simply be embedded in | | 3497 | character, then it can simply be embedded in |
3498 | .Ev PS1 | | 3498 | .Ev PS1 |
3499 | (or | | 3499 | (or |
3500 | .Ev PS2 ) | | 3500 | .Ev PS2 ) |
3501 | as in | | 3501 | as in |
3502 | .Dl PS1="${PSlit}mset${PSlit}XYZ${PSlit}mclr${PSlit}ABC" | | 3502 | .Dl PS1="${PSlit}mset${PSlit}XYZ${PSlit}mclr${PSlit}ABC" |
3503 | The prompt visible will be | | 3503 | The prompt visible will be |
3504 | .Dq XYZABC | | 3504 | .Dq XYZABC |
3505 | with the | | 3505 | with the |
3506 | .Dq XYZ | | 3506 | .Dq XYZ |
3507 | part shown according as defined by the mode setting characters | | 3507 | part shown according as defined by the mode setting characters |
3508 | .Dq mset , | | 3508 | .Dq mset , |
3509 | and then cleared again by | | 3509 | and then cleared again by |
3510 | .Dq mclr . | | 3510 | .Dq mclr . |
3511 | See | | 3511 | See |
3512 | .Xr tput 1 | | 3512 | .Xr tput 1 |
3513 | for one method to generate appropriate mode sequences. | | 3513 | for one method to generate appropriate mode sequences. |
3514 | Note that both parts, XYZ and ABC, must each contain at least one | | 3514 | Note that both parts, XYZ and ABC, must each contain at least one |
3515 | character. | | 3515 | character. |
3516 | .Pp | | 3516 | .Pp |
3517 | If | | 3517 | If |
3518 | .Ev PSlit | | 3518 | .Ev PSlit |
3519 | is unset, which is its initial state, or set to a null string, | | 3519 | is unset, which is its initial state, or set to a null string, |
3520 | no literal character will be defined, | | 3520 | no literal character will be defined, |
3521 | and all characters of the prompt strings will be assumed | | 3521 | and all characters of the prompt strings will be assumed |
3522 | to be visible characters (which includes spaces etc.) | | 3522 | to be visible characters (which includes spaces etc.) |
3523 | To allow smooth use of prompts, without needing redefinition, when | | 3523 | To allow smooth use of prompts, without needing redefinition, when |
3524 | .Xr editline 7 | | 3524 | .Xr editline 7 |
3525 | is disabled, the character chosen should be one which will be | | 3525 | is disabled, the character chosen should be one which will be |
3526 | ignored by the terminal if received, as when | | 3526 | ignored by the terminal if received, as when |
3527 | .Xr editline 7 | | 3527 | .Xr editline 7 |
3528 | is not in use, the prompt strings are simply written to the terminal. | | 3528 | is not in use, the prompt strings are simply written to the terminal. |
3529 | For example, setting: | | 3529 | For example, setting: |
3530 | .Bd -compact -literal -offset left | | 3530 | .Bd -literal -offset left -compact |
3531 | PSlit="$(printf\ '\e1')" | | 3531 | PSlit="$(printf\ '\e1')" |
3532 | PS1="${PSlit}$(tput\ bold\ blink)${PSlit}\e$${PSlit}$(tput\ sgr0)${PSlit}\ " | | 3532 | PS1="${PSlit}$(tput\ bold\ blink)${PSlit}\e$${PSlit}$(tput\ sgr0)${PSlit}\ " |
3533 | .Ed | | 3533 | .Ed |
3534 | will arrange for the primary prompt to be a bold blinking dollar sign, | | 3534 | will arrange for the primary prompt to be a bold blinking dollar sign, |
3535 | if supported by the current terminal, followed by an (ordinary) space, | | 3535 | if supported by the current terminal, followed by an (ordinary) space, |
3536 | and, as the SOH (Control-A) character ('\e1') will not normally affect | | 3536 | and, as the SOH (Control-A) character ('\e1') will not normally affect |
3537 | a terminal, this same prompt will usually work with | | 3537 | a terminal, this same prompt will usually work with |
3538 | .Xr editline 7 | | 3538 | .Xr editline 7 |
3539 | enabled or disabled. | | 3539 | enabled or disabled. |
3540 | .Sh ENVIRONMENT | | 3540 | .Sh ENVIRONMENT |
3541 | .Bl -tag -width MAILCHECK | | 3541 | .Bl -tag -width MAILCHECK |
3542 | .It Ev CDPATH | | 3542 | .It Ev CDPATH |
3543 | The search path used with the | | 3543 | The search path used with the |
3544 | .Ic cd | | 3544 | .Ic cd |
3545 | built-in. | | 3545 | built-in. |
3546 | .It Ev EDITRC | | 3546 | .It Ev EDITRC |
3547 | Gives the name of the file containing commands for | | 3547 | Gives the name of the file containing commands for |
3548 | .Xr editline 7 . | | 3548 | .Xr editline 7 . |
3549 | See | | 3549 | See |
3550 | .Xr editrc 5 | | 3550 | .Xr editrc 5 |
3551 | for possible content and format. | | 3551 | for possible content and format. |
3552 | The file is processed, when in interactive mode with | | 3552 | The file is processed, when in interactive mode with |
3553 | command line editing enabled, whenever | | 3553 | command line editing enabled, whenever |
3554 | .Ev EDITRC | | 3554 | .Ev EDITRC |
3555 | is set (even with no actual value change,) | | 3555 | is set (even with no actual value change,) |
3556 | and if command line editing changes from disabled to enabled, | | 3556 | and if command line editing changes from disabled to enabled, |
3557 | or the editor style used is changed. | | 3557 | or the editor style used is changed. |
3558 | (See the | | 3558 | (See the |
3559 | .Fl E | | 3559 | .Fl E |
3560 | and | | 3560 | and |
3561 | .Fl V | | 3561 | .Fl V |
3562 | options of the | | 3562 | options of the |
3563 | .Ic set | | 3563 | .Ic set |
3564 | built-in command, described in | | 3564 | built-in command, described in |
3565 | .Sx Built-ins | | 3565 | .Sx Built-ins |
3566 | above, which are documented further above in | | 3566 | above, which are documented further above in |
3567 | .Sx Argument List Processing . ) | | 3567 | .Sx Argument List Processing . ) |
3568 | If unset | | 3568 | If unset |
3569 | .Dq $HOME/.editrc | | 3569 | .Dq $HOME/.editrc |
3570 | is used. | | 3570 | is used. |
3571 | .It Ev HISTSIZE | | 3571 | .It Ev HISTSIZE |
3572 | The number of lines in the history buffer for the shell. | | 3572 | The number of lines in the history buffer for the shell. |
3573 | .It Ev HOME | | 3573 | .It Ev HOME |
3574 | Set automatically by | | 3574 | Set automatically by |
3575 | .Xr login 1 | | 3575 | .Xr login 1 |
3576 | from the user's login directory in the password file | | 3576 | from the user's login directory in the password file |
3577 | .Pq Xr passwd 5 . | | 3577 | .Pq Xr passwd 5 . |
3578 | This environment variable also functions as the default argument for the | | 3578 | This environment variable also functions as the default argument for the |
3579 | .Ic cd | | 3579 | .Ic cd |
3580 | built-in. | | 3580 | built-in. |
3581 | .It Ev HOSTNAME | | 3581 | .It Ev HOSTNAME |
3582 | Set to the current hostname of the system, as returned by | | 3582 | Set to the current hostname of the system, as returned by |
3583 | .Xr gethostname 3 . | | 3583 | .Xr gethostname 3 . |
3584 | This is obtained each time | | 3584 | This is obtained each time |
3585 | .Ev HOSTNAME | | 3585 | .Ev HOSTNAME |
3586 | is expanded, so changes to the system's name are reflected | | 3586 | is expanded, so changes to the system's name are reflected |
3587 | without further action. | | 3587 | without further action. |
3588 | If unset, it returns nothing. | | 3588 | If unset, it returns nothing. |
3589 | Setting it does nothing except reverse the effect of an earlier | | 3589 | Setting it does nothing except reverse the effect of an earlier |
3590 | .Ic unset . | | 3590 | .Ic unset . |
3591 | .It Ev IFS | | 3591 | .It Ev IFS |
3592 | Input Field Separators. | | 3592 | Input Field Separators. |
3593 | This is normally set to | | 3593 | This is normally set to |
3594 | .Aq space , | | 3594 | .Aq space , |
3595 | .Aq tab , | | 3595 | .Aq tab , |
3596 | and | | 3596 | and |
3597 | .Aq newline . | | 3597 | .Aq newline . |
3598 | See the | | 3598 | See the |
3599 | .Sx White Space Splitting | | 3599 | .Sx White Space Splitting |
3600 | section for more details. | | 3600 | section for more details. |
3601 | .It Ev LANG | | 3601 | .It Ev LANG |
3602 | The string used to specify localization information that allows users | | 3602 | The string used to specify localization information that allows users |
3603 | to work with different culture-specific and language conventions. | | 3603 | to work with different culture-specific and language conventions. |
3604 | See | | 3604 | See |
3605 | .Xr nls 7 . | | 3605 | .Xr nls 7 . |
3606 | .It Ev LINENO | | 3606 | .It Ev LINENO |
3607 | The current line number in the script or function. | | 3607 | The current line number in the script or function. |
3608 | See the section | | 3608 | See the section |
3609 | .Sx LINENO | | 3609 | .Sx LINENO |
3610 | below for more details. | | 3610 | below for more details. |
3611 | .It Ev MAIL | | 3611 | .It Ev MAIL |
3612 | The name of a mail file, that will be checked for the arrival of new mail. | | 3612 | The name of a mail file, that will be checked for the arrival of new mail. |
3613 | Overridden by | | 3613 | Overridden by |
3614 | .Ev MAILPATH . | | 3614 | .Ev MAILPATH . |
3615 | The check occurs just before | | 3615 | The check occurs just before |
3616 | .Ev PS1 | | 3616 | .Ev PS1 |
3617 | is written, immediately after reporting jobs which have changed status, | | 3617 | is written, immediately after reporting jobs which have changed status, |
3618 | in interactive shells only. | | 3618 | in interactive shells only. |
3619 | New mail is considered to have arrived if the monitored file | | 3619 | New mail is considered to have arrived if the monitored file |
3620 | has increased in size since the last check. | | 3620 | has increased in size since the last check. |
3621 | .\" .It Ev MAILCHECK | | 3621 | .\" .It Ev MAILCHECK |
3622 | .\" The frequency in seconds that the shell checks for the arrival of mail | | 3622 | .\" The frequency in seconds that the shell checks for the arrival of mail |
3623 | .\" in the files specified by the | | 3623 | .\" in the files specified by the |
3624 | .\" .Ev MAILPATH | | 3624 | .\" .Ev MAILPATH |
3625 | .\" or the | | 3625 | .\" or the |
3626 | .\" .Ev MAIL | | 3626 | .\" .Ev MAIL |
3627 | .\" file. | | 3627 | .\" file. |
3628 | .\" If set to 0, the check will occur at each prompt. | | 3628 | .\" If set to 0, the check will occur at each prompt. |
3629 | .It Ev MAILPATH | | 3629 | .It Ev MAILPATH |
3630 | A colon | | 3630 | A colon |
3631 | .Dq \&: | | 3631 | .Dq \&: |
3632 | separated list of file names, for the shell to check for incoming mail. | | 3632 | separated list of file names, for the shell to check for incoming mail. |
3633 | This environment setting overrides the | | 3633 | This environment setting overrides the |
3634 | .Ev MAIL | | 3634 | .Ev MAIL |
3635 | setting. | | 3635 | setting. |
3636 | There is a maximum of 10 mailboxes that can be monitored at once. | | 3636 | There is a maximum of 10 mailboxes that can be monitored at once. |
3637 | .It Ev PATH | | 3637 | .It Ev PATH |
3638 | The default search path for executables. | | 3638 | The default search path for executables. |
3639 | See the | | 3639 | See the |
3640 | .Sx Path Search | | 3640 | .Sx Path Search |
3641 | section above. | | 3641 | section above. |
3642 | .It Ev PPID | | 3642 | .It Ev PPID |
3643 | The process identified of the parent process of the | | 3643 | The process identified of the parent process of the |
3644 | current shell. | | 3644 | current shell. |
3645 | This value is set at shell startup, ignoring | | 3645 | This value is set at shell startup, ignoring |
3646 | any value in the environment, and then made readonly. | | 3646 | any value in the environment, and then made readonly. |
3647 | .It Ev PS1 | | 3647 | .It Ev PS1 |
3648 | The primary prompt string, which defaults to | | 3648 | The primary prompt string, which defaults to |
3649 | .Dq $ \ , | | 3649 | .Dq $ \ , |
3650 | unless you are the superuser, in which case it defaults to | | 3650 | unless you are the superuser, in which case it defaults to |
3651 | .Dq # \ . | | 3651 | .Dq # \ . |
3652 | This string is subject to parameter, arithmetic, and if | | 3652 | This string is subject to parameter, arithmetic, and if |
3653 | enabled by setting the | | 3653 | enabled by setting the |
3654 | .Ic promptcmds | | 3654 | .Ic promptcmds |
3655 | option, command substitution before being output. | | 3655 | option, command substitution before being output. |
3656 | During execution of commands used by command substitution, | | 3656 | During execution of commands used by command substitution, |
3657 | execution tracing, the | | 3657 | execution tracing, the |
3658 | .Ic xtrace | | 3658 | .Ic xtrace |
3659 | .Ic ( set Fl x ) | | 3659 | .Ic ( set Fl x ) |
3660 | option is temporarily disabled. | | 3660 | option is temporarily disabled. |
3661 | If | | 3661 | If |
3662 | .Ic promptcmds | | 3662 | .Ic promptcmds |
3663 | is not set and the prompt string uses command substitution, | | 3663 | is not set and the prompt string uses command substitution, |
3664 | the prompt used will be an appropriate error string. | | 3664 | the prompt used will be an appropriate error string. |
3665 | For other expansion errors, a message will be output, | | 3665 | For other expansion errors, a message will be output, |
3666 | and the unexpanded string will then be used as the prompt. | | 3666 | and the unexpanded string will then be used as the prompt. |
3667 | .It Ev PS2 | | 3667 | .It Ev PS2 |
3668 | The secondary prompt string, which defaults to | | 3668 | The secondary prompt string, which defaults to |
3669 | .Dq > \ . | | 3669 | .Dq > \ . |
3670 | After expansion (as for | | 3670 | After expansion (as for |
3671 | .Ev PS1 ) | | 3671 | .Ev PS1 ) |
3672 | it is written whenever more input is required to complete the | | 3672 | it is written whenever more input is required to complete the |
3673 | current command. | | 3673 | current command. |
3674 | .It Ev PS4 | | 3674 | .It Ev PS4 |
3675 | Output, after expansion like | | 3675 | Output, after expansion like |
3676 | .Ev PS1 , | | 3676 | .Ev PS1 , |
3677 | before each line when execution trace | | 3677 | before each line when execution trace |
3678 | .Ic ( set Fl x ) | | 3678 | .Ic ( set Fl x ) |
3679 | is enabled. | | 3679 | is enabled. |
3680 | .Ev PS4 | | 3680 | .Ev PS4 |
3681 | defaults to | | 3681 | defaults to |
3682 | .Dq + \ . | | 3682 | .Dq + \ . |
3683 | .It Ev PSc | | 3683 | .It Ev PSc |
3684 | Initialized by the shell, ignoring any value from the environment, | | 3684 | Initialized by the shell, ignoring any value from the environment, |
3685 | to a single character string, either | | 3685 | to a single character string, either |
3686 | .Sq \&# | | 3686 | .Sq \&# |
3687 | or | | 3687 | or |
3688 | .Sq \&$ , | | 3688 | .Sq \&$ , |
3689 | depending upon whether the current user is the superuser or not. | | 3689 | depending upon whether the current user is the superuser or not. |
3690 | This is intended for use when building a custom | | 3690 | This is intended for use when building a custom |
3691 | .Ev PS1 . | | 3691 | .Ev PS1 . |
3692 | .It Ev PSlit | | 3692 | .It Ev PSlit |
3693 | Defines the character which may be embedded in pairs, in | | 3693 | Defines the character which may be embedded in pairs, in |
3694 | .Ev PS1 | | 3694 | .Ev PS1 |
3695 | or | | 3695 | or |
3696 | .Ev PS2 | | 3696 | .Ev PS2 |
3697 | to indicate to | | 3697 | to indicate to |
3698 | .Xr editline 7 | | 3698 | .Xr editline 7 |
3699 | that the characters between each pair of occurrences of the | | 3699 | that the characters between each pair of occurrences of the |
3700 | .Ev PSlit | | 3700 | .Ev PSlit |
3701 | character will not appear in the visible prompt, and will not | | 3701 | character will not appear in the visible prompt, and will not |
3702 | cause the terminal's cursor to change position, but rather set terminal | | 3702 | cause the terminal's cursor to change position, but rather set terminal |
3703 | attributes for the following prompt character(s) at least one of | | 3703 | attributes for the following prompt character(s) at least one of |
3704 | which must be present. | | 3704 | which must be present. |
3705 | See | | 3705 | See |
3706 | .Sx Command Line Editing | | 3706 | .Sx Command Line Editing |
3707 | above for more information. | | 3707 | above for more information. |
3708 | .It Ev RANDOM | | 3708 | .It Ev RANDOM |
3709 | Returns a different pseudo-random integer, | | 3709 | Returns a different pseudo-random integer, |
3710 | in the range [0,32767] each time it is accessed. | | 3710 | in the range [0,32767] each time it is accessed. |
3711 | .Ev RANDOM | | 3711 | .Ev RANDOM |
3712 | can be assigned an integer value to seed the PRNG. | | 3712 | can be assigned an integer value to seed the PRNG. |
3713 | If the value assigned is a constant, then the | | 3713 | If the value assigned is a constant, then the |
3714 | sequence of values produces on subsequent references of | | 3714 | sequence of values produces on subsequent references of |
3715 | .Ev RANDOM | | 3715 | .Ev RANDOM |
3716 | will repeat after the next time the same constant is assigned. | | 3716 | will repeat after the next time the same constant is assigned. |
3717 | Note, this is not guaranteed to remain constant from one version | | 3717 | Note, this is not guaranteed to remain constant from one version |
3718 | of the shell to another \(en the PRNG algorithm, or seeding | | 3718 | of the shell to another \(en the PRNG algorithm, or seeding |
3719 | method is subject to change. | | 3719 | method is subject to change. |
3720 | If | | 3720 | If |
3721 | .Ev RANDOM | | 3721 | .Ev RANDOM |
3722 | is assigned an empty value (null string) then the next time | | 3722 | is assigned an empty value (null string) then the next time |
3723 | .Ev RANDOM | | 3723 | .Ev RANDOM |
3724 | is accessed, it will be seeded from a more genuinely random source. | | 3724 | is accessed, it will be seeded from a more genuinely random source. |
3725 | The sequence of pseudo-random numbers generated will not be able to | | 3725 | The sequence of pseudo-random numbers generated will not be able to |
3726 | be generated again (except by luck, whether good or bad, depends!) | | 3726 | be generated again (except by luck, whether good or bad, depends!) |
3727 | This is also how the initial seed is generated, if none has been | | 3727 | This is also how the initial seed is generated, if none has been |
3728 | assigned before | | 3728 | assigned before |
3729 | .Ev RANDOM | | 3729 | .Ev RANDOM |
3730 | is first accessed after shell initialization. | | 3730 | is first accessed after shell initialization. |
3731 | .It Ev SECONDS | | 3731 | .It Ev SECONDS |
3732 | Returns the number of seconds since the current shell was started. | | 3732 | Returns the number of seconds since the current shell was started. |
3733 | Attempts to set this variable are ignored. | | 3733 | Attempts to set this variable are ignored. |
3734 | If unset, it remains unset, and returns nothing, unless set again. | | 3734 | If unset, it remains unset, and returns nothing, unless set again. |
3735 | .It Ev START_TIME | | 3735 | .It Ev START_TIME |
3736 | Initialized by the shell to the number of seconds since the Epoch | | 3736 | Initialized by the shell to the number of seconds since the Epoch |
3737 | (see | | 3737 | (see |
3738 | .Xr localtime 3 ) | | 3738 | .Xr localtime 3 ) |
3739 | when the shell was started. | | 3739 | when the shell was started. |
3740 | The value of | | 3740 | The value of |
3741 | .Dl $(( Ns Ev START_TIME + Ev SECONDS Ns )) | | 3741 | .Dl $(( Ns Ev START_TIME + Ev SECONDS Ns )) |
3742 | represents the current time, if | | 3742 | represents the current time, if |
3743 | .Ev START_TIME | | 3743 | .Ev START_TIME |
3744 | has not been modified, and | | 3744 | has not been modified, and |
3745 | .Ev SECONDS | | 3745 | .Ev SECONDS |
3746 | is not unset. | | 3746 | is not unset. |
3747 | .It Ev TERM | | 3747 | .It Ev TERM |
3748 | The default terminal setting for the shell. | | 3748 | The default terminal setting for the shell. |
3749 | This is inherited by | | 3749 | This is inherited by |
3750 | children of the shell, and is used in the history editing modes. | | 3750 | children of the shell, and is used in the history editing modes. |
3751 | .\" This is explicitly last, not in sort order - please leave! | | 3751 | .\" This is explicitly last, not in sort order - please leave! |
3752 | .It Ev ToD | | 3752 | .It Ev ToD |
3753 | When referenced, uses the value of | | 3753 | When referenced, uses the value of |
3754 | .Ev ToD_FORMAT | | 3754 | .Ev ToD_FORMAT |
3755 | (or | | 3755 | (or |
3756 | .Dq \&%T | | 3756 | .Dq \&%T |
3757 | if | | 3757 | if |
3758 | .Ev ToD_FORMAT | | 3758 | .Ev ToD_FORMAT |
3759 | is unset) as the format argument to | | 3759 | is unset) as the format argument to |
3760 | .Xr strftime 3 | | 3760 | .Xr strftime 3 |
3761 | to encode the current time of day, in the time zone | | 3761 | to encode the current time of day, in the time zone |
3762 | defined by | | 3762 | defined by |
3763 | .Ev TZ | | 3763 | .Ev TZ |
3764 | if set, or current local time if not, and returns the result. | | 3764 | if set, or current local time if not, and returns the result. |
3765 | If unset | | 3765 | If unset |
3766 | .Ev ToD | | 3766 | .Ev ToD |
3767 | returns nothing. | | 3767 | returns nothing. |
3768 | Setting it has no effect, other than to reverse the effect of an earlier | | 3768 | Setting it has no effect, other than to reverse the effect of an earlier |
3769 | .Ic unset . | | 3769 | .Ic unset . |
3770 | .It Ev ToD_FORMAT | | 3770 | .It Ev ToD_FORMAT |
3771 | Can be set to the | | 3771 | Can be set to the |
3772 | .Xr strftime 3 | | 3772 | .Xr strftime 3 |
3773 | format string to be used when expanding | | 3773 | format string to be used when expanding |
3774 | .Ev ToD . | | 3774 | .Ev ToD . |
3775 | Initially unset. | | 3775 | Initially unset. |
3776 | .It Ev TZ | | 3776 | .It Ev TZ |
3777 | If set, gives the time zone | | 3777 | If set, gives the time zone |
3778 | (see | | 3778 | (see |
3779 | .Xr localtime 3 , | | 3779 | .Xr localtime 3 , |
3780 | .Xr environ 7 ) | | 3780 | .Xr environ 7 ) |
3781 | to use when formatting | | 3781 | to use when formatting |
3782 | .Ev ToD | | 3782 | .Ev ToD |
3783 | and if exported, other utilities that deal with times. | | 3783 | and if exported, other utilities that deal with times. |
3784 | If unset, the system's local wall clock time zone is used. | | 3784 | If unset, the system's local wall clock time zone is used. |
3785 | .It Ev NETBSD_SHELL | | 3785 | .It Ev NETBSD_SHELL |
3786 | Unlike the variables previously mentioned, | | 3786 | Unlike the variables previously mentioned, |
3787 | this variable is somewhat strange, | | 3787 | this variable is somewhat strange, |
3788 | in that it cannot be set, | | 3788 | in that it cannot be set, |
3789 | inherited from the environment, | | 3789 | inherited from the environment, |
3790 | modified, or exported from the shell. | | 3790 | modified, or exported from the shell. |
3791 | If set, by the shell, it indicates that the shell is the | | 3791 | If set, by the shell, it indicates that the shell is the |
3792 | .Ic sh | | 3792 | .Ic sh |
3793 | defined by this manual page, and gives its version information. | | 3793 | defined by this manual page, and gives its version information. |
3794 | It can also give information in additional space separated words, | | 3794 | It can also give information in additional space separated words, |
3795 | after the version string. | | 3795 | after the version string. |
3796 | If the shell was built as part of a reproducible build, | | 3796 | If the shell was built as part of a reproducible build, |
3797 | the relevant date that was used for that build will be included. | | 3797 | the relevant date that was used for that build will be included. |
3798 | Finally, any non-standard compilation options, | | 3798 | Finally, any non-standard compilation options, |
3799 | which may affect features available, | | 3799 | which may affect features available, |
3800 | that were used when building the shell will be listed. | | 3800 | that were used when building the shell will be listed. |
3801 | .Ev NETBSD_SHELL | | 3801 | .Ev NETBSD_SHELL |
3802 | behaves like any other variable that has the read-only | | 3802 | behaves like any other variable that has the read-only |
3803 | and un-exportable attributes set. | | 3803 | and un-exportable attributes set. |
3804 | .El | | 3804 | .El |
3805 | .Ss Ev LINENO | | 3805 | .Ss Ev LINENO |
3806 | .Ev LINENO | | 3806 | .Ev LINENO |
3807 | is in many respects a normal shell variable, containing an | | 3807 | is in many respects a normal shell variable, containing an |
3808 | integer value. and can be expanded using any of the forms | | 3808 | integer value. and can be expanded using any of the forms |
3809 | mentioned above which can be used for any other variable. | | 3809 | mentioned above which can be used for any other variable. |
3810 | .Pp | | 3810 | .Pp |
3811 | .Ev LINENO | | 3811 | .Ev LINENO |
3812 | can be exported, made readonly, or unset, as with any other | | 3812 | can be exported, made readonly, or unset, as with any other |
3813 | variable, with similar effects. | | 3813 | variable, with similar effects. |
3814 | Note that while being readonly prevents later attempts to | | 3814 | Note that while being readonly prevents later attempts to |
3815 | set, or unset, | | 3815 | set, or unset, |
3816 | .Ev LINENO , | | 3816 | .Ev LINENO , |
3817 | it does not prevent its value changing. | | 3817 | it does not prevent its value changing. |
3818 | References to | | 3818 | References to |
3819 | .Ev LINENO | | 3819 | .Ev LINENO |
3820 | .Pq "when not unset" | | 3820 | .Pq "when not unset" |
3821 | always obtain the current line number. | | 3821 | always obtain the current line number. |
3822 | However, | | 3822 | However, |
3823 | .Ev LINENO | | 3823 | .Ev LINENO |
3824 | should normally not ever be set or unset. | | 3824 | should normally not ever be set or unset. |
3825 | In this shell setting | | 3825 | In this shell setting |
3826 | .Ev LINENO | | 3826 | .Ev LINENO |
3827 | reverses the effect of an earlier | | 3827 | reverses the effect of an earlier |
3828 | .Ic unset , | | 3828 | .Ic unset , |
3829 | but does not otherwise affect the value obtained. | | 3829 | but does not otherwise affect the value obtained. |
3830 | If unset, | | 3830 | If unset, |
3831 | .Ev LINENO | | 3831 | .Ev LINENO |
3832 | should not normally be set again, doing so is not portable. | | 3832 | should not normally be set again, doing so is not portable. |
3833 | If | | 3833 | If |
3834 | .Ev LINENO | | 3834 | .Ev LINENO |
3835 | is set or unset, different shells act differently. | | 3835 | is set or unset, different shells act differently. |
3836 | The value of | | 3836 | The value of |
3837 | .Ev LINENO | | 3837 | .Ev LINENO |
3838 | is never imported from the environment when the shell is | | 3838 | is never imported from the environment when the shell is |
3839 | started, though if present there, as with any other variable, | | 3839 | started, though if present there, as with any other variable, |
3840 | .Ev LINENO | | 3840 | .Ev LINENO |
3841 | will be exported by this shell. | | 3841 | will be exported by this shell. |
3842 | .Pp | | 3842 | .Pp |
3843 | .Ev LINENO | | 3843 | .Ev LINENO |
3844 | is set automatically by the shell to be the number of the source | | 3844 | is set automatically by the shell to be the number of the source |
3845 | line on which it occurs. | | 3845 | line on which it occurs. |
3846 | When exported, | | 3846 | When exported, |
3847 | .Ev LINENO | | 3847 | .Ev LINENO |
3848 | is exported with its value set to the line number it would have | | 3848 | is exported with its value set to the line number it would have |
3849 | had had it been referenced on the command line of the command to | | 3849 | had had it been referenced on the command line of the command to |
3850 | which it is exported. | | 3850 | which it is exported. |
3851 | Line numbers are counted from 1, which is the first line the shell | | 3851 | Line numbers are counted from 1, which is the first line the shell |
3852 | reads from any particular file. | | 3852 | reads from any particular file. |
3853 | For this shell, standard input, including in an interactive shell, | | 3853 | For this shell, standard input, including in an interactive shell, |
3854 | the user's terminal, is just another file and lines are counted | | 3854 | the user's terminal, is just another file and lines are counted |
3855 | there as well. | | 3855 | there as well. |
3856 | However note that not all shells count interactive | | 3856 | However note that not all shells count interactive |
3857 | lines this way, it is not wise to rely upon | | 3857 | lines this way, it is not wise to rely upon |
3858 | .Ev LINENO | | 3858 | .Ev LINENO |
3859 | having a useful value, except in a script, or a function. | | 3859 | having a useful value, except in a script, or a function. |
3860 | .Pp | | 3860 | .Pp |
3861 | The role of | | 3861 | The role of |
3862 | .Ev LINENO | | 3862 | .Ev LINENO |
3863 | in functions is less clear. | | 3863 | in functions is less clear. |
3864 | In some shells, | | 3864 | In some shells, |
3865 | .Ev LINENO | | 3865 | .Ev LINENO |
3866 | continues to refer to the line number in the script which defines | | 3866 | continues to refer to the line number in the script which defines |
3867 | the function, | | 3867 | the function, |
3868 | in others lines count from one within the function, always (and | | 3868 | in others lines count from one within the function, always (and |
3869 | resume counting normally once the function definition is complete) | | 3869 | resume counting normally once the function definition is complete) |
3870 | and others count in functions from one if the function is defined | | 3870 | and others count in functions from one if the function is defined |
3871 | interactively, but otherwise just reference the line number in the | | 3871 | interactively, but otherwise just reference the line number in the |
3872 | script in which the function is defined. | | 3872 | script in which the function is defined. |
3873 | This shell gives the user the option to choose. | | 3873 | This shell gives the user the option to choose. |
3874 | If the | | 3874 | If the |
3875 | .Fl L | | 3875 | .Fl L |
3876 | flag (the | | 3876 | flag (the |
3877 | .Ic local_lineno | | 3877 | .Ic local_lineno |
3878 | option, see | | 3878 | option, see |
3879 | .Sx Argument List Processing ) | | 3879 | .Sx Argument List Processing ) |
3880 | is set, when the function is defined, then the function | | 3880 | is set, when the function is defined, then the function |
3881 | defaults to counting lines with one being the first line of the | | 3881 | defaults to counting lines with one being the first line of the |
3882 | function. | | 3882 | function. |
3883 | When the | | 3883 | When the |
3884 | .Fl L | | 3884 | .Fl L |
3885 | flag is not set, the shell counts lines in a function definition | | 3885 | flag is not set, the shell counts lines in a function definition |
3886 | in the same continuous sequence as the lines that surround the | | 3886 | in the same continuous sequence as the lines that surround the |
3887 | function definition. | | 3887 | function definition. |
3888 | Further, if | | 3888 | Further, if |
3889 | .Ev LINENO | | 3889 | .Ev LINENO |
3890 | is made local | | 3890 | is made local |
3891 | (see | | 3891 | (see |
3892 | .Sx Built-ins | | 3892 | .Sx Built-ins |
3893 | above) | | 3893 | above) |
3894 | inside the function, the function can decide which | | 3894 | inside the function, the function can decide which |
3895 | behavior it prefers. | | 3895 | behavior it prefers. |
3896 | If | | 3896 | If |
3897 | .Ev LINENO | | 3897 | .Ev LINENO |
3898 | is made local and inherited, and not given a value, as in | | 3898 | is made local and inherited, and not given a value, as in |
3899 | .Dl local Fl I Ev LINENO | | 3899 | .Dl local Fl I Ev LINENO |
3900 | then from that point in the function, | | 3900 | then from that point in the function, |
3901 | .Ev LINENO | | 3901 | .Ev LINENO |
3902 | will give the line number as if lines are counted in sequence | | 3902 | will give the line number as if lines are counted in sequence |
3903 | with the lines that surround the function definition (and | | 3903 | with the lines that surround the function definition (and |
3904 | any other function definitions in which this is nested.) | | 3904 | any other function definitions in which this is nested.) |
3905 | If | | 3905 | If |
3906 | .Ev LINENO | | 3906 | .Ev LINENO |
3907 | is made local, and in that same command, given a value, as | | 3907 | is made local, and in that same command, given a value, as |
3908 | .Dl local Oo Fl I Ns | Ns Fl N Oc Ev LINENO Ns = Ns Ar value | | 3908 | .Dl local Oo Fl I Ns | Ns Fl N Oc Ev LINENO Ns = Ns Ar value |
3909 | then | | 3909 | then |
3910 | .Ev LINENO | | 3910 | .Ev LINENO |
3911 | will give the line number as if lines are counted from one | | 3911 | will give the line number as if lines are counted from one |
3912 | from the beginning of the function. | | 3912 | from the beginning of the function. |
3913 | The value nominally assigned in this case is irrelevant, and ignored. | | 3913 | The value nominally assigned in this case is irrelevant, and ignored. |
3914 | For completeness, if lineno is made local and unset, as in | | 3914 | For completeness, if lineno is made local and unset, as in |
3915 | .Dl local Fl N Ev LINENO | | 3915 | .Dl local Fl N Ev LINENO |
3916 | then | | 3916 | then |
3917 | .Ev LINENO | | 3917 | .Ev LINENO |
3918 | is simply unset inside the function, and gives no value at all. | | 3918 | is simply unset inside the function, and gives no value at all. |
3919 | .Pp | | 3919 | .Pp |
3920 | Now for some technical details. | | 3920 | Now for some technical details. |
3921 | The line on which | | 3921 | The line on which |
3922 | .Ev LINENO | | 3922 | .Ev LINENO |
3923 | occurs in a parameter expansion, is the line that contains the | | 3923 | occurs in a parameter expansion, is the line that contains the |
3924 | .Sq \&$ | | 3924 | .Sq \&$ |
3925 | that begins the expansion of | | 3925 | that begins the expansion of |
3926 | .Ev LINENO . | | 3926 | .Ev LINENO . |
3927 | In the case of nested expansions, that | | 3927 | In the case of nested expansions, that |
3928 | .Sq \&$ | | 3928 | .Sq \&$ |
3929 | is the one that actually has | | 3929 | is the one that actually has |
3930 | .Ev LINENO | | 3930 | .Ev LINENO |
3931 | as its parameter. | | 3931 | as its parameter. |
3932 | In an arithmetic expansion, where no | | 3932 | In an arithmetic expansion, where no |
3933 | .Sq \&$ | | 3933 | .Sq \&$ |
3934 | is used to evaluate | | 3934 | is used to evaluate |
3935 | .Ev LINENO | | 3935 | .Ev LINENO |
3936 | but | | 3936 | but |
3937 | .Ev LINENO | | 3937 | .Ev LINENO |
3938 | is simply referenced as a variable, then the value is the | | 3938 | is simply referenced as a variable, then the value is the |
3939 | line number of the line that contains the | | 3939 | line number of the line that contains the |
3940 | .Sq L | | 3940 | .Sq L |
3941 | of | | 3941 | of |
3942 | .Ev LINENO . | | 3942 | .Ev LINENO . |
3943 | For functions line one of the function definition (when relevant) | | 3943 | For functions line one of the function definition (when relevant) |
3944 | is the line that contains the first character of the | | 3944 | is the line that contains the first character of the |
3945 | function name in the definition. | | 3945 | function name in the definition. |
3946 | When exported, the line number of the command is the line number | | 3946 | When exported, the line number of the command is the line number |
3947 | where the first character of the word which becomes the command name occurs. | | 3947 | where the first character of the word which becomes the command name occurs. |
3948 | .Pp | | 3948 | .Pp |
3949 | When the shell opens a new file, for any reason, | | 3949 | When the shell opens a new file, for any reason, |
3950 | it counts lines from one in that file, | | 3950 | it counts lines from one in that file, |
3951 | and then resumes its original counting once it resumes reading the | | 3951 | and then resumes its original counting once it resumes reading the |
3952 | previous input stream. | | 3952 | previous input stream. |
3953 | When handling a string passed to | | 3953 | When handling a string passed to |
3954 | .Ic eval | | 3954 | .Ic eval |
3955 | the line number starts at the line on which the string starts, | | 3955 | the line number starts at the line on which the string starts, |
3956 | and then if the string contains internal newline characters, | | 3956 | and then if the string contains internal newline characters, |
3957 | those characters increase the line number. | | 3957 | those characters increase the line number. |
3958 | This means that references to | | 3958 | This means that references to |
3959 | .Ev LINENO | | 3959 | .Ev LINENO |
3960 | in such a case can produce values larger than would be | | 3960 | in such a case can produce values larger than would be |
3961 | produced by a reference on the line after the | | 3961 | produced by a reference on the line after the |
3962 | .Ic eval . | | 3962 | .Ic eval . |
3963 | .Sh FILES | | 3963 | .Sh FILES |
3964 | .Bl -item | | 3964 | .Bl -item |
3965 | .It | | 3965 | .It |
3966 | .Pa $HOME/.profile | | 3966 | .Pa $HOME/.profile |
3967 | .It | | 3967 | .It |
3968 | .Pa /etc/profile | | 3968 | .Pa /etc/profile |
3969 | .El | | 3969 | .El |
3970 | .Sh EXIT STATUS | | 3970 | .Sh EXIT STATUS |
3971 | Errors that are detected by the shell, such as a syntax error, will cause the | | 3971 | Errors that are detected by the shell, such as a syntax error, will cause the |
3972 | shell to exit with a non-zero exit status. | | 3972 | shell to exit with a non-zero exit status. |
3973 | If the shell is not an | | 3973 | If the shell is not an |
3974 | interactive shell, the execution of the shell file will be aborted. | | 3974 | interactive shell, the execution of the shell file will be aborted. |
3975 | Otherwise | | 3975 | Otherwise |
3976 | the shell will return the exit status of the last command executed, or | | 3976 | the shell will return the exit status of the last command executed, or |
3977 | if the exit built-in is used with a numeric argument, it will return the | | 3977 | if the exit built-in is used with a numeric argument, it will return the |
3978 | argument. | | 3978 | argument. |
3979 | .Sh SEE ALSO | | 3979 | .Sh SEE ALSO |
3980 | .Xr csh 1 , | | 3980 | .Xr csh 1 , |
3981 | .Xr echo 1 , | | 3981 | .Xr echo 1 , |
3982 | .Xr getopt 1 , | | 3982 | .Xr getopt 1 , |
3983 | .Xr ksh 1 , | | 3983 | .Xr ksh 1 , |
3984 | .Xr login 1 , | | 3984 | .Xr login 1 , |
3985 | .Xr printf 1 , | | 3985 | .Xr printf 1 , |
3986 | .Xr test 1 , | | 3986 | .Xr test 1 , |
3987 | .Xr editline 3 , | | 3987 | .Xr editline 3 , |
3988 | .Xr getopt 3 , | | 3988 | .Xr getopt 3 , |
3989 | .\" .Xr profile 4 , | | 3989 | .\" .Xr profile 4 , |
3990 | .Xr editrc 5 , | | 3990 | .Xr editrc 5 , |
3991 | .Xr passwd 5 , | | 3991 | .Xr passwd 5 , |
3992 | .Xr editline 7 , | | 3992 | .Xr editline 7 , |
3993 | .Xr environ 7 , | | 3993 | .Xr environ 7 , |
3994 | .Xr nls 7 , | | 3994 | .Xr nls 7 , |
3995 | .Xr sysctl 8 | | 3995 | .Xr sysctl 8 |
3996 | .Sh HISTORY | | 3996 | .Sh HISTORY |
3997 | A | | 3997 | A |
3998 | .Nm | | 3998 | .Nm |
3999 | command appeared in | | 3999 | command appeared in |
4000 | .At v1 . | | 4000 | .At v1 . |
4001 | It was replaced in | | 4001 | It was replaced in |
4002 | .At v7 | | 4002 | .At v7 |
4003 | with a version that introduced the basis of the current syntax. | | 4003 | with a version that introduced the basis of the current syntax. |
4004 | That was, however, unmaintainable so we wrote this one. | | 4004 | That was, however, unmaintainable so we wrote this one. |
4005 | .Sh BUGS | | 4005 | .Sh BUGS |
4006 | Setuid shell scripts should be avoided at all costs, as they are a | | 4006 | Setuid shell scripts should be avoided at all costs, as they are a |
4007 | significant security risk. | | 4007 | significant security risk. |
4008 | .Pp | | 4008 | .Pp |
4009 | The characters generated by filename completion should probably be quoted | | 4009 | The characters generated by filename completion should probably be quoted |
4010 | to ensure that the filename is still valid after the input line has been | | 4010 | to ensure that the filename is still valid after the input line has been |
4011 | processed. | | 4011 | processed. |
4012 | .Pp | | 4012 | .Pp |
4013 | The | | 4013 | The |
4014 | .Ic trap | | 4014 | .Ic trap |
4015 | command cannot usefully be used, yet, within a command substitution, | | 4015 | command cannot usefully be used, yet, within a command substitution, |
4016 | to obtain the current trap values, | | 4016 | to obtain the current trap values, |
4017 | as all command substitutions are currently executed within a | | 4017 | as all command substitutions are currently executed within a |
4018 | sub-shell environment, | | 4018 | sub-shell environment, |
4019 | and in sub-shells all non-ignored, non-default, traps are reset. | | 4019 | and in sub-shells all non-ignored, non-default, traps are reset. |
4020 | As a workaround, it is possible to redirect output from | | 4020 | As a workaround, it is possible to redirect output from |
4021 | .Dq trap | | 4021 | .Dq trap |
4022 | or | | 4022 | or |
4023 | .Dq trap -p | | 4023 | .Dq trap -p |
4024 | to a file, and then read the file later using the | | 4024 | to a file, and then read the file later using the |
4025 | .Dq \&. | | 4025 | .Dq \&. |
4026 | command. | | 4026 | command. |
4027 | .Pp | | 4027 | .Pp |
4028 | Job control of compound statements (loops, etc) is a complete mess. | | 4028 | Job control of compound statements (loops, etc) is a complete mess. |
4029 | .Pp | | 4029 | .Pp |
4030 | Many, many, more. | | 4030 | Many, many, more. |
4031 | (But less than there were...) | | 4031 | (But less than there were...) |