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