| @@ -1,2107 +1,2358 @@ | | | @@ -1,2107 +1,2358 @@ |
1 | .\" $NetBSD: sh.1,v 1.119 2016/02/24 15:28:36 wiz Exp $ | | 1 | .\" $NetBSD: sh.1,v 1.120 2016/03/31 16:18:22 christos 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 January 5, 2015 | | 34 | .Dd March 31, 2016 |
35 | .Dt SH 1 | | 35 | .Dt SH 1 |
36 | .ds flags abCEeFfhnuvxIimpqV | | 36 | .ds flags abCEeFfhnuvxIimpqV |
37 | .Os | | 37 | .Os |
38 | .Sh NAME | | 38 | .Sh NAME |
39 | .Nm sh | | 39 | .Nm sh |
40 | .Nd command interpreter (shell) | | 40 | .Nd command interpreter (shell) |
41 | .Sh SYNOPSIS | | 41 | .Sh SYNOPSIS |
42 | .Nm | | 42 | .Nm |
43 | .Bk -words | | 43 | .Bk -words |
44 | .Op Fl \*[flags] | | 44 | .Op Fl \*[flags] |
45 | .Op Cm +\*[flags] | | 45 | .Op Cm +\*[flags] |
46 | .Ek | | 46 | .Ek |
47 | .Bk -words | | 47 | .Bk -words |
48 | .Op Fl o Ar option_name | | 48 | .Op Fl o Ar option_name |
49 | .Op Cm +o Ar option_name | | 49 | .Op Cm +o Ar option_name |
50 | .Ek | | 50 | .Ek |
51 | .Bk -words | | 51 | .Bk -words |
52 | .Op Ar command_file Oo Ar argument ... Oc | | 52 | .Op Ar command_file Oo Ar argument ... Oc |
53 | .Ek | | 53 | .Ek |
54 | .Nm | | 54 | .Nm |
55 | .Fl c | | 55 | .Fl c |
56 | .Bk -words | | 56 | .Bk -words |
57 | .Op Fl \*[flags] | | 57 | .Op Fl \*[flags] |
58 | .Op Cm +\*[flags] | | 58 | .Op Cm +\*[flags] |
59 | .Ek | | 59 | .Ek |
60 | .Bk -words | | 60 | .Bk -words |
61 | .Op Fl o Ar option_name | | 61 | .Op Fl o Ar option_name |
62 | .Op Cm +o Ar option_name | | 62 | .Op Cm +o Ar option_name |
63 | .Ek | | 63 | .Ek |
64 | .Bk -words | | 64 | .Bk -words |
65 | .Ar command_string | | 65 | .Ar command_string |
66 | .Op Ar command_name Oo Ar argument ... Oc | | 66 | .Op Ar command_name Oo Ar argument ... Oc |
67 | .Ek | | 67 | .Ek |
68 | .Nm | | 68 | .Nm |
69 | .Fl s | | 69 | .Fl s |
70 | .Bk -words | | 70 | .Bk -words |
71 | .Op Fl \*[flags] | | 71 | .Op Fl \*[flags] |
72 | .Op Cm +\*[flags] | | 72 | .Op Cm +\*[flags] |
73 | .Ek | | 73 | .Ek |
74 | .Bk -words | | 74 | .Bk -words |
75 | .Op Fl o Ar option_name | | 75 | .Op Fl o Ar option_name |
76 | .Op Cm +o Ar option_name | | 76 | .Op Cm +o Ar option_name |
77 | .Ek | | 77 | .Ek |
78 | .Bk -words | | 78 | .Bk -words |
79 | .Op Ar argument ... | | 79 | .Op Ar argument ... |
80 | .Ek | | 80 | .Ek |
81 | .Sh DESCRIPTION | | 81 | .Sh DESCRIPTION |
82 | .Nm | | 82 | .Nm |
83 | is the standard command interpreter for the system. | | 83 | is the standard command interpreter for the system. |
84 | The current version of | | 84 | The current version of |
85 | .Nm | | 85 | .Nm |
86 | is in the process of being changed to conform with the | | 86 | is in the process of being changed to conform with the |
87 | .Tn POSIX | | 87 | .Tn POSIX |
88 | 1003.2 and 1003.2a specifications for the shell. | | 88 | 1003.2 and 1003.2a specifications for the shell. |
89 | This version has many | | 89 | This version has many |
90 | features which make it appear similar in some respects to the Korn shell, | | 90 | features which make it appear similar in some respects to the Korn shell, |
91 | but it is not a Korn shell clone (see | | 91 | but it is not a Korn shell clone (see |
92 | .Xr ksh 1 ) . | | 92 | .Xr ksh 1 ) . |
93 | Only features designated by | | 93 | Only features designated by |
94 | .Tn POSIX , | | 94 | .Tn POSIX , |
95 | plus a few Berkeley extensions, are being incorporated into this shell. | | 95 | plus a few Berkeley extensions, are being incorporated into this shell. |
96 | .\" We expect | | 96 | .\" We expect |
97 | .\" .Tn POSIX | | 97 | .\" .Tn POSIX |
98 | .\" conformance by the time 4.4 BSD is released. | | 98 | .\" conformance by the time 4.4 BSD is released. |
99 | This man page is not intended | | 99 | This man page is not intended |
100 | to be a tutorial or a complete specification of the shell. | | 100 | to be a tutorial or a complete specification of the shell. |
101 | .Ss Overview | | 101 | .Ss Overview |
102 | The shell is a command that reads lines from either a file or the | | 102 | The shell is a command that reads lines from either a file or the |
103 | terminal, interprets them, and generally executes other commands. | | 103 | terminal, interprets them, and generally executes other commands. |
104 | It is the program that is running when a user logs into the system | | 104 | It is the program that is running when a user logs into the system |
105 | (although a user can select a different shell with the | | 105 | (although a user can select a different shell with the |
106 | .Xr chsh 1 | | 106 | .Xr chsh 1 |
107 | command). | | 107 | command). |
108 | The shell implements a language that has flow control | | 108 | The shell implements a language that has flow control |
109 | constructs, a macro facility that provides a variety of features in | | 109 | constructs, a macro facility that provides a variety of features in |
110 | addition to data storage, along with built in history and line editing | | 110 | addition to data storage, along with built in history and line editing |
111 | capabilities. | | 111 | capabilities. |
112 | It incorporates many features to aid interactive use and | | 112 | It incorporates many features to aid interactive use and |
113 | has the advantage that the interpretative language is common to both | | 113 | has the advantage that the interpretative language is common to both |
114 | interactive and non-interactive use (shell scripts). | | 114 | interactive and non-interactive use (shell scripts). |
115 | That is, commands | | 115 | That is, commands |
116 | can be typed directly to the running shell or can be put into a file and | | 116 | can be typed directly to the running shell or can be put into a file and |
117 | the file can be executed directly by the shell. | | 117 | the file can be executed directly by the shell. |
118 | .Ss Invocation | | 118 | .Ss Invocation |
119 | If no arguments are present and if the standard input of the shell | | 119 | If no arguments are present and if the standard input of the shell |
120 | is connected to a terminal (or if the | | 120 | is connected to a terminal (or if the |
121 | .Fl i | | 121 | .Fl i |
122 | flag is set), | | 122 | flag is set), |
123 | and the | | 123 | and the |
124 | .Fl c | | 124 | .Fl c |
125 | option is not present, the shell is considered an interactive shell. | | 125 | option is not present, the shell is considered an interactive shell. |
126 | An interactive shell generally prompts before each command and handles | | 126 | An interactive shell generally prompts before each command and handles |
127 | programming and command errors differently (as described below). | | 127 | programming and command errors differently (as described below). |
128 | When first starting, | | 128 | When first starting, |
129 | the shell inspects argument 0, and if it begins with a dash | | 129 | the shell inspects argument 0, and if it begins with a dash |
130 | .Sq - , | | 130 | .Sq - , |
131 | the shell is also considered | | 131 | the shell is also considered |
132 | a login shell. | | 132 | a login shell. |
133 | This is normally done automatically by the system | | 133 | This is normally done automatically by the system |
134 | when the user first logs in. | | 134 | when the user first logs in. |
135 | A login shell first reads commands | | 135 | A login shell first reads commands |
136 | from the files | | 136 | from the files |
137 | .Pa /etc/profile | | 137 | .Pa /etc/profile |
138 | and | | 138 | and |
139 | .Pa .profile | | 139 | .Pa .profile |
140 | if they exist. | | 140 | if they exist. |
141 | If the environment variable | | 141 | If the environment variable |
142 | .Ev ENV | | 142 | .Ev ENV |
143 | is set on entry to a shell, or is set in the | | 143 | is set on entry to a shell, or is set in the |
144 | .Pa .profile | | 144 | .Pa .profile |
145 | of a login shell, the shell next reads | | 145 | of a login shell, the shell next reads |
146 | commands from the file named in | | 146 | commands from the file named in |
147 | .Ev ENV . | | 147 | .Ev ENV . |
148 | Therefore, a user should place commands that are to be executed only at | | 148 | Therefore, a user should place commands that are to be executed only at |
149 | login time in the | | 149 | login time in the |
150 | .Pa .profile | | 150 | .Pa .profile |
151 | file, and commands that are executed for every shell inside the | | 151 | file, and commands that are executed for every shell inside the |
152 | .Ev ENV | | 152 | .Ev ENV |
153 | file. | | 153 | file. |
154 | To set the | | 154 | To set the |
155 | .Ev ENV | | 155 | .Ev ENV |
156 | variable to some file, place the following line in your | | 156 | variable to some file, place the following line in your |
157 | .Pa .profile | | 157 | .Pa .profile |
158 | of your home directory | | 158 | of your home directory |
159 | .Pp | | 159 | .Pp |
160 | .Dl ENV=$HOME/.shinit; export ENV | | 160 | .Dl ENV=$HOME/.shinit; export ENV |
161 | .Pp | | 161 | .Pp |
162 | substituting for | | 162 | substituting for |
163 | .Dq .shinit | | 163 | .Dq .shinit |
164 | any filename you wish. | | 164 | any filename you wish. |
165 | Since the | | 165 | Since the |
166 | .Ev ENV | | 166 | .Ev ENV |
167 | file is read for every invocation of the shell, including shell scripts | | 167 | file is read for every invocation of the shell, including shell scripts |
168 | and non-interactive shells, the following paradigm is useful for | | 168 | and non-interactive shells, the following paradigm is useful for |
169 | restricting commands in the | | 169 | restricting commands in the |
170 | .Ev ENV | | 170 | .Ev ENV |
171 | file to interactive invocations. | | 171 | file to interactive invocations. |
172 | Place commands within the | | 172 | Place commands within the |
173 | .Dq case | | 173 | .Dq case |
174 | and | | 174 | and |
175 | .Dq esac | | 175 | .Dq esac |
176 | below (these commands are described later): | | 176 | below (these commands are described later): |
177 | .Pp | | 177 | .Pp |
178 | .Bl -item -compact -offset indent | | 178 | .Bl -item -compact -offset indent |
179 | .It | | 179 | .It |
180 | .Li case $- in *i*) | | 180 | .Li case $- in *i*) |
181 | .Bl -item -compact -offset indent | | 181 | .Bl -item -compact -offset indent |
182 | .It | | 182 | .It |
183 | .Li # commands for interactive use only | | 183 | .Li # commands for interactive use only |
184 | .It | | 184 | .It |
185 | .Li ... | | 185 | .Li ... |
186 | .El | | 186 | .El |
187 | .It | | 187 | .It |
188 | .Li esac | | 188 | .Li esac |
189 | .El | | 189 | .El |
190 | .Pp | | 190 | .Pp |
191 | If command line arguments besides the options have been specified, then | | 191 | If command line arguments besides the options have been specified, then |
192 | the shell treats the first argument as the name of a file from which to | | 192 | the shell treats the first argument as the name of a file from which to |
193 | read commands (a shell script), and the remaining arguments are set as the | | 193 | read commands (a shell script), and the remaining arguments are set as the |
194 | positional parameters of the shell ($1, $2, etc). | | 194 | positional parameters of the shell ($1, $2, etc). |
195 | Otherwise, the shell | | 195 | Otherwise, the shell |
196 | reads commands from its standard input. | | 196 | reads commands from its standard input. |
197 | .Ss Argument List Processing | | 197 | .Ss Argument List Processing |
198 | All of the single letter options have a corresponding name that can be | | 198 | All of the single letter options have a corresponding name that can be |
199 | used as an argument to the | | 199 | used as an argument to the |
200 | .Fl o | | 200 | .Fl o |
201 | option. | | 201 | option. |
202 | The set | | 202 | The set |
203 | .Fl o | | 203 | .Fl o |
204 | name is provided next to the single letter option in | | 204 | name is provided next to the single letter option in |
205 | the description below. | | 205 | the description below. |
206 | Specifying a dash | | 206 | Specifying a dash |
207 | .Dq - | | 207 | .Dq - |
208 | turns the option on, while using a plus | | 208 | turns the option on, while using a plus |
209 | .Dq + | | 209 | .Dq + |
210 | disables the option. | | 210 | disables the option. |
211 | The following options can be set from the command line or | | 211 | The following options can be set from the command line or |
212 | with the | | 212 | with the |
213 | .Ic set | | 213 | .Ic set |
214 | built-in (described later). | | 214 | built-in (described later). |
215 | .Bl -tag -width aaaallexportfoo -offset indent | | 215 | .Bl -tag -width aaaallexportfoo -offset indent |
216 | .It Fl a Em allexport | | 216 | .It Fl a Em allexport |
217 | Export all variables assigned to. | | 217 | Export all variables assigned to. |
218 | .It Fl c | | 218 | .It Fl c |
219 | Read commands from the | | 219 | Read commands from the |
220 | .Ar command_string | | 220 | .Ar command_string |
221 | operand instead of from the standard input. | | 221 | operand instead of from the standard input. |
222 | Special parameter 0 will be set from the | | 222 | Special parameter 0 will be set from the |
223 | .Ar command_name | | 223 | .Ar command_name |
224 | operand and the positional parameters ($1, $2, etc.) | | 224 | operand and the positional parameters ($1, $2, etc.) |
225 | set from the remaining argument operands. | | 225 | set from the remaining argument operands. |
226 | .Fl c | | 226 | .Fl c |
227 | is only available at invocation, it cannot be | | 227 | is only available at invocation, it cannot be |
228 | .Ic set , | | 228 | .Ic set , |
229 | and there is no form using | | 229 | and there is no form using |
230 | .Dq \&+ . | | 230 | .Dq \&+ . |
231 | .It Fl C Em noclobber | | 231 | .It Fl C Em noclobber |
232 | Don't overwrite existing files with | | 232 | Don't overwrite existing files with |
233 | .Dq \*[Gt] . | | 233 | .Dq \*[Gt] . |
234 | .It Fl e Em errexit | | 234 | .It Fl e Em errexit |
235 | If not interactive, exit immediately if any untested command fails. | | 235 | If not interactive, exit immediately if any untested command fails. |
236 | The exit status of a command is considered to be | | 236 | The exit status of a command is considered to be |
237 | explicitly tested if the command is used to control an | | 237 | explicitly tested if the command is used to control an |
238 | .Ic if , | | 238 | .Ic if , |
239 | .Ic elif , | | 239 | .Ic elif , |
240 | .Ic while , | | 240 | .Ic while , |
241 | or | | 241 | or |
242 | .Ic until , | | 242 | .Ic until , |
243 | or if the command is the left hand operand of an | | 243 | or if the command is the left hand operand of an |
244 | .Dq \*[Am]\*[Am] | | 244 | .Dq \*[Am]\*[Am] |
245 | or | | 245 | or |
246 | .Dq || | | 246 | .Dq || |
247 | operator, | | 247 | operator, |
248 | or if it is a pipeline (or simple command) preceded by the | | 248 | or if it is a pipeline (or simple command) preceded by the |
249 | .Dq \&! | | 249 | .Dq \&! |
250 | operator. | | 250 | operator. |
251 | With pipelines, only the status of the entire pipeline | | 251 | With pipelines, only the status of the entire pipeline |
252 | (indicated by the last command it contains) | | 252 | (indicated by the last command it contains) |
253 | is tested when | | 253 | is tested when |
254 | .Fl e | | 254 | .Fl e |
255 | is set to determine if the shell should exit. | | 255 | is set to determine if the shell should exit. |
256 | .It Fl f Em noglob | | 256 | .It Fl f Em noglob |
257 | Disable pathname expansion. | | 257 | Disable pathname expansion. |
258 | .It Fl n Em noexec | | 258 | .It Fl n Em noexec |
259 | If not interactive, read commands but do not execute them. | | 259 | If not interactive, read commands but do not execute them. |
260 | This is useful for checking the syntax of shell scripts. | | 260 | This is useful for checking the syntax of shell scripts. |
261 | .It Fl u Em nounset | | 261 | .It Fl u Em nounset |
262 | Write a message to standard error when attempting to expand a variable | | 262 | Write a message to standard error when attempting to expand a variable |
263 | that is not set, and if the shell is not interactive, exit immediately. | | 263 | that is not set, and if the shell is not interactive, exit immediately. |
264 | .It Fl v Em verbose | | 264 | .It Fl v Em verbose |
265 | The shell writes its input to standard error as it is read. | | 265 | The shell writes its input to standard error as it is read. |
266 | Useful for debugging. | | 266 | Useful for debugging. |
267 | .It Fl x Em xtrace | | 267 | .It Fl x Em xtrace |
268 | Write each command to standard error (preceded by a | | 268 | Write each command to standard error (preceded by a |
269 | .Sq +\ ) | | 269 | .Sq +\ ) |
270 | before it is executed. | | 270 | before it is executed. |
271 | Useful for debugging. | | 271 | Useful for debugging. |
272 | .It Fl q Em quietprofile | | 272 | .It Fl q Em quietprofile |
273 | If the | | 273 | If the |
274 | .Fl v | | 274 | .Fl v |
275 | or | | 275 | or |
276 | .Fl x | | 276 | .Fl x |
277 | options have been set, do not apply them when reading | | 277 | options have been set, do not apply them when reading |
278 | initialization files, these being | | 278 | initialization files, these being |
279 | .Pa /etc/profile , | | 279 | .Pa /etc/profile , |
280 | .Pa .profile , | | 280 | .Pa .profile , |
281 | and the file specified by the | | 281 | and the file specified by the |
282 | .Ev ENV | | 282 | .Ev ENV |
283 | environment variable. | | 283 | environment variable. |
284 | .It Fl I Em ignoreeof | | 284 | .It Fl I Em ignoreeof |
285 | Ignore EOFs from input when interactive. | | 285 | Ignore EOFs from input when interactive. |
286 | .It Fl i Em interactive | | 286 | .It Fl i Em interactive |
287 | Force the shell to behave interactively. | | 287 | Force the shell to behave interactively. |
288 | .It Fl m Em monitor | | 288 | .It Fl m Em monitor |
289 | Turn on job control (set automatically when interactive). | | 289 | Turn on job control (set automatically when interactive). |
290 | .It Fl s Em stdin | | 290 | .It Fl s Em stdin |
291 | Read commands from standard input (set automatically if no file arguments | | 291 | Read commands from standard input (set automatically if no file arguments |
292 | are present). | | 292 | are present). |
293 | This option has no effect when set or reset after the shell has | | 293 | This option has no effect when set or reset after the shell has |
294 | already started running (i.e. with | | 294 | already started running (i.e. with |
295 | .Ic set ) . | | 295 | .Ic set ) . |
296 | .It Fl V Em vi | | 296 | .It Fl V Em vi |
297 | Enable the built-in | | 297 | Enable the built-in |
298 | .Xr vi 1 | | 298 | .Xr vi 1 |
299 | command line editor (disables | | 299 | command line editor (disables |
300 | .Fl E | | 300 | .Fl E |
301 | if it has been set). | | 301 | if it has been set). |
302 | (See the | | 302 | (See the |
303 | .Sx Command Line Editing | | 303 | .Sx Command Line Editing |
304 | section below.) | | 304 | section below.) |
305 | .It Fl E Em emacs | | 305 | .It Fl E Em emacs |
306 | Enable the built-in emacs style | | 306 | Enable the built-in emacs style |
307 | command line editor (disables | | 307 | command line editor (disables |
308 | .Fl V | | 308 | .Fl V |
309 | if it has been set). | | 309 | if it has been set). |
310 | (See the | | 310 | (See the |
311 | .Sx Command Line Editing | | 311 | .Sx Command Line Editing |
312 | section below.) | | 312 | section below.) |
313 | .It Fl b Em notify | | 313 | .It Fl b Em notify |
314 | Enable asynchronous notification of background job completion. | | 314 | Enable asynchronous notification of background job completion. |
315 | (Not implemented.) | | 315 | (Not implemented.) |
316 | .It Fl F Em fork | | 316 | .It Fl F Em fork |
317 | Cause the shell to always use | | 317 | Cause the shell to always use |
318 | .Xr fork 2 | | 318 | .Xr fork 2 |
319 | instead of attempting | | 319 | instead of attempting |
320 | .Xr vfork 2 | | 320 | .Xr vfork 2 |
321 | when it needs to create a new process. | | 321 | when it needs to create a new process. |
322 | This should normally have no visible effect, | | 322 | This should normally have no visible effect, |
323 | but can slow execution. | | 323 | but can slow execution. |
324 | The | | 324 | The |
325 | .Nm | | 325 | .Nm |
326 | can be compiled to always use | | 326 | can be compiled to always use |
327 | .Xr fork 2 | | 327 | .Xr fork 2 |
328 | in which case altering the | | 328 | in which case altering the |
329 | .Fl F | | 329 | .Fl F |
330 | flag has no effect. | | 330 | flag has no effect. |
331 | .It Fl h Em trackall | | 331 | .It Fl h Em trackall |
332 | Bind commands in functions to file system paths when the function is defined. | | 332 | Bind commands in functions to file system paths when the function is defined. |
| | | 333 | .\" They can seek me here (that dreaded filesystem) |
333 | When off, | | 334 | When off, |
334 | the file system is searched for commands each time the function is invoked. | | 335 | the file system is searched for commands each time the function is invoked. |
335 | (Not implemented.) | | 336 | (Not implemented.) |
| | | 337 | .\" then can seek me there (the filesystem, once again) |
336 | .It Fl p Em nopriv | | 338 | .It Fl p Em nopriv |
337 | Do not attempt to reset effective uid if it does not match uid. | | 339 | Do not attempt to reset effective uid if it does not match uid. |
338 | This is not set by default to help avoid incorrect usage by setuid | | 340 | This is not set by default to help avoid incorrect usage by setuid |
339 | root programs via | | 341 | root programs via |
340 | .Xr system 3 | | 342 | .Xr system 3 |
341 | or | | 343 | or |
342 | .Xr popen 3 . | | 344 | .Xr popen 3 . |
343 | .It "\ \ " Em cdprint | | 345 | .It "\ \ " Em cdprint |
344 | Make an interactive shell always print the new directory name when | | 346 | Make an interactive shell always print the new directory name when |
345 | changed by the | | 347 | changed by the |
346 | .Ic cd | | 348 | .Ic cd |
347 | command. | | 349 | command. |
348 | .It "\ \ " Em nolog | | 350 | .It "\ \ " Em nolog |
349 | Prevent the entry of function definitions into the command history (see | | 351 | Prevent the entry of function definitions into the command history (see |
350 | .Ic fc | | 352 | .Ic fc |
351 | in the | | 353 | in the |
352 | .Sx Built-ins | | 354 | .Sx Built-ins |
353 | section.) | | 355 | section.) |
354 | (Not implemented.) | | 356 | (Not implemented.) |
| | | 357 | .It "\ \ " Em posix |
| | | 358 | Enables closer adherence to the shell standard. |
| | | 359 | This option will default set at shell startup if the |
| | | 360 | environment variable |
| | | 361 | .Ev POSIXLY_CORRECT |
| | | 362 | is present. |
| | | 363 | That can be overridden by the |
| | | 364 | .Fl o |
| | | 365 | option on the command line. |
| | | 366 | Currently this option controls whether (!posix) or not (posix) |
| | | 367 | the file given by the |
| | | 368 | .Ev ENV |
| | | 369 | variable is read at startup by a non-interactive shell. |
| | | 370 | Consequently, while it can be manipulated by the |
| | | 371 | .Ic set |
| | | 372 | command, doing so has no current purpose. |
355 | .It "\ \ " Em tabcomplete | | 373 | .It "\ \ " Em tabcomplete |
356 | Enables filename completion in the command line editor. | | 374 | Enables filename completion in the command line editor. |
357 | Typing a tab character will extend the current input word to match a | | 375 | Typing a tab character will extend the current input word to match a |
358 | filename. | | 376 | filename. |
359 | If more than one filename matches it is only extended to be the common prefix. | | 377 | If more than one filename matches it is only extended to be the common prefix. |
360 | Typing a second tab character will list all the matching names. | | 378 | Typing a second tab character will list all the matching names. |
361 | One of the editing modes, either | | 379 | One of the editing modes, either |
362 | .Fl E | | 380 | .Fl E |
363 | or | | 381 | or |
364 | .Fl V , | | 382 | .Fl V , |
365 | must be enabled for this to work. | | 383 | must be enabled for this to work. |
366 | .El | | 384 | .El |
367 | .Ss Lexical Structure | | 385 | .Ss Lexical Structure |
368 | The shell reads input in terms of lines from a file and breaks it up into | | 386 | The shell reads input in terms of lines from a file and breaks it up into |
369 | words at whitespace (blanks and tabs), and at certain sequences of | | 387 | words at whitespace (blanks and tabs), and at certain sequences of |
370 | characters that are special to the shell called | | 388 | characters that are special to the shell called |
371 | .Dq operators . | | 389 | .Dq operators . |
372 | There are two types of operators: control operators and redirection | | 390 | There are two types of operators: control operators and redirection |
373 | operators (their meaning is discussed later). | | 391 | operators (their meaning is discussed later). |
374 | Following is a list of operators: | | 392 | Following is a list of operators: |
375 | .Bl -ohang -offset indent | | 393 | .Bl -ohang -offset indent |
376 | .It "Control operators:" | | 394 | .It "Control operators:" |
377 | .Dl \*[Am] \*[Am]\*[Am] \&( \&) \&; ;; | || \*[Lt]newline\*[Gt] | | 395 | .Dl \*[Am] \*[Am]\*[Am] \&( \&) \&; ;; | || \*[Lt]newline\*[Gt] |
378 | .It "Redirection operators:" | | 396 | .It "Redirection operators:" |
379 | .Dl \*[Lt] \*[Gt] \*[Gt]| \*[Lt]\*[Lt] \*[Gt]\*[Gt] \*[Lt]\*[Am] \*[Gt]\*[Am] \*[Lt]\*[Lt]- \*[Lt]\*[Gt] | | 397 | .Dl \*[Lt] \*[Gt] \*[Gt]| \*[Lt]\*[Lt] \*[Gt]\*[Gt] \*[Lt]\*[Am] \*[Gt]\*[Am] \*[Lt]\*[Lt]- \*[Lt]\*[Gt] |
380 | .El | | 398 | .El |
381 | .Ss Quoting | | 399 | .Ss Quoting |
382 | Quoting is used to remove the special meaning of certain characters or | | 400 | Quoting is used to remove the special meaning of certain characters or |
383 | words to the shell, such as operators, whitespace, or keywords. | | 401 | words to the shell, such as operators, whitespace, or keywords. |
384 | There are three types of quoting: matched single quotes, | | 402 | There are three types of quoting: matched single quotes, |
385 | matched double quotes, and backslash. | | 403 | matched double quotes, and backslash. |
386 | .Ss Backslash | | 404 | .Ss Backslash |
387 | A backslash preserves the literal meaning of the following | | 405 | A backslash preserves the literal meaning of the following |
388 | character, with the exception of | | 406 | character, with the exception of |
389 | .Aq newline . | | 407 | .Aq newline . |
390 | A backslash preceding a | | 408 | A backslash preceding a |
391 | .Aq newline | | 409 | .Aq newline |
392 | is treated as a line continuation. | | 410 | is treated as a line continuation. |
393 | .Ss Single Quotes | | 411 | .Ss Single Quotes |
394 | Enclosing characters in single quotes preserves the literal meaning of all | | 412 | Enclosing characters in single quotes preserves the literal meaning of all |
395 | the characters (except single quotes, making it impossible to put | | 413 | the characters (except single quotes, making it impossible to put |
396 | single quotes in a single-quoted string). | | 414 | single quotes in a single-quoted string). |
397 | .Ss Double Quotes | | 415 | .Ss Double Quotes |
398 | Enclosing characters within double quotes preserves the literal | | 416 | Enclosing characters within double quotes preserves the literal |
399 | meaning of all characters except dollar sign | | 417 | meaning of all characters except dollar sign |
400 | .Pq $ , | | 418 | .Pq $ , |
401 | backquote | | 419 | backquote |
402 | .Pq ` , | | 420 | .Pq ` , |
403 | and backslash | | 421 | and backslash |
404 | .Pq \e . | | 422 | .Pq \e . |
405 | The backslash inside double quotes is historically weird, and serves to | | 423 | The backslash inside double quotes is historically weird, and serves to |
406 | quote only the following characters: | | 424 | quote only the following characters: |
407 | .Dl $ ` \*q \e \*[Lt]newline\*[Gt] . | | 425 | .Dl $ ` \*q \e \*[Lt]newline\*[Gt] . |
408 | Otherwise it remains literal. | | 426 | Otherwise it remains literal. |
409 | .Ss Reserved Words | | 427 | .Ss Reserved Words |
410 | Reserved words are words that have special meaning to the | | 428 | Reserved words are words that have special meaning to the |
411 | shell and are recognized at the beginning of a line and | | 429 | shell and are recognized at the beginning of a line and |
412 | after a control operator. | | 430 | after a control operator. |
413 | The following are reserved words: | | 431 | The following are reserved words: |
414 | .Bl -column while while while while while -offset indent | | 432 | .Bl -column while while while while while -offset indent |
415 | .It ! Ta elif Ta fi Ta while Ta case | | 433 | .It ! Ta elif Ta fi Ta while Ta case |
416 | .It else Ta for Ta then Ta { Ta } | | 434 | .It else Ta for Ta then Ta { Ta } |
417 | .It do Ta done Ta until Ta if Ta esac | | 435 | .It do Ta done Ta until Ta if Ta esac |
418 | .El | | 436 | .El |
419 | .Pp | | 437 | .Pp |
420 | Their meaning is discussed later. | | 438 | Their meaning is discussed later. |
421 | .Ss Aliases | | 439 | .Ss Aliases |
422 | An alias is a name and corresponding value set using the | | 440 | An alias is a name and corresponding value set using the |
423 | .Ic alias | | 441 | .Ic alias |
424 | built-in command. | | 442 | built-in command. |
425 | Whenever a reserved word may occur (see above), | | 443 | Whenever a reserved word may occur (see above), |
426 | and after checking for reserved words, the shell | | 444 | and after checking for reserved words, the shell |
427 | checks the word to see if it matches an alias. | | 445 | checks the word to see if it matches an alias. |
428 | If it does, it replaces it in the input stream with its value. | | 446 | If it does, it replaces it in the input stream with its value. |
429 | For example, if there is an alias called | | 447 | For example, if there is an alias called |
430 | .Dq lf | | 448 | .Dq lf |
431 | with the value | | 449 | with the value |
432 | .Dq "ls -F" , | | 450 | .Dq "ls -F" , |
433 | then the input: | | 451 | then the input: |
434 | .Pp | | 452 | .Pp |
435 | .Dl lf foobar Aq return | | 453 | .Dl lf foobar Aq return |
436 | .Pp | | 454 | .Pp |
437 | would become | | 455 | would become |
438 | .Pp | | 456 | .Pp |
439 | .Dl ls -F foobar Aq return | | 457 | .Dl ls -F foobar Aq return |
440 | .Pp | | 458 | .Pp |
441 | Aliases provide a convenient way for naive users to create shorthands for | | 459 | Aliases provide a convenient way for naive users to create shorthands for |
442 | commands without having to learn how to create functions with arguments. | | 460 | commands without having to learn how to create functions with arguments. |
443 | They can also be used to create lexically obscure code. | | 461 | They can also be used to create lexically obscure code. |
444 | This use is discouraged. | | 462 | This use is discouraged. |
445 | .Ss Commands | | 463 | .Ss Commands |
446 | The shell interprets the words it reads according to a language, the | | 464 | The shell interprets the words it reads according to a language, the |
447 | specification of which is outside the scope of this man page (refer to the | | 465 | specification of which is outside the scope of this man page (refer to the |
448 | BNF in the | | 466 | BNF in the |
449 | .Tn POSIX | | 467 | .Tn POSIX |
450 | 1003.2 document). | | 468 | 1003.2 document). |
451 | Essentially though, a line is read and if the first | | 469 | Essentially though, a line is read and if the first |
452 | word of the line (or after a control operator) is not a reserved word, | | 470 | word of the line (or after a control operator) is not a reserved word, |
453 | then the shell has recognized a simple command. | | 471 | then the shell has recognized a simple command. |
454 | Otherwise, a complex | | 472 | Otherwise, a complex |
455 | command or some other special construct may have been recognized. | | 473 | command or some other special construct may have been recognized. |
456 | .Ss Simple Commands | | 474 | .Ss Simple Commands |
457 | If a simple command has been recognized, the shell performs | | 475 | If a simple command has been recognized, the shell performs |
458 | the following actions: | | 476 | the following actions: |
459 | .Bl -enum -offset indent | | 477 | .Bl -enum -offset indent |
460 | .It | | 478 | .It |
461 | Leading words of the form | | 479 | Leading words of the form |
462 | .Dq name=value | | 480 | .Dq name=value |
463 | are stripped off and assigned to the environment of the simple command. | | 481 | are stripped off and assigned to the environment of the simple command. |
464 | Redirection operators and their arguments (as described below) are | | 482 | Redirection operators and their arguments (as described below) are |
465 | stripped off and saved for processing. | | 483 | stripped off and saved for processing. |
466 | .It | | 484 | .It |
467 | The remaining words are expanded as described in the | | 485 | The remaining words are expanded as described in the |
468 | .Sx Word Expansions | | 486 | .Sx Word Expansions |
469 | section below, | | 487 | section below, |
470 | and the first remaining word is considered the command name and the | | 488 | and the first remaining word is considered the command name and the |
471 | command is located. | | 489 | command is located. |
472 | The remaining words are considered the arguments of the command. | | 490 | The remaining words are considered the arguments of the command. |
473 | If no command name resulted, then the | | 491 | If no command name resulted, then the |
474 | .Dq name=value | | 492 | .Dq name=value |
475 | variable assignments recognized in item 1 affect the current shell. | | 493 | variable assignments recognized in item 1 affect the current shell. |
476 | .It | | 494 | .It |
477 | Redirections are performed as described in the next section. | | 495 | Redirections are performed as described in the next section. |
478 | .El | | 496 | .El |
479 | .Ss Redirections | | 497 | .Ss Redirections |
480 | Redirections are used to change where a command reads its input or sends | | 498 | Redirections are used to change where a command reads its input or sends |
481 | its output. | | 499 | its output. |
482 | In general, redirections open, close, or duplicate an | | 500 | In general, redirections open, close, or duplicate an |
483 | existing reference to a file. | | 501 | existing reference to a file. |
484 | The overall format used for redirection is: | | 502 | The overall format used for redirection is: |
485 | .Pp | | 503 | .Pp |
486 | .Dl [n] Va redir-op Ar file | | 504 | .Dl [n] Va redir-op Ar file |
487 | .Pp | | 505 | .Pp |
488 | where | | 506 | where |
489 | .Va redir-op | | 507 | .Va redir-op |
490 | is one of the redirection operators mentioned previously. | | 508 | is one of the redirection operators mentioned previously. |
491 | Following is a list of the possible redirections. | | 509 | Following is a list of the possible redirections. |
492 | The | | 510 | The |
493 | .Bq n | | 511 | .Bq n |
494 | is an optional number, as in | | 512 | is an optional number, as in |
495 | .Sq 3 | | 513 | .Sq 3 |
496 | (not | | 514 | (not |
497 | .Sq Bq 3 ) , | | 515 | .Sq Bq 3 ) , |
498 | that refers to a file descriptor. | | 516 | that refers to a file descriptor. |
499 | .Bl -tag -width aaabsfiles -offset indent | | 517 | .Bl -tag -width aaabsfiles -offset indent |
500 | .It [n] Ns \*[Gt] file | | 518 | .It [n] Ns \*[Gt] file |
501 | Redirect standard output (or n) to file. | | 519 | Redirect standard output (or n) to file. |
502 | .It [n] Ns \*[Gt]| file | | 520 | .It [n] Ns \*[Gt]| file |
503 | Same, but override the | | 521 | Same, but override the |
504 | .Fl C | | 522 | .Fl C |
505 | option. | | 523 | option. |
506 | .It [n] Ns \*[Gt]\*[Gt] file | | 524 | .It [n] Ns \*[Gt]\*[Gt] file |
507 | Append standard output (or n) to file. | | 525 | Append standard output (or n) to file. |
508 | .It [n] Ns \*[Lt] file | | 526 | .It [n] Ns \*[Lt] file |
509 | Redirect standard input (or n) from file. | | 527 | Redirect standard input (or n) from file. |
510 | .It [n1] Ns \*[Lt]\*[Am] Ns n2 | | 528 | .It [n1] Ns \*[Lt]\*[Am] Ns n2 |
511 | Duplicate standard input (or n1) from file descriptor n2. | | 529 | Duplicate standard input (or n1) from file descriptor n2. |
512 | .It [n] Ns \*[Lt]\*[Am]- | | 530 | .It [n] Ns \*[Lt]\*[Am]- |
513 | Close standard input (or n). | | 531 | Close standard input (or n). |
514 | .It [n1] Ns \*[Gt]\*[Am] Ns n2 | | 532 | .It [n1] Ns \*[Gt]\*[Am] Ns n2 |
515 | Duplicate standard output (or n1) to n2. | | 533 | Duplicate standard output (or n1) to n2. |
516 | .It [n] Ns \*[Gt]\*[Am]- | | 534 | .It [n] Ns \*[Gt]\*[Am]- |
517 | Close standard output (or n). | | 535 | Close standard output (or n). |
518 | .It [n] Ns \*[Lt]\*[Gt] file | | 536 | .It [n] Ns \*[Lt]\*[Gt] file |
519 | Open file for reading and writing on standard input (or n). | | 537 | Open file for reading and writing on standard input (or n). |
520 | .El | | 538 | .El |
521 | .Pp | | 539 | .Pp |
522 | The following redirection is often called a | | 540 | The following redirection is often called a |
523 | .Dq here-document . | | 541 | .Dq here-document . |
524 | .Bl -item -offset indent | | 542 | .Bl -item -offset indent |
525 | .It | | 543 | .It |
526 | .Li [n]\*[Lt]\*[Lt] delimiter | | 544 | .Li [n]\*[Lt]\*[Lt] delimiter |
527 | .Dl here-doc-text ... | | 545 | .Dl here-doc-text ... |
528 | .Li delimiter | | 546 | .Li delimiter |
529 | .El | | 547 | .El |
530 | .Pp | | 548 | .Pp |
531 | All the text on successive lines up to the delimiter, or to an EOF, is | | 549 | All the text on successive lines up to the delimiter, |
| | | 550 | which must appear on a line by itself, with nothing other |
| | | 551 | than an immediately following newline, is |
532 | saved away and made available to the command on standard input, or file | | 552 | saved away and made available to the command on standard input, or file |
533 | descriptor n if it is specified. | | 553 | descriptor n if it is specified. |
534 | If the delimiter as specified on the initial line is | | 554 | If the delimiter as specified on the initial line is |
535 | quoted, then the here-doc-text is treated literally; otherwise, the text is | | 555 | quoted, then the here-doc-text is treated literally; otherwise, the text is |
536 | subjected to parameter expansion, command substitution, and arithmetic | | 556 | subjected to parameter expansion, command substitution, and arithmetic |
537 | expansion as described in the | | 557 | expansion as described in the |
538 | .Sx Word Expansions | | 558 | .Sx Word Expansions |
539 | section below. | | 559 | section below. |
540 | If the operator is | | 560 | If the operator is |
541 | .Dq \*[Lt]\*[Lt]- | | 561 | .Dq \*[Lt]\*[Lt]\(mi |
542 | instead of | | 562 | instead of |
543 | .Dq \*[Lt]\*[Lt] , | | 563 | .Dq \*[Lt]\*[Lt] , |
544 | then leading tabs in the here-doc-text are stripped. | | 564 | then leading tabs in all lines in the here-doc-text, including before the |
| | | 565 | end delimiter, are stripped. |
| | | 566 | If the delimiter is not quoted, lines in here-doc-text that end with |
| | | 567 | an unquoted \e are joined to the following line, the \e and following |
| | | 568 | newline are simply removed while reading the here-doc, which thus guarantees |
| | | 569 | that neither of those lines can be the end delimiter. |
545 | .Ss Search and Execution | | 570 | .Ss Search and Execution |
546 | There are three types of commands: shell functions, built-in commands, and | | 571 | There are three types of commands: shell functions, built-in commands, and |
547 | normal programs -- and the command is searched for (by name) in that order. | | 572 | normal programs -- and the command is searched for (by name) in that order. |
548 | They each are executed in a different way. | | 573 | They each are executed in a different way. |
549 | .Pp | | 574 | .Pp |
550 | When a shell function is executed, all of the shell positional parameters | | 575 | When a shell function is executed, all of the shell positional parameters |
551 | (except $0, which remains unchanged) are set to the arguments of the shell | | 576 | (except $0, which remains unchanged) are set to the arguments of the shell |
552 | function. | | 577 | function. |
553 | The variables which are explicitly placed in the environment of | | 578 | The variables which are explicitly placed in the environment of |
554 | the command (by placing assignments to them before the function name) are | | 579 | the command (by placing assignments to them before the function name) are |
555 | made local to the function and are set to the values given. | | 580 | made local to the function and are set to the values given. |
556 | Then the command given in the function definition is executed. | | 581 | Then the command given in the function definition is executed. |
557 | The positional parameters are restored to their original values | | 582 | The positional parameters are restored to their original values |
558 | when the command completes. | | 583 | when the command completes. |
559 | This all occurs within the current shell. | | 584 | This all occurs within the current shell. |
560 | .Pp | | 585 | .Pp |
561 | Shell built-ins are executed internally to the shell, without spawning a | | 586 | Shell built-ins are executed internally to the shell, without spawning a |
562 | new process. | | 587 | new process. |
563 | .Pp | | 588 | .Pp |
564 | Otherwise, if the command name doesn't match a function or built-in, the | | 589 | Otherwise, if the command name doesn't match a function or built-in, the |
565 | command is searched for as a normal program in the file system (as | | 590 | command is searched for as a normal program in the file system (as |
566 | described in the next section). | | 591 | described in the next section). |
| | | 592 | .\" But the damned elusive filesystem shall never be defeated! |
567 | When a normal program is executed, the shell runs the program, | | 593 | When a normal program is executed, the shell runs the program, |
568 | passing the arguments and the environment to the program. | | 594 | passing the arguments and the environment to the program. |
569 | If the program is not a normal executable file (i.e., if it does | | 595 | If the program is not a normal executable file (i.e., if it does |
570 | not begin with the "magic number" whose | | 596 | not begin with the "magic number" whose |
571 | .Tn ASCII | | 597 | .Tn ASCII |
572 | representation is "#!", so | | 598 | representation is "#!", so |
573 | .Xr execve 2 | | 599 | .Xr execve 2 |
574 | returns | | 600 | returns |
575 | .Er ENOEXEC | | 601 | .Er ENOEXEC |
576 | then) the shell will interpret the program in a subshell. | | 602 | then) the shell will interpret the program in a subshell. |
577 | The child shell will reinitialize itself in this case, | | 603 | The child shell will reinitialize itself in this case, |
578 | so that the effect will be as if a | | 604 | so that the effect will be as if a |
579 | new shell had been invoked to handle the ad-hoc shell script, except that | | 605 | new shell had been invoked to handle the ad-hoc shell script, except that |
580 | the location of hashed commands located in the parent shell will be | | 606 | the location of hashed commands located in the parent shell will be |
581 | remembered by the child. | | 607 | remembered by the child. |
582 | .Pp | | 608 | .Pp |
583 | Note that previous versions of this document and the source code itself | | 609 | Note that previous versions of this document and the source code itself |
584 | misleadingly and sporadically refer to a shell script without a magic | | 610 | misleadingly and sporadically refer to a shell script without a magic |
585 | number as a "shell procedure". | | 611 | number as a "shell procedure". |
586 | .Ss Path Search | | 612 | .Ss Path Search |
587 | When locating a command, the shell first looks to see if it has a shell | | 613 | When locating a command, the shell first looks to see if it has a shell |
588 | function by that name. | | 614 | function by that name. |
589 | Then it looks for a built-in command by that name. | | 615 | Then it looks for a built-in command by that name. |
590 | If a built-in command is not found, one of two things happen: | | 616 | If a built-in command is not found, one of two things happen: |
591 | .Bl -enum | | 617 | .Bl -enum |
592 | .It | | 618 | .It |
593 | Command names containing a slash are simply executed without performing | | 619 | Command names containing a slash are simply executed without performing |
594 | any searches. | | 620 | any searches. |
595 | .It | | 621 | .It |
596 | The shell searches each entry in | | 622 | The shell searches each entry in |
597 | .Ev PATH | | 623 | .Ev PATH |
598 | in turn for the command. | | 624 | in turn for the command. |
599 | The value of the | | 625 | The value of the |
600 | .Ev PATH | | 626 | .Ev PATH |
601 | variable should be a series of entries separated by colons. | | 627 | variable should be a series of entries separated by colons. |
602 | Each entry consists of a directory name. | | 628 | Each entry consists of a directory name. |
603 | The current directory may be indicated | | 629 | The current directory may be indicated |
604 | implicitly by an empty directory name, or explicitly by a single period. | | 630 | implicitly by an empty directory name, or explicitly by a single period. |
605 | .El | | 631 | .El |
606 | .Ss Command Exit Status | | 632 | .Ss Command Exit Status |
607 | Each command has an exit status that can influence the behavior | | 633 | Each command has an exit status that can influence the behavior |
608 | of other shell commands. | | 634 | of other shell commands. |
609 | The paradigm is that a command exits | | 635 | The paradigm is that a command exits |
610 | with zero for normal or success, and non-zero for failure, | | 636 | with zero for normal or success, and non-zero for failure, |
611 | error, or a false indication. | | 637 | error, or a false indication. |
612 | The man page for each command | | 638 | The man page for each command |
613 | should indicate the various exit codes and what they mean. | | 639 | should indicate the various exit codes and what they mean. |
614 | Additionally, the built-in commands return exit codes, as does | | 640 | Additionally, the built-in commands return exit codes, as does |
615 | an executed shell function. | | 641 | an executed shell function. |
616 | .Pp | | 642 | .Pp |
617 | If a command consists entirely of variable assignments then the | | 643 | If a command consists entirely of variable assignments then the |
618 | exit status of the command is that of the last command substitution | | 644 | exit status of the command is that of the last command substitution |
619 | if any, otherwise 0. | | 645 | if any, otherwise 0. |
620 | .Ss Complex Commands | | 646 | .Ss Complex Commands |
621 | Complex commands are combinations of simple commands with control | | 647 | Complex commands are combinations of simple commands with control |
622 | operators or reserved words, together creating a larger complex command. | | 648 | operators or reserved words, together creating a larger complex command. |
623 | More generally, a command is one of the following: | | 649 | More generally, a command is one of the following: |
624 | .Bl -bullet | | 650 | .Bl -bullet |
625 | .It | | 651 | .It |
626 | simple command | | 652 | simple command |
627 | .It | | 653 | .It |
628 | pipeline | | 654 | pipeline |
629 | .It | | 655 | .It |
630 | list or compound-list | | 656 | list or compound-list |
631 | .It | | 657 | .It |
632 | compound command | | 658 | compound command |
633 | .It | | 659 | .It |
634 | function definition | | 660 | function definition |
635 | .El | | 661 | .El |
636 | .Pp | | 662 | .Pp |
637 | Unless otherwise stated, the exit status of a command is that of the last | | 663 | Unless otherwise stated, the exit status of a command is that of the last |
638 | simple command executed by the command. | | 664 | simple command executed by the command. |
639 | .Ss Pipelines | | 665 | .Ss Pipelines |
640 | A pipeline is a sequence of one or more commands separated | | 666 | A pipeline is a sequence of one or more commands separated |
641 | by the control operator |. | | 667 | by the control operator |. |
642 | The standard output of all but | | 668 | The standard output of all but |
643 | the last command is connected to the standard input | | 669 | the last command is connected to the standard input |
644 | of the next command. | | 670 | of the next command. |
645 | The standard output of the last | | 671 | The standard output of the last |
646 | command is inherited from the shell, as usual. | | 672 | command is inherited from the shell, as usual. |
647 | .Pp | | 673 | .Pp |
648 | The format for a pipeline is: | | 674 | The format for a pipeline is: |
649 | .Pp | | 675 | .Pp |
650 | .Dl [!] command1 [ | command2 ...] | | 676 | .Dl [!] command1 [ | command2 ...] |
651 | .Pp | | 677 | .Pp |
652 | The standard output of command1 is connected to the standard input of | | 678 | The standard output of command1 is connected to the standard input of |
653 | command2. | | 679 | command2. |
654 | The standard input, standard output, or both of a command is | | 680 | The standard input, standard output, or both of a command is |
655 | considered to be assigned by the pipeline before any redirection specified | | 681 | considered to be assigned by the pipeline before any redirection specified |
656 | by redirection operators that are part of the command. | | 682 | by redirection operators that are part of the command. |
657 | .Pp | | 683 | .Pp |
658 | If the pipeline is not in the background (discussed later), the shell | | 684 | If the pipeline is not in the background (discussed later), the shell |
659 | waits for all commands to complete. | | 685 | waits for all commands to complete. |
660 | .Pp | | 686 | .Pp |
661 | If the reserved word ! does not precede the pipeline, the exit status is | | 687 | If the reserved word ! does not precede the pipeline, the exit status is |
662 | the exit status of the last command specified in the pipeline. | | 688 | the exit status of the last command specified in the pipeline. |
663 | Otherwise, the exit status is the logical NOT of the exit status of the | | 689 | Otherwise, the exit status is the logical NOT of the exit status of the |
664 | last command. | | 690 | last command. |
665 | That is, if the last command returns zero, the exit status | | 691 | That is, if the last command returns zero, the exit status |
666 | is 1; if the last command returns greater than zero, the exit status is | | 692 | is 1; if the last command returns greater than zero, the exit status is |
667 | zero. | | 693 | zero. |
668 | .Pp | | 694 | .Pp |
669 | Because pipeline assignment of standard input or standard output or both | | 695 | Because pipeline assignment of standard input or standard output or both |
670 | takes place before redirection, it can be modified by redirection. | | 696 | takes place before redirection, it can be modified by redirection. |
671 | For example: | | 697 | For example: |
672 | .Pp | | 698 | .Pp |
673 | .Dl $ command1 2\*[Gt]\*[Am]1 | command2 | | 699 | .Dl $ command1 2\*[Gt]\*[Am]1 | command2 |
674 | .Pp | | 700 | .Pp |
675 | sends both the standard output and standard error of command1 | | 701 | sends both the standard output and standard error of command1 |
676 | to the standard input of command2. | | 702 | to the standard input of command2. |
677 | .Pp | | 703 | .Pp |
678 | A ; or | | 704 | A ; or |
679 | .Aq newline | | 705 | .Aq newline |
680 | terminator causes the preceding AND-OR-list (described | | 706 | terminator causes the preceding AND-OR-list (described |
681 | next) to be executed sequentially; a \*[Am] causes asynchronous execution of | | 707 | next) to be executed sequentially; a \*[Am] causes asynchronous execution of |
682 | the preceding AND-OR-list. | | 708 | the preceding AND-OR-list. |
683 | .Pp | | 709 | .Pp |
684 | Note that unlike some other shells, each process in the pipeline is a | | 710 | Note that unlike some other shells, each process in the pipeline is a |
685 | child of the invoking shell (unless it is a shell built-in, in which case | | 711 | child of the invoking shell (unless it is a shell built-in, in which case |
686 | it executes in the current shell -- but any effect it has on the | | 712 | it executes in the current shell -- but any effect it has on the |
687 | environment is wiped). | | 713 | environment is wiped). |
688 | .Ss Background Commands -- \*[Am] | | 714 | .Ss Background Commands -- \*[Am] |
689 | If a command is terminated by the control operator ampersand (\*[Am]), the | | 715 | If a command is terminated by the control operator ampersand (\*[Am]), the |
690 | shell executes the command asynchronously -- that is, the shell does not | | 716 | shell executes the command asynchronously -- that is, the shell does not |
691 | wait for the command to finish before executing the next command. | | 717 | wait for the command to finish before executing the next command. |
692 | .Pp | | 718 | .Pp |
693 | The format for running a command in background is: | | 719 | The format for running a command in background is: |
694 | .Pp | | 720 | .Pp |
695 | .Dl command1 \*[Am] [command2 \*[Am] ...] | | 721 | .Dl command1 \*[Am] [command2 \*[Am] ...] |
696 | .Pp | | 722 | .Pp |
697 | If the shell is not interactive, the standard input of an asynchronous | | 723 | If the shell is not interactive, the standard input of an asynchronous |
698 | command is set to | | 724 | command is set to |
699 | .Pa /dev/null . | | 725 | .Pa /dev/null . |
| | | 726 | The process identifier of the most recent command started in the |
| | | 727 | background can be obtained from the value of the special parameter |
| | | 728 | .Dq \&! |
| | | 729 | (see |
| | | 730 | .Sx Special Parameters ) . |
700 | .Ss Lists -- Generally Speaking | | 731 | .Ss Lists -- Generally Speaking |
701 | A list is a sequence of zero or more commands separated by newlines, | | 732 | A list is a sequence of zero or more commands separated by newlines, |
702 | semicolons, or ampersands, and optionally terminated by one of these three | | 733 | semicolons, or ampersands, and optionally terminated by one of these three |
703 | characters. | | 734 | characters. |
704 | The commands in a list are executed in the order they are written. | | 735 | The commands in a list are executed in the order they are written. |
705 | If command is followed by an ampersand, the shell starts the | | 736 | If command is followed by an ampersand, the shell starts the |
706 | command and immediately proceed onto the next command; otherwise it waits | | 737 | command and immediately proceeds to the next command; otherwise it waits |
707 | for the command to terminate before proceeding to the next one. | | 738 | for the command to terminate before proceeding to the next one. |
708 | .Ss Short-Circuit List Operators | | 739 | .Ss Short-Circuit List Operators |
709 | .Dq \*[Am]\*[Am] | | 740 | .Dq \*[Am]\*[Am] |
710 | and | | 741 | and |
711 | .Dq || | | 742 | .Dq || |
712 | are AND-OR list operators. | | 743 | are AND-OR list operators. |
713 | .Dq \*[Am]\*[Am] | | 744 | .Dq \*[Am]\*[Am] |
714 | executes the first command, and then executes the second command if and only | | 745 | executes the first command, and then executes the second command if and only |
715 | if the exit status of the first command is zero. | | 746 | if the exit status of the first command is zero. |
716 | .Dq || | | 747 | .Dq || |
717 | is similar, but executes the second command if and only if the exit status | | 748 | is similar, but executes the second command if and only if the exit status |
718 | of the first command is nonzero. | | 749 | of the first command is nonzero. |
719 | .Dq \*[Am]\*[Am] | | 750 | .Dq \*[Am]\*[Am] |
720 | and | | 751 | and |
721 | .Dq || | | 752 | .Dq || |
722 | both have the same priority. | | 753 | both have the same priority. |
723 | Note that these operators are left-associative, so | | 754 | Note that these operators are left-associative, so |
724 | .Dq true || echo bar \*[Am]\*[Am] echo baz | | 755 | .Dq true || echo bar \*[Am]\*[Am] echo baz |
725 | writes | | 756 | writes |
726 | .Dq baz | | 757 | .Dq baz |
727 | and nothing else. | | 758 | and nothing else. |
728 | This is not the way it works in C. | | 759 | This is not the way it works in C. |
729 | Also, if you forget the left-hand side (for example when continuing lines but | | 760 | Also, if you forget the left-hand side (for example when continuing lines but |
730 | forgetting to use a backslash) it defaults to a true statement. | | 761 | forgetting to use a backslash) it defaults to a true statement. |
731 | This behavior is not useful and should not be relied upon. | | 762 | This behavior is not useful and should not be relied upon. |
732 | Similarly, if input to the | | 763 | Similarly, if input to the |
733 | .Nm | | 764 | .Nm |
734 | reaches end of file immediately after one of these operators, | | 765 | reaches end of file immediately after one of these operators, |
735 | it is assumed that a true statement follows. | | 766 | it is assumed that a true statement follows. |
736 | This behavior is also not useful and should not be relied upon. | | 767 | This behavior is also not useful and should not be relied upon. |
737 | .Ss Flow-Control Constructs -- if, while, for, case | | 768 | .Ss Flow-Control Constructs -- if, while, for, case |
738 | The syntax of the if command is | | 769 | The syntax of the if command is |
739 | .Bd -literal -offset indent | | 770 | .Bd -literal -offset indent |
740 | if list | | 771 | if list |
741 | then list | | 772 | then list |
742 | [ elif list | | 773 | [ elif list |
743 | then list ] ... | | 774 | then list ] ... |
744 | [ else list ] | | 775 | [ else list ] |
745 | fi | | 776 | fi |
746 | .Ed | | 777 | .Ed |
747 | .Pp | | 778 | .Pp |
748 | The syntax of the while command is | | 779 | The syntax of the while command is |
749 | .Bd -literal -offset indent | | 780 | .Bd -literal -offset indent |
750 | while list | | 781 | while list |
751 | do list | | 782 | do list |
752 | done | | 783 | done |
753 | .Ed | | 784 | .Ed |
754 | .Pp | | 785 | .Pp |
755 | The two lists are executed repeatedly while the exit status of the | | 786 | The two lists are executed repeatedly while the exit status of the |
756 | first list is zero. | | 787 | first list is zero. |
757 | The until command is similar, but has the word | | 788 | The until command is similar, but has the word |
758 | until in place of while, which causes it to | | 789 | until in place of while, which causes it to |
759 | repeat until the exit status of the first list is zero. | | 790 | repeat until the exit status of the first list is zero. |
760 | .Pp | | 791 | .Pp |
761 | The syntax of the for command is | | 792 | The syntax of the for command is |
762 | .Bd -literal -offset indent | | 793 | .Bd -literal -offset indent |
763 | for variable in word ... | | 794 | for variable [ in word ... ] |
764 | do list | | 795 | do list |
765 | done | | 796 | done |
766 | .Ed | | 797 | .Ed |
767 | .Pp | | 798 | .Pp |
768 | The words are expanded, and then the list is executed repeatedly with the | | 799 | The words are expanded, or "$@" if no words are given, |
| | | 800 | and then the list is executed repeatedly with the |
769 | variable set to each word in turn. | | 801 | variable set to each word in turn. |
770 | do and done may be replaced with | | 802 | do and done may be replaced with |
771 | .Dq { | | 803 | .Dq { |
772 | and | | 804 | and |
773 | .Dq } . | | 805 | .Dq } , |
| | | 806 | but doing so is non-standard and not recommended. |
774 | .Pp | | 807 | .Pp |
775 | The syntax of the break and continue command is | | 808 | The syntax of the break and continue command is |
776 | .Bd -literal -offset indent | | 809 | .Bd -literal -offset indent |
777 | break [ num ] | | 810 | break [ num ] |
778 | continue [ num ] | | 811 | continue [ num ] |
779 | .Ed | | 812 | .Ed |
780 | .Pp | | 813 | .Pp |
781 | Break terminates the num innermost for or while loops. | | 814 | Break terminates the num innermost for or while loops. |
782 | Continue continues with the next iteration of the innermost loop. | | 815 | Continue continues with the next iteration of the innermost loop. |
783 | These are implemented as built-in commands. | | 816 | These are implemented as built-in commands. |
784 | .Pp | | 817 | .Pp |
785 | The syntax of the case command is | | 818 | The syntax of the case command is |
786 | .Bd -literal -offset indent | | 819 | .Bd -literal -offset indent |
787 | case word in | | 820 | case word in |
788 | pattern) list ;; | | 821 | pattern) list ;; |
789 | \&... | | 822 | \&... |
790 | esac | | 823 | esac |
791 | .Ed | | 824 | .Ed |
792 | .Pp | | 825 | .Pp |
793 | The pattern can actually be one or more patterns (see | | 826 | The pattern can actually be one or more patterns (see |
794 | .Sx Shell Patterns | | 827 | .Sx Shell Patterns |
795 | described later), separated by | | 828 | described later), separated by |
796 | .Dq \*(Ba | | 829 | .Dq \*(Ba |
797 | characters. | | 830 | characters. |
798 | .Ss Grouping Commands Together | | 831 | .Ss Grouping Commands Together |
799 | Commands may be grouped by writing either | | 832 | Commands may be grouped by writing either |
800 | .Pp | | 833 | .Pp |
801 | .Dl (list) | | 834 | .Dl (list) |
802 | .Pp | | 835 | .Pp |
803 | or | | 836 | or |
804 | .Pp | | 837 | .Pp |
805 | .Dl { list; } | | 838 | .Dl { list; } |
806 | .Pp | | 839 | .Pp |
807 | The first of these executes the commands in a subshell. | | 840 | The first of these executes the commands in a subshell. |
808 | Built-in commands grouped into a (list) will not affect the current shell. | | 841 | Built-in commands grouped into a (list) will not affect the current shell. |
809 | The second form does not fork another shell so is slightly more efficient. | | 842 | The second form does not fork another shell so is slightly more efficient. |
810 | Grouping commands together this way allows you to redirect | | 843 | Grouping commands together this way allows you to redirect |
811 | their output as though they were one program: | | 844 | their output as though they were one program: |
812 | .Bd -literal -offset indent | | 845 | .Bd -literal -offset indent |
813 | { echo -n \*q hello \*q ; echo \*q world" ; } \*[Gt] greeting | | 846 | { echo -n \*q hello \*q ; echo \*q world" ; } \*[Gt] greeting |
814 | .Ed | | 847 | .Ed |
815 | .Pp | | 848 | .Pp |
816 | Note that | | 849 | Note that |
817 | .Dq } | | 850 | .Dq } |
818 | must follow a control operator (here, | | 851 | must follow a control operator (here, |
819 | .Dq \&; ) | | 852 | .Dq \&; ) |
820 | so that it is recognized as a reserved word and not as another command argument. | | 853 | so that it is recognized as a reserved word and not as another command argument. |
821 | .Ss Functions | | 854 | .Ss Functions |
822 | The syntax of a function definition is | | 855 | The syntax of a function definition is |
823 | .Pp | | 856 | .Pp |
824 | .Dl name ( ) command | | 857 | .Dl name ( ) command [ redirect... ] |
825 | .Pp | | 858 | .Pp |
826 | A function definition is an executable statement; when executed it | | 859 | A function definition is an executable statement; when executed it |
827 | installs a function named name and returns an exit status of zero. | | 860 | installs a function named name and returns an exit status of zero. |
828 | The command is normally a list enclosed between | | 861 | The command is normally a list enclosed between |
829 | .Dq { | | 862 | .Dq { |
830 | and | | 863 | and |
831 | .Dq } . | | 864 | .Dq } . |
| | | 865 | The standard syntax also allows the command to be any of the other |
| | | 866 | compound commands, or a sub-shell, all of which are supported. |
| | | 867 | As an extension, this shell also allows a simple command to be |
| | | 868 | used, though users should be aware this is non-standard syntax. |
| | | 869 | This means that |
| | | 870 | .Dl l() ls "$@" |
| | | 871 | works to make |
| | | 872 | .Dq l |
| | | 873 | an alternative name for the |
| | | 874 | .Ic ls |
| | | 875 | command. |
| | | 876 | .Pp |
| | | 877 | If the optional redirect, (see |
| | | 878 | .Sx Redirections ) , |
| | | 879 | which may be of any of the normal forms, |
| | | 880 | is given, it is applied each time the |
| | | 881 | function is called. |
| | | 882 | This means that a simple |
| | | 883 | .Dq "Hello World |
| | | 884 | function might be written (in the extended syntax) as: |
| | | 885 | .Dl hello() cat <<EOF |
| | | 886 | .Dl Hello World! |
| | | 887 | .Dl EOF |
| | | 888 | To be correctly standards conforming this should be re-written as: |
| | | 889 | .Dl hello() { cat; } <<EOF |
| | | 890 | .Dl Hello World! |
| | | 891 | .Dl EOF |
| | | 892 | Note the distinction between those forms, and |
| | | 893 | .Dl hello() { cat <<EOF |
| | | 894 | .Dl Hello World! |
| | | 895 | .Dl EOF |
| | | 896 | .Dl \&} |
| | | 897 | which reads and processes the |
| | | 898 | .Ic "here document |
| | | 899 | each time the shell executes the function, and which applies |
| | | 900 | that input only to the cat command, not to any other commands |
| | | 901 | that might appear in the function. |
832 | .Pp | | 902 | .Pp |
833 | Variables may be declared to be local to a function by using a local | | 903 | Variables may be declared to be local to a function by using a local |
834 | command. | | 904 | command. |
835 | This should appear as the first statement of a function, and the syntax is | | 905 | This should appear as the first statement of a function, and the syntax is |
836 | .Pp | | 906 | .Pp |
837 | .Dl local [ variable | - ] ... | | 907 | .Dl local [ variable | - ] ... |
838 | .Pp | | 908 | .Pp |
839 | .Dq Local | | 909 | .Dq Ic local |
840 | is implemented as a built-in command. | | 910 | is implemented as a built-in command. |
841 | .Pp | | 911 | .Pp |
842 | When a variable is made local, it inherits the initial value and exported | | 912 | When a variable is made local, it inherits the initial value and exported, |
| | | 913 | unexportable, |
843 | and read-only flags from the variable with the same name in the surrounding | | 914 | and read-only flags from the variable with the same name in the surrounding |
844 | scope, if there is one. | | 915 | scope, if there is one. |
845 | Otherwise, the variable is initially unset. | | 916 | Otherwise, the variable is initially unset. |
| | | 917 | Making a read-only variable local is possible, but pointless. |
| | | 918 | If the |
| | | 919 | .Ic readonly |
| | | 920 | command is applied to a variable that has been declared local, |
| | | 921 | the variable cannot be (further) modified within the function, |
| | | 922 | or any other functions it calls, however when the function returns, |
| | | 923 | the previous status (and value) of the variable is returned. |
| | | 924 | .Pp |
| | | 925 | Values may be given to local variables on the |
| | | 926 | .Ic local |
| | | 927 | command line in a similar fashion as used for |
| | | 928 | .Ic export |
| | | 929 | and |
| | | 930 | .Ic readonly . |
| | | 931 | .Pp |
846 | The shell uses dynamic scoping, so that if you make the variable x local to | | 932 | The shell uses dynamic scoping, so that if you make the variable x local to |
847 | function f, which then calls function g, references to the variable x made | | 933 | function f, which then calls function g, references to the variable x made |
848 | inside g will refer to the variable x declared inside f, not to the global | | 934 | inside g will refer to the variable x declared inside f, not to the global |
849 | variable named x. | | 935 | variable named x. |
850 | .Pp | | 936 | .Pp |
| | | 937 | Note that the parameters $1, $2, ... (see |
| | | 938 | .Sx Positional Parameters ) , |
| | | 939 | and $#, $* and $@ (see |
| | | 940 | .Sx Special Parameters ) , |
| | | 941 | are always made local in all functions, and are reset inside the |
| | | 942 | function to represent the options and arguments passed to the function. |
| | | 943 | Note that $0 however retains the value it had outside the function, |
| | | 944 | as do all the other special parameters. |
| | | 945 | .Pp |
851 | The only special parameter that can be made local is | | 946 | The only special parameter that can be made local is |
852 | .Dq - . | | 947 | .Dq - . |
853 | Making | | 948 | Making |
854 | .Dq - | | 949 | .Dq - |
855 | local causes any shell options that are changed via the set command inside the | | 950 | local causes any shell options that are changed via the set command inside the |
856 | function to be restored to their original values when the function | | 951 | function to be restored to their original values when the function |
857 | returns. | | 952 | returns. |
858 | .Pp | | 953 | .Pp |
| | | 954 | It is a syntax error to use |
| | | 955 | .Ic local |
| | | 956 | outside the scope of a function definition. |
| | | 957 | When used inside a function, it exits with status 0. |
| | | 958 | .Pp |
859 | The syntax of the return command is | | 959 | The syntax of the return command is |
860 | .Pp | | 960 | .Pp |
861 | .Dl return [ exitstatus ] | | 961 | .Dl return [ exitstatus ] |
862 | .Pp | | 962 | .Pp |
863 | It terminates the currently executing function. | | 963 | It terminates the currently executing function or |
| | | 964 | .Dq \&. |
| | | 965 | script. |
864 | Return is implemented as a built-in command. | | 966 | Return is implemented as a built-in command. |
| | | 967 | The exit status of the function (or |
| | | 968 | .Dl \&. |
| | | 969 | command) is either that given on the |
| | | 970 | .Ic return |
| | | 971 | command line, or the value of the special parameter |
| | | 972 | .Dq $? |
| | | 973 | immediately before the return was executed. |
865 | .Ss Variables and Parameters | | 974 | .Ss Variables and Parameters |
866 | The shell maintains a set of parameters. | | 975 | The shell maintains a set of parameters. |
867 | A parameter denoted by a name is called a variable. | | 976 | A parameter denoted by a name is called a variable. |
868 | When starting up, the shell turns all the environment | | 977 | When starting up, the shell turns all the environment |
869 | variables into shell variables. | | 978 | variables into shell variables. |
870 | New variables can be set using the form | | 979 | New variables can be set using the form |
871 | .Pp | | 980 | .Pp |
872 | .Dl name=value | | 981 | .Dl name=value |
873 | .Pp | | 982 | .Pp |
874 | Variables set by the user must have a name consisting solely of | | 983 | Variables set by the user must have a name consisting solely of |
875 | alphabetics, numerics, and underscores - the first of which must not be | | 984 | alphabetics, numerics, and underscores - the first of which must not be |
876 | numeric. | | 985 | numeric. |
877 | A parameter can also be denoted by a number or a special | | 986 | A parameter can also be denoted by a number or a special |
878 | character as explained below. | | 987 | character as explained below. |
879 | .Ss Positional Parameters | | 988 | .Ss Positional Parameters |
880 | A positional parameter is a parameter denoted by a number (n \*[Gt] 0). | | 989 | A positional parameter is a parameter denoted by a number (n \*[Gt] 0). |
881 | The shell sets these initially to the values of its command line arguments | | 990 | The shell sets these initially to the values of its command line arguments |
882 | that follow the name of the shell script. | | 991 | that follow the name of the shell script. |
883 | The | | 992 | The |
884 | .Ic set | | 993 | .Ic set |
885 | built-in can also be used to set or reset them. | | 994 | built-in can also be used to set or reset them, and |
| | | 995 | .Ic shift |
| | | 996 | can be used to manipulate the list. |
| | | 997 | .Pp |
| | | 998 | To refer to the 10th (and later) positional parameters, |
| | | 999 | the form ${n} must be used. |
| | | 1000 | Without the braces, a digit following |
| | | 1001 | .Dq $ |
| | | 1002 | can only refer to one of the first 9 positional parameters, |
| | | 1003 | or the special parameter |
| | | 1004 | .Dq 0 . |
| | | 1005 | The word |
| | | 1006 | .Dq $10 |
| | | 1007 | is treated identically to |
| | | 1008 | .Dq ${1}0 . |
886 | .Ss Special Parameters | | 1009 | .Ss Special Parameters |
887 | A special parameter is a parameter denoted by one of the following special | | 1010 | A special parameter is a parameter denoted by one of the following special |
888 | characters. | | 1011 | characters. |
889 | The value of the parameter is listed next to its character. | | 1012 | The value of the parameter is listed next to its character. |
890 | .Bl -tag -width thinhyphena | | 1013 | .Bl -tag -width thinhyphena |
891 | .It * | | 1014 | .It * |
892 | Expands to the positional parameters, starting from one. | | 1015 | Expands to the positional parameters, starting from one. |
893 | When the | | 1016 | When the |
894 | expansion occurs within a double-quoted string it expands to a single | | 1017 | expansion occurs within a double-quoted string it expands to a single |
895 | field with the value of each parameter separated by the first character of | | 1018 | field with the value of each parameter separated by the first character of |
896 | the | | 1019 | the |
897 | .Ev IFS | | 1020 | .Ev IFS |
898 | variable, or by a | | 1021 | variable, or by a |
899 | .Aq space | | 1022 | .Aq space |
900 | if | | 1023 | if |
901 | .Ev IFS | | 1024 | .Ev IFS |
902 | is unset. | | 1025 | is unset. |
903 | .It @ | | 1026 | .It @ |
904 | Expands to the positional parameters, starting from one. | | 1027 | Expands to the positional parameters, starting from one. |
905 | When the expansion occurs within double quotes, each positional | | 1028 | When the expansion occurs within double quotes, each positional |
906 | parameter expands as a separate argument. | | 1029 | parameter expands as a separate argument. |
907 | If there are no positional parameters, the | | 1030 | If there are no positional parameters, the |
908 | expansion of @ generates zero arguments, even when @ is | | 1031 | expansion of @ generates zero arguments, even when @ is |
909 | double-quoted. | | 1032 | double-quoted. |
910 | What this basically means, for example, is | | 1033 | What this basically means, for example, is |
911 | if $1 is | | 1034 | if $1 is |
912 | .Dq abc | | 1035 | .Dq abc |
913 | and $2 is | | 1036 | and $2 is |
914 | .Dq def ghi , | | 1037 | .Dq def ghi , |
915 | then | | 1038 | then |
916 | .Qq $@ | | 1039 | .Qq $@ |
917 | expands to | | 1040 | expands to |
918 | the two arguments: | | 1041 | the two arguments: |
919 | .Pp | | 1042 | .Pp |
920 | .Sm off | | 1043 | .Sm off |
921 | .Dl \*q abc \*q \ \*q def\ ghi \*q | | 1044 | .Dl \*q abc \*q \ \*q def\ ghi \*q |
922 | .Sm on | | 1045 | .Sm on |
923 | .It # | | 1046 | .It # |
924 | Expands to the number of positional parameters. | | 1047 | Expands to the number of positional parameters. |
925 | .It \&? | | 1048 | .It \&? |
926 | Expands to the exit status of the most recent pipeline. | | 1049 | Expands to the exit status of the most recent pipeline. |
927 | .It - (Hyphen.) | | 1050 | .It - (Hyphen.) |
928 | Expands to the current option flags (the single-letter | | 1051 | Expands to the current option flags (the single-letter |
929 | option names concatenated into a string) as specified on | | 1052 | option names concatenated into a string) as specified on |
930 | invocation, by the set built-in command, or implicitly | | 1053 | invocation, by the set built-in command, or implicitly |
931 | by the shell. | | 1054 | by the shell. |
932 | .It $ | | 1055 | .It $ |
933 | Expands to the process ID of the invoked shell. | | 1056 | Expands to the process ID of the invoked shell. |
934 | A subshell retains the same value of $ as its parent. | | 1057 | A subshell retains the same value of $ as its parent. |
935 | .It \&! | | 1058 | .It \&! |
936 | Expands to the process ID of the most recent background | | 1059 | Expands to the process ID of the most recent background |
937 | command executed from the current shell. | | 1060 | command executed from the current shell. |
938 | For a pipeline, the process ID is that of the last command in the pipeline. | | 1061 | For a pipeline, the process ID is that of the last command in the pipeline. |
| | | 1062 | If no background commands have yet been started by the shell, then |
| | | 1063 | .Dq \&! |
| | | 1064 | will be unset. |
| | | 1065 | Once set, the value of |
| | | 1066 | .Dq \&! |
| | | 1067 | will be retained until another background command is started. |
939 | .It 0 (Zero.) | | 1068 | .It 0 (Zero.) |
940 | Expands to the name of the shell or shell script. | | 1069 | Expands to the name of the shell or shell script. |
941 | .El | | 1070 | .El |
942 | .Ss Word Expansions | | 1071 | .Ss Word Expansions |
943 | This section describes the various expansions that are performed on words. | | 1072 | This section describes the various expansions that are performed on words. |
944 | Not all expansions are performed on every word, as explained later. | | 1073 | Not all expansions are performed on every word, as explained later. |
945 | .Pp | | 1074 | .Pp |
946 | Tilde expansions, parameter expansions, command substitutions, arithmetic | | 1075 | Tilde expansions, parameter expansions, command substitutions, arithmetic |
947 | expansions, and quote removals that occur within a single word expand to a | | 1076 | expansions, and quote removals that occur within a single word expand to a |
948 | single field. | | 1077 | single field. |
949 | It is only field splitting or pathname expansion that can | | 1078 | It is only field splitting or pathname expansion that can |
950 | create multiple fields from a single word. | | 1079 | create multiple fields from a single word. |
951 | The single exception to this | | 1080 | The single exception to this |
952 | rule is the expansion of the special parameter @ within double quotes, as | | 1081 | rule is the expansion of the special parameter @ within double quotes, as |
953 | was described above. | | 1082 | was described above. |
954 | .Pp | | 1083 | .Pp |
955 | The order of word expansion is: | | 1084 | The order of word expansion is: |
956 | .Bl -enum | | 1085 | .Bl -enum |
957 | .It | | 1086 | .It |
958 | Tilde Expansion, Parameter Expansion, Command Substitution, | | 1087 | Tilde Expansion, Parameter Expansion, Command Substitution, |
959 | Arithmetic Expansion (these all occur at the same time). | | 1088 | Arithmetic Expansion (these all occur at the same time). |
960 | .It | | 1089 | .It |
961 | Field Splitting is performed on fields | | 1090 | Field Splitting is performed on fields |
962 | generated by step (1) unless the | | 1091 | generated by step (1) unless the |
963 | .Ev IFS | | 1092 | .Ev IFS |
964 | variable is null. | | 1093 | variable is null. |
965 | .It | | 1094 | .It |
966 | Pathname Expansion (unless set | | 1095 | Pathname Expansion (unless set |
967 | .Fl f | | 1096 | .Fl f |
968 | is in effect). | | 1097 | is in effect). |
969 | .It | | 1098 | .It |
970 | Quote Removal. | | 1099 | Quote Removal. |
971 | .El | | 1100 | .El |
972 | .Pp | | 1101 | .Pp |
973 | The $ character is used to introduce parameter expansion, command | | 1102 | The $ character is used to introduce parameter expansion, command |
974 | substitution, or arithmetic evaluation. | | 1103 | substitution, or arithmetic evaluation. |
975 | .Ss Tilde Expansion (substituting a user's home directory) | | 1104 | .Ss Tilde Expansion (substituting a user's home directory) |
976 | A word beginning with an unquoted tilde character (~) is | | 1105 | A word beginning with an unquoted tilde character (~) is |
977 | subjected to tilde expansion. | | 1106 | subjected to tilde expansion. |
978 | All the characters up to | | 1107 | All the characters up to |
979 | a slash (/) or the end of the word are treated as a username | | 1108 | a slash (/) or the end of the word are treated as a username |
980 | and are replaced with the user's home directory. | | 1109 | and are replaced with the user's home directory. |
981 | If the username is missing (as in | | 1110 | If the username is missing (as in |
982 | .Pa ~/foobar ) , | | 1111 | .Pa ~/foobar ) , |
983 | the tilde is replaced with the value of the | | 1112 | the tilde is replaced with the value of the |
984 | .Va HOME | | 1113 | .Va HOME |
985 | variable (the current user's home directory). | | 1114 | variable (the current user's home directory). |
986 | .Ss Parameter Expansion | | 1115 | .Ss Parameter Expansion |
987 | The format for parameter expansion is as follows: | | 1116 | The format for parameter expansion is as follows: |
988 | .Pp | | 1117 | .Pp |
989 | .Dl ${expression} | | 1118 | .Dl ${expression} |
990 | .Pp | | 1119 | .Pp |
991 | where expression consists of all characters until the matching | | 1120 | where expression consists of all characters until the matching |
992 | .Dq } . | | 1121 | .Dq } . |
993 | Any | | 1122 | Any |
994 | .Dq } | | 1123 | .Dq } |
995 | escaped by a backslash or within a quoted string, and characters in | | 1124 | escaped by a backslash or within a quoted string, and characters in |
996 | embedded arithmetic expansions, command substitutions, and variable | | 1125 | embedded arithmetic expansions, command substitutions, and variable |
997 | expansions, are not examined in determining the matching | | 1126 | expansions, are not examined in determining the matching |
998 | .Dq } . | | 1127 | .Dq } . |
999 | .Pp | | 1128 | .Pp |
1000 | The simplest form for parameter expansion is: | | 1129 | The simplest form for parameter expansion is: |
1001 | .Pp | | 1130 | .Pp |
1002 | .Dl ${parameter} | | 1131 | .Dl ${parameter} |
1003 | .Pp | | 1132 | .Pp |
1004 | The value, if any, of parameter is substituted. | | 1133 | The value, if any, of parameter is substituted. |
1005 | .Pp | | 1134 | .Pp |
1006 | The parameter name or symbol can be enclosed in braces, which are | | 1135 | The parameter name or symbol can be enclosed in braces, which are |
1007 | optional except for positional parameters with more than one digit or | | 1136 | optional except for positional parameters with more than one digit or |
1008 | when parameter is followed by a character that could be interpreted as | | 1137 | when parameter is followed by a character that could be interpreted as |
1009 | part of the name. | | 1138 | part of the name. |
1010 | If a parameter expansion occurs inside double quotes: | | 1139 | If a parameter expansion occurs inside double quotes: |
1011 | .Bl -enum | | 1140 | .Bl -enum |
1012 | .It | | 1141 | .It |
1013 | Pathname expansion is not performed on the results of the expansion. | | 1142 | Pathname expansion is not performed on the results of the expansion. |
1014 | .It | | 1143 | .It |
1015 | Field splitting is not performed on the results of the | | 1144 | Field splitting is not performed on the results of the |
1016 | expansion, with the exception of the special rules for @. | | 1145 | expansion, with the exception of the special rules for @. |
1017 | .El | | 1146 | .El |
1018 | .Pp | | 1147 | .Pp |
1019 | In addition, a parameter expansion can be modified by using one of the | | 1148 | In addition, a parameter expansion can be modified by using one of the |
1020 | following formats. | | 1149 | following formats. |
1021 | If the | | 1150 | If the |
1022 | .Dq Dv \&: | | 1151 | .Dq Dv \&: |
1023 | is omitted in the following modifiers, then the expansion is applied only | | 1152 | is omitted in the following modifiers, then the expansion is applied only |
1024 | to unset parameters, not null ones. | | 1153 | to unset parameters, not null ones. |
1025 | .Bl -tag -width aaparameterwordaaaaa | | 1154 | .Bl -tag -width aaparameterwordaaaaa |
1026 | .It ${parameter:-word} | | 1155 | .It ${parameter:\(miword} |
1027 | Use Default Values. | | 1156 | Use Default Values. |
1028 | If parameter is unset or null, the expansion of word | | 1157 | If parameter is unset or null, the expansion of word |
1029 | is substituted; otherwise, the value of parameter is substituted. | | 1158 | is substituted; otherwise, the value of parameter is substituted. |
1030 | .It ${parameter:=word} | | 1159 | .It ${parameter:=word} |
1031 | Assign Default Values. | | 1160 | Assign Default Values. |
1032 | If parameter is unset or null, the expansion of | | 1161 | If parameter is unset or null, the expansion of |
1033 | word is assigned to parameter. | | 1162 | word is assigned to parameter. |
1034 | In all cases, the final value of parameter is substituted. | | 1163 | In all cases, the final value of parameter is substituted. |
1035 | Only variables, not positional parameters or special | | 1164 | Only variables, not positional parameters or special |
1036 | parameters, can be assigned in this way. | | 1165 | parameters, can be assigned in this way. |
1037 | .It ${parameter:?[word]} | | 1166 | .It ${parameter:?[word]} |
1038 | Indicate Error if Null or Unset. | | 1167 | Indicate Error if Null or Unset. |
1039 | If parameter is unset or null, the | | 1168 | If parameter is unset or null, the |
1040 | expansion of word (or a message indicating it is unset if word is omitted) | | 1169 | expansion of word (or a message indicating it is unset if word is omitted) |
1041 | is written to standard error and the shell exits with a nonzero exit status. | | 1170 | is written to standard error and the shell exits with a nonzero exit status. |
1042 | Otherwise, the value of parameter is substituted. | | 1171 | Otherwise, the value of parameter is substituted. |
1043 | An interactive shell need not exit. | | 1172 | An interactive shell need not exit. |
1044 | .It ${parameter:+word} | | 1173 | .It ${parameter:+word} |
1045 | Use Alternative Value. | | 1174 | Use Alternative Value. |
1046 | If parameter is unset or null, null is | | 1175 | If parameter is unset or null, null is |
1047 | substituted; otherwise, the expansion of word is substituted. | | 1176 | substituted; otherwise, the expansion of word is substituted. |
1048 | .It ${#parameter} | | 1177 | .It ${#parameter} |
1049 | String Length. | | 1178 | String Length. |
1050 | The length in characters of the value of parameter. | | 1179 | The length in characters of the value of parameter. |
1051 | .El | | 1180 | .El |
1052 | .Pp | | 1181 | .Pp |
1053 | The following four varieties of parameter expansion provide for substring | | 1182 | The following four varieties of parameter expansion provide for substring |
1054 | processing. | | 1183 | processing. |
1055 | In each case, pattern matching notation (see | | 1184 | In each case, pattern matching notation (see |
1056 | .Sx Shell Patterns ) , | | 1185 | .Sx Shell Patterns ) , |
1057 | rather than regular expression notation, is used to evaluate the patterns. | | 1186 | rather than regular expression notation, is used to evaluate the patterns. |
1058 | If parameter is * or @, the result of the expansion is unspecified. | | 1187 | If parameter is * or @, the result of the expansion is unspecified. |
1059 | Enclosing the full parameter expansion string in double quotes does not | | 1188 | Enclosing the full parameter expansion string in double quotes does not |
1060 | cause the following four varieties of pattern characters to be quoted, | | 1189 | cause the following four varieties of pattern characters to be quoted, |
1061 | whereas quoting characters within the braces has this effect. | | 1190 | whereas quoting characters within the braces has this effect. |
1062 | .Bl -tag -width aaparameterwordaaaaa | | 1191 | .Bl -tag -width aaparameterwordaaaaa |
1063 | .It ${parameter%word} | | 1192 | .It ${parameter%word} |
1064 | Remove Smallest Suffix Pattern. | | 1193 | Remove Smallest Suffix Pattern. |
1065 | The word is expanded to produce a pattern. | | 1194 | The word is expanded to produce a pattern. |
1066 | The parameter expansion then results in parameter, with the | | 1195 | The parameter expansion then results in parameter, with the |
1067 | smallest portion of the suffix matched by the pattern deleted. | | 1196 | smallest portion of the suffix matched by the pattern deleted. |
1068 | .It ${parameter%%word} | | 1197 | .It ${parameter%%word} |
1069 | Remove Largest Suffix Pattern. | | 1198 | Remove Largest Suffix Pattern. |
1070 | The word is expanded to produce a pattern. | | 1199 | The word is expanded to produce a pattern. |
1071 | The parameter expansion then results in parameter, with the largest | | 1200 | The parameter expansion then results in parameter, with the largest |
1072 | portion of the suffix matched by the pattern deleted. | | 1201 | portion of the suffix matched by the pattern deleted. |
1073 | .It ${parameter#word} | | 1202 | .It ${parameter#word} |
1074 | Remove Smallest Prefix Pattern. | | 1203 | Remove Smallest Prefix Pattern. |
1075 | The word is expanded to produce a pattern. | | 1204 | The word is expanded to produce a pattern. |
1076 | The parameter expansion then results in parameter, with the | | 1205 | The parameter expansion then results in parameter, with the |
1077 | smallest portion of the prefix matched by the pattern deleted. | | 1206 | smallest portion of the prefix matched by the pattern deleted. |
1078 | .It ${parameter##word} | | 1207 | .It ${parameter##word} |
1079 | Remove Largest Prefix Pattern. | | 1208 | Remove Largest Prefix Pattern. |
1080 | The word is expanded to produce a pattern. | | 1209 | The word is expanded to produce a pattern. |
1081 | The parameter expansion then results in parameter, with the largest | | 1210 | The parameter expansion then results in parameter, with the largest |
1082 | portion of the prefix matched by the pattern deleted. | | 1211 | portion of the prefix matched by the pattern deleted. |
1083 | .El | | 1212 | .El |
1084 | .Ss Command Substitution | | 1213 | .Ss Command Substitution |
1085 | Command substitution allows the output of a command to be substituted in | | 1214 | Command substitution allows the output of a command to be substituted in |
1086 | place of the command name itself. | | 1215 | place of the command name itself. |
1087 | Command substitution occurs when the command is enclosed as follows: | | 1216 | Command substitution occurs when the command is enclosed as follows: |
1088 | .Pp | | 1217 | .Pp |
1089 | .Dl $(command) | | 1218 | .Dl $(command) |
1090 | .Pp | | 1219 | .Pp |
1091 | or | | 1220 | or |
1092 | .Po | | 1221 | .Po |
1093 | .Dq backquoted | | 1222 | .Dq backquoted |
1094 | version | | 1223 | version |
1095 | .Pc : | | 1224 | .Pc : |
1096 | .Pp | | 1225 | .Pp |
1097 | .Dl `command` | | 1226 | .Dl `command` |
1098 | .Pp | | 1227 | .Pp |
1099 | The shell expands the command substitution by executing command in a | | 1228 | The shell expands the command substitution by executing command in a |
1100 | subshell environment and replacing the command substitution with the | | 1229 | subshell environment and replacing the command substitution with the |
1101 | standard output of the command, removing sequences of one or more | | 1230 | standard output of the command, removing sequences of one or more |
1102 | .Ao newline Ac Ns s | | 1231 | .Ao newline Ac Ns s |
1103 | at the end of the substitution. | | 1232 | at the end of the substitution. |
1104 | (Embedded | | 1233 | (Embedded |
1105 | .Ao newline Ac Ns s | | 1234 | .Ao newline Ac Ns s |
1106 | before | | 1235 | before |
1107 | the end of the output are not removed; however, during field splitting, | | 1236 | the end of the output are not removed; however, during field splitting, |
1108 | they may be translated into | | 1237 | they may be translated into |
1109 | .Ao space Ac Ns s , | | 1238 | .Ao space Ac Ns s , |
1110 | depending on the value of | | 1239 | depending on the value of |
1111 | .Ev IFS | | 1240 | .Ev IFS |
1112 | and quoting that is in effect.) | | 1241 | and quoting that is in effect.) |
1113 | .Ss Arithmetic Expansion | | 1242 | .Ss Arithmetic Expansion |
1114 | Arithmetic expansion provides a mechanism for evaluating an arithmetic | | 1243 | Arithmetic expansion provides a mechanism for evaluating an arithmetic |
1115 | expression and substituting its value. | | 1244 | expression and substituting its value. |
1116 | The format for arithmetic expansion is as follows: | | 1245 | The format for arithmetic expansion is as follows: |
1117 | .Pp | | 1246 | .Pp |
1118 | .Dl $((expression)) | | 1247 | .Dl $((expression)) |
1119 | .Pp | | 1248 | .Pp |
1120 | The expression is treated as if it were in double quotes, except | | 1249 | The expression is treated as if it were in double quotes, except |
1121 | that a double quote inside the expression is not treated specially. | | 1250 | that a double quote inside the expression is not treated specially. |
1122 | The shell expands all tokens in the expression for parameter expansion, | | 1251 | The shell expands all tokens in the expression for parameter expansion, |
1123 | command substitution, and quote removal. | | 1252 | command substitution, and quote removal. |
1124 | .Pp | | 1253 | .Pp |
1125 | Next, the shell treats this as an arithmetic expression and | | 1254 | Next, the shell treats this as an arithmetic expression and |
1126 | substitutes the value of the expression. | | 1255 | substitutes the value of the expression. |
1127 | .Pp | | 1256 | .Pp |
1128 | Arithmetic expressions use a syntax similar to that | | 1257 | Arithmetic expressions use a syntax similar to that |
1129 | of the C language, and are evaluated using the | | 1258 | of the C language, and are evaluated using the |
1130 | .Ql intmax_t | | 1259 | .Ql intmax_t |
1131 | data type (this is an extension to | | 1260 | data type (this is an extension to |
1132 | .Tn POSIX , | | 1261 | .Tn POSIX , |
1133 | which requires only | | 1262 | which requires only |
1134 | .Ql long | | 1263 | .Ql long |
1135 | arithmetic). | | 1264 | arithmetic). |
1136 | Shell variables may be referenced by name inside an arithmetic | | 1265 | Shell variables may be referenced by name inside an arithmetic |
1137 | expression, without needing a | | 1266 | expression, without needing a |
1138 | .Dq \&$ | | 1267 | .Dq \&$ |
1139 | sign. | | 1268 | sign. |
1140 | .Ss White Space Splitting (Field Splitting) | | 1269 | .Ss White Space Splitting (Field Splitting) |
1141 | After parameter expansion, command substitution, and | | 1270 | After parameter expansion, command substitution, and |
1142 | arithmetic expansion the shell scans the results of | | 1271 | arithmetic expansion the shell scans the results of |
1143 | expansions and substitutions that did not occur in double quotes for | | 1272 | expansions and substitutions that did not occur in double quotes, |
1144 | field splitting and multiple fields can result. | | 1273 | and |
| | | 1274 | .Dq $@ |
| | | 1275 | even if it did, |
| | | 1276 | for field splitting and multiple fields can result. |
1145 | .Pp | | 1277 | .Pp |
1146 | The shell treats each character of the | | 1278 | The shell treats each character of the |
1147 | .Ev IFS | | 1279 | .Ev IFS |
1148 | as a delimiter and use the delimiters to split the results of parameter | | 1280 | as a delimiter and uses the delimiters to split the results of parameter |
1149 | expansion and command substitution into fields. | | 1281 | expansion and command substitution into fields. |
1150 | .Pp | | 1282 | .Pp |
1151 | Non-whitespace characters in | | 1283 | Non-whitespace characters in |
1152 | .Ev IFS | | 1284 | .Ev IFS |
1153 | are treated strictly as parameter terminators. | | 1285 | are treated strictly as parameter separators. |
1154 | So adjacent non-whitespace | | 1286 | So adjacent non-whitespace |
1155 | .Ev IFS | | 1287 | .Ev IFS |
1156 | characters will produce empty parameters. | | 1288 | characters will produce empty parameters. |
| | | 1289 | On the other hand, any sequence of whitespace |
| | | 1290 | characters that occur in |
| | | 1291 | .Ev IFS |
| | | 1292 | (known as |
| | | 1293 | .Ev IFS |
| | | 1294 | whitespace) |
| | | 1295 | can occur, leading and trailing |
| | | 1296 | .Ev IFS |
| | | 1297 | whitespace, and |
| | | 1298 | .Ev IFS |
| | | 1299 | whitespace surrounding a non whitespace |
| | | 1300 | .Ev IFS |
| | | 1301 | delimiter, is removed. |
| | | 1302 | Any sequence of |
| | | 1303 | .Ev IFS |
| | | 1304 | whitespace characters without a non-whitespace |
| | | 1305 | .Ev IFS |
| | | 1306 | delimiter acts as a field separator. |
1157 | .Pp | | 1307 | .Pp |
1158 | If | | 1308 | If |
1159 | .Ev IFS | | 1309 | .Ev IFS |
1160 | is unset it is assumed to contain space, tab, and newline. | | 1310 | is unset it is assumed to contain space, tab, and newline, |
| | | 1311 | all of which are |
| | | 1312 | .Ev IFS |
| | | 1313 | whitespace characters. |
| | | 1314 | If |
| | | 1315 | .Ev IFS |
| | | 1316 | is set to a null string, there are no delimiters, |
| | | 1317 | and no field splitting occurs. |
1161 | .Ss Pathname Expansion (File Name Generation) | | 1318 | .Ss Pathname Expansion (File Name Generation) |
1162 | Unless the | | 1319 | Unless the |
1163 | .Fl f | | 1320 | .Fl f |
1164 | flag is set, file name generation is performed after word splitting is | | 1321 | flag is set, file name generation is performed after word splitting is |
1165 | complete. | | 1322 | complete. |
1166 | Each word is viewed as a series of patterns, separated by slashes. | | 1323 | Each word is viewed as a series of patterns, separated by slashes. |
1167 | The process of expansion replaces the word with the names of all | | 1324 | The process of expansion replaces the word with the names of all |
1168 | existing files whose names can be formed by replacing each pattern with a | | 1325 | existing files whose names can be formed by replacing each pattern with a |
1169 | string that matches the specified pattern. | | 1326 | string that matches the specified pattern. |
1170 | There are two restrictions on | | 1327 | There are two restrictions on |
1171 | this: first, a pattern cannot match a string containing a slash, and | | 1328 | this: first, a pattern cannot match a string containing a slash, and |
1172 | second, a pattern cannot match a string starting with a period unless the | | 1329 | second, a pattern cannot match a string starting with a period unless the |
1173 | first character of the pattern is a period. | | 1330 | first character of the pattern is a period. |
1174 | The next section describes the | | 1331 | The next section describes the |
1175 | patterns used for both Pathname Expansion and the | | 1332 | patterns used for both Pathname Expansion and the |
1176 | .Ic case | | 1333 | .Ic case |
1177 | command. | | 1334 | command. |
1178 | .Ss Shell Patterns | | 1335 | .Ss Shell Patterns |
1179 | A pattern consists of normal characters, which match themselves, | | 1336 | A pattern consists of normal characters, which match themselves, |
1180 | and meta-characters. | | 1337 | and meta-characters. |
1181 | The meta-characters are | | 1338 | The meta-characters are |
1182 | .Dq \&! , | | 1339 | .Dq \&! , |
1183 | .Dq * , | | 1340 | .Dq * , |
1184 | .Dq \&? , | | 1341 | .Dq \&? , |
1185 | and | | 1342 | and |
1186 | .Dq \&[ . | | 1343 | .Dq \&[ . |
1187 | These characters lose their special meanings if they are quoted. | | 1344 | These characters lose their special meanings if they are quoted. |
1188 | When command or variable substitution is performed | | 1345 | When command or variable substitution is performed |
1189 | and the dollar sign or backquotes are not double-quoted, | | 1346 | and the dollar sign or backquotes are not double-quoted, |
1190 | the value of the variable or the output of | | 1347 | the value of the variable or the output of |
1191 | the command is scanned for these characters and they are turned into | | 1348 | the command is scanned for these characters and they are turned into |
1192 | meta-characters. | | 1349 | meta-characters. |
1193 | .Pp | | 1350 | .Pp |
1194 | An asterisk | | 1351 | An asterisk |
1195 | .Pq Dq * | | 1352 | .Pq Dq * |
1196 | matches any string of characters. | | 1353 | matches any string of characters. |
1197 | A question mark | | 1354 | A question mark |
1198 | .Pq Dq \&? | | 1355 | .Pq Dq \&? |
1199 | matches any single character. | | 1356 | matches any single character. |
1200 | A left bracket | | 1357 | A left bracket |
1201 | .Pq Dq \&[ | | 1358 | .Pq Dq \&[ |
1202 | introduces a character class. | | 1359 | introduces a character class. |
1203 | The end of the character class is indicated by a right bracket | | 1360 | The end of the character class is indicated by a right bracket |
1204 | .Pq Dq \&] ; | | 1361 | .Pq Dq \&] ; |
1205 | if this | | 1362 | if this |
1206 | .Dq \&] | | 1363 | .Dq \&] |
1207 | is missing then the | | 1364 | is missing then the |
1208 | .Dq \&[ | | 1365 | .Dq \&[ |
1209 | matches a | | 1366 | matches a |
1210 | .Dq \&[ | | 1367 | .Dq \&[ |
1211 | rather than introducing a character class. | | 1368 | rather than introducing a character class. |
1212 | A character class matches any of the characters between the square brackets. | | 1369 | A character class matches any of the characters between the square brackets. |
1213 | A named class of characters (see | | 1370 | A named class of characters (see |
1214 | .Xr wctype 3 ) | | 1371 | .Xr wctype 3 ) |
1215 | may be specified by surrounding the name with | | 1372 | may be specified by surrounding the name with |
1216 | .Pq Dq [: | | 1373 | .Pq Dq [: |
1217 | and | | 1374 | and |
1218 | .Pq Dq :] . | | 1375 | .Pq Dq :] . |
1219 | For example, | | 1376 | For example, |
1220 | .Pq Dq [[:alpha:]] | | 1377 | .Pq Dq [[:alpha:]] |
1221 | is a shell pattern that matches a single letter. | | 1378 | is a shell pattern that matches a single letter. |
1222 | A range of characters may be specified using a minus sign | | 1379 | A range of characters may be specified using a minus sign |
1223 | .Pq Dq - . | | 1380 | .Pq Dq \(mi . |
1224 | The character class may be complemented | | 1381 | The character class may be complemented |
1225 | by making an exclamation mark | | 1382 | by making an exclamation mark |
1226 | .Pq Dq \&! | | 1383 | .Pq Dq \&! |
1227 | the first character of the character class. | | 1384 | the first character of the character class. |
1228 | .Pp | | 1385 | .Pp |
1229 | To include a | | 1386 | To include a |
1230 | .Dq \&] | | 1387 | .Dq \&] |
1231 | in a character class, make it the first character listed (after the | | 1388 | in a character class, make it the first character listed (after the |
1232 | .Dq \&! , | | 1389 | .Dq \&! , |
1233 | if any). | | 1390 | if any). |
1234 | To include a | | 1391 | To include a |
1235 | .Dq - , | | 1392 | .Dq \(mi , |
1236 | make it the first or last character listed. | | 1393 | make it the first or last character listed. |
1237 | .Ss Built-ins | | 1394 | .Ss Built-ins |
1238 | This section lists the built-in commands which are built-in because they | | 1395 | This section lists the built-in commands which are built-in because they |
1239 | need to perform some operation that can't be performed by a separate | | 1396 | need to perform some operation that can't be performed by a separate |
1240 | process. | | 1397 | process. |
1241 | In addition to these, there are several other commands that may | | 1398 | In addition to these, there are several other commands that may |
1242 | be built in for efficiency (e.g. | | 1399 | be built in for efficiency (e.g. |
1243 | .Xr printf 1 , | | 1400 | .Xr printf 1 , |
1244 | .Xr echo 1 , | | 1401 | .Xr echo 1 , |
1245 | .Xr test 1 , | | 1402 | .Xr test 1 , |
1246 | etc). | | 1403 | etc). |
1247 | .Bl -tag -width 5n | | 1404 | .Bl -tag -width 5n |
1248 | .It : [ Ar arg ... ] | | 1405 | .It : [ Ar arg ... ] |
1249 | A null command that returns a 0 (true) exit value. | | 1406 | A null command that returns a 0 (true) exit value. |
1250 | Any arguments are ignored. | | 1407 | Any arguments or redirects are evaluated, then ignored. |
1251 | .It \&. file | | 1408 | .It \&. file |
1252 | The dot command reads and executes the commands from the specified | | 1409 | The dot command reads and executes the commands from the specified |
1253 | .Ar file | | 1410 | .Ar file |
1254 | in the current shell environment. | | 1411 | in the current shell environment. |
1255 | The file does not need to be executable and is looked up from the directories | | 1412 | The file does not need to be executable and is looked up from the directories |
1256 | listed in the | | 1413 | listed in the |
1257 | .Ev PATH | | 1414 | .Ev PATH |
1258 | variable if it does not contain a directory separator | | 1415 | variable if its name does not contain a directory separator |
1259 | .Pq Sq / . | | 1416 | .Pq Sq / . |
1260 | The return command can be used for a premature return from the sourced file. | | 1417 | The return command can be used for a premature return from the sourced file. |
1261 | .Pp | | 1418 | .Pp |
1262 | The POSIX standard is unclear on how loop control keywords (break | | 1419 | The POSIX standard has been unclear on how loop control keywords (break |
1263 | and continue) behave across a dot command boundary. | | 1420 | and continue) behave across a dot command boundary. |
1264 | This implementation allows them to control loops surrounding the dot command, | | 1421 | This implementation allows them to control loops surrounding the dot command, |
1265 | but obviously such behavior should not be relied on. | | 1422 | but obviously such behavior should not be relied on. |
| | | 1423 | It is now permitted by the standard, but not required. |
1266 | .It alias Op Ar name Ns Op Ar "=string ..." | | 1424 | .It alias Op Ar name Ns Op Ar "=string ..." |
1267 | If | | 1425 | If |
1268 | .Ar name=string | | 1426 | .Ar name=string |
1269 | is specified, the shell defines the alias | | 1427 | is specified, the shell defines the alias |
1270 | .Ar name | | 1428 | .Ar name |
1271 | with value | | 1429 | with value |
1272 | .Ar string . | | 1430 | .Ar string . |
1273 | If just | | 1431 | If just |
1274 | .Ar name | | 1432 | .Ar name |
1275 | is specified, the value of the alias | | 1433 | is specified, the value of the alias |
1276 | .Ar name | | 1434 | .Ar name |
1277 | is printed. | | 1435 | is printed. |
1278 | With no arguments, the | | 1436 | With no arguments, the |
1279 | .Ic alias | | 1437 | .Ic alias |
1280 | built-in prints the | | 1438 | built-in prints the |
1281 | names and values of all defined aliases (see | | 1439 | names and values of all defined aliases (see |
1282 | .Ic unalias ) . | | 1440 | .Ic unalias ) . |
1283 | .It bg [ Ar job ] ... | | 1441 | .It bg [ Ar job ] ... |
1284 | Continue the specified jobs (or the current job if no | | 1442 | Continue the specified jobs (or the current job if no |
1285 | jobs are given) in the background. | | 1443 | jobs are given) in the background. |
1286 | .It command Oo Fl p Oc Oo Fl v Oc Oo Fl V Oc Ar command Oo Ar arg ... Oc | | 1444 | .It command Oo Fl p Oc Oo Fl v Oc Oo Fl V Oc Ar command Oo Ar arg ... Oc |
1287 | Execute the specified command but ignore shell functions when searching | | 1445 | Execute the specified command but ignore shell functions when searching |
1288 | for it. | | 1446 | for it. |
1289 | (This is useful when you | | 1447 | (This is useful when you |
1290 | have a shell function with the same name as a built-in command.) | | 1448 | have a shell function with the same name as a command.) |
1291 | .Bl -tag -width 5n | | 1449 | .Bl -tag -width 5n |
1292 | .It Fl p | | 1450 | .It Fl p |
1293 | search for command using a | | 1451 | search for command using a |
1294 | .Ev PATH | | 1452 | .Ev PATH |
1295 | that guarantees to find all the standard utilities. | | 1453 | that guarantees to find all the standard utilities. |
1296 | .It Fl V | | 1454 | .It Fl V |
1297 | Do not execute the command but | | 1455 | Do not execute the command but |
1298 | search for the command and print the resolution of the | | 1456 | search for the command and print the resolution of the |
1299 | command search. | | 1457 | command search. |
1300 | This is the same as the | | 1458 | This is the same as the |
1301 | .Ic type | | 1459 | .Ic type |
1302 | built-in. | | 1460 | built-in. |
1303 | .It Fl v | | 1461 | .It Fl v |
1304 | Do not execute the command but | | 1462 | Do not execute the command but |
1305 | search for the command and print the absolute pathname | | 1463 | search for the command and print the absolute pathname |
1306 | of utilities, the name for built-ins or the expansion of aliases. | | 1464 | of utilities, the name for built-ins or the expansion of aliases. |
1307 | .El | | 1465 | .El |
1308 | .It cd Oo Fl P Oc Op Ar directory Op Ar replace | | 1466 | .It cd Oo Fl P Oc Op Ar directory Op Ar replace |
1309 | Switch to the specified directory (default | | 1467 | Switch to the specified directory (default |
1310 | .Ev $HOME ) . | | 1468 | .Ev $HOME ) . |
1311 | If | | 1469 | If |
1312 | .Ar replace | | 1470 | .Ar replace |
1313 | is specified, then the new directory name is generated by replacing | | 1471 | is specified, then the new directory name is generated by replacing |
1314 | the first occurrence of | | 1472 | the first occurrence of |
1315 | .Ar directory | | 1473 | .Ar directory |
1316 | in the current directory name with | | 1474 | in the current directory name with |
1317 | .Ar replace . | | 1475 | .Ar replace . |
1318 | If | | 1476 | If |
1319 | .Ar directory | | 1477 | .Ar directory |
1320 | is | | 1478 | is |
1321 | .Sq - , | | 1479 | .Sq - , |
1322 | then the current working directory is changed to the previous current | | 1480 | then the current working directory is changed to the previous current |
1323 | working directory as set in | | 1481 | working directory as set in |
1324 | .Ev OLDPWD . | | 1482 | .Ev OLDPWD . |
1325 | Otherwise if an entry for | | 1483 | Otherwise if an entry for |
1326 | .Ev CDPATH | | 1484 | .Ev CDPATH |
1327 | appears in the environment of the | | 1485 | appears in the environment of the |
1328 | .Ic cd | | 1486 | .Ic cd |
1329 | command or the shell variable | | 1487 | command or the shell variable |
1330 | .Ev CDPATH | | 1488 | .Ev CDPATH |
1331 | is set and the directory name does not begin with a slash, | | 1489 | is set and the directory name does not begin with a slash, |
1332 | or its first (or only) component isn't dot or dot dot, | | 1490 | or its first (or only) component isn't dot or dot dot, |
1333 | then the directories listed in | | 1491 | then the directories listed in |
1334 | .Ev CDPATH | | 1492 | .Ev CDPATH |
1335 | will be searched for the specified directory. | | 1493 | will be searched for the specified directory. |
1336 | The format of | | 1494 | The format of |
1337 | .Ev CDPATH | | 1495 | .Ev CDPATH |
1338 | is the same as that of | | 1496 | is the same as that of |
1339 | .Ev PATH . | | 1497 | .Ev PATH . |
1340 | .Pp | | 1498 | .Pp |
1341 | The | | 1499 | The |
1342 | .Fl P | | 1500 | .Fl P |
1343 | option instructs the shell to update | | 1501 | option instructs the shell to update |
1344 | .Ev PWD | | 1502 | .Ev PWD |
1345 | with the specified physical directory path and change to that directory. | | 1503 | with the specified physical directory path and change to that directory. |
1346 | This is the default. | | 1504 | This is the default. |
1347 | .Pp | | 1505 | .Pp |
1348 | When the directory changes, the variable | | 1506 | When the directory changes, the variable |
1349 | .Ev OLDPWD | | 1507 | .Ev OLDPWD |
1350 | is set to the working directory before the change. | | 1508 | is set to the working directory before the change. |
1351 | .Pp | | 1509 | .Pp |
1352 | Some shells also support a | | 1510 | Some shells also support a |
1353 | .Fl L | | 1511 | .Fl L |
1354 | option, which instructs the shell to update | | 1512 | option, which instructs the shell to update |
1355 | .Ev PWD | | 1513 | .Ev PWD |
1356 | with the logical path and to change the current directory | | 1514 | with the logical path and to change the current directory |
1357 | accordingly. | | 1515 | accordingly. |
1358 | This is not supported. | | 1516 | This is not supported. |
1359 | .Pp | | 1517 | .Pp |
1360 | In an interactive shell, the | | 1518 | In an interactive shell, the |
1361 | .Ic cd | | 1519 | .Ic cd |
1362 | command will print out the name of the | | 1520 | command will print out the name of the |
1363 | directory that it actually switched to if this is different from the name | | 1521 | directory that it actually switched to if this is different from the name |
1364 | that the user gave. | | 1522 | that the user gave. |
1365 | These may be different either because the | | 1523 | These may be different either because the |
1366 | .Ev CDPATH | | 1524 | .Ev CDPATH |
1367 | mechanism was used or because a symbolic link was crossed. | | 1525 | mechanism was used or because a symbolic link was crossed. |
1368 | .It eval Ar string ... | | 1526 | .It eval Ar string ... |
1369 | Concatenate all the arguments with spaces. | | 1527 | Concatenate all the arguments with spaces. |
1370 | Then re-parse and execute the command. | | 1528 | Then re-parse and execute the command. |
1371 | .It exec Op Ar command arg ... | | 1529 | .It exec Op Ar command arg ... |
1372 | Unless command is omitted, the shell process is replaced with the | | 1530 | Unless command is omitted, the shell process is replaced with the |
1373 | specified program (which must be a real program, not a shell built-in or | | 1531 | specified program (which must be a real program, not a shell built-in or |
1374 | function). | | 1532 | function). |
1375 | Any redirections on the | | 1533 | Any redirections on the |
1376 | .Ic exec | | 1534 | .Ic exec |
1377 | command are marked as permanent, so that they are not undone when the | | 1535 | command are marked as permanent, so that they are not undone when the |
1378 | .Ic exec | | 1536 | .Ic exec |
1379 | command finishes. | | 1537 | command finishes. |
1380 | File descriptors created via such redirections are marked close-on-exec | | 1538 | File descriptors created via such redirections are marked close-on-exec |
1381 | (see | | 1539 | (see |
1382 | .Xr open 2 | | 1540 | .Xr open 2 |
1383 | .Dv O_CLOEXEC | | 1541 | .Dv O_CLOEXEC |
1384 | or | | 1542 | or |
1385 | .Xr fcntl 2 | | 1543 | .Xr fcntl 2 |
1386 | .Dv F_SETFD / | | 1544 | .Dv F_SETFD / |
1387 | .Dv FD_CLOEXEC ) , | | 1545 | .Dv FD_CLOEXEC ) , |
1388 | unless the descriptors they point to refer to the standard input, | | 1546 | unless the descriptors they point to refer to the standard input, |
1389 | output, or error (file descriptors 0, 1, 2). | | 1547 | output, or error (file descriptors 0, 1, 2). |
1390 | Traditionally Bourne-like shells | | 1548 | Traditionally Bourne-like shells |
1391 | (except | | 1549 | (except |
1392 | .Xr ksh 1 ) , | | 1550 | .Xr ksh 1 ) , |
1393 | made those file descriptors available to exec'ed processes. | | 1551 | made those file descriptors available to exec'ed processes. |
1394 | .It exit Op Ar exitstatus | | 1552 | .It exit Op Ar exitstatus |
1395 | Terminate the shell process. | | 1553 | Terminate the shell process. |
1396 | If | | 1554 | If |
1397 | .Ar exitstatus | | 1555 | .Ar exitstatus |
1398 | is given it is used as the exit status of the shell; otherwise the | | 1556 | is given it is used as the exit status of the shell; otherwise the |
1399 | exit status of the preceding command is used. | | 1557 | exit status of the preceding command is used. |
1400 | .It export Ar name ... | | 1558 | .It export Oo Fl npx Oc Ar name ... |
1401 | .It export Fl p | | 1559 | .It export Fl p Oo Fl x Oc |
1402 | The specified names are exported so that they will appear in the | | 1560 | With no options, |
| | | 1561 | the specified names are exported so that they will appear in the |
1403 | environment of subsequent commands. | | 1562 | environment of subsequent commands. |
1404 | The only way to un-export a variable is to unset it. | | 1563 | With |
| | | 1564 | .Fl n |
| | | 1565 | the specified names are un-exported. |
| | | 1566 | Variables can also be un-exported using the unset builtin command. |
| | | 1567 | With |
| | | 1568 | .Fl x |
| | | 1569 | (exclude) the specified names are marked not to be exported, |
| | | 1570 | and any that had been exported, will be un-exported. |
| | | 1571 | Later attempts to export the variable will be refused. |
| | | 1572 | Note this does not prevent explicitly exporting a variable |
| | | 1573 | to a single command, script or function by preceding that |
| | | 1574 | command invocation by a variable assignment to that variable, |
| | | 1575 | provided the variable is not also readonly. |
| | | 1576 | That is |
| | | 1577 | .Dl export -x FOO ; # FOO will now not be exported by default |
| | | 1578 | .Dl FOO=some_value my_command |
| | | 1579 | still passes the value (FOO=some_value) to |
| | | 1580 | .Ic my_command |
| | | 1581 | through the environment. |
| | | 1582 | .Pp |
1405 | The shell allows the value of a variable to be set at the | | 1583 | The shell allows the value of a variable to be set at the |
1406 | same time it is exported by writing | | 1584 | same time it is exported by writing |
1407 | .Pp | | 1585 | .Pp |
1408 | .Dl export name=value | | 1586 | .Dl export name=value |
1409 | .Pp | | 1587 | .Pp |
1410 | With no arguments the export command lists the names of all exported variables. | | 1588 | With no arguments the export command lists the names of all exported variables, |
| | | 1589 | or if |
| | | 1590 | .Fl x |
| | | 1591 | was given, all variables marked not for export. |
1411 | With the | | 1592 | With the |
1412 | .Fl p | | 1593 | .Fl p |
1413 | option specified the output will be formatted suitably for non-interactive use. | | 1594 | option specified the output will be formatted suitably for non-interactive use. |
| | | 1595 | .Pp |
| | | 1596 | The |
| | | 1597 | .Ic export |
| | | 1598 | built-in exits with status 0, |
| | | 1599 | unless an invalid option, or option combination, is given, |
| | | 1600 | or unless an attempt is made to export a variable which has |
| | | 1601 | been marked as unavailable for export, |
| | | 1602 | in which cases it exits with status 1. |
| | | 1603 | .Pp |
| | | 1604 | Note that there is no restriction upon exporting, |
| | | 1605 | or un-exporting, readonly variables. |
| | | 1606 | The no-export flag can be reset by unsetting the variable |
| | | 1607 | and creating it again \(en provided it is not also readonly. |
1414 | .It fc Oo Fl e Ar editor Oc Oo Ar first Oo Ar last Oc Oc | | 1608 | .It fc Oo Fl e Ar editor Oc Oo Ar first Oo Ar last Oc Oc |
1415 | .It fc Fl l Oo Fl nr Oc Oo Ar first Oo Ar last Oc Oc | | 1609 | .It fc Fl l Oo Fl nr Oc Oo Ar first Oo Ar last Oc Oc |
1416 | .It fc Fl s Oo Ar old=new Oc Oo Ar first Oc | | 1610 | .It fc Fl s Oo Ar old=new Oc Oo Ar first Oc |
1417 | The | | 1611 | The |
1418 | .Ic fc | | 1612 | .Ic fc |
1419 | built-in lists, or edits and re-executes, commands previously entered | | 1613 | built-in lists, or edits and re-executes, commands previously entered |
1420 | to an interactive shell. | | 1614 | to an interactive shell. |
1421 | .Bl -tag -width 5n | | 1615 | .Bl -tag -width 5n |
1422 | .It Fl e No editor | | 1616 | .It Fl e No editor |
1423 | Use the editor named by editor to edit the commands. | | 1617 | Use the editor named by editor to edit the commands. |
1424 | The editor string is a command name, subject to search via the | | 1618 | The editor string is a command name, subject to search via the |
1425 | .Ev PATH | | 1619 | .Ev PATH |
1426 | variable. | | 1620 | variable. |
1427 | The value in the | | 1621 | The value in the |
1428 | .Ev FCEDIT | | 1622 | .Ev FCEDIT |
1429 | variable is used as a default when | | 1623 | variable is used as a default when |
1430 | .Fl e | | 1624 | .Fl e |
1431 | is not specified. | | 1625 | is not specified. |
1432 | If | | 1626 | If |
1433 | .Ev FCEDIT | | 1627 | .Ev FCEDIT |
1434 | is null or unset, the value of the | | 1628 | is null or unset, the value of the |
1435 | .Ev EDITOR | | 1629 | .Ev EDITOR |
1436 | variable is used. | | 1630 | variable is used. |
1437 | If | | 1631 | If |
1438 | .Ev EDITOR | | 1632 | .Ev EDITOR |
1439 | is null or unset, | | 1633 | is null or unset, |
1440 | .Xr ed 1 | | 1634 | .Xr ed 1 |
1441 | is used as the editor. | | 1635 | is used as the editor. |
1442 | .It Fl l No (ell) | | 1636 | .It Fl l No (ell) |
1443 | List the commands rather than invoking an editor on them. | | 1637 | List the commands rather than invoking an editor on them. |
1444 | The commands are written in the sequence indicated by | | 1638 | The commands are written in the sequence indicated by |
1445 | the first and last operands, as affected by | | 1639 | the first and last operands, as affected by |
1446 | .Fl r , | | 1640 | .Fl r , |
1447 | with each command preceded by the command number. | | 1641 | with each command preceded by the command number. |
1448 | .It Fl n | | 1642 | .It Fl n |
1449 | Suppress command numbers when listing with -l. | | 1643 | Suppress command numbers when listing with -l. |
1450 | .It Fl r | | 1644 | .It Fl r |
1451 | Reverse the order of the commands listed (with | | 1645 | Reverse the order of the commands listed (with |
1452 | .Fl l ) | | 1646 | .Fl l ) |
1453 | or edited (with neither | | 1647 | or edited (with neither |
1454 | .Fl l | | 1648 | .Fl l |
1455 | nor | | 1649 | nor |
1456 | .Fl s ) . | | 1650 | .Fl s ) . |
1457 | .It Fl s | | 1651 | .It Fl s |
1458 | Re-execute the command without invoking an editor. | | 1652 | Re-execute the command without invoking an editor. |
1459 | .It first | | 1653 | .It first |
1460 | .It last | | 1654 | .It last |
1461 | Select the commands to list or edit. | | 1655 | Select the commands to list or edit. |
1462 | The number of previous commands that | | 1656 | The number of previous commands that |
1463 | can be accessed are determined by the value of the | | 1657 | can be accessed are determined by the value of the |
1464 | .Ev HISTSIZE | | 1658 | .Ev HISTSIZE |
1465 | variable. | | 1659 | variable. |
1466 | The value of first or last or both are one of the following: | | 1660 | The value of first or last or both are one of the following: |
1467 | .Bl -tag -width 5n | | 1661 | .Bl -tag -width 5n |
1468 | .It [+]number | | 1662 | .It [+]number |
1469 | A positive number representing a command number; command numbers can be | | 1663 | A positive number representing a command number; command numbers can be |
1470 | displayed with the | | 1664 | displayed with the |
1471 | .Fl l | | 1665 | .Fl l |
1472 | option. | | 1666 | option. |
1473 | .It Fl number | | 1667 | .It Fl number |
1474 | A negative decimal number representing the command that was executed | | 1668 | A negative decimal number representing the command that was executed |
1475 | number of commands previously. | | 1669 | number of commands previously. |
1476 | For example, \-1 is the immediately previous command. | | 1670 | For example, \-1 is the immediately previous command. |
1477 | .El | | 1671 | .El |
1478 | .It string | | 1672 | .It string |
1479 | A string indicating the most recently entered command that begins with | | 1673 | A string indicating the most recently entered command that begins with |
1480 | that string. | | 1674 | that string. |
1481 | If the old=new operand is not also specified with | | 1675 | If the old=new operand is not also specified with |
1482 | .Fl s , | | 1676 | .Fl s , |
1483 | the string form of the first operand cannot contain an embedded equal sign. | | 1677 | the string form of the first operand cannot contain an embedded equal sign. |
1484 | .El | | 1678 | .El |
1485 | .Pp | | 1679 | .Pp |
1486 | The following environment variables affect the execution of fc: | | 1680 | The following environment variables affect the execution of fc: |
1487 | .Bl -tag -width HISTSIZE | | 1681 | .Bl -tag -width HISTSIZE |
1488 | .It Ev FCEDIT | | 1682 | .It Ev FCEDIT |
1489 | Name of the editor to use. | | 1683 | Name of the editor to use. |
1490 | .It Ev HISTSIZE | | 1684 | .It Ev HISTSIZE |
1491 | The number of previous commands that are accessible. | | 1685 | The number of previous commands that are accessible. |
1492 | .El | | 1686 | .El |
1493 | .It fg Op Ar job | | 1687 | .It fg Op Ar job |
1494 | Move the specified job or the current job to the foreground. | | 1688 | Move the specified job or the current job to the foreground. |
1495 | .It getopts Ar optstring var | | 1689 | .It getopts Ar optstring var |
1496 | The | | 1690 | The |
1497 | .Tn POSIX | | 1691 | .Tn POSIX |
1498 | .Ic getopts | | 1692 | .Ic getopts |
1499 | command, not to be confused with the | | 1693 | command, not to be confused with the |
1500 | .Em Bell Labs | | 1694 | .Em Bell Labs |
1501 | -derived | | 1695 | -derived |
1502 | .Xr getopt 1 . | | 1696 | .Xr getopt 1 . |
1503 | .Pp | | 1697 | .Pp |
1504 | The first argument should be a series of letters, each of which may be | | 1698 | The first argument should be a series of letters, each of which may be |
1505 | optionally followed by a colon to indicate that the option requires an | | 1699 | optionally followed by a colon to indicate that the option requires an |
1506 | argument. | | 1700 | argument. |
1507 | The variable specified is set to the parsed option. | | 1701 | The variable specified is set to the parsed option. |
1508 | .Pp | | 1702 | .Pp |
1509 | The | | 1703 | The |
1510 | .Ic getopts | | 1704 | .Ic getopts |
1511 | command deprecates the older | | 1705 | command deprecates the older |
1512 | .Xr getopt 1 | | 1706 | .Xr getopt 1 |
1513 | utility due to its handling of arguments containing whitespace. | | 1707 | utility due to its handling of arguments containing whitespace. |
1514 | .Pp | | 1708 | .Pp |
1515 | The | | 1709 | The |
1516 | .Ic getopts | | 1710 | .Ic getopts |
1517 | built-in may be used to obtain options and their arguments | | 1711 | built-in may be used to obtain options and their arguments |
1518 | from a list of parameters. | | 1712 | from a list of parameters. |
1519 | When invoked, | | 1713 | When invoked, |
1520 | .Ic getopts | | 1714 | .Ic getopts |
1521 | places the value of the next option from the option string in the list in | | 1715 | places the value of the next option from the option string in the list in |
1522 | the shell variable specified by | | 1716 | the shell variable specified by |
1523 | .Va var | | 1717 | .Va var |
1524 | and its index in the shell variable | | 1718 | and its index in the shell variable |
1525 | .Ev OPTIND . | | 1719 | .Ev OPTIND . |
1526 | When the shell is invoked, | | 1720 | When the shell is invoked, |
1527 | .Ev OPTIND | | 1721 | .Ev OPTIND |
1528 | is initialized to 1. | | 1722 | is initialized to 1. |
1529 | For each option that requires an argument, the | | 1723 | For each option that requires an argument, the |
1530 | .Ic getopts | | 1724 | .Ic getopts |
1531 | built-in will place it in the shell variable | | 1725 | built-in will place it in the shell variable |
1532 | .Ev OPTARG . | | 1726 | .Ev OPTARG . |
1533 | If an option is not allowed for in the | | 1727 | If an option is not allowed for in the |
1534 | .Va optstring , | | 1728 | .Va optstring , |
1535 | then | | 1729 | then |
1536 | .Ev OPTARG | | 1730 | .Ev OPTARG |
1537 | will be unset. | | 1731 | will be unset. |
1538 | .Pp | | 1732 | .Pp |
1539 | .Va optstring | | 1733 | .Va optstring |
1540 | is a string of recognized option letters (see | | 1734 | is a string of recognized option letters (see |
1541 | .Xr getopt 3 ) . | | 1735 | .Xr getopt 3 ) . |
1542 | If a letter is followed by a colon, the option is expected to have an | | 1736 | If a letter is followed by a colon, the option is expected to have an |
1543 | argument which may or may not be separated from it by whitespace. | | 1737 | argument which may or may not be separated from it by whitespace. |
1544 | If an option character is not found where expected, | | 1738 | If an option character is not found where expected, |
1545 | .Ic getopts | | 1739 | .Ic getopts |
1546 | will set the variable | | 1740 | will set the variable |
1547 | .Va var | | 1741 | .Va var |
1548 | to a | | 1742 | to a |
1549 | .Dq \&? ; | | 1743 | .Dq \&? ; |
1550 | .Ic getopts | | 1744 | .Ic getopts |
1551 | will then unset | | 1745 | will then unset |
1552 | .Ev OPTARG | | 1746 | .Ev OPTARG |
1553 | and write output to standard error. | | 1747 | and write output to standard error. |
1554 | By specifying a colon as the first character of | | 1748 | By specifying a colon as the first character of |
1555 | .Va optstring | | 1749 | .Va optstring |
1556 | all errors will be ignored. | | 1750 | all errors will be ignored. |
1557 | .Pp | | 1751 | .Pp |
1558 | A nonzero value is returned when the last option is reached. | | 1752 | A nonzero value is returned when the last option is reached. |
1559 | If there are no remaining arguments, | | 1753 | If there are no remaining arguments, |
1560 | .Ic getopts | | 1754 | .Ic getopts |
1561 | will set | | 1755 | will set |
1562 | .Va var | | 1756 | .Va var |
1563 | to the special option, | | 1757 | to the special option, |
1564 | .Dq -- , | | 1758 | .Dq -- , |
1565 | otherwise, it will set | | 1759 | otherwise, it will set |
1566 | .Va var | | 1760 | .Va var |
1567 | to | | 1761 | to |
1568 | .Dq \&? . | | 1762 | .Dq \&? . |
1569 | .Pp | | 1763 | .Pp |
1570 | The following code fragment shows how one might process the arguments | | 1764 | The following code fragment shows how one might process the arguments |
1571 | for a command that can take the options | | 1765 | for a command that can take the options |
1572 | .Op a | | 1766 | .Op a |
1573 | and | | 1767 | and |
1574 | .Op b , | | 1768 | .Op b , |
1575 | and the option | | 1769 | and the option |
1576 | .Op c , | | 1770 | .Op c , |
1577 | which requires an argument. | | 1771 | which requires an argument. |
1578 | .Bd -literal -offset indent | | 1772 | .Bd -literal -offset indent |
1579 | while getopts abc: f | | 1773 | while getopts abc: f |
1580 | do | | 1774 | do |
1581 | case $f in | | 1775 | case $f in |
1582 | a | b) flag=$f;; | | 1776 | a | b) flag=$f;; |
1583 | c) carg=$OPTARG;; | | 1777 | c) carg=$OPTARG;; |
1584 | \e?) echo $USAGE; exit 1;; | | 1778 | \e?) echo $USAGE; exit 1;; |
1585 | esac | | 1779 | esac |
1586 | done | | 1780 | done |
1587 | shift $(expr $OPTIND - 1) | | 1781 | shift $(expr $OPTIND - 1) |
1588 | .Ed | | 1782 | .Ed |
1589 | .Pp | | 1783 | .Pp |
1590 | This code will accept any of the following as equivalent: | | 1784 | This code will accept any of the following as equivalent: |
1591 | .Bd -literal -offset indent | | 1785 | .Bd -literal -offset indent |
1592 | cmd \-acarg file file | | 1786 | cmd \-acarg file file |
1593 | cmd \-a \-c arg file file | | 1787 | cmd \-a \-c arg file file |
1594 | cmd \-carg -a file file | | 1788 | cmd \-carg -a file file |
1595 | cmd \-a \-carg \-\- file file | | 1789 | cmd \-a \-carg \-\- file file |
1596 | .Ed | | 1790 | .Ed |
1597 | .It hash Fl rv Ar command ... | | 1791 | .It hash Fl rv Ar command ... |
1598 | The shell maintains a hash table which remembers the | | 1792 | The shell maintains a hash table which remembers the |
1599 | locations of commands. | | 1793 | locations of commands. |
1600 | With no arguments whatsoever, | | 1794 | With no arguments whatsoever, |
1601 | the | | 1795 | the |
1602 | .Ic hash | | 1796 | .Ic hash |
1603 | command prints out the contents of this table. | | 1797 | command prints out the contents of this table. |
1604 | Entries which have not been looked at since the last | | 1798 | Entries which have not been looked at since the last |
1605 | .Ic cd | | 1799 | .Ic cd |
1606 | command are marked with an asterisk; it is possible for these entries | | 1800 | command are marked with an asterisk; it is possible for these entries |
1607 | to be invalid. | | 1801 | to be invalid. |
1608 | .Pp | | 1802 | .Pp |
1609 | With arguments, the | | 1803 | With arguments, the |
1610 | .Ic hash | | 1804 | .Ic hash |
1611 | command removes the specified commands from the hash table (unless | | 1805 | command removes the specified commands from the hash table (unless |
1612 | they are functions) and then locates them. | | 1806 | they are functions) and then locates them. |
1613 | With the | | 1807 | With the |
1614 | .Fl v | | 1808 | .Fl v |
1615 | option, hash prints the locations of the commands as it finds them. | | 1809 | option, hash prints the locations of the commands as it finds them. |
1616 | The | | 1810 | The |
1617 | .Fl r | | 1811 | .Fl r |
1618 | option causes the hash command to delete all the entries in the hash table | | 1812 | option causes the hash command to delete all the entries in the hash table |
1619 | except for functions. | | 1813 | except for functions. |
1620 | .It inputrc Ar file | | 1814 | .It inputrc Ar file |
1621 | Read the | | 1815 | Read the |
1622 | .Va file | | 1816 | .Va file |
1623 | to set key bindings as defined by | | 1817 | to set key bindings as defined by |
1624 | .Xr editrc 5 . | | 1818 | .Xr editrc 5 . |
1625 | .It jobid Op Ar job | | 1819 | .It jobid Op Ar job |
1626 | Print the process id's of the processes in the job. | | 1820 | Print the process id's of the processes in the job. |
1627 | If the | | 1821 | If the |
1628 | .Ar job | | 1822 | .Ar job |
1629 | argument is omitted, the current job is used. | | 1823 | argument is omitted, the current job is used. |
1630 | .It jobs | | 1824 | .It jobs |
1631 | This command lists out all the background processes | | 1825 | This command lists out all the background processes |
1632 | which are children of the current shell process. | | 1826 | which are children of the current shell process. |
1633 | .It pwd Op Fl \&LP | | 1827 | .It pwd Op Fl \&LP |
1634 | Print the current directory. | | 1828 | Print the current directory. |
1635 | If | | 1829 | If |
1636 | .Fl L | | 1830 | .Fl L |
1637 | is specified the cached value (initially set from | | 1831 | is specified the cached value (initially set from |
1638 | .Ev PWD ) | | 1832 | .Ev PWD ) |
1639 | is checked to see if it refers to the current directory; if it does | | 1833 | is checked to see if it refers to the current directory; if it does |
1640 | the value is printed. | | 1834 | the value is printed. |
1641 | Otherwise the current directory name is found using | | 1835 | Otherwise the current directory name is found using |
1642 | .Xr getcwd 3 . | | 1836 | .Xr getcwd 3 . |
1643 | The environment variable | | 1837 | The environment variable |
1644 | .Ev PWD | | 1838 | .Ev PWD |
1645 | is set to the printed value. | | 1839 | is set to the printed value. |
1646 | .Pp | | 1840 | .Pp |
1647 | The default is | | 1841 | The default is |
1648 | .Ic pwd | | 1842 | .Ic pwd |
1649 | .Fl L , | | 1843 | .Fl L , |
1650 | but note that the built-in | | 1844 | but note that the built-in |
1651 | .Ic cd | | 1845 | .Ic cd |
1652 | command doesn't currently support the | | 1846 | command doesn't currently support the |
1653 | .Fl L | | 1847 | .Fl L |
1654 | option and will cache (almost) the absolute path. | | 1848 | option and will cache (almost) the absolute path. |
1655 | If | | 1849 | If |
1656 | .Ic cd | | 1850 | .Ic cd |
1657 | is changed, | | 1851 | is changed, |
1658 | .Ic pwd | | 1852 | .Ic pwd |
1659 | may be changed to default to | | 1853 | may be changed to default to |
1660 | .Ic pwd | | 1854 | .Ic pwd |
1661 | .Fl P . | | 1855 | .Fl P . |
1662 | .Pp | | 1856 | .Pp |
1663 | If the current directory is renamed and replaced by a symlink to the | | 1857 | If the current directory is renamed and replaced by a symlink to the |
1664 | same directory, or the initial | | 1858 | same directory, or the initial |
1665 | .Ev PWD | | 1859 | .Ev PWD |
1666 | value followed a symbolic link, then the cached value may not | | 1860 | value followed a symbolic link, then the cached value may not |
1667 | be the absolute path. | | 1861 | be the absolute path. |
1668 | .Pp | | 1862 | .Pp |
1669 | The built-in command may differ from the program of the same name because | | 1863 | The built-in command may differ from the program of the same name because |
1670 | the program will use | | 1864 | the program will use |
1671 | .Ev PWD | | 1865 | .Ev PWD |
1672 | and the built-in uses a separately cached value. | | 1866 | and the built-in uses a separately cached value. |
1673 | .It read Oo Fl p Ar prompt Oc Oo Fl r Oc Ar variable Oo Ar ... Oc | | 1867 | .It read Oo Fl p Ar prompt Oc Oo Fl r Oc Ar variable Oo Ar ... Oc |
1674 | The prompt is printed if the | | 1868 | The prompt is printed if the |
1675 | .Fl p | | 1869 | .Fl p |
1676 | option is specified and the standard input is a terminal. | | 1870 | option is specified and the standard input is a terminal. |
1677 | Then a line is read from the standard input. | | 1871 | Then a line is read from the standard input. |
1678 | The trailing newline is deleted from the | | 1872 | The trailing newline is deleted from the |
1679 | line and the line is split as described in the | | 1873 | line and the line is split as described in the |
1680 | .Sx Word Expansions | | 1874 | .Sx Word Expansions |
1681 | section above, and the pieces are assigned to the variables in order. | | 1875 | section above, and the pieces are assigned to the variables in order. |
1682 | If there are more pieces than variables, the remaining pieces | | 1876 | If there are more pieces than variables, the remaining pieces |
1683 | (along with the characters in | | 1877 | (along with the characters in |
1684 | .Ev IFS | | 1878 | .Ev IFS |
1685 | that separated them) are assigned to the last variable. | | 1879 | that separated them) are assigned to the last variable. |
1686 | If there are more variables than pieces, | | 1880 | If there are more variables than pieces, |
1687 | the remaining variables are assigned the null string. | | 1881 | the remaining variables are assigned the null string. |
1688 | The | | 1882 | The |
1689 | .Ic read | | 1883 | .Ic read |
1690 | built-in will indicate success unless EOF is encountered on input, in | | 1884 | built-in will indicate success unless EOF is encountered on input, in |
1691 | which case failure is returned. | | 1885 | which case failure is returned. |
1692 | .Pp | | 1886 | .Pp |
1693 | By default, unless the | | 1887 | By default, unless the |
1694 | .Fl r | | 1888 | .Fl r |
1695 | option is specified, the backslash | | 1889 | option is specified, the backslash |
1696 | .Dq \e | | 1890 | .Dq \e |
1697 | acts as an escape character, causing the following character to be treated | | 1891 | acts as an escape character, causing the following character to be treated |
1698 | literally. | | 1892 | literally. |
1699 | If a backslash is followed by a newline, the backslash and the | | 1893 | If a backslash is followed by a newline, the backslash and the |
1700 | newline will be deleted. | | 1894 | newline will be deleted. |
1701 | .It readonly Ar name ... | | 1895 | .It readonly Ar name ... |
1702 | .It readonly Fl p | | 1896 | .It readonly Fl p |
1703 | The specified names are marked as read only, so that they cannot be | | 1897 | The specified names are marked as read only, so that they cannot be |
1704 | subsequently modified or unset. | | 1898 | subsequently modified or unset. |
1705 | The shell allows the value of a variable | | 1899 | The shell allows the value of a variable |
1706 | to be set at the same time it is marked read only by writing | | 1900 | to be set at the same time it is marked read only by writing |
1707 | .Pp | | 1901 | .Pp |
1708 | .Dl readonly name=value | | 1902 | .Dl readonly name=value |
1709 | .Pp | | 1903 | .Pp |
1710 | With no arguments the readonly command lists the names of all read only | | 1904 | With no arguments the readonly command lists the names of all read only |
1711 | variables. | | 1905 | variables. |
1712 | With the | | 1906 | With the |
1713 | .Fl p | | 1907 | .Fl p |
1714 | option specified the output will be formatted suitably for non-interactive use. | | 1908 | option specified the output will be formatted suitably for non-interactive use. |
1715 | .Pp | | 1909 | .Pp |
1716 | .It return [ Ar n ] | | 1910 | .It return [ Ar n ] |
1717 | Stop executing the current function or a dot command with return value of | | 1911 | Stop executing the current function or a dot command with return value of |
1718 | .Ar n | | 1912 | .Ar n |
1719 | or the value of the last executed command, if not specified. | | 1913 | or the value of the last executed command, if not specified. |
1720 | For portability, | | 1914 | For portability, |
1721 | .Ar n | | 1915 | .Ar n |
1722 | should be in the range from 0 to 255. | | 1916 | should be in the range from 0 to 255. |
1723 | .Pp | | 1917 | .Pp |
1724 | The POSIX standard says that the results of | | 1918 | The POSIX standard says that the results of |
1725 | .Sq return | | 1919 | .Sq return |
1726 | outside a function or a dot command are unspecified. | | 1920 | outside a function or a dot command are unspecified. |
1727 | This implementation treats such a return as a no-op with a return value of 0 | | 1921 | This implementation treats such a return as a no-op with a return value of 0 |
1728 | (success, true). | | 1922 | (success, true). |
1729 | Use the exit command instead, if you want to return from a script or exit | | 1923 | Use the exit command instead, if you want to return from a script or exit |
1730 | your shell. | | 1924 | your shell. |
1731 | .It set Oo { Fl options | Cm +options | Cm \-- } Oc Ar arg ... | | 1925 | .It set Oo { Fl options | Cm +options | Cm \-- } Oc Ar arg ... |
1732 | The | | 1926 | The |
1733 | .Ic set | | 1927 | .Ic set |
1734 | command performs three different functions. | | 1928 | command performs three different functions. |
1735 | .Pp | | 1929 | .Pp |
1736 | With no arguments, it lists the values of all shell variables. | | 1930 | With no arguments, it lists the values of all shell variables. |
1737 | .Pp | | 1931 | .Pp |
1738 | If options are given, it sets the specified option | | 1932 | If options are given, it sets the specified option |
1739 | flags, or clears them as described in the | | 1933 | flags, or clears them as described in the |
1740 | .Sx Argument List Processing | | 1934 | .Sx Argument List Processing |
1741 | section. | | 1935 | section. |
1742 | .Pp | | 1936 | .Pp |
1743 | The third use of the set command is to set the values of the shell's | | 1937 | The third use of the set command is to set the values of the shell's |
1744 | positional parameters to the specified arguments. | | 1938 | positional parameters to the specified arguments. |
1745 | To change the positional | | 1939 | To change the positional |
1746 | parameters without changing any options, use | | 1940 | parameters without changing any options, use |
1747 | .Dq -- | | 1941 | .Dq -- |
1748 | as the first argument to set. | | 1942 | as the first argument to set. |
1749 | If no arguments are present, the set command | | 1943 | If no arguments are present, the set command |
1750 | will clear all the positional parameters (equivalent to executing | | 1944 | will clear all the positional parameters (equivalent to executing |
1751 | .Dq shift $# . ) | | 1945 | .Dq shift $# . ) |
1752 | .It setvar Ar variable Ar value | | 1946 | .It setvar Ar variable Ar value |
1753 | Assigns value to variable. | | 1947 | Assigns value to variable. |
1754 | (In general it is better to write | | 1948 | (In general it is better to write |
1755 | variable=value rather than using | | 1949 | variable=value rather than using |
1756 | .Ic setvar . | | 1950 | .Ic setvar . |
1757 | .Ic setvar | | 1951 | .Ic setvar |
1758 | is intended to be used in | | 1952 | is intended to be used in |
1759 | functions that assign values to variables whose names are passed as | | 1953 | functions that assign values to variables whose names are passed as |
1760 | parameters.) | | 1954 | parameters.) |
1761 | .It shift Op Ar n | | 1955 | .It shift Op Ar n |
1762 | Shift the positional parameters n times. | | 1956 | Shift the positional parameters n times. |
1763 | A | | 1957 | If n is omitted, 1 is assumed. |
| | | 1958 | Each |
1764 | .Ic shift | | 1959 | .Ic shift |
1765 | sets the value of | | 1960 | sets the value of |
1766 | .Va $1 | | 1961 | .Va $1 |
1767 | to the value of | | 1962 | to the previous value of |
1768 | .Va $2 , | | 1963 | .Va $2 , |
1769 | the value of | | 1964 | the value of |
1770 | .Va $2 | | 1965 | .Va $2 |
1771 | to the value of | | 1966 | to the previous value of |
1772 | .Va $3 , | | 1967 | .Va $3 , |
1773 | and so on, decreasing | | 1968 | and so on, decreasing |
1774 | the value of | | 1969 | the value of |
1775 | .Va $# | | 1970 | .Va $# |
1776 | by one. | | 1971 | by one. |
1777 | If there are zero positional parameters, | | 1972 | The shift count must be less than or equal to the number of |
1778 | .Ic shift | | 1973 | positional parameters ( |
1779 | does nothing. | | 1974 | .Dq $# ) |
| | | 1975 | before the shift. |
1780 | .It trap Oo Fl l Oc | | 1976 | .It trap Oo Fl l Oc |
1781 | .It trap Oo Ar action Oc Ar signal ... | | 1977 | .It trap Oo Ar action Oc Ar signal ... |
1782 | Cause the shell to parse and execute action when any of the specified | | 1978 | Cause the shell to parse and execute action when any of the specified |
1783 | signals are received. | | 1979 | signals are received. |
1784 | The signals are specified by signal number or as the name of the signal. | | 1980 | The signals are specified by signal number or as the name of the signal. |
1785 | If | | 1981 | If |
1786 | .Ar signal | | 1982 | .Ar signal |
1787 | is | | 1983 | is |
1788 | .Li 0 | | 1984 | .Li 0 |
1789 | or its equivalent, EXIT, | | 1985 | or its equivalent, EXIT, |
1790 | the action is executed when the shell exits. | | 1986 | the action is executed when the shell exits. |
1791 | .Ar action | | 1987 | .Ar action |
1792 | may be null, which cause the specified signals to be ignored. | | 1988 | may be null, which cause the specified signals to be ignored. |
1793 | With | | 1989 | With |
1794 | .Ar action | | 1990 | .Ar action |
1795 | omitted or set to | | 1991 | omitted or set to |
1796 | .Sq - | | 1992 | .Sq - |
1797 | the specified signals are set to their default action. | | 1993 | the specified signals are set to their default action. |
1798 | When the shell forks off a subshell, it resets trapped (but not ignored) | | 1994 | When the shell forks off a subshell, it resets trapped (but not ignored) |
1799 | signals to the default action. | | 1995 | signals to the default action. |
1800 | On non-interactive shells, the | | 1996 | On non-interactive shells, the |
1801 | .Ic trap | | 1997 | .Ic trap |
1802 | command has no effect on signals that were | | 1998 | command has no effect on signals that were |
1803 | ignored on entry to the shell. | | 1999 | ignored on entry to the shell. |
1804 | On interactive shells, the | | 2000 | On interactive shells, the |
1805 | .Ic trap | | 2001 | .Ic trap |
1806 | command will catch or reset signals ignored on entry. | | 2002 | command will catch or reset signals ignored on entry. |
1807 | Issuing | | 2003 | Issuing |
1808 | .Ic trap | | 2004 | .Ic trap |
1809 | with option | | 2005 | with option |
1810 | .Ar -l | | 2006 | .Ar -l |
1811 | will print a list of valid signal names. | | 2007 | will print a list of valid signal names. |
1812 | .Ic trap | | 2008 | .Ic trap |
1813 | without any arguments cause it to write a list of signals and their | | 2009 | without any arguments cause it to write a list of signals and their |
1814 | associated action to the standard output in a format that is suitable | | 2010 | associated action to the standard output in a format that is suitable |
1815 | as an input to the shell that achieves the same trapping results. | | 2011 | as an input to the shell that achieves the same trapping results. |
1816 | .Pp | | 2012 | .Pp |
1817 | Examples: | | 2013 | Examples: |
1818 | .Pp | | 2014 | .Pp |
1819 | .Dl trap | | 2015 | .Dl trap |
1820 | .Pp | | 2016 | .Pp |
1821 | List trapped signals and their corresponding action | | 2017 | List trapped signals and their corresponding action |
1822 | .Pp | | 2018 | .Pp |
1823 | .Dl trap -l | | 2019 | .Dl trap -l |
1824 | .Pp | | 2020 | .Pp |
1825 | Print a list of valid signals | | 2021 | Print a list of valid signals |
1826 | .Pp | | 2022 | .Pp |
1827 | .Dl trap '' INT QUIT tstp 30 | | 2023 | .Dl trap '' INT QUIT tstp 30 |
1828 | .Pp | | 2024 | .Pp |
1829 | Ignore signals INT QUIT TSTP USR1 | | 2025 | Ignore signals INT QUIT TSTP USR1 |
1830 | .Pp | | 2026 | .Pp |
1831 | .Dl trap date INT | | 2027 | .Dl trap date INT |
1832 | .Pp | | 2028 | .Pp |
1833 | Print date upon receiving signal INT | | 2029 | Run the |
| | | 2030 | .Dq date |
| | | 2031 | command (print the date) upon receiving signal INT |
1834 | .It type Op Ar name ... | | 2032 | .It type Op Ar name ... |
1835 | Interpret each name as a command and print the resolution of the command | | 2033 | Interpret each name as a command and print the resolution of the command |
1836 | search. | | 2034 | search. |
1837 | Possible resolutions are: | | 2035 | Possible resolutions are: |
1838 | shell keyword, alias, shell built-in, | | 2036 | shell keyword, alias, shell built-in, |
1839 | command, tracked alias and not found. | | 2037 | command, tracked alias and not found. |
1840 | For aliases the alias expansion is | | 2038 | For aliases the alias expansion is |
1841 | printed; for commands and tracked aliases the complete pathname of the | | 2039 | printed; for commands and tracked aliases the complete pathname of the |
1842 | command is printed. | | 2040 | command is printed. |
1843 | .It ulimit Oo Fl H \*(Ba Fl S Oc Oo Fl a \*(Ba Fl btfdscmlrpnv Oo Ar value Oc Oc | | 2041 | .It ulimit Oo Fl H \*(Ba Fl S Oc Oo Fl a \*(Ba Fl btfdscmlrpnv Oo Ar value Oc Oc |
1844 | Inquire about or set the hard or soft limits on processes or set new | | 2042 | Inquire about or set the hard or soft limits on processes or set new |
1845 | limits. | | 2043 | limits. |
1846 | The choice between hard limit (which no process is allowed to | | 2044 | The choice between hard limit (which no process is allowed to |
1847 | violate, and which may not be raised once it has been lowered) and soft | | 2045 | violate, and which may not be raised once it has been lowered) and soft |
1848 | limit (which causes processes to be signaled but not necessarily killed, | | 2046 | limit (which causes processes to be signaled but not necessarily killed, |
1849 | and which may be raised) is made with these flags: | | 2047 | and which may be raised) is made with these flags: |
1850 | .Bl -tag -width Fl | | 2048 | .Bl -tag -width Fl |
1851 | .It Fl H | | 2049 | .It Fl H |
1852 | set or inquire about hard limits | | 2050 | set or inquire about hard limits |
1853 | .It Fl S | | 2051 | .It Fl S |
1854 | set or inquire about soft limits. | | 2052 | set or inquire about soft limits. |
1855 | If neither | | 2053 | If neither |
1856 | .Fl H | | 2054 | .Fl H |
1857 | nor | | 2055 | nor |
1858 | .Fl S | | 2056 | .Fl S |
1859 | is specified, the soft limit is displayed or both limits are set. | | 2057 | is specified, the soft limit is displayed or both limits are set. |
1860 | If both are specified, the last one wins. | | 2058 | If both are specified, the last one wins. |
1861 | .El | | 2059 | .El |
1862 | .Pp | | 2060 | .Pp |
1863 | The limit to be interrogated or set, then, is chosen by specifying | | 2061 | The limit to be interrogated or set, then, is chosen by specifying |
1864 | any one of these flags: | | 2062 | any one of these flags: |
1865 | .Bl -tag -width Fl | | 2063 | .Bl -tag -width Fl |
1866 | .It Fl a | | 2064 | .It Fl a |
1867 | show all the current limits | | 2065 | show all the current limits |
1868 | .It Fl b | | 2066 | .It Fl b |
1869 | show or set the limit on the socket buffer size of a process (in bytes) | | 2067 | show or set the limit on the socket buffer size of a process (in bytes) |
1870 | .It Fl t | | 2068 | .It Fl t |
1871 | show or set the limit on CPU time (in seconds) | | 2069 | show or set the limit on CPU time (in seconds) |
1872 | .It Fl f | | 2070 | .It Fl f |
1873 | show or set the limit on the largest file that can be created | | 2071 | show or set the limit on the largest file that can be created |
1874 | (in 512-byte blocks) | | 2072 | (in 512-byte blocks) |
1875 | .It Fl d | | 2073 | .It Fl d |
1876 | show or set the limit on the data segment size of a process (in kilobytes) | | 2074 | show or set the limit on the data segment size of a process (in kilobytes) |
1877 | .It Fl s | | 2075 | .It Fl s |
1878 | show or set the limit on the stack size of a process (in kilobytes) | | 2076 | show or set the limit on the stack size of a process (in kilobytes) |
1879 | .It Fl c | | 2077 | .It Fl c |
1880 | show or set the limit on the largest core dump size that can be produced | | 2078 | show or set the limit on the largest core dump size that can be produced |
1881 | (in 512-byte blocks) | | 2079 | (in 512-byte blocks) |
1882 | .It Fl m | | 2080 | .It Fl m |
1883 | show or set the limit on the total physical memory that can be | | 2081 | show or set the limit on the total physical memory that can be |
1884 | in use by a process (in kilobytes) | | 2082 | in use by a process (in kilobytes) |
1885 | .It Fl l | | 2083 | .It Fl l |
1886 | show or set the limit on how much memory a process can lock with | | 2084 | show or set the limit on how much memory a process can lock with |
1887 | .Xr mlock 2 | | 2085 | .Xr mlock 2 |
1888 | (in kilobytes) | | 2086 | (in kilobytes) |
1889 | .It Fl r | | 2087 | .It Fl r |
1890 | show or set the limit on the number of threads this user can | | 2088 | show or set the limit on the number of threads this user can |
1891 | have at one time | | 2089 | have at one time |
1892 | .It Fl p | | 2090 | .It Fl p |
1893 | show or set the limit on the number of processes this user can | | 2091 | show or set the limit on the number of processes this user can |
1894 | have at one time | | 2092 | have at one time |
1895 | .It Fl n | | 2093 | .It Fl n |
1896 | show or set the limit on the number of files a process can have open at once | | 2094 | show or set the limit on the number of files a process can have open at once |
1897 | .It Fl v | | 2095 | .It Fl v |
1898 | show or set the limit on how large a process address space can be | | 2096 | show or set the limit on how large a process address space can be |
1899 | .El | | 2097 | .El |
1900 | .Pp | | 2098 | .Pp |
1901 | If none of these is specified, it is the limit on file size that is shown | | 2099 | If none of these is specified, it is the limit on file size that is shown |
1902 | or set. | | 2100 | or set. |
1903 | If value is specified, the limit is set to that number; otherwise | | 2101 | If value is specified, the limit is set to that number; otherwise |
1904 | the current limit is displayed. | | 2102 | the current limit is displayed. |
1905 | .Pp | | 2103 | .Pp |
1906 | Limits of an arbitrary process can be displayed or set using the | | 2104 | Limits of an arbitrary process can be displayed or set using the |
1907 | .Xr sysctl 8 | | 2105 | .Xr sysctl 8 |
1908 | utility. | | 2106 | utility. |
1909 | .Pp | | 2107 | .Pp |
1910 | .It umask Op Ar mask | | 2108 | .It umask Op Ar mask |
1911 | Set the value of umask (see | | 2109 | Set the value of umask (see |
1912 | .Xr umask 2 ) | | 2110 | .Xr umask 2 ) |
1913 | to the specified octal value. | | 2111 | to the specified octal value. |
1914 | If the argument is omitted, the umask value is printed. | | 2112 | If the argument is omitted, the umask value is printed. |
1915 | .It unalias Oo Fl a Oc Oo Ar name Oc | | 2113 | .It unalias Oo Fl a Oc Oo Ar name Oc |
1916 | If | | 2114 | If |
1917 | .Ar name | | 2115 | .Ar name |
1918 | is specified, the shell removes that alias. | | 2116 | is specified, the shell removes that alias. |
1919 | If | | 2117 | If |
1920 | .Fl a | | 2118 | .Fl a |
1921 | is specified, all aliases are removed. | | 2119 | is specified, all aliases are removed. |
1922 | .It unset Ar name ... | | 2120 | .It unset Oo Fl efv Oc Ar name ... |
1923 | The specified variables and functions are unset and unexported. | | 2121 | If |
1924 | If a given name corresponds to both a variable and a function, both | | 2122 | .Fl v |
1925 | the variable and the function are unset. | | 2123 | is specified, the specified variables are unset and unexported. |
| | | 2124 | Readonly variables cannot be unset. |
| | | 2125 | If |
| | | 2126 | .Fl f |
| | | 2127 | is specified, the specified functions are undefined. |
| | | 2128 | If |
| | | 2129 | .Fl e |
| | | 2130 | is given, the specified variables are unexported, but otherwise unchanged. |
| | | 2131 | .Pp |
| | | 2132 | If no flags are provided |
| | | 2133 | .Fl v |
| | | 2134 | is assumed. |
| | | 2135 | If |
| | | 2136 | .Fl f |
| | | 2137 | is given with one (or both) of |
| | | 2138 | .Fl v |
| | | 2139 | or |
| | | 2140 | .Fl e , |
| | | 2141 | then the named variables will be unset, or unexported, and functions |
| | | 2142 | of the same names will be undefined. |
| | | 2143 | It makes no sense to give both |
| | | 2144 | .Fl v |
| | | 2145 | and |
| | | 2146 | .Fl e |
| | | 2147 | as unsetting a variable unexports it as well. |
| | | 2148 | However doing so is not an error, the last specified is used. |
| | | 2149 | The exit status is 0, unless an attempt was made to unset |
| | | 2150 | a readonly variable, in which case the exit status is 1. |
| | | 2151 | It is not an error to unset (or undefine) a variable (or function) |
| | | 2152 | that is not currently set (or defined.) |
1926 | .It wait Op Ar job | | 2153 | .It wait Op Ar job |
1927 | Wait for the specified job to complete and return the exit status of the | | 2154 | Wait for the specified job to complete and return the exit status of the |
1928 | last process in the job. | | 2155 | last process in the job, or 127 if the job is not a current child of |
| | | 2156 | the shell. |
1929 | If the argument is omitted, wait for all jobs to | | 2157 | If the argument is omitted, wait for all jobs to |
1930 | complete and then return an exit status of zero. | | 2158 | complete and then return an exit status of zero. |
| | | 2159 | If the wait is interrupted by a signal, |
| | | 2160 | its exit status will be greater than 128. |
| | | 2161 | .Pp |
| | | 2162 | Once waited upon, by specific process number or job-id, |
| | | 2163 | or by a |
| | | 2164 | .Ic wait |
| | | 2165 | with no argumentss, |
| | | 2166 | knowledge of the child is removed from the system, |
| | | 2167 | and it cannot be waited upon again. |
1931 | .El | | 2168 | .El |
1932 | .Ss Command Line Editing | | 2169 | .Ss Command Line Editing |
1933 | When | | 2170 | When |
1934 | .Nm | | 2171 | .Nm |
1935 | is being used interactively from a terminal, the current command | | 2172 | is being used interactively from a terminal, the current command |
1936 | and the command history (see | | 2173 | and the command history (see |
1937 | .Ic fc | | 2174 | .Ic fc |
1938 | in the | | 2175 | in the |
1939 | .Sx Built-ins | | 2176 | .Sx Built-ins |
1940 | section) | | 2177 | section) |
1941 | can be edited using emacs-mode or vi-mode command-line editing. | | 2178 | can be edited using emacs-mode or vi-mode command-line editing. |
1942 | The command | | 2179 | The command |
1943 | .Ql set -o emacs | | 2180 | .Ql set -o emacs |
1944 | enables emacs-mode editing. | | 2181 | enables emacs-mode editing. |
1945 | The command | | 2182 | The command |
1946 | .Ql set -o vi | | 2183 | .Ql set -o vi |
1947 | enables vi-mode editing and places the current shell process into | | 2184 | enables vi-mode editing and places the current shell process into |
1948 | .Ar vi | | 2185 | .Ar vi |
1949 | insert mode. | | 2186 | insert mode. |
1950 | (See the | | 2187 | (See the |
1951 | .Sx Argument List Processing | | 2188 | .Sx Argument List Processing |
1952 | section above.) | | 2189 | section above.) |
1953 | .Pp | | 2190 | .Pp |
1954 | The | | 2191 | The |
1955 | .Ar vi | | 2192 | .Ar vi |
1956 | mode uses commands similar to a subset of those described in the | | 2193 | mode uses commands similar to a subset of those described in the |
1957 | .Xr vi 1 | | 2194 | .Xr vi 1 |
1958 | man page. | | 2195 | man page. |
1959 | With vi-mode | | 2196 | With vi-mode |
1960 | enabled, | | 2197 | enabled, |
1961 | .Nm sh | | 2198 | .Nm sh |
1962 | can be switched between insert mode and command mode. | | 2199 | can be switched between insert mode and command mode. |
1963 | It's similar to | | 2200 | It's similar to |
1964 | .Xr vi 1 : | | 2201 | .Xr vi 1 : |
1965 | pressing the | | 2202 | pressing the |
1966 | .Aq ESC | | 2203 | .Aq ESC |
1967 | key will throw you into command VI command mode. | | 2204 | key will throw you into command VI command mode. |
1968 | Pressing the | | 2205 | Pressing the |
1969 | .Aq return | | 2206 | .Aq return |
1970 | key while in command mode will pass the line to the shell. | | 2207 | key while in command mode will pass the line to the shell. |
1971 | .Pp | | 2208 | .Pp |
1972 | The | | 2209 | The |
1973 | .Ar emacs | | 2210 | .Ar emacs |
1974 | mode uses commands similar to a subset available in | | 2211 | mode uses commands similar to a subset available in |
1975 | the | | 2212 | the |
1976 | .Xr emacs 1 | | 2213 | .Xr emacs 1 |
1977 | editor. | | 2214 | editor. |
1978 | With emacs-mode enabled, special keys can be used to modify the text | | 2215 | With emacs-mode enabled, special keys can be used to modify the text |
1979 | in the buffer using the control key. | | 2216 | in the buffer using the control key. |
1980 | .Pp | | 2217 | .Pp |
1981 | .Nm | | 2218 | .Nm |
1982 | uses the | | 2219 | uses the |
1983 | .Xr editline 3 | | 2220 | .Xr editline 3 |
1984 | library. | | 2221 | library. |
1985 | .Sh ENVIRONMENT | | 2222 | .Sh ENVIRONMENT |
1986 | .Bl -tag -width MAILCHECK | | 2223 | .Bl -tag -width MAILCHECK |
| | | 2224 | .It Ev CDPATH |
| | | 2225 | The search path used with the |
| | | 2226 | .Ic cd |
| | | 2227 | built-in. |
| | | 2228 | .It Ev HISTSIZE |
| | | 2229 | The number of lines in the history buffer for the shell. |
1987 | .It Ev HOME | | 2230 | .It Ev HOME |
1988 | Set automatically by | | 2231 | Set automatically by |
1989 | .Xr login 1 | | 2232 | .Xr login 1 |
1990 | from the user's login directory in the password file | | 2233 | from the user's login directory in the password file |
1991 | .Pq Xr passwd 5 . | | 2234 | .Pq Xr passwd 5 . |
1992 | This environment variable also functions as the default argument for the | | 2235 | This environment variable also functions as the default argument for the |
1993 | .Ic cd | | 2236 | .Ic cd |
1994 | built-in. | | 2237 | built-in. |
1995 | .It Ev PATH | | 2238 | .It Ev IFS |
1996 | The default search path for executables. | | 2239 | Input Field Separators. |
| | | 2240 | This is normally set to |
| | | 2241 | .Aq space , |
| | | 2242 | .Aq tab , |
| | | 2243 | and |
| | | 2244 | .Aq newline . |
1997 | See the | | 2245 | See the |
1998 | .Sx Path Search | | 2246 | .Sx White Space Splitting |
1999 | section above. | | 2247 | section for more details. |
2000 | .It Ev CDPATH | | | |
2001 | The search path used with the | | | |
2002 | .Ic cd | | | |
2003 | built-in. | | | |
2004 | .It Ev LINENO | | | |
2005 | The current line number in the script or function. | | | |
2006 | .It Ev LANG | | 2248 | .It Ev LANG |
2007 | The string used to specify localization information that allows users | | 2249 | The string used to specify localization information that allows users |
2008 | to work with different culture-specific and language conventions. | | 2250 | to work with different culture-specific and language conventions. |
2009 | See | | 2251 | See |
2010 | .Xr nls 7 . | | 2252 | .Xr nls 7 . |
| | | 2253 | .It Ev LINENO |
| | | 2254 | The current line number in the script or function. |
2011 | .It Ev MAIL | | 2255 | .It Ev MAIL |
2012 | The name of a mail file, that will be checked for the arrival of new mail. | | 2256 | The name of a mail file, that will be checked for the arrival of new mail. |
2013 | Overridden by | | 2257 | Overridden by |
2014 | .Ev MAILPATH . | | 2258 | .Ev MAILPATH . |
2015 | .It Ev MAILCHECK | | 2259 | .It Ev MAILCHECK |
2016 | The frequency in seconds that the shell checks for the arrival of mail | | 2260 | The frequency in seconds that the shell checks for the arrival of mail |
2017 | in the files specified by the | | 2261 | in the files specified by the |
2018 | .Ev MAILPATH | | 2262 | .Ev MAILPATH |
2019 | or the | | 2263 | or the |
2020 | .Ev MAIL | | 2264 | .Ev MAIL |
2021 | file. | | 2265 | file. |
2022 | If set to 0, the check will occur at each prompt. | | 2266 | If set to 0, the check will occur at each prompt. |
2023 | .It Ev MAILPATH | | 2267 | .It Ev MAILPATH |
2024 | A colon | | 2268 | A colon |
2025 | .Dq \&: | | 2269 | .Dq \&: |
2026 | separated list of file names, for the shell to check for incoming mail. | | 2270 | separated list of file names, for the shell to check for incoming mail. |
2027 | This environment setting overrides the | | 2271 | This environment setting overrides the |
2028 | .Ev MAIL | | 2272 | .Ev MAIL |
2029 | setting. | | 2273 | setting. |
2030 | There is a maximum of 10 mailboxes that can be monitored at once. | | 2274 | There is a maximum of 10 mailboxes that can be monitored at once. |
| | | 2275 | .It Ev PATH |
| | | 2276 | The default search path for executables. |
| | | 2277 | See the |
| | | 2278 | .Sx Path Search |
| | | 2279 | section above. |
2031 | .It Ev PS1 | | 2280 | .It Ev PS1 |
2032 | The primary prompt string, which defaults to | | 2281 | The primary prompt string, which defaults to |
2033 | .Dq $ \ , | | 2282 | .Dq $ \ , |
2034 | unless you are the superuser, in which case it defaults to | | 2283 | unless you are the superuser, in which case it defaults to |
2035 | .Dq # \ . | | 2284 | .Dq # \ . |
2036 | .It Ev PS2 | | 2285 | .It Ev PS2 |
2037 | The secondary prompt string, which defaults to | | 2286 | The secondary prompt string, which defaults to |
2038 | .Dq \*[Gt] \ . | | 2287 | .Dq \*[Gt] \ . |
2039 | .It Ev PS4 | | 2288 | .It Ev PS4 |
2040 | Output before each line when execution trace (set -x) is enabled, | | 2289 | Output before each line when execution trace (set -x) is enabled, |
2041 | defaults to | | 2290 | defaults to |
2042 | .Dq + \ . | | 2291 | .Dq + \ . |
2043 | .It Ev IFS | | | |
2044 | Input Field Separators. | | | |
2045 | This is normally set to | | | |
2046 | .Aq space , | | | |
2047 | .Aq tab , | | | |
2048 | and | | | |
2049 | .Aq newline . | | | |
2050 | See the | | | |
2051 | .Sx White Space Splitting | | | |
2052 | section for more details. | | | |
2053 | .It Ev TERM | | 2292 | .It Ev TERM |
2054 | The default terminal setting for the shell. | | 2293 | The default terminal setting for the shell. |
2055 | This is inherited by | | 2294 | This is inherited by |
2056 | children of the shell, and is used in the history editing modes. | | 2295 | children of the shell, and is used in the history editing modes. |
2057 | .It Ev HISTSIZE | | 2296 | .\" This is explicitly last, not in sort order - please leave! |
2058 | The number of lines in the history buffer for the shell. | | 2297 | .It Ev NETBSD_SHELL |
| | | 2298 | Unlike the variables mentioned above, |
| | | 2299 | this variable is somewhat strange, |
| | | 2300 | in that it cannot be set, |
| | | 2301 | inherited from the environment, |
| | | 2302 | modified, or exported from the shell. |
| | | 2303 | If set, it indicates that the shell is the |
| | | 2304 | .Ic sh |
| | | 2305 | defined by this manual page, and gives its version information. |
| | | 2306 | It behaves like any other variable that has the read-only |
| | | 2307 | and un-exportable attributes set. |
2059 | .El | | 2308 | .El |
2060 | .Sh FILES | | 2309 | .Sh FILES |
2061 | .Bl -item | | 2310 | .Bl -item |
2062 | .It | | 2311 | .It |
2063 | .Pa $HOME/.profile | | 2312 | .Pa $HOME/.profile |
2064 | .It | | 2313 | .It |
2065 | .Pa /etc/profile | | 2314 | .Pa /etc/profile |
2066 | .El | | 2315 | .El |
2067 | .Sh EXIT STATUS | | 2316 | .Sh EXIT STATUS |
2068 | Errors that are detected by the shell, such as a syntax error, will cause the | | 2317 | Errors that are detected by the shell, such as a syntax error, will cause the |
2069 | shell to exit with a non-zero exit status. | | 2318 | shell to exit with a non-zero exit status. |
2070 | If the shell is not an | | 2319 | If the shell is not an |
2071 | interactive shell, the execution of the shell file will be aborted. | | 2320 | interactive shell, the execution of the shell file will be aborted. |
2072 | Otherwise | | 2321 | Otherwise |
2073 | the shell will return the exit status of the last command executed, or | | 2322 | the shell will return the exit status of the last command executed, or |
2074 | if the exit built-in is used with a numeric argument, it will return the | | 2323 | if the exit built-in is used with a numeric argument, it will return the |
2075 | argument. | | 2324 | argument. |
2076 | .Sh SEE ALSO | | 2325 | .Sh SEE ALSO |
2077 | .Xr csh 1 , | | 2326 | .Xr csh 1 , |
2078 | .Xr echo 1 , | | 2327 | .Xr echo 1 , |
2079 | .Xr getopt 1 , | | 2328 | .Xr getopt 1 , |
2080 | .Xr ksh 1 , | | 2329 | .Xr ksh 1 , |
2081 | .Xr login 1 , | | 2330 | .Xr login 1 , |
2082 | .Xr printf 1 , | | 2331 | .Xr printf 1 , |
2083 | .Xr test 1 , | | 2332 | .Xr test 1 , |
2084 | .Xr editline 3 , | | 2333 | .Xr editline 3 , |
2085 | .Xr getopt 3 , | | 2334 | .Xr getopt 3 , |
2086 | .\" .Xr profile 4 , | | 2335 | .\" .Xr profile 4 , |
2087 | .Xr editrc 5 , | | 2336 | .Xr editrc 5 , |
2088 | .Xr passwd 5 , | | 2337 | .Xr passwd 5 , |
2089 | .Xr environ 7 , | | 2338 | .Xr environ 7 , |
2090 | .Xr nls 7 , | | 2339 | .Xr nls 7 , |
2091 | .Xr sysctl 8 | | 2340 | .Xr sysctl 8 |
2092 | .Sh HISTORY | | 2341 | .Sh HISTORY |
2093 | A | | 2342 | A |
2094 | .Nm | | 2343 | .Nm |
2095 | command appeared in | | 2344 | command appeared in |
2096 | .At v1 . | | 2345 | .At v1 . |
2097 | It was, however, unmaintainable so we wrote this one. | | 2346 | It was, however, unmaintainable so we wrote this one. |
2098 | .Sh BUGS | | 2347 | .Sh BUGS |
2099 | Setuid shell scripts should be avoided at all costs, as they are a | | 2348 | Setuid shell scripts should be avoided at all costs, as they are a |
2100 | significant security risk. | | 2349 | significant security risk. |
2101 | .Pp | | 2350 | .Pp |
2102 | PS1, PS2, and PS4 should be subject to parameter expansion before | | 2351 | PS1, PS2, and PS4 should be subject to parameter expansion before |
2103 | being displayed. | | 2352 | being displayed. |
2104 | .Pp | | 2353 | .Pp |
2105 | The characters generated by filename completion should probably be quoted | | 2354 | The characters generated by filename completion should probably be quoted |
2106 | to ensure that the filename is still valid after the input line has been | | 2355 | to ensure that the filename is still valid after the input line has been |
2107 | processed. | | 2356 | processed. |
| | | 2357 | .Pp |
| | | 2358 | Many, many, more. |