.th SH VI 9/15/77
.if t .tr *\(**
.sh NAME
sh \- a shell (command interpreter)
.sh SYNOPSIS
.bd sh
[
.bd \-V
] [
.bd \-v
] [
.bd \-t
] [
.bd \-c
] [
.bd \-i
] [
name
[
arg ...
]
]
.sh DESCRIPTION
.it Sh
is a command interpreter.
It arranges and interprets command lines and the contents of command files.
It is a modification of the standard shell
.it sh
(I),
and almost completely upward compatible therewith.
The intent, in working on a new shell,
is to provide an environment which is more easily tailored to the
wishes of each individual user.
Most new features of this shell,
especially the
.it alias
feature,
are toward this end.
Later versions of this shell may include improvements to the command
language of the shell and allow more easy repetition of commands.
The intent here is to make the command language more resemble a
high-level language \- C being the natural choice for
\s-2UNIX\s0,
and to provide some means of repeating modified commands without retyping,
perhaps akin to the
\s-2INTERLISP\s0
.it redo
feature.
The eventual goal is a C\-shell,
.it csh
(or ``seashell'' if you prefer.)
.s3
.bd "Notes:"
this shell is currently available as
.it "/usr/pascal/sh"
on the Cory and Evans
\s-2UNIX\s0
systems at UC Berkeley.
We discuss the major features of the shell beginning with the objects
of the shell world,
then the lexical structure of the shell input,
the syntactic structure,
details on command execution,
pre-defined variables,
start-up processing,
options,
and finally a list of the built-in commands with a simple description of each.
This documentation is neither fully polished nor devoid of forward references.
.it Sh
was a ``working'' version of the new
.it csh
which became useful when the completion of
.it csh
was delayed.
It is hoped that this documentation will serve as a reference for
.it sh
users who have lived, to this point, by word-of-mouth information.
.s3
.bd "Objects."
The major
.it objects
of the shell world are the
.it variables
and the
.it "argument list"
which consists of specially named and initialized variables.
The variables in the argument list have numeric names, e.g. `1' and `2'.
The other variables have alphabetic names, composed of upper and
lower case letters.
Variable names may be up to 20 characters long.
There is a distinction between a variable existing and not existing,
akin to a variable being on the
.it "a-list"
in
\s-2LISP\s0.
Initially, no variables exist;
in shell terminology, no variables are
.it set.
Variables have string values only;
some numeric operations are defined on variables,
but the representation of variables is always as a string.
Some variables have special meaning to the shell;
thus
.it pid
is the process id of the shell, set to a string with this value
when the shell is created.
These variables have, however, no special status.
They may be manipulated as any other variables are,
with the caveat being that these manipulations may directly affect
the behavior of the shell.
One other point to be noted is that some of the built-in variables
are essentially `toggles';
that is, the shell cares only if they are set or not,
not what their value is.
The standard way to set such a variable is to set it to be the null
string.
.s3
.bd "Lexical structure."
The primary lexical structuring of the input to the shell is the line.
A new-line character is thus normally of syntactic significance, although
it may be escaped with a `\e' as described below.
The most fundamental delimiters for the shell are the blank and the
tab character, generated by a control-i.
There are also a number of characters which have special significance
as they define tokens which are part of the command language of the shell:
`>' and `<' which denote input and output redirection,
`(' and `)' which are used to delimit command lists,
`;' which is used to separate commands for sequential execution,
and `|' and `^' which are completely equivalent ways of specifying a
.it pipe
in a
.it pipeline.
The ways in which these are used in construction of shell commands
will be discussed in the next section.
.s3
At the syntactic level, there is also a
.it "parameter substitution"
facility, which can be used to substitute variables.
Parameter substitution is introduced by the character `$'
and has several different forms, each of which yields zero or more
characters into the input stream replacing it.
We describe each such construct in turn.
.s3
.lp +22 20
$number	Substitutes the number'th argument in the currently
positioned argument list.
The accessing of the argument will be described later.
.s3
.lp +22 20
$*	Substitutes all arguments in the current argument list,
starting at the first `$1';
successive arguments are separated by blanks.
.s3
.lp +22 20
$name
.lp +22 20
${name}	Substitutes the value of the shell variable
.it name.
The second form can be used when this construct is immediately
followed by a letter.
.s3
.lp +22 20
$$	Equivalent to `${pid}'.
.s3
.lp +22 20
${name?str1:str2}	Substitutes
.it str1
if name is set else substitutes
.it str2.
Currently only quoting with `\e' works correctly within
.it str1
and
.it str2.
In particular, `$' constructs and quoting via `\'' and `"' within
these strings is unreliable as it is badly implemented.
.s3
.lp +22 20
${name:default}	Substitutes the value of
.it name
if this variable is set, else substitutes
the string
.it default.
.s3
.lp +22 20
${name?str}	Substitutes the string
.it str
if the variable
.it name
is set, else substitutes nothing.
.i0
.s3
Whenever a paramter is being substituted a slightly different effect
occurs if the `$' is immediately followed by a `.'.
In this case, any substitution from parameters trims suffices from
the parameter.
Thus if `$0' gives `a.out', then `$.0' will give `a',
and if `$prog' would give `foo.p' then `$.prog' would give `foo'.
Also if the `$' character is not followed by any character described
above then that character is returned.
.s3
It is possible to
.it quote
special characters to prevent their special meaning.
Before describing the various ways to do this, we should note that
the characters `[', `*' and `?' have special meaning in command
contexts where they cause
.it "filename expansion,"
a kind of pattern matching of an lexical token against file names.
These characters also often need to be quoted.
The most simple kind of quoting is that with the character `\e',
thus `\e>' is the same as the character `>',
but will not be recognized as a syntactic metacharacter for output
file redirection.
There is a way to quote longer strings using either the delimiter
`\'' or `"'.
Thus the construct:
.dt
.s3
	echo "*** NOTES ***"
.s3
could be used to prevent the spaces and `*'s from having their
special meaning.
It should be noted that no quoting, expansion or substitution of
any kind occurs within `\''s or `"'s, and that the quoting
must terminate before an end of line.
It is also possible in the shell to escape the newline character with
a `\e', this causing the newline to be effectively replaced by a blank.
.s3
.bd "Syntactic structure."
The syntactic structure of the input to
.it sh
is essentially the same as that to
.it sh
(I).
The fundamental component of a command is a
.it pipeline,
which consists of one or more commands separated by the character
`|' or `^', with the separator optionally followed by the character `*',
i.e. `|*' or `^*'.
Each command in the pipeline has its standard output connected to the
standard input of the next.
The forms with the character `*' cause the diagnostic output to go through
the pipe with the standard output.
.s3
More than one pipeline may be given on a single line if they
are separated by the sequential execution separator `;'.
The separator `&' termiates such a list of commands and causes
the entire list to be executed without waiting for termination.
The variable
.it pcs
is set to the process id of the shell co-ordinating the execution
of the command list, and this number is typed on the shells diagnostic output.
When the command terminates,
.it pcs
is
.it unset.
Note that the command
.s3
	date ; echo boo &
.s3
is thus equivalent to
.s3
	(date ; echo boo) &
.s3
rather than like
.s3
	date ; (echo boo&)
.s3
as it is in
.it sh
(I).
.s3
Finally, the basic commands are composed of a command name and
a list of (zero or more) arguments.
There may also be input or output redirection specifiers of the form
`<', `>' or `>>', possibly followed by `*', and then a parameter
specifying a file name.
The `*' here, as in the pipe specifiers above, specifies that diagnostic
output is to be redirected with standard output (and is thus not
allowed with `<'.)
The form `< name' causes the standard input to be taken from the file
.it name,
which is first subjected to
.it "filename expansion"
as described below if it contains any of the characters
`*', `?' or `['.
The form `> name' causes the standard output to be put in the file
.it name
which is created, or truncated to length zero before execution begins
if it exists.
The form `>> name' is like `> name' but output is put at the end of
.it name
if it already exists.
It should be noted that when a pipeline is executed in the background,
the first element of the pipeline will take input from
.it /dev/null
unless the input is otherwise redirected.
.s3
A final syntactic structuring is provided by parentheses `(' and `)'.
A command may be given as a ny of the forms given above thus enclosed
and participate in a pipeline.
Thus,
.s3
	(date; time; echo "***") | lpr
