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