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