











                             4.4BSD


                          Programmer's


                     Supplementary Documents



                              (PSD)

















































Now  in  its twentieth year, the USENIX Association, the UNIX and
Advanced Computing Systems professional and  technical  organiza-
tion,  is  a not-for-profit membership association of individuals
and institutions with an interest in UNIX and UNIX-like  systems,
and,  by  extension, C++, X windows, and other advanced tools and
technologies.

USENIX and its members are dedicated to:

o    fostering innovation and communicating research and  techno-
     logical developments,

o    sharing ideas and experience relevant to UNIX, UNIX-related,
     and advanced computing systems, and

o    providing a neutral  forum  for  the  exercise  of  critical
     thought and airing of technical issues.

USENIX  publishes  a  journal  (Computing  Systems), a newsletter
(;login:), Proceedings from its  frequent  Conferences  and  Sym-
posia, and a Book Series.

SAGE, The Systems Administrators Guild, a Special Technical Group
with the USENIX Association, is dedicated to the  advancement  of
system administration as a profession.

SAGE brings together systems managers and administrators to:

o    propagate knowledge of good professional practice,

o    recruit talented individuals to the profession,

o    recognize individuals who attain professional excellence,

o    foster  technical development and share solutions to techni-
     cal problems, and

o    communicate in an organized voice  with  users,  management,
     and vendors on system administration topics.






























                             4.4BSD


                          Programmer's


                     Supplementary Documents



                              (PSD)








                 Berkeley Software Distribution


                           April, 1994








                 Computer Systems Research Group

              University of California at Berkeley














                    A USENIX Association Book
                   O'Reilly & Associates, Inc.
                   103 Morris Street, Suite A












                      Sebastopol, CA 94572

































































First Printing, 1994
Second Printing, 1995



Copyright  1979,  1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993,
1994 The Regents of the University  of  California.   All  rights
reserved.



Other  than  the specific manual pages and documents listed below
as copyrighted by AT&T, redistribution and use of this manual  in
source  and  binary forms, with or without modification, are per-
mitted provided that the following conditions are met:

1)   Redistributions of this manual  must  retain  the  copyright
     notices  on  this page, this list of conditions and the fol-
     lowing disclaimer.

2)   Software or documentation that  incorporates  part  of  this
     manual  must  reproduce  the copyright notices on this page,
     this list of conditions and the following disclaimer in  the
     documentation  and/or other materials provided with the dis-
     tribution.

3)   All advertising materials mentioning features or use of this
     software  must display the following acknowledgement: ``This
     product includes software developed  by  the  University  of
     California, Berkeley and its contributors.''

4)   Neither the name of the University nor the names of its con-
     tributors may be used to endorse or promote products derived
     from  this  software  without specific prior written permis-
     sion.

