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