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