sh: Add do-nothing -h option.
[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
6156762f 37.\" $FreeBSD: src/bin/sh/sh.1,v 1.171 2011/06/18 23:43:28 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 & ,
984263bc
MD
875the shell executes the command asynchronously;
876the shell does not wait for the command to finish
877before executing the next command.
878.Pp
879The format for running a command in background is:
99512ac4
PA
880.Pp
881.D1 Ar command1 Li & Op Ar command2 Li & Ar ...
984263bc
MD
882.Pp
883If the shell is not interactive, the standard input of an
99512ac4
PA
884asynchronous command is set to
885.Pa /dev/null .
984263bc
MD
886.Ss Lists (Generally Speaking)
887A list is a sequence of zero or more commands separated by
888newlines, semicolons, or ampersands,
889and optionally terminated by one of these three characters.
890The commands in a
891list are executed in the order they are written.
892If command is followed by an ampersand, the shell starts the
893command and immediately proceeds onto the next command;
894otherwise it waits for the command to terminate before
895proceeding to the next one.
896.Ss Short-Circuit List Operators
897.Dq Li &&
898and
899.Dq Li ||
900are AND-OR list operators.
901.Dq Li &&
902executes the first command, and then executes the second command
903if the exit status of the first command is zero.
904.Dq Li ||
905is similar, but executes the second command if the exit
906status of the first command is nonzero.
907.Dq Li &&
908and
909.Dq Li ||
910both have the same priority.
911.Ss Flow-Control Constructs (if, while, for, case)
912The syntax of the
913.Ic if
914command is:
99512ac4
PA
915.Bd -unfilled -offset indent -compact
916.Ic if Ar list
917.Ic then Ar list
918.Oo Ic elif Ar list
919.Ic then Ar list Oc Ar ...
920.Op Ic else Ar list
921.Ic fi
922.Ed
984263bc
MD
923.Pp
924The syntax of the
925.Ic while
926command is:
99512ac4
PA
927.Bd -unfilled -offset indent -compact
928.Ic while Ar list
929.Ic do Ar list
930.Ic done
931.Ed
984263bc
MD
932.Pp
933The two lists are executed repeatedly while the exit status of the
934first list is zero.
935The
936.Ic until
937command is similar, but has the word
938.Ic until
939in place of
940.Ic while ,
941which causes it to
942repeat until the exit status of the first list is zero.
943.Pp
944The syntax of the
945.Ic for
946command is:
99512ac4
PA
947.Bd -unfilled -offset indent -compact
948.Ic for Ar variable Op Ic in Ar word ...
949.Ic do Ar list
950.Ic done
951.Ed
984263bc 952.Pp
10185af4
PA
953If
954.Ic in
955and the following words are omitted,
99512ac4 956.Ic in Li \&"$@\&"
10185af4 957is used instead.
984263bc
MD
958The words are expanded, and then the list is executed
959repeatedly with the variable set to each word in turn.
960The
961.Ic do
962and
963.Ic done
964commands may be replaced with
cca2c150 965.Ql {
984263bc 966and
cca2c150 967.Ql } .
984263bc
MD
968.Pp
969The syntax of the
970.Ic break
971and
972.Ic continue
973commands is:
99512ac4
PA
974.D1 Ic break Op Ar num
975.D1 Ic continue Op Ar num
984263bc
MD
976.Pp
977The
978.Ic break
979command terminates the
980.Ar num
981innermost
982.Ic for
983or
984.Ic while
985loops.
986The
987.Ic continue
988command continues with the next iteration of the innermost loop.
99512ac4 989These are implemented as special built-in commands.
984263bc
MD
990.Pp
991The syntax of the
992.Ic case
99512ac4
PA
993command is:
994.Bd -unfilled -offset indent -compact
995.Ic case Ar word Ic in
996.Ar pattern Ns Li ) Ar list Li ;;
997.Ar ...
998.Ic esac
999.Ed
984263bc
MD
1000.Pp
1001The pattern can actually be one or more patterns
1002(see
1003.Sx Shell Patterns
1004described later),
1005separated by
cca2c150 1006.Ql \&|
984263bc 1007characters.
21f23b60
PA
1008If the selected list is terminated by the control operator
1009.Ql ;&
1010instead of
1011.Ql ;; ,
1012execution continues with the next list.
99512ac4
PA
1013The exit code of the
1014.Ic case
1015command is the exit code of the last command executed in the list or
1016zero if no patterns were matched.
984263bc
MD
1017.Ss Grouping Commands Together
1018Commands may be grouped by writing either
99512ac4
PA
1019.Pp
1020.D1 Li \&( Ns Ar list Ns Li \%)
984263bc
MD
1021.Pp
1022or
99512ac4
PA
1023.Pp
1024.D1 Li { Ar list Ns Li \&; }
984263bc 1025.Pp
1de90000 1026The first form executes the commands in a subshell environment.
984263bc 1027Note that built-in commands thus executed do not affect the current shell.
1de90000 1028The second form never forks another shell,
984263bc
MD
1029so it is slightly more efficient.
1030Grouping commands together this way allows the user to
1031redirect their output as though they were one program:
1032.Bd -literal -offset indent
1033{ echo -n "hello"; echo " world"; } > greeting
1034.Ed
1035.Ss Functions
1036The syntax of a function definition is
99512ac4
PA
1037.Pp
1038.D1 Ar name Li \&( \&) Ar command
984263bc
MD
1039.Pp
1040A function definition is an executable statement; when
99512ac4
PA
1041executed it installs a function named
1042.Ar name
1043and returns an
10185af4 1044exit status of zero.
99512ac4
PA
1045The
1046.Ar command
1047is normally a list
984263bc 1048enclosed between
cca2c150 1049.Ql {
984263bc 1050and
cca2c150 1051.Ql } .
984263bc
MD
1052.Pp
1053Variables may be declared to be local to a function by
1054using the
1055.Ic local
1056command.
1057This should appear as the first statement of a function,
1058and the syntax is:
99512ac4
PA
1059.Pp
1060.D1 Ic local Oo Ar variable ... Oc Op Fl
984263bc
MD
1061.Pp
1062The
1063.Ic local
1064command is implemented as a built-in command.
1065.Pp
1066When a variable is made local, it inherits the initial
1067value and exported and readonly flags from the variable
1068with the same name in the surrounding scope, if there is
10185af4
PA
1069one.
1070Otherwise, the variable is initially unset.
1071The shell
984263bc 1072uses dynamic scoping, so that if the variable
99512ac4 1073.Va x
984263bc
MD
1074is made local to function
1075.Em f ,
1076which then calls function
1077.Em g ,
1078references to the variable
99512ac4 1079.Va x
984263bc
MD
1080made inside
1081.Em g
1082will refer to the variable
99512ac4 1083.Va x
984263bc
MD
1084declared inside
1085.Em f ,
1086not to the global variable named
99512ac4 1087.Va x .
984263bc 1088.Pp
10185af4 1089The only special parameter that can be made local is
cca2c150 1090.Ql - .
984263bc 1091Making
cca2c150 1092.Ql -
984263bc 1093local causes any shell options that are
99512ac4
PA
1094changed via the
1095.Ic set
1096command inside the function to be
984263bc
MD
1097restored to their original values when the function
1098returns.
1099.Pp
1100The syntax of the
1101.Ic return
1102command is
99512ac4
PA
1103.Pp
1104.D1 Ic return Op Ar exitstatus
984263bc 1105.Pp
10185af4
PA
1106It terminates the current executional scope, returning from the previous
1107nested function, sourced script, or shell instance, in that order.
984263bc
MD
1108The
1109.Ic return
99512ac4 1110command is implemented as a special built-in command.
984263bc 1111.Ss Variables and Parameters
10185af4
PA
1112The shell maintains a set of parameters.
1113A parameter
1114denoted by a name is called a variable.
1115When starting up,
984263bc 1116the shell turns all the environment variables into shell
10185af4
PA
1117variables.
1118New variables can be set using the form
99512ac4
PA
1119.Pp
1120.D1 Ar name Ns = Ns Ar value
984263bc
MD
1121.Pp
1122Variables set by the user must have a name consisting solely
1123of alphabetics, numerics, and underscores.
1124The first letter of a variable name must not be numeric.
1125A parameter can also be denoted by a number
1126or a special character as explained below.
1127.Ss Positional Parameters
1128A positional parameter is a parameter denoted by a number greater than zero.
1129The shell sets these initially to the values of its command line
10185af4
PA
1130arguments that follow the name of the shell script.
1131The
984263bc
MD
1132.Ic set
1133built-in command can also be used to set or reset them.
1134.Ss Special Parameters
99512ac4
PA
1135Special parameters are parameters denoted by a single special character
1136or the digit zero.
1137They are shown in the following list, exactly as they would appear in input
10185af4 1138typed by the user or in the source of a shell script.
984263bc 1139.Bl -hang
10185af4
PA
1140.It Li $*
1141Expands to the positional parameters, starting from one.
1142When
984263bc
MD
1143the expansion occurs within a double-quoted string
1144it expands to a single field with the value of each parameter
1145separated by the first character of the
99512ac4 1146.Va IFS
984263bc 1147variable,
99512ac4
PA
1148or by a space if
1149.Va IFS
984263bc 1150is unset.
10185af4
PA
1151.It Li $@
1152Expands to the positional parameters, starting from one.
1153When
984263bc
MD
1154the expansion occurs within double-quotes, each positional
1155parameter expands as a separate argument.
1156If there are no positional parameters, the
1157expansion of
1158.Li @
1159generates zero arguments, even when
1160.Li @
10185af4
PA
1161is double-quoted.
1162What this basically means, for example, is
99512ac4
PA
1163if
1164.Li $1
1165is
1166.Dq Li abc
1167and
1168.Li $2
1169is
1170.Dq Li "def ghi" ,
984263bc 1171then
99512ac4 1172.Li \&"$@\&"
984263bc
MD
1173expands to
1174the two arguments:
1175.Bd -literal -offset indent
1176"abc" "def ghi"
1177.Ed
10185af4 1178.It Li $#
984263bc 1179Expands to the number of positional parameters.
99512ac4 1180.It Li $?
984263bc 1181Expands to the exit status of the most recent pipeline.
10185af4 1182.It Li $-
984263bc
MD
1183(hyphen) Expands to the current option flags (the single-letter
1184option names concatenated into a string) as specified on
99512ac4
PA
1185invocation, by the
1186.Ic set
1187built-in command, or implicitly
984263bc 1188by the shell.
10185af4
PA
1189.It Li $$
1190Expands to the process ID of the invoked shell.
1191A subshell
99512ac4
PA
1192retains the same value of
1193.Va $
1194as its parent.
1195.It Li $!
984263bc 1196Expands to the process ID of the most recent background
10185af4
PA
1197command executed from the current shell.
1198For a
984263bc
MD
1199pipeline, the process ID is that of the last command in the
1200pipeline.
99512ac4
PA
1201If this parameter is referenced, the shell will remember
1202the process ID and its exit status until the
1203.Ic wait
1204built-in command reports completion of the process.
10185af4 1205.It Li $0
99512ac4
PA
1206(zero) Expands to the name of the shell script if passed on the command line,
1207the
1208.Ar name
1209operand if given (with
1210.Fl c )
1211or otherwise argument 0 passed to the shell.
1212.El
1213.Ss Special Variables
1214The following variables are set by the shell or
1215have special meaning to it:
1216.Bl -tag -width ".Va HISTSIZE"
1217.It Va CDPATH
1218The search path used with the
1219.Ic cd
1220built-in.
1221.It Va EDITOR
1222The fallback editor used with the
1223.Ic fc
1224built-in.
1225If not set, the default editor is
1226.Xr ed 1 .
1227.It Va FCEDIT
1228The default editor used with the
1229.Ic fc
1230built-in.
1231.It Va HISTSIZE
1232The number of previous commands that are accessible.
1233.It Va HOME
1234The user's home directory,
1235used in tilde expansion and as a default directory for the
1236.Ic cd
1237built-in.
1238.It Va IFS
1239Input Field Separators.
1240This is normally set to
1241.Aq space ,
1242.Aq tab ,
1243and
1244.Aq newline .
1245See the
1246.Sx White Space Splitting
1247section for more details.
1248.It Va LINENO
1249The current line number in the script or function.
1250.It Va MAIL
1251The name of a mail file, that will be checked for the arrival of new
1252mail.
1253Overridden by
1254.Va MAILPATH .
1255.It Va MAILPATH
1256A colon
1257.Pq Ql \&:
1258separated list of file names, for the shell to check for incoming
1259mail.
1260This variable overrides the
1261.Va MAIL
1262setting.
1263There is a maximum of 10 mailboxes that can be monitored at once.
1264.It Va PATH
1265The default search path for executables.
1266See the
1267.Sx Path Search
1268section for details.
1269.It Va PPID
1270The parent process ID of the invoked shell.
1271This is set at startup
1272unless this variable is in the environment.
1273A later change of parent process ID is not reflected.
1274A subshell retains the same value of
1275.Va PPID .
1276.It Va PS1
1277The primary prompt string, which defaults to
1278.Dq Li "$ " ,
1279unless you are the superuser, in which case it defaults to
1280.Dq Li "# " .
1281.It Va PS2
1282The secondary prompt string, which defaults to
1283.Dq Li "> " .
1284.It Va PS4
1285The prefix for the trace output (if
1286.Fl x
1287is active).
1288The default is
1289.Dq Li "+ " .
984263bc
MD
1290.El
1291.Ss Word Expansions
1292This clause describes the various expansions that are
10185af4
PA
1293performed on words.
1294Not all expansions are performed on
984263bc
MD
1295every word, as explained later.
1296.Pp
1297Tilde expansions, parameter expansions, command substitutions,
1298arithmetic expansions, and quote removals that occur within
10185af4
PA
1299a single word expand to a single field.
1300It is only field
984263bc
MD
1301splitting or pathname expansion that can create multiple
1302fields from a single word.
1303The single exception to this rule is
1304the expansion of the special parameter
99512ac4 1305.Va @
984263bc
MD
1306within double-quotes,
1307as was described above.
1308.Pp
1309The order of word expansion is:
1310.Bl -enum
1311.It
1312Tilde Expansion, Parameter Expansion, Command Substitution,
1313Arithmetic Expansion (these all occur at the same time).
1314.It
1315Field Splitting is performed on fields generated by step (1)
1316unless the
99512ac4 1317.Va IFS
984263bc
MD
1318variable is null.
1319.It
1320Pathname Expansion (unless the
1321.Fl f
1322option is in effect).
1323.It
1324Quote Removal.
1325.El
1326.Pp
1327The
cca2c150 1328.Ql $
984263bc 1329character is used to introduce parameter expansion, command
99512ac4 1330substitution, or arithmetic expansion.
984263bc
MD
1331.Ss Tilde Expansion (substituting a user's home directory)
1332A word beginning with an unquoted tilde character
10185af4 1333.Pq Ql ~
984263bc
MD
1334is
1335subjected to tilde expansion.
1336All the characters up to a slash
10185af4 1337.Pq Ql /
984263bc 1338or the end of the word are treated as a username
10185af4
PA
1339and are replaced with the user's home directory.
1340If the
99512ac4
PA
1341username is missing (as in
1342.Pa ~/foobar ) ,
1343the tilde is replaced with the value of the
1344.Va HOME
1345variable (the current user's home directory).
984263bc
MD
1346.Ss Parameter Expansion
1347The format for parameter expansion is as follows:
984263bc 1348.Pp
99512ac4
PA
1349.D1 Li ${ Ns Ar expression Ns Li }
1350.Pp
1351where
1352.Ar expression
1353consists of all characters until the matching
cca2c150 1354.Ql } .
984263bc 1355Any
cca2c150 1356.Ql }
99512ac4
PA
1357escaped by a backslash or within a single-quoted or double-quoted
1358string, and characters in
984263bc
MD
1359embedded arithmetic expansions, command substitutions, and variable
1360expansions, are not examined in determining the matching
cca2c150 1361.Ql } .
99512ac4
PA
1362If the variants with
1363.Ql + ,
1364.Ql - ,
1365.Ql =
1366or
1367.Ql ?\&
1368occur within a double-quoted string,
1369as an extension there may be unquoted parts
1370(via double-quotes inside the expansion);
1371.Ql }
1372within such parts are also not examined in determining the matching
1373.Ql } .
984263bc
MD
1374.Pp
1375The simplest form for parameter expansion is:
984263bc 1376.Pp
99512ac4
PA
1377.D1 Li ${ Ns Ar parameter Ns Li }
1378.Pp
1379The value, if any, of
1380.Ar parameter
1381is substituted.
984263bc
MD
1382.Pp
1383The parameter name or symbol can be enclosed in braces, which are
1384optional except for positional parameters with more than one digit or
1385when parameter is followed by a character that could be interpreted as
1386part of the name.
1387If a parameter expansion occurs inside double-quotes:
1388.Bl -enum
1389.It
1390Pathname expansion is not performed on the results of the
1391expansion.
1392.It
1393Field splitting is not performed on the results of the
1394expansion, with the exception of the special parameter
99512ac4 1395.Va @ .
984263bc
MD
1396.El
1397.Pp
1398In addition, a parameter expansion can be modified by using one of the
1399following formats.
1400.Bl -tag -width indent
99512ac4 1401.It Li ${ Ns Ar parameter Ns Li :- Ns Ar word Ns Li }
10185af4 1402Use Default Values.
99512ac4
PA
1403If
1404.Ar parameter
1405is unset or null, the expansion of
1406.Ar word
1407is substituted; otherwise, the value of
1408.Ar parameter
1409is substituted.
1410.It Li ${ Ns Ar parameter Ns Li := Ns Ar word Ns Li }
10185af4 1411Assign Default Values.
99512ac4
PA
1412If
1413.Ar parameter
1414is unset or null, the expansion of
1415.Ar word
1416is assigned to
1417.Ar parameter .
10185af4 1418In all cases, the
99512ac4
PA
1419final value of
1420.Ar parameter
1421is substituted.
1422Quoting inside
1423.Ar word
1424does not prevent field splitting or pathname expansion.
10185af4 1425Only variables, not positional
984263bc
MD
1426parameters or special parameters, can be
1427assigned in this way.
99512ac4 1428.It Li ${ Ns Ar parameter Ns Li :? Ns Oo Ar word Oc Ns Li }
10185af4
PA
1429Indicate Error if Null or Unset.
1430If
99512ac4
PA
1431.Ar parameter
1432is unset or null, the expansion of
1433.Ar word
1434(or a message indicating it is unset if
1435.Ar word
1436is omitted) is written to standard
984263bc
MD
1437error and the shell exits with a nonzero
1438exit status.
1439Otherwise, the value of
99512ac4
PA
1440.Ar parameter
1441is substituted.
10185af4 1442An
984263bc 1443interactive shell need not exit.
99512ac4 1444.It Li ${ Ns Ar parameter Ns Li :+ Ns Ar word Ns Li }
10185af4 1445Use Alternate Value.
99512ac4
PA
1446If
1447.Ar parameter
1448is unset or null, null is substituted;
1449otherwise, the expansion of
1450.Ar word
1451is substituted.
984263bc
MD
1452.El
1453.Pp
1454In the parameter expansions shown previously, use of the colon in the
1455format results in a test for a parameter that is unset or null; omission
1456of the colon results in a test for a parameter that is only unset.
99512ac4
PA
1457.Pp
1458The
1459.Ar word
1460inherits the type of quoting
1461(unquoted, double-quoted or here-document)
1462from the surroundings,
1463with the exception that a backslash that quotes a closing brace is removed
1464during quote removal.
984263bc 1465.Bl -tag -width indent
99512ac4 1466.It Li ${# Ns Ar parameter Ns Li }
10185af4
PA
1467String Length.
1468The length in characters of
99512ac4
PA
1469the value of
1470.Ar parameter .
984263bc
MD
1471.El
1472.Pp
1473The following four varieties of parameter expansion provide for substring
1474processing.
1475In each case, pattern matching notation
1476(see
1477.Sx Shell Patterns ) ,
1478rather than regular expression notation,
1479is used to evaluate the patterns.
1480If parameter is one of the special parameters
99512ac4 1481.Va *
984263bc 1482or
99512ac4 1483.Va @ ,
984263bc
MD
1484the result of the expansion is unspecified.
1485Enclosing the full parameter expansion string in double-quotes does not
1486cause the following four varieties of pattern characters to be quoted,
1487whereas quoting characters within the braces has this effect.
1488.Bl -tag -width indent
99512ac4 1489.It Li ${ Ns Ar parameter Ns Li % Ns Ar word Ns Li }
10185af4 1490Remove Smallest Suffix Pattern.
99512ac4
PA
1491The
1492.Ar word
10185af4
PA
1493is expanded to produce a pattern.
1494The
984263bc 1495parameter expansion then results in
99512ac4
PA
1496.Ar parameter ,
1497with the smallest portion of the
984263bc 1498suffix matched by the pattern deleted.
99512ac4 1499.It Li ${ Ns Ar parameter Ns Li %% Ns Ar word Ns Li }
10185af4 1500Remove Largest Suffix Pattern.
99512ac4
PA
1501The
1502.Ar word
10185af4
PA
1503is expanded to produce a pattern.
1504The
984263bc 1505parameter expansion then results in
99512ac4
PA
1506.Ar parameter ,
1507with the largest portion of the
984263bc 1508suffix matched by the pattern deleted.
99512ac4 1509.It Li ${ Ns Ar parameter Ns Li # Ns Ar word Ns Li }
10185af4 1510Remove Smallest Prefix Pattern.
99512ac4
PA
1511The
1512.Ar word
10185af4
PA
1513is expanded to produce a pattern.
1514The
984263bc 1515parameter expansion then results in
99512ac4
PA
1516.Ar parameter ,
1517with the smallest portion of the
984263bc 1518prefix matched by the pattern deleted.
99512ac4 1519.It Li ${ Ns Ar parameter Ns Li ## Ns Ar word Ns Li }
10185af4 1520Remove Largest Prefix Pattern.
99512ac4
PA
1521The
1522.Ar word
10185af4
PA
1523is expanded to produce a pattern.
1524The
984263bc 1525parameter expansion then results in
99512ac4
PA
1526.Ar parameter ,
1527with the largest portion of the
984263bc
MD
1528prefix matched by the pattern deleted.
1529.El
1530.Ss Command Substitution
1531Command substitution allows the output of a command to be substituted in
10185af4
PA
1532place of the command name itself.
1533Command substitution occurs when
984263bc 1534the command is enclosed as follows:
99512ac4
PA
1535.Pp
1536.D1 Li $( Ns Ar command Ns Li )\&
984263bc
MD
1537.Pp
1538or the backquoted version:
99512ac4
PA
1539.Pp
1540.D1 Li ` Ns Ar command Ns Li `
984263bc 1541.Pp
1de90000
PA
1542The shell expands the command substitution by executing command
1543and replacing the command substitution
984263bc
MD
1544with the standard output of the command,
1545removing sequences of one or more newlines at the end of the substitution.
1546Embedded newlines before the end of the output are not removed;
1547however, during field splitting, they may be translated into spaces
1548depending on the value of
99512ac4 1549.Va IFS
984263bc 1550and the quoting that is in effect.
1de90000
PA
1551The command is executed in a subshell environment,
1552except that the built-in commands
1553.Ic jobid ,
1554.Ic jobs ,
1555.Ic times
1556and
1557.Ic trap
1558return information about the main shell environment
32931063 1559if they are the only command in a command substitution.
984263bc
MD
1560.Ss Arithmetic Expansion
1561Arithmetic expansion provides a mechanism for evaluating an arithmetic
1562expression and substituting its value.
1563The format for arithmetic expansion is as follows:
984263bc 1564.Pp
99512ac4
PA
1565.D1 Li $(( Ns Ar expression Ns Li ))
1566.Pp
1567The
1568.Ar expression
1569is treated as if it were in double-quotes, except
10185af4
PA
1570that a double-quote inside the expression is not treated specially.
1571The
99512ac4
PA
1572shell expands all tokens in the
1573.Ar expression
1574for parameter expansion,
1575command substitution,
1576arithmetic expansion
1577and quote removal.
1578.Pp
1579The allowed expressions are a subset of C expressions,
1580summarized below.
1581.Bl -tag -width "Variables" -offset indent
1582.It Values
1583All values are of type
1584.Ft intmax_t .
1585.It Constants
1586Decimal, octal (starting with
1587.Li 0 )
1588and hexadecimal (starting with
1589.Li 0x )
1590integer constants.
1591.It Variables
1592Shell variables can be read and written
1593and contain integer constants.
1594.It Unary operators
1595.Li "! ~ + -"
1596.It Binary operators
1597.Li "* / % + - << >> < <= > >= == != & ^ | && ||"
1598.It Assignment operators
1599.Li "= += -= *= /= %= <<= >>= &= ^= |="
1600.It Conditional operator
1601.Li "? :"
1602.El
984263bc 1603.Pp
99512ac4 1604The result of the expression is substituted in decimal.
984263bc
MD
1605.Ss White Space Splitting (Field Splitting)
1606After parameter expansion, command substitution, and
1607arithmetic expansion the shell scans the results of
1608expansions and substitutions that did not occur in double-quotes for
1609field splitting and multiple fields can result.
1610.Pp
1611The shell treats each character of the
99512ac4
PA
1612.Va IFS
1613variable as a delimiter and uses
984263bc
MD
1614the delimiters to split the results of parameter expansion and command
1615substitution into fields.
1616.Ss Pathname Expansion (File Name Generation)
1617Unless the
1618.Fl f
1619option is set,
1620file name generation is performed
10185af4
PA
1621after word splitting is complete.
1622Each word is
1623viewed as a series of patterns, separated by slashes.
1624The
984263bc
MD
1625process of expansion replaces the word with the names of
1626all existing files whose names can be formed by replacing
1627each pattern with a string that matches the specified pattern.
1628There are two restrictions on this: first, a pattern cannot match
1629a string containing a slash, and second,
1630a pattern cannot match a string starting with a period
1631unless the first character of the pattern is a period.
1632The next section describes the patterns used for both
1633Pathname Expansion and the
1634.Ic case
1635command.
1636.Ss Shell Patterns
1637A pattern consists of normal characters, which match themselves,
1638and meta-characters.
1639The meta-characters are
cca2c150
TN
1640.Ql \&! ,
1641.Ql * ,
1642.Ql \&? ,
984263bc 1643and
cca2c150 1644.Ql \&[ .
984263bc
MD
1645These characters lose their special meanings if they are quoted.
1646When command or variable substitution is performed and the dollar sign
1647or back quotes are not double-quoted, the value of the
1648variable or the output of the command is scanned for these
1649characters and they are turned into meta-characters.
1650.Pp
1651An asterisk
10185af4 1652.Pq Ql *
984263bc
MD
1653matches any string of characters.
1654A question mark
10185af4 1655.Pq Ql \&?
984263bc
MD
1656matches any single character.
1657A left bracket
cca2c150 1658.Pq Ql \&[
984263bc
MD
1659introduces a character class.
1660The end of the character class is indicated by a
cca2c150 1661.Ql \&] ;
984263bc 1662if the
cca2c150 1663.Ql \&]
984263bc 1664is missing then the
cca2c150 1665.Ql \&[
984263bc 1666matches a
cca2c150 1667.Ql \&[
984263bc
MD
1668rather than introducing a character class.
1669A character class matches any of the characters between the square brackets.
1670A range of characters may be specified using a minus sign.
215809b7
PA
1671A named class of characters (see
1672.Xr wctype 3 )
1673may be specified by surrounding the name with
1674.Ql \&[:
1675and
1676.Ql :\&] .
1677For example,
1678.Ql \&[\&[:alpha:\&]\&]
1679is a shell pattern that matches a single letter.
984263bc 1680The character class may be complemented by making an exclamation point
10185af4 1681.Pq Ql !\&
bb9a009b 1682or the caret
10185af4 1683.Pq Ql ^\&
984263bc
MD
1684the first character of the character class.
1685.Pp
1686To include a
cca2c150 1687.Ql \&]
984263bc
MD
1688in a character class, make it the first character listed
1689(after the
cca2c150 1690.Ql \&!
bb9a009b 1691or
cca2c150 1692.Ql \&^ ,
984263bc
MD
1693if any).
1694To include a
cca2c150 1695.Ql - ,
984263bc
MD
1696make it the first or last character listed.
1697.Ss Built-in Commands
99512ac4 1698This section lists the built-in commands.
984263bc
MD
1699.Bl -tag -width indent
1700.It Ic \&:
1701A null command that returns a 0 (true) exit value.
1702.It Ic \&. Ar file
1703The commands in the specified file are read and executed by the shell.
10185af4
PA
1704The
1705.Ic return
1706command may be used to return to the
1707.Ic \&.
1708command's caller.
984263bc
MD
1709If
1710.Ar file
1711contains any
cca2c150 1712.Ql /
10185af4
PA
1713characters, it is used as is.
1714Otherwise, the shell searches the
99512ac4 1715.Va PATH
10185af4
PA
1716for the file.
1717If it is not found in the
99512ac4 1718.Va PATH ,
984263bc 1719it is sought in the current working directory.
10185af4
PA
1720.It Ic \&[
1721A built-in equivalent of
1722.Xr test 1 .
1bd69ff1 1723.It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc Ar ... Oc
984263bc
MD
1724If
1725.Ar name Ns = Ns Ar string
1726is specified, the shell defines the alias
1727.Ar name
1728with value
1729.Ar string .
1730If just
1731.Ar name
1732is specified, the value of the alias
1733.Ar name
1734is printed.
1735With no arguments, the
1736.Ic alias
1737built-in command prints the names and values of all defined aliases
1738(see
1739.Ic unalias ) .
1740Alias values are written with appropriate quoting so that they are
1741suitable for re-input to the shell.
10185af4
PA
1742Also see the
1743.Sx Aliases
1744subsection.
984263bc
MD
1745.It Ic bg Op Ar job ...
1746Continue the specified jobs
1747(or the current job if no jobs are given)
1748in the background.
99512ac4
PA
1749.It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc
1750List or alter key bindings for the line editor.
1751This command is documented in
1752.Xr editrc 5 .
1753.It Ic break Op Ar num
1754See the
1755.Sx Flow-Control Constructs
1756subsection.
984263bc
MD
1757.It Ic builtin Ar cmd Op Ar arg ...
1758Execute the specified built-in command,
1759.Ar cmd .
1760This is useful when the user wishes to override a shell function
1761with the same name as a built-in command.
8c603ea4 1762.It Ic cd Oo Fl L | P Oc Oo Fl e Oc Op Ar directory
984263bc
MD
1763Switch to the specified
1764.Ar directory ,
1765or to the directory specified in the
99512ac4 1766.Va HOME
984263bc
MD
1767environment variable if no
1768.Ar directory
1769is specified.
1770If
1771.Ar directory
1772does not begin with
1773.Pa / , \&. ,
1774or
1775.Pa .. ,
1776then the directories listed in the
99512ac4 1777.Va CDPATH
984263bc
MD
1778variable will be
1779searched for the specified
1780.Ar directory .
1781If
99512ac4 1782.Va CDPATH
984263bc
MD
1783is unset, the current directory is searched.
1784The format of
99512ac4 1785.Va CDPATH
984263bc 1786is the same as that of
99512ac4 1787.Va PATH .
984263bc
MD
1788In an interactive shell,
1789the
1790.Ic cd
1791command will print out the name of the directory
1792that it actually switched to
1793if this is different from the name that the user gave.
1794These may be different either because the
99512ac4 1795.Va CDPATH
984263bc
MD
1796mechanism was used or because a symbolic link was crossed.
1797.Pp
1798If the
1799.Fl P
1800option is specified,
1801.Pa ..
1802is handled physically and symbolic links are resolved before
1803.Pa ..
1804components are processed.
1805If the
1806.Fl L
1807option is specified,
1808.Pa ..
1809is handled logically.
1810This is the default.
8c603ea4
PA
1811.Pp
1812The
1813.Fl e
1814option causes
1815.Ic cd
1816to return exit status 1 if the full pathname of the new directory
1817cannot be determined reliably or at all.
1818Normally this is not considered an error,
1819although a warning is printed.
984263bc
MD
1820.It Ic chdir
1821A synonym for the
1822.Ic cd
1823built-in command.
1824.It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ...
99512ac4
PA
1825.It Ic command Oo Fl p Oc Fl v Ar utility
1826.It Ic command Oo Fl p Oc Fl V Ar utility
10185af4 1827The first form of invocation executes the specified
99512ac4
PA
1828.Ar utility ,
1829ignoring shell functions in the search.
1830If
984263bc 1831.Ar utility
99512ac4
PA
1832is a special builtin,
1833it is executed as if it were a regular builtin.
984263bc
MD
1834.Pp
1835If the
1836.Fl p
1837option is specified, the command search is performed using a
1838default value of
99512ac4 1839.Va PATH
984263bc 1840that is guaranteed to find all of the standard utilities.
10185af4
PA
1841.Pp
1842If the
1843.Fl v
1844option is specified,
1845.Ar utility
1846is not executed but a description of its interpretation by the shell is
1847printed.
1848For ordinary commands the output is the path name; for shell built-in
1849commands, shell functions and keywords only the name is written.
1850Aliases are printed as
1851.Dq Ic alias Ar name Ns = Ns Ar value .
1852.Pp
1853The
1854.Fl V
1855option is identical to
1856.Fl v
1857except for the output.
1858It prints
1859.Dq Ar utility Ic is Ar description
1860where
1861.Ar description
1862is either
1863the path name to
1864.Ar utility ,
99512ac4 1865a special shell builtin,
10185af4
PA
1866a shell builtin,
1867a shell function,
1868a shell keyword
1869or
1870an alias for
8e8ff7b0 1871.Ar value .
99512ac4
PA
1872.It Ic continue Op Ar num
1873See the
1874.Sx Flow-Control Constructs
1875subsection.
10185af4
PA
1876.It Ic echo Oo Fl e | n Oc Op Ar string ...
1877Print a space-separated list of the arguments to the standard output
1878and append a newline character.
984263bc
MD
1879.Bl -tag -width indent
1880.It Fl n
1881Suppress the output of the trailing newline.
1882.It Fl e
1883Process C-style backslash escape sequences.
99512ac4 1884The
984263bc 1885.Ic echo
99512ac4 1886command understands the following character escapes:
984263bc
MD
1887.Bl -tag -width indent
1888.It \ea
1889Alert (ring the terminal bell)
1890.It \eb
1891Backspace
1892.It \ec
1893Suppress the trailing newline (this has the side-effect of truncating the
1894line if it is not the last character)
1895.It \ee
99512ac4
PA
1896The ESC character
1897.Tn ( ASCII
18980x1b)
984263bc
MD
1899.It \ef
1900Formfeed
1901.It \en
1902Newline
1903.It \er
1904Carriage return
1905.It \et
1906Horizontal tab
1907.It \ev
1908Vertical tab
1909.It \e\e
1910Literal backslash
1911.It \e0nnn
99512ac4
PA
1912(Zero) The character whose octal value is
1913.Ar nnn
984263bc
MD
1914.El
1915.Pp
1916If
1917.Ar string
1918is not enclosed in quotes then the backslash itself must be escaped
10185af4
PA
1919with a backslash to protect it from the shell.
1920For example
984263bc
MD
1921.Bd -literal -offset indent
1922$ echo -e "a\evb"
1923a
1924 b
1925$ echo -e a\e\evb
1926a
1927 b
1928$ echo -e "a\e\eb"
1929a\eb
1930$ echo -e a\e\e\e\eb
1931a\eb
1932.Ed
1933.El
1934.Pp
1935Only one of the
1936.Fl e
1937and
1938.Fl n
1939options may be specified.
1940.It Ic eval Ar string ...
1941Concatenate all the arguments with spaces.
1942Then re-parse and execute the command.
1bd69ff1 1943.It Ic exec Op Ar command Op Ar arg ...
984263bc
MD
1944Unless
1945.Ar command
1946is omitted,
1947the shell process is replaced with the specified program
1948(which must be a real program, not a shell built-in command or function).
1949Any redirections on the
1950.Ic exec
1951command are marked as permanent,
1952so that they are not undone when the
1953.Ic exec
1954command finishes.
1955.It Ic exit Op Ar exitstatus
1956Terminate the shell process.
1957If
1958.Ar exitstatus
1959is given
1de90000
PA
1960it is used as the exit status of the shell.
1961Otherwise, if the shell is executing an
99512ac4
PA
1962.Cm EXIT
1963trap, the exit status of the last command before the trap is used;
1964if the shell is executing a trap for a signal,
1de90000
PA
1965the shell exits by resending the signal to itself.
1966Otherwise, the exit status of the preceding command is used.
99512ac4 1967The exit status should be an integer between 0 and 255.
10185af4
PA
1968.It Ic export Ar name ...
1969.It Ic export Op Fl p
984263bc
MD
1970The specified names are exported so that they will
1971appear in the environment of subsequent commands.
1972The only way to un-export a variable is to
1973.Ic unset
1974it.
1975The shell allows the value of a variable to be set
1976at the same time as it is exported by writing
984263bc 1977.Pp
99512ac4
PA
1978.D1 Ic export Ar name Ns = Ns Ar value
1979.Pp
1980With no arguments the
1981.Ic export
1982command lists the names
984263bc
MD
1983of all exported variables.
1984If the
1985.Fl p
1986option is specified, the exported variables are printed as
1987.Dq Ic export Ar name Ns = Ns Ar value
1988lines, suitable for re-input to the shell.
10185af4
PA
1989.It Ic false
1990A null command that returns a non-zero (false) exit value.
984263bc
MD
1991.It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last
1992.It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last
1993.It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first
1994The
1995.Ic fc
1996built-in command lists, or edits and re-executes,
1997commands previously entered to an interactive shell.
1998.Bl -tag -width indent
1999.It Fl e Ar editor
2000Use the editor named by
2001.Ar editor
2002to edit the commands.
99512ac4
PA
2003The
2004.Ar editor
2005string is a command name,
984263bc 2006subject to search via the
99512ac4 2007.Va PATH
984263bc
MD
2008variable.
2009The value in the
99512ac4 2010.Va FCEDIT
984263bc
MD
2011variable is used as a default when
2012.Fl e
2013is not specified.
2014If
99512ac4 2015.Va FCEDIT
984263bc 2016is null or unset, the value of the
99512ac4 2017.Va EDITOR
984263bc
MD
2018variable is used.
2019If
99512ac4 2020.Va EDITOR
984263bc
MD
2021is null or unset,
2022.Xr ed 1
2023is used as the editor.
2024.It Fl l No (ell)
2025List the commands rather than invoking
10185af4
PA
2026an editor on them.
2027The commands are written in the
99512ac4
PA
2028sequence indicated by the
2029.Ar first
2030and
2031.Ar last
2032operands, as affected by
984263bc
MD
2033.Fl r ,
2034with each command preceded by the command number.
2035.It Fl n
2036Suppress command numbers when listing with
2037.Fl l .
2038.It Fl r
2039Reverse the order of the commands listed
2040(with
2041.Fl l )
2042or edited
2043(with neither
2044.Fl l
2045nor
2046.Fl s ) .
2047.It Fl s
2048Re-execute the command without invoking an editor.
2049.It Ar first
2050.It Ar last
2051Select the commands to list or edit.
2052The number of previous commands that can be accessed
2053are determined by the value of the
99512ac4 2054.Va HISTSIZE
984263bc
MD
2055variable.
2056The value of
2057.Ar first
2058or
2059.Ar last
2060or both are one of the following:
2061.Bl -tag -width indent
99512ac4 2062.It Oo Cm + Oc Ns Ar num
984263bc
MD
2063A positive number representing a command number;
2064command numbers can be displayed with the
2065.Fl l
2066option.
99512ac4 2067.It Fl Ar num
984263bc
MD
2068A negative decimal number representing the
2069command that was executed
2070.Ar num
2071of
2072commands previously.
99512ac4 2073For example, \-1 is the immediately previous command.
984263bc
MD
2074.It Ar string
2075A string indicating the most recently entered command
2076that begins with that string.
2077If the
99512ac4 2078.Ar old Ns = Ns Ar new
984263bc
MD
2079operand is not also specified with
2080.Fl s ,
2081the string form of the first operand cannot contain an embedded equal sign.
2082.El
2083.El
2084.Pp
99512ac4 2085The following variables affect the execution of
984263bc 2086.Ic fc :
99512ac4
PA
2087.Bl -tag -width ".Va HISTSIZE"
2088.It Va FCEDIT
10185af4 2089Name of the editor to use for history editing.
99512ac4 2090.It Va HISTSIZE
984263bc
MD
2091The number of previous commands that are accessible.
2092.El
2093.It Ic fg Op Ar job
2094Move the specified
2095.Ar job
2096or the current job to the foreground.
99512ac4
PA
2097.It Ic getopts Ar optstring var
2098The
2099.Tn POSIX
984263bc
MD
2100.Ic getopts
2101command.
2102The
2103.Ic getopts
2104command deprecates the older
2105.Xr getopt 1
2106command.
2107The first argument should be a series of letters, each possibly
2108followed by a colon which indicates that the option takes an argument.
10185af4
PA
2109The specified variable is set to the parsed option.
2110The index of
984263bc 2111the next argument is placed into the shell variable
99512ac4 2112.Va OPTIND .
984263bc 2113If an option takes an argument, it is placed into the shell variable
99512ac4 2114.Va OPTARG .
984263bc 2115If an invalid option is encountered,
99512ac4 2116.Ar var
984263bc 2117is set to
cca2c150 2118.Ql \&? .
984263bc
MD
2119It returns a false value (1) when it encounters the end of the options.
2120.It Ic hash Oo Fl rv Oc Op Ar command ...
2121The shell maintains a hash table which remembers the locations of commands.
2122With no arguments whatsoever, the
2123.Ic hash
2124command prints out the contents of this table.
2125Entries which have not been looked at since the last
2126.Ic cd
2127command are marked with an asterisk;
2128it is possible for these entries to be invalid.
2129.Pp
2130With arguments, the
2131.Ic hash
2132command removes each specified
2133.Ar command
2134from the hash table (unless they are functions) and then locates it.
2135With the
2136.Fl v
2137option,
2138.Ic hash
2139prints the locations of the commands as it finds them.
2140The
2141.Fl r
2142option causes the
2143.Ic hash
2144command to delete all the entries in the hash table except for functions.
2145.It Ic jobid Op Ar job
99512ac4 2146Print the process IDs of the processes in the specified
984263bc
MD
2147.Ar job .
2148If the
2149.Ar job
2150argument is omitted, use the current job.
9d7989de 2151.It Ic jobs Oo Fl lps Oc Op Ar job ...
984263bc
MD
2152Print information about the specified jobs, or all jobs if no
2153.Ar job
2154argument is given.
2155The information printed includes job ID, status and command name.
2156.Pp
2157If the
2158.Fl l
2159option is specified, the PID of each job is also printed.
2160If the
9d7989de
PA
2161.Fl p
2162option is specified, only the process IDs for the process group leaders
2163are printed, one per line.
2164If the
984263bc 2165.Fl s
9d7989de
PA
2166option is specified, only the PIDs of the job commands are printed, one per
2167line.
99512ac4
PA
2168.It Ic kill
2169A built-in equivalent of
2170.Xr kill 1
2171that additionally supports sending signals to jobs.
10185af4
PA
2172.It Ic local Oo Ar variable ... Oc Op Fl
2173See the
2174.Sx Functions
2175subsection.
99512ac4
PA
2176.It Ic printf
2177A built-in equivalent of
2178.Xr printf 1 .
10185af4
PA
2179.It Ic pwd Op Fl L | P
2180Print the path of the current directory.
2181The built-in command may
984263bc
MD
2182differ from the program of the same name because the
2183built-in command remembers what the current directory
10185af4
PA
2184is rather than recomputing it each time.
2185This makes
2186it faster.
2187However, if the current directory is
984263bc
MD
2188renamed,
2189the built-in version of
2190.Xr pwd 1
2191will continue to print the old name for the directory.
2192.Pp
2193If the
2194.Fl P
2195option is specified, symbolic links are resolved.
2196If the
2197.Fl L
2198option is specified, the shell's notion of the current directory
2199is printed (symbolic links are not resolved).
2200This is the default.
99512ac4
PA
2201.It Ic read Oo Fl p Ar prompt Oc Oo
2202.Fl t Ar timeout Oc Oo Fl er Oc Ar variable ...
984263bc
MD
2203The
2204.Ar prompt
2205is printed if the
2206.Fl p
2207option is specified
10185af4
PA
2208and the standard input is a terminal.
2209Then a line is
2210read from the standard input.
2211The trailing newline
984263bc
MD
2212is deleted from the line and the line is split as
2213described in the section on
2214.Sx White Space Splitting (Field Splitting)
2215above, and
2216the pieces are assigned to the variables in order.
2217If there are more pieces than variables, the remaining
2218pieces (along with the characters in
99512ac4 2219.Va IFS
984263bc
MD
2220that separated them)
2221are assigned to the last variable.
2222If there are more variables than pieces, the remaining
2223variables are assigned the null string.
2224.Pp
2225Backslashes are treated specially, unless the
2226.Fl r
2227option is
10185af4
PA
2228specified.
2229If a backslash is followed by
984263bc 2230a newline, the backslash and the newline will be
10185af4
PA
2231deleted.
2232If a backslash is followed by any other
984263bc
MD
2233character, the backslash will be deleted and the following
2234character will be treated as though it were not in
99512ac4 2235.Va IFS ,
984263bc
MD
2236even if it is.
2237.Pp
2238If the
2239.Fl t
2240option is specified and the
2241.Ar timeout
99512ac4 2242elapses before a complete line of input is supplied,
984263bc
MD
2243the
2244.Ic read
10185af4 2245command will return an exit status of 1 without assigning any values.
984263bc
MD
2246The
2247.Ar timeout
2248value may optionally be followed by one of
cca2c150
TN
2249.Ql s ,
2250.Ql m
984263bc 2251or
cca2c150 2252.Ql h
984263bc
MD
2253to explicitly specify seconds, minutes or hours.
2254If none is supplied,
cca2c150 2255.Ql s
984263bc
MD
2256is assumed.
2257.Pp
2258The
2259.Fl e
2260option exists only for backward compatibility with older scripts.
2261.It Ic readonly Oo Fl p Oc Op Ar name ...
2262Each specified
2263.Ar name
2264is marked as read only,
2265so that it cannot be subsequently modified or unset.
2266The shell allows the value of a variable to be set
2267at the same time as it is marked read only
2268by using the following form:
99512ac4
PA
2269.Pp
2270.D1 Ic readonly Ar name Ns = Ns Ar value
984263bc
MD
2271.Pp
2272With no arguments the
2273.Ic readonly
2274command lists the names of all read only variables.
2275If the
2276.Fl p
2277option is specified, the read-only variables are printed as
2278.Dq Ic readonly Ar name Ns = Ns Ar value
2279lines, suitable for re-input to the shell.
10185af4
PA
2280.It Ic return Op Ar exitstatus
2281See the
2282.Sx Functions
2283subsection.
984263bc
MD
2284.It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo
2285.Fl c Ar string Oc Op Fl - Ar arg ...
2286The
2287.Ic set
2288command performs three different functions:
2289.Bl -item
2290.It
2291With no arguments, it lists the values of all shell variables.
2292.It
2293If options are given,
2294either in short form or using the long
2295.Dq Fl /+o Ar longname
2296form,
2297it sets or clears the specified options as described in the section called
2298.Sx Argument List Processing .
2299.It
2300If the
2301.Dq Fl -
2302option is specified,
2303.Ic set
2304will replace the shell's positional parameters with the subsequent
2305arguments.
2306If no arguments follow the
2307.Dq Fl -
2308option,
2309all the positional parameters will be cleared,
2310which is equivalent to executing the command
99512ac4 2311.Dq Li "shift $#" .
984263bc
MD
2312The
2313.Dq Fl -
2314flag may be omitted when specifying arguments to be used
2315as positional replacement parameters.
2316This is not recommended,
2317because the first argument may begin with a dash
10185af4 2318.Pq Ql -
984263bc 2319or a plus
10185af4 2320.Pq Ql + ,
984263bc
MD
2321which the
2322.Ic set
2323command will interpret as a request to enable or disable options.
2324.El
99512ac4 2325.It Ic setvar Ar variable value
984263bc
MD
2326Assigns the specified
2327.Ar value
2328to the specified
2329.Ar variable .
99512ac4
PA
2330The
2331.Ic setvar
2332command is intended to be used in functions that
984263bc
MD
2333assign values to variables whose names are passed as parameters.
2334In general it is better to write
99512ac4 2335.Dq Ar variable Ns = Ns Ar value
984263bc
MD
2336rather than using
2337.Ic setvar .
2338.It Ic shift Op Ar n
2339Shift the positional parameters
2340.Ar n
2341times, or once if
2342.Ar n
2343is not specified.
99512ac4
PA
2344A shift sets the value of
2345.Li $1
2346to the value of
2347.Li $2 ,
2348the value of
2349.Li $2
2350to the value of
2351.Li $3 ,
2352and so on,
2353decreasing the value of
2354.Li $#
2355by one.
984263bc 2356If there are zero positional parameters, shifting does not do anything.
10185af4
PA
2357.It Ic test
2358A built-in equivalent of
2359.Xr test 1 .
0d5aaed6
PA
2360.It Ic times
2361Print the amount of time spent executing the shell and its children.
2362The first output line shows the user and system times for the shell
2363itself, the second one contains the user and system times for the
2364children.
984263bc 2365.It Ic trap Oo Ar action Oc Ar signal ...
10185af4 2366.It Ic trap Fl l
984263bc
MD
2367Cause the shell to parse and execute
2368.Ar action
2369when any specified
2370.Ar signal
2371is received.
2372The signals are specified by name or number.
2373In addition, the pseudo-signal
2374.Cm EXIT
99512ac4
PA
2375may be used to specify an
2376.Ar action
2377that is performed when the shell terminates.
984263bc
MD
2378The
2379.Ar action
10185af4
PA
2380may be an empty string or a dash
2381.Pq Ql - ;
984263bc
MD
2382the former causes the specified signal to be ignored
2383and the latter causes the default action to be taken.
10185af4
PA
2384Omitting the
2385.Ar action
2386is another way to request the default action, for compatibility reasons this
2387usage is not recommended though.
1de90000
PA
2388In a subshell environment,
2389the shell resets trapped (but not ignored) signals to the default action.
984263bc
MD
2390The
2391.Ic trap
2392command has no effect on signals that were ignored on entry to the shell.
10185af4
PA
2393.Pp
2394Option
2395.Fl l
2396causes the
2397.Ic trap
2398command to display a list of valid signal names.
2399.It Ic true
2400A null command that returns a 0 (true) exit value.
984263bc
MD
2401.It Ic type Op Ar name ...
2402Interpret each
2403.Ar name
2404as a command and print the resolution of the command search.
2405Possible resolutions are:
99512ac4
PA
2406shell keyword, alias, special shell builtin, shell builtin, command,
2407tracked alias
984263bc
MD
2408and not found.
2409For aliases the alias expansion is printed;
2410for commands and tracked aliases
2411the complete pathname of the command is printed.
2412.It Ic ulimit Oo Fl HSabcdflmnstuv Oc Op Ar limit
2413Set or display resource limits (see
2414.Xr getrlimit 2 ) .
2415If
2416.Ar limit
2417is specified, the named resource will be set;
2418otherwise the current resource value will be displayed.
2419.Pp
2420If
2421.Fl H
2422is specified, the hard limits will be set or displayed.
2423While everybody is allowed to reduce a hard limit,
2424only the superuser can increase it.
2425The
2426.Fl S
2427option
10185af4
PA
2428specifies the soft limits instead.
2429When displaying limits,
984263bc
MD
2430only one of
2431.Fl S
2432or
2433.Fl H
2434can be given.
2435The default is to display the soft limits,
2436and to set both the hard and the soft limits.
2437.Pp
2438Option
2439.Fl a
2440causes the
2441.Ic ulimit
2442command to display all resources.
2443The parameter
2444.Ar limit
2445is not acceptable in this mode.
2446.Pp
2447The remaining options specify which resource value is to be
2448displayed or modified.
2449They are mutually exclusive.
2450.Bl -tag -width indent
2451.It Fl b Ar sbsize
2452The maximum size of socket buffer usage, in bytes.
2453.It Fl c Ar coredumpsize
2454The maximal size of core dump files, in 512-byte blocks.
2455.It Fl d Ar datasize
2456The maximal size of the data segment of a process, in kilobytes.
2457.It Fl f Ar filesize
2458The maximal size of a file, in 512-byte blocks.
2459.It Fl l Ar lockedmem
2460The maximal size of memory that can be locked by a process, in
2461kilobytes.
2462.It Fl m Ar memoryuse
2463The maximal resident set size of a process, in kilobytes.
2464.It Fl n Ar nofiles
2465The maximal number of descriptors that could be opened by a process.
2466.It Fl s Ar stacksize
2467The maximal size of the stack segment, in kilobytes.
2468.It Fl t Ar time
2469The maximal amount of CPU time to be used by each process, in seconds.
2470.It Fl u Ar userproc
2471The maximal number of simultaneous processes for this user ID.
2472.It Fl v Ar virtualmem
2473The maximal virtual size of a process, in kilobytes.
2474.El
10185af4 2475.It Ic umask Oo Fl S Oc Op Ar mask
984263bc
MD
2476Set the file creation mask (see
2477.Xr umask 2 )
10185af4
PA
2478to the octal or symbolic (see
2479.Xr chmod 1 )
2480value specified by
984263bc
MD
2481.Ar mask .
2482If the argument is omitted, the current mask value is printed.
10185af4
PA
2483If the
2484.Fl S
2485option is specified, the output is symbolic, otherwise the output is octal.
2486.It Ic unalias Oo Fl a Oc Op Ar name ...
2487The specified alias names are removed.
984263bc
MD
2488If
2489.Fl a
2490is specified, all aliases are removed.
2491.It Ic unset Oo Fl fv Oc Ar name ...
2492The specified variables or functions are unset and unexported.
2493If the
2494.Fl v
2495option is specified or no options are given, the
2496.Ar name
2497arguments are treated as variable names.
2498If the
2499.Fl f
2500option is specified, the
2501.Ar name
2502arguments are treated as function names.
2503.It Ic wait Op Ar job
2504Wait for the specified
2505.Ar job
2506to complete and return the exit status of the last process in the
2507.Ar job .
2508If the argument is omitted, wait for all jobs to complete
2509and return an exit status of zero.
2510.El
2511.Ss Commandline Editing
2512When
2513.Nm
2514is being used interactively from a terminal, the current command
2515and the command history
2516(see
2517.Ic fc
2518in
2519.Sx Built-in Commands )
99512ac4
PA
2520can be edited using
2521.Nm vi Ns -mode
2522command line editing.
984263bc 2523This mode uses commands similar
99512ac4
PA
2524to a subset of those described in the
2525.Xr vi 1
2526man page.
984263bc 2527The command
99512ac4 2528.Dq Li "set -o vi"
984263bc 2529(or
99512ac4
PA
2530.Dq Li "set -V" )
2531enables
2532.Nm vi Ns -mode
2533editing and places
984263bc 2534.Nm
99512ac4
PA
2535into
2536.Nm vi
2537insert mode.
2538With
2539.Nm vi Ns -mode
2540enabled,
984263bc
MD
2541.Nm
2542can be switched between insert mode and command mode by typing
2543.Aq ESC .
2544Hitting
2545.Aq return
2546while in command mode will pass the line to the shell.
2547.Pp
2548Similarly, the
99512ac4 2549.Dq Li "set -o emacs"
984263bc 2550(or
99512ac4 2551.Dq Li "set -E" )
984263bc 2552command can be used to enable a subset of
99512ac4
PA
2553.Nm emacs Ns -style
2554command line editing features.
10185af4
PA
2555.Sh ENVIRONMENT
2556The following environment variables affect the execution of
2557.Nm :
99512ac4
PA
2558.Bl -tag -width ".Ev LANGXXXXXX"
2559.It Ev ENV
2560Initialization file for interactive shells.
2561.It Ev LANG , Ev LC_*
2562Locale settings.
2563These are inherited by children of the shell,
2564and is used in a limited manner by the shell itself.
2565.It Ev PWD
2566An absolute pathname for the current directory,
2567possibly containing symbolic links.
2568This is used and updated by the shell.
10185af4
PA
2569.It Ev TERM
2570The default terminal setting for the shell.
2571This is inherited by children of the shell, and is used in the history
2572editing modes.
2573.El
99512ac4
PA
2574.Pp
2575Additionally, all environment variables are turned into shell variables
2576at startup,
2577which may affect the shell as described under
2578.Sx Special Variables .
10185af4
PA
2579.Sh EXIT STATUS
2580Errors that are detected by the shell, such as a syntax error, will
2581cause the shell to exit with a non-zero exit status.
2582If the shell is not an interactive shell, the execution of the shell
2583file will be aborted.
2584Otherwise the shell will return the exit status of the last command
99512ac4
PA
2585executed, or if the
2586.Ic exit
2587builtin is used with a numeric argument, it
10185af4 2588will return the argument.
984263bc
MD
2589.Sh SEE ALSO
2590.Xr builtin 1 ,
10185af4 2591.Xr chsh 1 ,
984263bc 2592.Xr echo 1 ,
10185af4 2593.Xr ed 1 ,
7cd7d057 2594.Xr emacs 1 Pq Pa pkgsrc/editors/emacs ,
99512ac4 2595.Xr kill 1 ,
984263bc
MD
2596.Xr printf 1 ,
2597.Xr pwd 1 ,
10185af4
PA
2598.Xr test 1 ,
2599.Xr vi 1 ,
2600.Xr execve 2 ,
2601.Xr getrlimit 2 ,
2602.Xr umask 2 ,
215809b7 2603.Xr wctype 3 ,
e0bca924
SW
2604.Xr editrc 5 ,
2605.Xr script 7
984263bc
MD
2606.Sh HISTORY
2607A
2608.Nm
10185af4 2609command, the Thompson shell, appeared in
984263bc 2610.At v1 .
10185af4
PA
2611It was superseded in
2612.At v7
2613by the Bourne shell, which inherited the name
2614.Nm .
2615.Pp
2616This version of
2617.Nm
2618was rewritten in 1989 under the
2619.Bx
2620license after the Bourne shell from
2621.At V.4 .
2622.Sh AUTHORS
2623This version of
2624.Nm
2625was originally written by
2626.An Kenneth Almquist .
2627.Sh BUGS
2628The
2629.Nm
7602056e
PA
2630utility does not recognize multibyte characters other than UTF-8.
2631Splitting using
2632.Va IFS
2633and the line editing library
2634.Xr editline 3
2635do not recognize multibyte characters.
3f2d021a
YT
2636.Pp
2637The characters generated by filename completion should probably be quoted
2638to ensure that the filename is still valid after the input line has been
2639processed.