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