NetBSD/share/man/man0/title.prm

590 lines
17 KiB
Plaintext
Raw Normal View History

1994-08-08 23:32:44 +04:00
.\" Copyright (c) 1980, 1993, 1994 Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 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 contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" 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, INCIDENTAL, 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.
.\"
.\" @(#)title.prm 8.4 (Berkeley) 8/8/94
.\"
.af % i
.nr LL 6.5i
.EH ''''
.OH ''''
.EF ''''
.OF ''''
\&
.sp |1.5i
.nr PS 36
.nr VS 39
.LP
.ft B
.ce 3
4.4BSD
Programmer's
Reference Manual
.nr PS 24
.nr VS 32
.LP
.ft B
.ce 1
(PRM)
.bp
\&
.sp |0.83i
.nr PS 14
.nr VS 16.5
.LP
Now in its twentieth year, the USENIX Association,
the UNIX and Advanced Computing Systems professional and technical organization,
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.
.LP
USENIX and its members are dedicated to:
.IP \(bu
fostering innovation and communicating research and technological developments,
.IP \(bu
sharing ideas and experience relevant to UNIX,
UNIX-related, and advanced computing systems, and
.IP \(bu
providing a neutral forum for the exercise of critical
thought and airing of technical issues.
.LP
USENIX publishes a journal (\fBComputing Systems\fP),
a newsletter (\fI;login:\fP),
Proceedings from its frequent Conferences and Symposia,
and a Book Series.
.LP
SAGE, The Systems Administrators Guild, a Special Technical Group with
the USENIX Association, is dedicated to the advancement of system
administration as a profession.
.LP
SAGE brings together systems managers and administrators to:
.IP \(bu
propagate knowledge of good professional practice,
.IP \(bu
recruit talented individuals to the profession,
.IP \(bu
recognize individuals who attain professional excellence,
.IP \(bu
foster technical development and share solutions to technical
problems, and
.IP \(bu
communicate in an organized voice with users, management, and vendors
on system administration topics.
.bp
\&
.sp |1i
.nr PS 36
.nr VS 39
.LP
.ft B
.ce 3
4.4BSD
Programmer's
Reference Manual
.nr PS 24
.nr VS 32
.LP
.ft B
.ce 1
(PRM)
.sp 1i
.nr PS 24
.nr VS 26
.LP
.ft B
.ce 1
Berkeley Software Distribution
.nr PS 18
.nr VS 26
.LP
.ft B
.ce 1
April, 1994
.sp 1i
.nr PS 18
.nr VS 20
.LP
.ft B
.ce 2
Computer Systems Research Group
University of California at Berkeley
.sp 2.2i
.nr PS 12
.nr VS 14.5
.LP
.ft B
.ce 4
A USENIX Association Book
O'Reilly & Associates, Inc.
103 Morris Street, Suite A
Sebastopol, CA 94572
.bp
.hy 0
.nr PS 9
.nr VS 11
.LP
First Printing, 1994
.br
Second Printing, 1995
.sp 1
.LP
Copyright 1979, 1980, 1983, 1986, 1993, 1994
The Regents of the University of California. All rights reserved.
.sp 1
.LP
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 permitted provided that the
following conditions are met:
.IP 1)
Redistributions of this manual must retain the copyright
notices on this page, this list of conditions and the following disclaimer.
.IP 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 distribution.
.IP 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.''
.IP 4)
Neither the name of the University nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
.LP
\fB\s-1THIS 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, INCIDENTAL, 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.\s+1\fP
.sp 1
.LP
The Institute of Electrical and Electronics Engineers and the American
National Standards Committee X3, on Information Processing Systems have
given us permission to reprint portions of their documentation.
.sp 0.5
.LP
In the following statement, the phrase ``this text'' refers to portions
of the system documentation.
.LP
``Portions of this text are reprinted and reproduced in
electronic form in 4.4BSD from IEEE Std 1003.1-1988, IEEE
Standard Portable Operating System Interface for Computer Environments
(POSIX), copyright 1988 by the Institute of Electrical and Electronics
Engineers, Inc. In the event of any discrepancy between these versions
and the original IEEE Standard, the original IEEE Standard is the referee
document.''
.sp 0.5
.LP
In the following statement, the phrase ``This material'' refers to portions
of the system documentation.
.LP
``This material is reproduced with permission from American National
Standards Committee X3, on Information Processing Systems. Computer and
Business Equipment Manufacturers Association (CBEMA), 311 First St., NW,
Suite 500, Washington, DC 20001-2178. The developmental work of
Programming Language C was completed by the X3J11 Technical Committee.''
.sp 1
.LP
Manual pages ptrace.2, ecvt.3, mp.3, plot.3, L-devices.5, L-dialcodes.5,
L.aliases.5, L.cmds.5, L.sys.5, USERFILE.5, dump.5, and plot.5
are copyright 1979, AT&T Bell Laboratories, Incorporated.
Holders of \x'-1p'UNIX\v'-4p'\s-3TM\s0\v'4p'/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.
.sp 1
.LP
The views and conclusions contained in this manual are those of the
authors and should not be interpreted as representing official policies,
either expressed or implied, of the Regents of the University of California.
.sp 1
.LP
The 4.4BSD Daemon used on the cover is
copyright 1994 by Marshall Kirk McKusick
and is reproduced with permission.
.br
This book was printed and bound in the United States of America.
.br
Distributed by O'Reilly & Associates, Inc.
.sp 1
.IP "[recycle logo]" 16
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 consistent
with high quality.
.LP
.sp 1
ISBN: 1-56592-078-3
.bp
\&
.sp |1.5i
.nr PS 24
.nr VS 26
.LP
.ce 1
\fBContents\fP
.sp 1
.nr PS 14
.nr VS 17
.LP
.TS
expand;
l r.
Introduction vii
List of Manual Pages ix
Permuted Index xxix
Reference Manual Sections 2, 3, 4, 5 tabbed pages
List of Documents inside back cover
.TE
.if o .bp
\&
.EH ''''
.OH ''''
.bp
.OH '\s10Introduction''- % -\s0'
.EH '\s10- % -''Introduction\s0'
.de IR
\fI\\$1\^\fR\\$2
..
.de RI
\fR\\$1\fI\\$2\^\fR\\$3
..
.ce
\fB\s24Introduction\s0\fP
.sp 2
.nr PS 10
.nr VS 12
.LP
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 abbreviations for the volume names are listed in square brackets;
the abbreviations for the manual sections are listed in parenthesis.
.DS
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
.DE
.LP
References to individual documents are given as ``volume:document'',
thus USD:1 refers to the first document in the ``User's Supplementary
Documents''.
References to manual pages are given as ``\fIname\fP(section)'' thus
.IR sh (1)
refers to the shell manual entry in section 1.
.LP
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 information about the
4.4BSD operating system, its facilities, or its implementation.
Various documents on those topics are contained in the
``\s-1UNIX\s+1 User's Supplementary Documents'' (USD), the
``\s-1UNIX\s+1 Programmer's Supplementary Documents'' (PSD),
and ``\s-1UNIX\s+1 System Manager's Manual'' (SMM).
In particular, for an overview see ``The \s-1UNIX\s+1 Time-Sharing System'' (PSD:1)
by Ritchie and Thompson; for a tutorial see
``\s8\s-1UNIX\s+1\s10 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).
.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
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 section 1.
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.
.R
These directories are searched automatically by the command interpreters.
Additional directories that may be of interest include
.I
/\|usr/\|contrib/\|bin,
.R
which has contributed software
.I
/\|usr/\|old/\|bin,
.R
which has old but sometimes still useful software and
.I
/\|usr/\|local/\|bin,
.R
which contains software local to your site.
.LP
Games have been relegated to URM section 6 and
.I
/\|usr/\|games,
.R
to keep them from contaminating
the more staid information of URM section 1.
.LP
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.
.LP
System calls are entries into the BSD kernel.
The system call interface is identical to a C language
procedure call; the equivalent C procedures are described in PRM section 2.
.LP
An assortment of subroutines is available;
they are described in PRM section 3.
The primary libraries in which they are kept are described in
.IR intro (3).
The functions are described in terms of C.
.LP
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.
.LP
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.
.LP
Commands and procedures intended for use primarily by the
system administrator are described in SMM section 8.
The files described here are almost all kept in the directory
.I /\|etc.
The system administration binaries reside in
.I
/\|sbin,
.R
and
.I
/\|usr/\|sbin.
.LP
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.
.LP
All entries are based on a common format;
not all subsections always appear.
.RS
.LP
The
.I name
subsection lists the exact names of the commands and subroutines
covered under the entry and gives a 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 show 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 ``\-'' 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 ``\-''.
.LP
.RE
The
.IR description ""
subsection discusses in detail the subject at hand.
.LP
The
.IR files ""
subsection gives the names of files that 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 that may be produced.
Messages that are intended to be self-explanatory are not listed.
.LP
The
.IR bugs ""
subsection gives known bugs and sometimes deficiencies.
Occasionally the suggested fix is also described.
.LP
.RE
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.
.if o .bp
\&
.EH ''''
.OH ''''
.bp
.OH '\s10Manual Pages''- % -\s0'
.EH '\s10- % -''Manual Pages\s0'
.EF '\s10\\\\*(Dt''\\\\*(Ed\s0'
.OF '\s10\\\\*(Ed''\\\\*(Dt\s0'
.nr PS 10
.nr VS 12
.LP
.ce
\s24\fBList \|of \|Manual \|Pages\fP\s0
.nr x 0.5
.in +\nxi
.nf
.ta \n(.lu-\nxuR
.de xx
\\$1\f3 \a \fP\\$2
..
.de t
.sp 1v
.ne .5i
.cs 3
.ti -\\nxi
.ss 18
\fB\\$2. \\$3\fP
.ss 12
.if t .sp .5v
.cs 3 36
.ds Ed Section \\$2
.ds Dt \\$3
.so \\$1
..
.t toc1 1 "Commands and Application Programs"
.t toc2 2 "System Calls"
.t toc3 3 "C Library Subroutines"
.t toc4 4 "Special Files"
.t toc5 5 "File Formats"
.t toc6 6 "Games"
.t toc7 7 "Miscellaneous"
.t toc8 8 "System Maintenance"
.in -\nxi
.cs 3
.ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i 6i 6.5i
.if o .bp
\&
.EH ''''
.OH ''''
.bp
\&
.OH '\s10Permuted Index''- % -\s0'
.EH '\s10- % -''Permuted Index\s0'
.ds Ed 4.4BSD
.ds Dt April \|1994
.ce
\s24\fBPermuted \|Index\fP\s0
.sp 2
.nr PS 8
.nr VS 9
.LP
.\" backup from slotput 1, slot, 2
.tr ~
.nf
.cs 3 36
.de xx
.ds s1\"
.if \w\\$2 .ds s1 ~~\"
.ds s2 ~~~\"
.ds s3\"
.if \w\\$4 .ds s3 ~~\"
.ds s4 ~~\"
.ds s5 ~~\"
.ds y \\*(s4\f3\fP\\*(s5
.ta 6i-\w\\*(s5u
\h"3i-\w\\$1\\*(s1\\$2\\*(s2u"\\$1\\*(s1\\$2\\*(s2\\$3\\*(s3\\$4\\*y\\$5
..
.so ptxx
.cs 3
.ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i 6i 6.5i