VirtualBox

source: kBuild/trunk/src/kash/sh.1@ 2654

Last change on this file since 2654 was 1233, checked in by bird, 17 years ago

keywords.

  • Property svn:eol-style set to LF
  • Property svn:keywords set to Id
File size: 56.2 KB
Line 
1.\" $NetBSD: sh.1,v 1.80 2005/05/24 00:03:52 wiz Exp $
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. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)sh.1 8.6 (Berkeley) 5/4/95
33.\"
34.Dd May 7, 2005
35.Os
36.Dt SH 1
37.Sh NAME
38.Nm sh
39.Nd command interpreter (shell)
40.Sh SYNOPSIS
41.Nm
42.Bk -words
43.Op Fl aCefnuvxIimqVEb
44.Op Cm +aCefnuvxIimqVEb
45.Ek
46.Bk -words
47.Op Fl o Ar option_name
48.Op Cm +o Ar option_name
49.Ek
50.Bk -words
51.Op Ar command_file Oo Ar argument ... Oc
52.Ek
53.Nm
54.Fl c
55.Bk -words
56.Op Fl aCefnuvxIimqVEb
57.Op Cm +aCefnuvxIimqVEb
58.Ek
59.Bk -words
60.Op Fl o Ar option_name
61.Op Cm +o Ar option_name
62.Ek
63.Bk -words
64.Ar command_string
65.Op Ar command_name Oo Ar argument ... Oc
66.Ek
67.Nm
68.Fl s
69.Bk -words
70.Op Fl aCefnuvxIimqVEb
71.Op Cm +aCefnuvxIimqVEb
72.Ek
73.Bk -words
74.Op Fl o Ar option_name
75.Op Cm +o Ar option_name
76.Ek
77.Bk -words
78.Op Ar argument ...
79.Ek
80.Sh DESCRIPTION
81.Nm
82is the standard command interpreter for the system.
83The current version of
84.Nm
85is in the process of being changed to conform with the
86.Tn POSIX
871003.2 and 1003.2a specifications for the shell.
88This version has many
89features which make it appear similar in some respects to the Korn shell,
90but it is not a Korn shell clone (see
91.Xr ksh 1 ) .
92Only features designated by
93.Tn POSIX ,
94plus a few Berkeley extensions, are being incorporated into this shell.
95.\" We expect
96.\" .Tn POSIX
97.\" conformance by the time 4.4 BSD is released.
98This man page is not intended
99to be a tutorial or a complete specification of the shell.
100.Ss Overview
101The shell is a command that reads lines from either a file or the
102terminal, interprets them, and generally executes other commands.
103It is the program that is running when a user logs into the system
104(although a user can select a different shell with the
105.Xr chsh 1
106command).
107The shell implements a language that has flow control
108constructs, a macro facility that provides a variety of features in
109addition to data storage, along with built in history and line editing
110capabilities.
111It incorporates many features to aid interactive use and
112has the advantage that the interpretative language is common to both
113interactive and non-interactive use (shell scripts).
114That is, commands
115can be typed directly to the running shell or can be put into a file and
116the file can be executed directly by the shell.
117.Ss Invocation
118If no args are present and if the standard input of the shell
119is connected to a terminal (or if the
120.Fl i
121flag is set),
122and the
123.Fl c
124option is not present, the shell is considered an interactive shell.
125An interactive shell generally prompts before each command and handles
126programming and command errors differently (as described below).
127When first starting,
128the shell inspects argument 0, and if it begins with a dash
129.Sq - ,
130the shell is also considered
131a login shell.
132This is normally done automatically by the system
133when the user first logs in.
134A login shell first reads commands
135from the files
136.Pa /etc/profile
137and
138.Pa .profile
139if they exist.
140If the environment variable
141.Ev ENV
142is set on entry to a shell, or is set in the
143.Pa .profile
144of a login shell, the shell next reads
145commands from the file named in
146.Ev ENV .
147Therefore, a user should place commands that are to be executed only at
148login time in the
149.Pa .profile
150file, and commands that are executed for every shell inside the
151.Ev ENV
152file.
153To set the
154.Ev ENV
155variable to some file, place the following line in your
156.Pa .profile
157of your home directory
158.Pp
159.Dl ENV=$HOME/.shinit; export ENV
160.Pp
161substituting for
162.Dq .shinit
163any filename you wish.
164Since the
165.Ev ENV
166file is read for every invocation of the shell, including shell scripts
167and non-interactive shells, the following paradigm is useful for
168restricting commands in the
169.Ev ENV
170file to interactive invocations.
171Place commands within the
172.Dq case
173and
174.Dq esac
175below (these commands are described later):
176.Pp
177.Bl -item -compact -offset indent
178.It
179.Li case $- in *i*)
180.Bl -item -compact -offset indent
181.It
182.Li # commands for interactive use only
183.It
184.Li ...
185.El
186.It
187.Li esac
188.El
189.Pp
190If command line arguments besides the options have been specified, then
191the shell treats the first argument as the name of a file from which to
192read commands (a shell script), and the remaining arguments are set as the
193positional parameters of the shell ($1, $2, etc).
194Otherwise, the shell
195reads commands from its standard input.
196.Ss Argument List Processing
197All of the single letter options have a corresponding name that can be
198used as an argument to the
199.Fl o
200option.
201The set
202.Fl o
203name is provided next to the single letter option in
204the description below.
205Specifying a dash
206.Dq -
207turns the option on, while using a plus
208.Dq +
209disables the option.
210The following options can be set from the command line or
211with the
212.Ic set
213builtin (described later).
214.Bl -tag -width aaaallexportfoo -offset indent
215.It Fl a Em allexport
216Export all variables assigned to.
217.It Fl c
218Read commands from the
219.Ar command_string
220operand instead of from the standard input.
221Special parameter 0 will be set from the
222.Ar command_name
223operand and the positional parameters ($1, $2, etc.)
224set from the remaining argument operands.
225.It Fl C Em noclobber
226Don't overwrite existing files with
227.Dq \*[Gt] .
228.It Fl e Em errexit
229If not interactive, exit immediately if any untested command fails.
230The exit status of a command is considered to be
231explicitly tested if the command is used to control an
232.Ic if ,
233.Ic elif ,
234.Ic while ,
235or
236.Ic until ;
237or if the command is the left hand operand of an
238.Dq \*[Am]\*[Am]
239or
240.Dq ||
241operator.
242.It Fl f Em noglob
243Disable pathname expansion.
244.It Fl n Em noexec
245If not interactive, read commands but do not execute them.
246This is useful for checking the syntax of shell scripts.
247.It Fl u Em nounset
248Write a message to standard error when attempting to expand a variable
249that is not set, and if the shell is not interactive, exit immediately.
250.It Fl v Em verbose
251The shell writes its input to standard error as it is read.
252Useful for debugging.
253.It Fl x Em xtrace
254Write each command to standard error (preceded by a
255.Sq +\ )
256before it is executed.
257Useful for debugging.
258.It Fl q Em quietprofile
259If the
260.Fl v
261or
262.Fl x
263options have been set, do not apply them when reading
264initialization files, these being
265.Pa /etc/profile ,
266.Pa .profile ,
267and the file specified by the
268.Ev ENV
269environment variable.
270.It Fl I Em ignoreeof
271Ignore EOF's from input when interactive.
272.It Fl i Em interactive
273Force the shell to behave interactively.
274.It Fl m Em monitor
275Turn on job control (set automatically when interactive).
276.It Fl s Em stdin
277Read commands from standard input (set automatically if no file arguments
278are present).
279This option has no effect when set after the shell has
280already started running (i.e. with
281.Ic set ) .
282.It Fl V Em vi
283Enable the built-in
284.Xr vi 1
285command line editor (disables
286.Fl E
287if it has been set).
288(See the
289.Sx Command Line Editing
290section below.)
291.It Fl E Em emacs
292Enable the built-in emacs style
293command line editor (disables
294.Fl V
295if it has been set).
296(See the
297.Sx Command Line Editing
298section below.)
299.It Fl b Em notify
300Enable asynchronous notification of background job completion.
301(UNIMPLEMENTED for 4.4alpha)
302.It "\ \ " Em cdprint
303Make an interactive shell always print the new directory name when
304changed by the
305.Ic cd
306command.
307.It "\ \ " Em tabcomplete
308Enables filename completion in the command line editor.
309Typing a tab character will extend the current input word to match a
310filename.
311If more than one filename matches it is only extended to be the common prefix.
312Typing a second tab character will list all the matching names.
313.El
314.Ss Lexical Structure
315The shell reads input in terms of lines from a file and breaks it up into
316words at whitespace (blanks and tabs), and at certain sequences of
317characters that are special to the shell called
318.Dq operators .
319There are two types of operators: control operators and redirection
320operators (their meaning is discussed later).
321Following is a list of operators:
322.Bl -ohang -offset indent
323.It "Control operators:"
324.Dl \*[Am] \*[Am]\*[Am] \&( \&) \&; ;; | || \*[Lt]newline\*[Gt]
325.It "Redirection operators:"
326.Dl \*[Lt] \*[Gt] \*[Gt]| \*[Lt]\*[Lt] \*[Gt]\*[Gt] \*[Lt]\*[Am] \*[Gt]\*[Am] \*[Lt]\*[Lt]- \*[Lt]\*[Gt]
327.El
328.Ss Quoting
329Quoting is used to remove the special meaning of certain characters or
330words to the shell, such as operators, whitespace, or keywords.
331There are three types of quoting: matched single quotes,
332matched double quotes, and backslash.
333.Ss Backslash
334A backslash preserves the literal meaning of the following
335character, with the exception of
336.Aq newline .
337A backslash preceding a
338.Aq newline
339is treated as a line continuation.
340.Ss Single Quotes
341Enclosing characters in single quotes preserves the literal meaning of all
342the characters (except single quotes, making it impossible to put
343single-quotes in a single-quoted string).
344.Ss Double Quotes
345Enclosing characters within double quotes preserves the literal
346meaning of all characters except dollarsign
347.Pq $ ,
348backquote
349.Pq ` ,
350and backslash
351.Pq \e .
352The backslash inside double quotes is historically weird, and serves to
353quote only the following characters:
354.Dl $ ` \*q \e \*[Lt]newline\*[Gt] .
355Otherwise it remains literal.
356.Ss Reserved Words
357Reserved words are words that have special meaning to the
358shell and are recognized at the beginning of a line and
359after a control operator.
360The following are reserved words:
361.Bl -column while while while while while -offset indent
362.It ! Ta elif Ta fi Ta while Ta case
363.It else Ta for Ta then Ta { Ta }
364.It do Ta done Ta until Ta if Ta esac
365.El
366.Pp
367Their meaning is discussed later.
368.Ss Aliases
369An alias is a name and corresponding value set using the
370.Ic alias
371builtin command.
372Whenever a reserved word may occur (see above),
373and after checking for reserved words, the shell
374checks the word to see if it matches an alias.
375If it does, it replaces it in the input stream with its value.
376For example, if there is an alias called
377.Dq lf
378with the value
379.Dq "ls -F" ,
380then the input:
381.Pp
382.Dl lf foobar Aq return
383.Pp
384would become
385.Pp
386.Dl ls -F foobar Aq return
387.Pp
388Aliases provide a convenient way for naive users to create shorthands for
389commands without having to learn how to create functions with arguments.
390They can also be used to create lexically obscure code.
391This use is discouraged.
392.Ss Commands
393The shell interprets the words it reads according to a language, the
394specification of which is outside the scope of this man page (refer to the
395BNF in the
396.Tn POSIX
3971003.2 document).
398Essentially though, a line is read and if the first
399word of the line (or after a control operator) is not a reserved word,
400then the shell has recognized a simple command.
401Otherwise, a complex
402command or some other special construct may have been recognized.
403.Ss Simple Commands
404If a simple command has been recognized, the shell performs
405the following actions:
406.Bl -enum -offset indent
407.It
408Leading words of the form
409.Dq name=value
410are stripped off and assigned to the environment of the simple command.
411Redirection operators and their arguments (as described below) are
412stripped off and saved for processing.
413.It
414The remaining words are expanded as described in
415the section called
416.Dq Expansions ,
417and the first remaining word is considered the command name and the
418command is located.
419The remaining words are considered the arguments of the command.
420If no command name resulted, then the
421.Dq name=value
422variable assignments recognized in item 1 affect the current shell.
423.It
424Redirections are performed as described in the next section.
425.El
426.Ss Redirections
427Redirections are used to change where a command reads its input or sends
428its output.
429In general, redirections open, close, or duplicate an
430existing reference to a file.
431The overall format used for redirection is:
432.Pp
433.Dl [n] Va redir-op Ar file
434.Pp
435where
436.Va redir-op
437is one of the redirection operators mentioned previously.
438Following is a list of the possible redirections.
439The
440.Bq n
441is an optional number, as in
442.Sq 3
443(not
444.Sq Bq 3 ) ,
445that refers to a file descriptor.
446.Bl -tag -width aaabsfiles -offset indent
447.It [n] Ns \*[Gt] file
448Redirect standard output (or n) to file.
449.It [n] Ns \*[Gt]| file
450Same, but override the
451.Fl C
452option.
453.It [n] Ns \*[Gt]\*[Gt] file
454Append standard output (or n) to file.
455.It [n] Ns \*[Lt] file
456Redirect standard input (or n) from file.
457.It [n1] Ns \*[Lt]\*[Am] Ns n2
458Duplicate standard input (or n1) from file descriptor n2.
459.It [n] Ns \*[Lt]\*[Am]-
460Close standard input (or n).
461.It [n1] Ns \*[Gt]\*[Am] Ns n2
462Duplicate standard output (or n1) to n2.
463.It [n] Ns \*[Gt]\*[Am]-
464Close standard output (or n).
465.It [n] Ns \*[Lt]\*[Gt] file
466Open file for reading and writing on standard input (or n).
467.El
468.Pp
469The following redirection is often called a
470.Dq here-document .
471.Bl -item -offset indent
472.It
473.Li [n]\*[Lt]\*[Lt] delimiter
474.Dl here-doc-text ...
475.Li delimiter
476.El
477.Pp
478All the text on successive lines up to the delimiter is saved away and
479made available to the command on standard input, or file descriptor n if
480it is specified.
481If the delimiter as specified on the initial line is
482quoted, then the here-doc-text is treated literally, otherwise the text is
483subjected to parameter expansion, command substitution, and arithmetic
484expansion (as described in the section on
485.Dq Expansions ) .
486If the operator is
487.Dq \*[Lt]\*[Lt]-
488instead of
489.Dq \*[Lt]\*[Lt] ,
490then leading tabs in the here-doc-text are stripped.
491.Ss Search and Execution
492There are three types of commands: shell functions, builtin commands, and
493normal programs -- and the command is searched for (by name) in that order.
494They each are executed in a different way.
495.Pp
496When a shell function is executed, all of the shell positional parameters
497(except $0, which remains unchanged) are set to the arguments of the shell
498function.
499The variables which are explicitly placed in the environment of
500the command (by placing assignments to them before the function name) are
501made local to the function and are set to the values given.
502Then the command given in the function definition is executed.
503The positional parameters are restored to their original values
504when the command completes.
505This all occurs within the current shell.
506.Pp
507Shell builtins are executed internally to the shell, without spawning a
508new process.
509.Pp
510Otherwise, if the command name doesn't match a function or builtin, the
511command is searched for as a normal program in the file system (as
512described in the next section).
513When a normal program is executed, the shell runs the program,
514passing the arguments and the environment to the program.
515If the program is not a normal executable file (i.e., if it does
516not begin with the "magic number" whose
517.Tn ASCII
518representation is "#!", so
519.Xr execve 2
520returns
521.Er ENOEXEC
522then) the shell will interpret the program in a subshell.
523The child shell will reinitialize itself in this case,
524so that the effect will be as if a
525new shell had been invoked to handle the ad-hoc shell script, except that
526the location of hashed commands located in the parent shell will be
527remembered by the child.
528.Pp
529Note that previous versions of this document and the source code itself
530misleadingly and sporadically refer to a shell script without a magic
531number as a "shell procedure".
532.Ss Path Search
533When locating a command, the shell first looks to see if it has a shell
534function by that name.
535Then it looks for a builtin command by that name.
536If a builtin command is not found, one of two things happen:
537.Bl -enum
538.It
539Command names containing a slash are simply executed without performing
540any searches.
541.It
542The shell searches each entry in
543.Ev PATH
544in turn for the command.
545The value of the
546.Ev PATH
547variable should be a series of entries separated by colons.
548Each entry consists of a directory name.
549The current directory may be indicated
550implicitly by an empty directory name, or explicitly by a single period.
551.El
552.Ss Command Exit Status
553Each command has an exit status that can influence the behavior
554of other shell commands.
555The paradigm is that a command exits
556with zero for normal or success, and non-zero for failure,
557error, or a false indication.
558The man page for each command
559should indicate the various exit codes and what they mean.
560Additionally, the builtin commands return exit codes, as does
561an executed shell function.
562.Pp
563If a command consists entirely of variable assignments then the
564exit status of the command is that of the last command substitution
565if any, otherwise 0.
566.Ss Complex Commands
567Complex commands are combinations of simple commands with control
568operators or reserved words, together creating a larger complex command.
569More generally, a command is one of the following:
570.Bl -bullet
571.It
572simple command
573.It
574pipeline
575.It
576list or compound-list
577.It
578compound command
579.It
580function definition
581.El
582.Pp
583Unless otherwise stated, the exit status of a command is that of the last
584simple command executed by the command.
585.Ss Pipelines
586A pipeline is a sequence of one or more commands separated
587by the control operator |.
588The standard output of all but
589the last command is connected to the standard input
590of the next command.
591The standard output of the last
592command is inherited from the shell, as usual.
593.Pp
594The format for a pipeline is:
595.Pp
596.Dl [!] command1 [ | command2 ...]
597.Pp
598The standard output of command1 is connected to the standard input of
599command2.
600The standard input, standard output, or both of a command is
601considered to be assigned by the pipeline before any redirection specified
602by redirection operators that are part of the command.
603.Pp
604If the pipeline is not in the background (discussed later), the shell
605waits for all commands to complete.
606.Pp
607If the reserved word ! does not precede the pipeline, the exit status is
608the exit status of the last command specified in the pipeline.
609Otherwise, the exit status is the logical NOT of the exit status of the
610last command.
611That is, if the last command returns zero, the exit status
612is 1; if the last command returns greater than zero, the exit status is
613zero.
614.Pp
615Because pipeline assignment of standard input or standard output or both
616takes place before redirection, it can be modified by redirection.
617For example:
618.Pp
619.Dl $ command1 2\*[Gt]\*[Am]1 | command2
620.Pp
621sends both the standard output and standard error of command1
622to the standard input of command2.
623.Pp
624A ; or
625.Aq newline
626terminator causes the preceding AND-OR-list (described
627next) to be executed sequentially; a \*[Am] causes asynchronous execution of
628the preceding AND-OR-list.
629.Pp
630Note that unlike some other shells, each process in the pipeline is a
631child of the invoking shell (unless it is a shell builtin, in which case
632it executes in the current shell -- but any effect it has on the
633environment is wiped).
634.Ss Background Commands -- \*[Am]
635If a command is terminated by the control operator ampersand (\*[Am]), the
636shell executes the command asynchronously -- that is, the shell does not
637wait for the command to finish before executing the next command.
638.Pp
639The format for running a command in background is:
640.Pp
641.Dl command1 \*[Am] [command2 \*[Am] ...]
642.Pp
643If the shell is not interactive, the standard input of an asynchronous
644command is set to
645.Pa /dev/null .
646.Ss Lists -- Generally Speaking
647A list is a sequence of zero or more commands separated by newlines,
648semicolons, or ampersands, and optionally terminated by one of these three
649characters.
650The commands in a list are executed in the order they are written.
651If command is followed by an ampersand, the shell starts the
652command and immediately proceed onto the next command; otherwise it waits
653for the command to terminate before proceeding to the next one.
654.Ss Short-Circuit List Operators
655.Dq \*[Am]\*[Am]
656and
657.Dq ||
658are AND-OR list operators.
659.Dq \*[Am]\*[Am]
660executes the first command, and then executes the second command if and only
661if the exit status of the first command is zero.
662.Dq ||
663is similar, but executes the second command if and only if the exit status
664of the first command is nonzero.
665.Dq \*[Am]\*[Am]
666and
667.Dq ||
668both have the same priority.
669Note that these operators are left-associative, so
670.Dq true || echo bar && echo baz
671writes
672.Dq baz
673and nothing else.
674This is not the way it works in C.
675.Ss Flow-Control Constructs -- if, while, for, case
676The syntax of the if command is
677.Bd -literal -offset indent
678if list
679then list
680[ elif list
681then list ] ...
682[ else list ]
683fi
684.Ed
685.Pp
686The syntax of the while command is
687.Bd -literal -offset indent
688while list
689do list
690done
691.Ed
692.Pp
693The two lists are executed repeatedly while the exit status of the
694first list is zero.
695The until command is similar, but has the word
696until in place of while, which causes it to
697repeat until the exit status of the first list is zero.
698.Pp
699The syntax of the for command is
700.Bd -literal -offset indent
701for variable in word ...
702do list
703done
704.Ed
705.Pp
706The words are expanded, and then the list is executed repeatedly with the
707variable set to each word in turn.
708do and done may be replaced with
709.Dq {
710and
711.Dq } .
712.Pp
713The syntax of the break and continue command is
714.Bd -literal -offset indent
715break [ num ]
716continue [ num ]
717.Ed
718.Pp
719Break terminates the num innermost for or while loops.
720Continue continues with the next iteration of the innermost loop.
721These are implemented as builtin commands.
722.Pp
723The syntax of the case command is
724.Bd -literal -offset indent
725case word in
726pattern) list ;;
727\&...
728esac
729.Ed
730.Pp
731The pattern can actually be one or more patterns (see
732.Sx Shell Patterns
733described later), separated by
734.Dq \*(Ba
735characters.
736.Ss Grouping Commands Together
737Commands may be grouped by writing either
738.Pp
739.Dl (list)
740.Pp
741or
742.Pp
743.Dl { list; }
744.Pp
745The first of these executes the commands in a subshell.
746Builtin commands grouped into a (list) will not affect the current shell.
747The second form does not fork another shell so is slightly more efficient.
748Grouping commands together this way allows you to redirect
749their output as though they were one program:
750.Pp
751.Bd -literal -offset indent
752{ echo -n \*q hello \*q ; echo \*q world" ; } \*[Gt] greeting
753.Ed
754.Pp
755Note that
756.Dq }
757must follow a control operator (here,
758.Dq \&; )
759so that it is recognized as a reserved word and not as another command argument.
760.Ss Functions
761The syntax of a function definition is
762.Pp
763.Dl name ( ) command
764.Pp
765A function definition is an executable statement; when executed it
766installs a function named name and returns an exit status of zero.
767The command is normally a list enclosed between
768.Dq {
769and
770.Dq } .
771.Pp
772Variables may be declared to be local to a function by using a local
773command.
774This should appear as the first statement of a function, and the syntax is
775.Pp
776.Dl local [ variable | - ] ...
777.Pp
778Local is implemented as a builtin command.
779.Pp
780When a variable is made local, it inherits the initial value and exported
781and readonly flags from the variable with the same name in the surrounding
782scope, if there is one.
783Otherwise, the variable is initially unset.
784The shell uses dynamic scoping, so that if you make the variable x local to
785function f, which then calls function g, references to the variable x made
786inside g will refer to the variable x declared inside f, not to the global
787variable named x.
788.Pp
789The only special parameter that can be made local is
790.Dq - .
791Making
792.Dq -
793local any shell options that are changed via the set command inside the
794function to be restored to their original values when the function
795returns.
796.Pp
797The syntax of the return command is
798.Pp
799.Dl return [ exitstatus ]
800.Pp
801It terminates the currently executing function.
802Return is implemented as a builtin command.
803.Ss Variables and Parameters
804The shell maintains a set of parameters.
805A parameter denoted by a name is called a variable.
806When starting up, the shell turns all the environment
807variables into shell variables.
808New variables can be set using the form
809.Pp
810.Dl name=value
811.Pp
812Variables set by the user must have a name consisting solely of
813alphabetics, numerics, and underscores - the first of which must not be
814numeric.
815A parameter can also be denoted by a number or a special
816character as explained below.
817.Ss Positional Parameters
818A positional parameter is a parameter denoted by a number (n \*[Gt] 0).
819The shell sets these initially to the values of its command line arguments
820that follow the name of the shell script.
821The
822.Ic set
823builtin can also be used to set or reset them.
824.Ss Special Parameters
825A special parameter is a parameter denoted by one of the following special
826characters.
827The value of the parameter is listed next to its character.
828.Bl -tag -width thinhyphena
829.It *
830Expands to the positional parameters, starting from one.
831When the
832expansion occurs within a double-quoted string it expands to a single
833field with the value of each parameter separated by the first character of
834the
835.Ev IFS
836variable, or by a
837.Aq space
838if
839.Ev IFS
840is unset.
841.It @
842Expands to the positional parameters, starting from one.
843When the expansion occurs within double-quotes, each positional
844parameter expands as a separate argument.
845If there are no positional parameters, the
846expansion of @ generates zero arguments, even when @ is
847double-quoted.
848What this basically means, for example, is
849if $1 is
850.Dq abc
851and $2 is
852.Dq def ghi ,
853then
854.Qq $@
855expands to
856the two arguments:
857.Pp
858.Sm off
859.Dl \*q abc \*q \ \*q def\ ghi \*q
860.Sm on
861.It #
862Expands to the number of positional parameters.
863.It \&?
864Expands to the exit status of the most recent pipeline.
865.It - (Hyphen.)
866Expands to the current option flags (the single-letter
867option names concatenated into a string) as specified on
868invocation, by the set builtin command, or implicitly
869by the shell.
870.It $
871Expands to the process ID of the invoked shell.
872A subshell retains the same value of $ as its parent.
873.It \&!
874Expands to the process ID of the most recent background
875command executed from the current shell.
876For a pipeline, the process ID is that of the last command in the pipeline.
877.It 0 (Zero.)
878Expands to the name of the shell or shell script.
879.El
880.Ss Word Expansions
881This clause describes the various expansions that are performed on words.
882Not all expansions are performed on every word, as explained later.
883.Pp
884Tilde expansions, parameter expansions, command substitutions, arithmetic
885expansions, and quote removals that occur within a single word expand to a
886single field.
887It is only field splitting or pathname expansion that can
888create multiple fields from a single word.
889The single exception to this
890rule is the expansion of the special parameter @ within double-quotes, as
891was described above.
892.Pp
893The order of word expansion is:
894.Bl -enum
895.It
896Tilde Expansion, Parameter Expansion, Command Substitution,
897Arithmetic Expansion (these all occur at the same time).
898.It
899Field Splitting is performed on fields
900generated by step (1) unless the
901.Ev IFS
902variable is null.
903.It
904Pathname Expansion (unless set
905.Fl f
906is in effect).
907.It
908Quote Removal.
909.El
910.Pp
911The $ character is used to introduce parameter expansion, command
912substitution, or arithmetic evaluation.
913.Ss Tilde Expansion (substituting a user's home directory)
914A word beginning with an unquoted tilde character (~) is
915subjected to tilde expansion.
916All the characters up to
917a slash (/) or the end of the word are treated as a username
918and are replaced with the user's home directory.
919If the username is missing (as in
920.Pa ~/foobar ) ,
921the tilde is replaced with the value of the
922.Va HOME
923variable (the current user's home directory).
924.Ss Parameter Expansion
925The format for parameter expansion is as follows:
926.Pp
927.Dl ${expression}
928.Pp
929where expression consists of all characters until the matching
930.Dq } .
931Any
932.Dq }
933escaped by a backslash or within a quoted string, and characters in
934embedded arithmetic expansions, command substitutions, and variable
935expansions, are not examined in determining the matching
936.Dq } .
937.Pp
938The simplest form for parameter expansion is:
939.Pp
940.Dl ${parameter}
941.Pp
942The value, if any, of parameter is substituted.
943.Pp
944The parameter name or symbol can be enclosed in braces, which are
945optional except for positional parameters with more than one digit or
946when parameter is followed by a character that could be interpreted as
947part of the name.
948If a parameter expansion occurs inside double-quotes:
949.Bl -enum
950.It
951Pathname expansion is not performed on the results of the expansion.
952.It
953Field splitting is not performed on the results of the
954expansion, with the exception of the special rules for @.
955.El
956.Pp
957In addition, a parameter expansion can be modified by using one of the
958following formats.
959.Bl -tag -width aaparameterwordaaaaa
960.It ${parameter:-word}
961Use Default Values.
962If parameter is unset or null, the expansion of word
963is substituted; otherwise, the value of parameter is substituted.
964.It ${parameter:=word}
965Assign Default Values.
966If parameter is unset or null, the expansion of
967word is assigned to parameter.
968In all cases, the final value of parameter is substituted.
969Only variables, not positional parameters or special
970parameters, can be assigned in this way.
971.It ${parameter:?[word]}
972Indicate Error if Null or Unset.
973If parameter is unset or null, the
974expansion of word (or a message indicating it is unset if word is omitted)
975is written to standard error and the shell exits with a nonzero exit status.
976Otherwise, the value of parameter is substituted.
977An interactive shell need not exit.
978.It ${parameter:+word}
979Use Alternative Value.
980If parameter is unset or null, null is
981substituted; otherwise, the expansion of word is substituted.
982.El
983.Pp
984In the parameter expansions shown previously, use of the colon in the
985format results in a test for a parameter that is unset or null; omission
986of the colon results in a test for a parameter that is only unset.
987.Bl -tag -width aaparameterwordaaaaa
988.It ${#parameter}
989String Length.
990The length in characters of the value of parameter.
991.El
992.Pp
993The following four varieties of parameter expansion provide for substring
994processing.
995In each case, pattern matching notation (see
996.Sx Shell Patterns ) ,
997rather than regular expression notation, is used to evaluate the patterns.
998If parameter is * or @, the result of the expansion is unspecified.
999Enclosing the full parameter expansion string in double-quotes does not
1000cause the following four varieties of pattern characters to be quoted,
1001whereas quoting characters within the braces has this effect.
1002.Bl -tag -width aaparameterwordaaaaa
1003.It ${parameter%word}
1004Remove Smallest Suffix Pattern.
1005The word is expanded to produce a pattern.
1006The parameter expansion then results in parameter, with the
1007smallest portion of the suffix matched by the pattern deleted.
1008.It ${parameter%%word}
1009Remove Largest Suffix Pattern.
1010The word is expanded to produce a pattern.
1011The parameter expansion then results in parameter, with the largest
1012portion of the suffix matched by the pattern deleted.
1013.It ${parameter#word}
1014Remove Smallest Prefix Pattern.
1015The word is expanded to produce a pattern.
1016The parameter expansion then results in parameter, with the
1017smallest portion of the prefix matched by the pattern deleted.
1018.It ${parameter##word}
1019Remove Largest Prefix Pattern.
1020The word is expanded to produce a pattern.
1021The parameter expansion then results in parameter, with the largest
1022portion of the prefix matched by the pattern deleted.
1023.El
1024.Ss Command Substitution
1025Command substitution allows the output of a command to be substituted in
1026place of the command name itself.
1027Command substitution occurs when the command is enclosed as follows:
1028.Pp
1029.Dl $(command)
1030.Pp
1031or
1032.Po
1033.Dq backquoted
1034version
1035.Pc :
1036.Pp
1037.Dl `command`
1038.Pp
1039The shell expands the command substitution by executing command in a
1040subshell environment and replacing the command substitution with the
1041standard output of the command, removing sequences of one or more
1042.Ao newline Ac Ns s
1043at the end of the substitution.
1044(Embedded
1045.Ao newline Ac Ns s
1046before
1047the end of the output are not removed; however, during field splitting,
1048they may be translated into
1049.Ao space Ac Ns s ,
1050depending on the value of
1051.Ev IFS
1052and quoting that is in effect.)
1053.Ss Arithmetic Expansion
1054Arithmetic expansion provides a mechanism for evaluating an arithmetic
1055expression and substituting its value.
1056The format for arithmetic expansion is as follows:
1057.Pp
1058.Dl $((expression))
1059.Pp
1060The expression is treated as if it were in double-quotes, except
1061that a double-quote inside the expression is not treated specially.
1062The shell expands all tokens in the expression for parameter expansion,
1063command substitution, and quote removal.
1064.Pp
1065Next, the shell treats this as an arithmetic expression and
1066substitutes the value of the expression.
1067.Ss White Space Splitting (Field Splitting)
1068After parameter expansion, command substitution, and
1069arithmetic expansion the shell scans the results of
1070expansions and substitutions that did not occur in double-quotes for
1071field splitting and multiple fields can result.
1072.Pp
1073The shell treats each character of the
1074.Ev IFS
1075as a delimiter and use the delimiters to split the results of parameter
1076expansion and command substitution into fields.
1077.Pp
1078Non-whitespace characters in
1079.Ev IFS
1080are treated strictly as parameter terminators.
1081So adjacent non-whitespace
1082.Ev IFS
1083characters will produce empty parameters.
1084.Pp
1085If
1086.Ev IFS
1087is unset it is assumed to contain space, tab, and newline.
1088.Ss Pathname Expansion (File Name Generation)
1089Unless the
1090.Fl f
1091flag is set, file name generation is performed after word splitting is
1092complete.
1093Each word is viewed as a series of patterns, separated by slashes.
1094The process of expansion replaces the word with the names of all
1095existing files whose names can be formed by replacing each pattern with a
1096string that matches the specified pattern.
1097There are two restrictions on
1098this: first, a pattern cannot match a string containing a slash, and
1099second, a pattern cannot match a string starting with a period unless the
1100first character of the pattern is a period.
1101The next section describes the
1102patterns used for both Pathname Expansion and the
1103.Ic case
1104command.
1105.Ss Shell Patterns
1106A pattern consists of normal characters, which match themselves,
1107and meta-characters.
1108The meta-characters are
1109.Dq \&! ,
1110.Dq * ,
1111.Dq \&? ,
1112and
1113.Dq \&[ .
1114These characters lose their special meanings if they are quoted.
1115When command or variable substitution is performed
1116and the dollar sign or back quotes are not double quoted,
1117the value of the variable or the output of
1118the command is scanned for these characters and they are turned into
1119meta-characters.
1120.Pp
1121An asterisk
1122.Pq Dq *
1123matches any string of characters.
1124A question mark matches any single character.
1125A left bracket
1126.Pq Dq \&[
1127introduces a character class.
1128The end of the character class is indicated by a
1129.Pq Dq \&] ;
1130if the
1131.Dq \&]
1132is missing then the
1133.Dq \&[
1134matches a
1135.Dq \&[
1136rather than introducing a character class.
1137A character class matches any of the characters between the square brackets.
1138A range of characters may be specified using a minus sign.
1139The character class may be complemented
1140by making an exclamation point the first character of the character class.
1141.Pp
1142To include a
1143.Dq \&]
1144in a character class, make it the first character listed (after the
1145.Dq \&! ,
1146if any).
1147To include a minus sign, make it the first or last character listed.
1148.Ss Builtins
1149This section lists the builtin commands which are builtin because they
1150need to perform some operation that can't be performed by a separate
1151process.
1152In addition to these, there are several other commands that may
1153be builtin for efficiency (e.g.
1154.Xr printf 1 ,
1155.Xr echo 1 ,
1156.Xr test 1 ,
1157etc).
1158.Bl -tag -width 5n
1159.It :
1160A null command that returns a 0 (true) exit value.
1161.It \&. file
1162The commands in the specified file are read and executed by the shell.
1163.It alias Op Ar name Ns Op Ar "=string ..."
1164If
1165.Ar name=string
1166is specified, the shell defines the alias
1167.Ar name
1168with value
1169.Ar string .
1170If just
1171.Ar name
1172is specified, the value of the alias
1173.Ar name
1174is printed.
1175With no arguments, the
1176.Ic alias
1177builtin prints the
1178names and values of all defined aliases (see
1179.Ic unalias ) .
1180.It bg [ Ar job ] ...
1181Continue the specified jobs (or the current job if no
1182jobs are given) in the background.
1183.It Xo command
1184.Op Fl p
1185.Op Fl v
1186.Op Fl V
1187.Ar command
1188.Op Ar arg ...
1189.Xc
1190Execute the specified command but ignore shell functions when searching
1191for it.
1192(This is useful when you
1193have a shell function with the same name as a builtin command.)
1194.Bl -tag -width 5n
1195.It Fl p
1196search for command using a
1197.Ev PATH
1198that guarantees to find all the standard utilities.
1199.It Fl V
1200Do not execute the command but
1201search for the command and print the resolution of the
1202command search.
1203This is the same as the type builtin.
1204.It Fl v
1205Do not execute the command but
1206search for the command and print the absolute pathname
1207of utilities, the name for builtins or the expansion of aliases.
1208.El
1209.It cd Op Ar directory Op Ar replace
1210Switch to the specified directory (default
1211.Ev $HOME ) .
1212If
1213.Ar replace
1214is specified, then the new directory name is generated by replacing
1215the first occurrence of
1216.Ar directory
1217in the current directory name with
1218.Ar replace .
1219Otherwise if an entry for
1220.Ev CDPATH
1221appears in the environment of the
1222.Ic cd
1223command or the shell variable
1224.Ev CDPATH
1225is set and the directory name does not begin with a slash, then the
1226directories listed in
1227.Ev CDPATH
1228will be searched for the specified directory.
1229The format of
1230.Ev CDPATH
1231is the same as that of
1232.Ev PATH .
1233In an interactive shell, the
1234.Ic cd
1235command will print out the name of the
1236directory that it actually switched to if this is different from the name
1237that the user gave.
1238These may be different either because the
1239.Ev CDPATH
1240mechanism was used or because a symbolic link was crossed.
1241.It eval Ar string ...
1242Concatenate all the arguments with spaces.
1243Then re-parse and execute the command.
1244.It exec Op Ar command arg ...
1245Unless command is omitted, the shell process is replaced with the
1246specified program (which must be a real program, not a shell builtin or
1247function).
1248Any redirections on the
1249.Ic exec
1250command are marked as permanent, so that they are not undone when the
1251.Ic exec
1252command finishes.
1253.It exit Op Ar exitstatus
1254Terminate the shell process.
1255If
1256.Ar exitstatus
1257is given it is used as the exit status of the shell; otherwise the
1258exit status of the preceding command is used.
1259.It export Ar name ...
1260.It export Fl p
1261The specified names are exported so that they will appear in the
1262environment of subsequent commands.
1263The only way to un-export a variable is to unset it.
1264The shell allows the value of a variable to be set at the
1265same time it is exported by writing
1266.Pp
1267.Dl export name=value
1268.Pp
1269With no arguments the export command lists the names of all exported variables.
1270With the
1271.Fl p
1272option specified the output will be formatted suitably for non-interactive use.
1273.It Xo fc Op Fl e Ar editor
1274.Op Ar first Op Ar last
1275.Xc
1276.It Xo fc Fl l
1277.Op Fl nr
1278.Op Ar first Op Ar last
1279.Xc
1280.It Xo fc Fl s Op Ar old=new
1281.Op Ar first
1282.Xc
1283The
1284.Ic fc
1285builtin lists, or edits and re-executes, commands previously entered
1286to an interactive shell.
1287.Bl -tag -width 5n
1288.It Fl e No editor
1289Use the editor named by editor to edit the commands.
1290The editor string is a command name, subject to search via the
1291.Ev PATH
1292variable.
1293The value in the
1294.Ev FCEDIT
1295variable is used as a default when
1296.Fl e
1297is not specified.
1298If
1299.Ev FCEDIT
1300is null or unset, the value of the
1301.Ev EDITOR
1302variable is used.
1303If
1304.Ev EDITOR
1305is null or unset,
1306.Xr ed 1
1307is used as the editor.
1308.It Fl l No (ell)
1309List the commands rather than invoking an editor on them.
1310The commands are written in the sequence indicated by
1311the first and last operands, as affected by
1312.Fl r ,
1313with each command preceded by the command number.
1314.It Fl n
1315Suppress command numbers when listing with -l.
1316.It Fl r
1317Reverse the order of the commands listed (with
1318.Fl l )
1319or edited (with neither
1320.Fl l
1321nor
1322.Fl s ) .
1323.It Fl s
1324Re-execute the command without invoking an editor.
1325.It first
1326.It last
1327Select the commands to list or edit.
1328The number of previous commands that
1329can be accessed are determined by the value of the
1330.Ev HISTSIZE
1331variable.
1332The value of first or last or both are one of the following:
1333.Bl -tag -width 5n
1334.It [+]number
1335A positive number representing a command number; command numbers can be
1336displayed with the
1337.Fl l
1338option.
1339.It Fl number
1340A negative decimal number representing the command that was executed
1341number of commands previously.
1342For example, \-1 is the immediately previous command.
1343.El
1344.It string
1345A string indicating the most recently entered command that begins with
1346that string.
1347If the old=new operand is not also specified with
1348.Fl s ,
1349the string form of the first operand cannot contain an embedded equal sign.
1350.El
1351.Pp
1352The following environment variables affect the execution of fc:
1353.Bl -tag -width HISTSIZE
1354.It Ev FCEDIT
1355Name of the editor to use.
1356.It Ev HISTSIZE
1357The number of previous commands that are accessible.
1358.El
1359.It fg Op Ar job
1360Move the specified job or the current job to the foreground.
1361.It getopts Ar optstring var
1362The
1363.Tn POSIX
1364.Ic getopts
1365command, not to be confused with the
1366.Em Bell Labs
1367-derived
1368.Xr getopt 1 .
1369.Pp
1370The first argument should be a series of letters, each of which may be
1371optionally followed by a colon to indicate that the option requires an
1372argument.
1373The variable specified is set to the parsed option.
1374.Pp
1375The
1376.Ic getopts
1377command deprecates the older
1378.Xr getopt 1
1379utility due to its handling of arguments containing whitespace.
1380.Pp
1381The
1382.Ic getopts
1383builtin may be used to obtain options and their arguments
1384from a list of parameters.
1385When invoked,
1386.Ic getopts
1387places the value of the next option from the option string in the list in
1388the shell variable specified by
1389.Va var
1390and its index in the shell variable
1391.Ev OPTIND .
1392When the shell is invoked,
1393.Ev OPTIND
1394is initialized to 1.
1395For each option that requires an argument, the
1396.Ic getopts
1397builtin will place it in the shell variable
1398.Ev OPTARG .
1399If an option is not allowed for in the
1400.Va optstring ,
1401then
1402.Ev OPTARG
1403will be unset.
1404.Pp
1405.Va optstring
1406is a string of recognized option letters (see
1407.Xr getopt 3 ) .
1408If a letter is followed by a colon, the option is expected to have an
1409argument which may or may not be separated from it by whitespace.
1410If an option character is not found where expected,
1411.Ic getopts
1412will set the variable
1413.Va var
1414to a
1415.Dq \&? ;
1416.Ic getopts
1417will then unset
1418.Ev OPTARG
1419and write output to standard error.
1420By specifying a colon as the first character of
1421.Va optstring
1422all errors will be ignored.
1423.Pp
1424A nonzero value is returned when the last option is reached.
1425If there are no remaining arguments,
1426.Ic getopts
1427will set
1428.Va var
1429to the special option,
1430.Dq -- ,
1431otherwise, it will set
1432.Va var
1433to
1434.Dq \&? .
1435.Pp
1436The following code fragment shows how one might process the arguments
1437for a command that can take the options
1438.Op a
1439and
1440.Op b ,
1441and the option
1442.Op c ,
1443which requires an argument.
1444.Pp
1445.Bd -literal -offset indent
1446while getopts abc: f
1447do
1448 case $f in
1449 a | b) flag=$f;;
1450 c) carg=$OPTARG;;
1451 \\?) echo $USAGE; exit 1;;
1452 esac
1453done
1454shift `expr $OPTIND - 1`
1455.Ed
1456.Pp
1457This code will accept any of the following as equivalent:
1458.Pp
1459.Bd -literal -offset indent
1460cmd \-acarg file file
1461cmd \-a \-c arg file file
1462cmd \-carg -a file file
1463cmd \-a \-carg \-\- file file
1464.Ed
1465.It hash Fl rv Ar command ...
1466The shell maintains a hash table which remembers the
1467locations of commands.
1468With no arguments whatsoever,
1469the
1470.Ic hash
1471command prints out the contents of this table.
1472Entries which have not been looked at since the last
1473.Ic cd
1474command are marked with an asterisk; it is possible for these entries
1475to be invalid.
1476.Pp
1477With arguments, the
1478.Ic hash
1479command removes the specified commands from the hash table (unless
1480they are functions) and then locates them.
1481With the
1482.Fl v
1483option, hash prints the locations of the commands as it finds them.
1484The
1485.Fl r
1486option causes the hash command to delete all the entries in the hash table
1487except for functions.
1488.It inputrc Ar file
1489Read the
1490.Va file
1491to set keybindings as defined by
1492.Xr editrc 5 .
1493.It jobid Op Ar job
1494Print the process id's of the processes in the job.
1495If the
1496.Ar job
1497argument is omitted, the current job is used.
1498.It jobs
1499This command lists out all the background processes
1500which are children of the current shell process.
1501.It pwd Op Fl LP
1502Print the current directory.
1503If
1504.Fl L
1505is specified the cached value (initially set from
1506.Ev PWD )
1507is checked to see if it refers to the current directory, if it does
1508the value is printed.
1509Otherwise the current directory name is found using
1510.Xr getcwd(3) .
1511The environment variable
1512.Ev PWD
1513is set to printed value.
1514.Pp
1515The default is
1516.Ic pwd
1517.Fl L ,
1518but note that the builtin
1519.Ic cd
1520command doesn't currently support
1521.Fl L
1522or
1523.Fl P
1524and will cache (almost) the absolute path.
1525If
1526.Ic cd
1527is changed,
1528.Ic pwd
1529may be changed to default to
1530.Ic pwd
1531.Fl P .
1532.Pp
1533If the current directory is renamed and replaced by a symlink to the
1534same directory, or the initial
1535.Ev PWD
1536value followed a symbolic link, then the cached value may not
1537be the absolute path.
1538.Pp
1539The builtin command may differ from the program of the same name because
1540the program will use
1541.Ev PWD
1542and the builtin uses a separately cached value.
1543.It Xo read Op Fl p Ar prompt
1544.Op Fl r
1545.Ar variable
1546.Op Ar ...
1547.Xc
1548The prompt is printed if the
1549.Fl p
1550option is specified and the standard input is a terminal.
1551Then a line is read from the standard input.
1552The trailing newline is deleted from the
1553line and the line is split as described in the section on word splitting
1554above, and the pieces are assigned to the variables in order.
1555If there are more pieces than variables, the remaining pieces
1556(along with the characters in
1557.Ev IFS
1558that separated them) are assigned to the last variable.
1559If there are more variables than pieces,
1560the remaining variables are assigned the null string.
1561The
1562.Ic read
1563builtin will indicate success unless EOF is encountered on input, in
1564which case failure is returned.
1565.Pp
1566By default, unless the
1567.Fl r
1568option is specified, the backslash
1569.Dq \e
1570acts as an escape character, causing the following character to be treated
1571literally.
1572If a backslash is followed by a newline, the backslash and the
1573newline will be deleted.
1574.It readonly Ar name ...
1575.It readonly Fl p
1576The specified names are marked as read only, so that they cannot be
1577subsequently modified or unset.
1578The shell allows the value of a variable
1579to be set at the same time it is marked read only by writing
1580.Pp
1581.Dl readonly name=value
1582.Pp
1583With no arguments the readonly command lists the names of all read only
1584variables.
1585With the
1586.Fl p
1587option specified the output will be formatted suitably for non-interactive use.
1588.Pp
1589.It Xo set
1590.Oo {
1591.Fl options | Cm +options | Cm -- }
1592.Oc Ar arg ...
1593.Xc
1594The
1595.Ic set
1596command performs three different functions.
1597.Pp
1598With no arguments, it lists the values of all shell variables.
1599.Pp
1600If options are given, it sets the specified option
1601flags, or clears them as described in the section called
1602.Sx Argument List Processing .
1603.Pp
1604The third use of the set command is to set the values of the shell's
1605positional parameters to the specified args.
1606To change the positional
1607parameters without changing any options, use
1608.Dq --
1609as the first argument to set.
1610If no args are present, the set command
1611will clear all the positional parameters (equivalent to executing
1612.Dq shift $# . )
1613.It setvar Ar variable Ar value
1614Assigns value to variable.
1615(In general it is better to write
1616variable=value rather than using
1617.Ic setvar .
1618.Ic setvar
1619is intended to be used in
1620functions that assign values to variables whose names are passed as
1621parameters.)
1622.It shift Op Ar n
1623Shift the positional parameters n times.
1624A
1625.Ic shift
1626sets the value of
1627.Va $1
1628to the value of
1629.Va $2 ,
1630the value of
1631.Va $2
1632to the value of
1633.Va $3 ,
1634and so on, decreasing
1635the value of
1636.Va $#
1637by one.
1638If there are zero positional parameters,
1639.Ic shift
1640does nothing.
1641.It Xo trap
1642.Op Fl l
1643.Xc
1644.It Xo trap
1645.Op Ar action
1646.Ar signal ...
1647.Xc
1648Cause the shell to parse and execute action when any of the specified
1649signals are received.
1650The signals are specified by signal number or as the name of the signal.
1651If
1652.Ar signal
1653is
1654.Li 0 ,
1655the action is executed when the shell exits.
1656.Ar action
1657may be null, which cause the specified signals to be ignored.
1658With
1659.Ar action
1660omitted or set to `-' the specified signals are set to their default action.
1661When the shell forks off a subshell, it resets trapped (but not ignored)
1662signals to the default action.
1663The
1664.Ic trap
1665command has no effect on signals that were
1666ignored on entry to the shell.
1667Issuing
1668.Ic trap
1669with option
1670.Ar -l
1671will print a list of valid signal names.
1672.Ic trap
1673without any arguments cause it to write a list of signals and their
1674associated action to the standard output in a format that is suitable
1675as an input to the shell that achieves the same trapping results.
1676.Pp
1677Examples:
1678.Pp
1679.Dl trap
1680.Pp
1681List trapped signals and their corresponding action
1682.Pp
1683.Dl trap -l
1684.Pp
1685Print a list of valid signals
1686.Pp
1687.Dl trap '' INT QUIT tstp 30
1688.Pp
1689Ignore signals INT QUIT TSTP USR1
1690.Pp
1691.Dl trap date INT
1692.Pp
1693Print date upon receiving signal INT
1694.It type Op Ar name ...
1695Interpret each name as a command and print the resolution of the command
1696search.
1697Possible resolutions are:
1698shell keyword, alias, shell builtin,
1699command, tracked alias and not found.
1700For aliases the alias expansion is
1701printed; for commands and tracked aliases the complete pathname of the
1702command is printed.
1703.It ulimit Xo
1704.Op Fl H \*(Ba Fl S
1705.Op Fl a \*(Ba Fl tfdscmlpn Op Ar value
1706.Xc
1707Inquire about or set the hard or soft limits on processes or set new
1708limits.
1709The choice between hard limit (which no process is allowed to
1710violate, and which may not be raised once it has been lowered) and soft
1711limit (which causes processes to be signaled but not necessarily killed,
1712and which may be raised) is made with these flags:
1713.Bl -tag -width Fl
1714.It Fl H
1715set or inquire about hard limits
1716.It Fl S
1717set or inquire about soft limits.
1718If neither
1719.Fl H
1720nor
1721.Fl S
1722is specified, the soft limit is displayed or both limits are set.
1723If both are specified, the last one wins.
1724.El
1725.Pp
1726.Bl -tag -width Fl
1727The limit to be interrogated or set, then, is chosen by specifying
1728any one of these flags:
1729.It Fl a
1730show all the current limits
1731.It Fl b
1732show or set the limit on the socket buffer size of a process (in bytes)
1733.It Fl t
1734show or set the limit on CPU time (in seconds)
1735.It Fl f
1736show or set the limit on the largest file that can be created
1737(in 512-byte blocks)
1738.It Fl d
1739show or set the limit on the data segment size of a process (in kilobytes)
1740.It Fl s
1741show or set the limit on the stack size of a process (in kilobytes)
1742.It Fl c
1743show or set the limit on the largest core dump size that can be produced
1744(in 512-byte blocks)
1745.It Fl m
1746show or set the limit on the total physical memory that can be
1747in use by a process (in kilobytes)
1748.It Fl l
1749show or set the limit on how much memory a process can lock with
1750.Xr mlock 2
1751(in kilobytes)
1752.It Fl p
1753show or set the limit on the number of processes this user can
1754have at one time
1755.It Fl n
1756show or set the limit on the number of files a process can have open at once
1757.El
1758.Pp
1759If none of these is specified, it is the limit on file size that is shown
1760or set.
1761If value is specified, the limit is set to that number; otherwise
1762the current limit is displayed.
1763.Pp
1764Limits of an arbitrary process can be displayed or set using the
1765.Xr sysctl 8
1766utility.
1767.Pp
1768.It umask Op Ar mask
1769Set the value of umask (see
1770.Xr umask 2 )
1771to the specified octal value.
1772If the argument is omitted, the umask value is printed.
1773.It unalias Xo
1774.Op Fl a
1775.Op Ar name
1776.Xc
1777If
1778.Ar name
1779is specified, the shell removes that alias.
1780If
1781.Fl a
1782is specified, all aliases are removed.
1783.It unset Ar name ...
1784The specified variables and functions are unset and unexported.
1785If a given name corresponds to both a variable and a function, both
1786the variable and the function are unset.
1787.It wait Op Ar job
1788Wait for the specified job to complete and return the exit status of the
1789last process in the job.
1790If the argument is omitted, wait for all jobs to
1791complete and then return an exit status of zero.
1792.El
1793.Ss Command Line Editing
1794When
1795.Nm
1796is being used interactively from a terminal, the current command
1797and the command history (see
1798.Ic fc
1799in
1800.Sx Builtins )
1801can be edited using emacs-mode or vi-mode command-line editing.
1802The command
1803.Ql set -o emacs
1804enables emacs-mode editing.
1805The command
1806.Ql set -o vi
1807enables vi-mode editing and places sh into vi insert mode.
1808(See the
1809.Sx Argument List Processing
1810section above.)
1811.Pp
1812The vi mode uses commands similar to a subset of those described in the
1813.Xr vi 1
1814man page.
1815With vi-mode
1816enabled, sh can be switched between insert mode and command mode.
1817It's similar to vi: typing
1818.Aq ESC
1819will throw you into command VI command mode.
1820Hitting
1821.Aq return
1822while in command mode will pass the line to the shell.
1823.Pp
1824The emacs mode uses commands similar to a subset available in
1825the emacs editor.
1826With emacs-mode enabled, special keys can be used to modify the text
1827in the buffer using the control key.
1828.Pp
1829.Nm
1830uses the
1831.Xr editline 3
1832library.
1833.Sh EXIT STATUS
1834Errors that are detected by the shell, such as a syntax error, will cause the
1835shell to exit with a non-zero exit status.
1836If the shell is not an
1837interactive shell, the execution of the shell file will be aborted.
1838Otherwise
1839the shell will return the exit status of the last command executed, or
1840if the exit builtin is used with a numeric argument, it will return the
1841argument.
1842.Sh ENVIRONMENT
1843.Bl -tag -width MAILCHECK
1844.It Ev HOME
1845Set automatically by
1846.Xr login 1
1847from the user's login directory in the password file
1848.Pq Xr passwd 5 .
1849This environment variable also functions as the default argument for the
1850cd builtin.
1851.It Ev PATH
1852The default search path for executables.
1853See the above section
1854.Sx Path Search .
1855.It Ev CDPATH
1856The search path used with the cd builtin.
1857.It Ev LANG
1858The string used to specify localization information that allows users
1859to work with different culture-specific and language conventions.
1860See
1861.Xr nls 7 .
1862.It Ev MAIL
1863The name of a mail file, that will be checked for the arrival of new mail.
1864Overridden by
1865.Ev MAILPATH .
1866.It Ev MAILCHECK
1867The frequency in seconds that the shell checks for the arrival of mail
1868in the files specified by the
1869.Ev MAILPATH
1870or the
1871.Ev MAIL
1872file.
1873If set to 0, the check will occur at each prompt.
1874.It Ev MAILPATH
1875A colon
1876.Dq \&:
1877separated list of file names, for the shell to check for incoming mail.
1878This environment setting overrides the
1879.Ev MAIL
1880setting.
1881There is a maximum of 10 mailboxes that can be monitored at once.
1882.It Ev PS1
1883The primary prompt string, which defaults to
1884.Dq $ \ ,
1885unless you are the superuser, in which case it defaults to
1886.Dq # \ .
1887.It Ev PS2
1888The secondary prompt string, which defaults to
1889.Dq \*[Gt] \ .
1890.It Ev PS4
1891Output before each line when execution trace (set -x) is enabled,
1892defaults to
1893.Dq + \ .
1894.It Ev IFS
1895Input Field Separators.
1896This is normally set to
1897.Aq space ,
1898.Aq tab ,
1899and
1900.Aq newline .
1901See the
1902.Sx White Space Splitting
1903section for more details.
1904.It Ev TERM
1905The default terminal setting for the shell.
1906This is inherited by
1907children of the shell, and is used in the history editing modes.
1908.It Ev HISTSIZE
1909The number of lines in the history buffer for the shell.
1910.El
1911.Sh FILES
1912.Bl -item -width HOMEprofilexxxx
1913.It
1914.Pa $HOME/.profile
1915.It
1916.Pa /etc/profile
1917.El
1918.Sh SEE ALSO
1919.Xr csh 1 ,
1920.Xr echo 1 ,
1921.Xr getopt 1 ,
1922.Xr ksh 1 ,
1923.Xr login 1 ,
1924.Xr printf 1 ,
1925.Xr test 1 ,
1926.Xr editline 3 ,
1927.Xr getopt 3 ,
1928.\" .Xr profile 4 ,
1929.Xr editrc 5 ,
1930.Xr passwd 5 ,
1931.Xr environ 7 ,
1932.Xr nls 7 ,
1933.Xr sysctl 8
1934.Sh HISTORY
1935A
1936.Nm
1937command appeared in
1938.At v1 .
1939It was, however, unmaintainable so we wrote this one.
1940.Sh BUGS
1941Setuid shell scripts should be avoided at all costs, as they are a
1942significant security risk.
1943.Pp
1944PS1, PS2, and PS4 should be subject to parameter expansion before
1945being displayed.
1946.Pp
1947The characters generated by filename completion should probably be quoted
1948to ensure that the filename is still valid after the input line has been
1949processed.
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette