NAME

sh - shell (command line interpreter)


SYNOPSIS

sh
[-vnx] [name [arg1 ..[arg9]]].


DESCRIPTION

Sh
is a command line interpreter:
it reads lines typed by the user and interprets them as requests to
execute other programs.



Commands.

In simplest form, a command line consists of the command name followed
by arguments to the command, all separated by spaces:

command arg1 arg2 ... argn
The shell splits up the command name and the arguments into separate
strings.
Then a file with name
command
is sought;
command
may be a path name to specify any file in the system.
If
command
is found, it is brought into memory and executed.
The arguments collected by the shell are accessible to the command.
When the command is finished, the shell resumes its own execution and
indicates its readiness to accept another command by typing a
prompt character.

If file
command
cannot be found in the current directory or through its pathname, the
shell searches a specific system directory of commands intended
to be available to sh users in general.

An example of a simple command is:

sort list
which would look for the tool 'sort' in the current directory,
then in the system directory, and
then sort the contents of file 'list', printing the
output at the user's terminal.

Some characters on the command line have special meanings to the
shell (these are discussed below).
The character '@' may be included anywhere in the command line
to cause the following character to lose any special meaning
it may have to the shell (to be 'escaped').
Sequences of characters enclosed in double (") or single (')
quotes are also taken literally.



Standard I/O

Shell programs in general have open three standard files:
'input', 'output', and 'error output'.
All three are assigned to the user's terminal unless redirected by
the special arguments '<', '>', '?', '>>', '??', (and sometimes
'-').

An argument of the form '<name' causes the file
'name' to be used as the standard input file of the associated
command.

An argument of the form '>name' causes file 'name' to be used
as the standard output.

An argument of the form '?name' causes the file 'name' to be used
as the standard error output.

Arguments of the form '>>name' or '??name' cause program output
to be appended to 'name' for standard output or error output
respectively.
If 'name' does not exist, it will be created.

Most tools have the capability to read their input from a series
of files.
In this case, the list of files overrides reading from standard
input.
However, many of the tools allow the user to read from both a list
of files and from input by specifying the filename '-' for
standard input.
For example,

roff file1 - file2
would read its input from 'file1', then from the standard input,
then from 'file2'.



Filters and Pipes.

The output from one command may be directed to the input of another.
A sequence of commands separated by vertical bars (|) or carets ('^')
causes the shell to arrange that the standard output of each command
be delivered to the standard input of the next command in sequence.
Thus in the command line:

sort list | uniq | crt
'sort' sorts the contents of file 'list';
its output is passed to 'uniq',
which strips out duplicate lines.
The output from 'uniq' is then input to 'crt', which prepares
the lines for viewing on the user's crt terminal.

The vertical bar is called a 'pipe'.
Programs such as 'sort', 'uniq', and 'crt', which copy standard
input to standard output (making some changes along the way) are called
'filters'.



Command separators

Commands need not be on different lines; instead they may be
separated by semicolons:

ar t file; ed
The above command will first list the contents of the archived
file 'file', then
enter the editor.

The shell also allows commands to be grouped together with
parentheses, where the group can then be used as a filter.
For example,

(date; cat chocolate) | comm vanilla
writes first the date and then the file 'chocolate' to standard
output, which is then read as input by 'comm'.
This tool compares the results with existing file 'vanilla' to
see which lines the two files have in common.



Multitasking

On many systems the shell also allows processes to be executed
in the background.
If a command is followed by '&', the shell will not wait for the
command to finish before prompting again; instead,
it is ready immediately to accept a new command.
For instance,

ratfor ambrose >george &
preprocesses the file 'ambrose', putting the output on 'george'.
No matter how long the compilation takes,
the shell returns immediately.
The identification number of the process running that command is
printed.
This identification may be used to wait for the completion of
the command or to terminate it.

The '&' may be used several times in a line.
Parentheses and pipes are also allowed (within the same background
process).



Script files.

The shell itself is a command, and may be called recursively,
either implicitly or explicitly.
This is primarily useful for executing files containing lines
of shell commands.
For instance, suppose you had a file named 'nbrcount'
which looked like this:


echo 'Counting strings of digits'
tr <program 0-9 9 | tr !9 | wc -c


These commands count all the digit strings in 'program'.
You could have the shell execute the commands by typing:

sh nbrcount
The shell will also execute script files implicitly.
For example, giving the command

nbrcount
would cause the shell to notice that the file 'nbrcount' contained
text rather than executable code.
The shell would then execute itself again, using 'nbrcount' as
its input.

Arguments may also be passed to script files.
In script files, character sequences of the form '$n',
where n is a digit between 1 and 9, are replaced by the
nth argument to the invocation of the shell.
For instance, suppose the file 'private' contained the following
commands:


cat $1 $2 $3 | crypt key >$4
ar u loveletters $4


Then, executing the command

private Dan John Harold fair
would merge the files 'Dan', 'John', and 'Harold', encrypt
them, and store them away in an archive under the name 'fair'.

Script files may be used as filters in pipelines just like regular
commands.

Script files sometimes require in-line data to be available to them.
A specj) != NEWLINE; k = k + 1) {
         file(k) = lin(j)
         j = j + 1
         }
      file(k) = EOS
      if (k > 1)
 e standard
