mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-24 11:29:10 +00:00
1948 lines
53 KiB
Groff
1948 lines
53 KiB
Groff
.\" Copyright (c) 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" Kenneth Almquist.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" from: @(#)sh.1 8.6 (Berkeley) 5/4/95
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 5, 1995
|
|
.Dt SH 1
|
|
.Os BSD 4
|
|
.Sh NAME
|
|
.Nm sh
|
|
.Nd command interpreter (shell)
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl /+abCEefIimnpsTuVvx
|
|
.Op Fl /+o Ar longname
|
|
.Op Fl c Ar string
|
|
.Op Ar arg ...\&
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is the standard command interpreter for the system.
|
|
The current version of
|
|
.Nm
|
|
is in the process of being changed to
|
|
conform with the
|
|
.St -p1003.2
|
|
specification for the shell. This version has many features which make
|
|
it appear
|
|
similar in some respects to the Korn shell, but it is not a Korn
|
|
shell clone like
|
|
.Xr pdksh 1 .
|
|
Only features
|
|
designated by POSIX, plus a few Berkeley extensions, are being
|
|
incorporated into this shell.
|
|
This man page is not intended to be a tutorial nor a complete
|
|
specification of the shell.
|
|
.Ss Overview
|
|
The shell is a command that reads lines from
|
|
either a file or the terminal, interprets them, and
|
|
generally executes other commands.
|
|
It is the program that is started when a user logs into the system,
|
|
although a user can select a different shell with the
|
|
.Xr chsh 1
|
|
command.
|
|
The shell
|
|
implements a language that has flow control constructs,
|
|
a macro facility that provides a variety of features in
|
|
addition to data storage, along with builtin history and line
|
|
editing capabilities. It incorporates many features to
|
|
aid interactive use and has the advantage that the interpretative
|
|
language is common to both interactive and non-interactive
|
|
use (shell scripts). That is, commands can be typed directly
|
|
to the running shell or can be put into a file,
|
|
which can be executed directly by the shell.
|
|
.Ss Invocation
|
|
.\"
|
|
.\" XXX This next sentence is incredibly confusing.
|
|
.\"
|
|
If no arguments are present and if the standard input of the shell
|
|
is connected to a terminal
|
|
(or if the
|
|
.Fl i
|
|
option is set),
|
|
the shell is considered an interactive shell. An interactive shell
|
|
generally prompts before each command and handles programming
|
|
and command errors differently (as described below).
|
|
When first starting, the shell inspects argument 0, and
|
|
if it begins with a dash
|
|
.Pq Li - ,
|
|
the shell is also considered a login shell.
|
|
This is normally done automatically by the system
|
|
when the user first logs in. A login shell first reads commands
|
|
from the files
|
|
.Pa /etc/profile
|
|
and then
|
|
.Pa .profile
|
|
if they exist. If the environment variable
|
|
.Ev ENV
|
|
is set on entry to a shell, or is set in the
|
|
.Pa .profile
|
|
of a login shell, the shell then reads commands from the file named in
|
|
.Ev ENV .
|
|
Therefore, a user should place commands that are to be executed only
|
|
at login time in the
|
|
.Pa .profile
|
|
file, and commands that are executed for every shell inside the
|
|
.Ev ENV
|
|
file.
|
|
The user can set the
|
|
.Ev ENV
|
|
variable to some file by placing the following line in the file
|
|
.Pa .profile
|
|
in the home directory,
|
|
substituting for
|
|
.Pa .shinit
|
|
the filename desired:
|
|
.Pp
|
|
.Dl ENV=$HOME/.shinit; export ENV
|
|
.Pp
|
|
The first non-option argument specified on the command line
|
|
will be treated as the
|
|
name of a file from which to read commands (a shell script), and
|
|
the remaining arguments are set as the positional parameters
|
|
of the shell ($1, $2, etc). Otherwise, the shell reads commands
|
|
from its standard input.
|
|
.Pp
|
|
Unlike older versions of
|
|
.Nm
|
|
the
|
|
.Ev ENV
|
|
script is only sourced on invocation of interactive shells. This
|
|
closes a well-known, and sometimes easily exploitable security
|
|
hole related to poorly thought out
|
|
.Ev ENV
|
|
scripts.
|
|
.Ss Argument List Processing
|
|
All of the single letter options to
|
|
.Nm
|
|
have a corresponding long name,
|
|
with the exception of
|
|
.Fl c
|
|
and
|
|
.Fl /+o .
|
|
These long names are provided next to the single letter options
|
|
in the descriptions below.
|
|
The long name for an option may be specified as an argument to the
|
|
.Fl /+o
|
|
option of
|
|
.Xr sh 1 .
|
|
Once the shell is running,
|
|
the long name for an option may be specified as an argument to the
|
|
.Fl /+o
|
|
option of the
|
|
.Ic set
|
|
builtin command
|
|
(described later in the section called
|
|
.Sx Builtin Commands ) .
|
|
Introducing an option with a dash
|
|
.Pq Li -
|
|
enables the option,
|
|
while using a plus
|
|
.Pq Li +
|
|
disables the option.
|
|
A
|
|
.Dq Li --
|
|
or plain
|
|
.Dq Li -
|
|
will stop option processing and will force the remaining
|
|
words on the command line to be treated as arguments.
|
|
The
|
|
.Fl /+o
|
|
and
|
|
.Fl c
|
|
options do not have long names.
|
|
They take arguments and are described after the single letter options.
|
|
.Bl -tag -width Ds
|
|
.It Fl a Li allexport
|
|
Flag variables for export when assignments are made to them.
|
|
.It Fl b Li notify
|
|
Enable asynchronous notification of background job
|
|
completion.
|
|
.Pq UNIMPLEMENTED
|
|
.It Fl C Li noclobber
|
|
Do not overwrite existing files with
|
|
.Dq Li > .
|
|
.Pq UNIMPLEMENTED
|
|
.It Fl E Li emacs
|
|
Enable the builtin
|
|
.Xr emacs 1
|
|
command line editor (disables the
|
|
.Fl V
|
|
option if it has been set).
|
|
.It Fl e Li errexit
|
|
Exit immediately if any untested command fails in non-interactive mode.
|
|
The exit status of a command is considered to be
|
|
explicitly tested if the command is used to control
|
|
an if, elif, while, or until; or if the command is the left
|
|
hand operand of an
|
|
.Dq Li &&
|
|
or
|
|
.Dq Li ||
|
|
operator.
|
|
.It Fl f Li noglob
|
|
Disable pathname expansion.
|
|
.It Fl I Li ignoreeof
|
|
Ignore
|
|
.Dv EOF Ns ' Ns s
|
|
from input when in interactive mode.
|
|
.It Fl i Li interactive
|
|
Force the shell to behave interactively.
|
|
.It Fl m Li monitor
|
|
Turn on job control (set automatically when interactive).
|
|
.It Fl n Li noexec
|
|
If not interactive, read commands but do not
|
|
execute them. This is useful for checking the
|
|
syntax of shell scripts.
|
|
.It Fl p Li privileged
|
|
Turn on privileged mode. This mode is enabled on startup
|
|
if either the effective user or group id is not equal to the
|
|
real user or group id. Turning this mode off sets the
|
|
effective user and group ids to the real user and group ids.
|
|
When this mode is enabled for interactive shells, the file
|
|
.Pa /etc/suid_profile
|
|
is sourced instead of
|
|
.Pa ~/.profile
|
|
after
|
|
.Pa /etc/profile
|
|
is sourced, and the contents of the
|
|
.Ev ENV
|
|
variable are ignored.
|
|
.It Fl s Li stdin
|
|
Read commands from standard input (set automatically
|
|
if no file arguments are present). This option has
|
|
no effect when set after the shell has already started
|
|
running (i.e. when set with the
|
|
.Ic set
|
|
command).
|
|
.It Fl T Li asynctraps
|
|
When waiting for a child, execute traps immediately.
|
|
If this option is not set,
|
|
traps are executed after the child exits,
|
|
as specified in
|
|
.St -p1003.2
|
|
This nonstandard option is useful for putting guarding shells around
|
|
children that block signals. The surrounding shell may kill the child
|
|
or it may just return control to the tty and leave the child alone,
|
|
like this:
|
|
.Bd -literal -offset indent
|
|
sh -T -c "trap 'exit 1' 2 ; some-blocking-program"
|
|
.Ed
|
|
.Pp
|
|
.It Fl u Li nounset
|
|
Write a message to standard error when attempting
|
|
to expand a variable that is not set, and if the
|
|
shell is not interactive, exit immediately.
|
|
.Pq UNIMPLEMENTED
|
|
.It Fl V Li vi
|
|
Enable the builtin
|
|
.Xr vi 1
|
|
command line editor (disables
|
|
.Fl E
|
|
if it has been set).
|
|
.It Fl v Li verbose
|
|
The shell writes its input to standard error
|
|
as it is read. Useful for debugging.
|
|
.It Fl x Li xtrace
|
|
Write each command
|
|
(preceded by
|
|
.Dq Li +\ )
|
|
to standard error before it is executed.
|
|
Useful for debugging.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fl c
|
|
option may be used to pass its string argument to the shell
|
|
to be interpreted as input.
|
|
Keep in mind that this option only accepts a single string as its
|
|
argument, hence multi-word strings must be quoted.
|
|
.Pp
|
|
The
|
|
.Fl /+o
|
|
option takes as its only argument the long name of an option
|
|
to be enabled or disabled.
|
|
For example, the following two invocations of
|
|
.Nm
|
|
both enable the builtin
|
|
.Xr emacs 1
|
|
command line editor:
|
|
.Bd -literal -offset indent
|
|
set -E
|
|
set -o emacs
|
|
.Ed
|
|
.Ss Lexical Structure
|
|
The shell reads input in terms of lines from a file and breaks
|
|
it up into words at whitespace (blanks and tabs), and at
|
|
certain sequences of
|
|
characters called
|
|
.Dq operators ,
|
|
which are special to the shell.
|
|
There are two types of operators: control operators and
|
|
redirection operators (their meaning is discussed later).
|
|
The following is a list of valid operators:
|
|
.Bl -tag -width Ds
|
|
.It Control operators:
|
|
.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
|
|
.It Xo
|
|
.Li & Ta Xo
|
|
.Li && Ta Xo
|
|
.Li ( Ta Xo
|
|
.Li ) Ta Xo
|
|
.Li \en
|
|
.Xc Xc Xc Xc Xc
|
|
.It Xo
|
|
.Li ;; Ta Xo
|
|
.Li ; Ta Xo
|
|
.Li | Ta Xo
|
|
.Li ||
|
|
.Xc Xc Xc Xc
|
|
.El
|
|
.It Redirection operators:
|
|
.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
|
|
.It Xo
|
|
.Li < Ta Xo
|
|
.Li > Ta Xo
|
|
.Li << Ta Xo
|
|
.Li >> Ta Xo
|
|
.Li <>
|
|
.Xc Xc Xc Xc Xc
|
|
.It Xo
|
|
.Li <& Ta Xo
|
|
.Li >& Ta Xo
|
|
.Li <<- Ta Xo
|
|
.Li >|
|
|
.Xc Xc Xc Xc
|
|
.El
|
|
.El
|
|
.Ss Quoting
|
|
Quoting is used to remove the special meaning of certain characters
|
|
or words to the shell, such as operators, whitespace, or
|
|
keywords. There are three types of quoting: matched single quotes,
|
|
matched double quotes, and backslash.
|
|
.Bl -tag -width Ds
|
|
.It Single Quotes
|
|
Enclosing characters in single quotes preserves the literal
|
|
meaning of all the characters (except single quotes, making
|
|
it impossible to put single-quotes in a single-quoted string).
|
|
.It Double Quotes
|
|
Enclosing characters within double quotes preserves the literal
|
|
meaning of all characters except dollarsign
|
|
.Pq Li $ ,
|
|
backquote
|
|
.Pq Li ` ,
|
|
and backslash
|
|
.Po Li \e\"
|
|
.Pc .
|
|
The backslash inside double quotes is historically weird.
|
|
It remains literal unless it precedes the following characters,
|
|
which it serves to quote:
|
|
.Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact
|
|
.It Xo
|
|
.Li $ Ta Xo
|
|
.Li ` Ta Xo
|
|
.Li \&" Ta Xo
|
|
.Li \e\ Ta Xo
|
|
.Li \en
|
|
.Xc Xc Xc Xc Xc
|
|
.El
|
|
.It Backslash
|
|
A backslash preserves the literal meaning of the following
|
|
character, with the exception of the newline character
|
|
.Pq Li \en .
|
|
A backslash preceding a newline is treated as a line continuation.
|
|
.El
|
|
.Ss Reserved Words
|
|
Reserved words are words that have special meaning to the
|
|
shell and are recognized at the beginning of a line and
|
|
after a control operator. The following are reserved words:
|
|
.Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center
|
|
.It Xo
|
|
.Li \&! Ta Xo
|
|
.Li { Ta Xo
|
|
.Li } Ta Xo
|
|
.Ic case Ta Xo
|
|
.Ic do
|
|
.Xc Xc Xc Xc Xc
|
|
.It Xo
|
|
.Ic done Ta Xo
|
|
.Ic elif Ta Xo
|
|
.Ic else Ta Xo
|
|
.Ic esac Ta Xo
|
|
.Ic fi
|
|
.Xc Xc Xc Xc Xc
|
|
.It Xo
|
|
.Ic for Ta Xo
|
|
.Ic if Ta Xo
|
|
.Ic then Ta Xo
|
|
.Ic until Ta Xo
|
|
.Ic while
|
|
.Xc Xc Xc Xc Xc
|
|
.El
|
|
.Ss Aliases
|
|
An alias is a name and corresponding value set using the
|
|
.Ic alias
|
|
builtin command. Whenever a reserved word may occur (see above),
|
|
and after checking for reserved words, the shell
|
|
checks the word to see if it matches an alias.
|
|
If it does, it replaces it in the input stream with its value.
|
|
For example, if there is an alias called
|
|
.Dq Li lf
|
|
with the value
|
|
.Dq Li ls -F ,
|
|
then the input
|
|
.Bd -literal -offset indent
|
|
lf foobar
|
|
.Ed
|
|
.Pp
|
|
would become
|
|
.Bd -literal -offset indent
|
|
ls -F foobar
|
|
.Ed
|
|
.Pp
|
|
Aliases provide a convenient way for naive users to
|
|
create shorthands for commands without having to learn how
|
|
to create functions with arguments. They can also be
|
|
used to create lexically obscure code. This use is discouraged.
|
|
.Ss Commands
|
|
The shell interprets the words it reads according to a
|
|
language, the specification of which is outside the scope
|
|
of this man page (refer to the BNF in the
|
|
.St -p1003.2
|
|
document). Essentially though, a line is read and if
|
|
the first word of the line (or after a control operator)
|
|
is not a reserved word, then the shell has recognized a
|
|
simple command. Otherwise, a complex command or some
|
|
other special construct may have been recognized.
|
|
.Ss Simple Commands
|
|
If a simple command has been recognized, the shell performs
|
|
the following actions:
|
|
.Bl -enum
|
|
.It
|
|
Leading words of the form
|
|
.Dq Li name=value
|
|
are stripped off and assigned to the environment of
|
|
the simple command. Redirection operators and
|
|
their arguments (as described below) are stripped
|
|
off and saved for processing.
|
|
.It
|
|
The remaining words are expanded as described in
|
|
the section called
|
|
.Sx Word Expansions ,
|
|
and the first remaining word is considered the command
|
|
name and the command is located. The remaining
|
|
words are considered the arguments of the command.
|
|
If no command name resulted, then the
|
|
.Dq Li name=value
|
|
variable assignments recognized in 1) affect the
|
|
current shell.
|
|
.It
|
|
Redirections are performed as described in
|
|
the next section.
|
|
.El
|
|
.Ss Redirections
|
|
Redirections are used to change where a command reads its input
|
|
or sends its output. In general, redirections open, close, or
|
|
duplicate an existing reference to a file. The overall format
|
|
used for redirection is:
|
|
.Pp
|
|
.Dl [n] redir-op file
|
|
.Pp
|
|
The
|
|
.Ql redir-op
|
|
is one of the redirection operators mentioned
|
|
previously. The following gives some examples of how these
|
|
operators can be used.
|
|
Note that stdin and stdout are commonly used abbreviations
|
|
for standard input and standard output respectively.
|
|
.Bl -tag -width "1234567890XX" -offset indent
|
|
.It Li [n]> file
|
|
redirect stdout (or file descriptor n) to file
|
|
.It Li [n]>| file
|
|
same as above, but override the
|
|
.Fl C
|
|
option
|
|
.It Li [n]>> file
|
|
append stdout (or file descriptor n) to file
|
|
.It Li [n]< file
|
|
redirect stdin (or file descriptor n) from file
|
|
.It Li [n]<> file
|
|
redirect stdin (or file descriptor n) to and from file
|
|
.It Li [n1]<&n2
|
|
duplicate stdin (or file descriptor n1) from file descriptor n2
|
|
.It Li [n]<&-
|
|
close stdin (or file descriptor n)
|
|
.It Li [n1]>&n2
|
|
duplicate stdout (or file descriptor n1) to file descriptor n2
|
|
.It Li [n]>&-
|
|
close stdout (or file descriptor n)
|
|
.El
|
|
.Pp
|
|
The following redirection is often called a
|
|
.Dq here-document .
|
|
.Bd -literal -offset indent
|
|
[n]<< delimiter
|
|
here-doc-text
|
|
...
|
|
delimiter
|
|
.Ed
|
|
.Pp
|
|
All the text on successive lines up to the delimiter is
|
|
saved away and made available to the command on standard
|
|
input, or file descriptor n if it is specified. If the delimiter
|
|
as specified on the initial line is quoted, then the here-doc-text
|
|
is treated literally, otherwise the text is subjected to
|
|
parameter expansion, command substitution, and arithmetic
|
|
expansion (as described in the section on
|
|
.Sx Word Expansions ) .
|
|
If the operator is
|
|
.Dq Li <<-
|
|
instead of
|
|
.Dq Li << ,
|
|
then leading tabs
|
|
in the here-doc-text are stripped.
|
|
.Ss Search and Execution
|
|
There are three types of commands: shell functions,
|
|
builtin commands, and normal programs.
|
|
The command is searched for (by name) in that order.
|
|
The three types of commands are all executed in a different way.
|
|
.Pp
|
|
When a shell function is executed, all of the shell positional
|
|
parameters (except $0, which remains unchanged) are
|
|
set to the arguments of the shell function.
|
|
The variables which are explicitly placed in the environment of
|
|
the command (by placing assignments to them before the
|
|
function name) are made local to the function and are set
|
|
to the values given.
|
|
Then the command given in the function definition is executed.
|
|
The positional parameters are restored to their original values
|
|
when the command completes.
|
|
This all occurs within the current shell.
|
|
.Pp
|
|
Shell builtin commands are executed internally to the shell, without
|
|
spawning a new process.
|
|
.Pp
|
|
Otherwise, if the command name does not match a function
|
|
or builtin command, the command is searched for as a normal
|
|
program in the filesystem (as described in the next section).
|
|
When a normal program is executed, the shell runs the program,
|
|
passing the arguments and the environment to the program.
|
|
If the program is not a normal executable file
|
|
(i.e. if it does not begin with the
|
|
.Qq magic number
|
|
whose
|
|
.Tn ASCII
|
|
representation is
|
|
.Qq #! ,
|
|
resulting in an
|
|
.Er ENOEXEC
|
|
return value from
|
|
.Xr execve 2 )
|
|
the shell will interpret the program in a subshell.
|
|
The child shell will reinitialize itself in this case,
|
|
so that the effect will be
|
|
as if a new shell had been invoked to handle the ad-hoc shell script,
|
|
except that the location of hashed commands located in
|
|
the parent shell will be remembered by the child.
|
|
.Pp
|
|
Note that previous versions of this document
|
|
and the source code itself misleadingly and sporadically
|
|
refer to a shell script without a magic number
|
|
as a
|
|
.Qq shell procedure .
|
|
.Ss Path Search
|
|
When locating a command, the shell first looks to see if
|
|
it has a shell function by that name. Then it looks for a
|
|
builtin command by that name. If a builtin command is not found,
|
|
one of two things happen:
|
|
.Bl -enum
|
|
.It
|
|
Command names containing a slash are simply executed without
|
|
performing any searches.
|
|
.It
|
|
The shell searches each entry in
|
|
.Ev PATH
|
|
in turn for the command. The value of the
|
|
.Ev PATH
|
|
variable should be a series of
|
|
entries separated by colons. Each entry consists of a
|
|
directory name.
|
|
The current directory
|
|
may be indicated implicitly by an empty directory name,
|
|
or explicitly by a single period.
|
|
.El
|
|
.Ss Command Exit Status
|
|
Each command has an exit status that can influence the behavior
|
|
of other shell commands. The paradigm is that a command exits
|
|
with zero for normal or success, and non-zero for failure,
|
|
error, or a false indication. The man page for each command
|
|
should indicate the various exit codes and what they mean.
|
|
Additionally, the builtin commands return exit codes, as does
|
|
an executed shell function.
|
|
.Pp
|
|
If a command is terminated by a signal, its exit status is 128 plus
|
|
the signal number. Signal numbers are defined in the header file
|
|
.Aq Pa sys/signal.h .
|
|
.Ss Complex Commands
|
|
Complex commands are combinations of simple commands
|
|
with control operators or reserved words, together creating a larger complex
|
|
command. More generally, a command is one of the following:
|
|
.Bl -item -offset indent
|
|
.It
|
|
simple command
|
|
.It
|
|
pipeline
|
|
.It
|
|
list or compound-list
|
|
.It
|
|
compound command
|
|
.It
|
|
function definition
|
|
.El
|
|
.Pp
|
|
Unless otherwise stated, the exit status of a command is
|
|
that of the last simple command executed by the command.
|
|
.Ss Pipelines
|
|
A pipeline is a sequence of one or more commands separated
|
|
by the control operator |. The standard output of all but
|
|
the last command is connected to the standard input
|
|
of the next command. The standard output of the last
|
|
command is inherited from the shell, as usual.
|
|
.Pp
|
|
The format for a pipeline is:
|
|
.Pp
|
|
.Dl [!] command1 [ | command2 ...]
|
|
.Pp
|
|
The standard output of command1 is connected to the standard
|
|
input of command2. The standard input, standard output, or
|
|
both of a command is considered to be assigned by the
|
|
pipeline before any redirection specified by redirection
|
|
operators that are part of the command.
|
|
.Pp
|
|
If the pipeline is not in the background (discussed later),
|
|
the shell waits for all commands to complete.
|
|
.Pp
|
|
If the reserved word ! does not precede the pipeline, the
|
|
exit status is the exit status of the last command specified
|
|
in the pipeline. Otherwise, the exit status is the logical
|
|
NOT of the exit status of the last command. That is, if
|
|
the last command returns zero, the exit status is 1; if
|
|
the last command returns greater than zero, the exit status
|
|
is zero.
|
|
.Pp
|
|
Because pipeline assignment of standard input or standard
|
|
output or both takes place before redirection, it can be
|
|
modified by redirection. For example:
|
|
.Pp
|
|
.Dl $ command1 2>&1 | command2
|
|
.Pp
|
|
sends both the standard output and standard error of
|
|
.Ql command1
|
|
to the standard input of
|
|
.Ql command2 .
|
|
.Pp
|
|
A
|
|
.Dq Li \&;
|
|
or newline terminator causes the preceding
|
|
AND-OR-list
|
|
(described below in the section called
|
|
.Sx Short-Circuit List Operators )
|
|
to be executed sequentially;
|
|
an
|
|
.Dq Li &
|
|
causes asynchronous execution of the preceding AND-OR-list.
|
|
.Pp
|
|
Note that unlike some other shells,
|
|
.Nm
|
|
executes each process in the pipeline as a child of the
|
|
.Nm
|
|
process.
|
|
Shell builtin commands are the exception to this rule.
|
|
They are executed in the current shell, although they do not affect its
|
|
environment when used in pipelines.
|
|
.Ss Background Commands (&)
|
|
If a command is terminated by the control operator ampersand
|
|
.Pq Li & ,
|
|
the shell executes the command asynchronously;
|
|
the shell does not wait for the command to finish
|
|
before executing the next command.
|
|
.Pp
|
|
The format for running a command in background is:
|
|
.Bd -literal -offset indent
|
|
command1 & [command2 & ...]
|
|
.Ed
|
|
.Pp
|
|
If the shell is not interactive, the standard input of an
|
|
asynchronous command is set to /dev/null.
|
|
.Ss Lists (Generally Speaking)
|
|
A list is a sequence of zero or more commands separated by
|
|
newlines, semicolons, or ampersands,
|
|
and optionally terminated by one of these three characters.
|
|
The commands in a
|
|
list are executed in the order they are written.
|
|
If command is followed by an ampersand, the shell starts the
|
|
command and immediately proceed onto the next command;
|
|
otherwise it waits for the command to terminate before
|
|
proceeding to the next one.
|
|
.Ss Short-Circuit List Operators
|
|
.Dq Li &&
|
|
and
|
|
.Dq Li ||
|
|
are AND-OR list operators.
|
|
.Dq Li &&
|
|
executes the first command, and then executes the second command
|
|
if the exit status of the first command is zero.
|
|
.Dq Li ||
|
|
is similar, but executes the second command if the exit
|
|
status of the first command is nonzero.
|
|
.Dq Li &&
|
|
and
|
|
.Dq Li ||
|
|
both have the same priority.
|
|
.Ss Flow-Control Constructs (if, while, for, case)
|
|
The syntax of the
|
|
.Ic if
|
|
command is:
|
|
.\"
|
|
.\" XXX Use .Dl to work around broken handling of .Ic inside .Bd and .Ed .
|
|
.\"
|
|
.Dl Ic if Ar list
|
|
.Dl Ic then Ar list
|
|
.Dl [ Ic elif Ar list
|
|
.Dl Ic then Ar list ] ...
|
|
.Dl [ Ic else Ar list ]
|
|
.Dl Ic fi
|
|
.Pp
|
|
The syntax of the
|
|
.Ic while
|
|
command is:
|
|
.Dl Ic while Ar list
|
|
.Dl Ic do Ar list
|
|
.Dl Ic done
|
|
.Pp
|
|
The two lists are executed repeatedly while the exit status of the
|
|
first list is zero.
|
|
The
|
|
.Ic until
|
|
command is similar, but has the word
|
|
.Ic until
|
|
in place of
|
|
.Ic while ,
|
|
which causes it to
|
|
repeat until the exit status of the first list is zero.
|
|
.Pp
|
|
The syntax of the
|
|
.Ic for
|
|
command is:
|
|
.Dl Ic for Ar variable Ic in Ar word ...
|
|
.Dl Ic do Ar list
|
|
.Dl Ic done
|
|
.Pp
|
|
The words are expanded, and then the list is executed
|
|
repeatedly with the variable set to each word in turn.
|
|
The
|
|
.Ic do
|
|
and
|
|
.Ic done
|
|
commands may be replaced with
|
|
.Dq Li {
|
|
and
|
|
.Dq Li } .
|
|
.Pp
|
|
The syntax of the
|
|
.Ic break
|
|
and
|
|
.Ic continue
|
|
commands is:
|
|
.Dl Ic break Op Ar num
|
|
.Dl Ic continue Op Ar num
|
|
.Pp
|
|
The
|
|
.Ic break
|
|
command terminates the
|
|
.Ar num
|
|
innermost
|
|
.Ic for
|
|
or
|
|
.Ic while
|
|
loops.
|
|
The
|
|
.Ic continue
|
|
command continues with the next iteration of the innermost loop.
|
|
These are implemented as builtin commands.
|
|
.Pp
|
|
The syntax of the
|
|
.Ic case
|
|
command is
|
|
.Dl Ic case Ar word Ic in
|
|
.Dl pattern) list ;;
|
|
.Dl ...
|
|
.Dl Ic esac
|
|
.Pp
|
|
The pattern can actually be one or more patterns
|
|
(see
|
|
.Sx Shell Patterns
|
|
described later),
|
|
separated by
|
|
.Dq Li \&|
|
|
characters.
|
|
.Ss Grouping Commands Together
|
|
Commands may be grouped by writing either
|
|
.Bd -literal -offset indent
|
|
(list)
|
|
.Ed
|
|
.Pp
|
|
or
|
|
.Bd -literal -offset indent
|
|
{ list; }
|
|
.Ed
|
|
.Pp
|
|
The first form executes the commands in a subshell.
|
|
Note that builtin commands thus executed do not affect the current shell.
|
|
The second form does not fork another shell,
|
|
so it is slightly more efficient.
|
|
Grouping commands together this way allows the user to
|
|
redirect their output as though they were one program:
|
|
.Bd -literal -offset indent
|
|
{ echo -n "hello"; echo " world"; } > greeting
|
|
.Ed
|
|
.Ss Functions
|
|
The syntax of a function definition is
|
|
.Bd -literal -offset indent
|
|
name ( ) command
|
|
.Ed
|
|
.Pp
|
|
A function definition is an executable statement; when
|
|
executed it installs a function named name and returns an
|
|
exit status of zero. The command is normally a list
|
|
enclosed between
|
|
.Dq Li {
|
|
and
|
|
.Dq Li } .
|
|
.Pp
|
|
Variables may be declared to be local to a function by
|
|
using the
|
|
.Ic local
|
|
command.
|
|
This should appear as the first statement of a function,
|
|
and the syntax is:
|
|
.Bd -ragged -offset indent
|
|
.Ic local
|
|
.Op Ar variable ...\&
|
|
.Op Ar -
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Ic local
|
|
command is implemented as a builtin command.
|
|
.Pp
|
|
When a variable is made local, it inherits the initial
|
|
value and exported and readonly flags from the variable
|
|
with the same name in the surrounding scope, if there is
|
|
one. Otherwise, the variable is initially unset. The shell
|
|
uses dynamic scoping, so that if the variable
|
|
.Em x
|
|
is made local to function
|
|
.Em f ,
|
|
which then calls function
|
|
.Em g ,
|
|
references to the variable
|
|
.Em x
|
|
made inside
|
|
.Em g
|
|
will refer to the variable
|
|
.Em x
|
|
declared inside
|
|
.Em f ,
|
|
not to the global variable named
|
|
.Em x .
|
|
.Pp
|
|
The only special parameter than can be made local is
|
|
.Dq Li - .
|
|
Making
|
|
.Dq Li -
|
|
local causes any shell options that are
|
|
changed via the set command inside the function to be
|
|
restored to their original values when the function
|
|
returns.
|
|
.Pp
|
|
The syntax of the
|
|
.Ic return
|
|
command is
|
|
.Bd -ragged -offset indent
|
|
.Ic return
|
|
.Op Ar exitstatus
|
|
.Ed
|
|
.Pp
|
|
It terminates the currently executing function.
|
|
The
|
|
.Ic return
|
|
command is implemented as a builtin command.
|
|
.Ss Variables and Parameters
|
|
The shell maintains a set of parameters. A parameter
|
|
denoted by a name is called a variable. When starting up,
|
|
the shell turns all the environment variables into shell
|
|
variables. New variables can be set using the form
|
|
.Bd -literal -offset indent
|
|
name=value
|
|
.Ed
|
|
.Pp
|
|
Variables set by the user must have a name consisting solely
|
|
of alphabetics, numerics, and underscores.
|
|
The first letter of a variable name must not be numeric.
|
|
A parameter can also be denoted by a number
|
|
or a special character as explained below.
|
|
.Ss Positional Parameters
|
|
A positional parameter is a parameter denoted by a number greater than zero.
|
|
The shell sets these initially to the values of its command line
|
|
arguments that follow the name of the shell script. The
|
|
.Ic set
|
|
builtin command can also be used to set or reset them.
|
|
.Ss Special Parameters
|
|
A special parameter is a parameter denoted by one of the following
|
|
special characters. The value of the parameter is listed
|
|
next to its character.
|
|
.Bl -hang
|
|
.It Li *
|
|
Expands to the positional parameters, starting from one. When
|
|
the expansion occurs within a double-quoted string
|
|
it expands to a single field with the value of each parameter
|
|
separated by the first character of the
|
|
.Ev IFS
|
|
variable,
|
|
or by a
|
|
.Aq space
|
|
if
|
|
.Ev IFS
|
|
is unset.
|
|
.It Li @
|
|
Expands to the positional parameters, starting from one. When
|
|
the expansion occurs within double-quotes, each positional
|
|
parameter expands as a separate argument.
|
|
If there are no positional parameters, the
|
|
expansion of
|
|
.Li @
|
|
generates zero arguments, even when
|
|
.Li @
|
|
is double-quoted. What this basically means, for example, is
|
|
if $1 is
|
|
.Dq abc
|
|
and $2 is
|
|
.Dq def ghi ,
|
|
then
|
|
.Qq Li $@
|
|
expands to
|
|
the two arguments:
|
|
.Bd -literal -offset indent
|
|
"abc" "def ghi"
|
|
.Ed
|
|
.It Li #
|
|
Expands to the number of positional parameters.
|
|
.It Li \&?
|
|
Expands to the exit status of the most recent pipeline.
|
|
.It Li -
|
|
(hyphen) Expands to the current option flags (the single-letter
|
|
option names concatenated into a string) as specified on
|
|
invocation, by the set builtin command, or implicitly
|
|
by the shell.
|
|
.It Li $
|
|
Expands to the process ID of the invoked shell. A subshell
|
|
retains the same value of $ as its parent.
|
|
.It Li \&!
|
|
Expands to the process ID of the most recent background
|
|
command executed from the current shell. For a
|
|
pipeline, the process ID is that of the last command in the
|
|
pipeline.
|
|
.It Li 0
|
|
(zero) Expands to the name of the shell or shell script.
|
|
.El
|
|
.Ss Word Expansions
|
|
This clause describes the various expansions that are
|
|
performed on words. Not all expansions are performed on
|
|
every word, as explained later.
|
|
.Pp
|
|
Tilde expansions, parameter expansions, command substitutions,
|
|
arithmetic expansions, and quote removals that occur within
|
|
a single word expand to a single field. It is only field
|
|
splitting or pathname expansion that can create multiple
|
|
fields from a single word.
|
|
The single exception to this rule is
|
|
the expansion of the special parameter
|
|
.Li @
|
|
within double-quotes,
|
|
as was described above.
|
|
.Pp
|
|
The order of word expansion is:
|
|
.Bl -enum
|
|
.It
|
|
Tilde Expansion, Parameter Expansion, Command Substitution,
|
|
Arithmetic Expansion (these all occur at the same time).
|
|
.It
|
|
Field Splitting is performed on fields generated by step (1)
|
|
unless the
|
|
.Ev IFS
|
|
variable is null.
|
|
.It
|
|
Pathname Expansion (unless the
|
|
.Fl f
|
|
option is in effect).
|
|
.It
|
|
Quote Removal.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Dq Li $
|
|
character is used to introduce parameter expansion, command
|
|
substitution, or arithmetic evaluation.
|
|
.Ss Tilde Expansion (substituting a user's home directory)
|
|
A word beginning with an unquoted tilde character
|
|
.Pq Li ~
|
|
is
|
|
subjected to tilde expansion.
|
|
All the characters up to a slash
|
|
.Pq Li /
|
|
or the end of the word are treated as a username
|
|
and are replaced with the user's home directory. If the
|
|
username is missing (as in ~/foobar), the tilde is replaced
|
|
with the value of the HOME variable (the current user's
|
|
home directory).
|
|
.Ss Parameter Expansion
|
|
The format for parameter expansion is as follows:
|
|
.Bd -literal -offset indent
|
|
${expression}
|
|
.Ed
|
|
.Pp
|
|
where expression consists of all characters until the matching
|
|
.Dq Li } .
|
|
Any
|
|
.Dq Li }
|
|
escaped by a backslash or within a quoted string, and characters in
|
|
embedded arithmetic expansions, command substitutions, and variable
|
|
expansions, are not examined in determining the matching
|
|
.Dq Li } .
|
|
.Pp
|
|
The simplest form for parameter expansion is:
|
|
.Bd -literal -offset indent
|
|
${parameter}
|
|
.Ed
|
|
.Pp
|
|
The value, if any, of parameter is substituted.
|
|
.Pp
|
|
The parameter name or symbol can be enclosed in braces, which are
|
|
optional except for positional parameters with more than one digit or
|
|
when parameter is followed by a character that could be interpreted as
|
|
part of the name.
|
|
If a parameter expansion occurs inside double-quotes:
|
|
.Bl -enum
|
|
.It
|
|
Pathname expansion is not performed on the results of the
|
|
expansion.
|
|
.It
|
|
Field splitting is not performed on the results of the
|
|
expansion, with the exception of the special parameter
|
|
.Li @ .
|
|
.El
|
|
.Pp
|
|
In addition, a parameter expansion can be modified by using one of the
|
|
following formats.
|
|
.Bl -tag -width Ds
|
|
.It Li ${parameter:-word}
|
|
Use Default Values. If parameter is unset or
|
|
null, the expansion of word is
|
|
substituted; otherwise, the value of
|
|
parameter is substituted.
|
|
.It Li ${parameter:=word}
|
|
Assign Default Values. If parameter is unset
|
|
or null, the expansion of word is
|
|
assigned to parameter. In all cases, the
|
|
final value of parameter is
|
|
substituted. Only variables, not positional
|
|
parameters or special parameters, can be
|
|
assigned in this way.
|
|
.It Li ${parameter:?[word]}
|
|
Indicate Error if Null or Unset. If
|
|
parameter is unset or null, the expansion of
|
|
word (or a message indicating it is unset if
|
|
word is omitted) is written to standard
|
|
error and the shell exits with a nonzero
|
|
exit status.
|
|
Otherwise, the value of
|
|
parameter is substituted. An
|
|
interactive shell need not exit.
|
|
.It Li ${parameter:+word}
|
|
Use Alternate Value. If parameter is unset
|
|
or null, null is substituted;
|
|
otherwise, the expansion of word is
|
|
substituted.
|
|
.Pp
|
|
In the parameter expansions shown previously, use of the colon in the
|
|
format results in a test for a parameter that is unset or null; omission
|
|
of the colon results in a test for a parameter that is only unset.
|
|
.It Li ${#parameter}
|
|
String Length. The length in characters of
|
|
the value of parameter.
|
|
.Pp
|
|
The following four varieties of parameter expansion provide for substring
|
|
processing.
|
|
In each case, pattern matching notation
|
|
(see
|
|
.Sx Shell Patterns ) ,
|
|
rather than regular expression notation,
|
|
is used to evaluate the patterns.
|
|
If parameter is one of the special parameters
|
|
.Li *
|
|
or
|
|
.Li @ ,
|
|
the result of the expansion is unspecified.
|
|
Enclosing the full parameter expansion string in double-quotes does not
|
|
cause the following four varieties of pattern characters to be quoted,
|
|
whereas quoting characters within the braces has this effect.
|
|
.It Li ${parameter%word}
|
|
Remove Smallest Suffix Pattern. The word
|
|
is expanded to produce a pattern. The
|
|
parameter expansion then results in
|
|
parameter, with the smallest portion of the
|
|
suffix matched by the pattern deleted.
|
|
.It Li ${parameter%%word}
|
|
Remove Largest Suffix Pattern. The word
|
|
is expanded to produce a pattern. The
|
|
parameter expansion then results in
|
|
parameter, with the largest portion of the
|
|
suffix matched by the pattern deleted.
|
|
.It Li ${parameter#word}
|
|
Remove Smallest Prefix Pattern. The word
|
|
is expanded to produce a pattern. The
|
|
parameter expansion then results in
|
|
parameter, with the smallest portion of the
|
|
prefix matched by the pattern deleted.
|
|
.It Li ${parameter##word}
|
|
Remove Largest Prefix Pattern. The word
|
|
is expanded to produce a pattern. The
|
|
parameter expansion then results in
|
|
parameter, with the largest portion of the
|
|
prefix matched by the pattern deleted.
|
|
.El
|
|
.Ss Command Substitution
|
|
Command substitution allows the output of a command to be substituted in
|
|
place of the command name itself. Command substitution occurs when
|
|
the command is enclosed as follows:
|
|
.Bd -literal -offset indent
|
|
$(command)
|
|
.Ed
|
|
.Pp
|
|
or the backquoted version:
|
|
.Bd -literal -offset indent
|
|
`command`
|
|
.Ed
|
|
.Pp
|
|
The shell expands the command substitution by executing command in a
|
|
subshell environment and replacing the command substitution
|
|
with the standard output of the command,
|
|
removing sequences of one or more newlines at the end of the substitution.
|
|
Embedded newlines before the end of the output are not removed;
|
|
however, during field splitting, they may be translated into spaces
|
|
depending on the value of
|
|
.Ev IFS
|
|
and the quoting that is in effect.
|
|
.Ss Arithmetic Expansion
|
|
Arithmetic expansion provides a mechanism for evaluating an arithmetic
|
|
expression and substituting its value.
|
|
The format for arithmetic expansion is as follows:
|
|
.Bd -literal -offset indent
|
|
$((expression))
|
|
.Ed
|
|
.Pp
|
|
The expression is treated as if it were in double-quotes, except
|
|
that a double-quote inside the expression is not treated specially. The
|
|
shell expands all tokens in the expression for parameter expansion,
|
|
command substitution, and quote removal.
|
|
.Pp
|
|
Next, the shell treats this as an arithmetic expression and
|
|
substitutes the value of the expression.
|
|
.Ss White Space Splitting (Field Splitting)
|
|
After parameter expansion, command substitution, and
|
|
arithmetic expansion the shell scans the results of
|
|
expansions and substitutions that did not occur in double-quotes for
|
|
field splitting and multiple fields can result.
|
|
.Pp
|
|
The shell treats each character of the
|
|
.Ev IFS
|
|
as a delimiter and uses
|
|
the delimiters to split the results of parameter expansion and command
|
|
substitution into fields.
|
|
.Ss Pathname Expansion (File Name Generation)
|
|
Unless the
|
|
.Fl f
|
|
option is set,
|
|
file name generation is performed
|
|
after word splitting is complete. Each word is
|
|
viewed as a series of patterns, separated by slashes. The
|
|
process of expansion replaces the word with the names of
|
|
all existing files whose names can be formed by replacing
|
|
each pattern with a string that matches the specified pattern.
|
|
There are two restrictions on this: first, a pattern cannot match
|
|
a string containing a slash, and second,
|
|
a pattern cannot match a string starting with a period
|
|
unless the first character of the pattern is a period.
|
|
The next section describes the patterns used for both
|
|
Pathname Expansion and the
|
|
.Ic case
|
|
command.
|
|
.Ss Shell Patterns
|
|
A pattern consists of normal characters, which match themselves,
|
|
and meta-characters.
|
|
The meta-characters are
|
|
.Dq Li \&! ,
|
|
.Dq Li * ,
|
|
.Dq Li \&? ,
|
|
and
|
|
.Dq Li [ .
|
|
These characters lose their special meanings if they are quoted.
|
|
When command or variable substitution is performed and the dollar sign
|
|
or back quotes are not double-quoted, the value of the
|
|
variable or the output of the command is scanned for these
|
|
characters and they are turned into meta-characters.
|
|
.Pp
|
|
An asterisk
|
|
.Pq Li *
|
|
matches any string of characters.
|
|
A question mark
|
|
.Pq Li \&?
|
|
matches any single character.
|
|
A left bracket
|
|
.Pq Li [
|
|
introduces a character class.
|
|
The end of the character class is indicated by a
|
|
.Dq Li \&] ;
|
|
if the
|
|
.Dq Li \&]
|
|
is missing then the
|
|
.Dq Li [
|
|
matches a
|
|
.Dq Li [
|
|
rather than introducing a character class.
|
|
A character class matches any of the characters between the square brackets.
|
|
A range of characters may be specified using a minus sign.
|
|
The character class may be complemented by making an exclamation point
|
|
.Pq Li !\&
|
|
the first character of the character class.
|
|
.Pp
|
|
To include a
|
|
.Dq Li \&]
|
|
in a character class, make it the first character listed
|
|
(after the
|
|
.Dq Li \&! ,
|
|
if any).
|
|
To include a
|
|
.Dq Li - ,
|
|
make it the first or last character listed.
|
|
.Ss Builtin Commands
|
|
This section lists the commands which
|
|
are builtin because they need to perform some operation
|
|
that can not be performed by a separate process. In addition to
|
|
these, a builtin version of the
|
|
.Xr printf 1
|
|
command is provided for efficiency.
|
|
.Bl -tag -width Ds
|
|
.It Ic \&:
|
|
A null command that returns a 0 (true) exit value.
|
|
.It Ic \&. Ar file
|
|
The commands in the specified file are read and executed by the shell.
|
|
If
|
|
.Ar file
|
|
contains any
|
|
.Dq /
|
|
characters, it is used as is. Otherwise, the shell searches the
|
|
.Ev PATH
|
|
for the file. If it is not found in the
|
|
.Ev PATH ,
|
|
it is sought in the current working directory.
|
|
.It Ic alias Op Ar name ...
|
|
.It Ic alias Xo
|
|
.Op Ar name Ns = Ns Ar string ...
|
|
.Xc
|
|
If
|
|
.Ar name Ns = Ns Ar string
|
|
is specified, the shell defines the alias
|
|
.Ar name
|
|
with value
|
|
.Ar string .
|
|
If just
|
|
.Ar name
|
|
is specified, the value of the alias
|
|
.Ar name
|
|
is printed.
|
|
With no arguments, the
|
|
.Ic alias
|
|
builtin command prints the names and values of all defined aliases
|
|
(see
|
|
.Ic unalias ) .
|
|
.It Ic bg Op Ar job ...
|
|
Continue the specified jobs
|
|
(or the current job if no jobs are given)
|
|
in the background.
|
|
.It Ic command Ar cmd Op Ar arg ...
|
|
Execute the specified builtin command,
|
|
.Ar cmd .
|
|
This is useful when the user wishes to override a shell function
|
|
with the same name as a builtin command.
|
|
.It Ic cd Op Ar directory
|
|
Switch to the specified
|
|
.Ar directory ,
|
|
or to the directory specified in the
|
|
.Ev HOME
|
|
environment variable if no
|
|
.Ar directory
|
|
is specified.
|
|
If
|
|
.Ar directory
|
|
is not found as a subdirectory of the current directory
|
|
(and does not begin with
|
|
.Dq Li / ,
|
|
.Dq Li ./ ,
|
|
or
|
|
.Dq Li ../ ) ,
|
|
then the directories listed in the
|
|
.Ev CDPATH
|
|
variable will be
|
|
searched for the specified
|
|
.Ar directory .
|
|
The format of
|
|
.Ar CDPATH
|
|
is the same as that of
|
|
.Ev PATH .
|
|
In an interactive shell,
|
|
the
|
|
.Ic cd
|
|
command will print out the name of the directory
|
|
that it actually switched to
|
|
if this is different from the name that the user gave.
|
|
These may be different either because the
|
|
.Ev CDPATH
|
|
mechanism was used or because a symbolic link was crossed.
|
|
.It Xo
|
|
.Ic echo
|
|
.Op Fl en
|
|
.Ar string
|
|
.Xc
|
|
Print
|
|
.Ar string
|
|
to the standard output with a newline appended.
|
|
.Bl -tag -width Ds
|
|
.It Fl n
|
|
Suppress the output of the trailing newline.
|
|
.It Fl e
|
|
Process C-style backslash escape sequences.
|
|
.Ic echo
|
|
understands the following character escapes:
|
|
.Bl -tag -width Ds
|
|
.It \ea
|
|
Alert (ring the terminal bell)
|
|
.It \eb
|
|
Backspace
|
|
.It \ec
|
|
Suppress the trailing newline (this has the side-effect of truncating the
|
|
line if it is not the last character)
|
|
.It \ee
|
|
The ESC character (ASCII 0x1b)
|
|
.It \ef
|
|
Formfeed
|
|
.It \en
|
|
Newline
|
|
.It \er
|
|
Carriage return
|
|
.It \et
|
|
Horizontal tab
|
|
.It \ev
|
|
Vertical tab
|
|
.It \e\e
|
|
Literal backslash
|
|
.It \e0nnn
|
|
(Zero) The character whose octal value is nnn
|
|
.El
|
|
.Pp
|
|
If
|
|
.Ar string
|
|
is not enclosed in quotes then the backslash itself must be escaped
|
|
with a backslash to protect it from the shell. For example
|
|
.Bd -literal -offset indent
|
|
$ echo -e "a\evb"
|
|
a
|
|
b
|
|
$ echo -e a\e\evb
|
|
a
|
|
b
|
|
$ echo -e "a\e\eb"
|
|
a\eb
|
|
$ echo -e a\e\e\e\eb
|
|
a\eb
|
|
.Ed
|
|
.El
|
|
.It Ic eval Ar string ...
|
|
Concatenate all the arguments with spaces.
|
|
Then re-parse and execute the command.
|
|
.It Ic exec Op Ar command Op arg ...
|
|
Unless
|
|
.Ar command
|
|
is omitted,
|
|
the shell process is replaced with the specified program
|
|
(which must be a real program, not a shell builtin command or function).
|
|
Any redirections on the
|
|
.Ic exec
|
|
command are marked as permanent,
|
|
so that they are not undone when the
|
|
.Ic exec
|
|
command finishes.
|
|
.It Ic exit Op Ar exitstatus
|
|
Terminate the shell process.
|
|
If
|
|
.Ar exitstatus
|
|
is given
|
|
it is used as the exit status of the shell;
|
|
otherwise the exit status of the preceding command is used.
|
|
.It Ic export Ar name ...
|
|
The specified names are exported so that they will
|
|
appear in the environment of subsequent commands.
|
|
The only way to un-export a variable is to
|
|
.Ic unset
|
|
it.
|
|
The shell allows the value of a variable to be set
|
|
at the same time as it is exported by writing
|
|
.Bd -literal -offset indent
|
|
export name=value
|
|
.Ed
|
|
.Pp
|
|
With no arguments the export command lists the names
|
|
of all exported variables.
|
|
.It Xo
|
|
.Ic fc
|
|
.Op Fl e Ar editor
|
|
.Op Ar first Op Ar last
|
|
.Xc
|
|
.It Xo
|
|
.Ic fc
|
|
.Fl l
|
|
.Op Fl nr
|
|
.Op Ar first Op Ar last
|
|
.Xc
|
|
.It Xo
|
|
.Ic fc
|
|
.Fl s
|
|
.Op Ar old=new
|
|
.Op Ar first
|
|
.Xc
|
|
The
|
|
.Ic fc
|
|
builtin command lists, or edits and re-executes,
|
|
commands previously entered to an interactive shell.
|
|
.Bl -tag -width Ds
|
|
.It Fl e Ar editor
|
|
Use the editor named by
|
|
.Ar editor
|
|
to edit the commands.
|
|
The editor string is a command name,
|
|
subject to search via the
|
|
.Ev PATH
|
|
variable.
|
|
The value in the
|
|
.Ev FCEDIT
|
|
variable is used as a default when
|
|
.Fl e
|
|
is not specified.
|
|
If
|
|
.Ev FCEDIT
|
|
is null or unset, the value of the
|
|
.Ev EDITOR
|
|
variable is used.
|
|
If
|
|
.Ev EDITOR
|
|
is null or unset,
|
|
.Xr ed 1
|
|
is used as the editor.
|
|
.It Fl l No (ell)
|
|
List the commands rather than invoking
|
|
an editor on them. The commands are written in the
|
|
sequence indicated by the first and last operands, as
|
|
affected by
|
|
.Fl r ,
|
|
with each command preceded by the command number.
|
|
.It Fl n
|
|
Suppress command numbers when listing with
|
|
.Fl l .
|
|
.It Fl r
|
|
Reverse the order of the commands listed
|
|
(with
|
|
.Fl l )
|
|
or edited
|
|
(with neither
|
|
.Fl l
|
|
nor
|
|
.Fl s ) .
|
|
.It Fl s
|
|
Re-execute the command without invoking an editor.
|
|
.It Ar first
|
|
.It Ar last
|
|
Select the commands to list or edit.
|
|
The number of previous commands that can be accessed
|
|
are determined by the value of the
|
|
.Ev HISTSIZE
|
|
variable.
|
|
The value of
|
|
.Ar first
|
|
or
|
|
.Ar last
|
|
or both are one of the following:
|
|
.Bl -tag -width Ds
|
|
.It Ar [+]num
|
|
A positive number representing a command number;
|
|
command numbers can be displayed with the
|
|
.Fl l
|
|
option.
|
|
.It Ar -num
|
|
A negative decimal number representing the
|
|
command that was executed
|
|
.Ar num
|
|
of
|
|
commands previously.
|
|
For example, -1 is the immediately previous command.
|
|
.It Ar string
|
|
A string indicating the most recently entered command
|
|
that begins with that string.
|
|
If the
|
|
.Ar old=new
|
|
operand is not also specified with
|
|
.Fl s ,
|
|
the string form of the first operand cannot contain an embedded equal sign.
|
|
.El
|
|
.El
|
|
.Pp
|
|
The following environment variables affect the execution of
|
|
.Ic fc :
|
|
.Bl -tag -width Ds
|
|
.It Ev FCEDIT
|
|
Name of the editor to use.
|
|
.It Ev HISTSIZE
|
|
The number of previous commands that are accessible.
|
|
.El
|
|
.It Ic fg Op Ar job
|
|
Move the specified
|
|
.Ar job
|
|
or the current job to the foreground.
|
|
.It Ic getopts Ar optstring Ar var
|
|
The POSIX
|
|
.Ic getopts
|
|
command.
|
|
The
|
|
.Ic getopts
|
|
command deprecates the older
|
|
.Xr getopt 1
|
|
command.
|
|
The first argument should be a series of letters, each possibly
|
|
followed by a colon which indicates that the option takes an argument.
|
|
The specified variable is set to the parsed option. The index of
|
|
the next argument is placed into the shell variable
|
|
.Ev OPTIND .
|
|
If an option takes an argument, it is placed into the shell variable
|
|
.Ev OPTARG .
|
|
If an invalid option is encountered,
|
|
.Ev var
|
|
is set to
|
|
.Dq Li \&? .
|
|
It returns a false value (1) when it encounters the end of the options.
|
|
.It Xo
|
|
.Ic hash
|
|
.Op Fl rv
|
|
.Op Ar command ...
|
|
.Xc
|
|
The shell maintains a hash table which remembers the locations of commands.
|
|
With no arguments whatsoever, the
|
|
.Ic hash
|
|
command prints out the contents of this table.
|
|
Entries which have not been looked at since the last
|
|
.Ic cd
|
|
command are marked with an asterisk;
|
|
it is possible for these entries to be invalid.
|
|
.Pp
|
|
With arguments, the
|
|
.Ic hash
|
|
command removes each specified
|
|
.Ar command
|
|
from the hash table (unless they are functions) and then locates it.
|
|
With the
|
|
.Fl v
|
|
option,
|
|
.Ic hash
|
|
prints the locations of the commands as it finds them.
|
|
The
|
|
.Fl r
|
|
option causes the
|
|
.Ic hash
|
|
command to delete all the entries in the hash table except for functions.
|
|
.It Ic jobid Op Ar job
|
|
Print the process id's of the processes in the specified
|
|
.Ar job .
|
|
If the
|
|
.Ar job
|
|
argument is omitted, use the current job.
|
|
.It Ic jobs
|
|
This command lists out all the background processes
|
|
which are children of the current shell process.
|
|
.It Ic pwd
|
|
Print the path of the current directory. The builtin command may
|
|
differ from the program of the same name because the
|
|
builtin command remembers what the current directory
|
|
is rather than recomputing it each time. This makes
|
|
it faster. However, if the current directory is
|
|
renamed,
|
|
the builtin version of
|
|
.Xr pwd 1
|
|
will continue to print the old name for the directory.
|
|
.It Xo
|
|
.Ic read
|
|
.Op Fl p Ar prompt
|
|
.Op Fl t Ar timeout
|
|
.Op Fl er
|
|
.Ar variable ...
|
|
.Xc
|
|
The
|
|
.Ar prompt
|
|
is printed if the
|
|
.Fl p
|
|
option is specified
|
|
and the standard input is a terminal. Then a line is
|
|
read from the standard input. The trailing newline
|
|
is deleted from the line and the line is split as
|
|
described in the section on
|
|
.Sx White Space Splitting (Field Splitting)
|
|
above, and
|
|
the pieces are assigned to the variables in order.
|
|
If there are more pieces than variables, the remaining
|
|
pieces (along with the characters in
|
|
.Ev IFS
|
|
that separated them)
|
|
are assigned to the last variable.
|
|
If there are more variables than pieces, the remaining
|
|
variables are assigned the null string.
|
|
.Pp
|
|
Backslashes are treated specially, unless the
|
|
.Fl r
|
|
option is
|
|
specified. If a backslash is followed by
|
|
a newline, the backslash and the newline will be
|
|
deleted. If a backslash is followed by any other
|
|
character, the backslash will be deleted and the following
|
|
character will be treated as though it were not in
|
|
.Ev IFS ,
|
|
even if it is.
|
|
.Pp
|
|
If the
|
|
.Fl t
|
|
option is specified and the
|
|
.Ar timeout
|
|
elapses before any input is supplied,
|
|
the
|
|
.Ic read
|
|
command will return without assigning any values.
|
|
The
|
|
.Ar timeout
|
|
value may optionally be followed by one of
|
|
.Dq s ,
|
|
.Dq m
|
|
or
|
|
.Dq h
|
|
to explicitly specify seconds, minutes or or hours.
|
|
If none is supplied,
|
|
.Dq s
|
|
is assumed.
|
|
.Pp
|
|
The
|
|
.Fl e
|
|
option exists only for backward compatibility with older scripts.
|
|
.It Ic readonly Ar name ...
|
|
Each specified
|
|
.Ar name
|
|
is marked as read only,
|
|
so that it cannot be subsequently modified or unset.
|
|
The shell allows the value of a variable to be set
|
|
at the same time as it is marked read only
|
|
by using the following form:
|
|
.Bd -literal -offset indent
|
|
readonly name=value
|
|
.Ed
|
|
.Pp
|
|
With no arguments the
|
|
.Ic readonly
|
|
command lists the names of all read only variables.
|
|
.It Xo
|
|
.Ic set
|
|
.Op Fl /+abCEefIimnpTuVvx
|
|
.Op Fl /+o Ar longname
|
|
.Op Fl c Ar string
|
|
.Op Fl - Ar arg ...
|
|
.Xc
|
|
The
|
|
.Ic set
|
|
command performs three different functions:
|
|
.Bl -item
|
|
.It
|
|
With no arguments, it lists the values of all shell variables.
|
|
.It
|
|
If options are given,
|
|
either in short form or using the long
|
|
.Dq Fl /+o Ar longname
|
|
form,
|
|
it sets or clears the specified options as described in the section called
|
|
.Sx Argument List Processing .
|
|
.It
|
|
If the
|
|
.Dq Fl -
|
|
option is specified,
|
|
.Ic set
|
|
will replace the shell's positional parameters with the subsequent
|
|
arguments.
|
|
If no arguments follow the
|
|
.Dq Fl -
|
|
option,
|
|
all the positional parameters will be cleared,
|
|
which is equivalent to executing the command
|
|
.Dq Li shift $# .
|
|
The
|
|
.Dq Fl -
|
|
flag may be ommitted when specifying arguments to be used
|
|
as positional replacement parameters.
|
|
This is not recommended,
|
|
because the first argument may begin with a dash
|
|
.Pq Li -
|
|
or a plus
|
|
.Pq Li + ,
|
|
which the
|
|
.Ic set
|
|
command will interpret as a request to enable or disable options.
|
|
.El
|
|
.It Ic setvar Ar variable Ar value
|
|
Assigns the specified
|
|
.Ar value
|
|
to the specified
|
|
.Ar variable .
|
|
.Ic Setvar
|
|
is intended to be used in functions that
|
|
assign values to variables whose names are passed as parameters.
|
|
In general it is better to write
|
|
.Bd -literal -offset indent
|
|
variable=value
|
|
.Ed
|
|
rather than using
|
|
.Ic setvar .
|
|
.It Ic shift Op Ar n
|
|
Shift the positional parameters
|
|
.Ar n
|
|
times, or once if
|
|
.Ar n
|
|
is not specified.
|
|
A shift sets the value of $1 to the value of $2,
|
|
the value of $2 to the value of $3, and so on,
|
|
decreasing the value of $# by one.
|
|
If there are zero positional parameters, shifting does not do anything.
|
|
.It Xo
|
|
.Ic trap
|
|
.Op Ar action
|
|
.Ar signal ...
|
|
.Xc
|
|
Cause the shell to parse and execute
|
|
.Ar action
|
|
when any specified
|
|
.Ar signal
|
|
is received.
|
|
The signals are specified by signal number.
|
|
The
|
|
.Ar action
|
|
may be null or omitted;
|
|
the former causes the specified signal to be ignored
|
|
and the latter causes the default action to be taken.
|
|
When the shell forks off a subshell,
|
|
it resets trapped (but not ignored) signals to the default action.
|
|
The
|
|
.Ic trap
|
|
command has no effect on signals that were ignored on entry to the shell.
|
|
.It Ic type Op Ar name ...
|
|
Interpret each
|
|
.Ar name
|
|
as a command and print the resolution of the command search.
|
|
Possible resolutions are:
|
|
shell keyword, alias, shell builtin command, command, tracked alias
|
|
and not found.
|
|
For aliases the alias expansion is printed;
|
|
for commands and tracked aliases
|
|
the complete pathname of the command is printed.
|
|
.It Xo
|
|
.Ic ulimit
|
|
.Op Fl HSabcdflmnust
|
|
.Op Ar limit
|
|
.Xc
|
|
Set or display resource limits (see
|
|
.Xr getrlimit 2 ) .
|
|
If
|
|
.Ar limit
|
|
is specified, the named resource will be set;
|
|
otherwise the current resource value will be displayed.
|
|
.Pp
|
|
If
|
|
.Fl H
|
|
is specified, the hard limits will be set or displayed.
|
|
While everybody is allowed to reduce a hard limit,
|
|
only the superuser can increase it.
|
|
The
|
|
.Fl S
|
|
option
|
|
specifies the soft limits instead. When displaying limits,
|
|
only one of
|
|
.Fl S
|
|
or
|
|
.Fl H
|
|
can be given.
|
|
The default is to display the soft limits,
|
|
and to set both the hard and the soft limits.
|
|
.Pp
|
|
Option
|
|
.Fl a
|
|
causes the
|
|
.Ic ulimit
|
|
command to display all resources.
|
|
The parameter
|
|
.Ar limit
|
|
is not acceptable in this mode.
|
|
.Pp
|
|
The remaining options specify which resource value is to be
|
|
displayed or modified.
|
|
They are mutually exclusive.
|
|
.Bl -tag -width Ds
|
|
.It Fl b Ar sbsize
|
|
The maximum size of socket buffer usage, in bytes.
|
|
.It Fl c Ar coredumpsize
|
|
The maximal size of core dump files, in 512-byte blocks.
|
|
.It Fl d Ar datasize
|
|
The maximal size of the data segment of a process, in kilobytes.
|
|
.It Fl f Ar filesize
|
|
The maximal size of a file, in 512-byte blocks.
|
|
.It Fl l Ar lockedmem
|
|
The maximal size of memory that can be locked by a process, in
|
|
kilobytes.
|
|
.It Fl m Ar memoryuse
|
|
The maximal resident set size of a process, in kilobytes.
|
|
.It Fl n Ar nofiles
|
|
The maximal number of descriptors that could be opened by a process.
|
|
.It Fl s Ar stacksize
|
|
The maximal size of the stack segment, in kilobytes.
|
|
.It Fl t Ar time
|
|
The maximal amount of CPU time to be used by each process, in seconds.
|
|
.It Fl u Ar userproc
|
|
The maximal number of simultaneous processes for this user ID.
|
|
.El
|
|
.It Ic umask Op Ar mask
|
|
Set the file creation mask (see
|
|
.Xr umask 2 )
|
|
to the octal value specified by
|
|
.Ar mask .
|
|
If the argument is omitted, the current mask value is printed.
|
|
.It Xo
|
|
.Ic unalias
|
|
.Op Fl a
|
|
.Op Ar name
|
|
.Xc
|
|
If
|
|
.Ar name
|
|
is specified, the shell removes that alias.
|
|
If
|
|
.Fl a
|
|
is specified, all aliases are removed.
|
|
.It Ic unset Ar name ...
|
|
The specified variables and functions are unset and unexported.
|
|
If a given
|
|
.Ar name
|
|
corresponds to both a variable and a function,
|
|
both the variable and the function are unset.
|
|
.It Ic wait Op Ar job
|
|
Wait for the specified
|
|
.Ar job
|
|
to complete and return the exit status of the last process in the
|
|
.Ar job .
|
|
If the argument is omitted, wait for all jobs to complete
|
|
and return an exit status of zero.
|
|
.El
|
|
.Ss Commandline Editing
|
|
When
|
|
.Nm
|
|
is being used interactively from a terminal, the current command
|
|
and the command history
|
|
(see
|
|
.Ic fc
|
|
in
|
|
.Sx Builtin Commands )
|
|
can be edited using vi-mode command line editing.
|
|
This mode uses commands similar
|
|
to a subset of those described in the vi man page.
|
|
The command
|
|
.Dq Li set -o vi
|
|
(or
|
|
.Dq Li set -V )
|
|
enables vi-mode editing and places
|
|
.Nm
|
|
into vi insert mode. With vi-mode enabled,
|
|
.Nm
|
|
can be switched between insert mode and command mode by typing
|
|
.Aq ESC .
|
|
Hitting
|
|
.Aq return
|
|
while in command mode will pass the line to the shell.
|
|
.Pp
|
|
Similarly, the
|
|
.Dq Li set -o emacs
|
|
(or
|
|
.Dq Li set -E )
|
|
command can be used to enable a subset of
|
|
emacs-style command line editing features.
|
|
.Sh SEE ALSO
|
|
.Xr builtin 1 ,
|
|
.Xr echo 1 ,
|
|
.Xr expr 1 ,
|
|
.Xr pwd 1 ,
|
|
.Xr printf 1 ,
|
|
.Xr test 1
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
command appeared in
|
|
.At V.1 .
|