











                             44..44BBSSDD


                             UUsseerr''ss


                     SSuupppplleemmeennttaarryy DDooccuummeennttss



                              ((UUSSDD))

















































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  (CCoommppuuttiinngg  SSyysstteemmss), a newsletter
(_;_l_o_g_i_n_:), 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 ''''





                             44..44BBSSDD


                             UUsseerr''ss


                     SSuupppplleemmeennttaarryy DDooccuummeennttss



                              ((UUSSDD))








                 BBeerrkkeelleeyy SSooffttwwaarree DDiissttrriibbuuttiioonn


                           AApprriill,, 11999944








                 CCoommppuutteerr SSyysstteemmss RReesseeaarrcchh GGrroouupp

              UUnniivveerrssiittyy ooff CCaalliiffoorrnniiaa aatt BBeerrkkeelleeyy














                    AA UUSSEENNIIXX AAssssoocciiaattiioonn BBooookk
                   OO''RReeiillllyy && AAssssoocciiaatteess,, IInncc..
                   110033 MMoorrrriiss SSttrreeeett,, SSuuiittee AA












                      SSeebbaassttooppooll,, CCAA 9944557722

































































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.

TTHHIISS SSOOFFTTWWAARREE IISS PPRROOVVIIDDEEDD BBYY TTHHEE RREEGGEENNTTSS  AANNDD  CCOONNTTRRIIBBUUTTOORRSS  ````AASS
IISS''''  AANNDD  AANNYY  EEXXPPRREESSSS OORR IIMMPPLLIIEEDD WWAARRRRAANNTTIIEESS,, IINNCCLLUUDDIINNGG,, BBUUTT NNOOTT
LLIIMMIITTEEDD TTOO,, TTHHEE IIMMPPLLIIEEDD WWAARRRRAANNTTIIEESS OOFF MMEERRCCHHAANNTTAABBIILLIITTYY AANNDD FFIITTNNEESSSS
FFOORR  AA  PPAARRTTIICCUULLAARR PPUURRPPOOSSEE AARREE DDIISSCCLLAAIIMMEEDD..  IINN NNOO EEVVEENNTT SSHHAALLLL TTHHEE
RREEGGEENNTTSS OORR CCOONNTTRRIIBBUUTTOORRSS BBEE LLIIAABBLLEE FFOORR AANNYY DDIIRREECCTT,, IINNDDIIRREECCTT,, IINNCCII--
DDEENNTTAALL,,  SSPPEECCIIAALL,, EEXXEEMMPPLLAARRYY,, OORR CCOONNSSEEQQUUEENNTTIIAALL DDAAMMAAGGEESS ((IINNCCLLUUDDIINNGG,,
BBUUTT NNOOTT LLIIMMIITTEEDD TTOO,, PPRROOCCUURREEMMEENNTT OOFF SSUUBBSSTTIITTUUTTEE GGOOOODDSS OORR  SSEERRVVIICCEESS;;
LLOOSSSS  OOFF UUSSEE,, DDAATTAA,, OORR PPRROOFFIITTSS;; OORR BBUUSSIINNEESSSS IINNTTEERRRRUUPPTTIIOONN)) HHOOWWEEVVEERR
CCAAUUSSEEDD AANNDD OONN AANNYY  TTHHEEOORRYY  OOFF  LLIIAABBIILLIITTYY,,  WWHHEETTHHEERR  IINN  CCOONNTTRRAACCTT,,
SSTTRRIICCTT  LLIIAABBIILLIITTYY,,  OORR  TTOORRTT  ((IINNCCLLUUDDIINNGG NNEEGGLLIIGGEENNCCEE OORR OOTTHHEERRWWIISSEE))
AARRIISSIINNGG IINN AANNYY WWAAYY OOUUTT OOFF TTHHEE  UUSSEE  OOFF  TTHHIISS  SSOOFFTTWWAARREE,,  EEVVEENN  IIFF
AADDVVIISSEEDD OOFF TTHHEE PPOOSSSSIIBBIILLIITTYY OOFF SSUUCCHH DDAAMMAAGGEE..



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





































                            CCoonntteennttss



Introduction                                                   ix


GGeettttiinngg SSttaarrtteedd


Unix for Beginners - Second Edition                      tabbed 1

     An introduction to the most basic uses of the system.


Learn - Computer-Aided Instruction on UNIX (Second Editiont)abbed 2

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


BBaassiicc UUttiilliittiieess


An Introduction to the UNIX Shell                        tabbed 3

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


An Introduction to the C shell                           tabbed 4

     This  introduction to _c_s_h_, (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.


CCoommmmuunniiccaattiinngg wwiitthh tthhee WWoorrlldd


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.


TTeexxtt EEddiittiinngg


A Tutorial Introduction to the Unix Text Editor          tabbed 9

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


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 _v_i screen editor.


Ex Reference Manual (Version 3.7)                       tabbed 12

     The final reference for the _e_x editor.


Vi Reference Manual                                     tabbed 13

     The definitive reference for the _n_v_i editor.


Jove Manual for UNIX Users                              tabbed 14

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












Contents                                                   - ix -


SED - A Non-interactive Text Editor                     tabbed 15

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


AWK - A Pattern Scanning and Processing Language (SecondtEadbibteidon1)6

     A program for data selection and transformation.


DDooccuummeenntt PPrreeppaarraattiioonn


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

     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 _n_r_o_f_f using -me                     tabbed 19

     Another popular macro package for _n_r_o_f_f_.


-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  _t_r_o_f_f  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 _e_q_n_, 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 _e_q_n_.


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, _r_e_f_e_r_,  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  _r_e_f_e_r  programs  in  a
     somewhat larger context.


BIB - A Program for Formatting Bibliographies           tabbed 28

     This is an alternative to _r_e_f_e_r 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.


AAmmuusseemmeennttss


A Guide to the Dungeons of Doom                         tabbed 30

     An introduction to the popular game of _r_o_g_u_e, 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




































































                             IInnttrroodduuccttiioonn



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 ``_n_a_m_e(section)'' thus _s_h(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 _/_b_i_n (for _b_i_nary
programs).  Some programs also reside in _/_u_s_r_/_b_i_n_, to save  space
in  _/_b_i_n_.   These  directories  are searched automatically by the
command interpreters.  Additional  directories  that  may  be  of
interest include _/_u_s_r_/_c_o_n_t_r_i_b_/_b_i_n_, which has contributed software
_/_u_s_r_/_o_l_d_/_b_i_n_, which has old but sometimes still  useful  software
and _/_u_s_r_/_l_o_c_a_l_/_b_i_n_, which contains software local to your site.

Games  have  been  relegated  to URM section 6 and _/_u_s_r_/_g_a_m_e_s_, 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  _i_n_t_r_o(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 _/_e_t_c_.  The
system administration binaries reside in _/_s_b_i_n_, and _/_u_s_r_/_s_b_i_n_.

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 _n_a_m_e subsection lists the exact names  of  the  commands
     and  subroutines  covered  under the entry and gives a short
     description of their purpose.

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

          BBoollddffaaccee 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  _d_e_s_c_r_i_p_t_i_o_n  subsection discusses in detail the subject
     at hand.

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

     A _s_e_e _a_l_s_o subsection gives pointers to related information.

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

     The _b_u_g_s 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.



















































