.de IR
\fI\\$1\^\fR\\$2
..
.de RI
\fR\\$1\fI\\$2\^\fR\\$3
..
.TL
INTRODUCTION TO VOLUME 1
.af PN i
.pn 3
.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.
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.
.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).
.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
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.
These procedures often involve use of commands
of section 1, where an attempt has been made to
single out peculiarly maintenance-flavored commands
by marking them 1M.
.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
.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.
