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