











                             4.4BSD


                             User's


                     Supplementary Documents



                              (USD)

















































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.
























=1 .if 0 .tl ''''





                             4.4BSD


                             User's


                     Supplementary Documents



                              (USD)








                 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  USD:1,  2, 3, 5, 6, 9, 10, 15, 16, 17, 21, 22, 23, 24,
25, 26, 27, and 29 are copyright 1979,  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.


Documents  USD:8,  14,  and  28  are part of the user contributed
software.



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-076-7





































                            Contents



Introduction                                                   ix


Getting Started


Unix for Beginners - Second Edition                      tabbed 1

     An introduction to the most basic uses of the system.


Learn - Computer-Aided Instruction on UNIX (Second Editiotabbed 2

     Describes  a  computer-aided  instruction  program that
     walks new users through the basics of files,  the  edi-
     tor, and document prepararation software.


Basic Utilities


An Introduction to the UNIX Shell                        tabbed 3

     Steve  Bourne's introduction to the capabilities of sh,
     a command interpreter especially  popular  for  writing
     shell scripts.


An Introduction to the C shell                           tabbed 4

     This  introduction to csh, (a command interpreter popu-
     lar for interactive work) describes many commonly  used
     UNIX  commands, assumes little prior knowledge of UNIX,
     and has a glossary useful for beginners.


DC - An Interactive Desk Calculator                      tabbed 5

     A super HP calculator, if  you  do  not  need  floating
     point.


BC - An Arbitrary Precision Desk-Calculator Language     tabbed 6











- viii -                                                 Contents


     A  front  end for DC that provides infix notation, con-
     trol flow, and built-in functions.


Communicating with the World


Mail Reference Manual                                    tabbed 7

     Complete details on one of the programs for sending and
     reading your mail.


The Rand MH Message Handling System                      tabbed 8

     This  system  for managing your computer mail uses lots
     of small programs, instead of one large one.


Text Editing


A Tutorial Introduction to the Unix Text Editor          tabbed 9

     An easy way to get started with the line editor, ed.


Advanced Editing on Unix                                tabbed 10

     The next step.


An Introduction to Display Editing with Vi              tabbed 11

     The document to learn to use the vi screen editor.


Ex Reference Manual (Version 3.7)                       tabbed 12

     The final reference for the ex editor.


Vi Reference Manual                                     tabbed 13

     The definitive reference for the nvi editor.


Jove Manual for UNIX Users                              tabbed 14

     Jove is a small, self-documenting, customizable display
     editor, based on EMACS.  A plausible alternative to vi.












Contents                                                   - ix -


SED - A Non-interactive Text Editor                     tabbed 15

     Describes a one-pass variant of ed useful as  a  filter
     for processing large files.


AWK - A Pattern Scanning and Processing Language (Secondtabbedo16

     A program for data selection and transformation.


Document Preparation


Typing Documents on UNIX: Using the -ms Macros with TroftabbedN17ff

     Describes  and  gives  examples of the basic use of the
     typesetting tools and ``-ms'', a frequently used  pack-
     age  of  formatting requests that make it easier to lay
     out most documents.


A Revised Version of -ms                                tabbed 18

     A brief description of the Berkeley revisions  made  to
     the -ms formatting macros for nroff and troff.


Writing Papers with nroff using -me                     tabbed 19

     Another popular macro package for nroff.


-me Reference Manual                                    tabbed 20

     The final word on -me.


NROFF/TROFF User's Manual                               tabbed 21

     Extremely  detailed  information  about  these document
     formatting programs.


A TROFF Tutorial                                        tabbed 22

     An introduction to the most basic  uses  of  troff  for
     those  who  really want to know such things, or want to
     write their own macros.


A System for Typesetting Mathematics                    tabbed 23











- x -                                                    Contents


     Describes eqn, an easy-to-learn language for high-qual-
     ity mathematical typesetting.


Typesetting Mathematics - User's Guide (Second Edition) tabbed 24

     More details about how to use eqn.


Tbl - A Program to Format Tables                        tabbed 25

     A program for easily typesetting tabular material.


Refer - A Bibliography System                           tabbed 26

     An  introduction  to  one set of tools used to maintain
     bibliographic databases.  The major program, refer,  is
     used  to  automatically  retrieve and format the refer-
     ences based on document citations.


Some Applications of Inverted Indexes on the UNIX Systemtabbed 27

     Mike Lesk's paper describes the  refer  programs  in  a
     somewhat larger context.


BIB - A Program for Formatting Bibliographies           tabbed 28

     This is an alternative to refer for expanding citations
     in documents.


Writing Tools - The STYLE and DICTION Programs          tabbed 29

     These are programs which can help  you  understand  and
     improve your writing style.


Amusements


A Guide to the Dungeons of Doom                         tabbed 30

     An introduction to the popular game of rogue, a fantasy
     game which is one of the biggest  known  users  of  VAX
     cycles.


Star Trek                                               tabbed 31

     You  are  the Captain of the Starship Enterprise.  Wipe
     out the Klingons and save the Federation.









Contents                                                   - xi -


List of Documents                               inside back cover






























































- xii -                                                  Contents




































































                             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









- xiv -                                              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                                               - xv -


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.











- xvi -                                              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.



















































