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