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