.\"	$NetBSD: t1,v 1.3 2010/08/22 02:19:07 perry Exp $
.\"
.\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" Redistributions of source code and documentation must retain the above
.\" copyright notice, this list of conditions and the following
.\" disclaimer.
.\"
.\" 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.
.\"
.\" All advertising materials mentioning features or use of this software
.\" must display the following acknowledgment:
.\"
.\" This product includes software developed or owned by Caldera
.\" International, Inc.  Neither the name of Caldera International, Inc.
.\" nor the names of other contributors may be used to endorse or promote
.\" products derived from this software without specific prior written
.\" permission.
.\"
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
.\" INTERNATIONAL, INC.  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 CALDERA INTERNATIONAL, INC. 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) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"	@(#)t1	8.1 (Berkeley) 8/14/93
.\"
.EH 'USD:3-%''An Introduction to the UNIX Shell'
.OH 'An Introduction to the UNIX Shell''USD:3-%'
.\".RP
.TL
An Introduction to the UNIX Shell
.AU
S. R. Bourne
.AI
Murray Hill, NJ
.AU
(Updated for 4.3BSD by Mark Seiden)
.AU
(Further updated by Perry E. Metzger)\(dg
.AB
.FS
\(dg This paper was updated in 2010 to reflect most features of modern
POSIX shells, which all follow the design of S.R. Bourne's original v7
Unix shell.
Among these are ash, bash, ksh and others.
Typically one of these will be installed as /bin/sh on a modern system.
It does not describe the behavior of the c shell (csh).
If it's the c shell (csh) you're interested in, a good place to
begin is William Joy's paper "An Introduction to the C shell" (USD:4).
.FE
.LP
The
.ul
shell
is a command programming language that provides an interface
to the
.UX
operating system.
Its features include
control-flow primitives, parameter passing, variables and
string substitution.
Constructs such as
.ul
while, if then else, case
and
.ul
for
are available.
Two-way communication is possible between the
.ul
shell
and commands.
String-valued parameters, typically file names or flags, may be
passed to a command.
A return code is set by commands that may be used to determine control-flow,
and the standard output from a command may be used
as shell input.
.LP
The
.ul
shell
can modify the environment
in which commands run.
Input and output can be redirected
to files, and processes that communicate through `pipes'
can be invoked.
Commands are found by
searching directories
in the file system in a
sequence that can be defined by the user.
Commands can be read either from the terminal or from a file,
which allows command procedures to be
stored for later use.
.AE
.ds ST \v'.3m'\s+2*\s0\v'-.3m'
.SH
1.0\ Introduction
.LP
The shell is both a command language
and a programming language
that provides an interface to the UNIX
operating system.
This memorandum describes, with
examples, the UNIX shell.
The first section covers most of the
everyday requirements
of terminal users.
Some familiarity with UNIX
is an advantage when reading this section;
see, for example,
"UNIX for beginners".
.[
unix beginn kernigh 1978
.]
Section 2 describes those features
of the shell primarily intended
for use within shell procedures.
These include the control-flow
primitives and string-valued variables
provided by the shell.
A knowledge of a programming language
would be a help when reading this section.
The last section describes the more
advanced features of the shell.
References of the form "see \fIpipe\fP (2)"
are to a section of the UNIX manual.
.[
seventh 1978 ritchie thompson
.]
.SH
1.1\ Simple\ commands
.LP
Simple commands consist of one or more words
separated by blanks.
The first word is the name of the command
to be executed; any remaining words
are passed as arguments to the command.
For example,
.DS
	who
.DE
is a command that prints the names
of users logged in.
The command
.DS
	ls \(mil
.DE
prints a list of files in the current
directory.
The argument \fI\(mil\fP tells \fIls\fP
to print status information, size and
the creation date for each file.
.SH
1.2\ Input\ output\ redirection
.LP
Most commands produce output on the standard output
that is initially connected to the terminal.
This output may be sent to a file
by writing, for example,
.DS
	ls \(mil >file
.DE
The notation \fI>file\fP
is interpreted by the shell and is not passed
as an argument to \fIls.\fP
If \fIfile\fP does not exist then the
shell creates it;
otherwise the original contents of
\fIfile\fP are replaced with the output
from \fIls.\fP
Output may be appended to a file
using the notation
.DS
	ls \(mil \*(APfile
.DE
In this case \fIfile\fP is also created if it does not already
exist.
.LP
The standard input of a command may be taken
from a file instead of the terminal by
writing, for example,
.DS
	wc <file
.DE
The command \fIwc\fP reads its standard input
(in this case redirected from \fIfile\fP)
and prints the number of characters, words and
lines found.
If only the number of lines is required
then
.DS
	wc \(mil <file
.DE
could be used.
.\" I considered adding the following, but have thought better of it
.\" for now.
.\" -- Perry Metzger
.\"
.\" .LP
.\" Error messages are typically printed by commands on a different
.\" channel, called standard error, which may also be redirected using the
.\" notation 2>\|.
.\" For example
.\" .DS
.\" command some args >out 2>errors
.\" .DE
.\" will redirect standard output to the file `out' but standard error
.\" (and thus all error messages) to `errors'.
.\" The notation 2>&1 sets standard error pointing to the same
.\" place as standard out.
.\" Thus:
.\" .DS
.\" command some args 2>&1 >everything
.\" .DE
.\" will put both standard out and standard error into the file `everything'.
.\" See section 3.7 below for more details.
.SH
1.3\ Pipelines\ and\ filters
.LP
The standard output of one command may be
connected to the standard input of another
by writing
the `pipe' operator,
indicated by \*(VT,
as in,
.DS
	ls \(mil \*(VT wc
.DE
Two commands connected in this way constitute
a \fIpipeline\fP and
the overall effect is the same as
.DS
	ls \(mil >file; wc <file
.DE
except that no \fIfile\fP is used.
Instead the two \fIprocesses\fP are connected
by a pipe (see \fIpipe\fP(2)) and are
run in parallel.
Pipes are unidirectional and
synchronization is achieved by
halting \fIwc\fP when there is
nothing to read and halting \fIls\fP
when the pipe is full.
.LP
A \fIfilter\fP is a command
that reads its standard input,
transforms it in some way,
and prints the result as output.
One such filter, \fIgrep,\fP
selects from its input those lines
that contain some specified string.
For example,
.DS
	ls \*(VT grep old
.DE
prints those lines, if any, of the output
from \fIls\fP that contain
the string \fIold.\fP
Another useful filter is \fIsort\fP.
For example,
.DS
	who \*(VT sort
.DE
will print an alphabetically sorted list
of logged in users.
.LP
A pipeline may consist of more than two commands,
for example,
.DS
	ls \*(VT grep old \*(VT wc \(mil
.DE
prints the number of file names
in the current directory containing
the string \fIold.\fP
.SH
1.4\ Background\ commands
.LP
To execute a command (or pipeline) the shell normally
creates the new \fIprocesses\fP
and waits for them to finish.
A command may be run without waiting
for it to finish.
For example,
.DS
	cc pgm.c &
.DE
calls the C compiler to compile
the file \fIpgm.c\|.\fP
The trailing \fB&\fP is an operator that instructs the shell
not to wait for the command to finish.
To help keep track of such a process
the shell reports its job number (see below) and process
id following its creation.
Such a command is said to be running in the \fIbackground\fP.
By contrast, a command executed without the \fB&\fP is said to be
running in the \fIforeground\fP.\(dg
.FS
\(dg Even after execution, one may move commands from the foreground
to the background, or temporarily suspend their execution (which is
known as \fIstopping\fP a command.
This is described in detail in section 3.10 on \fIJob Control\fB.
.FE
.LP
A list of currently active processes, including ones not associated
with the current shell, may be obtained using the \fIps\fP(1) command.
.SH
1.5\ File\ name\ generation
.LP
Many commands accept arguments
which are file names.
For example,
.DS
	ls \(mil main.c
.DE
prints information relating to the file \fImain.c\fP\|.
.LP
The shell provides a mechanism
for generating a list of file names
that match a pattern.
For example,
.DS
	ls \(mil \*(ST.c
.DE
generates, as arguments to \fIls,\fP
all file names in the current directory that end in \fI.c\|.\fP
The character \*(ST is a pattern that will match any string
including the null string.
In general \fIpatterns\fP are specified
as follows.
.RS
.IP \fB\*(ST\fR 8
Matches any string of characters
including the null string.
.IP \fB?\fR 8
Matches any single character.
.IP \fB[\*(ZZ]\fR 8
Matches any one of the characters
enclosed.
A pair of characters separated by a minus will
match any character lexically between
the pair.
.RE
.LP
For example,
.DS
	[a\(miz]\*(ST
.DE
matches all names in the current directory
beginning with
one of the letters \fIa\fP through \fIz.\fP
.DS
	/usr/fred/test/?
.DE
matches all names in the directory
\fB/usr/fred/test\fP that consist of a single character.
If no file name is found that matches
the pattern then the pattern is passed,
unchanged, as an argument.
.LP
This mechanism is useful both to save typing
and to select names according to some pattern.
It may also be used to find files.
For example,
.DS
	echo /usr/fred/\*(ST/core
.DE
finds and prints the names of all \fIcore\fP files in sub-directories
of \fB/usr/fred\|.\fP
(\fIecho\fP is a standard UNIX command that prints
its arguments, separated by blanks.)
This last feature can be expensive,
requiring a scan of all
sub-directories of \fB/usr/fred\|.\fP
.LP
There is one exception to the general
rules given for patterns.
The character `\fB.\fP'
at the start of a file name must be explicitly
matched.
.DS
	echo \*(ST
.DE
will therefore echo all file names in the current
directory not beginning
with `\fB.\fP'\|.
.DS
	echo \fB.\fP\*(ST
.DE
will echo all those file names that begin with `\fB.\fP'\|.
This avoids inadvertent matching
of the names `\fB.\fP' and `\fB..\fP'
which mean `the current directory'
and `the parent directory'
respectively.
(Notice that \fIls\fP suppresses
information for the files `\fB.\fP' and `\fB..\fP'\|.)
.LP
Finally, the tilde character, `\fB\(ap\fP', may be used to indicate the
home directory of a user.
The `\fB\(ap\fP' at the beginning of a path name followed by a
non-alphabetic character expands to the current user's home
directory.
If the `\fB\(ap\fP' is followed by a login name, it expands to the named
user's home directory.
For example:
.DS
	ls \(ap
	cd \(apegbert/
.DE
will list the contents of the user's home directory and then change
to the home directory of the user ``egbert''.
.SH
1.6\ Quoting
.LP
Characters that have a special meaning
to the shell, such as \fB< > \*(ST ? \*(VT &\|,\fR
are called metacharacters.
A complete list of metacharacters is given
in appendix B.
Any character preceded by a \fB\\\fR is \fIquoted\fP
and loses its special meaning, if any.
The \fB\\\fP is elided so that
.DS
	echo \\?
.DE
will echo a single \fB?\|,\fP
and
.DS
	echo \\\\
.DE
will echo a single \fB\\\|.\fR
To allow long strings to be continued over
more than one line
the sequence \fB\\newline\fP
is ignored.
.LP
\fB\\\fP is convenient for quoting
single characters.
When more than one character needs
quoting the above mechanism is clumsy and
error prone.
A string of characters may be quoted
by enclosing the string between single quotes.
For example,
.DS
	echo xx\'\*(ST\*(ST\*(ST\*(ST\'xx
.DE
will echo
.DS
	xx\*(ST\*(ST\*(ST\*(STxx
.DE
The quoted string may not contain
a single quote
but may contain newlines, which are preserved.
This quoting mechanism is the most
simple and is recommended
for casual use.
.LP
A third quoting mechanism using double quotes
is also available
that prevents interpretation of some but not all
metacharacters.
Discussion of the
details is deferred
to section 3.5\|.
.SH
1.7\ Prompting
.LP
When the shell is used from a terminal it will
issue a prompt before reading a command.
By default this prompt is `\fB$\ \fR'\|.
It may be changed by saying,
for example,
.DS
	\s-1PS1\s0="yesdear$ "
.DE
that sets the prompt to be the string \fIyesdear$\|.\fP
If a newline is typed and further input is needed
then the shell will issue the prompt `\fB>\ \fR'\|.
Sometimes this can be caused by mistyping
a quote mark.
If it is unexpected then entering the interrupt character
(typically \s-1CONTROL-C\s0) 
will return the shell to read another command.
This prompt may be changed by saying, for example,
.DS
	\s-1PS2\s0=more
.DE
Entering the interrupt character may also be used to terminate most
programs running as the current foreground job.
.LP
(\s-1PS1\s0 and \s-1PS2\s0 are \fIshell variables\fP, which will be
described in section 2.4 below.)
.SH
1.8\ The\ shell\ and\ login
.LP
Following \fIlogin\fP(1)
the shell is called to read and execute
commands typed at the terminal.
If the user's login directory
contains the file \fB.profile\fP
then it is assumed to contain commands
and is read by the shell before reading
any commands from the terminal.
.LP
(Most versions of the shell also specify a file that is read and
executed on start-up whether or not the shell is invoked by login.
The \s-1ENV\s0 shell variable, described in section 2.4 below, can be
used to override the name of this file.
See the shell manual page for further information.)
.SH
1.9\ Summary
.sp
.RS
.IP \(bu
\fBls\fP
.br
Print the names of files in the current directory.
.IP \(bu
\fBls >file\fP
.br
Put the output from \fIls\fP into \fIfile.\fP
.IP \(bu
\fBls \*(VT wc \(mil\fR
.br
Print the number of files in the current directory.
.IP \(bu
\fBls \*(VT grep old\fR
.br
Print those file names containing the string \fIold.\fP
.IP \(bu
\fBls \*(VT grep old \*(VT wc \(mil\fR
.br
Print the number of files whose name contains the string \fIold.\fP
.IP \(bu
\fBcc pgm.c &\fR
.br
Run \fIcc\fP in the background.
.RE