.s3
executes the commands
.it date,
.it time,
and echoes the character string `***' to the line printer daemon
.it lpr.
.s3
.bd "Command execution."
When a command is to be executed,
the shell first examines the command name to see if it is a name
of a built-in command.
If it is not, then the shell will see if the name is actually
an
.it alias
of another name.
If it is, then the process starts over again,
wiht the command name replaced by its
.it alias.
This process of alternately checking for built-in commands and for
aliases will continue up to 100 times to allow multiple aliases.
If this process terminates with the recognition of a built-in command
then that command will be performed.
If not, then the shell will attempt to find the resulting command in the
directories in its search path as defined by the value of the
variable
.it path.
This variable consists of a sequence of directory names separated by
the character `\-'.
The default value for
.it path
is
`\-/bin\-/usr/bin'
where here the initial `\-' signals that the first directory to
be searched is `.', which is the same as the null string.
After this, we are to search the directories `/bin' and `/usr/bin'
for commands.
If the variable
.it path
is not set, then the value `\-' is assumed, causing
only the current directory to be searched.
If the given command name includes the character `/',
then it will be executed if and only if the path includes a null
directory specification, and never from other prefixes in the path.
Thus even if there is a `/bin/bin/date',
`bin/date' will not find it with the default path.
If the command name contains `*', '?' or `[',
then it will undergo
.it "filename expansion"
as described below and will be interpreted only
relative to the current directory or as a full path name.
.s3
There is a general process of
.it "filename expansion"
applied to the arguments to the command.
In this process the characters `*', `?' and `[' have special meaning.
The character `*' will match any sequence of characters in a file name,
the character `?' any single character,
and the construct
`[chars]' will match any of the characters in
.it chars
with the construct
`x\-y'
within chars standing for all characters between and including `x' and `y'.
This process applies to arbitrary path names, and is subject to two
restrictions.
First, each `/' in such a path name must appear explicitly in the
pattern \- `/'s are never matched by `*', `/' or a `[' construct.
Similarly, if the first character of a file name is the character
`.', it must be matched explicitly with a character `.' in the pattern.
If, during command argument expansion, some arguments specify
filename expansion, but none of these arguments matches any file
name, then a diagnostic ``No match'' will be given and the command
will be suppressed.
.s3
A special variant of this filename substitution occurs in input
redirect filenames, command names, and arguments to the built-in
command
.it chdir.
Here the expansion must result in exactly one filename or a diagnostic
will be printed indicating that the given pattern is ``Ambiguous''.
.s3
If the shell finds a file which is executable but is not recognized
by the system as an object file, then it will be examined to see if
it is appropriate to be used as a shell script or by one of the
interpreters the shell knows about.
If the first word of the file contains the magic number of one of
the interpreters, e.g. 0404 octal for the Pascal interpreter
.it px
(VI),
then this interpreter will be forked with the arguments shifted
to the right, the name of the file becoming the first argument.
If the first word of the file does not indicate any of the interpreters,
yet contains
\s-2ASCII\s0
characters then a shell will be invoked as an interpreter.
The path name for this shell may be specified using the
.it shell
variable.
.s3
When a command terminates, if it terminates abnormally, a message
will be printed indicating the cause of abnormal termination.
If the command was not the one being waited for, i.e. if a background
process started with `&' terminates abnormally,
its process number will also be given.
Finally, a time statistics line may be printed at command termination.
This is described with the
.it time
variable below.
.s3
.bd "Predefined and special variables."
The following variables have special meaning to the shell and
affect its behavior or are set as side effects of various commands.
.s3
.lp +15 12
home	Set to the users home directory as given in the
.it htmp
data base.
Usually the directory where the user logs in, this is the default
destination for a
.it chdir
command.
.s3
.lp +15 12
nargs	Maintained as the number of arguments in the current argument
list.
.s3
.lp +15 12
nice	If given a numeric value, each executed command will be
.it niced
to this priority immediately before execution.
.s3
.lp +15 12
path	Specifies the search path for command executions as described
above.
.s3
.lp +15 12
pcs	The process number of the last command started with `&'.
Unset when this command completes.
.s3
.lp +15 12
pid	The process number of the shell; used in `$$'.
.s3
.lp +15 12
prompt	The prompt which preceded each command line interactively.
If the shell is not interactive, then this variable is not set.
.s3
.lp +15 12
shell	The shell which is the default interpreter for executable
files not recognized by the system.
Defaults to `/usr/pascal/sh', the current home of
.it sh.
.s3
.lp +15 12
time	When set, causes a command statistic line to be given following
each executed command.
This line includes the number of user cpu seconds, system cpu seconds,
real time in hours minutes and seconds, and
the machine utilization over this period expressed as a percentage.
If given a numeric value,
statistics will be given only for commands requiring more than
this many total cpu seconds.
.i0
.s3
.bd "Start up processing."
When a new shell is created it first sets the
.it home
variable from the
.it htmp
database,
initializes the
.it prompt,
.it shell,
and
.it pid
variables and sets up any default aliases and interpreters.
(Current default \fIalias\fR is ``time'' for ``tyme'',
interpreter is ``/bin/px'' on value 0404.)
The shell then process the command line arguments as follows:
.s3
.lp +7 5
\fB\-V\fR	Causes the shell to be
.it verbose
like \fB\-v\fR, but even when processing
the startup files, e.g.
.it \&.profile.
.s3
.lp +7 5
\fB\-v\fR	Causes the shell to be verbose; command input
is echoed to the output with indication of the arguments which
were substituted for parameters with the `$' mechanisms;
such substitutions are bracketed with `[' and `]' for visibility.
.s3
.lp +7 5
\fB\-c\fR	Causes the shell to take as input the contents
of the immediately following string.
.s3
.lp +7 5
\fB\-t\fR	Causes the shell to read exactly one line of
input from its standard input.
.s3
.lp +7 5
\fB\-i\fR	Causes the shell to be interactive:
the remaining arguments are \fInot\fR interpreted as a file to
be executed and parameters,
and the shell ignores interrupts and quits and prompts
for input.
Shells which have standard input and output teletypes
also are interactive in the sense that they ignore interrupts and quits.
.i0
.s3
If either the
.bd \-c
or
.bd \-t
flag is given, then the shell does not prompt, i.e.
.it prompt
is unset.
If none of the
\fB\-c\fR,
\fB\-i\fR,
or
\fB\-t\fR
flags are given,
then the first argument
argument is taken to be the name of a file containing commands to be executed.
This argument becomes available as the 0'th parameter during
interpretation, i.e. `$0'.
Its value is immune to
.it shift
and
.it rewind
operations.
The remaining arguments become the positional parameters,
`$1', `$2', etc.
The number of such positional parameters will be given by the variable
.it nargs.
These parameters may be manipulated by
.it rewind
and
.it shift
and given new values by
.it set.
.s3
After setting up all of this, the shell will read commands from
the file
.it \&.profile
in the user's home directory.
This file is typically used to set aliases and variables
that the user wishes and also to change the value of
.it path.
If the shell is a login shell,
defined as having been invoked with a name which started with `\-',
the shell will then read commands from the file `.login' in the same directory.
Shells normally terminate when they receive an end-of-file from their
standard input;
login shells will print ``logout'' when this occurs and execute the commands
from the file `.logout' in the home directory.
The home directory for the purpose of finding `.logout' is independent
of the current value of the variable
.it home.
.s3
.bd "Built-in commands."
The following commands are built into the shell.
Input and output redirections have no effect on these commands,
and are not allowed.
Note also that since the command
.it if
(I)
is not done within the shell, it cannot, in general,
be used to qualify a built-in command.
In general, therefore, the shell control structure must be used like
\s-2FORTRAN\-II\s0
with only
.it goto
(I)
commands on
.it if
(I)
commands.
.s3
.lp +12 10
abort	Terminate abnormally.
Useful only for shell debugging or fits of frenzy.
.s3
.lp +12 10
alias	Specify an alias for a command.
When given two arguments the first argument is given alias the second
argument.
When given one argument the alias for that argument will be given.
When given no arguments all aliases are given.
.s3
.lp +12 10
chdir	Change directory.
If no argument is given change to the directory in the variable
.it home.
The argument may contain the metacharacters `*', `?' and `['
which are interpreted as for executed commands.
This is the only built-in function which takes such arguments.
.s3
.lp +12 10
interp	Specify interpreters.
Same as
.it alias
except that the first argument is the value of the first word of
a file for this interpreter, i.e. its magic number,
and the second is the name of the interpreter.
.s3
.lp +12 10
logout	Same as a control-d.
.s3
.lp +12 10
noquit	Causes the shell to ignore \s-2QUIT\s0 signals.
This is the default.
.s3
.lp +12 10
quit	Causes the shell to not ignore \s-2QUIT\s0 signals
for the purposes of debugging.
.s3
.lp +12 10
rewind	Causes the shell to reset the argument list to the state
at entry, reversing the effect of all
.it shifts.
.s3
.lp +12 10
set	Give one or more variables or parameters new values.
With no arguments types the names and values of all variables.
The simples kind of set is to set a variable `on', i.e. to
the null string.
To do this you can just mention its name, i.e.
.s3
	set time
.s3
It is also possible to give variables string values by specifying
the value after an `=', thus
.s3
	set time=  prompt="+ "
.s3
sets
.it time
in the same was as the previous example, and also changes
the
.it prompt.
Finally, it is possible to do arithmetic in the
.it set
command.
Operators available are `+=', `\-=', `*=', `/=', `|=',
`&=', `%=', `=', `++' and `\-\-'.
Thus
.s3
	set i++ j*=$i
.s3
increments the value of variable
.it i
and then multiples the value of the variable
.it j
by the value of the variable
.it i.
Note that the operators `|' and `&' must be quoted, i.e.:
.s3
	set i\e|=1
.s3
to make the value of
.it i
be odd.
One final operator is `@' which is equivalent to an
.it unset.
All of these operators except `@' may be applied to parameters, e.g.:
.s3
	set 0=a.out 1=$.1
.s3
.lp +12 10
shift	Causes the argument list to be right shifted, argument 2
becoming argument 1, etc.
May be given a count, possibly negative, for multiple right or
left shifts, i.e. `shift \-1' for a left shift.
.s3
.lp +12 10
tyme	An internal version of \fItime\fR corresponding to ``set time''
for the course of the command.
Does not work correctly for `&' processes.
Note that \fItime\fR is aliased to
.it tyme
by default.
.s3
.lp +12 10
unalias	Given a parameter, removes that alias from the list of aliases.
.s3
.lp +12 10
uninterp	Like unalias for interpreters, takes the magic number and
removes the corresponding entry.
.s3
.lp +12 10
unset	Removes the specified variables.
.s3
.lp +12 10
wait	Wait for all processes to terminate,
or for the specified process to terminate.
.it Wait
may be aborted with an
\s-2INTERRUPT\s0.
.s3
.lp +12 10
:	Label marker for
.it goto
targets.
.i0
.sh FILES
.dt
/etc/htmp		home directory data base
.br
/etc/passwd		home directory data when not in \fIhtmp\fR
.br
\&.login			start-up for login shells
.br
\&.logout			prologue for login shells
.br
\&.profile			beginning script for all shells
.br
/dev/null		source of end-of-file
.sh SEE\ ALSO
sh (I), chdir (I), chdir (II), if (I), goto (I)
.sh AUTHOR
William N. Joy
.sh BUGS
As this is an experimental shell, there are probably several.
Mostly, the design has a lot of rough edges and the new features
don't always ``like'' each other.
Some of them can't be successfully mixed.