input.
However, within a shell procedure commands could be embedded this way:

                           ed file <<!
                           editing requests
                           !

The lines between <<! and ! are called a 'here' document; they are read
by the shell and made available as the standard input.
The character '!' is arbitrary, the document being terminated by a line
that consists of whatever character followed the <<.




Shell Flags.

The shell accepts several special arguments when it is invoked.
The argument -v asks the shell to print each line of a script
file as it is read as input.
For instance,

sh -v private Jasmine Irma Jennifer twostars
would print each line of the script file 'private' as soon as
it is read by the shell.

The argument -x is similar to the -v above except that commands
are printed right before they are executed.
These commands will be printed in the actual format the
system expects when attempting to execute the program.

The argument -n suppresses execution of the command entirely.

The argument -c causes the remaining arguments to be executed
as a shell command.



Termination.

The shell may be left by typing an end-of-file or by typing
'logout' as a command.




FILES

Scratch files for pipelines are created with the names "Pn"
where n is the number of the pipe on the command line
(e.g. 1, 2, etc.).
Scratch files named "doc" are created for 'here documents'.


SEE ALSO

The Unix command 'sh'

The Bell system Technical Journal, vol. 57, no. 6, part 2,
July-Aug 1978



DIAGNOSTICS



cannot locate shell

Issued whenever the shell is attempting to spawn a copy of itself to
process a script file.
The shell was unable to find the correct file.
(The file is set in a string declaration in the "scrf" routine.)


cannot spawn background process

Spawn returned an error status when attempting to execute a command
in the background.
Possibly system quotas were overflowed.


cannot spawn process

The requested task could not be executed by "spawn".
Generally indicates some sort of system problem.


can't open 'here document'

The shell creates a temporary file for each 'here document'
and this file could not be created for some reason.
Perhaps the maximum number of opened files has been exceeded
or the user does not have the appropriate privileges for
creating files.


can't open teletype channel

The shell was attempting to open an output channel to the user's
teletype for prompting and was unable to do so.


dopar -- invalid token following parenthesis

Syntax error on the command line.


empty command

Parentheses, pipes, or other shell characters showed up without
any commands between them.


invalid shell command

An unlikely error which means part of the code thought it had
found a shell command, but another part thought it hadn't.


invalid task

Printed whenever a command could not be located
i      getnum = ptscan(BACKWARD, pnum)
      }
   else
      getnum = EOF
   if (getnum == OK)
      i = i + 1   # point at  is determined by the TREESIZE definition in the source code.


stack size exceeded

The size of a stack of pointers into the parse tree was exceeded.
The size of the stack is determined by the MAXSTACK definition
in the source code.


syntax error

There was some sort of error in the syntax of the command line.
Sometimes a suggested reason is printed.


unbalanced quotes

There weren't matching pairs of single and/or double quotes


unbalanced right parenthesis


unbalanced left parenthesis

Unmatched parentheses


too many characters pushed back

There were some horrible problems in attempting to read
the input line and put characters back onto a stack for
re-reading.
The size of the stack is determined by the BUFSIZE definition
in the source code.



execut -- invalid parse tree
mktree -- too many children
setree -- doubly defined argument


These are primarily debugging aids for the parser.
Contact a systems programmer if they show up...



AUTHORS


Dennis Hall, Debbie Scherrer, Joe Sventek
(Lawrence Berkeley Laboratory)


BUGS/DEFICIENCIES

If a user wants to escape a shell special character that appears
as the first character of an argument, he must escape it with
quotes rather than an '@' sign.