sh: Save/restore changed variables in optimized command substitution.
[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
32931063 37.\" $FreeBSD: src/bin/sh/sh.1,v 1.168 2011/06/12 23:06:04 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
32931063 1550if they are the only command in a command substitution.
984263bc
MD
1551.Ss Arithmetic Expansion
1552Arithmetic expansion provides a mechanism for evaluating an arithmetic
1553expression and substituting its value.
1554The format for arithmetic expansion is as follows:
984263bc 1555.Pp
99512ac4
PA
1556.D1 Li $(( Ns Ar expression Ns Li ))
1557.Pp
1558The
1559.Ar expression
1560is treated as if it were in double-quotes, except
10185af4
PA
1561that a double-quote inside the expression is not treated specially.
1562The
99512ac4
PA
1563shell expands all tokens in the
1564.Ar expression
1565for parameter expansion,
1566command substitution,
1567arithmetic expansion
1568and quote removal.
1569.Pp
1570The allowed expressions are a subset of C expressions,
1571summarized below.
1572.Bl -tag -width "Variables" -offset indent
1573.It Values
1574All values are of type
1575.Ft intmax_t .
1576.It Constants
1577Decimal, octal (starting with
1578.Li 0 )
1579and hexadecimal (starting with
1580.Li 0x )
1581integer constants.
1582.It Variables
1583Shell variables can be read and written
1584and contain integer constants.
1585.It Unary operators
1586.Li "! ~ + -"
1587.It Binary operators
1588.Li "* / % + - << >> < <= > >= == != & ^ | && ||"
1589.It Assignment operators
1590.Li "= += -= *= /= %= <<= >>= &= ^= |="
1591.It Conditional operator
1592.Li "? :"
1593.El
984263bc 1594.Pp
99512ac4 1595The result of the expression is substituted in decimal.
984263bc
MD
1596.Ss White Space Splitting (Field Splitting)
1597After parameter expansion, command substitution, and
1598arithmetic expansion the shell scans the results of
1599expansions and substitutions that did not occur in double-quotes for
1600field splitting and multiple fields can result.
1601.Pp
1602The shell treats each character of the
99512ac4
PA
1603.Va IFS
1604variable as a delimiter and uses
984263bc
MD
1605the delimiters to split the results of parameter expansion and command
1606substitution into fields.
1607.Ss Pathname Expansion (File Name Generation)
1608Unless the
1609.Fl f
1610option is set,
1611file name generation is performed
10185af4
PA
1612after word splitting is complete.
1613Each word is
1614viewed as a series of patterns, separated by slashes.
1615The
984263bc
MD
1616process of expansion replaces the word with the names of
1617all existing files whose names can be formed by replacing
1618each pattern with a string that matches the specified pattern.
1619There are two restrictions on this: first, a pattern cannot match
1620a string containing a slash, and second,
1621a pattern cannot match a string starting with a period
1622unless the first character of the pattern is a period.
1623The next section describes the patterns used for both
1624Pathname Expansion and the
1625.Ic case
1626command.
1627.Ss Shell Patterns
1628A pattern consists of normal characters, which match themselves,
1629and meta-characters.
1630The meta-characters are
cca2c150
TN
1631.Ql \&! ,
1632.Ql * ,
1633.Ql \&? ,
984263bc 1634and
cca2c150 1635.Ql \&[ .
984263bc
MD
1636These characters lose their special meanings if they are quoted.
1637When command or variable substitution is performed and the dollar sign
1638or back quotes are not double-quoted, the value of the
1639variable or the output of the command is scanned for these
1640characters and they are turned into meta-characters.
1641.Pp
1642An asterisk
10185af4 1643.Pq Ql *
984263bc
MD
1644matches any string of characters.
1645A question mark
10185af4 1646.Pq Ql \&?
984263bc
MD
1647matches any single character.
1648A left bracket
cca2c150 1649.Pq Ql \&[
984263bc
MD
1650introduces a character class.
1651The end of the character class is indicated by a
cca2c150 1652.Ql \&] ;
984263bc 1653if the
cca2c150 1654.Ql \&]
984263bc 1655is missing then the
cca2c150 1656.Ql \&[
984263bc 1657matches a
cca2c150 1658.Ql \&[
984263bc
MD
1659rather than introducing a character class.
1660A character class matches any of the characters between the square brackets.
1661A range of characters may be specified using a minus sign.
1662The character class may be complemented by making an exclamation point
10185af4 1663.Pq Ql !\&
bb9a009b 1664or the caret
10185af4 1665.Pq Ql ^\&
984263bc
MD
1666the first character of the character class.
1667.Pp
1668To include a
cca2c150 1669.Ql \&]
984263bc
MD
1670in a character class, make it the first character listed
1671(after the
cca2c150 1672.Ql \&!
bb9a009b 1673or
cca2c150 1674.Ql \&^ ,
984263bc
MD
1675if any).
1676To include a
cca2c150 1677.Ql - ,
984263bc
MD
1678make it the first or last character listed.
1679.Ss Built-in Commands
99512ac4 1680This section lists the built-in commands.
984263bc
MD
1681.Bl -tag -width indent
1682.It Ic \&:
1683A null command that returns a 0 (true) exit value.
1684.It Ic \&. Ar file
1685The commands in the specified file are read and executed by the shell.
10185af4
PA
1686The
1687.Ic return
1688command may be used to return to the
1689.Ic \&.
1690command's caller.
984263bc
MD
1691If
1692.Ar file
1693contains any
cca2c150 1694.Ql /
10185af4
PA
1695characters, it is used as is.
1696Otherwise, the shell searches the
99512ac4 1697.Va PATH
10185af4
PA
1698for the file.
1699If it is not found in the
99512ac4 1700.Va PATH ,
984263bc 1701it is sought in the current working directory.
10185af4
PA
1702.It Ic \&[
1703A built-in equivalent of
1704.Xr test 1 .
1bd69ff1 1705.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc Ar ... Oc
984263bc
MD
1706If
1707.Ar name Ns = Ns Ar string
1708is specified, the shell defines the alias
1709.Ar name
1710with value
1711.Ar string .
1712If just
1713.Ar name
1714is specified, the value of the alias
1715.Ar name
1716is printed.
1717With no arguments, the
1718.Ic alias
1719built-in command prints the names and values of all defined aliases
1720(see
1721.Ic unalias ) .
1722Alias values are written with appropriate quoting so that they are
1723suitable for re-input to the shell.
10185af4
PA
1724Also see the
1725.Sx Aliases
1726subsection.
984263bc
MD
1727.It Ic bg Op Ar job ...
1728Continue the specified jobs
1729(or the current job if no jobs are given)
1730in the background.
99512ac4
PA
1731.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc
1732List or alter key bindings for the line editor.
1733This command is documented in
1734.Xr editrc 5 .
1735.It Ic break Op Ar num
1736See the
1737.Sx Flow-Control Constructs
1738subsection.
984263bc
MD
1739.It Ic builtin Ar cmd Op Ar arg ...
1740Execute the specified built-in command,
1741.Ar cmd .
1742This is useful when the user wishes to override a shell function
1743with the same name as a built-in command.
8c603ea4 1744.It Ic cd Oo Fl L | P Oc Oo Fl e Oc Op Ar directory
984263bc
MD
1745Switch to the specified
1746.Ar directory ,
1747or to the directory specified in the
99512ac4 1748.Va HOME
984263bc
MD
1749environment variable if no
1750.Ar directory
1751is specified.
1752If
1753.Ar directory
1754does not begin with
1755.Pa / , \&. ,
1756or
1757.Pa .. ,
1758then the directories listed in the
99512ac4 1759.Va CDPATH
984263bc
MD
1760variable will be
1761searched for the specified
1762.Ar directory .
1763If
99512ac4 1764.Va CDPATH
984263bc
MD
1765is unset, the current directory is searched.
1766The format of
99512ac4 1767.Va CDPATH
984263bc 1768is the same as that of
99512ac4 1769.Va PATH .
984263bc
MD
1770In an interactive shell,
1771the
1772.Ic cd
1773command will print out the name of the directory
1774that it actually switched to
1775if this is different from the name that the user gave.
1776These may be different either because the
99512ac4 1777.Va CDPATH
984263bc
MD
1778mechanism was used or because a symbolic link was crossed.
1779.Pp
1780If the
1781.Fl P
1782option is specified,
1783.Pa ..
1784is handled physically and symbolic links are resolved before
1785.Pa ..
1786components are processed.
1787If the
1788.Fl L
1789option is specified,
1790.Pa ..
1791is handled logically.
1792This is the default.
8c603ea4
PA
1793.Pp
1794The
1795.Fl e
1796option causes
1797.Ic cd
1798to return exit status 1 if the full pathname of the new directory
1799cannot be determined reliably or at all.
1800Normally this is not considered an error,
1801although a warning is printed.
984263bc
MD
1802.It Ic chdir
1803A synonym for the
1804.Ic cd
1805built-in command.
1806.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ...
99512ac4
PA
1807.It Ic command Oo Fl p Oc Fl v Ar utility
1808.It Ic command Oo Fl p Oc Fl V Ar utility
10185af4 1809The first form of invocation executes the specified
99512ac4
PA
1810.Ar utility ,
1811ignoring shell functions in the search.
1812If
984263bc 1813.Ar utility
99512ac4
PA
1814is a special builtin,
1815it is executed as if it were a regular builtin.
984263bc
MD
1816.Pp
1817If the
1818.Fl p
1819option is specified, the command search is performed using a
1820default value of
99512ac4 1821.Va PATH
984263bc 1822that is guaranteed to find all of the standard utilities.
10185af4
PA
1823.Pp
1824If the
1825.Fl v
1826option is specified,
1827.Ar utility
1828is not executed but a description of its interpretation by the shell is
1829printed.
1830For ordinary commands the output is the path name; for shell built-in
1831commands, shell functions and keywords only the name is written.
1832Aliases are printed as
1833.Dq Ic alias Ar name Ns = Ns Ar value .
1834.Pp
1835The
1836.Fl V
1837option is identical to
1838.Fl v
1839except for the output.
1840It prints
1841.Dq Ar utility Ic is Ar description
1842where
1843.Ar description
1844is either
1845the path name to
1846.Ar utility ,
99512ac4 1847a special shell builtin,
10185af4
PA
1848a shell builtin,
1849a shell function,
1850a shell keyword
1851or
1852an alias for
8e8ff7b0 1853.Ar value .
99512ac4
PA
1854.It Ic continue Op Ar num
1855See the
1856.Sx Flow-Control Constructs
1857subsection.
10185af4
PA
1858.It Ic echo Oo Fl e | n Oc Op Ar string ...
1859Print a space-separated list of the arguments to the standard output
1860and append a newline character.
984263bc
MD
1861.Bl -tag -width indent
1862.It Fl n
1863Suppress the output of the trailing newline.
1864.It Fl e
1865Process C-style backslash escape sequences.
99512ac4 1866The
984263bc 1867.Ic echo
99512ac4 1868command understands the following character escapes:
984263bc
MD
1869.Bl -tag -width indent
1870.It \ea
1871Alert (ring the terminal bell)
1872.It \eb
1873Backspace
1874.It \ec
1875Suppress the trailing newline (this has the side-effect of truncating the
1876line if it is not the last character)
1877.It \ee
99512ac4
PA
1878The ESC character
1879.Tn ( ASCII
18800x1b)
984263bc
MD
1881.It \ef
1882Formfeed
1883.It \en
1884Newline
1885.It \er
1886Carriage return
1887.It \et
1888Horizontal tab
1889.It \ev
1890Vertical tab
1891.It \e\e
1892Literal backslash
1893.It \e0nnn
99512ac4
PA
1894(Zero) The character whose octal value is
1895.Ar nnn
984263bc
MD
1896.El
1897.Pp
1898If
1899.Ar string
1900is not enclosed in quotes then the backslash itself must be escaped
10185af4
PA
1901with a backslash to protect it from the shell.
1902For example
984263bc
MD
1903.Bd -literal -offset indent
1904$ echo -e "a\evb"
1905a
1906 b
1907$ echo -e a\e\evb
1908a
1909 b
1910$ echo -e "a\e\eb"
1911a\eb
1912$ echo -e a\e\e\e\eb
1913a\eb
1914.Ed
1915.El
1916.Pp
1917Only one of the
1918.Fl e
1919and
1920.Fl n
1921options may be specified.
1922.It Ic eval Ar string ...
1923Concatenate all the arguments with spaces.
1924Then re-parse and execute the command.
1bd69ff1 1925.It Ic exec Op Ar command Op Ar arg ...
984263bc
MD
1926Unless
1927.Ar command
1928is omitted,
1929the shell process is replaced with the specified program
1930(which must be a real program, not a shell built-in command or function).
1931Any redirections on the
1932.Ic exec
1933command are marked as permanent,
1934so that they are not undone when the
1935.Ic exec
1936command finishes.
1937.It Ic exit Op Ar exitstatus
1938Terminate the shell process.
1939If
1940.Ar exitstatus
1941is given
1de90000
PA
1942it is used as the exit status of the shell.
1943Otherwise, if the shell is executing an
99512ac4
PA
1944.Cm EXIT
1945trap, the exit status of the last command before the trap is used;
1946if the shell is executing a trap for a signal,
1de90000
PA
1947the shell exits by resending the signal to itself.
1948Otherwise, the exit status of the preceding command is used.
99512ac4 1949The exit status should be an integer between 0 and 255.
10185af4
PA
1950.It Ic export Ar name ...
1951.It Ic export Op Fl p
984263bc
MD
1952The specified names are exported so that they will
1953appear in the environment of subsequent commands.
1954The only way to un-export a variable is to
1955.Ic unset
1956it.
1957The shell allows the value of a variable to be set
1958at the same time as it is exported by writing
984263bc 1959.Pp
99512ac4
PA
1960.D1 Ic export Ar name Ns = Ns Ar value
1961.Pp
1962With no arguments the
1963.Ic export
1964command lists the names
984263bc
MD
1965of all exported variables.
1966If the
1967.Fl p
1968option is specified, the exported variables are printed as
1969.Dq Ic export Ar name Ns = Ns Ar value
1970lines, suitable for re-input to the shell.
10185af4
PA
1971.It Ic false
1972A null command that returns a non-zero (false) exit value.
984263bc
MD
1973.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last
1974.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last
1975.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first
1976The
1977.Ic fc
1978built-in command lists, or edits and re-executes,
1979commands previously entered to an interactive shell.
1980.Bl -tag -width indent
1981.It Fl e Ar editor
1982Use the editor named by
1983.Ar editor
1984to edit the commands.
99512ac4
PA
1985The
1986.Ar editor
1987string is a command name,
984263bc 1988subject to search via the
99512ac4 1989.Va PATH
984263bc
MD
1990variable.
1991The value in the
99512ac4 1992.Va FCEDIT
984263bc
MD
1993variable is used as a default when
1994.Fl e
1995is not specified.
1996If
99512ac4 1997.Va FCEDIT
984263bc 1998is null or unset, the value of the
99512ac4 1999.Va EDITOR
984263bc
MD
2000variable is used.
2001If
99512ac4 2002.Va EDITOR
984263bc
MD
2003is null or unset,
2004.Xr ed 1
2005is used as the editor.
2006.It Fl l No (ell)
2007List the commands rather than invoking
10185af4
PA
2008an editor on them.
2009The commands are written in the
99512ac4
PA
2010sequence indicated by the
2011.Ar first
2012and
2013.Ar last
2014operands, as affected by
984263bc
MD
2015.Fl r ,
2016with each command preceded by the command number.
2017.It Fl n
2018Suppress command numbers when listing with
2019.Fl l .
2020.It Fl r
2021Reverse the order of the commands listed
2022(with
2023.Fl l )
2024or edited
2025(with neither
2026.Fl l
2027nor
2028.Fl s ) .
2029.It Fl s
2030Re-execute the command without invoking an editor.
2031.It Ar first
2032.It Ar last
2033Select the commands to list or edit.
2034The number of previous commands that can be accessed
2035are determined by the value of the
99512ac4 2036.Va HISTSIZE
984263bc
MD
2037variable.
2038The value of
2039.Ar first
2040or
2041.Ar last
2042or both are one of the following:
2043.Bl -tag -width indent
99512ac4 2044.It Oo Cm + Oc Ns Ar num
984263bc
MD
2045A positive number representing a command number;
2046command numbers can be displayed with the
2047.Fl l
2048option.
99512ac4 2049.It Fl Ar num
984263bc
MD
2050A negative decimal number representing the
2051command that was executed
2052.Ar num
2053of
2054commands previously.
99512ac4 2055For example, \-1 is the immediately previous command.
984263bc
MD
2056.It Ar string
2057A string indicating the most recently entered command
2058that begins with that string.
2059If the
99512ac4 2060.Ar old Ns = Ns Ar new
984263bc
MD
2061operand is not also specified with
2062.Fl s ,
2063the string form of the first operand cannot contain an embedded equal sign.
2064.El
2065.El
2066.Pp
99512ac4 2067The following variables affect the execution of
984263bc 2068.Ic fc :
99512ac4
PA
2069.Bl -tag -width ".Va HISTSIZE"
2070.It Va FCEDIT
10185af4 2071Name of the editor to use for history editing.
99512ac4 2072.It Va HISTSIZE
984263bc
MD
2073The number of previous commands that are accessible.
2074.El
2075.It Ic fg Op Ar job
2076Move the specified
2077.Ar job
2078or the current job to the foreground.
99512ac4
PA
2079.It Ic getopts Ar optstring var
2080The
2081.Tn POSIX
984263bc
MD
2082.Ic getopts
2083command.
2084The
2085.Ic getopts
2086command deprecates the older
2087.Xr getopt 1
2088command.
2089The first argument should be a series of letters, each possibly
2090followed by a colon which indicates that the option takes an argument.
10185af4
PA
2091The specified variable is set to the parsed option.
2092The index of
984263bc 2093the next argument is placed into the shell variable
99512ac4 2094.Va OPTIND .
984263bc 2095If an option takes an argument, it is placed into the shell variable
99512ac4 2096.Va OPTARG .
984263bc 2097If an invalid option is encountered,
99512ac4 2098.Ar var
984263bc 2099is set to
cca2c150 2100.Ql \&? .
984263bc
MD
2101It returns a false value (1) when it encounters the end of the options.
2102.It Ic hash Oo Fl rv Oc Op Ar command ...
2103The shell maintains a hash table which remembers the locations of commands.
2104With no arguments whatsoever, the
2105.Ic hash
2106command prints out the contents of this table.
2107Entries which have not been looked at since the last
2108.Ic cd
2109command are marked with an asterisk;
2110it is possible for these entries to be invalid.
2111.Pp
2112With arguments, the
2113.Ic hash
2114command removes each specified
2115.Ar command
2116from the hash table (unless they are functions) and then locates it.
2117With the
2118.Fl v
2119option,
2120.Ic hash
2121prints the locations of the commands as it finds them.
2122The
2123.Fl r
2124option causes the
2125.Ic hash
2126command to delete all the entries in the hash table except for functions.
2127.It Ic jobid Op Ar job
99512ac4 2128Print the process IDs of the processes in the specified
984263bc
MD
2129.Ar job .
2130If the
2131.Ar job
2132argument is omitted, use the current job.
9d7989de 2133.It Ic jobs Oo Fl lps Oc Op Ar job ...
984263bc
MD
2134Print information about the specified jobs, or all jobs if no
2135.Ar job
2136argument is given.
2137The information printed includes job ID, status and command name.
2138.Pp
2139If the
2140.Fl l
2141option is specified, the PID of each job is also printed.
2142If the
9d7989de
PA
2143.Fl p
2144option is specified, only the process IDs for the process group leaders
2145are printed, one per line.
2146If the
984263bc 2147.Fl s
9d7989de
PA
2148option is specified, only the PIDs of the job commands are printed, one per
2149line.
99512ac4
PA
2150.It Ic kill
2151A built-in equivalent of
2152.Xr kill 1
2153that additionally supports sending signals to jobs.
10185af4
PA
2154.It Ic local Oo Ar variable ... Oc Op Fl
2155See the
2156.Sx Functions
2157subsection.
99512ac4
PA
2158.It Ic printf
2159A built-in equivalent of
2160.Xr printf 1 .
10185af4
PA
2161.It Ic pwd Op Fl L | P
2162Print the path of the current directory.
2163The built-in command may
984263bc
MD
2164differ from the program of the same name because the
2165built-in command remembers what the current directory
10185af4
PA
2166is rather than recomputing it each time.
2167This makes
2168it faster.
2169However, if the current directory is
984263bc
MD
2170renamed,
2171the built-in version of
2172.Xr pwd 1
2173will continue to print the old name for the directory.
2174.Pp
2175If the
2176.Fl P
2177option is specified, symbolic links are resolved.
2178If the
2179.Fl L
2180option is specified, the shell's notion of the current directory
2181is printed (symbolic links are not resolved).
2182This is the default.
99512ac4
PA
2183.It Ic read Oo Fl p Ar prompt Oc Oo
2184.Fl t Ar timeout Oc Oo Fl er Oc Ar variable ...
984263bc
MD
2185The
2186.Ar prompt
2187is printed if the
2188.Fl p
2189option is specified
10185af4
PA
2190and the standard input is a terminal.
2191Then a line is
2192read from the standard input.
2193The trailing newline
984263bc
MD
2194is deleted from the line and the line is split as
2195described in the section on
2196.Sx White Space Splitting (Field Splitting)
2197above, and
2198the pieces are assigned to the variables in order.
2199If there are more pieces than variables, the remaining
2200pieces (along with the characters in
99512ac4 2201.Va IFS
984263bc
MD
2202that separated them)
2203are assigned to the last variable.
2204If there are more variables than pieces, the remaining
2205variables are assigned the null string.
2206.Pp
2207Backslashes are treated specially, unless the
2208.Fl r
2209option is
10185af4
PA
2210specified.
2211If a backslash is followed by
984263bc 2212a newline, the backslash and the newline will be
10185af4
PA
2213deleted.
2214If a backslash is followed by any other
984263bc
MD
2215character, the backslash will be deleted and the following
2216character will be treated as though it were not in
99512ac4 2217.Va IFS ,
984263bc
MD
2218even if it is.
2219.Pp
2220If the
2221.Fl t
2222option is specified and the
2223.Ar timeout
99512ac4 2224elapses before a complete line of input is supplied,
984263bc
MD
2225the
2226.Ic read
10185af4 2227command will return an exit status of 1 without assigning any values.
984263bc
MD
2228The
2229.Ar timeout
2230value may optionally be followed by one of
cca2c150
TN
2231.Ql s ,
2232.Ql m
984263bc 2233or
cca2c150 2234.Ql h
984263bc
MD
2235to explicitly specify seconds, minutes or hours.
2236If none is supplied,
cca2c150 2237.Ql s
984263bc
MD
2238is assumed.
2239.Pp
2240The
2241.Fl e
2242option exists only for backward compatibility with older scripts.
2243.It Ic readonly Oo Fl p Oc Op Ar name ...
2244Each specified
2245.Ar name
2246is marked as read only,
2247so that it cannot be subsequently modified or unset.
2248The shell allows the value of a variable to be set
2249at the same time as it is marked read only
2250by using the following form:
99512ac4
PA
2251.Pp
2252.D1 Ic readonly Ar name Ns = Ns Ar value
984263bc
MD
2253.Pp
2254With no arguments the
2255.Ic readonly
2256command lists the names of all read only variables.
2257If the
2258.Fl p
2259option is specified, the read-only variables are printed as
2260.Dq Ic readonly Ar name Ns = Ns Ar value
2261lines, suitable for re-input to the shell.
10185af4
PA
2262.It Ic return Op Ar exitstatus
2263See the
2264.Sx Functions
2265subsection.
984263bc
MD
2266.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo
2267.Fl c Ar string Oc Op Fl - Ar arg ...
2268The
2269.Ic set
2270command performs three different functions:
2271.Bl -item
2272.It
2273With no arguments, it lists the values of all shell variables.
2274.It
2275If options are given,
2276either in short form or using the long
2277.Dq Fl /+o Ar longname
2278form,
2279it sets or clears the specified options as described in the section called
2280.Sx Argument List Processing .
2281.It
2282If the
2283.Dq Fl -
2284option is specified,
2285.Ic set
2286will replace the shell's positional parameters with the subsequent
2287arguments.
2288If no arguments follow the
2289.Dq Fl -
2290option,
2291all the positional parameters will be cleared,
2292which is equivalent to executing the command
99512ac4 2293.Dq Li "shift $#" .
984263bc
MD
2294The
2295.Dq Fl -
2296flag may be omitted when specifying arguments to be used
2297as positional replacement parameters.
2298This is not recommended,
2299because the first argument may begin with a dash
10185af4 2300.Pq Ql -
984263bc 2301or a plus
10185af4 2302.Pq Ql + ,
984263bc
MD
2303which the
2304.Ic set
2305command will interpret as a request to enable or disable options.
2306.El
99512ac4 2307.It Ic setvar Ar variable value
984263bc
MD
2308Assigns the specified
2309.Ar value
2310to the specified
2311.Ar variable .
99512ac4
PA
2312The
2313.Ic setvar
2314command is intended to be used in functions that
984263bc
MD
2315assign values to variables whose names are passed as parameters.
2316In general it is better to write
99512ac4 2317.Dq Ar variable Ns = Ns Ar value
984263bc
MD
2318rather than using
2319.Ic setvar .
2320.It Ic shift Op Ar n
2321Shift the positional parameters
2322.Ar n
2323times, or once if
2324.Ar n
2325is not specified.
99512ac4
PA
2326A shift sets the value of
2327.Li $1
2328to the value of
2329.Li $2 ,
2330the value of
2331.Li $2
2332to the value of
2333.Li $3 ,
2334and so on,
2335decreasing the value of
2336.Li $#
2337by one.
984263bc 2338If there are zero positional parameters, shifting does not do anything.
10185af4
PA
2339.It Ic test
2340A built-in equivalent of
2341.Xr test 1 .
0d5aaed6
PA
2342.It Ic times
2343Print the amount of time spent executing the shell and its children.
2344The first output line shows the user and system times for the shell
2345itself, the second one contains the user and system times for the
2346children.
984263bc 2347.It Ic trap Oo Ar action Oc Ar signal ...
10185af4 2348.It Ic trap Fl l
984263bc
MD
2349Cause the shell to parse and execute
2350.Ar action
2351when any specified
2352.Ar signal
2353is received.
2354The signals are specified by name or number.
2355In addition, the pseudo-signal
2356.Cm EXIT
99512ac4
PA
2357may be used to specify an
2358.Ar action
2359that is performed when the shell terminates.
984263bc
MD
2360The
2361.Ar action
10185af4
PA
2362may be an empty string or a dash
2363.Pq Ql - ;
984263bc
MD
2364the former causes the specified signal to be ignored
2365and the latter causes the default action to be taken.
10185af4
PA
2366Omitting the
2367.Ar action
2368is another way to request the default action, for compatibility reasons this
2369usage is not recommended though.
1de90000
PA
2370In a subshell environment,
2371the shell resets trapped (but not ignored) signals to the default action.
984263bc
MD
2372The
2373.Ic trap
2374command has no effect on signals that were ignored on entry to the shell.
10185af4
PA
2375.Pp
2376Option
2377.Fl l
2378causes the
2379.Ic trap
2380command to display a list of valid signal names.
2381.It Ic true
2382A null command that returns a 0 (true) exit value.
984263bc
MD
2383.It Ic type Op Ar name ...
2384Interpret each
2385.Ar name
2386as a command and print the resolution of the command search.
2387Possible resolutions are:
99512ac4
PA
2388shell keyword, alias, special shell builtin, shell builtin, command,
2389tracked alias
984263bc
MD
2390and not found.
2391For aliases the alias expansion is printed;
2392for commands and tracked aliases
2393the complete pathname of the command is printed.
2394.It Ic ulimit Oo Fl HSabcdflmnstuv Oc Op Ar limit
2395Set or display resource limits (see
2396.Xr getrlimit 2 ) .
2397If
2398.Ar limit
2399is specified, the named resource will be set;
2400otherwise the current resource value will be displayed.
2401.Pp
2402If
2403.Fl H
2404is specified, the hard limits will be set or displayed.
2405While everybody is allowed to reduce a hard limit,
2406only the superuser can increase it.
2407The
2408.Fl S
2409option
10185af4
PA
2410specifies the soft limits instead.
2411When displaying limits,
984263bc
MD
2412only one of
2413.Fl S
2414or
2415.Fl H
2416can be given.
2417The default is to display the soft limits,
2418and to set both the hard and the soft limits.
2419.Pp
2420Option
2421.Fl a
2422causes the
2423.Ic ulimit
2424command to display all resources.
2425The parameter
2426.Ar limit
2427is not acceptable in this mode.
2428.Pp
2429The remaining options specify which resource value is to be
2430displayed or modified.
2431They are mutually exclusive.
2432.Bl -tag -width indent
2433.It Fl b Ar sbsize
2434The maximum size of socket buffer usage, in bytes.
2435.It Fl c Ar coredumpsize
2436The maximal size of core dump files, in 512-byte blocks.
2437.It Fl d Ar datasize
2438The maximal size of the data segment of a process, in kilobytes.
2439.It Fl f Ar filesize
2440The maximal size of a file, in 512-byte blocks.
2441.It Fl l Ar lockedmem
2442The maximal size of memory that can be locked by a process, in
2443kilobytes.
2444.It Fl m Ar memoryuse
2445The maximal resident set size of a process, in kilobytes.
2446.It Fl n Ar nofiles
2447The maximal number of descriptors that could be opened by a process.
2448.It Fl s Ar stacksize
2449The maximal size of the stack segment, in kilobytes.
2450.It Fl t Ar time
2451The maximal amount of CPU time to be used by each process, in seconds.
2452.It Fl u Ar userproc
2453The maximal number of simultaneous processes for this user ID.
2454.It Fl v Ar virtualmem
2455The maximal virtual size of a process, in kilobytes.
2456.El
10185af4 2457.It Ic umask Oo Fl S Oc Op Ar mask
984263bc
MD
2458Set the file creation mask (see
2459.Xr umask 2 )
10185af4
PA
2460to the octal or symbolic (see
2461.Xr chmod 1 )
2462value specified by
984263bc
MD
2463.Ar mask .
2464If the argument is omitted, the current mask value is printed.
10185af4
PA
2465If the
2466.Fl S
2467option is specified, the output is symbolic, otherwise the output is octal.
2468.It Ic unalias Oo Fl a Oc Op Ar name ...
2469The specified alias names are removed.
984263bc
MD
2470If
2471.Fl a
2472is specified, all aliases are removed.
2473.It Ic unset Oo Fl fv Oc Ar name ...
2474The specified variables or functions are unset and unexported.
2475If the
2476.Fl v
2477option is specified or no options are given, the
2478.Ar name
2479arguments are treated as variable names.
2480If the
2481.Fl f
2482option is specified, the
2483.Ar name
2484arguments are treated as function names.
2485.It Ic wait Op Ar job
2486Wait for the specified
2487.Ar job
2488to complete and return the exit status of the last process in the
2489.Ar job .
2490If the argument is omitted, wait for all jobs to complete
2491and return an exit status of zero.
2492.El
2493.Ss Commandline Editing
2494When
2495.Nm
2496is being used interactively from a terminal, the current command
2497and the command history
2498(see
2499.Ic fc
2500in
2501.Sx Built-in Commands )
99512ac4
PA
2502can be edited using
2503.Nm vi Ns -mode
2504command line editing.
984263bc 2505This mode uses commands similar
99512ac4
PA
2506to a subset of those described in the
2507.Xr vi 1
2508man page.
984263bc 2509The command
99512ac4 2510.Dq Li "set -o vi"
984263bc 2511(or
99512ac4
PA
2512.Dq Li "set -V" )
2513enables
2514.Nm vi Ns -mode
2515editing and places
984263bc 2516.Nm
99512ac4
PA
2517into
2518.Nm vi
2519insert mode.
2520With
2521.Nm vi Ns -mode
2522enabled,
984263bc
MD
2523.Nm
2524can be switched between insert mode and command mode by typing
2525.Aq ESC .
2526Hitting
2527.Aq return
2528while in command mode will pass the line to the shell.
2529.Pp
2530Similarly, the
99512ac4 2531.Dq Li "set -o emacs"
984263bc 2532(or
99512ac4 2533.Dq Li "set -E" )
984263bc 2534command can be used to enable a subset of
99512ac4
PA
2535.Nm emacs Ns -style
2536command line editing features.
10185af4
PA
2537.Sh ENVIRONMENT
2538The following environment variables affect the execution of
2539.Nm :
99512ac4
PA
2540.Bl -tag -width ".Ev LANGXXXXXX"
2541.It Ev ENV
2542Initialization file for interactive shells.
2543.It Ev LANG , Ev LC_*
2544Locale settings.
2545These are inherited by children of the shell,
2546and is used in a limited manner by the shell itself.
2547.It Ev PWD
2548An absolute pathname for the current directory,
2549possibly containing symbolic links.
2550This is used and updated by the shell.
10185af4
PA
2551.It Ev TERM
2552The default terminal setting for the shell.
2553This is inherited by children of the shell, and is used in the history
2554editing modes.
2555.El
99512ac4
PA
2556.Pp
2557Additionally, all environment variables are turned into shell variables
2558at startup,
2559which may affect the shell as described under
2560.Sx Special Variables .
10185af4
PA
2561.Sh EXIT STATUS
2562Errors that are detected by the shell, such as a syntax error, will
2563cause the shell to exit with a non-zero exit status.
2564If the shell is not an interactive shell, the execution of the shell
2565file will be aborted.
2566Otherwise the shell will return the exit status of the last command
99512ac4
PA
2567executed, or if the
2568.Ic exit
2569builtin is used with a numeric argument, it
10185af4 2570will return the argument.
984263bc
MD
2571.Sh SEE ALSO
2572.Xr builtin 1 ,
10185af4 2573.Xr chsh 1 ,
984263bc 2574.Xr echo 1 ,
10185af4 2575.Xr ed 1 ,
7cd7d057 2576.Xr emacs 1 Pq Pa pkgsrc/editors/emacs ,
99512ac4 2577.Xr kill 1 ,
984263bc
MD
2578.Xr printf 1 ,
2579.Xr pwd 1 ,
10185af4
PA
2580.Xr test 1 ,
2581.Xr vi 1 ,
2582.Xr execve 2 ,
2583.Xr getrlimit 2 ,
2584.Xr umask 2 ,
e0bca924
SW
2585.Xr editrc 5 ,
2586.Xr script 7
984263bc
MD
2587.Sh HISTORY
2588A
2589.Nm
10185af4 2590command, the Thompson shell, appeared in
984263bc 2591.At v1 .
10185af4
PA
2592It was superseded in
2593.At v7
2594by the Bourne shell, which inherited the name
2595.Nm .
2596.Pp
2597This version of
2598.Nm
2599was rewritten in 1989 under the
2600.Bx
2601license after the Bourne shell from
2602.At V.4 .
2603.Sh AUTHORS
2604This version of
2605.Nm
2606was originally written by
2607.An Kenneth Almquist .
2608.Sh BUGS
2609The
2610.Nm
7602056e
PA
2611utility does not recognize multibyte characters other than UTF-8.
2612Splitting using
2613.Va IFS
2614and the line editing library
2615.Xr editline 3
2616do not recognize multibyte characters.
3f2d021a
YT
2617.Pp
2618The characters generated by filename completion should probably be quoted
2619to ensure that the filename is still valid after the input line has been
2620processed.