THIS SOFTWARE IS PROVIDED BY THE REGENTS  AND  CONTRIBUTORS  ``AS
IS''  AND  ANY  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR  A  PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCI-
DENTAL,  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES;
LOSS  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY  THEORY  OF  LIABILITY,  WHETHER  IN  CONTRACT,
STRICT  LIABILITY,  OR  TORT  (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE  USE  OF  THIS  SOFTWARE,  EVEN  IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



Documents  PSD:1,  2,  3,  4, 6, 11, 15, 16, and 17 are copyright
1979, AT&T Bell Laboratories, Incorporated.  Document PSD:8 is  a
modification  of  an earlier document that is copyrighted 1979 by












AT&T Bell Laboratories,  Incorporated.   Holders  of  UNIXTM/32V,
System  III,  or System V software licenses are permitted to copy
these documents,  or  any  portion  of  them,  as  necessary  for
licensed  use of the software, provided this copyright notice and
statement of permission are included.


Document PSD:10 is part of the user contributed software  and  is
copyright  1992 by the Free Software Foundation, Inc.  Permission
is granted to make and distribute verbatim copies of  this  docu-
ment provided the copyright notice and this permission notice are
preserved on all copies.


Document PSD:13 is part of the user contributed software  and  is
copyright  1983  by  Walter F. Tichy.  Permission to copy the RCS
documentation or any portion thereof as  necessary  for  licensed
use  of  the  software  is granted to licensees of this software,
provided this copyright notice is included.



The views and conclusions contained in this manual are  those  of
the  authors  and should not be interpreted as representing offi-
cial policies, either expressed or implied, of the Regents of the
University of California.



The 4.4BSD Daemon used on the cover is copyright 1994 by Marshall
Kirk McKusick and is reproduced with permission.
This book was printed and bound in the United States of  America.
Distributed by O'Reilly & Associates, Inc.


[recycle logo]  This  book is printed on acid-free paper with 50%
                recycled  content,  10-13%  post-consumer  waste.
                O'Reilly & Associates is committed to using paper
                with the highest recycled content available  con-
                sistent with high quality.


ISBN: 1-56592-079-1




























                            Contents



Introduction                                                   ix


Documents of Historical Interest


The Unix Time-Sharing System                             tabbed 1

     Dennis  Ritchie and Ken Thompson's original paper about
     UNIX, reprinted from Communications of the ACM.


Unix Implementation                                      tabbed 2

     Ken Thompson's description of the implementation of the
     Version 7 kernel and file system.


The Unix I/O System                                      tabbed 3

     Dennis  Ritchie's overview of the I/O System of Version
     7; still helpful for those writing device drivers.


Unix Programming - Second Edition                        tabbed 4

     Describes the programming interface to the UNIX version
     7  operating  system  and  the  standard  I/O  library.
     Should be supplemented by  Kernighan  and  Pike,  ``The
     UNIX Programming Environment'', Prentice-Hall, 1984 and
     especially by the Programmer Reference Manual section 2
     (system calls) and 3 (library routines).


Berkeley Software Architecture Manual (4.4 Edition)      tabbed 5

     A  concise  and  terse  description  of the system call
     interface provided in Berkeley  Unix,  as  revised  for
     4.4BSD.  This will never be a best seller.


Languages in common use












- viii -                                                 Contents


The C Programming Language - Reference Manual            tabbed 6

     Official  statement of the syntax of C.  Should be sup-
     plemented  by  ``The  C  Programming  Language,''  B.W.
     Kernighan  and  D.M. Ritchie, Prentice-Hall, 1978, that
     contains a tutorial introduction and many examples.


Berkeley Pascal User's Manual                            tabbed 7

     An implementation of this language popular for learning
     to program.


A Portable Fortran 77 Compiler                           tabbed 8

     A  revised  version  of  the  document which originally
     appeared in Volume 2b of the Bell  Labs  documentation;
     this version reflects the work done at Berkeley.


Introduction to the f77 I/O Library                      tabbed 9

     A  description  of the revised input/output library for
     Fortran 77, reflecting work carried out at Berkeley.


Programming Tools


Debugging with GDB: The GNU Source-Level Debugger       tabbed 10

     How to debug programs using the source level gdb debug-
     ger  (or  how  to debug programs without having to know
     much about machine language).


A Tutorial Introduction to ADB                          tabbed 11

     How to debug programs using the assembly-language level
     adb debugger.


Make - A Program for Maintaining Computer Programs      tabbed 12

     Indispensable  tool  for making sure large programs are
     properly compiled with minimal effort.


An Introduction to the Revision Control System          tabbed 13

     RCS is a user-contributed  tool  for  working  together
     with  other  people  without  stepping  on each other's
     toes.  An alternative to sccs for controlling  software









Contents                                                   - ix -


     changes.


An Introduction to the Source Code Control System       tabbed 14

     A  useful  introductory  article  for  those users with
     installations licensed for SCCS.


YACC: Yet Another Compiler-Compiler                     tabbed 15

     Converts a BNF specification of a language and semantic
     actions written in C into a compiler for that language.


LEX - A Lexical Analyzer Generator                      tabbed 16

     Creates a recognizer for a set of regular  expressions:
     each  regular expression can be followed by arbitrary C
     code to be executed upon finding  the  regular  expres-
     sion.


The M4 Macro Processor                                  tabbed 17

     M4  is a macro processor useful in its own right and as
     a front-end for C, Ratfor, and Cobol.


gprof: a Call Graph Execution Profiler                  tabbed 18

     A program to show the call graph and execution time  of
     a program.  Indispensable aid for improving the running
     time of almost everything.


Programming Libraries


Screen Updating and Cursor Movement Optimization        tabbed 19

     Describes  the  curses  package,  an  aid  for  writing
     screen-oriented, terminal-independent programs.


General Reference


An Introductory 4.4BSD Interprocess Communication Tutoritabbed 20

     How  to write programs that use the Interprocess Commu-
     nication Facilities of 4.4BSD.











- x -                                                    Contents


An Advanced 4.4BSD Interprocess Communication Tutorial  tabbed 21

     The reference document (with  some  examples)  for  the
     Interprocess Communication Facilities of 4.4BSD.


List of Documents                               inside back cover



























































                             Introduction



The  documentation  for  4.4BSD is in a format similar to the one
used for the 4.2BSD and 4.3BSD manuals.  It is divided into three
sets;  each  set  consists of one or more volumes.  The abbrevia-
tions for the volume names are listed  in  square  brackets;  the
abbreviations  for the manual sections are listed in parenthesis.

     I. User's Documents
          User's Reference Manual [URM]
               Commands (1)
               Games (6)
               Macro packages and language conventions (7)
          User's Supplementary Documents [USD]
               Getting Started
               Basic Utilities
               Communicating with the World
               Text Editing
               Document Preparation
               Amusements

     II. Programmer's Documents
          Programmer's Reference Manual [PRM]
               System calls (2)
               Subroutines (3)
               Special files (4)
               File formats and conventions (5)
          Programmer's Supplementary Documents [PSD]
               Documents of Historic Interest
               Languages in common use
               Programming Tools
               Programming Libraries
               General Reference

     III. System Manager's Manual [SMM]
          Maintenance commands (8)
          System Installation and Administration


References to individual documents are  given  as  ``volume:docu-
ment'',  thus  USD:1 refers to the first document in the ``User's
Supplementary Documents''.  References to manual pages are  given
as  ``name(section)'' thus sh(1) refers to the shell manual entry
in section 1.

The manual pages give descriptions of the features of the  4.4BSD
system, as developed at the University of California at Berkeley.
They do not attempt to provide perspective or  tutorial  informa-
tion  about  the  4.4BSD operating system, its facilities, or its
implementation.  Various documents on those topics are  contained
in  the ``UNIX User's Supplementary Documents'' (USD), the ``UNIX
Programmer's Supplementary Documents'' (PSD), and  ``UNIX  System









- xii -                                              Introduction


Manager's  Manual''  (SMM).   In  particular, for an overview see
``The UNIX Time-Sharing System'' (PSD:1) by Ritchie and Thompson;
for  a  tutorial see ``UNIX for Beginners'' (USD:1) by Kernighan,
and for an guide to the new features of this latest version,  see
``Berkeley  Software Architecture Manual (4.4 Edition)'' (PSD:5).

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.

Commands  are  programs  intended  to  be invoked directly by the
user, in contrast to subroutines, that are intended to be  called
by  the user's programs.  User commands are described in URM sec-
tion 1.  Commands generally reside in directory /bin (for  binary
programs).   Some programs also reside in /usr/bin, to save space
in /bin.  These directories are  searched  automatically  by  the
command  interpreters.   Additional  directories  that  may be of
interest include /usr/contrib/bin, which has contributed software
/usr/old/bin,  which  has old but sometimes still useful software
and /usr/local/bin, which contains software local to your site.

Games have been relegated to URM section  6  and  /usr/games,  to
keep  them  from  contaminating the more staid information of URM
section 1.

Miscellaneous collection of information necessary for writing  in
various  specialized  languages  such  as  character codes, macro
packages for typesetting, etc is contained in URM section 7.

System calls are entries into the BSD kernel.   The  system  call
interface is identical to a C language procedure call; the equiv-
alent C procedures are described in PRM section 2.

An assortment of subroutines is available; they are described  in
PRM  section 3.  The primary libraries in which they are kept are
described in intro(3).  The functions are described in  terms  of
C.

PRM  section  4  discusses  the  characteristics  of  each system
``file'' that refers to an I/O device.  The names in this section
refer  to the HP300 device names for the hardware, instead of the
names of the special files themselves.

The file formats and conventions (PRM 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.

Commands and procedures intended for use primarily by the  system
administrator   are  described  in  SMM  section  8.   The  files









Introduction                                             - xiii -


described here are almost all kept in the  directory  /etc.   The
system administration binaries reside in /sbin, and /usr/sbin.

Each  section  consists  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.  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.

All entries are based on a common  format;  not  all  subsections
always appear.

     The  name  subsection  lists the exact names of the commands
     and subroutines covered under the entry and  gives  a  short
     description of their purpose.

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

          Boldface  words  are considered literals, and are typed
          just as they appear.

          Square brackets [ ] around an argument  show  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  ``-''  usually
          means that it is an 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 ``-''.

     The description subsection discusses in detail  the  subject
     at hand.

     The files subsection gives the names of files that are built
     into the program.

     A see also subsection gives pointers to related information.

     A  diagnostics  subsection  discusses the diagnostic indica-
     tions that may be produced.  Messages that are  intended  to
     be self-explanatory are not listed.

     The bugs subsection gives known bugs and sometimes deficien-
     cies.  Occasionally the suggested fix is also described.











- xiv -                                              Introduction


At the beginning of URM, PRM, and SSM is a List of Manual  Pages,
organized  by section and alphabetically within each section, and
a Permuted Index derived  from  that  List.   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 that  exist  only
to  exercise  a particular system call.  Finally, there is a list
of documents on the inside back cover of each volume.



















































