Rev 2714 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
2714 | cejka | 1 | .\" $NetBSD: sh.1,v 1.40 2000/11/20 17:48:05 christos Exp $ |
2 | .\" Copyright (c) 1991, 1993 |
||
3 | .\" The Regents of the University of California. All rights reserved. |
||
4 | .\" |
||
5 | .\" This code is derived from software contributed to Berkeley by |
||
6 | .\" Kenneth Almquist. |
||
7 | .\" |
||
8 | .\" Redistribution and use in source and binary forms, with or without |
||
9 | .\" modification, are permitted provided that the following conditions |
||
10 | .\" are met: |
||
11 | .\" 1. Redistributions of source code must retain the above copyright |
||
12 | .\" notice, this list of conditions and the following disclaimer. |
||
13 | .\" 2. Redistributions in binary form must reproduce the above copyright |
||
14 | .\" notice, this list of conditions and the following disclaimer in the |
||
15 | .\" documentation and/or other materials provided with the distribution. |
||
16 | .\" 3. All advertising materials mentioning features or use of this software |
||
17 | .\" must display the following acknowledgement: |
||
18 | .\" This product includes software developed by the University of |
||
19 | .\" California, Berkeley and its contributors. |
||
20 | .\" 4. Neither the name of the University nor the names of its contributors |
||
21 | .\" may be used to endorse or promote products derived from this software |
||
22 | .\" without specific prior written permission. |
||
23 | .\" |
||
24 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
||
25 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
||
26 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
||
27 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
||
28 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
||
29 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
||
30 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
||
31 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
||
32 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
||
33 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
||
34 | .\" SUCH DAMAGE. |
||
35 | .\" |
||
36 | .\" @(#)sh.1 8.6 (Berkeley) 5/4/95 |
||
37 | .\" |
||
38 | .Dd January 9, 1999 |
||
39 | .Os |
||
40 | .Dt SH 1 |
||
41 | .Sh NAME |
||
42 | sh \- command interpreter (shell) |
||
43 | .Sh SYNOPSIS |
||
44 | .Nm sh |
||
45 | .Op Fl /+aCefnuvxIimqsVEbc |
||
46 | .Op Fl o Ar longname |
||
47 | .Bk -words |
||
48 | .Op Ar target ... |
||
49 | .Ek |
||
50 | .Sh DESCRIPTION |
||
51 | Sh is the standard command interpreter for the system. The current version |
||
52 | of |
||
53 | .Nm |
||
54 | is in the process of being changed to conform with the |
||
55 | .Tn POSIX |
||
56 | 1003.2 and 1003.2a specifications for the shell. This version has many |
||
57 | features which make it appear similar in some respects to the Korn shell, |
||
58 | but it is not a Korn shell clone (see |
||
59 | .Xr ksh 1 ) . |
||
60 | Only features designated by |
||
61 | .Tn POSIX , |
||
62 | plus a few Berkeley extensions, are being incorporated into this shell. |
||
63 | We expect |
||
64 | .Tn POSIX |
||
65 | conformance by the time 4.4 BSD is released. This man page is not intended |
||
66 | to be a tutorial or a complete specification of the shell. |
||
67 | .Ss Overview |
||
68 | The shell is a command that reads lines from either a file or the |
||
69 | terminal, interprets them, and generally executes other commands. It is |
||
70 | the program that is running when a user logs into the system (although a |
||
71 | user can select a different shell with the |
||
72 | .Xr chsh 1 |
||
73 | command). The shell implements a language that has flow control |
||
74 | constructs, a macro facility that provides a variety of features in |
||
75 | addition to data storage, along with built in history and line editing |
||
76 | capabilities. It incorporates many features to aid interactive use and |
||
77 | has the advantage that the interpretative language is common to both |
||
78 | interactive and non-interactive use (shell scripts). That is, commands |
||
79 | can be typed directly to the running shell or can be put into a file and |
||
80 | the file can be executed directly by the shell. |
||
81 | .Ss Invocation |
||
82 | If no args are present and if the standard input of the shell |
||
83 | is connected to a terminal (or if the |
||
84 | .Fl i |
||
85 | flag is set), |
||
86 | and the |
||
87 | .Fl c |
||
88 | option is not present, the shell is considered an interactive shell. An |
||
89 | interactive shell generally prompts before each command and handles |
||
90 | programming and command errors differently (as described below). When |
||
91 | first starting, the shell inspects argument 0, and if it begins with a |
||
92 | dash |
||
93 | .Sq - , |
||
94 | the shell is also considered |
||
95 | a login shell. This is normally done automatically by the system |
||
96 | when the user first logs in. A login shell first reads commands |
||
97 | from the files |
||
98 | .Pa /etc/profile |
||
99 | and |
||
100 | .Pa .profile |
||
101 | if they exist. |
||
102 | If the environment variable |
||
103 | .Ev ENV |
||
104 | is set on entry to a shell, or is set in the |
||
105 | .Pa .profile |
||
106 | of a login shell, the shell next reads |
||
107 | commands from the file named in |
||
108 | .Ev ENV . |
||
109 | Therefore, a user should place commands that are to be executed only at |
||
110 | login time in the |
||
111 | .Pa .profile |
||
112 | file, and commands that are executed for every shell inside the |
||
113 | .Ev ENV |
||
114 | file. To set the |
||
115 | .Ev ENV |
||
116 | variable to some file, place the following line in your |
||
117 | .Pa .profile |
||
118 | of your home directory |
||
119 | .Pp |
||
120 | .Dl ENV=$HOME/.shinit; export ENV |
||
121 | .Pp |
||
122 | substituting for |
||
123 | .Dq .shinit |
||
124 | any filename you wish. Since the |
||
125 | .Ev ENV |
||
126 | file is read for every invocation of the shell, including shell scripts |
||
127 | and non-interactive shells, the following paradigm is useful for |
||
128 | restricting commands in the |
||
129 | .Ev ENV |
||
130 | file to interactive invocations. Place commands within the |
||
131 | .Dq case |
||
132 | and |
||
133 | .Dq esac |
||
134 | below (these commands are described later): |
||
135 | .Pp |
||
136 | .Bl -item -compact -offset indent |
||
137 | .It |
||
138 | .Li case $- in *i*) |
||
139 | .Bl -item -compact -offset indent |
||
140 | .It |
||
141 | .Li # commands for interactive use only |
||
142 | .It |
||
143 | .Li ... |
||
144 | .El |
||
145 | .It |
||
146 | .Li esac |
||
147 | .El |
||
148 | .Pp |
||
149 | If command line arguments besides the options have been specified, then |
||
150 | the shell treats the first argument as the name of a file from which to |
||
151 | read commands (a shell script), and the remaining arguments are set as the |
||
152 | positional parameters of the shell ($1, $2, etc). Otherwise, the shell |
||
153 | reads commands from its standard input. |
||
154 | .Ss Argument List Processing |
||
155 | All of the single letter options have a corresponding name that can be |
||
156 | used as an argument to the |
||
157 | .Fl o |
||
158 | option. The set |
||
159 | .Fl o |
||
160 | name is provided next to the single letter option in |
||
161 | the description below. Specifying a dash |
||
162 | .Dq - |
||
163 | turns the option on, while using a plus |
||
164 | .Dq + |
||
165 | disables the option. |
||
166 | The following options can be set from the command line or |
||
167 | with the |
||
168 | .Xr set 1 |
||
169 | builtin (described later). |
||
170 | .Bl -tag -width aaaallexportfoo -offset indent |
||
171 | .It Fl a Em allexport |
||
172 | Export all variables assigned to. (UNIMPLEMENTED for 4.4alpha) |
||
173 | .It Fl c |
||
174 | Read commands from the command line. |
||
175 | No commands will be read from the standard input. |
||
176 | .It Fl C Em noclobber |
||
177 | Don't overwrite existing files with |
||
178 | .Dq > . |
||
179 | (UNIMPLEMENTED for 4.4alpha) |
||
180 | .It Fl e Em errexit |
||
181 | If not interactive, exit immediately if any untested command fails. |
||
182 | The exit status of a command is considered to be |
||
183 | explicitly tested if the command is used to control |
||
184 | an |
||
185 | .Ic if , |
||
186 | .Ic elif , |
||
187 | .Ic while , |
||
188 | or |
||
189 | .Ic until ; |
||
190 | or if the command is the left hand operand of an |
||
191 | .Dq && |
||
192 | or |
||
193 | .Dq || |
||
194 | operator. |
||
195 | .It Fl f Em noglob |
||
196 | Disable pathname expansion. |
||
197 | .It Fl n Em noexec |
||
198 | If not interactive, read commands but do not execute them. This is useful |
||
199 | for checking the syntax of shell scripts. |
||
200 | .It Fl u Em nounset |
||
201 | Write a message to standard error when attempting to expand a variable |
||
202 | that is not set, and if the shell is not interactive, exit immediately. |
||
203 | (UNIMPLEMENTED for 4.4alpha) |
||
204 | .It Fl v Em verbose |
||
205 | The shell writes its input to standard error as it is read. Useful for |
||
206 | debugging. |
||
207 | .It Fl x Em xtrace |
||
208 | Write each command to standard error (preceded |
||
209 | by a |
||
210 | .Sq +\ ) |
||
211 | before it is executed. Useful for debugging. |
||
212 | .It Fl q Em quietprofile |
||
213 | If the |
||
214 | .Fl v |
||
215 | or |
||
216 | .Fl x |
||
217 | options have been set, do not apply them when reading |
||
218 | initialization files, these being |
||
219 | .Pa /etc/profile , |
||
220 | .Pa .profile , |
||
221 | and the file specified by the |
||
222 | .Ev ENV |
||
223 | environment variable. |
||
224 | .It Fl I Em ignoreeof |
||
225 | Ignore EOF's from input when interactive. |
||
226 | .It Fl i Em interactive |
||
227 | Force the shell to behave interactively. |
||
228 | .It Fl m Em monitor |
||
229 | Turn on job control (set automatically when interactive). |
||
230 | .It Fl s Em stdin |
||
231 | Read commands from standard input (set automatically if no file arguments |
||
232 | are present). This option has no effect when set after the shell has |
||
233 | already started running (i.e. with |
||
234 | .Xr set 1 ) . |
||
235 | .It Fl V Em vi |
||
236 | Enable the built-in |
||
237 | .Xr vi 1 |
||
238 | command line editor (disables |
||
239 | .Fl E |
||
240 | if it has been set). |
||
241 | .It Fl E Em emacs |
||
242 | Enable the built-in |
||
243 | .Xr emacs 1 |
||
244 | command line editor (disables |
||
245 | .Fl V |
||
246 | if it has been set). |
||
247 | .It Fl b Em notify |
||
248 | Enable asynchronous notification of background job completion. |
||
249 | (UNIMPLEMENTED for 4.4alpha) |
||
250 | .El |
||
251 | .Ss Lexical Structure |
||
252 | The shell reads input in terms of lines from a file and breaks it up into |
||
253 | words at whitespace (blanks and tabs), and at certain sequences of |
||
254 | characters that are special to the shell called |
||
255 | .Dq operators . |
||
256 | There are two types of operators: control operators and redirection |
||
257 | operators (their meaning is discussed later). Following is a list of operators: |
||
258 | .Bl -ohang -offset indent |
||
259 | .It "Control operators:" |
||
260 | .Dl & && ( ) ; ;; | || <newline> |
||
261 | .It "Redirection operator:" |
||
262 | .Dl < > >| << >> <& >& <<- <> |
||
263 | .El |
||
264 | .Ss Quoting |
||
265 | Quoting is used to remove the special meaning of certain characters or |
||
266 | words to the shell, such as operators, whitespace, or keywords. There are |
||
267 | three types of quoting: matched single quotes, matched double quotes, and |
||
268 | backslash. |
||
269 | .Ss Backslash |
||
270 | A backslash preserves the literal meaning of the following |
||
271 | character, with the exception of |
||
272 | .Aq newline . |
||
273 | A backslash preceding a |
||
274 | .Aq newline |
||
275 | is treated as a line continuation. |
||
276 | .Ss Single Quotes |
||
277 | Enclosing characters in single quotes preserves the literal meaning of all |
||
278 | the characters (except single quotes, making it impossible to put |
||
279 | single-quotes in a single-quoted string). |
||
280 | .Ss Double Quotes |
||
281 | Enclosing characters within double quotes preserves the literal |
||
282 | meaning of all characters except dollarsign |
||
283 | .Pq $ , |
||
284 | backquote |
||
285 | .Pq ` , |
||
286 | and backslash |
||
287 | .Pq \e . |
||
288 | The backslash inside double quotes is historically weird, and serves to |
||
289 | quote only the following characters: |
||
290 | .Dl $ ` \*q \e <newline> . |
||
291 | Otherwise it remains literal. |
||
292 | .Ss Reserved Words |
||
293 | Reserved words are words that have special meaning to the |
||
294 | shell and are recognized at the beginning of a line and |
||
295 | after a control operator. The following are reserved words: |
||
296 | .Bl -column while while while while while -offset indent |
||
297 | .It ! Ta elif Ta fi Ta while Ta case |
||
298 | .It else Ta for Ta then Ta { Ta } |
||
299 | .It do Ta done Ta until Ta if Ta esac |
||
300 | .El |
||
301 | .Pp |
||
302 | Their meaning is discussed later. |
||
303 | .Ss Aliases |
||
304 | An alias is a name and corresponding value set using the |
||
305 | .Xr alias 1 |
||
306 | builtin command. Whenever a reserved word may occur (see above), |
||
307 | and after checking for reserved words, the shell |
||
308 | checks the word to see if it matches an alias. If it does, |
||
309 | it replaces it in the input stream with its value. For example, |
||
310 | if there is an alias called |
||
311 | .Dq lf |
||
312 | with the value |
||
313 | .Dq "ls -F" , |
||
314 | then the input: |
||
315 | .Pp |
||
316 | .Dl lf foobar <return> |
||
317 | .Pp |
||
318 | would become |
||
319 | .Pp |
||
320 | .Dl ls -F foobar <return> |
||
321 | .Pp |
||
322 | Aliases provide a convenient way for naive users to create shorthands for |
||
323 | commands without having to learn how to create functions with arguments. |
||
324 | They can also be used to create lexically obscure code. This use is |
||
325 | discouraged. |
||
326 | .Ss Commands |
||
327 | The shell interprets the words it reads according to a language, the |
||
328 | specification of which is outside the scope of this man page (refer to the |
||
329 | BNF in the |
||
330 | .Tn POSIX |
||
331 | 1003.2 document). Essentially though, a line is read and if the first |
||
332 | word of the line (or after a control operator) is not a reserved word, |
||
333 | then the shell has recognized a simple command. Otherwise, a complex |
||
334 | command or some other special construct may have been recognized. |
||
335 | .Ss Simple Commands |
||
336 | If a simple command has been recognized, the shell performs |
||
337 | the following actions: |
||
338 | .Bl -enum -offset indent |
||
339 | .It |
||
340 | Leading words of the form |
||
341 | .Dq name=value |
||
342 | are stripped off and assigned to the environment of the simple command. |
||
343 | Redirection operators and their arguments (as described below) are |
||
344 | stripped off and saved for processing. |
||
345 | .It |
||
346 | The remaining words are expanded as described in |
||
347 | the section called |
||
348 | .Dq Expansions , |
||
349 | and the first remaining word is considered the command name and the |
||
350 | command is located. The remaining words are considered the arguments of |
||
351 | the command. If no command name resulted, then the |
||
352 | .Dq name=value |
||
353 | variable assignments recognized in item 1 affect the current shell. |
||
354 | .It |
||
355 | Redirections are performed as described in the next section. |
||
356 | .El |
||
357 | .Ss Redirections |
||
358 | Redirections are used to change where a command reads its input or sends |
||
359 | its output. In general, redirections open, close, or duplicate an |
||
360 | existing reference to a file. The overall format used for redirection is: |
||
361 | .Pp |
||
362 | .Dl [n] Va redir-op Ar file |
||
363 | .Pp |
||
364 | where |
||
365 | .Va redir-op |
||
366 | is one of the redirection operators mentioned previously. Following is a |
||
367 | list of the possible redirections. The |
||
368 | .Bq n |
||
369 | is an optional number, as in |
||
370 | .Sq 3 |
||
371 | (not |
||
372 | .Sq Bq 3 , |
||
373 | that refers to a file descriptor. |
||
374 | .Bl -tag -width aaabsfiles -offset indent |
||
375 | .It [n] Ns > file |
||
376 | Redirect standard output (or n) to file. |
||
377 | .It [n] Ns >| file |
||
378 | Same, but override the |
||
379 | .Fl C |
||
380 | option. |
||
381 | .It [n] Ns >> file |
||
382 | Append standard output (or n) to file. |
||
383 | .It [n] Ns < file |
||
384 | Redirect standard input (or n) from file. |
||
385 | .It [n1] Ns <& Ns n2 |
||
386 | Duplicate standard input (or n1) from file descriptor n2. |
||
387 | .It [n] Ns <&- |
||
388 | Close standard input (or n). |
||
389 | .It [n1] Ns >& Ns n2 |
||
390 | Duplicate standard output (or n1) from n2. |
||
391 | .It [n] Ns >&- |
||
392 | Close standard output (or n). |
||
393 | .It [n] Ns <> file |
||
394 | Open file for reading and writing on standard input (or n). |
||
395 | .El |
||
396 | .Pp |
||
397 | The following redirection is often called a |
||
398 | .Dq here-document . |
||
399 | .Bl -item -offset indent |
||
400 | .It |
||
401 | .Li [n]<< delimiter |
||
402 | .Dl here-doc-text... |
||
403 | .Li delimiter |
||
404 | .El |
||
405 | .Pp |
||
406 | All the text on successive lines up to the delimiter is saved away and |
||
407 | made available to the command on standard input, or file descriptor n if |
||
408 | it is specified. If the delimiter as specified on the initial line is |
||
409 | quoted, then the here-doc-text is treated literally, otherwise the text is |
||
410 | subjected to parameter expansion, command substitution, and arithmetic |
||
411 | expansion (as described in the section on |
||
412 | .Dq Expansions ) . |
||
413 | If the operator is |
||
414 | .Dq <<- |
||
415 | instead of |
||
416 | .Dq << , |
||
417 | then leading tabs in the here-doc-text are stripped. |
||
418 | .Ss Search and Execution |
||
419 | There are three types of commands: shell functions, builtin commands, and |
||
420 | normal programs -- and the command is searched for (by name) in that |
||
421 | order. They each are executed in a different way. |
||
422 | .Pp |
||
423 | When a shell function is executed, all of the shell positional parameters |
||
424 | (except $0, which remains unchanged) are set to the arguments of the shell |
||
425 | function. The variables which are explicitly placed in the environment of |
||
426 | the command (by placing assignments to them before the function name) are |
||
427 | made local to the function and are set to the values given. Then the |
||
428 | command given in the function definition is executed. The positional |
||
429 | parameters are restored to their original values when the command |
||
430 | completes. This all occurs within the current shell. |
||
431 | .Pp |
||
432 | Shell builtins are executed internally to the shell, without spawning a |
||
433 | new process. |
||
434 | .Pp |
||
435 | Otherwise, if the command name doesn't match a function or builtin, the |
||
436 | command is searched for as a normal program in the filesystem (as |
||
437 | described in the next section). When a normal program is executed, the |
||
438 | shell runs the program, passing the arguments and the environment to the |
||
439 | program. If the program is not a normal executable file (i.e., if it does |
||
440 | not begin with the "magic number" whose |
||
441 | .Tn ASCII |
||
442 | representation is "#!", so |
||
443 | .Xr execve 2 |
||
444 | returns |
||
445 | .Er ENOEXEC |
||
446 | then) the shell will interpret the program in a subshell. The child shell |
||
447 | will reinitialize itself in this case, so that the effect will be as if a |
||
448 | new shell had been invoked to handle the ad-hoc shell script, except that |
||
449 | the location of hashed commands located in the parent shell will be |
||
450 | remembered by the child. |
||
451 | .Pp |
||
452 | Note that previous versions of this document and the source code itself |
||
453 | misleadingly and sporadically refer to a shell script without a magic |
||
454 | number as a "shell procedure". |
||
455 | .Ss Path Search |
||
456 | .Pp |
||
457 | When locating a command, the shell first looks to see if it has a shell |
||
458 | function by that name. Then it looks for a builtin command by that name. |
||
459 | If a builtin command is not found, one of two things happen: |
||
460 | .Bl -enum |
||
461 | .It |
||
462 | Command names containing a slash are simply executed without performing |
||
463 | any searches. |
||
464 | .It |
||
465 | The shell searches each entry in |
||
466 | .Ev PATH |
||
467 | in turn for the command. The value of the |
||
468 | .Ev PATH |
||
469 | variable should be a series of entries separated by colons. Each entry |
||
470 | consists of a directory name. The current directory may be indicated |
||
471 | implicitly by an empty directory name, or explicitly by a single period. |
||
472 | .El |
||
473 | .Ss Command Exit Status |
||
474 | Each command has an exit status that can influence the behavior |
||
475 | of other shell commands. The paradigm is that a command exits |
||
476 | with zero for normal or success, and non-zero for failure, |
||
477 | error, or a false indication. The man page for each command |
||
478 | should indicate the various exit codes and what they mean. |
||
479 | Additionally, the builtin commands return exit codes, as does |
||
480 | an executed shell function. |
||
481 | .Ss Complex Commands |
||
482 | Complex commands are combinations of simple commands with control |
||
483 | operators or reserved words, together creating a larger complex command. |
||
484 | More generally, a command is one of the following: |
||
485 | .Bl -bullet |
||
486 | .It |
||
487 | simple command |
||
488 | .It |
||
489 | pipeline |
||
490 | .It |
||
491 | list or compound-list |
||
492 | .It |
||
493 | compound command |
||
494 | .It |
||
495 | function definition |
||
496 | .El |
||
497 | .Pp |
||
498 | Unless otherwise stated, the exit status of a command is that of the last |
||
499 | simple command executed by the command. |
||
500 | .Ss Pipelines |
||
501 | .Pp |
||
502 | A pipeline is a sequence of one or more commands separated |
||
503 | by the control operator |. The standard output of all but |
||
504 | the last command is connected to the standard input |
||
505 | of the next command. The standard output of the last |
||
506 | command is inherited from the shell, as usual. |
||
507 | .Pp |
||
508 | The format for a pipeline is: |
||
509 | .Pp |
||
510 | .Dl [!] command1 [ | command2 ...] |
||
511 | .Pp |
||
512 | The standard output of command1 is connected to the standard input of |
||
513 | command2. The standard input, standard output, or both of a command is |
||
514 | considered to be assigned by the pipeline before any redirection specified |
||
515 | by redirection operators that are part of the command. |
||
516 | .Pp |
||
517 | If the pipeline is not in the background (discussed later), the shell |
||
518 | waits for all commands to complete. |
||
519 | .Pp |
||
520 | If the reserved word ! does not precede the pipeline, the exit status is |
||
521 | the exit status of the last command specified in the pipeline. |
||
522 | Otherwise, the exit status is the logical NOT of the exit status of the |
||
523 | last command. That is, if the last command returns zero, the exit status |
||
524 | is 1; if the last command returns greater than zero, the exit status is |
||
525 | zero. |
||
526 | .Pp |
||
527 | Because pipeline assignment of standard input or standard output or both |
||
528 | takes place before redirection, it can be modified by redirection. For |
||
529 | example: |
||
530 | .Pp |
||
531 | .Dl $ command1 2>&1 | command2 |
||
532 | .Pp |
||
533 | sends both the standard output and standard error of command1 |
||
534 | to the standard input of command2. |
||
535 | .Pp |
||
536 | A ; or <newline> terminator causes the preceding AND-OR-list (described |
||
537 | next) to be executed sequentially; a & causes asynchronous execution of |
||
538 | the preceding AND-OR-list. |
||
539 | .Pp |
||
540 | Note that unlike some other shells, each process in the pipeline is a |
||
541 | child of the invoking shell (unless it is a shell builtin, in which case |
||
542 | it executes in the current shell -- but any effect it has on the |
||
543 | environment is wiped). |
||
544 | .Ss Background Commands -- & |
||
545 | If a command is terminated by the control operator ampersand (&), the |
||
546 | shell executes the command asynchronously -- that is, the shell does not |
||
547 | wait for the command to finish before executing the next command. |
||
548 | .Pp |
||
549 | The format for running a command in background is: |
||
550 | .Pp |
||
551 | .Dl command1 & [command2 & ...] |
||
552 | .Pp |
||
553 | If the shell is not interactive, the standard input of an asynchronous |
||
554 | command is set to |
||
555 | .Pa /dev/null . |
||
556 | .Ss Lists -- Generally Speaking |
||
557 | A list is a sequence of zero or more commands separated by newlines, |
||
558 | semicolons, or ampersands, and optionally terminated by one of these three |
||
559 | characters. The commands in a list are executed in the order they are |
||
560 | written. If command is followed by an ampersand, the shell starts the |
||
561 | command and immediately proceed onto the next command; otherwise it waits |
||
562 | for the command to terminate before proceeding to the next one. |
||
563 | .Ss Short-Circuit List Operators |
||
564 | .Dq && |
||
565 | and |
||
566 | .Dq || |
||
567 | are AND-OR list operators. |
||
568 | .Dq && |
||
569 | executes the first command, and then executes the second command iff the |
||
570 | exit status of the first command is zero. |
||
571 | .Dq || |
||
572 | is similar, but executes the second command iff the exit status of the first |
||
573 | command is nonzero. |
||
574 | .Dq && |
||
575 | and |
||
576 | .Dq || |
||
577 | both have the same priority. |
||
578 | .Ss Flow-Control Constructs -- if, while, for, case |
||
579 | The syntax of the if command is |
||
580 | .Bd -literal -offset indent |
||
581 | if list |
||
582 | then list |
||
583 | [ elif list |
||
584 | then list ] ... |
||
585 | [ else list ] |
||
586 | fi |
||
587 | .Ed |
||
588 | .Pp |
||
589 | The syntax of the while command is |
||
590 | .Bd -literal -offset indent |
||
591 | while list |
||
592 | do list |
||
593 | done |
||
594 | .Ed |
||
595 | .Pp |
||
596 | The two lists are executed repeatedly while the exit status of the |
||
597 | first list is zero. The until command is similar, but has the word |
||
598 | until in place of while, which causes it to |
||
599 | repeat until the exit status of the first list is zero. |
||
600 | .Pp |
||
601 | The syntax of the for command is |
||
602 | .Bd -literal -offset indent |
||
603 | for variable in word... |
||
604 | do list |
||
605 | done |
||
606 | .Ed |
||
607 | .Pp |
||
608 | The words are expanded, and then the list is executed repeatedly with the |
||
609 | variable set to each word in turn. do and done may be replaced with |
||
610 | .Dq { |
||
611 | and |
||
612 | .Dq } . |
||
613 | .Pp |
||
614 | The syntax of the break and continue command is |
||
615 | .Bd -literal -offset indent |
||
616 | break [ num ] |
||
617 | continue [ num ] |
||
618 | .Ed |
||
619 | .Pp |
||
620 | Break terminates the num innermost for or while loops. |
||
621 | Continue continues with the next iteration of the innermost loop. |
||
622 | These are implemented as builtin commands. |
||
623 | .Pp |
||
624 | The syntax of the case command is |
||
625 | .Bd -literal -offset indent |
||
626 | case word in |
||
627 | pattern) list ;; |
||
628 | \&... |
||
629 | esac |
||
630 | .Ed |
||
631 | .Pp |
||
632 | The pattern can actually be one or more patterns (see Shell |
||
633 | Patterns described later), separated by |
||
634 | .Dq \*(Ba |
||
635 | characters. |
||
636 | .Ss Grouping Commands Together |
||
637 | Commands may be grouped by writing either |
||
638 | .Pp |
||
639 | .Dl (list) |
||
640 | .Pp |
||
641 | or |
||
642 | .Pp |
||
643 | .Dl { list; } |
||
644 | .Pp |
||
645 | The first of these executes the commands in a subshell. Builtin commands |
||
646 | grouped into a (list) will not affect the current shell. The second form |
||
647 | does not fork another shell so is slightly more efficient. Grouping |
||
648 | commands together this way allows you to redirect their output as though |
||
649 | they were one program: |
||
650 | .Pp |
||
651 | .Bd -literal -offset indent |
||
652 | { echo \*q hello \\c\*q ; echo \*q world" } > greeting |
||
653 | .Ed |
||
654 | .Pp |
||
655 | .Ss Functions |
||
656 | The syntax of a function definition is |
||
657 | .Pp |
||
658 | .Dl name ( ) command |
||
659 | .Pp |
||
660 | A function definition is an executable statement; when executed it |
||
661 | installs a function named name and returns an exit status of zero. The |
||
662 | command is normally a list enclosed between |
||
663 | .Dq { |
||
664 | and |
||
665 | .Dq } . |
||
666 | .Pp |
||
667 | Variables may be declared to be local to a function by using a local |
||
668 | command. This should appear as the first statement of a function, and the |
||
669 | syntax is |
||
670 | .Pp |
||
671 | .Dl local [ variable | - ] ... |
||
672 | .Pp |
||
673 | Local is implemented as a builtin command. |
||
674 | .Pp |
||
675 | When a variable is made local, it inherits the initial value and exported |
||
676 | and readonly flags from the variable with the same name in the surrounding |
||
677 | scope, if there is one. Otherwise, the variable is initially unset. The |
||
678 | shell uses dynamic scoping, so that if you make the variable x local to |
||
679 | function f, which then calls function g, references to the variable x made |
||
680 | inside g will refer to the variable x declared inside f, not to the global |
||
681 | variable named x. |
||
682 | .Pp |
||
683 | The only special parameter than can be made local is |
||
684 | .Dq - . |
||
685 | Making |
||
686 | .Dq - |
||
687 | local any shell options that are changed via the set command inside the |
||
688 | function to be restored to their original values when the function |
||
689 | returns. |
||
690 | .Pp |
||
691 | The syntax of the return command is |
||
692 | .Pp |
||
693 | .Dl return [ exitstatus ] |
||
694 | .Pp |
||
695 | It terminates the currently executing function. Return is |
||
696 | implemented as a builtin command. |
||
697 | .Ss Variables and Parameters |
||
698 | The shell maintains a set of parameters. A parameter denoted by a name is |
||
699 | called a variable. When starting up, the shell turns all the environment |
||
700 | variables into shell variables. New variables can be set using the form |
||
701 | .Pp |
||
702 | .Dl name=value |
||
703 | .Pp |
||
704 | Variables set by the user must have a name consisting solely of |
||
705 | alphabetics, numerics, and underscores - the first of which must not be |
||
706 | numeric. A parameter can also be denoted by a number or a special |
||
707 | character as explained below. |
||
708 | .Ss Positional Parameters |
||
709 | A positional parameter is a parameter denoted by a number (n > 0). The |
||
710 | shell sets these initially to the values of its command line arguments |
||
711 | that follow the name of the shell script. The |
||
712 | .Xr set 1 |
||
713 | builtin can also be used to set or reset them. |
||
714 | .Ss Special Parameters |
||
715 | A special parameter is a parameter denoted by one of the following special |
||
716 | characters. The value of the parameter is listed next to its character. |
||
717 | .Bl -tag -width thinhyphena |
||
718 | .It * |
||
719 | Expands to the positional parameters, starting from one. When the |
||
720 | expansion occurs within a double-quoted string it expands to a single |
||
721 | field with the value of each parameter separated by the first character of |
||
722 | the |
||
723 | .Ev IFS |
||
724 | variable, or by a <space> if |
||
725 | .Ev IFS |
||
726 | is unset. |
||
727 | .It @ |
||
728 | Expands to the positional parameters, starting from one. When |
||
729 | the expansion occurs within double-quotes, each positional |
||
730 | parameter expands as a separate argument. |
||
731 | If there are no positional parameters, the |
||
732 | expansion of @ generates zero arguments, even when @ is |
||
733 | double-quoted. What this basically means, for example, is |
||
734 | if $1 is |
||
735 | .Dq abc |
||
736 | and $2 is |
||
737 | .Dq def ghi , |
||
738 | then |
||
739 | .Qq $@ |
||
740 | expands to |
||
741 | the two arguments: |
||
742 | .Pp |
||
743 | .Sm off |
||
744 | .Dl \*q abc \*q \ \*q def\ ghi \*q |
||
745 | .Sm on |
||
746 | .It # |
||
747 | Expands to the number of positional parameters. |
||
748 | .It ? |
||
749 | Expands to the exit status of the most recent pipeline. |
||
750 | .It - (Hyphen.) |
||
751 | Expands to the current option flags (the single-letter |
||
752 | option names concatenated into a string) as specified on |
||
753 | invocation, by the set builtin command, or implicitly |
||
754 | by the shell. |
||
755 | .It $ |
||
756 | Expands to the process ID of the invoked shell. A subshell |
||
757 | retains the same value of $ as its parent. |
||
758 | .It ! |
||
759 | Expands to the process ID of the most recent background |
||
760 | command executed from the current shell. For a |
||
761 | pipeline, the process ID is that of the last command in the |
||
762 | pipeline. |
||
763 | .It 0 (Zero.) |
||
764 | Expands to the name of the shell or shell script. |
||
765 | .El |
||
766 | .Ss Word Expansions |
||
767 | This clause describes the various expansions that are performed on words. |
||
768 | Not all expansions are performed on every word, as explained later. |
||
769 | .Pp |
||
770 | Tilde expansions, parameter expansions, command substitutions, arithmetic |
||
771 | expansions, and quote removals that occur within a single word expand to a |
||
772 | single field. It is only field splitting or pathname expansion that can |
||
773 | create multiple fields from a single word. The single exception to this |
||
774 | rule is the expansion of the special parameter @ within double-quotes, as |
||
775 | was described above. |
||
776 | .Pp |
||
777 | The order of word expansion is: |
||
778 | .Bl -enum |
||
779 | .It |
||
780 | Tilde Expansion, Parameter Expansion, Command Substitution, |
||
781 | Arithmetic Expansion (these all occur at the same time). |
||
782 | .It |
||
783 | Field Splitting is performed on fields |
||
784 | generated by step (1) unless the |
||
785 | .Ev IFS |
||
786 | variable is null. |
||
787 | .It |
||
788 | Pathname Expansion (unless set |
||
789 | .Fl f |
||
790 | is in effect). |
||
791 | .It |
||
792 | Quote Removal. |
||
793 | .El |
||
794 | .Pp |
||
795 | The $ character is used to introduce parameter expansion, command |
||
796 | substitution, or arithmetic evaluation. |
||
797 | .Ss Tilde Expansion (substituting a user's home directory) |
||
798 | A word beginning with an unquoted tilde character (~) is |
||
799 | subjected to tilde expansion. All the characters up to |
||
800 | a slash (/) or the end of the word are treated as a username |
||
801 | and are replaced with the user's home directory. If the |
||
802 | username is missing (as in |
||
803 | .Pa ~/foobar ) , |
||
804 | the tilde is replaced with the value of the |
||
805 | .Va HOME |
||
806 | variable (the current user's home directory). |
||
807 | .Ss Parameter Expansion |
||
808 | The format for parameter expansion is as follows: |
||
809 | .Pp |
||
810 | .Dl ${expression} |
||
811 | .Pp |
||
812 | where expression consists of all characters until the matching |
||
813 | .Dq } . |
||
814 | Any |
||
815 | .Dq } |
||
816 | escaped by a backslash or within a quoted string, and characters in |
||
817 | embedded arithmetic expansions, command substitutions, and variable |
||
818 | expansions, are not examined in determining the matching |
||
819 | .Dq } . |
||
820 | .Pp |
||
821 | The simplest form for parameter expansion is: |
||
822 | .Pp |
||
823 | .Dl ${parameter} |
||
824 | .Pp |
||
825 | The value, if any, of parameter is substituted. |
||
826 | .Pp |
||
827 | The parameter name or symbol can be enclosed in braces, which are |
||
828 | optional except for positional parameters with more than one digit or |
||
829 | when parameter is followed by a character that could be interpreted as |
||
830 | part of the name. |
||
831 | If a parameter expansion occurs inside |
||
832 | double-quotes: |
||
833 | .Bl -enum |
||
834 | .It |
||
835 | Pathname expansion is not performed on the results of the |
||
836 | expansion. |
||
837 | .It |
||
838 | Field splitting is not performed on the results of the |
||
839 | expansion, with the exception of @. |
||
840 | .El |
||
841 | .Pp |
||
842 | In addition, a parameter expansion can be modified by using one of the |
||
843 | following formats. |
||
844 | .Bl -tag -width aaparameterwordaaaaa |
||
845 | .It ${parameter:-word} |
||
846 | Use Default Values. If parameter is unset or null, the expansion of word |
||
847 | is substituted; otherwise, the value of parameter is substituted. |
||
848 | .It ${parameter:=word} |
||
849 | Assign Default Values. If parameter is unset or null, the expansion of |
||
850 | word is assigned to parameter. In all cases, the final value of parameter |
||
851 | is substituted. Only variables, not positional parameters or special |
||
852 | parameters, can be assigned in this way. |
||
853 | .It ${parameter:?[word]} |
||
854 | Indicate Error if Null or Unset. If parameter is unset or null, the |
||
855 | expansion of word (or a message indicating it is unset if word is omitted) |
||
856 | is written to standard error and the shell exits with a nonzero exit |
||
857 | status. Otherwise, the value of parameter is substituted. An interactive |
||
858 | shell need not exit. |
||
859 | .It ${parameter:+word} |
||
860 | Use Alternative Value. If parameter is unset or null, null is |
||
861 | substituted; otherwise, the expansion of word is substituted. |
||
862 | .El |
||
863 | .Pp |
||
864 | In the parameter expansions shown previously, use of the colon in the |
||
865 | format results in a test for a parameter that is unset or null; omission |
||
866 | of the colon results in a test for a parameter that is only unset. |
||
867 | .Bl -tag -width aaparameterwordaaaaa |
||
868 | .It ${#parameter} |
||
869 | String Length. The length in characters of |
||
870 | the value of parameter. |
||
871 | .El |
||
872 | .Pp |
||
873 | The following four varieties of parameter expansion provide for substring |
||
874 | processing. In each case, pattern matching notation (see Shell Patterns), |
||
875 | rather than regular expression notation, is used to evaluate the patterns. |
||
876 | If parameter is * or @, the result of the expansion is unspecified. |
||
877 | Enclosing the full parameter expansion string in double-quotes does not |
||
878 | cause the following four varieties of pattern characters to be quoted, |
||
879 | whereas quoting characters within the braces has this effect. |
||
880 | .Bl -tag -width aaparameterwordaaaaa |
||
881 | .It ${parameter%word} |
||
882 | Remove Smallest Suffix Pattern. The word is expanded to produce a |
||
883 | pattern. The parameter expansion then results in parameter, with the |
||
884 | smallest portion of the suffix matched by the pattern deleted. |
||
885 | .It ${parameter%%word} |
||
886 | Remove Largest Suffix Pattern. The word is expanded to produce a pattern. |
||
887 | The parameter expansion then results in parameter, with the largest |
||
888 | portion of the suffix matched by the pattern deleted. |
||
889 | .It ${parameter#word} |
||
890 | Remove Smallest Prefix Pattern. The word is expanded to produce a |
||
891 | pattern. The parameter expansion then results in parameter, with the |
||
892 | smallest portion of the prefix matched by the pattern deleted. |
||
893 | .It ${parameter##word} |
||
894 | Remove Largest Prefix Pattern. The word is expanded to produce a pattern. |
||
895 | The parameter expansion then results in parameter, with the largest |
||
896 | portion of the prefix matched by the pattern deleted. |
||
897 | .El |
||
898 | .Ss Command Substitution |
||
899 | Command substitution allows the output of a command to be substituted in |
||
900 | place of the command name itself. Command substitution occurs when |
||
901 | the command is enclosed as follows: |
||
902 | .Pp |
||
903 | .Dl $(command) |
||
904 | .Pp |
||
905 | or |
||
906 | .Po |
||
907 | .Dq backquoted |
||
908 | version |
||
909 | .Pc : |
||
910 | .Pp |
||
911 | .Dl `command` |
||
912 | .Pp |
||
913 | The shell expands the command substitution by executing command in a |
||
914 | subshell environment and replacing the command substitution with the |
||
915 | standard output of the command, removing sequences of one or more |
||
916 | <newline>s at the end of the substitution. (Embedded <newline>s before |
||
917 | the end of the output are not removed; however, during field splitting, |
||
918 | they may be translated into <space>s, depending on the value of |
||
919 | .Ev IFS |
||
920 | and quoting that is in effect.) |
||
921 | .Ss Arithmetic Expansion |
||
922 | .Pp |
||
923 | Arithmetic expansion provides a mechanism for evaluating an arithmetic |
||
924 | expression and substituting its value. The format for arithmetic |
||
925 | expansion is as follows: |
||
926 | .Pp |
||
927 | .Dl $((expression)) |
||
928 | .Pp |
||
929 | The expression is treated as if it were in double-quotes, except |
||
930 | that a double-quote inside the expression is not treated specially. The |
||
931 | shell expands all tokens in the expression for parameter expansion, |
||
932 | command substitution, and quote removal. |
||
933 | .Pp |
||
934 | Next, the shell treats this as an arithmetic expression and |
||
935 | substitutes the value of the expression. |
||
936 | .Ss White Space Splitting (Field Splitting) |
||
937 | After parameter expansion, command substitution, and |
||
938 | arithmetic expansion the shell scans the results of |
||
939 | expansions and substitutions that did not occur in double-quotes for |
||
940 | field splitting and multiple fields can result. |
||
941 | .Pp |
||
942 | The shell treats each character of the |
||
943 | .Ev IFS |
||
944 | as a delimiter and use the delimiters to split the results of parameter |
||
945 | expansion and command substitution into fields. |
||
946 | .Ss Pathname Expansion (File Name Generation) |
||
947 | Unless the |
||
948 | .Fl f |
||
949 | flag is set, file name generation is performed after word splitting is |
||
950 | complete. Each word is viewed as a series of patterns, separated by |
||
951 | slashes. The process of expansion replaces the word with the names of all |
||
952 | existing files whose names can be formed by replacing each pattern with a |
||
953 | string that matches the specified pattern. There are two restrictions on |
||
954 | this: first, a pattern cannot match a string containing a slash, and |
||
955 | second, a pattern cannot match a string starting with a period unless the |
||
956 | first character of the pattern is a period. The next section describes the |
||
957 | patterns used for both Pathname Expansion and the |
||
958 | .Xr case 1 |
||
959 | command. |
||
960 | .Ss Shell Patterns |
||
961 | A pattern consists of normal characters, which match themselves, |
||
962 | and meta-characters. The meta-characters are |
||
963 | .Dq ! , |
||
964 | .Dq * , |
||
965 | .Dq ? , |
||
966 | and |
||
967 | .Dq [ . |
||
968 | These characters lose their special meanings if they are quoted. When |
||
969 | command or variable substitution is performed and the dollar sign or back |
||
970 | quotes are not double quoted, the value of the variable or the output of |
||
971 | the command is scanned for these characters and they are turned into |
||
972 | meta-characters. |
||
973 | .Pp |
||
974 | An asterisk |
||
975 | .Pq Dq * |
||
976 | matches any string of characters. A question mark matches any single |
||
977 | character. A left bracket |
||
978 | .Pq Dq \&[ |
||
979 | introduces a character class. The end of |
||
980 | the character class is indicated by a |
||
981 | .Pq Dq \&] ; |
||
982 | if the |
||
983 | .Dq \&] |
||
984 | is missing then the |
||
985 | .Dq \&[ |
||
986 | matches a |
||
987 | .Dq \&[ |
||
988 | rather than introducing a character class. A character class matches any |
||
989 | of the characters between the square brackets. A range of characters may |
||
990 | be specified using a minus sign. The character class may be complemented |
||
991 | by making an exclamation point the first character of the character class. |
||
992 | .Pp |
||
993 | To include a |
||
994 | .Dq \&] |
||
995 | in a character class, make it the first character listed (after the |
||
996 | .Dq \&! , |
||
997 | if any). To include a minus sign, make it the first or last character listed |
||
998 | .Ss Builtins |
||
999 | .Pp |
||
1000 | This section lists the builtin commands which are builtin because they |
||
1001 | need to perform some operation that can't be performed by a separate |
||
1002 | process. In addition to these, there are several other commands that may |
||
1003 | be builtin for efficiency (e.g. |
||
1004 | .Xr printf 1 , |
||
1005 | .Xr echo 1 , |
||
1006 | .Xr test 1 , |
||
1007 | etc). |
||
1008 | .Bl -tag -width 5n |
||
1009 | .It : |
||
1010 | A null command that returns a 0 (true) exit value. |
||
1011 | .It \&. file |
||
1012 | The commands in the specified file are read and executed by the shell. |
||
1013 | .It alias Op Ar name Ns Op Ar "=string ..." |
||
1014 | If |
||
1015 | .Ar name=string |
||
1016 | is specified, the shell defines the alias |
||
1017 | .Ar name |
||
1018 | with value |
||
1019 | .Ar string . |
||
1020 | If just |
||
1021 | .Ar name |
||
1022 | is specified, the value of the alias |
||
1023 | .Ar name |
||
1024 | is printed. With no arguments, the |
||
1025 | .Ic alias |
||
1026 | builtin prints the |
||
1027 | names and values of all defined aliases (see |
||
1028 | .Ic unalias ) . |
||
1029 | .It bg [ Ar job ] ... |
||
1030 | Continue the specified jobs (or the current job if no |
||
1031 | jobs are given) in the background. |
||
1032 | .It command Ar command Ar arg... |
||
1033 | Execute the specified builtin command. (This is useful when you |
||
1034 | have a shell function with the same name as a builtin command.) |
||
1035 | .It cd Op Ar directory |
||
1036 | Switch to the specified directory (default |
||
1037 | .Ev $HOME ) . |
||
1038 | If an entry for |
||
1039 | .Ev CDPATH |
||
1040 | appears in the environment of the |
||
1041 | .Ic cd |
||
1042 | command or the shell variable |
||
1043 | .Ev CDPATH |
||
1044 | is set and the directory name does not begin with a slash, then the |
||
1045 | directories listed in |
||
1046 | .Ev CDPATH |
||
1047 | will be searched for the specified directory. The format of |
||
1048 | .Ev CDPATH |
||
1049 | is the same as that of |
||
1050 | .Ev PATH . |
||
1051 | In an interactive shell, the |
||
1052 | .Ic cd |
||
1053 | command will print out the name of the |
||
1054 | directory that it actually switched to if this is different from the name |
||
1055 | that the user gave. These may be different either because the |
||
1056 | .Ev CDPATH |
||
1057 | mechanism was used or because a symbolic link was crossed. |
||
1058 | .It eval Ar string... |
||
1059 | Concatenate all the arguments with spaces. Then re-parse and execute |
||
1060 | the command. |
||
1061 | .It exec Op Ar command arg... |
||
1062 | Unless command is omitted, the shell process is replaced with the |
||
1063 | specified program (which must be a real program, not a shell builtin or |
||
1064 | function). Any redirections on the |
||
1065 | .Ic exec |
||
1066 | command are marked as permanent, so that they are not undone when the |
||
1067 | .Ic exec |
||
1068 | command finishes. |
||
1069 | .It exit Op Ar exitstatus |
||
1070 | Terminate the shell process. If |
||
1071 | .Ar exitstatus |
||
1072 | is given it is used as the exit status of the shell; otherwise the |
||
1073 | exit status of the preceding command is used. |
||
1074 | .It export Ar name... |
||
1075 | .It export Fl p |
||
1076 | The specified names are exported so that they will appear in the |
||
1077 | environment of subsequent commands. The only way to un-export a variable |
||
1078 | is to unset it. The shell allows the value of a variable to be set at the |
||
1079 | same time it is exported by writing |
||
1080 | .Pp |
||
1081 | .Dl export name=value |
||
1082 | .Pp |
||
1083 | With no arguments the export command lists the names of all exported variables. |
||
1084 | With the |
||
1085 | .Fl p |
||
1086 | option specified the output will be formatted suitably for non-interactive use. |
||
1087 | .It Xo fc Op Fl e Ar editor |
||
1088 | .Op Ar first Op Ar last |
||
1089 | .Xc |
||
1090 | .It Xo fc Fl l |
||
1091 | .Op Fl nr |
||
1092 | .Op Ar first Op Ar last |
||
1093 | .Xc |
||
1094 | .It Xo fc Fl s Op Ar old=new |
||
1095 | .Op Ar first |
||
1096 | .Xc |
||
1097 | The |
||
1098 | .Ic fc |
||
1099 | builtin lists, or edits and re-executes, commands previously entered |
||
1100 | to an interactive shell. |
||
1101 | .Bl -tag -width 5n |
||
1102 | .It Fl e No editor |
||
1103 | Use the editor named by editor to edit the commands. The |
||
1104 | editor string is a command name, subject to search via the |
||
1105 | .Ev PATH |
||
1106 | variable. The value in the |
||
1107 | .Ev FCEDIT |
||
1108 | variable is used as a default when |
||
1109 | .Fl e |
||
1110 | is not specified. If |
||
1111 | .Ev FCEDIT |
||
1112 | is null or unset, the value of the |
||
1113 | .Ev EDITOR |
||
1114 | variable is used. If |
||
1115 | .Ev EDITOR |
||
1116 | is null or unset, |
||
1117 | .Xr ed 1 |
||
1118 | is used as the editor. |
||
1119 | .It Fl l No (ell) |
||
1120 | List the commands rather than invoking an editor on them. The commands |
||
1121 | are written in the sequence indicated by the first and last operands, as |
||
1122 | affected by |
||
1123 | .Fl r , |
||
1124 | with each command preceded by the command number. |
||
1125 | .It Fl n |
||
1126 | Suppress command numbers when listing with -l. |
||
1127 | .It Fl r |
||
1128 | Reverse the order of the commands listed (with |
||
1129 | .Fl l ) |
||
1130 | or edited (with neither |
||
1131 | .Fl l |
||
1132 | nor |
||
1133 | .Fl s ) . |
||
1134 | .It Fl s |
||
1135 | Re-execute the command without invoking an editor. |
||
1136 | .It first |
||
1137 | .It last |
||
1138 | Select the commands to list or edit. The number of previous commands that |
||
1139 | can be accessed are determined by the value of the |
||
1140 | .Ev HISTSIZE |
||
1141 | variable. The value of first or last or both are one of the following: |
||
1142 | .Bl -tag -width 5n |
||
1143 | .It [+]number |
||
1144 | A positive number representing a command number; command numbers can be |
||
1145 | displayed with the |
||
1146 | .Fl l |
||
1147 | option. |
||
1148 | .It Fl number |
||
1149 | A negative decimal number representing the command that was executed |
||
1150 | number of commands previously. For example, -1 is the immediately |
||
1151 | previous command. |
||
1152 | .El |
||
1153 | .It string |
||
1154 | A string indicating the most recently entered command that begins with |
||
1155 | that string. If the old=new operand is not also specified with |
||
1156 | .Fl s , |
||
1157 | the string form of the first operand cannot contain an embedded equal sign. |
||
1158 | .El |
||
1159 | .Pp |
||
1160 | The following environment variables affect the execution of fc: |
||
1161 | .Bl -tag -width HISTSIZE |
||
1162 | .It Ev FCEDIT |
||
1163 | Name of the editor to use. |
||
1164 | .It Ev HISTSIZE |
||
1165 | The number of previous commands that are accessible. |
||
1166 | .El |
||
1167 | .It fg Op Ar job |
||
1168 | Move the specified job or the current job to the foreground. |
||
1169 | .It getopts Ar optstring var |
||
1170 | The |
||
1171 | .Tn POSIX |
||
1172 | .Ic getopts |
||
1173 | command, not to be confused with the |
||
1174 | .Em Bell Labs |
||
1175 | -derived |
||
1176 | .Xr getopt 1 . |
||
1177 | .Pp |
||
1178 | The first argument should be a series of letters, each of which may be |
||
1179 | optionally followed by a colon to indicate that the option requires an |
||
1180 | argument. The variable specified is set to the parsed option. |
||
1181 | .Pp |
||
1182 | The |
||
1183 | .Ic getopts |
||
1184 | command deprecates the older |
||
1185 | .Xr getopt 1 |
||
1186 | utility due to its handling of arguments containing whitespace. |
||
1187 | .Pp |
||
1188 | The |
||
1189 | .Ic getopts |
||
1190 | builtin may be used to obtain options and their arguments |
||
1191 | from a list of parameters. When invoked, |
||
1192 | .Ic getopts |
||
1193 | places the value of the next option from the option string in the list in |
||
1194 | the shell variable specified by |
||
1195 | .Va var |
||
1196 | and it's index in the shell variable |
||
1197 | .Ev OPTIND . |
||
1198 | When the shell is invoked, |
||
1199 | .Ev OPTIND |
||
1200 | is initialized to 1. For each option that requires an argument, the |
||
1201 | .Ic getopts |
||
1202 | builtin will place it in the shell variable |
||
1203 | .Ev OPTARG . |
||
1204 | If an option is not allowed for in the |
||
1205 | .Va optstring , |
||
1206 | then |
||
1207 | .Ev OPTARG |
||
1208 | will be unset. |
||
1209 | .Pp |
||
1210 | .Va optstring |
||
1211 | is a string of recognized option letters (see |
||
1212 | .Xr getopt 3 ) . |
||
1213 | If a letter is followed by a colon, the option is expected to have an |
||
1214 | argument which may or may not be separated from it by white space. If an |
||
1215 | option character is not found where expected, |
||
1216 | .Ic getopts |
||
1217 | will set the variable |
||
1218 | .Va var |
||
1219 | to a |
||
1220 | .Dq ? ; |
||
1221 | .Ic getopts |
||
1222 | will then unset |
||
1223 | .Ev OPTARG |
||
1224 | and write output to standard error. By specifying a colon as the |
||
1225 | first character of |
||
1226 | .Va optstring |
||
1227 | all errors will be ignored. |
||
1228 | .Pp |
||
1229 | A nonzero value is returned when the last option is reached. |
||
1230 | If there are no remaining arguments, |
||
1231 | .Ic getopts |
||
1232 | will set |
||
1233 | .Va var |
||
1234 | to the special option, |
||
1235 | .Dq -- , |
||
1236 | otherwise, it will set |
||
1237 | .Va var |
||
1238 | to |
||
1239 | .Dq ? . |
||
1240 | .Pp |
||
1241 | The following code fragment shows how one might process the arguments |
||
1242 | for a command that can take the options |
||
1243 | .Op a |
||
1244 | and |
||
1245 | .Op b , |
||
1246 | and the option |
||
1247 | .Op c , |
||
1248 | which requires an argument. |
||
1249 | .Pp |
||
1250 | .Bd -literal -offset indent |
||
1251 | while getopts abc: f |
||
1252 | do |
||
1253 | case $f in |
||
1254 | a | b) flag=$f;; |
||
1255 | c) carg=$OPTARG;; |
||
1256 | \\?) echo $USAGE; exit 1;; |
||
1257 | esac |
||
1258 | done |
||
1259 | shift `expr $OPTIND - 1` |
||
1260 | .Ed |
||
1261 | .Pp |
||
1262 | This code will accept any of the following as equivalent: |
||
1263 | .Pp |
||
1264 | .Bd -literal -offset indent |
||
1265 | cmd \-acarg file file |
||
1266 | cmd \-a \-c arg file file |
||
1267 | cmd \-carg -a file file |
||
1268 | cmd \-a \-carg \-\- file file |
||
1269 | .Ed |
||
1270 | .It hash Fl rv Ar command... |
||
1271 | The shell maintains a hash table which remembers the |
||
1272 | locations of commands. With no arguments whatsoever, |
||
1273 | the |
||
1274 | .Ic hash |
||
1275 | command prints out the contents of this table. Entries which have not |
||
1276 | been looked at since the last |
||
1277 | .Ic cd |
||
1278 | command are marked with an asterisk; it is possible for these entries |
||
1279 | to be invalid. |
||
1280 | .Pp |
||
1281 | With arguments, the |
||
1282 | .Ic hash |
||
1283 | command removes the specified commands from the hash table (unless |
||
1284 | they are functions) and then locates them. With the |
||
1285 | .Fl v |
||
1286 | option, hash prints the locations of the commands as it finds them. The |
||
1287 | .Fl r |
||
1288 | option causes the hash command to delete all the entries in the hash table |
||
1289 | except for functions. |
||
1290 | .It jobid Op Ar job |
||
1291 | Print the process id's of the processes in the job. |
||
1292 | If the |
||
1293 | .Ar job |
||
1294 | argument is omitted, the current job is used. |
||
1295 | .It jobs |
||
1296 | This command lists out all the background processes |
||
1297 | which are children of the current shell process. |
||
1298 | .It pwd |
||
1299 | Print the current directory. The builtin command may |
||
1300 | differ from the program of the same name because the |
||
1301 | builtin command remembers what the current directory |
||
1302 | is rather than recomputing it each time. This makes |
||
1303 | it faster. However, if the current directory is |
||
1304 | renamed, the builtin version of |
||
1305 | .Ic pwd |
||
1306 | will continue to print the old name for the directory. |
||
1307 | .It Xo read Op Fl p Ar prompt |
||
1308 | .Op Fl r |
||
1309 | .Ar variable... |
||
1310 | .Xc |
||
1311 | The prompt is printed if the |
||
1312 | .Fl p |
||
1313 | option is specified and the standard input is a terminal. Then a line is |
||
1314 | read from the standard input. The trailing newline is deleted from the |
||
1315 | line and the line is split as described in the section on word splitting |
||
1316 | above, and the pieces are assigned to the variables in order. |
||
1317 | At least one variable must be specified. |
||
1318 | If there are |
||
1319 | more pieces than variables, the remaining pieces (along with the |
||
1320 | characters in |
||
1321 | .Ev IFS |
||
1322 | that separated them) are assigned to the last variable. If there are more |
||
1323 | variables than pieces, the remaining variables are assigned the null |
||
1324 | string. The |
||
1325 | .Ic read |
||
1326 | builtin will indicate success unless EOF is encountered on input, in |
||
1327 | which case failure is returned. |
||
1328 | .Pp |
||
1329 | By default, unless the |
||
1330 | .Fl r |
||
1331 | option is specified, the backslash |
||
1332 | .Dq \e |
||
1333 | acts as an escape character, causing the following character to be treated |
||
1334 | literally. If a backslash is followed by a newline, the backslash and the |
||
1335 | newline will be deleted. |
||
1336 | .It readonly Ar name... |
||
1337 | .It readonly Fl p |
||
1338 | The specified names are marked as read only, so that they cannot be |
||
1339 | subsequently modified or unset. The shell allows the value of a variable |
||
1340 | to be set at the same time it is marked read only by writing |
||
1341 | .Pp |
||
1342 | .Dl readonly name=value |
||
1343 | .Pp |
||
1344 | With no arguments the readonly command lists the names of all read only |
||
1345 | variables. |
||
1346 | With the |
||
1347 | .Fl p |
||
1348 | option specified the output will be formatted suitably for non-interactive use. |
||
1349 | .Pp |
||
1350 | .It Xo set |
||
1351 | .Oo { |
||
1352 | .Fl options | Cm +options | Cm -- } |
||
1353 | .Oc Ar arg... |
||
1354 | .Xc |
||
1355 | The |
||
1356 | .Ic set |
||
1357 | command performs three different functions. |
||
1358 | .Pp |
||
1359 | With no arguments, it lists the values of all shell |
||
1360 | variables. |
||
1361 | .Pp |
||
1362 | If options are given, it sets the specified option |
||
1363 | flags, or clears them as described in the section |
||
1364 | called |
||
1365 | .Sx Argument List Processing . |
||
1366 | .Pp |
||
1367 | The third use of the set command is to set the values of the shell's |
||
1368 | positional parameters to the specified args. To change the positional |
||
1369 | parameters without changing any options, use |
||
1370 | .Dq -- |
||
1371 | as the first argument to set. If no args are present, the set command |
||
1372 | will clear all the positional parameters (equivalent to executing |
||
1373 | .Dq shift $# . ) |
||
1374 | .It setvar Ar variable Ar value |
||
1375 | Assigns value to variable. (In general it is better to write |
||
1376 | variable=value rather than using |
||
1377 | .Ic setvar . |
||
1378 | .Ic setvar |
||
1379 | is intended to be used in |
||
1380 | functions that assign values to variables whose names are passed as |
||
1381 | parameters.) |
||
1382 | .It shift Op Ar n |
||
1383 | Shift the positional parameters n times. A |
||
1384 | .Ic shift |
||
1385 | sets the value of |
||
1386 | .Va $1 |
||
1387 | to the value of |
||
1388 | .Va $2 , |
||
1389 | the value of |
||
1390 | .Va $2 |
||
1391 | to the value of |
||
1392 | .Va $3 , |
||
1393 | and so on, decreasing |
||
1394 | the value of |
||
1395 | .Va $# |
||
1396 | by one. If there are zero positional parameters, |
||
1397 | .Ic shift |
||
1398 | does nothing. |
||
1399 | .It times |
||
1400 | Print the accumulated user and system times for the shell and for processes |
||
1401 | run from the shell. The return status is 0. |
||
1402 | .It Xo trap |
||
1403 | .Op Ar action |
||
1404 | .Ar signal... |
||
1405 | .Xc |
||
1406 | Cause the shell to parse and execute action when any of the specified |
||
1407 | signals are received. The signals are specified by signal number. If |
||
1408 | .Ar signal |
||
1409 | is |
||
1410 | .Li 0 , |
||
1411 | the action is executed when the shell exits. |
||
1412 | .Ar action |
||
1413 | may be null or omitted; the former causes the specified signal to be |
||
1414 | ignored and the latter causes the default action to be taken. When the |
||
1415 | shell forks off a subshell, it resets trapped (but not ignored) signals to |
||
1416 | the default action. The |
||
1417 | .Ic trap |
||
1418 | command has no effect on signals that were |
||
1419 | ignored on entry to the shell. |
||
1420 | .It type Op Ar name ... |
||
1421 | Interpret each name as a command and print the resolution of the command |
||
1422 | search. Possible resolutions are: |
||
1423 | shell keyword, alias, shell builtin, |
||
1424 | command, tracked alias and not found. For aliases the alias expansion is |
||
1425 | printed; for commands and tracked aliases the complete pathname of the |
||
1426 | command is printed. |
||
1427 | .It ulimit Xo |
||
1428 | .Op Fl H \*(Ba Fl S |
||
1429 | .Op Fl a \*(Ba Fl tfdscmlpn Op Ar value |
||
1430 | .Xc |
||
1431 | Inquire about or set the hard or soft limits on processes or set new |
||
1432 | limits. The choice between hard limit (which no process is allowed to |
||
1433 | violate, and which may not be raised once it has been lowered) and soft |
||
1434 | limit (which causes processes to be signaled but not necessarily killed, |
||
1435 | and which may be raised) is made with these flags: |
||
1436 | .Bl -tag -width Fl |
||
1437 | .It Fl H |
||
1438 | set or inquire about hard limits |
||
1439 | .It Fl S |
||
1440 | set or inquire about soft limits. If neither |
||
1441 | .Fl H |
||
1442 | nor |
||
1443 | .Fl S |
||
1444 | is specified, the soft limit is displayed or both limits are set. If both |
||
1445 | are specified, the last one wins. |
||
1446 | .El |
||
1447 | .Pp |
||
1448 | .Bl -tag -width Fl |
||
1449 | The limit to be interrogated or set, then, is chosen by specifying |
||
1450 | any one of these flags: |
||
1451 | .It Fl a |
||
1452 | show all the current limits |
||
1453 | .It Fl t |
||
1454 | show or set the limit on CPU time (in seconds) |
||
1455 | .It Fl f |
||
1456 | show or set the limit on the largest file that can be created |
||
1457 | (in 512-byte blocks) |
||
1458 | .It Fl d |
||
1459 | show or set the limit on the data segment size of a process (in kilobytes) |
||
1460 | .It Fl s |
||
1461 | show or set the limit on the stack size of a process (in kilobytes) |
||
1462 | .It Fl c |
||
1463 | show or set the limit on the largest core dump size that can be produced |
||
1464 | (in 512-byte blocks) |
||
1465 | .It Fl m |
||
1466 | show or set the limit on the total physical memory that can be |
||
1467 | in use by a process (in kilobytes) |
||
1468 | .It Fl l |
||
1469 | show or set the limit on how much memory a process can lock with |
||
1470 | .Xr mlock 2 |
||
1471 | (in kilobytes) |
||
1472 | .It Fl p |
||
1473 | show or set the limit on the number of processes this user can |
||
1474 | have at one time |
||
1475 | .It Fl n |
||
1476 | show or set the limit on the number files a process can have open at once |
||
1477 | .El |
||
1478 | .Pp |
||
1479 | If none of these is specified, it is the limit on file size that is shown |
||
1480 | or set. If value is specified, the limit is set to that number; otherwise |
||
1481 | the current limit is displayed. |
||
1482 | .Pp |
||
1483 | Limits of an arbitrary process can be displayed or set using the |
||
1484 | .Xr sysctl 8 |
||
1485 | utility. |
||
1486 | .Pp |
||
1487 | .It umask Op Ar mask |
||
1488 | Set the value of umask (see |
||
1489 | .Xr umask 2 ) |
||
1490 | to the specified octal value. If the argument is omitted, the umask value |
||
1491 | is printed. |
||
1492 | .It unalias Xo |
||
1493 | .Op Fl a |
||
1494 | .Op Ar name |
||
1495 | .Xc |
||
1496 | If |
||
1497 | .Ar name |
||
1498 | is specified, the shell removes that alias. If |
||
1499 | .Fl a |
||
1500 | is specified, all aliases are removed. |
||
1501 | .It unset Ar name... |
||
1502 | The specified variables and functions are unset and unexported. If a given |
||
1503 | name corresponds to both a variable and a function, both the variable and |
||
1504 | the function are unset. |
||
1505 | .It wait Op Ar job |
||
1506 | Wait for the specified job to complete and return the exit status of the |
||
1507 | last process in the job. If the argument is omitted, wait for all jobs to |
||
1508 | complete and the return an exit status of zero. |
||
1509 | .El |
||
1510 | .Ss Command Line Editing |
||
1511 | When |
||
1512 | .Nm |
||
1513 | is being used interactively from a terminal, the current command |
||
1514 | and the command history (see |
||
1515 | .Ic fc |
||
1516 | in |
||
1517 | .Sx Builtins ) |
||
1518 | can be edited using vi-mode command-line editing. This mode uses commands, |
||
1519 | described below, similar to a subset of those described in the vi man |
||
1520 | page. The command |
||
1521 | .Ql set -o vi |
||
1522 | enables vi-mode editing and place sh into vi insert mode. With vi-mode |
||
1523 | enabled, sh can be switched between insert mode and command mode. The |
||
1524 | editor is not described in full here, but will be in a later document. |
||
1525 | It's similar to vi: typing |
||
1526 | .Aq ESC |
||
1527 | will throw you into command VI command mode. Hitting |
||
1528 | .Aq return |
||
1529 | while in command mode will pass the line to the shell. |
||
1530 | .Sh ENVIRONMENT |
||
1531 | .Bl -tag -width MAILCHECK |
||
1532 | .It Ev HOME |
||
1533 | Set automaticly by |
||
1534 | .Xr login 1 |
||
1535 | from the user's login directory in the password file |
||
1536 | .Pq Xr passwd 4 . |
||
1537 | This environment variable also functions as the default argument for the |
||
1538 | cd builtin. |
||
1539 | .It Ev PATH |
||
1540 | The default search path for executables. See the above section |
||
1541 | .Sx Path Search . |
||
1542 | .It Ev CDPATH |
||
1543 | The search path used with the cd builtin. |
||
1544 | .It Ev MAIL |
||
1545 | The name of a mail file, that will be checked for the arrival of new mail. |
||
1546 | Overridden by |
||
1547 | .Ev MAILPATH . |
||
1548 | .It Ev MAILCHECK |
||
1549 | The frequency in seconds that the shell checks for the arrival of mail |
||
1550 | in the files specified by the |
||
1551 | .Ev MAILPATH |
||
1552 | or the |
||
1553 | .Ev MAIL |
||
1554 | file. If set to 0, the check will occur at each prompt. |
||
1555 | .It Ev MAILPATH |
||
1556 | A colon |
||
1557 | .Dq \&: |
||
1558 | separated list of file names, for the shell to check for incoming mail. |
||
1559 | This environment setting overrides the |
||
1560 | .Ev MAIL |
||
1561 | setting. There is a maximum of 10 mailboxes that can be monitored at once. |
||
1562 | .It Ev PS1 |
||
1563 | The primary prompt string, which defaults to |
||
1564 | .Dq $ \ , |
||
1565 | unless you are the superuser, in which case it defaults to |
||
1566 | .Dq # \ . |
||
1567 | .It Ev PS2 |
||
1568 | The secondary prompt string, which defaults to |
||
1569 | .Dq > \ . |
||
1570 | .It Ev IFS |
||
1571 | Input Field Separators. This is normally set to <space> <tab> and |
||
1572 | <newline>. See the |
||
1573 | .Sx White Space Splitting |
||
1574 | section for more details. |
||
1575 | .It Ev TERM |
||
1576 | The default terminal setting for the shell. This is inherited by |
||
1577 | children of the shell, and is used in the history editing modes. |
||
1578 | .It Ev HISTSIZE |
||
1579 | The number of lines in the history buffer for the shell. |
||
1580 | .El |
||
1581 | .Sh FILES |
||
1582 | .Bl -item -width HOMEprofilexxxx |
||
1583 | .It |
||
1584 | .Pa $HOME/.profile |
||
1585 | .It |
||
1586 | .Pa /etc/profile |
||
1587 | .El |
||
1588 | .Sh SEE ALSO |
||
1589 | .Xr csh 1 , |
||
1590 | .Xr getopt 1 , |
||
1591 | .Xr ksh 1 , |
||
1592 | .Xr login 1 , |
||
1593 | .Xr test 1 , |
||
1594 | .Xr getopt 3 , |
||
1595 | .Xr passwd 4 , |
||
1596 | .Xr profile 4 , |
||
1597 | .Xr environ 5 |
||
1598 | .Xr sysctl 8 |
||
1599 | .Sh HISTORY |
||
1600 | A |
||
1601 | .Nm |
||
1602 | command appeared in |
||
1603 | .At v1 . |
||
1604 | It was, however, unmaintainable so we wrote this one. |
||
1605 | .Sh EXIT STATUS |
||
1606 | Errors that are detected by the shell, such as a syntax error, will cause the |
||
1607 | shell to exit with a non-zero exit status. If the shell is not an |
||
1608 | interactive shell, the execution of the shell file will be aborted. Otherwise |
||
1609 | the shell will return the exit status of the last command executed, or |
||
1610 | if the exit builtin is used with a numeric argument, it will return the |
||
1611 | argument. |
||
1612 | .Sh BUGS |
||
1613 | Setuid shell scripts should be avoided at all costs, as they are a |
||
1614 | significant security risk. |