.na
.bl  15
.tr |
.in 0
.ce
UNIX PROGRAMMER'S MANUAL

.ce
Third Edition



.ce 3
K. Thompson

D. M. Ritchie




.ce
February, 1973
.sp 15
.ce 7
Copyright 8c9 1972
Bell Telephone Laboratories, Inc.

No part of this document may be reproduced,
or distributed outside the Laboratories, without
the written permission of Bell Telephone Laboratories.
.bp
.fo ''- % -''
.ro
.bl 2
.ce 2
PREFACE
to the Third Edition


In the months since the last appearance of this manual,
many changes have occurred
both in the system itself and in the way it is
used.

Perhaps most obviously,
there have been additions, deletions, and modifications
to the system and its software.
It is these changes, of course, that
caused the appearance of this revised manual.

Second, the number of people spending
an appreciable amount
of time writing UNIX software has increased.
Credit is due
to L.|L.|Cherry, M.|D.|McIlroy, L.|E.|McMahon, R.|Morris,
J.|F.|Ossanna,
and E.|N.|Pinson
for their contributions.

Finally, the number of UNIX installations
has grown to 16, with more expected.
None of these has exactly the same complement
of hardware or software.
Therefore, at any particular installation,
it is quite possible that this manual will
give inappropriate information.
.a

In particular,
.ul 3
any system which uses a PDP-11/20
processor will not include all the software described
herein, nor will the software behave the same way.
The second, or even the first, edition
of this manual is likely to be more
appropriate.

Besides additions, deletions, and
modifications to the writeups in each section,
this manual differs from its predecessors
in two ways:
all the commands used for system maintenance
and not intended for normal users have been moved
to a new section VIII;
and there is a new "How to Get Started"
chapter that gives some elementary facts
and many pointers to other sections.
.bp
.bl 2
.ce
INTRODUCTION TO THIS MANUAL


This manual gives descriptions of the publicly available
features of UNIX.
It provides neither a general
overview (see "The UNIX Time-sharing System" for that)
nor details of the implementation of the system (which
remain to be disclosed).

Within the area it surveys, this manual attempts
to be as complete and timely as possible.
A conscious
decision was made to describe each program
in exactly the state it was in at the time
its manual section
was prepared.
In particular, the
desire to describe something as it should be, not as it is,
was resisted.
Inevitably, this means that
many sections will soon be out of date.
(The rate of
change of the system is so great that a dismayingly
large number of early sections
had to be modified while the rest were being written.
The unbounded effort required to stay up-to-date
is best indicated by the fact that several of the programs
described were written specifically to aid in preparation
of this manual!)

This manual is divided into
eight sections:

   I.    Commands
   II.   System calls
   III.  Subroutines
   IV.   Special files
   V.    File formats
   VI.   User-maintained programs
   VII.  Miscellaneous
   VIII. Maintenance

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 /bin____ (for
bin___ary programs).  This directory is searched automatically
by the command line interpreter.  Some programs
classified as commands are located elsewhere; this
fact is indicated in the appropriate sections.

System calls are entries into the UNIX supervisor.
In assembly language, they are coded with the use
of the opcode "sys", a synonym for the
trap____ instruction.

A small assortment
of subroutines is available;
they are described in section III.
The binary form of most of them is kept in
the system library /usr/lib/liba.a.

The special files section IV discusses the characteristics of
each system "file" which actually refers to an I/O device.
Unlike previous editions, the names in this
section refer to the DEC device names for the
hardware,
instead of the neames of
the special files themselves.

The file formats section V 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.

User-maintained programs (section VI) are not considered part
of the UNIX system, and the principal reason for
listing them is to indicate their existence without
necessarily giving a complete description.
The author should be consulted for information.

The miscellaneous section (VII) gathers odds and ends.

Section VIII discusses commands which are not intended
for use by the ordinary user,
in some cases because they disclose information
in which he is presumably not interested,
and in others because they perform
privileged functions.


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,
its preparation date in the upper middle.
Entries within each section are
alphabetized.
The page numbers of each entry start at 1.
(The earlier hope for frequent, partial
updates of the manual is clearly in vain, but
in any event it is not feasible to
maintain consecutive page numbering in a document
like this.)

All entries have a common format.
.sp
.in 5
The name____ section repeats the entry name and gives
a very short description of its purpose.

The synopsis________ summarizes the use of the
program being described.
A few conventions are used, particularly in the
Commands section:

.in 8
Underlined words are considered literals, and
are typed just as they appear.

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.

Ellipses "..." are used to show that the previous argument-prototype
may be repeated.

A final convention is used by the commands themselves.
An argument beginning with a minus sign "-"
is often taken to mean some sort of flag 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 "-".

.in 5
The description___________ section discusses in detail the subject at hand.

The files_____ section gives the names of files which are
built into the program.

A see___ also____ section gives pointers to related information.

A diagnostics___________
section discusses
the diagnostics that may be produced.
This section tends to be as terse
as the diagnostics themselves.

The bugs____ section gives
known bugs and sometimes deficiencies.
Occasionally also the suggested fix is
described.

.in 0
Previous edition of this manual had
an owner_____ section, which has been dropped from this
edition because the "owners" of many routines became
fairly hard to pin down.
The major contributors to UNIX,
(cast in order of appearance)
together with their login names and most notable contributions,
are

   ken    K. Thompson		(UNIX, many commands)
   dmr    D. M. Ritchie		(many commands, as, ld, C)
   jfo    J. F. Ossanna		(roff, nroff)
   doug   M. D. McIlroy		(tmg, m6)
   rhm    R. Morris		(dc, much of library)
   lem    L. E. McMahon		(cref)
   llc    L. L. Cherry		(form, fed, salloc)
   csr    C. S. Roberts		(tss)
   enp    E. N. Pinson		(proof)

At the beginning of this document 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.


This manual was prepared using the UNIX text
editor ed__ and the formatting program roff____.

The assistance of R. Morris is gratefully acknowledged.
