xref: /freebsd/bin/sh/sh.1 (revision 0cdfe2ae89834a1a4b3468bfac870941ee17f2d5)
1.\"-
2.\" Copyright (c) 1991, 1993
3.\"	The Regents of the University of California.  All rights reserved.
4.\"
5.\" This code is derived from software contributed to Berkeley by
6.\" Kenneth Almquist.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"	from: @(#)sh.1	8.6 (Berkeley) 5/4/95
33.\" $FreeBSD$
34.\"
35.Dd June 14, 2013
36.Dt SH 1
37.Os
38.Sh NAME
39.Nm sh
40.Nd command interpreter (shell)
41.Sh SYNOPSIS
42.Nm
43.Op Fl /+abCEefIimnPpTuVvx
44.Op Fl /+o Ar longname
45.Oo
46.Ar script
47.Op Ar arg ...
48.Oc
49.Nm
50.Op Fl /+abCEefIimnPpTuVvx
51.Op Fl /+o Ar longname
52.Fl c Ar string
53.Oo
54.Ar name
55.Op Ar arg ...
56.Oc
57.Nm
58.Op Fl /+abCEefIimnPpTuVvx
59.Op Fl /+o Ar longname
60.Fl s
61.Op Ar arg ...
62.Sh DESCRIPTION
63The
64.Nm
65utility is the standard command interpreter for the system.
66The current version of
67.Nm
68is close to the
69.St -p1003.1
70specification for the shell.
71It only supports features
72designated by
73.Tn POSIX ,
74plus a few Berkeley extensions.
75This man page is not intended to be a tutorial nor a complete
76specification of the shell.
77.Ss Overview
78The shell is a command that reads lines from
79either a file or the terminal, interprets them, and
80generally executes other commands.
81It is the program that is started when a user logs into the system,
82although a user can select a different shell with the
83.Xr chsh 1
84command.
85The shell
86implements a language that has flow control constructs,
87a macro facility that provides a variety of features in
88addition to data storage, along with built-in history and line
89editing capabilities.
90It incorporates many features to
91aid interactive use and has the advantage that the interpretative
92language is common to both interactive and non-interactive
93use (shell scripts).
94That is, commands can be typed directly
95to the running shell or can be put into a file,
96which can be executed directly by the shell.
97.Ss Invocation
98.\"
99.\" XXX This next sentence is incredibly confusing.
100.\"
101If no arguments are present and if the standard input of the shell
102is connected to a terminal
103(or if the
104.Fl i
105option is set),
106the shell is considered an interactive shell.
107An interactive shell
108generally prompts before each command and handles programming
109and command errors differently (as described below).
110When first starting, the shell inspects argument 0, and
111if it begins with a dash
112.Pq Ql - ,
113the shell is also considered a login shell.
114This is normally done automatically by the system
115when the user first logs in.
116A login shell first reads commands
117from the files
118.Pa /etc/profile
119and then
120.Pa .profile
121in a user's home directory,
122if they exist.
123If the environment variable
124.Ev ENV
125is set on entry to a shell, or is set in the
126.Pa .profile
127of a login shell, the shell then subjects its value to parameter expansion
128and arithmetic expansion and reads commands from the named file.
129Therefore, a user should place commands that are to be executed only
130at login time in the
131.Pa .profile
132file, and commands that are executed for every shell inside the
133.Ev ENV
134file.
135The user can set the
136.Ev ENV
137variable to some file by placing the following line in the file
138.Pa .profile
139in the home directory,
140substituting for
141.Pa .shrc
142the filename desired:
143.Pp
144.Dl "ENV=$HOME/.shrc; export ENV"
145.Pp
146The first non-option argument specified on the command line
147will be treated as the
148name of a file from which to read commands (a shell script), and
149the remaining arguments are set as the positional parameters
150of the shell
151.Li ( $1 , $2 ,
152etc.).
153Otherwise, the shell reads commands
154from its standard input.
155.Pp
156Unlike older versions of
157.Nm
158the
159.Ev ENV
160script is only sourced on invocation of interactive shells.
161This
162closes a well-known, and sometimes easily exploitable security
163hole related to poorly thought out
164.Ev ENV
165scripts.
166.Ss Argument List Processing
167All of the single letter options to
168.Nm
169have a corresponding long name,
170with the exception of
171.Fl c
172and
173.Fl /+o .
174These long names are provided next to the single letter options
175in the descriptions below.
176The long name for an option may be specified as an argument to the
177.Fl /+o
178option of
179.Nm .
180Once the shell is running,
181the long name for an option may be specified as an argument to the
182.Fl /+o
183option of the
184.Ic set
185built-in command
186(described later in the section called
187.Sx Built-in Commands ) .
188Introducing an option with a dash
189.Pq Ql -
190enables the option,
191while using a plus
192.Pq Ql +
193disables the option.
194A
195.Dq Li --
196or plain
197.Ql -
198will stop option processing and will force the remaining
199words on the command line to be treated as arguments.
200The
201.Fl /+o
202and
203.Fl c
204options do not have long names.
205They take arguments and are described after the single letter options.
206.Bl -tag -width indent
207.It Fl a Li allexport
208Flag variables for export when assignments are made to them.
209.It Fl b Li notify
210Enable asynchronous notification of background job
211completion.
212(UNIMPLEMENTED)
213.It Fl C Li noclobber
214Do not overwrite existing files with
215.Ql > .
216.It Fl E Li emacs
217Enable the built-in
218.Xr emacs 1
219command line editor (disables the
220.Fl V
221option if it has been set;
222set automatically when interactive on terminals).
223.It Fl e Li errexit
224Exit immediately if any untested command fails in non-interactive mode.
225The exit status of a command is considered to be
226explicitly tested if the command is part of the list used to control
227an
228.Ic if , elif , while ,
229or
230.Ic until ;
231if the command is the left
232hand operand of an
233.Dq Li &&
234or
235.Dq Li ||
236operator; or if the command is a pipeline preceded by the
237.Ic !\&
238operator.
239If a shell function is executed and its exit status is explicitly
240tested, all commands of the function are considered to be tested as
241well.
242.It Fl f Li noglob
243Disable pathname expansion.
244.It Fl h Li trackall
245A do-nothing option for
246.Tn POSIX
247compliance.
248.It Fl I Li ignoreeof
249Ignore
250.Dv EOF Ap s
251from input when in interactive mode.
252.It Fl i Li interactive
253Force the shell to behave interactively.
254.It Fl m Li monitor
255Turn on job control (set automatically when interactive).
256.It Fl n Li noexec
257If not interactive, read commands but do not
258execute them.
259This is useful for checking the
260syntax of shell scripts.
261.It Fl P Li physical
262Change the default for the
263.Ic cd
264and
265.Ic pwd
266commands from
267.Fl L
268(logical directory layout)
269to
270.Fl P
271(physical directory layout).
272.It Fl p Li privileged
273Turn on privileged mode.
274This mode is enabled on startup
275if either the effective user or group ID is not equal to the
276real user or group ID.
277Turning this mode off sets the
278effective user and group IDs to the real user and group IDs.
279When this mode is enabled for interactive shells, the file
280.Pa /etc/suid_profile
281is sourced instead of
282.Pa ~/.profile
283after
284.Pa /etc/profile
285is sourced, and the contents of the
286.Ev ENV
287variable are ignored.
288.It Fl s Li stdin
289Read commands from standard input (set automatically
290if no file arguments are present).
291This option has
292no effect when set after the shell has already started
293running (i.e., when set with the
294.Ic set
295command).
296.It Fl T Li trapsasync
297When waiting for a child, execute traps immediately.
298If this option is not set,
299traps are executed after the child exits,
300as specified in
301.St -p1003.2 .
302This nonstandard option is useful for putting guarding shells around
303children that block signals.
304The surrounding shell may kill the child
305or it may just return control to the tty and leave the child alone,
306like this:
307.Bd -literal -offset indent
308sh -T -c "trap 'exit 1' 2 ; some-blocking-program"
309.Ed
310.It Fl u Li nounset
311Write a message to standard error when attempting
312to expand a variable, a positional parameter or
313the special parameter
314.Va \&!
315that is not set, and if the
316shell is not interactive, exit immediately.
317.It Fl V Li vi
318Enable the built-in
319.Xr vi 1
320command line editor (disables
321.Fl E
322if it has been set).
323.It Fl v Li verbose
324The shell writes its input to standard error
325as it is read.
326Useful for debugging.
327.It Fl x Li xtrace
328Write each command
329(preceded by the value of the
330.Va PS4
331variable subjected to parameter expansion and arithmetic expansion)
332to standard error before it is executed.
333Useful for debugging.
334.El
335.Pp
336The
337.Fl c
338option causes the commands to be read from the
339.Ar string
340operand instead of from the standard input.
341Keep in mind that this option only accepts a single string as its
342argument, hence multi-word strings must be quoted.
343.Pp
344The
345.Fl /+o
346option takes as its only argument the long name of an option
347to be enabled or disabled.
348For example, the following two invocations of
349.Nm
350both enable the built-in
351.Xr emacs 1
352command line editor:
353.Bd -literal -offset indent
354set -E
355set -o emacs
356.Ed
357.Pp
358If used without an argument, the
359.Fl o
360option displays the current option settings in a human-readable format.
361If
362.Cm +o
363is used without an argument, the current option settings are output
364in a format suitable for re-input into the shell.
365.Ss Lexical Structure
366The shell reads input in terms of lines from a file and breaks
367it up into words at whitespace (blanks and tabs), and at
368certain sequences of
369characters called
370.Dq operators ,
371which are special to the shell.
372There are two types of operators: control operators and
373redirection operators (their meaning is discussed later).
374The following is a list of valid operators:
375.Bl -tag -width indent
376.It Control operators:
377.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
378.It Li & Ta Li && Ta Li \&( Ta Li \&) Ta Li \en
379.It Li ;; Ta Li ;& Ta Li \&; Ta Li \&| Ta Li ||
380.El
381.It Redirection operators:
382.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
383.It Li < Ta Li > Ta Li << Ta Li >> Ta Li <>
384.It Li <& Ta Li >& Ta Li <<- Ta Li >| Ta \&
385.El
386.El
387.Pp
388The character
389.Ql #
390introduces a comment if used at the beginning of a word.
391The word starting with
392.Ql #
393and the rest of the line are ignored.
394.Pp
395.Tn ASCII
396.Dv NUL
397characters (character code 0) are not allowed in shell input.
398.Ss Quoting
399Quoting is used to remove the special meaning of certain characters
400or words to the shell, such as operators, whitespace, keywords,
401or alias names.
402.Pp
403There are four types of quoting: matched single quotes,
404dollar-single quotes,
405matched double quotes, and backslash.
406.Bl -tag -width indent
407.It Single Quotes
408Enclosing characters in single quotes preserves the literal
409meaning of all the characters (except single quotes, making
410it impossible to put single-quotes in a single-quoted string).
411.It Dollar-Single Quotes
412Enclosing characters between
413.Li $'
414and
415.Li '
416preserves the literal meaning of all characters
417except backslashes and single quotes.
418A backslash introduces a C-style escape sequence:
419.Bl -tag -width xUnnnnnnnn
420.It \ea
421Alert (ring the terminal bell)
422.It \eb
423Backspace
424.It \ec Ns Ar c
425The control character denoted by
426.Li ^ Ns Ar c
427in
428.Xr stty 1 .
429If
430.Ar c
431is a backslash, it must be doubled.
432.It \ee
433The ESC character
434.Tn ( ASCII
4350x1b)
436.It \ef
437Formfeed
438.It \en
439Newline
440.It \er
441Carriage return
442.It \et
443Horizontal tab
444.It \ev
445Vertical tab
446.It \e\e
447Literal backslash
448.It \e\&'
449Literal single-quote
450.It \e\&"
451Literal double-quote
452.It \e Ns Ar nnn
453The byte whose octal value is
454.Ar nnn
455(one to three digits)
456.It \ex Ns Ar nn
457The byte whose hexadecimal value is
458.Ar nn
459(one or more digits only the last two of which are used)
460.It \eu Ns Ar nnnn
461The Unicode code point
462.Ar nnnn
463(four hexadecimal digits)
464.It \eU Ns Ar nnnnnnnn
465The Unicode code point
466.Ar nnnnnnnn
467(eight hexadecimal digits)
468.El
469.Pp
470The sequences for Unicode code points are currently only useful with
471UTF-8 locales.
472They reject code point 0 and UTF-16 surrogates.
473.Pp
474If an escape sequence would produce a byte with value 0,
475that byte and the rest of the string until the matching single-quote
476are ignored.
477.Pp
478Any other string starting with a backslash is an error.
479.It Double Quotes
480Enclosing characters within double quotes preserves the literal
481meaning of all characters except dollar sign
482.Pq Ql $ ,
483backquote
484.Pq Ql ` ,
485and backslash
486.Pq Ql \e .
487The backslash inside double quotes is historically weird.
488It remains literal unless it precedes the following characters,
489which it serves to quote:
490.Pp
491.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
492.It Li $ Ta Li ` Ta Li \&" Ta Li \e Ta Li \en
493.El
494.It Backslash
495A backslash preserves the literal meaning of the following
496character, with the exception of the newline character
497.Pq Ql \en .
498A backslash preceding a newline is treated as a line continuation.
499.El
500.Ss Keywords
501Keywords or reserved words are words that have special meaning to the
502shell and are recognized at the beginning of a line and
503after a control operator.
504The following are keywords:
505.Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center
506.It Li \&! Ta { Ta } Ta Ic case Ta Ic do
507.It Ic done Ta Ic elif Ta Ic else Ta Ic esac Ta Ic fi
508.It Ic for Ta Ic if Ta Ic then Ta Ic until Ta Ic while
509.El
510.Ss Aliases
511An alias is a name and corresponding value set using the
512.Ic alias
513built-in command.
514Wherever the command word of a simple command may occur,
515and after checking for keywords if a keyword may occur, the shell
516checks the word to see if it matches an alias.
517If it does, it replaces it in the input stream with its value.
518For example, if there is an alias called
519.Dq Li lf
520with the value
521.Dq Li "ls -F" ,
522then the input
523.Pp
524.Dl "lf foobar"
525.Pp
526would become
527.Pp
528.Dl "ls -F foobar"
529.Pp
530Aliases provide a convenient way for naive users to
531create shorthands for commands without having to learn how
532to create functions with arguments.
533Using aliases in scripts is discouraged
534because the command that defines them must be executed
535before the code that uses them is parsed.
536This is fragile and not portable.
537.Pp
538An alias name may be escaped in a command line, so that it is not
539replaced by its alias value, by using quoting characters within or
540adjacent to the alias name.
541This is most often done by prefixing
542an alias name with a backslash to execute a function, built-in, or
543normal program with the same name.
544See the
545.Sx Quoting
546subsection.
547.Ss Commands
548The shell interprets the words it reads according to a
549language, the specification of which is outside the scope
550of this man page (refer to the BNF in the
551.St -p1003.2
552document).
553Essentially though, a line is read and if
554the first word of the line (or after a control operator)
555is not a keyword, then the shell has recognized a
556simple command.
557Otherwise, a complex command or some
558other special construct may have been recognized.
559.Ss Simple Commands
560If a simple command has been recognized, the shell performs
561the following actions:
562.Bl -enum
563.It
564Leading words of the form
565.Dq Li name=value
566are stripped off and assigned to the environment of
567the simple command.
568Redirection operators and
569their arguments (as described below) are stripped
570off and saved for processing.
571.It
572The remaining words are expanded as described in
573the section called
574.Sx Word Expansions ,
575and the first remaining word is considered the command
576name and the command is located.
577The remaining
578words are considered the arguments of the command.
579If no command name resulted, then the
580.Dq Li name=value
581variable assignments recognized in 1) affect the
582current shell.
583.It
584Redirections are performed as described in
585the next section.
586.El
587.Ss Redirections
588Redirections are used to change where a command reads its input
589or sends its output.
590In general, redirections open, close, or
591duplicate an existing reference to a file.
592The overall format
593used for redirection is:
594.Pp
595.D1 Oo Ar n Oc Ar redir-op file
596.Pp
597The
598.Ar redir-op
599is one of the redirection operators mentioned
600previously.
601The following gives some examples of how these
602operators can be used.
603Note that stdin and stdout are commonly used abbreviations
604for standard input and standard output respectively.
605.Bl -tag -width "1234567890XX" -offset indent
606.It Oo Ar n Oc Ns Li > Ar file
607redirect stdout (or file descriptor
608.Ar n )
609to
610.Ar file
611.It Oo Ar n Oc Ns Li >| Ar file
612same as above, but override the
613.Fl C
614option
615.It Oo Ar n Oc Ns Li >> Ar file
616append stdout (or file descriptor
617.Ar n )
618to
619.Ar file
620.It Oo Ar n Oc Ns Li < Ar file
621redirect stdin (or file descriptor
622.Ar n )
623from
624.Ar file
625.It Oo Ar n Oc Ns Li <> Ar file
626redirect stdin (or file descriptor
627.Ar n )
628to and from
629.Ar file
630.It Oo Ar n1 Oc Ns Li <& Ns Ar n2
631duplicate stdin (or file descriptor
632.Ar n1 )
633from file descriptor
634.Ar n2
635.It Oo Ar n Oc Ns Li <&-
636close stdin (or file descriptor
637.Ar n )
638.It Oo Ar n1 Oc Ns Li >& Ns Ar n2
639duplicate stdout (or file descriptor
640.Ar n1 )
641to file descriptor
642.Ar n2
643.It Oo Ar n Oc Ns Li >&-
644close stdout (or file descriptor
645.Ar n )
646.El
647.Pp
648The following redirection is often called a
649.Dq here-document .
650.Bd -unfilled -offset indent
651.Oo Ar n Oc Ns Li << Ar delimiter
652.Ar here-doc-text
653.Ar ...
654.Ar delimiter
655.Ed
656.Pp
657All the text on successive lines up to the delimiter is
658saved away and made available to the command on standard
659input, or file descriptor
660.Ar n
661if it is specified.
662If the
663.Ar delimiter
664as specified on the initial line is quoted, then the
665.Ar here-doc-text
666is treated literally, otherwise the text is subjected to
667parameter expansion, command substitution, and arithmetic
668expansion (as described in the section on
669.Sx Word Expansions ) .
670If the operator is
671.Dq Li <<-
672instead of
673.Dq Li << ,
674then leading tabs
675in the
676.Ar here-doc-text
677are stripped.
678.Ss Search and Execution
679There are three types of commands: shell functions,
680built-in commands, and normal programs.
681The command is searched for (by name) in that order.
682The three types of commands are all executed in a different way.
683.Pp
684When a shell function is executed, all of the shell positional
685parameters (except
686.Li $0 ,
687which remains unchanged) are
688set to the arguments of the shell function.
689The variables which are explicitly placed in the environment of
690the command (by placing assignments to them before the
691function name) are made local to the function and are set
692to the values given.
693Then the command given in the function definition is executed.
694The positional parameters are restored to their original values
695when the command completes.
696This all occurs within the current shell.
697.Pp
698Shell built-in commands are executed internally to the shell, without
699spawning a new process.
700There are two kinds of built-in commands: regular and special.
701Assignments before special builtins persist after they finish
702executing and assignment errors, redirection errors and certain
703operand errors cause a script to be aborted.
704Special builtins cannot be overridden with a function.
705Both regular and special builtins can affect the shell in ways
706normal programs cannot.
707.Pp
708Otherwise, if the command name does not match a function
709or built-in command, the command is searched for as a normal
710program in the file system (as described in the next section).
711When a normal program is executed, the shell runs the program,
712passing the arguments and the environment to the program.
713If the program is not a normal executable file
714(i.e., if it does not begin with the
715.Dq "magic number"
716whose
717.Tn ASCII
718representation is
719.Dq Li #! ,
720resulting in an
721.Er ENOEXEC
722return value from
723.Xr execve 2 )
724but appears to be a text file,
725the shell will run a new instance of
726.Nm
727to interpret it.
728.Pp
729Note that previous versions of this document
730and the source code itself misleadingly and sporadically
731refer to a shell script without a magic number
732as a
733.Dq "shell procedure" .
734.Ss Path Search
735When locating a command, the shell first looks to see if
736it has a shell function by that name.
737Then it looks for a
738built-in command by that name.
739If a built-in command is not found,
740one of two things happen:
741.Bl -enum
742.It
743Command names containing a slash are simply executed without
744performing any searches.
745.It
746The shell searches each entry in the
747.Va PATH
748variable
749in turn for the command.
750The value of the
751.Va PATH
752variable should be a series of
753entries separated by colons.
754Each entry consists of a
755directory name.
756The current directory
757may be indicated implicitly by an empty directory name,
758or explicitly by a single period.
759.El
760.Ss Command Exit Status
761Each command has an exit status that can influence the behavior
762of other shell commands.
763The paradigm is that a command exits
764with zero for normal or success, and non-zero for failure,
765error, or a false indication.
766The man page for each command
767should indicate the various exit codes and what they mean.
768Additionally, the built-in commands return exit codes, as does
769an executed shell function.
770.Pp
771If a command is terminated by a signal, its exit status is 128 plus
772the signal number.
773Signal numbers are defined in the header file
774.In sys/signal.h .
775.Ss Complex Commands
776Complex commands are combinations of simple commands
777with control operators or keywords, together creating a larger complex
778command.
779More generally, a command is one of the following:
780.Bl -item -offset indent
781.It
782simple command
783.It
784pipeline
785.It
786list or compound-list
787.It
788compound command
789.It
790function definition
791.El
792.Pp
793Unless otherwise stated, the exit status of a command is
794that of the last simple command executed by the command.
795.Ss Pipelines
796A pipeline is a sequence of one or more commands separated
797by the control operator
798.Ql \&| .
799The standard output of all but
800the last command is connected to the standard input
801of the next command.
802The standard output of the last
803command is inherited from the shell, as usual.
804.Pp
805The format for a pipeline is:
806.Pp
807.D1 Oo Li \&! Oc Ar command1 Op Li \&| Ar command2 ...
808.Pp
809The standard output of
810.Ar command1
811is connected to the standard input of
812.Ar command2 .
813The standard input, standard output, or
814both of a command is considered to be assigned by the
815pipeline before any redirection specified by redirection
816operators that are part of the command.
817.Pp
818Note that unlike some other shells,
819.Nm
820executes each process in a pipeline with more than one command
821in a subshell environment and as a child of the
822.Nm
823process.
824.Pp
825If the pipeline is not in the background (discussed later),
826the shell waits for all commands to complete.
827.Pp
828If the keyword
829.Ic !\&
830does not precede the pipeline, the
831exit status is the exit status of the last command specified
832in the pipeline.
833Otherwise, the exit status is the logical
834NOT of the exit status of the last command.
835That is, if
836the last command returns zero, the exit status is 1; if
837the last command returns greater than zero, the exit status
838is zero.
839.Pp
840Because pipeline assignment of standard input or standard
841output or both takes place before redirection, it can be
842modified by redirection.
843For example:
844.Pp
845.Dl "command1 2>&1 | command2"
846.Pp
847sends both the standard output and standard error of
848.Ar command1
849to the standard input of
850.Ar command2 .
851.Pp
852A
853.Ql \&;
854or newline terminator causes the preceding
855AND-OR-list
856(described below in the section called
857.Sx Short-Circuit List Operators )
858to be executed sequentially;
859an
860.Ql &
861causes asynchronous execution of the preceding AND-OR-list.
862.Ss Background Commands (&)
863If a command is terminated by the control operator ampersand
864.Pq Ql & ,
865the shell executes the command in a subshell environment (see
866.Sx Grouping Commands Together
867below) and asynchronously;
868the shell does not wait for the command to finish
869before executing the next command.
870.Pp
871The format for running a command in background is:
872.Pp
873.D1 Ar command1 Li & Op Ar command2 Li & Ar ...
874.Pp
875If the shell is not interactive, the standard input of an
876asynchronous command is set to
877.Pa /dev/null .
878.Ss Lists (Generally Speaking)
879A list is a sequence of zero or more commands separated by
880newlines, semicolons, or ampersands,
881and optionally terminated by one of these three characters.
882The commands in a
883list are executed in the order they are written.
884If command is followed by an ampersand, the shell starts the
885command and immediately proceeds onto the next command;
886otherwise it waits for the command to terminate before
887proceeding to the next one.
888.Ss Short-Circuit List Operators
889.Dq Li &&
890and
891.Dq Li ||
892are AND-OR list operators.
893.Dq Li &&
894executes the first command, and then executes the second command
895if the exit status of the first command is zero.
896.Dq Li ||
897is similar, but executes the second command if the exit
898status of the first command is nonzero.
899.Dq Li &&
900and
901.Dq Li ||
902both have the same priority.
903.Ss Flow-Control Constructs (if, while, for, case)
904The syntax of the
905.Ic if
906command is:
907.Bd -unfilled -offset indent -compact
908.Ic if Ar list
909.Ic then Ar list
910.Oo Ic elif Ar list
911.Ic then Ar list Oc Ar ...
912.Op Ic else Ar list
913.Ic fi
914.Ed
915.Pp
916The syntax of the
917.Ic while
918command is:
919.Bd -unfilled -offset indent -compact
920.Ic while Ar list
921.Ic do Ar list
922.Ic done
923.Ed
924.Pp
925The two lists are executed repeatedly while the exit status of the
926first list is zero.
927The
928.Ic until
929command is similar, but has the word
930.Ic until
931in place of
932.Ic while ,
933which causes it to
934repeat until the exit status of the first list is zero.
935.Pp
936The syntax of the
937.Ic for
938command is:
939.Bd -unfilled -offset indent -compact
940.Ic for Ar variable Op Ic in Ar word ...
941.Ic do Ar list
942.Ic done
943.Ed
944.Pp
945If
946.Ic in
947and the following words are omitted,
948.Ic in Li \&"$@\&"
949is used instead.
950The words are expanded, and then the list is executed
951repeatedly with the variable set to each word in turn.
952The
953.Ic do
954and
955.Ic done
956commands may be replaced with
957.Ql {
958and
959.Ql } .
960.Pp
961The syntax of the
962.Ic break
963and
964.Ic continue
965commands is:
966.D1 Ic break Op Ar num
967.D1 Ic continue Op Ar num
968.Pp
969The
970.Ic break
971command terminates the
972.Ar num
973innermost
974.Ic for
975or
976.Ic while
977loops.
978The
979.Ic continue
980command continues with the next iteration of the innermost loop.
981These are implemented as special built-in commands.
982.Pp
983The syntax of the
984.Ic case
985command is:
986.Bd -unfilled -offset indent -compact
987.Ic case Ar word Ic in
988.Ar pattern Ns Li ) Ar list Li ;;
989.Ar ...
990.Ic esac
991.Ed
992.Pp
993The pattern can actually be one or more patterns
994(see
995.Sx Shell Patterns
996described later),
997separated by
998.Ql \&|
999characters.
1000Tilde expansion, parameter expansion, command substitution,
1001arithmetic expansion and quote removal are applied to the word.
1002Then, each pattern is expanded in turn using tilde expansion,
1003parameter expansion, command substitution and arithmetic expansion and
1004the expanded form of the word is checked against it.
1005If a match is found, the corresponding list is executed.
1006If the selected list is terminated by the control operator
1007.Ql ;&
1008instead of
1009.Ql ;; ,
1010execution continues with the next list,
1011continuing until a list terminated with
1012.Ql ;;
1013or the end of the
1014.Ic case
1015command.
1016The exit code of the
1017.Ic case
1018command is the exit code of the last command executed in the list or
1019zero if no patterns were matched.
1020.Ss Grouping Commands Together
1021Commands may be grouped by writing either
1022.Pp
1023.D1 Li \&( Ns Ar list Ns Li \%)
1024.Pp
1025or
1026.Pp
1027.D1 Li { Ar list Ns Li \&; }
1028.Pp
1029The first form executes the commands in a subshell environment.
1030A subshell environment has its own copy of:
1031.Bl -enum
1032.It
1033The current working directory as set by
1034.Ic cd .
1035.It
1036The file creation mask as set by
1037.Ic umask .
1038.It
1039Resource limits as set by
1040.Ic ulimit .
1041.It
1042References to open files.
1043.It
1044Traps as set by
1045.Ic trap .
1046.It
1047Known jobs.
1048.It
1049Positional parameters and variables.
1050.It
1051Shell options.
1052.It
1053Shell functions.
1054.It
1055Shell aliases.
1056.El
1057.Pp
1058These are copied from the parent shell environment,
1059except that trapped (but not ignored) signals are reset to the default action
1060and known jobs are cleared.
1061Any changes do not affect the parent shell environment.
1062.Pp
1063A subshell environment may be implemented as a child process or differently.
1064If job control is enabled in an interactive shell,
1065commands grouped in parentheses can be suspended and continued as a unit.
1066.Pp
1067For compatibility with other shells,
1068two open parentheses in sequence should be separated by whitespace.
1069.Pp
1070The second form never forks another shell,
1071so it is slightly more efficient.
1072Grouping commands together this way allows the user to
1073redirect their output as though they were one program:
1074.Bd -literal -offset indent
1075{ echo -n "hello"; echo " world"; } > greeting
1076.Ed
1077.Ss Functions
1078The syntax of a function definition is
1079.Pp
1080.D1 Ar name Li \&( \&) Ar command
1081.Pp
1082A function definition is an executable statement; when
1083executed it installs a function named
1084.Ar name
1085and returns an
1086exit status of zero.
1087The
1088.Ar command
1089is normally a list
1090enclosed between
1091.Ql {
1092and
1093.Ql } .
1094.Pp
1095Variables may be declared to be local to a function by
1096using the
1097.Ic local
1098command.
1099This should appear as the first statement of a function,
1100and the syntax is:
1101.Pp
1102.D1 Ic local Oo Ar variable ... Oc Op Fl
1103.Pp
1104The
1105.Ic local
1106command is implemented as a built-in command.
1107.Pp
1108When a variable is made local, it inherits the initial
1109value and exported and readonly flags from the variable
1110with the same name in the surrounding scope, if there is
1111one.
1112Otherwise, the variable is initially unset.
1113The shell
1114uses dynamic scoping, so that if the variable
1115.Va x
1116is made local to function
1117.Em f ,
1118which then calls function
1119.Em g ,
1120references to the variable
1121.Va x
1122made inside
1123.Em g
1124will refer to the variable
1125.Va x
1126declared inside
1127.Em f ,
1128not to the global variable named
1129.Va x .
1130.Pp
1131The only special parameter that can be made local is
1132.Ql - .
1133Making
1134.Ql -
1135local causes any shell options that are
1136changed via the
1137.Ic set
1138command inside the function to be
1139restored to their original values when the function
1140returns.
1141.Pp
1142The syntax of the
1143.Ic return
1144command is
1145.Pp
1146.D1 Ic return Op Ar exitstatus
1147.Pp
1148It terminates the current executional scope, returning from the previous
1149nested function, sourced script, or shell instance, in that order.
1150The
1151.Ic return
1152command is implemented as a special built-in command.
1153.Ss Variables and Parameters
1154The shell maintains a set of parameters.
1155A parameter
1156denoted by a name is called a variable.
1157When starting up,
1158the shell turns all the environment variables into shell
1159variables.
1160New variables can be set using the form
1161.Pp
1162.D1 Ar name Ns = Ns Ar value
1163.Pp
1164Variables set by the user must have a name consisting solely
1165of alphabetics, numerics, and underscores.
1166The first letter of a variable name must not be numeric.
1167A parameter can also be denoted by a number
1168or a special character as explained below.
1169.Pp
1170Assignments are expanded differently from other words:
1171tilde expansion is also performed after the equals sign and after any colon
1172and usernames are also terminated by colons,
1173and field splitting and pathname expansion are not performed.
1174.Pp
1175This special expansion applies not only to assignments that form a simple
1176command by themselves or precede a command word,
1177but also to words passed to the
1178.Ic export ,
1179.Ic local
1180or
1181.Ic readonly
1182built-in commands that have this form.
1183For this, the builtin's name must be literal
1184(not the result of an expansion)
1185and may optionally be preceded by one or more literal instances of
1186.Ic command
1187without options.
1188.Ss Positional Parameters
1189A positional parameter is a parameter denoted by a number greater than zero.
1190The shell sets these initially to the values of its command line
1191arguments that follow the name of the shell script.
1192The
1193.Ic set
1194built-in command can also be used to set or reset them.
1195.Ss Special Parameters
1196Special parameters are parameters denoted by a single special character
1197or the digit zero.
1198They are shown in the following list, exactly as they would appear in input
1199typed by the user or in the source of a shell script.
1200.Bl -hang
1201.It Li $*
1202Expands to the positional parameters, starting from one.
1203When
1204the expansion occurs within a double-quoted string
1205it expands to a single field with the value of each parameter
1206separated by the first character of the
1207.Va IFS
1208variable,
1209or by a space if
1210.Va IFS
1211is unset.
1212.It Li $@
1213Expands to the positional parameters, starting from one.
1214When
1215the expansion occurs within double-quotes, each positional
1216parameter expands as a separate argument.
1217If there are no positional parameters, the
1218expansion of
1219.Li @
1220generates zero arguments, even when
1221.Li @
1222is double-quoted.
1223What this basically means, for example, is
1224if
1225.Li $1
1226is
1227.Dq Li abc
1228and
1229.Li $2
1230is
1231.Dq Li "def ghi" ,
1232then
1233.Li \&"$@\&"
1234expands to
1235the two arguments:
1236.Bd -literal -offset indent
1237"abc"   "def ghi"
1238.Ed
1239.It Li $#
1240Expands to the number of positional parameters.
1241.It Li $?
1242Expands to the exit status of the most recent pipeline.
1243.It Li $-
1244(hyphen) Expands to the current option flags (the single-letter
1245option names concatenated into a string) as specified on
1246invocation, by the
1247.Ic set
1248built-in command, or implicitly
1249by the shell.
1250.It Li $$
1251Expands to the process ID of the invoked shell.
1252A subshell
1253retains the same value of
1254.Va $
1255as its parent.
1256.It Li $!
1257Expands to the process ID of the most recent background
1258command executed from the current shell.
1259For a
1260pipeline, the process ID is that of the last command in the
1261pipeline.
1262If this parameter is referenced, the shell will remember
1263the process ID and its exit status until the
1264.Ic wait
1265built-in command reports completion of the process.
1266.It Li $0
1267(zero) Expands to the name of the shell script if passed on the command line,
1268the
1269.Ar name
1270operand if given (with
1271.Fl c )
1272or otherwise argument 0 passed to the shell.
1273.El
1274.Ss Special Variables
1275The following variables are set by the shell or
1276have special meaning to it:
1277.Bl -tag -width ".Va HISTSIZE"
1278.It Va CDPATH
1279The search path used with the
1280.Ic cd
1281built-in.
1282.It Va EDITOR
1283The fallback editor used with the
1284.Ic fc
1285built-in.
1286If not set, the default editor is
1287.Xr ed 1 .
1288.It Va FCEDIT
1289The default editor used with the
1290.Ic fc
1291built-in.
1292.It Va HISTSIZE
1293The number of previous commands that are accessible.
1294.It Va HOME
1295The user's home directory,
1296used in tilde expansion and as a default directory for the
1297.Ic cd
1298built-in.
1299.It Va IFS
1300Input Field Separators.
1301The default value is
1302.Aq space ,
1303.Aq tab ,
1304and
1305.Aq newline
1306in that order.
1307This default also applies if
1308.Va IFS
1309is unset, but not if it is set to the empty string.
1310See the
1311.Sx White Space Splitting
1312section for more details.
1313.It Va LINENO
1314The current line number in the script or function.
1315.It Va MAIL
1316The name of a mail file, that will be checked for the arrival of new
1317mail.
1318Overridden by
1319.Va MAILPATH .
1320.It Va MAILPATH
1321A colon
1322.Pq Ql \&:
1323separated list of file names, for the shell to check for incoming
1324mail.
1325This variable overrides the
1326.Va MAIL
1327setting.
1328There is a maximum of 10 mailboxes that can be monitored at once.
1329.It Va PATH
1330The default search path for executables.
1331See the
1332.Sx Path Search
1333section for details.
1334.It Va PPID
1335The parent process ID of the invoked shell.
1336This is set at startup
1337unless this variable is in the environment.
1338A later change of parent process ID is not reflected.
1339A subshell retains the same value of
1340.Va PPID .
1341.It Va PS1
1342The primary prompt string, which defaults to
1343.Dq Li "$ " ,
1344unless you are the superuser, in which case it defaults to
1345.Dq Li "# " .
1346.Va PS1
1347may include any of the following formatting sequences,
1348which are replaced by the given information:
1349.Bl -tag -width indent
1350.It Li \eH
1351The local hostname.
1352.It Li \eh
1353The fully-qualified hostname.
1354.It Li \eW
1355The final component of the current working directory.
1356.It Li \ew
1357The entire path of the current working directory.
1358.It Li \e$
1359Superuser status.
1360.Dq Li "$ "
1361for normal users and
1362.Dq Li "# "
1363for superusers.
1364.It Li \e\e
1365A literal backslash.
1366.El
1367.It Va PS2
1368The secondary prompt string, which defaults to
1369.Dq Li "> " .
1370.Va PS2
1371may include any of the formatting sequences from
1372.Va PS1 .
1373.It Va PS4
1374The prefix for the trace output (if
1375.Fl x
1376is active).
1377The default is
1378.Dq Li "+ " .
1379.El
1380.Ss Word Expansions
1381This clause describes the various expansions that are
1382performed on words.
1383Not all expansions are performed on
1384every word, as explained later.
1385.Pp
1386Tilde expansions, parameter expansions, command substitutions,
1387arithmetic expansions, and quote removals that occur within
1388a single word expand to a single field.
1389It is only field
1390splitting or pathname expansion that can create multiple
1391fields from a single word.
1392The single exception to this rule is
1393the expansion of the special parameter
1394.Va @
1395within double-quotes,
1396as was described above.
1397.Pp
1398The order of word expansion is:
1399.Bl -enum
1400.It
1401Tilde Expansion, Parameter Expansion, Command Substitution,
1402Arithmetic Expansion (these all occur at the same time).
1403.It
1404Field Splitting is performed on fields generated by step (1)
1405unless the
1406.Va IFS
1407variable is null.
1408.It
1409Pathname Expansion (unless the
1410.Fl f
1411option is in effect).
1412.It
1413Quote Removal.
1414.El
1415.Pp
1416The
1417.Ql $
1418character is used to introduce parameter expansion, command
1419substitution, or arithmetic expansion.
1420.Ss Tilde Expansion (substituting a user's home directory)
1421A word beginning with an unquoted tilde character
1422.Pq Ql ~
1423is
1424subjected to tilde expansion.
1425All the characters up to a slash
1426.Pq Ql /
1427or the end of the word are treated as a username
1428and are replaced with the user's home directory.
1429If the
1430username is missing (as in
1431.Pa ~/foobar ) ,
1432the tilde is replaced with the value of the
1433.Va HOME
1434variable (the current user's home directory).
1435.Ss Parameter Expansion
1436The format for parameter expansion is as follows:
1437.Pp
1438.D1 Li ${ Ns Ar expression Ns Li }
1439.Pp
1440where
1441.Ar expression
1442consists of all characters until the matching
1443.Ql } .
1444Any
1445.Ql }
1446escaped by a backslash or within a single-quoted or double-quoted
1447string, and characters in
1448embedded arithmetic expansions, command substitutions, and variable
1449expansions, are not examined in determining the matching
1450.Ql } .
1451If the variants with
1452.Ql + ,
1453.Ql - ,
1454.Ql =
1455or
1456.Ql ?\&
1457occur within a double-quoted string,
1458as an extension there may be unquoted parts
1459(via double-quotes inside the expansion);
1460.Ql }
1461within such parts are also not examined in determining the matching
1462.Ql } .
1463.Pp
1464The simplest form for parameter expansion is:
1465.Pp
1466.D1 Li ${ Ns Ar parameter Ns Li }
1467.Pp
1468The value, if any, of
1469.Ar parameter
1470is substituted.
1471.Pp
1472The parameter name or symbol can be enclosed in braces, which are
1473optional except for positional parameters with more than one digit or
1474when parameter is followed by a character that could be interpreted as
1475part of the name.
1476If a parameter expansion occurs inside double-quotes:
1477.Bl -enum
1478.It
1479Field splitting is not performed on the results of the
1480expansion, with the exception of the special parameter
1481.Va @ .
1482.It
1483Pathname expansion is not performed on the results of the
1484expansion.
1485.El
1486.Pp
1487In addition, a parameter expansion can be modified by using one of the
1488following formats.
1489.Bl -tag -width indent
1490.It Li ${ Ns Ar parameter Ns Li :- Ns Ar word Ns Li }
1491Use Default Values.
1492If
1493.Ar parameter
1494is unset or null, the expansion of
1495.Ar word
1496is substituted; otherwise, the value of
1497.Ar parameter
1498is substituted.
1499.It Li ${ Ns Ar parameter Ns Li := Ns Ar word Ns Li }
1500Assign Default Values.
1501If
1502.Ar parameter
1503is unset or null, the expansion of
1504.Ar word
1505is assigned to
1506.Ar parameter .
1507In all cases, the
1508final value of
1509.Ar parameter
1510is substituted.
1511Quoting inside
1512.Ar word
1513does not prevent field splitting or pathname expansion.
1514Only variables, not positional
1515parameters or special parameters, can be
1516assigned in this way.
1517.It Li ${ Ns Ar parameter Ns Li :? Ns Oo Ar word Oc Ns Li }
1518Indicate Error if Null or Unset.
1519If
1520.Ar parameter
1521is unset or null, the expansion of
1522.Ar word
1523(or a message indicating it is unset if
1524.Ar word
1525is omitted) is written to standard
1526error and the shell exits with a nonzero
1527exit status.
1528Otherwise, the value of
1529.Ar parameter
1530is substituted.
1531An
1532interactive shell need not exit.
1533.It Li ${ Ns Ar parameter Ns Li :+ Ns Ar word Ns Li }
1534Use Alternate Value.
1535If
1536.Ar parameter
1537is unset or null, null is substituted;
1538otherwise, the expansion of
1539.Ar word
1540is substituted.
1541.El
1542.Pp
1543In the parameter expansions shown previously, use of the colon in the
1544format results in a test for a parameter that is unset or null; omission
1545of the colon results in a test for a parameter that is only unset.
1546.Pp
1547The
1548.Ar word
1549inherits the type of quoting
1550(unquoted, double-quoted or here-document)
1551from the surroundings,
1552with the exception that a backslash that quotes a closing brace is removed
1553during quote removal.
1554.Bl -tag -width indent
1555.It Li ${# Ns Ar parameter Ns Li }
1556String Length.
1557The length in characters of
1558the value of
1559.Ar parameter .
1560.El
1561.Pp
1562The following four varieties of parameter expansion provide for substring
1563processing.
1564In each case, pattern matching notation
1565(see
1566.Sx Shell Patterns ) ,
1567rather than regular expression notation,
1568is used to evaluate the patterns.
1569If parameter is one of the special parameters
1570.Va *
1571or
1572.Va @ ,
1573the result of the expansion is unspecified.
1574Enclosing the full parameter expansion string in double-quotes does not
1575cause the following four varieties of pattern characters to be quoted,
1576whereas quoting characters within the braces has this effect.
1577.Bl -tag -width indent
1578.It Li ${ Ns Ar parameter Ns Li % Ns Ar word Ns Li }
1579Remove Smallest Suffix Pattern.
1580The
1581.Ar word
1582is expanded to produce a pattern.
1583The
1584parameter expansion then results in
1585.Ar parameter ,
1586with the smallest portion of the
1587suffix matched by the pattern deleted.
1588.It Li ${ Ns Ar parameter Ns Li %% Ns Ar word Ns Li }
1589Remove Largest Suffix Pattern.
1590The
1591.Ar word
1592is expanded to produce a pattern.
1593The
1594parameter expansion then results in
1595.Ar parameter ,
1596with the largest portion of the
1597suffix matched by the pattern deleted.
1598.It Li ${ Ns Ar parameter Ns Li # Ns Ar word Ns Li }
1599Remove Smallest Prefix Pattern.
1600The
1601.Ar word
1602is expanded to produce a pattern.
1603The
1604parameter expansion then results in
1605.Ar parameter ,
1606with the smallest portion of the
1607prefix matched by the pattern deleted.
1608.It Li ${ Ns Ar parameter Ns Li ## Ns Ar word Ns Li }
1609Remove Largest Prefix Pattern.
1610The
1611.Ar word
1612is expanded to produce a pattern.
1613The
1614parameter expansion then results in
1615.Ar parameter ,
1616with the largest portion of the
1617prefix matched by the pattern deleted.
1618.El
1619.Ss Command Substitution
1620Command substitution allows the output of a command to be substituted in
1621place of the command name itself.
1622Command substitution occurs when
1623the command is enclosed as follows:
1624.Pp
1625.D1 Li $( Ns Ar command Ns Li )\&
1626.Pp
1627or the backquoted version:
1628.Pp
1629.D1 Li ` Ns Ar command Ns Li `
1630.Pp
1631The shell expands the command substitution by executing command
1632and replacing the command substitution
1633with the standard output of the command,
1634removing sequences of one or more newlines at the end of the substitution.
1635Embedded newlines before the end of the output are not removed;
1636however, during field splitting, they may be translated into spaces
1637depending on the value of
1638.Va IFS
1639and the quoting that is in effect.
1640The command is executed in a subshell environment,
1641except that the built-in commands
1642.Ic jobid ,
1643.Ic jobs ,
1644and
1645.Ic trap
1646return information about the parent shell environment
1647and
1648.Ic times
1649returns information about the same process
1650if they are the only command in a command substitution.
1651.Pp
1652If a command substitution of the
1653.Li $(
1654form begins with a subshell,
1655the
1656.Li $(
1657and
1658.Li (\&
1659must be separated by whitespace
1660to avoid ambiguity with arithmetic expansion.
1661.Ss Arithmetic Expansion
1662Arithmetic expansion provides a mechanism for evaluating an arithmetic
1663expression and substituting its value.
1664The format for arithmetic expansion is as follows:
1665.Pp
1666.D1 Li $(( Ns Ar expression Ns Li ))
1667.Pp
1668The
1669.Ar expression
1670is treated as if it were in double-quotes, except
1671that a double-quote inside the expression is not treated specially.
1672The
1673shell expands all tokens in the
1674.Ar expression
1675for parameter expansion,
1676command substitution,
1677arithmetic expansion
1678and quote removal.
1679.Pp
1680The allowed expressions are a subset of C expressions,
1681summarized below.
1682.Bl -tag -width "Variables" -offset indent
1683.It Values
1684All values are of type
1685.Ft intmax_t .
1686.It Constants
1687Decimal, octal (starting with
1688.Li 0 )
1689and hexadecimal (starting with
1690.Li 0x )
1691integer constants.
1692.It Variables
1693Shell variables can be read and written
1694and contain integer constants.
1695.It Unary operators
1696.Li "! ~ + -"
1697.It Binary operators
1698.Li "* / % + - << >> < <= > >= == != & ^ | && ||"
1699.It Assignment operators
1700.Li "= += -= *= /= %= <<= >>= &= ^= |="
1701.It Conditional operator
1702.Li "? :"
1703.El
1704.Pp
1705The result of the expression is substituted in decimal.
1706.Ss White Space Splitting (Field Splitting)
1707In certain contexts,
1708after parameter expansion, command substitution, and
1709arithmetic expansion the shell scans the results of
1710expansions and substitutions that did not occur in double-quotes for
1711field splitting and multiple fields can result.
1712.Pp
1713Characters in
1714.Va IFS
1715that are whitespace
1716.Po
1717.Aq space ,
1718.Aq tab ,
1719and
1720.Aq newline
1721.Pc
1722are treated differently from other characters in
1723.Va IFS .
1724.Pp
1725Whitespace in
1726.Va IFS
1727at the beginning or end of a word is discarded.
1728.Pp
1729Subsequently, a field is delimited by either
1730.Bl -enum
1731.It
1732a non-whitespace character in
1733.Va IFS
1734with any whitespace in
1735.Va IFS
1736surrounding it, or
1737.It
1738one or more whitespace characters in
1739.Va IFS .
1740.El
1741.Pp
1742If a word ends with a non-whitespace character in
1743.Va IFS ,
1744there is no empty field after this character.
1745.Pp
1746If no field is delimited, the word is discarded.
1747In particular, if a word consists solely of an unquoted substitution
1748and the result of the substitution is null,
1749it is removed by field splitting even if
1750.Va IFS
1751is null.
1752.Ss Pathname Expansion (File Name Generation)
1753Unless the
1754.Fl f
1755option is set,
1756file name generation is performed
1757after word splitting is complete.
1758Each word is
1759viewed as a series of patterns, separated by slashes.
1760The
1761process of expansion replaces the word with the names of
1762all existing files whose names can be formed by replacing
1763each pattern with a string that matches the specified pattern.
1764There are two restrictions on this: first, a pattern cannot match
1765a string containing a slash, and second,
1766a pattern cannot match a string starting with a period
1767unless the first character of the pattern is a period.
1768The next section describes the patterns used for
1769Pathname Expansion,
1770the four varieties of parameter expansion for substring processing and the
1771.Ic case
1772command.
1773.Ss Shell Patterns
1774A pattern consists of normal characters, which match themselves,
1775and meta-characters.
1776The meta-characters are
1777.Ql * ,
1778.Ql \&? ,
1779and
1780.Ql \&[ .
1781These characters lose their special meanings if they are quoted.
1782When command or variable substitution is performed and the dollar sign
1783or back quotes are not double-quoted, the value of the
1784variable or the output of the command is scanned for these
1785characters and they are turned into meta-characters.
1786.Pp
1787An asterisk
1788.Pq Ql *
1789matches any string of characters.
1790A question mark
1791.Pq Ql \&?
1792matches any single character.
1793A left bracket
1794.Pq Ql \&[
1795introduces a character class.
1796The end of the character class is indicated by a
1797.Ql \&] ;
1798if the
1799.Ql \&]
1800is missing then the
1801.Ql \&[
1802matches a
1803.Ql \&[
1804rather than introducing a character class.
1805A character class matches any of the characters between the square brackets.
1806A locale-dependent range of characters may be specified using a minus sign.
1807A named class of characters (see
1808.Xr wctype 3 )
1809may be specified by surrounding the name with
1810.Ql \&[:
1811and
1812.Ql :\&] .
1813For example,
1814.Ql \&[\&[:alpha:\&]\&]
1815is a shell pattern that matches a single letter.
1816The character class may be complemented by making an exclamation point
1817.Pq Ql !\&
1818the first character of the character class.
1819A caret
1820.Pq Ql ^
1821has the same effect but is non-standard.
1822.Pp
1823To include a
1824.Ql \&]
1825in a character class, make it the first character listed
1826(after the
1827.Ql \&!
1828or
1829.Ql ^ ,
1830if any).
1831To include a
1832.Ql - ,
1833make it the first or last character listed.
1834.Ss Built-in Commands
1835This section lists the built-in commands.
1836.Bl -tag -width indent
1837.It Ic \&:
1838A null command that returns a 0 (true) exit value.
1839.It Ic \&. Ar file
1840The commands in the specified file are read and executed by the shell.
1841The
1842.Ic return
1843command may be used to return to the
1844.Ic \&.
1845command's caller.
1846If
1847.Ar file
1848contains any
1849.Ql /
1850characters, it is used as is.
1851Otherwise, the shell searches the
1852.Va PATH
1853for the file.
1854If it is not found in the
1855.Va PATH ,
1856it is sought in the current working directory.
1857.It Ic \&[
1858A built-in equivalent of
1859.Xr test 1 .
1860.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc ... Oc
1861If
1862.Ar name Ns = Ns Ar string
1863is specified, the shell defines the alias
1864.Ar name
1865with value
1866.Ar string .
1867If just
1868.Ar name
1869is specified, the value of the alias
1870.Ar name
1871is printed.
1872With no arguments, the
1873.Ic alias
1874built-in command prints the names and values of all defined aliases
1875(see
1876.Ic unalias ) .
1877Alias values are written with appropriate quoting so that they are
1878suitable for re-input to the shell.
1879Also see the
1880.Sx Aliases
1881subsection.
1882.It Ic bg Op Ar job ...
1883Continue the specified jobs
1884(or the current job if no jobs are given)
1885in the background.
1886.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc
1887List or alter key bindings for the line editor.
1888This command is documented in
1889.Xr editrc 5 .
1890.It Ic break Op Ar num
1891See the
1892.Sx Flow-Control Constructs
1893subsection.
1894.It Ic builtin Ar cmd Op Ar arg ...
1895Execute the specified built-in command,
1896.Ar cmd .
1897This is useful when the user wishes to override a shell function
1898with the same name as a built-in command.
1899.It Ic cd Oo Fl L | P Oc Oo Fl e Oc Op Ar directory
1900Switch to the specified
1901.Ar directory ,
1902or to the directory specified in the
1903.Va HOME
1904environment variable if no
1905.Ar directory
1906is specified.
1907If
1908.Ar directory
1909does not begin with
1910.Pa / , \&. ,
1911or
1912.Pa .. ,
1913then the directories listed in the
1914.Va CDPATH
1915variable will be
1916searched for the specified
1917.Ar directory .
1918If
1919.Va CDPATH
1920is unset, the current directory is searched.
1921The format of
1922.Va CDPATH
1923is the same as that of
1924.Va PATH .
1925In an interactive shell,
1926the
1927.Ic cd
1928command will print out the name of the directory
1929that it actually switched to
1930if this is different from the name that the user gave.
1931These may be different either because the
1932.Va CDPATH
1933mechanism was used or because a symbolic link was crossed.
1934.Pp
1935If the
1936.Fl P
1937option is specified,
1938.Pa ..
1939is handled physically and symbolic links are resolved before
1940.Pa ..
1941components are processed.
1942If the
1943.Fl L
1944option is specified,
1945.Pa ..
1946is handled logically.
1947This is the default.
1948.Pp
1949The
1950.Fl e
1951option causes
1952.Ic cd
1953to return exit status 1 if the full pathname of the new directory
1954cannot be determined reliably or at all.
1955Normally this is not considered an error,
1956although a warning is printed.
1957.It Ic chdir
1958A synonym for the
1959.Ic cd
1960built-in command.
1961.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ...
1962.It Ic command Oo Fl p Oc Fl v Ar utility
1963.It Ic command Oo Fl p Oc Fl V Ar utility
1964The first form of invocation executes the specified
1965.Ar utility ,
1966ignoring shell functions in the search.
1967If
1968.Ar utility
1969is a special builtin,
1970it is executed as if it were a regular builtin.
1971.Pp
1972If the
1973.Fl p
1974option is specified, the command search is performed using a
1975default value of
1976.Va PATH
1977that is guaranteed to find all of the standard utilities.
1978.Pp
1979If the
1980.Fl v
1981option is specified,
1982.Ar utility
1983is not executed but a description of its interpretation by the shell is
1984printed.
1985For ordinary commands the output is the path name; for shell built-in
1986commands, shell functions and keywords only the name is written.
1987Aliases are printed as
1988.Dq Ic alias Ar name Ns = Ns Ar value .
1989.Pp
1990The
1991.Fl V
1992option is identical to
1993.Fl v
1994except for the output.
1995It prints
1996.Dq Ar utility Ic is Ar description
1997where
1998.Ar description
1999is either
2000the path name to
2001.Ar utility ,
2002a special shell builtin,
2003a shell builtin,
2004a shell function,
2005a shell keyword
2006or
2007an alias for
2008.Ar value .
2009.It Ic continue Op Ar num
2010See the
2011.Sx Flow-Control Constructs
2012subsection.
2013.It Ic echo Oo Fl e | n Oc Op Ar string ...
2014Print a space-separated list of the arguments to the standard output
2015and append a newline character.
2016.Bl -tag -width indent
2017.It Fl n
2018Suppress the output of the trailing newline.
2019.It Fl e
2020Process C-style backslash escape sequences.
2021The
2022.Ic echo
2023command understands the following character escapes:
2024.Bl -tag -width indent
2025.It \ea
2026Alert (ring the terminal bell)
2027.It \eb
2028Backspace
2029.It \ec
2030Suppress the trailing newline (this has the side-effect of truncating the
2031line if it is not the last character)
2032.It \ee
2033The ESC character
2034.Tn ( ASCII
20350x1b)
2036.It \ef
2037Formfeed
2038.It \en
2039Newline
2040.It \er
2041Carriage return
2042.It \et
2043Horizontal tab
2044.It \ev
2045Vertical tab
2046.It \e\e
2047Literal backslash
2048.It \e0nnn
2049(Zero) The character whose octal value is
2050.Ar nnn
2051.El
2052.Pp
2053If
2054.Ar string
2055is not enclosed in quotes then the backslash itself must be escaped
2056with a backslash to protect it from the shell.
2057For example
2058.Bd -literal -offset indent
2059$ echo -e "a\evb"
2060a
2061 b
2062$ echo -e a\e\evb
2063a
2064 b
2065$ echo -e "a\e\eb"
2066a\eb
2067$ echo -e a\e\e\e\eb
2068a\eb
2069.Ed
2070.El
2071.Pp
2072Only one of the
2073.Fl e
2074and
2075.Fl n
2076options may be specified.
2077.It Ic eval Ar string ...
2078Concatenate all the arguments with spaces.
2079Then re-parse and execute the command.
2080.It Ic exec Op Ar command Op arg ...
2081Unless
2082.Ar command
2083is omitted,
2084the shell process is replaced with the specified program
2085(which must be a real program, not a shell built-in command or function).
2086Any redirections on the
2087.Ic exec
2088command are marked as permanent,
2089so that they are not undone when the
2090.Ic exec
2091command finishes.
2092.It Ic exit Op Ar exitstatus
2093Terminate the shell process.
2094If
2095.Ar exitstatus
2096is given
2097it is used as the exit status of the shell.
2098Otherwise, if the shell is executing an
2099.Cm EXIT
2100trap, the exit status of the last command before the trap is used;
2101if the shell is executing a trap for a signal,
2102the shell exits by resending the signal to itself.
2103Otherwise, the exit status of the preceding command is used.
2104The exit status should be an integer between 0 and 255.
2105.It Ic export Ar name ...
2106.It Ic export Op Fl p
2107The specified names are exported so that they will
2108appear in the environment of subsequent commands.
2109The only way to un-export a variable is to
2110.Ic unset
2111it.
2112The shell allows the value of a variable to be set
2113at the same time as it is exported by writing
2114.Pp
2115.D1 Ic export Ar name Ns = Ns Ar value
2116.Pp
2117With no arguments the
2118.Ic export
2119command lists the names
2120of all exported variables.
2121If the
2122.Fl p
2123option is specified, the exported variables are printed as
2124.Dq Ic export Ar name Ns = Ns Ar value
2125lines, suitable for re-input to the shell.
2126.It Ic false
2127A null command that returns a non-zero (false) exit value.
2128.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last
2129.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last
2130.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first
2131The
2132.Ic fc
2133built-in command lists, or edits and re-executes,
2134commands previously entered to an interactive shell.
2135.Bl -tag -width indent
2136.It Fl e Ar editor
2137Use the editor named by
2138.Ar editor
2139to edit the commands.
2140The
2141.Ar editor
2142string is a command name,
2143subject to search via the
2144.Va PATH
2145variable.
2146The value in the
2147.Va FCEDIT
2148variable is used as a default when
2149.Fl e
2150is not specified.
2151If
2152.Va FCEDIT
2153is null or unset, the value of the
2154.Va EDITOR
2155variable is used.
2156If
2157.Va EDITOR
2158is null or unset,
2159.Xr ed 1
2160is used as the editor.
2161.It Fl l No (ell)
2162List the commands rather than invoking
2163an editor on them.
2164The commands are written in the
2165sequence indicated by the
2166.Ar first
2167and
2168.Ar last
2169operands, as affected by
2170.Fl r ,
2171with each command preceded by the command number.
2172.It Fl n
2173Suppress command numbers when listing with
2174.Fl l .
2175.It Fl r
2176Reverse the order of the commands listed
2177(with
2178.Fl l )
2179or edited
2180(with neither
2181.Fl l
2182nor
2183.Fl s ) .
2184.It Fl s
2185Re-execute the command without invoking an editor.
2186.It Ar first
2187.It Ar last
2188Select the commands to list or edit.
2189The number of previous commands that can be accessed
2190are determined by the value of the
2191.Va HISTSIZE
2192variable.
2193The value of
2194.Ar first
2195or
2196.Ar last
2197or both are one of the following:
2198.Bl -tag -width indent
2199.It Oo Cm + Oc Ns Ar num
2200A positive number representing a command number;
2201command numbers can be displayed with the
2202.Fl l
2203option.
2204.It Fl Ar num
2205A negative decimal number representing the
2206command that was executed
2207.Ar num
2208of
2209commands previously.
2210For example, \-1 is the immediately previous command.
2211.It Ar string
2212A string indicating the most recently entered command
2213that begins with that string.
2214If the
2215.Ar old Ns = Ns Ar new
2216operand is not also specified with
2217.Fl s ,
2218the string form of the first operand cannot contain an embedded equal sign.
2219.El
2220.El
2221.Pp
2222The following variables affect the execution of
2223.Ic fc :
2224.Bl -tag -width ".Va HISTSIZE"
2225.It Va FCEDIT
2226Name of the editor to use for history editing.
2227.It Va HISTSIZE
2228The number of previous commands that are accessible.
2229.El
2230.It Ic fg Op Ar job
2231Move the specified
2232.Ar job
2233or the current job to the foreground.
2234.It Ic getopts Ar optstring var
2235The
2236.Tn POSIX
2237.Ic getopts
2238command.
2239The
2240.Ic getopts
2241command deprecates the older
2242.Xr getopt 1
2243command.
2244The first argument should be a series of letters, each possibly
2245followed by a colon which indicates that the option takes an argument.
2246The specified variable is set to the parsed option.
2247The index of
2248the next argument is placed into the shell variable
2249.Va OPTIND .
2250If an option takes an argument, it is placed into the shell variable
2251.Va OPTARG .
2252If an invalid option is encountered,
2253.Ar var
2254is set to
2255.Ql \&? .
2256It returns a false value (1) when it encounters the end of the options.
2257.It Ic hash Oo Fl rv Oc Op Ar command ...
2258The shell maintains a hash table which remembers the locations of commands.
2259With no arguments whatsoever, the
2260.Ic hash
2261command prints out the contents of this table.
2262.Pp
2263With arguments, the
2264.Ic hash
2265command removes each specified
2266.Ar command
2267from the hash table (unless they are functions) and then locates it.
2268With the
2269.Fl v
2270option,
2271.Ic hash
2272prints the locations of the commands as it finds them.
2273The
2274.Fl r
2275option causes the
2276.Ic hash
2277command to delete all the entries in the hash table except for functions.
2278.It Ic jobid Op Ar job
2279Print the process IDs of the processes in the specified
2280.Ar job .
2281If the
2282.Ar job
2283argument is omitted, use the current job.
2284.It Ic jobs Oo Fl lps Oc Op Ar job ...
2285Print information about the specified jobs, or all jobs if no
2286.Ar job
2287argument is given.
2288The information printed includes job ID, status and command name.
2289.Pp
2290If the
2291.Fl l
2292option is specified, the PID of each job is also printed.
2293If the
2294.Fl p
2295option is specified, only the process IDs for the process group leaders
2296are printed, one per line.
2297If the
2298.Fl s
2299option is specified, only the PIDs of the job commands are printed, one per
2300line.
2301.It Ic kill
2302A built-in equivalent of
2303.Xr kill 1
2304that additionally supports sending signals to jobs.
2305.It Ic local Oo Ar variable ... Oc Op Fl
2306See the
2307.Sx Functions
2308subsection.
2309.It Ic printf
2310A built-in equivalent of
2311.Xr printf 1 .
2312.It Ic pwd Op Fl L | P
2313Print the path of the current directory.
2314The built-in command may
2315differ from the program of the same name because the
2316built-in command remembers what the current directory
2317is rather than recomputing it each time.
2318This makes
2319it faster.
2320However, if the current directory is
2321renamed,
2322the built-in version of
2323.Xr pwd 1
2324will continue to print the old name for the directory.
2325.Pp
2326If the
2327.Fl P
2328option is specified, symbolic links are resolved.
2329If the
2330.Fl L
2331option is specified, the shell's notion of the current directory
2332is printed (symbolic links are not resolved).
2333This is the default.
2334.It Ic read Oo Fl p Ar prompt Oc Oo
2335.Fl t Ar timeout Oc Oo Fl er Oc Ar variable ...
2336The
2337.Ar prompt
2338is printed if the
2339.Fl p
2340option is specified
2341and the standard input is a terminal.
2342Then a line is
2343read from the standard input.
2344The trailing newline
2345is deleted from the line and the line is split as
2346described in the section on
2347.Sx White Space Splitting (Field Splitting)
2348above, and
2349the pieces are assigned to the variables in order.
2350If there are more pieces than variables, the remaining
2351pieces (along with the characters in
2352.Va IFS
2353that separated them)
2354are assigned to the last variable.
2355If there are more variables than pieces, the remaining
2356variables are assigned the null string.
2357.Pp
2358Backslashes are treated specially, unless the
2359.Fl r
2360option is
2361specified.
2362If a backslash is followed by
2363a newline, the backslash and the newline will be
2364deleted.
2365If a backslash is followed by any other
2366character, the backslash will be deleted and the following
2367character will be treated as though it were not in
2368.Va IFS ,
2369even if it is.
2370.Pp
2371If the
2372.Fl t
2373option is specified and the
2374.Ar timeout
2375elapses before a complete line of input is supplied,
2376the
2377.Ic read
2378command will return an exit status as if terminated by
2379.Dv SIGALRM
2380without assigning any values.
2381The
2382.Ar timeout
2383value may optionally be followed by one of
2384.Ql s ,
2385.Ql m
2386or
2387.Ql h
2388to explicitly specify seconds, minutes or hours.
2389If none is supplied,
2390.Ql s
2391is assumed.
2392.Pp
2393The
2394.Fl e
2395option exists only for backward compatibility with older scripts.
2396.Pp
2397The exit status is 0 on success, 1 on end of file,
2398between 2 and 128 if an error occurs
2399and greater than 128 if a trapped signal interrupts
2400.Ic read .
2401.It Ic readonly Oo Fl p Oc Op Ar name ...
2402Each specified
2403.Ar name
2404is marked as read only,
2405so that it cannot be subsequently modified or unset.
2406The shell allows the value of a variable to be set
2407at the same time as it is marked read only
2408by using the following form:
2409.Pp
2410.D1 Ic readonly Ar name Ns = Ns Ar value
2411.Pp
2412With no arguments the
2413.Ic readonly
2414command lists the names of all read only variables.
2415If the
2416.Fl p
2417option is specified, the read-only variables are printed as
2418.Dq Ic readonly Ar name Ns = Ns Ar value
2419lines, suitable for re-input to the shell.
2420.It Ic return Op Ar exitstatus
2421See the
2422.Sx Functions
2423subsection.
2424.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo
2425.Fl c Ar string Oc Op Fl - Ar arg ...
2426The
2427.Ic set
2428command performs three different functions:
2429.Bl -item
2430.It
2431With no arguments, it lists the values of all shell variables.
2432.It
2433If options are given,
2434either in short form or using the long
2435.Dq Fl /+o Ar longname
2436form,
2437it sets or clears the specified options as described in the section called
2438.Sx Argument List Processing .
2439.It
2440If the
2441.Dq Fl -
2442option is specified,
2443.Ic set
2444will replace the shell's positional parameters with the subsequent
2445arguments.
2446If no arguments follow the
2447.Dq Fl -
2448option,
2449all the positional parameters will be cleared,
2450which is equivalent to executing the command
2451.Dq Li "shift $#" .
2452The
2453.Dq Fl -
2454flag may be omitted when specifying arguments to be used
2455as positional replacement parameters.
2456This is not recommended,
2457because the first argument may begin with a dash
2458.Pq Ql -
2459or a plus
2460.Pq Ql + ,
2461which the
2462.Ic set
2463command will interpret as a request to enable or disable options.
2464.El
2465.It Ic setvar Ar variable value
2466Assigns the specified
2467.Ar value
2468to the specified
2469.Ar variable .
2470The
2471.Ic setvar
2472command is intended to be used in functions that
2473assign values to variables whose names are passed as parameters.
2474In general it is better to write
2475.Dq Ar variable Ns = Ns Ar value
2476rather than using
2477.Ic setvar .
2478.It Ic shift Op Ar n
2479Shift the positional parameters
2480.Ar n
2481times, or once if
2482.Ar n
2483is not specified.
2484A shift sets the value of
2485.Li $1
2486to the value of
2487.Li $2 ,
2488the value of
2489.Li $2
2490to the value of
2491.Li $3 ,
2492and so on,
2493decreasing the value of
2494.Li $#
2495by one.
2496If there are zero positional parameters, shifting does not do anything.
2497.It Ic test
2498A built-in equivalent of
2499.Xr test 1 .
2500.It Ic times
2501Print the amount of time spent executing the shell process and its children.
2502The first output line shows the user and system times for the shell process
2503itself, the second one contains the user and system times for the
2504children.
2505.It Ic trap Oo Ar action Oc Ar signal ...
2506.It Ic trap Fl l
2507Cause the shell to parse and execute
2508.Ar action
2509when any specified
2510.Ar signal
2511is received.
2512The signals are specified by name or number.
2513In addition, the pseudo-signal
2514.Cm EXIT
2515may be used to specify an
2516.Ar action
2517that is performed when the shell terminates.
2518The
2519.Ar action
2520may be an empty string or a dash
2521.Pq Ql - ;
2522the former causes the specified signal to be ignored
2523and the latter causes the default action to be taken.
2524Omitting the
2525.Ar action
2526is another way to request the default action, for compatibility reasons this
2527usage is not recommended though.
2528In a subshell or utility environment,
2529the shell resets trapped (but not ignored) signals to the default action.
2530The
2531.Ic trap
2532command has no effect on signals that were ignored on entry to the shell.
2533.Pp
2534Option
2535.Fl l
2536causes the
2537.Ic trap
2538command to display a list of valid signal names.
2539.It Ic true
2540A null command that returns a 0 (true) exit value.
2541.It Ic type Op Ar name ...
2542Interpret each
2543.Ar name
2544as a command and print the resolution of the command search.
2545Possible resolutions are:
2546shell keyword, alias, special shell builtin, shell builtin, command,
2547tracked alias
2548and not found.
2549For aliases the alias expansion is printed;
2550for commands and tracked aliases
2551the complete pathname of the command is printed.
2552.It Ic ulimit Oo Fl HSabcdflmnpstuvw Oc Op Ar limit
2553Set or display resource limits (see
2554.Xr getrlimit 2 ) .
2555If
2556.Ar limit
2557is specified, the named resource will be set;
2558otherwise the current resource value will be displayed.
2559.Pp
2560If
2561.Fl H
2562is specified, the hard limits will be set or displayed.
2563While everybody is allowed to reduce a hard limit,
2564only the superuser can increase it.
2565The
2566.Fl S
2567option
2568specifies the soft limits instead.
2569When displaying limits,
2570only one of
2571.Fl S
2572or
2573.Fl H
2574can be given.
2575The default is to display the soft limits,
2576and to set both the hard and the soft limits.
2577.Pp
2578Option
2579.Fl a
2580causes the
2581.Ic ulimit
2582command to display all resources.
2583The parameter
2584.Ar limit
2585is not acceptable in this mode.
2586.Pp
2587The remaining options specify which resource value is to be
2588displayed or modified.
2589They are mutually exclusive.
2590.Bl -tag -width indent
2591.It Fl b Ar sbsize
2592The maximum size of socket buffer usage, in bytes.
2593.It Fl c Ar coredumpsize
2594The maximal size of core dump files, in 512-byte blocks.
2595.It Fl d Ar datasize
2596The maximal size of the data segment of a process, in kilobytes.
2597.It Fl f Ar filesize
2598The maximal size of a file, in 512-byte blocks.
2599.It Fl l Ar lockedmem
2600The maximal size of memory that can be locked by a process, in
2601kilobytes.
2602.It Fl m Ar memoryuse
2603The maximal resident set size of a process, in kilobytes.
2604.It Fl n Ar nofiles
2605The maximal number of descriptors that could be opened by a process.
2606.It Fl p Ar pseudoterminals
2607The maximal number of pseudo-terminals for this user ID.
2608.It Fl s Ar stacksize
2609The maximal size of the stack segment, in kilobytes.
2610.It Fl t Ar time
2611The maximal amount of CPU time to be used by each process, in seconds.
2612.It Fl u Ar userproc
2613The maximal number of simultaneous processes for this user ID.
2614.It Fl v Ar virtualmem
2615The maximal virtual size of a process, in kilobytes.
2616.It Fl w Ar swapuse
2617The maximum amount of swap space reserved or used for this user ID,
2618in kilobytes.
2619.El
2620.It Ic umask Oo Fl S Oc Op Ar mask
2621Set the file creation mask (see
2622.Xr umask 2 )
2623to the octal or symbolic (see
2624.Xr chmod 1 )
2625value specified by
2626.Ar mask .
2627If the argument is omitted, the current mask value is printed.
2628If the
2629.Fl S
2630option is specified, the output is symbolic, otherwise the output is octal.
2631.It Ic unalias Oo Fl a Oc Op Ar name ...
2632The specified alias names are removed.
2633If
2634.Fl a
2635is specified, all aliases are removed.
2636.It Ic unset Oo Fl fv Oc Ar name ...
2637The specified variables or functions are unset and unexported.
2638If the
2639.Fl v
2640option is specified or no options are given, the
2641.Ar name
2642arguments are treated as variable names.
2643If the
2644.Fl f
2645option is specified, the
2646.Ar name
2647arguments are treated as function names.
2648.It Ic wait Op Ar job ...
2649Wait for each specified
2650.Ar job
2651to complete and return the exit status of the last process in the
2652last specified
2653.Ar job .
2654If any
2655.Ar job
2656specified is unknown to the shell, it is treated as if it
2657were a known job that exited with exit status 127.
2658If no operands are given, wait for all jobs to complete
2659and return an exit status of zero.
2660.El
2661.Ss Commandline Editing
2662When
2663.Nm
2664is being used interactively from a terminal, the current command
2665and the command history
2666(see
2667.Ic fc
2668in
2669.Sx Built-in Commands )
2670can be edited using
2671.Nm vi Ns -mode
2672command line editing.
2673This mode uses commands similar
2674to a subset of those described in the
2675.Xr vi 1
2676man page.
2677The command
2678.Dq Li "set -o vi"
2679(or
2680.Dq Li "set -V" )
2681enables
2682.Nm vi Ns -mode
2683editing and places
2684.Nm
2685into
2686.Nm vi
2687insert mode.
2688With
2689.Nm vi Ns -mode
2690enabled,
2691.Nm
2692can be switched between insert mode and command mode by typing
2693.Aq ESC .
2694Hitting
2695.Aq return
2696while in command mode will pass the line to the shell.
2697.Pp
2698Similarly, the
2699.Dq Li "set -o emacs"
2700(or
2701.Dq Li "set -E" )
2702command can be used to enable a subset of
2703.Nm emacs Ns -style
2704command line editing features.
2705.Sh ENVIRONMENT
2706The following environment variables affect the execution of
2707.Nm :
2708.Bl -tag -width ".Ev LANGXXXXXX"
2709.It Ev ENV
2710Initialization file for interactive shells.
2711.It Ev LANG , Ev LC_*
2712Locale settings.
2713These are inherited by children of the shell,
2714and is used in a limited manner by the shell itself.
2715.It Ev PWD
2716An absolute pathname for the current directory,
2717possibly containing symbolic links.
2718This is used and updated by the shell.
2719.It Ev TERM
2720The default terminal setting for the shell.
2721This is inherited by children of the shell, and is used in the history
2722editing modes.
2723.El
2724.Pp
2725Additionally, all environment variables are turned into shell variables
2726at startup,
2727which may affect the shell as described under
2728.Sx Special Variables .
2729.Sh FILES
2730.Bl -tag -width "/etc/suid_profileXX" -compact
2731.It Pa ~/.profile
2732User's login profile.
2733.It Pa /etc/profile
2734System login profile.
2735.It Pa /etc/shells
2736Shell database.
2737.It Pa /etc/suid_profile
2738Privileged shell profile.
2739.El
2740.Sh EXIT STATUS
2741Errors that are detected by the shell, such as a syntax error, will
2742cause the shell to exit with a non-zero exit status.
2743If the shell is not an interactive shell, the execution of the shell
2744file will be aborted.
2745Otherwise the shell will return the exit status of the last command
2746executed, or if the
2747.Ic exit
2748builtin is used with a numeric argument, it
2749will return the argument.
2750.Sh SEE ALSO
2751.Xr builtin 1 ,
2752.Xr chsh 1 ,
2753.Xr echo 1 ,
2754.Xr ed 1 ,
2755.Xr emacs 1 ,
2756.Xr kill 1 ,
2757.Xr printf 1 ,
2758.Xr pwd 1 ,
2759.Xr test 1 ,
2760.Xr vi 1 ,
2761.Xr execve 2 ,
2762.Xr getrlimit 2 ,
2763.Xr umask 2 ,
2764.Xr wctype 3 ,
2765.Xr editrc 5 ,
2766.Xr shells 5
2767.Sh HISTORY
2768A
2769.Nm
2770command, the Thompson shell, appeared in
2771.At v1 .
2772It was superseded in
2773.At v7
2774by the Bourne shell, which inherited the name
2775.Nm .
2776.Pp
2777This version of
2778.Nm
2779was rewritten in 1989 under the
2780.Bx
2781license after the Bourne shell from
2782.At V.4 .
2783.Sh AUTHORS
2784This version of
2785.Nm
2786was originally written by
2787.An Kenneth Almquist .
2788.Sh BUGS
2789The
2790.Nm
2791utility does not recognize multibyte characters other than UTF-8.
2792Splitting using
2793.Va IFS
2794and the line editing library
2795.Xr editline 3
2796do not recognize multibyte characters.
2797