.if \nv .rm CM
.de IR
\fI\\$1\^\fR\\$2
..
.de RI
\fR\\$1\fI\\$2\^\fR\\$3
..
.TL
INTRODUCTION TO VOLUME 1
.pn 4
.af PN i
.AU
Berkeley 2.9BSD Version
.LP
This volume gives descriptions of the publicly available
features of the
.UX
system.
It does not attempt to provide perspective or tutorial
information upon the
.UX
operating system,
its facilities, or its implementation.
Various documents on those topics are contained in
Volume 2.
In particular,
for an overview see `The
.UX
Time-Sharing System'
by Ritchie and Thompson; for a tutorial see
`\s8UNIX\s10 for Beginners' by Kernighan.
.LP
Within the area it surveys, this volume attempts
to be timely, complete and concise.
Where the latter two objectives conflict,
the obvious is often left unsaid in favor of brevity.
It is intended that each program be described
as it is, not as it should be.
Inevitably, this means that
various sections will soon be out of date.
.LP
The volume is divided into
eight sections:
.DS
1.	Commands
2.	System calls
3.	Subroutines
4.	Special files
5.	File formats and conventions
6.	Games
7.	Macro packages and language conventions
8.	Maintenance
.DE
Commands are programs intended to be invoked directly by
the user, in contradistinction to subroutines, which are
intended to be called by the user's programs.
Commands generally reside in directory
.I /bin
(for
.IR bin \|ary
programs).
Some programs also reside in
.I
/\|usr/\|bin,
.R
to save space in
.I  /bin.
Programs that originated at Berkeley are generally found
.IR /\|usr/\|ucb .
These directories are searched automatically by the command interpreter.
.LP
System calls are entries into the
.UX
supervisor.
Every system call has one or more C language interfaces
described in section 2.
The underlying assembly language interface, coded with opcode
.I sys,
a synonym for
.I trap,
is given as well.
.LP
An assortment
of subroutines is available;
they are described in section 3.
The primary libraries in which they are kept are described in
.IR intro (3).
The functions are described in terms of C, but most will
work with Fortran as well.
.LP
The special files section 4 discusses the characteristics of
each system `file' that actually refers to an I/O device.
The names in this
section refer to the DEC device names for the
hardware,
instead of the names of
the special files themselves.
.LP
The file formats and conventions section 5 documents the structure of particular
kinds of files; for example, the form of the output of the loader and
assembler is given.  Excluded are files used by only one command,
for example the assembler's intermediate files.
.LP
Games have been relegated to section 6 to keep them from contaminating
the more staid information of section 1.
.LP
Section 7 is a miscellaneous collection of information necessary to
writing in various specialized languages:
character codes, 
macro packages for typesetting,
etc.
.LP
The maintenance 
section 8 discusses procedures not intended
for use by the ordinary user.
It also includes programs that are used in monitoring system performance
or in accounting.
.LP
Each section consists of a number of independent
entries of a page or so each.
The name of the entry is in the upper corners of its pages,
together with the section number, and sometimes a
letter characteristic of a subcategory, e.g. graphics is 1G,
and the math library is 3M.
Entries within each section are
alphabetized.
The page numbers of each entry start at 1;
it is infeasible to number consecutively the pages of 
a document like this that is republished in many variant forms.
.LP
All entries are based on a common format,
not all of whose subsections will always appear.
.RS
.LP
The
.I name
subsection lists the exact names of the commands and subroutines
covered under the entry and gives
a very short description of their purpose.
.LP
The
.IR synopsis ""
summarizes the use of the
program being described.
A few conventions are used, particularly in the
Commands subsection:
.LP
.RS
.B Boldface
words are considered literals, and
are typed just as they appear.
.LP
Square brackets [ ] around an argument
indicate that the argument is optional.
When an argument is given as `name', it always
refers to a file name.
.LP
Ellipses `.\|.\|.' are used to show that the previous argument-prototype
may be repeated.
.LP
A final convention is used by the commands themselves.
An argument beginning with a minus sign `\-'
is often taken to mean some sort of option-specifying argument
even if it appears in a position where a file name
could appear.  Therefore, it is unwise to have files
whose names begin with `\-'.
.LP
.RE
The
.IR description ""
subsection discusses in detail the subject at hand.
.LP
The
.IR files ""
subsection gives the names of files which are
built into the program.
.LP
A
.I
see also
.R
subsection gives pointers to related information.
.LP
A
.I  diagnostics
subsection discusses
the diagnostic indications which may be produced.
Messages which are intended to be self-explanatory
are not listed.
.LP
The
.IR bugs ""
subsection gives
known bugs and sometimes deficiencies.
Occasionally also the suggested fix is
described.
.LP
In section 2 an
.I assembler
subsection carries the assembly language system interface.
.LP
.RE
At the beginning of the volume is a table of contents,
organized by section and alphabetically within each section.
There is also a permuted index derived from the table of contents.
Within each index entry, the title
of the writeup to which
it refers is followed by the appropriate section number in parentheses.
This fact is important because there is considerable
name duplication among the sections,
arising principally from commands which
exist only to exercise a particular system call.
.SH
HOW TO GET STARTED
.LP
This section sketches the basic information
you need to get started on \s-2UNIX\s0:
how to log in and log out,
how to communicate through your terminal,
and how to run a program.
See `\c
.UX
for Beginners'
in Volume 2 for a more complete introduction
to the system.
These procedures necessarily vary from system to system.
.LP
.I
Logging in.\ \ 
.R
You must call
.UX
from an appropriate terminal.
.UX
terminals are typified by the TTY 43,
the GE Terminet 300, the DASI 300S and 450, and most
video terminals such as
the Datamedia 5120 or HP 2640.
You must also have a valid user name,
which may be obtained, together with the telephone number, from the system administrators.
The same telephone number
generally serves terminals operating at all the standard speeds.
After a data connection is established,
the login procedure depends on what kind of terminal
you are using.
.I
.I
.R
.R
.LP
.I
300-baud terminals:\ \ 
.R
Such terminals include the GE Terminet 300 and most display terminals
run with popular modems.
These terminals generally have a speed
switch which should be set at `300' (or `30' for
30 characters per second)
and a half/full duplex switch which should be set at
full-duplex.
(This switch will often have to be changed
since many other systems require half-duplex).
When a connection is established, the system
types `login:'; you type your
user name, followed by the `return' key.
If you have a password, the system asks for it
and turns off the printer on the terminal
so the password will not appear.
After you have logged in,
the `return', `new line', or `linefeed' keys
will give exactly the same results.
.LP
.I
1200- and 150-baud terminals:\ \ 
.R
If there is a half/full duplex switch, set it at full-duplex.
When you have established a data connection,
the system may type out a few garbage characters
(the `login:' message at the wrong speed).
Depress the `break' (or `interrupt')
key; this is a speed-independent signal
to
.UX
that a different speed terminal
is in use.
The system then will type `login:,' this time at another
speed.
Continue depressing the break key
until `login:' appears in clear, then
respond with your user name.
From the TTY 37 terminal, and any other which has the `newline'
function (combined carriage return and linefeed), terminate each line you type with the
`new line' key,
otherwise use the `return' key.
.LP
.I
Hard-wired terminals.\ \ 
.R
Hard-wired terminals usually begin at the right
speed, up to 9600 baud; otherwise the preceding instructions
apply.
.LP
For all these terminals, it is important
that you type your name in lower-case if possible; if you type
upper-case letters,
.UX
will assume that your terminal cannot generate lower-case
letters and will translate all subsequent upper-case
letters to lower case.
.LP
The evidence that you have successfully
logged in is that the shell program
will type a `%' or `$' to you.
(The Shell is described below under
`How to run a program.')
.LP
For more information, consult
.IR tset (1)
or
.IR stty (1),
which tell how to adjust terminal behavior,
.IR getty (8),
which discusses the login sequence in more
detail, and
.IR tty(4),
which discusses terminal I/O.
.LP
.I
Logging out.\ \ 
.R
There are three ways to log out:
.IP
You can simply hang up the phone (if on a dialup line).
.IP
You can log out by typing an end-of-file indication
(EOT character, control-d) to the Shell.
The Shell will terminate and the `login: ' message
will appear again.
.IP
You can also log in directly as another user
by giving a
.IR login (1)
command.
.LP
.I
How to communicate through your terminal.\ \ 
.R
When you type characters, a gnome deep in the system
gathers your characters and saves them in a secret
place.
The
characters will not be given to a program
until you type a return (or newline), as described above
in
.I
Logging in.
.R
.LP
.UX
terminal I/O is full-duplex.
It has full read-ahead, which means that you can
type at any time,
even while a program is
typing at you.
Of course, if you type during output, the printed output will
have the input characters interspersed.
However, whatever you type will be saved
up and interpreted in correct sequence.
There is a limit to the amount of read-ahead,
but it is generous and not likely to be exceeded unless
the system is in trouble.
When the read-ahead limit is exceeded, the system
throws away all the saved characters,
or refuses input and beeps.
.LP
The character `@' in typed input
kills all the preceding characters in the line, so
typing mistakes
can be repaired on a single line.
Also, the character `#' erases the last character typed
(this is commonly changed to control-H or backspace).
Successive uses of `#' erase characters back to, but
not beyond, the beginning of the line.
`@' and `#' can be transmitted to a program
by preceding them with `\\'.
(So, to erase `\\', you need two `#'s).
These conventions can be changed by the
.IR tset (1)
command.
.LP
The `break' or `interrupt' key causes an
.I
interrupt signal,
.R
as does the
\s8ASCII\s0 `delete' (or `rubout') character,
which is not passed to programs.
This signal
generally causes whatever program
you are running to terminate.
It is typically used to stop a long printout that
you don't want.
However, programs can arrange either to ignore
this signal altogether,
or to be notified when it happens (instead
of being terminated).
The editor, for example, catches interrupts and
stops what it is doing,
instead of terminating, so that an interrupt can
be used to halt an editor printout without
losing the file being edited.
.LP
The
.IR quit ""
signal is generated
by typing the \s8ASCII\s10 FS character.
(FS appears many places on different terminals, most commonly
as control-\e or control-\^|\^.)
It not only causes a running program to terminate
but also generates a file with the core image
of the terminated process.
Quit is useful
for debugging.
.LP
Besides adapting to the speed of the terminal,
.UX
tries to be intelligent about whether
you have a terminal with the newline function
or whether it must be simulated with carriage-return
and line-feed.
In the latter case, all input carriage returns
are turned to newline characters (the standard
line delimiter)
and both a carriage return and a line feed
are echoed to the terminal.
If you get into the wrong mode, the
.IR reset (1)
or
.IR stty (1)
commands will rescue you.
.LP
Tab characters are used freely in
.UX
source programs.
If your terminal does not have the tab function,
you can arrange to have them turned into spaces
during output, and echoed as spaces
during input.
The system assumes
that tabs are set every eight columns.
Again, the
.IR tset (1)
command will set or reset this mode.
The command
.IR tabs (1)
will also set the tab stops automatically on many terminals.
.LP
.I
How to run a program; the shell.\ \ 
.R
When you have successfully logged in, a program
called the shell is listening to your terminal.
There are two shell programs in common use:
the standard Version 7 shell,
.IR sh (1),
and the Berkeley C shell,
.IR csh (1).
The shell reads typed-in lines, splits them up
into a command name and arguments, and executes the command.
A command is simply an executable program.
The shell looks first in your current directory
(see below)
for a program with the given name,
and if none is there, then in a system directory.
There is nothing special about system-provided
commands except that they are kept in a directory
where the shell can find them.
.LP
The command name is always the first word on an input line;
it and its arguments are separated from one another by
spaces.
.LP
When a program terminates, the Shell will ordinarily regain control and type 
a prompt (`%' or `$') at you to indicate that it is ready for another command.
.LP
Both shells have many other capabilities,
which are described in detail in the manual sections
.IR csh (1)
and
.IR sh (1).
.LP
.I
The current directory.\ \ 
.R
.UX
has a file system arranged in a hierarchy of directories.
When the system administrator gave you a user name,
he also created a directory for you (ordinarily
with the same name as your user name).
When you log in, any file
name you type is by default
in this directory.
Since you are the owner of this directory, you have
full permission to read, write, alter, or destroy
its contents.
Permissions to have your will with other directories
and files will have been granted or denied to you
by their owners.
As a matter of observed fact, few
.UX
users
protect their files from destruction,
let alone perusal, by other users.
.LP
To change the
current directory (but not the set of permissions you
were endowed with at login) use
.IR cd (1).
.LP
.I
Path names.\ \ 
.R
To refer to files not in the current directory, you must
use a path name.
Full path names begin with `/', the name of the root directory of the
whole file system.
After the slash comes the name of each directory containing the next
sub-directory (followed by a `/') until finally the
file name is reached.
For example,
.I
/\^usr/\^lem/\^filex
.R
refers to the file
.I
filex
.R
in the directory
.I
lem; lem
.R
is itself a subdirectory of
.I
usr; usr
.R
springs directly from the root directory.
.LP
If your current directory has subdirectories,
the path names of files therein begin with
the name of the subdirectory with no prefixed `/'.
.LP
A path name may be used anywhere a file name is
required.
.LP
Important commands which modify the contents of files
are
.IR cp (1),
.IR mv (1),
and
.IR rm (1),
which respectively copy, move (i.e. rename) and remove files.
To find out the status of files or directories, use 
.IR ls (1).
See
.IR mkdir (1)
for making directories and
.I
rmdir
.R
(in
.IR rm (1))
for destroying them.
.LP
For a fuller discussion of the file system, see
`The
.UX
Time-Sharing System,'
by Ken Thompson and Dennis Ritchie.
It may also be useful to glance through
section 2 of this manual, which discusses
system calls, even if you don't intend
to deal with the system at that level.
.LP
.I
Writing a program.\ \ 
.R
To enter the text of a source program into a
.UX
file, use
an editor (\c
.IR ex / vi (1)
or
.IR ed (1)).
The three principal languages in
.UX
are
provided by the C compiler
.IR cc (1),
the Fortran compiler
.IR f77 (1),
and the assembler
.IR as (1).
After the program text has been entered through 
the editor
and written on a file, you can give the file
to the appropriate language processor as an argument.
The output of the language processor
will be left on a file in the current directory named `a.out'.
(If the output is precious, use
.I mv
to move it to a less
exposed name soon.)\ 
If you wrote in assembly language, you will probably
need to load the program with library subroutines; see
.IR ld (1).
The other two language processors call
the loader automatically.
.LP
When you have finally gone through this entire process
without provoking any diagnostics, the resulting program
can be run by giving its name to the shell
in response to the prompt.
.LP
Your programs can receive arguments from the command line
just as system programs do,
see
.IR exec (2).
.LP
.I
Text processing.\ \ 
.R
Almost all text is entered through the editor
.IR ex (1),
its full-screen version \fIvi\fP,
or the original
.UX
editor,
.IR ed (1).
The commands most often used to write text on a terminal are:
.I
cat, more, pr, roff
.R
and
.I nroff,
all in section 1.
.LP
The
.I cat
command simply dumps \s8ASCII\s10 text
on the terminal, with no processing at all.
.I More
is used to print text a screenful at a time.
The
.IR pr ""
command paginates the text, supplies headings,
and has a facility for multi-column output.
.I
Nroff
.R
is an elaborate text formatting program.
Used naked, it requires careful forethought, but for
ordinary documents it has been tamed;
see
.IR ms (7)
and
.IR me (7).
.I Roff
is a simpler text formatting
program, and requires somewhat less forethought.
.I
.LP
.I Troff
prepares documents for a
Graphics Systems phototypesetter;
it is very similar to 
.I nroff,
and often works from exactly the same
source text.
It was used to produce this manual.
.LP
.I
Status inquiries.\ \ 
.R
Various commands exist to provide you with useful
information.
.IR Who (1)
prints a list of users presently logged in;
.IR w (1)
supplies a little more information about each user.
.IR Date (1)
prints the current time and date.
.IR Ls (1)
will list the files in your directory or give
summary information about particular files.
.LP
.I
Surprises.\ \ 
.R
Certain commands provide inter-user communication.
Even if you do not plan to use them, it would be
well to learn something about them, because someone else may
aim them at you.
.LP
To communicate with another user currently logged in,
.IR write (1)
is used;
.IR Mail (1)
will leave a message whose presence will be announced
to another user when he next logs in.
The write-ups in the manual also suggest how to respond to
the two commands if you are a target.
.LP
When you log in, a message-of-the-day may greet you
before the first prompt.
.SH
CONVERTING FROM THE 6TH EDITION
.LP
There follows a catalogue of significant, mostly incompatible,
changes that will affect old users converting to the 7th edition.
No attempt is made to list all new facilities, or even all
minor, but easily spotted changes,
just the bare essentials without which it will be
almost impossible to do anything.
.LP
.I
Addressing files.\ \ 
.R
Byte addresses in files are now long (32-bit) integers.
Accordingly
.I seek
has been replaced by
.IR lseek (2).
Every program that contains a 
.I seek
must be modified.
.I Stat
and
.IR fstat (2)
have been affected similarly, since file lengths are now
32- rather than 24-bit quantities.
.LP
.I
Assembly language.\ \ 
.R
System entry points are no longer built in symbols.
Their values must be obtained from
.I /usr/include/sys.s,
see
.IR intro (2).
All system calls modify r0.
This means that sequences like
.DS
mov	file,r0
sys	lseek,0,0,2
sys	write,buf,n
.DE
will no longer work.
(In fact, 
.I lseek
now modifies r1 as well, so be doubly cautious.)
.LP
The
.IR sleep (2)
entry point is gone; see the more general facility,
.IR alarm,
plus
.I pause.
.LP
Few library functions have assembly language entry points any more.
You will have to simulate the C calling sequence.
.LP
.I
Stty and gtty.\ \ 
.R
These system calls have been extensively altered,
see
.IR ioctl (2)
and
.IR tty (4).
.LP
.I
Archive files.\ \ 
.R
The format of files produced by
.IR ar (1)
has been altered.
To convert to the new style, use
.IR arcv (1).
.LP
.I 
C language, lint.\ \ 
.R
The official syntax for initialization
requires an equal sign = before an initializer,
and brackets { } around compound initial values;
arrays and structures are now initialized honestly.
Two-address operators, such as =+ and =-, are now written
+= and -= to avoid ambiguities, although the old
style is still accepted.
You will also certainly want to learn about
.DS
long integers
type definitions
casts (for type conversion)
unions (for more honest storage sharing)
#include <filename> (which searches in standard places)
.DE
.LP
The program
.IR lint (1)
checks for obsolete syntax and
does strong type checking of C programs, singly
or in groups that are expected to be loaded together.
It is indispensable for conversion work.
.LP
.I Fortran.\ \ 
The old 
.I fc
is replaced by
.I f77,
a true compiler for Fortran 77,
compatible with C.
There are substantial changes in the language;
see `A Portable Fortran 77 Compiler' in Volume 2.
.LP
.I
Stream editor.\ \ 
.R
The program
.IR sed (1)
is adapted to massive, repetitive
editing jobs of the sort encountered in converting to
the new system.
It is well worth learning.
.LP
.I
Standard I/O.\ \ 
.R
The old 
.I
fopen, getc, putc
.R
complex and the old
.I \-lp
package are both dead,
and even
.I getchar
has changed.
All have been replaced by the clean, highly efficient,
.IR stdio (3)
package.
The first things to know are that
.IR getchar (3)
returns the integer EOF (\-1), which is not a possible byte value,
on end of file, that 518-byte buffers are out, and that there
is a defined FILE data type.
.LP
.I Make.\ \ 
The program
.IR make (1)
handles the recompilation and loading of
software in an orderly way from
a `makefile' recipe given for each piece of software.
It remakes only as much as the modification dates of the input files
show is necessary.
The makefiles will guide you in building your new system.
.LP
.I
Shell, chdir; csh.\ \ 
.R
F. L. Bauer once said Algol 68 is the Everest that
must be climbed by every computer scientist because
it is there.
So it is with the shell for
.UX
users.
Everything beyond simple command invocation from a terminal is
different.
Even
.I chdir
is now spelled
.I cd.
You will want to study
.IR sh (1)
long and hard.
.IR Csh (1)
provides another way to do things, with history substitutions
and the interface to the process control mechanism.
.LP
.I Debugging.\ \ 
.IR Adb (1)
is a far more capable replacement for the debugger
.I db.
The first-time user should be especially careful about
distinguishing / and ? in
.I adb
commands, and watching to make sure that the
.I x
whose value he asked for is the real
.I x,
and not just some absolute location equal to the stack offset
of some automatic
.I x.
You can always use the `true' name,
.I \_x,
to pin down a C external variable.
.LP
.I Dsw.
This little-known, but indispensable facility has been
taken over by
.I
rm \-ri.
.LP
.I
Boot procedures.\ \ 
.R
Needless to say, these are all different.
See section 8 of this volume, and
`Installing and Operating 2.9BSD'.