update contrib (to 5.55)

[unix-history] / usr / src / share / man / man0 / title.urm

.\" Copyright (c) 1980, 1993 Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.roff%
.\"
.\"	@(#)title.urm	8.8 (Berkeley) %G%
.\"
.af % i
.EH ''''
.OH ''''
.OF '''\s10- % -\s0'
.EF '\s10- % -\s0'''
\&
.sp |2.75i
.nr PS 24
.nr VS 28
.LP
.ft B
.ce 2
UNIX User's Reference Manual
(URM)
.nr LL 5.5i
.nr PO 1.5i
.bp
\&
.sp |1.5i
.nr PS 11
.nr VS 13
.LP
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 programming tools.
It is 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),
Conference and Workshop Proceedings, and a Book Series.
.nr LL 6i
.nr PO 1i
.bp
\&
.sp |2.75i
.nr PS 18
.nr VS 22
.LP
.ft B
.ce 2
UNIX User's Reference Manual
(URM)
.sp |4i
.ce 2
4.4 Berkeley Software Distribution
(June, 1993)
.sp 3
.nr PS 15
.nr VS 18
.LP
.ce 2
Computer Systems Research Group
University of California, Berkeley
.sp |8.2i
.nr PS 12
.nr VS 15
.LP
.ce 4
A USENIX Association Book
The MIT Press
Cambridge, Massachusetts
London, England
.bp
.hy 0
.nr PS 9
.nr VS 11
.LP
First Printing, 1993
.sp 1
.LP
Copyright 1979, 1980, 1983, 1986, 1993
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 adb.1, bc.1, compact.1, crypt.1, dc.1, deroff.1, ed.1,
expr.1, graph.1, ld.1, learn.1, m4.1, plot.1, ptx.1, spell.1,
spline.1, struct.1, tar.1, units.1, uucp.1, uux.1, ching.6, eqnchar.7,
man.7, ms.7, and term.7
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
This book was printed and bound in the United States of America.
.br
Distributed by The MIT Press.
.bp
\&
.sp |1.5i
.nr PS 11
.nr VS 13
.LP
.ce 1
\s+4\fBContents\fP\s-4
.sp 3
.TS
expand;
l r.
The Computer Systems Research Group, 1979\-1993	vii
Prefaces	xi
Introduction	xvii
List of Manual Pages	xxiii
Permuted Index	xli
Reference Manual Sections 1, 6, 7	tabbed pages
List of Documents	inside back cover
.TE
.if o .bp
\&
.bp
.\"
.\" The contributor list below is derived from the file that resides in
.\" vangogh:~admin/contrib/contrib:
.\"
.\"	@(#)contrib	5.55 (Berkeley) 4/18/94
.\"
.\" This file should not be editted, rather the original contrib file
.\" should be used to recrete this one following the directions at its top.
.\" Contrib starts here and continues to the comment `END OF CONTRIB'.
.\"
\&
.sp |1i
.ps 16
.ce
\fBThe Computer Systems Research Group 1979 \- 1993\fP
.sp 3
.nr PS 11
.nr VS 12
.LP
.nf
.in +0.5i
\fBCSRG Technical Staff\fP
.sp 1
.in +1i
Jim Bloom
Keith Bostic
Ralph Campbell
Kevin Dunlap
William N. Joy
Michael J. Karels
Samuel J. Leffler
Marshall Kirk McKusick
Miriam Amos Nihart
Keith Sklower
Marc Teitelbaum
Michael Toy
.in -1i
.sp 3
\fBCSRG Administration and Support\fP
.sp 1
.in +1i
Robert Fabry
Domenico Ferrari
Susan L. Graham
Bob Henry
Anne Hughes
Bob Kridle
David Mosher
Pauline Schwartz
Mark Seiden
Jean Wood
.in -1i
.fi
.sp 3
\fBOrganizations that funded the CSRG with grants,
gifts, personnel, and/or hardware.\fP
.sp 1
.nf
.in +1i
Center for Advanced Aviation System Development, The MITRE Corp.
Compaq Computer Corporation
Cray Research Inc.
Department of Defense Advance Research Projects Agency (DARPA)
Digital Equipment Corporation
The Hewlett-Packard Company
NASA Ames Research Center
The National Science Foundation
The Open Software Foundation
UUNET Technologies Inc.
.in -1.5i
.fi
.bp
.nr PS 10
.nr VS 11
.LP
\fBThe following are people and organizations that provided a
large subsystem for the BSD releases.\fP
.sp
.TS
l l.
ANSI C library	Chris Torek
ANSI C prototypes	Donn Seeley and John Kohl
Autoconfiguration	Robert Elz
C library documentation	American National Standards Committee X3
CCI 6/32 support	Computer Consoles Inc.
DEC 3000/5000 support	Ralph Campbell
Disklabels	Symmetric Computer Systems
Documentation	Cynthia Livingston and The USENIX Association
Franz Lisp	Richard Fateman, John Foderaro, Keith Sklower, Kevin Layer
GCC, GDB	The Free Software Foundation
Groff	James Clark (The FSF)
HP300 support	Jeff Forys, Mike Hibler, Jay Lepreau, Donn Seeley and the Systems
	Programming Group; University of Utah Computer Science Department
ISODE	Marshall Rose
Ingres	Mike Stonebraker, Gene Wong, and the Berkeley Ingres Research Group
Intel 386/486 support	Bill Jolitz and TeleMuse
Job control	Jim Kulp
Kerberos	Project Athena and MIT
Kernel support	Bill Shannon and Sun Microsystems Inc.
LFS	Margo Seltzer, Mendel Rosenblum, Carl Staelin
MIPS support	Trent Hein
Math library	K.C. Ng, Zhishun Alex Liu, S. McDonald, P. Tang and W. Kahan
NFS	Rick Macklem
NFS automounter	Jan-Simon Pendry
Network device drivers	Micom-Interlan and Excelan
Omron Luna support	Akito Fujita and Shigeto Mochida
Quotas	Robert Elz
RPC support	Sun Microsystems Inc.
Shared library support	Rob Gingell and Sun Microsystems Inc.
Sony News 3400 support	Kazumasa Utashiro
Sparc I/II support	Computer Systems Engineering Group, Lawrence Berkeley Laboratory
Stackable file systems	John Heidemann
Stdio	Chris Torek
System documentation	The Institute of Electrical and Electronics Engineers, Inc.
TCP/IP	Rob Gurwitz and Bolt Beranek and Newman Inc.
Timezone support	Arthur David Olson
Transport/Network OSI layers	IBM Corporation and the University of Wisconsin
Kernel XNS assistance	William Nesheim, J. Q. Johnson, Chris Torek, and James O'Toole
User level XNS	Cornell University
VAX 3000 support	Mt. Xinu and Tom Ferrin
VAX BI support	Chris Torek
VAX device support	Digital Equipment Corporation and Helge Skrivervik
Versatec printer/plotter support	University of Toronto
Virtual memory implementation	Avadis Tevanian, Jr., Michael Wayne Young,
	and the Carnegie-Mellon University Mach project
X25 	University of British Columbia
.TE
.bp
.LP
\fBThe following are people and organizations that provided a specific
item, program, library routine or program maintenance for the BSD system.
(Their contribution may not be part of the final 4.4BSD release.)\fP
.nr PS 9
.nr VS 10
.ps 9
.vs 10
.TS
l l.
386 device drivers	Carnegie-Mellon University Mach project
386 device drivers	Don Ahn, Sean Fagan and Tim Tucker
HCX device drivers	Harris Corporation
Kernel enhancements	Robert Elz, Peter Ivanov, Ian Johnstone, Piers Lauder,
	John Lions, Tim Long, Chris Maltby, Greg Rose and John Wainwright 
ISO-9660 filesystem	Pace Willisson, Atsushi Murai
.TE
.sp -0.4
.TS
l l l l.
adventure(6)	Don Woods	log(3)	Peter McIlroy
adventure(6)	Jim Gillogly	look(1)	David Hitz
adventure(6)	Will Crowther	ls(1)	Elan Amir
apply(1)	Rob Pike	ls(1)	Michael Fischbein
apply(1)	Jan-Simon Pendry	lsearch(3)	Roger L. Snyder
ar(1)	Hugh A. Smith	m4(1)	Ozan Yigit
arithmetic(6)	Eamonn McManus	mail(1)	Kurt Schoens
arp(8)	Sun Microsystems Inc.	make(1)	Adam de Boor
at(1)	Steve Wall	me(7)	Eric Allman
atc(6)	Ed James	mergesort(3)	Peter McIlroy
awk(1)	Arnold Robbins	mh(1)	Marshall Rose
awk(1)	David Trueman	mh(1)	The Rand Corporation
backgammon(6)	Alan Char	mille(6)	Ken Arnold
banner(1)	Mark Horton	mknod(8)	Kevin Fall
battlestar(6)	David Riggle	monop(6)	Ken Arnold
bcd(6)	Steve Hayman	more(1)	Eric Shienbrood
bdes(1)	Matt Bishop	more(1)	Mark Nudleman
berknet(1)	Eric Schmidt	mountd(8)	Herb Hasler
bib(1)	Dain Samples	mprof(1)	Ben Zorn
bib(1)	Gary M. Levin	msgs(1)	David Wasley
bib(1)	Timothy A. Budd	multicast	Stephen Deering
bitstring(3)	Paul Vixie	mv(1)	Ken Smith
boggle(6)	Barry Brachman	named/bind(8)	Douglas Terry
bpf(4)	Steven McCanne	named/bind(8)	Kevin Dunlap
btree(3)	Mike Olson	news(1)	Rick Adams (and a cast of thousands)
byte-range locking	Scooter Morris	nm(1)	Hans Huebner
caesar(6)	John Eldridge	pascal(1)	Kirk McKusick
caesar(6)	Stan King	pascal(1)	Peter Kessler
cal(1)	Kim Letkeman	paste(1)	Adam S. Moskowitz
cat(1)	Kevin Fall	patch(1)	Larry Wall
chess(6)	Stuart Cracraft (The FSF)	pax(1)	Keith Muller
ching(6)	Guy Harris	phantasia(6)	C. Robertson
cksum(1)	James W. Williams	phantasia(6)	Edward A. Estes
clri(8)	Rich $alz	ping(8)	Mike Muuss
col(1)	Michael Rendell	pom(6)	Keith E. Brandt
comm(1)	Case Larsen	pr(1)	Keith Muller
compact(1)	Colin L. McMaster	primes(6)	Landon Curt Noll
compress(1)	James A. Woods	qsort(3)	Doug McIlroy
compress(1)	Joseph Orost	qsort(3)	Earl Cohen
compress(1)	Spencer Thomas	qsort(3)	Jon Bentley
courier(1)	Eric Cooper	quad(3)	Chris Torek
cp(1)	David Hitz	quiz(6)	Jim R. Oldroyd
cpio(1)	AT&T	quiz(6)	Keith Gabryelski
crypt(3)	Tom Truscott	radixsort(3)	Dan Bernstein
csh(1)	Christos Zoulas	radixsort(3)	Peter McIlroy
csh(1)	Len Shar	rain(6)	Eric P. Scott
curses(3)	Elan Amir	ranlib(1)	Hugh A. Smith
curses(3)	Ken Arnold	rcs(1)	Walter F. Tichy
cut(1)	Adam S. Moskowitz	rdist(1)	Michael Cooper
cut(1)	Marciano Pitargue	regex(3)	Henry Spencer
dbx(1)	Mark Linton	robots(6)	Ken Arnold
dd(1)	Keith Muller	rogue(6)	Timothy C. Stoehr
dd(1)	Lance Visser	rs(1)	John Kunze
des(1)	Jim Gillogly	sail(6)	David Riggle
des(1)	Phil Karn	sail(6)	Edward Wang
des(1)	Richard Outerbridge	sccs(1)	Eric Allman
dipress(1)	Xerox Corporation	scsiformat(1)	Lawrence Berkeley Laboratory
disklabel(8)	Symmetric Computer Systems	sdb(1)	Howard Katseff
du(1)	Chris Newcomb	sed(1)	Diomidis Spinellis
dungeon(6)	R.M. Supnik	sendmail(8)	Eric Allman
ed(1)	Rodney Ruddock	setmode(3)	Dave Borman
emacs(1)	Richard Stallman	sh(1)	Kenneth Almquist
erf(3)	Peter McIlroy, K.C. Ng	slattach(8)	Rick Adams
error(1)	Robert R. Henry	slip(8)	Rick Adams
ex(1)	Mark Horton	spms(1)	Peter J. Nicklin
factor(6)	Landon Curt Noll	strtod(3)	David M. Gay
file(1)	Ian Darwin	swab(3)	Jeffrey Mogul
find(1)	Cimarron Taylor	sysconf(3)	Sean Eric Fagan
finger(1)	Tony Nardo	sysline(1)	J.K. Foderaro
fish(6)	Muffy Barkocy	syslog(3)	Eric Allman
fmt(1)	Kurt Schoens	systat(1)	Bill Reeves
fnmatch(3)	Guido van Rossum	systat(1)	Robert Elz
fold(1)	Kevin Ruddy	tail(1)	Edward Sze-Tyan Wang
fortune(6)	Ken Arnold	talk(1)	Clem Cole
fpr(1)	Robert Corbett	talk(1)	Kipp Hickman
fsdb(8)	Computer Consoles Inc.	talk(1)	Peter Moore
fsplit(1)	Asa Romberger	telnet(1)	Dave Borman
fsplit(1)	Jerry Berkman	telnet(1)	Paul Borman
gcc/groff integration	UUNET Technologies, Inc.	termcap(5)	John A. Kunze
gcore(1)	Eric Cooper	termcap(5)	Mark Horton
getcap(3)	Casey Leedom	test(1)	Kenneth Almquist
glob(3)	Guido van Rossum	tetris(6)	Chris Torek
gprof(1)	Peter Kessler	tetris(6)	Darren F. Provine
gprof(1)	Robert R. Henry	timed(8)	Riccardo Gusella
hack(6)	Andries Brouwer (and a cast of thousands)	timed(8)	Stefano Zatti
hangman(6)	Ken Arnold	tn3270(1)	Gregory Minshall
hash(3)	Margo Seltzer	tr(1)	Igor Belchinskiy
heapsort(3)	Elmer Yglesias	traceroute(8)	Van Jacobson
heapsort(3)	Kevin Lew	trek(6)	Eric Allman
heapsort(3)	Ronnie Kon	tset(1)	Eric Allman
hunt(6)	Conrad Huang	tsort(1)	Michael Rendell
hunt(6)	Greg Couch	unifdef(1)	Dave Yost
icon(1)	Bill Mitchell	uniq(1)	Case Larsen
icon(1)	Ralph Griswold	uucpd(8)	Rick Adams
indent(1)	David Willcox	uudecode(1)	Mark Horton
indent(1)	Eric Schmidt	uuencode(1)	Mark Horton
indent(1)	James Gosling	uuq(1)	Lou Salkind
indent(1)	Sun Microsystems	uuq(1)	Rick Adams
init(1)	Donn Seeley	uusnap(8)	Randy King
j0(3)	Sun Microsystems, Inc.	uusnap(8)	Rick Adams
j1(3)	Sun Microsystems, Inc.	vacation(1)	Eric Allman
jn(3)	Sun Microsystems, Inc.	vi(1)	Steve Kirkendall
join(1)	David Goodenough	which(1)	Peter Kessler
join(1)	Michiro Hikida	who(1)	Michael Fischbein
join(1)	Steve Hayman	window(1)	Edward Wang
jot(1)	John Kunze	worm(6)	Michael Toy
jove(1)	Jonathon Payne	worms(6)	Eric P. Scott
kermit(1)	Columbia University	write(1)	Craig Leres
kvm(3)	Peter Shipley	write(1)	Jef Poskanzer
kvm(3)	Steven McCanne	wump(6)	Dave Taylor
lam(1)	John Kunze	X25/Ethernet	Univ. of Erlangen-Nuremberg
larn(6)	Noah Morgan	X25/LLC2	Dirk Husemann
lastcomm(1)	Len Edmondson	xargs(1)	John B. Roll Jr.
lex(1)	Vern Paxson	xneko(6)	Masayuki Koba
libm(3)	Peter McIlroy	XNSrouted(1)	Bill Nesheim
libm(3)	UUNET Technologies, Inc.	xroach(6)	J.T. Anderson
locate(1)	James A. Woods	yacc(1)	Robert Paul Corbett
lock(1)	Bob Toxen
.TE
.\"
.\" END OF CONTRIB: Contrib ends here.
.\"
.if o .bp
\&
.bp
.nr PS 10
.nr VS 12
\&
.sp |1.5i
.LP
.ce
\fB\s+4PREFACE\s-4\fP
.sp 3
.NH 1
Introduction
.PP
The major new facilities available in the 4.4BSD release are
a new virtual memory system, 
the addition of ISO/OSI networking support,
a new virtual filesystem interface supporting filesystem stacking,
a freely redistributable implementation of NFS,
a log-structured filesystem,
enhancement of the local filesystems to support
files and filesystems that are up to 2^63 bytes in size,
enhanced security and system management support,
and the conversion to and addition of the IEEE Std1003.1 (``POSIX'')
facilities and many of the IEEE Std1003.2 facilities.
In addition, many new utilities and additions have been made to the C-library.
The kernel sources have been reorganized to collect all machine-dependent
files for each architecture under one directory,
and most of the machine-independent code is now free of code
conditional on specific machines.
The user structure and process structure have been reorganized
to eliminate the statically-mapped user structure and to make most
of the process resources shareable by multiple processes.
The system and include files have been converted to be compatible
with ANSI C, including function prototypes for most of the exported
functions.
There are numerous other changes throughout the system.
.NH 1
Changes in the Kernel
.PP
This release includes several important structural kernel changes.
The kernel uses a new internal system call convention;
the use of global (``u-dot'') variables for parameters and error returns
has been eliminated,
and interrupted system calls no longer abort using non-local goto's (longjmp's).
A new sleep interface separates signal handling from scheduling priority,
returning characteristic errors to abort or restart the current system call.
This sleep call also passes a string describing the process state,
which is used by the ps(1) program.
The old sleep interface can be used only for non-interruptible sleeps.
.PP
Many data structures that were previously statically allocated
are now allocated dynamically.
These structures include mount entries, file entries,
user open file descriptors, the process entries, the vnode table,
the name cache, and the quota structures.
.PP
The 4.4BSD distribution adds support for several new architectures including
SPARC-based Sparcstations 1 and 2,
MIPS-based Decstation 3100 and 5000 and Sony NEWS,
68000-based Hewlett-Packard 9000/300 and Omron Luna, and
386-based Personal Computers.
Both the HP300 and SPARC ports feature the ability to run binaries
built for the native operating system (HP-UX or SunOS) by emulating
their system calls.
Though this native operating system compatibility was provided by the
developers as needed for their purposes and is by no means complete,
it is complete enough to run several non-trivial applications including
those that require HP-UX or SunOS shared libraries.
For example, the vendor supplied X11 server and windowing environment
can be used on both the HP300 and SPARC.
.NH 2
Virtual memory changes
.PP
The new virtual memory implementation is derived from the MACH
operating system developed at Carnegie-Mellon,
and was ported to the BSD kernel at the University of Utah.
The MACH virtual memory system call interface has been replaced with the
``mmap''-based interface described in the ``Berkeley Software
Architecture Manual''.
The interface is similar to the interfaces shipped
by several commercial vendors such as Sun, USL, and Convex Computer Corp.
The integration of the new virtual memory is functionally complete,
but, like most MACH-based virtual memory systems,
still has serious performance problems under heavy memory load.
.NH 2
Networking additions and changes
.PP
The ISO/OSI Networking consists of a kernel implementation of
transport class 4 (TP-4),
connectionless networking protocol (CLNP),
and 802.3-based link-level support (hardware-compatible with Ethernet*).
.FS
*Ethernet is a trademark of the Xerox Corporation.
.FE
We also include support for ISO Connection-Oriented Network Service,
X.25, TP-0.
The session and presentation layers are provided outside
the kernel by the ISO development environment (ISODE).
Included in this development environment are file
transfer and management (FTAM), virtual terminals (VT),
a directory services implementation (X.500), and miscellaneous other utilities.
.PP
Several important enhancements have been added to the TCP/IP
protocols including TCP header prediction and
serial line IP (SLIP) with header compression.
The routing implementation has been completely rewritten
to use a hierarchical routing tree with a mask per route
to support the arbitrary levels of routing found in the ISO protocols.
The routing table also stores and caches route characteristics
to speed the adaptation of the throughput and congestion avoidance
algorithms.
.NH 2
Additions and changes to filesystems
.PP
The 4.4BSD distribution contains most of the interfaces
specified in the IEEE Std1003.1 system interface standard.
Filesystem additions include IEEE Std1003.1 FIFOs,
byte-range file locking, and saved user and group identifiers.
.PP
A new virtual filesystem interface has been added to the
kernel to support multiple filesystems.
In comparison with other interfaces,
the Berkeley interface has been structured for more efficient support
of filesystems that maintain state (such as the local filesystem).
The interface has been extended with support for stackable
filesystems done at UCLA.
These extensions allow for filesystems to be layered on top of each
other and allow new vnode operations to be added without requiring
changes to existing filesystem implementations.
For example, the umap filesystem
is used to mount a sub-tree of an existing filesystem
that uses a different set of uids and gids than the local system.
Such a filesystem could be mounted from a remote site via NFS or it
could be a filesystem on removable media brought from some foreign
location that uses a different password file.
.PP
In addition to the local ``fast filesystem'',
we have added an implementation of the network filesystem (NFS)
that fully interoperates with the NFS shipped by Sun and its licensees.
Because our NFS implementation was implemented using only the
publicly available NFS specification,
it does not require a license from Sun to use in source or binary form.
By default it runs over UDP to be compatible with Sun's implementation.
However, it can be configured on a per-mount basis to run over TCP.
Using TCP allows it to be used quickly and efficiently through
gateways and over long-haul networks.
Using an extended protocol, it supports Leases to allow a limited
callback mechanism that greatly reduces the network traffic necessary
to maintain cache consistency between the server and its clients.
.PP
A new log-structured filesystem has been added that provides
near disk-speed output and fast crash recovery.
It is still experimental in the 4.4BSD release,
so we do not recommend it for production use.
We have also added a memory-based filesystem that runs in
pageable memory, allowing large temporary filesystems without
requiring dedicated physical memory.
.PP
The local ``fast filesystem'' has been enhanced to do 
clustering which allows large pieces of files to be
allocated contiguously resulting in near doubling
of filesystem throughput.
The filesystem interface has been extended to allow
files and filesystems to grow to 2^63 bytes in size.
The quota system has been rewritten to support both
user and group quotas (simultaneously if desired).
Quota expiration is based on time rather than
the previous metric of number of logins over quota.
This change makes quotas more useful on fileservers
onto which users seldom login.
.PP
The system security has been greatly enhanced by the
addition of additional file flags that permit a file to be
marked as immutable or append only.
Once set, these flags can only be cleared by the super-user
when the system is running single user.
To protect against indiscriminate reading or writing of kernel
memory, all writing and most reading of kernel data structures
must be done using a new ``sysctl'' interface.
The information to be access is described through an extensible
``Management Information Base'' (MIB).
.NH 2
POSIX terminal driver changes
.PP
The biggest area of change is a new terminal driver.
The terminal driver is similar to the System V terminal driver
with the addition of the necessary extensions to get the
functionality previously available in the 4.3BSD terminal driver.
4.4BSD also adds the IEEE Std1003.1 job control interface,
which is similar to the 4.3BSD job control interface,
but adds a security model that was missing in the
4.3BSD job control implementation.
A new system call, \fIsetsid\fP,
creates a job-control session consisting of a single process
group with one member, the caller, that becomes a session leader.
Only a session leader may acquire a controlling terminal.
This is done explicitly via a \s-1TIOCSCTTY\s+1 \fIioctl\fP call,
not implicitly by an \fIopen\fP call.
The call fails if the terminal is in use.
.PP
For backward compatibility,
both the old \fIioctl\fP
calls and old options to \fIstty\fP
are emulated.
.NH 1
Changes to the utilities
.PP
There are several new tools and utilities included in this release.
A new version of ``make'' allows much-simplified makefiles for the
system software and allows compilation for multiple architectures
from the same source tree (which may be mounted read-only).
Notable additions to the libraries include functions to traverse a
filesystem hierarchy, database interfaces to btree and hashing functions,
a new, fast implementation of stdio and a radix sort function.
The additions to the utility suite include greatly enhanced versions of
programs that display system status information, implementations of
various traditional tools described in the IEEE Std1003.2 standard,
and many others.
.PP
We have been tracking the IEEE Std1003.2 shell and utility work
and have included prototypes of many of the proposed utilities.
Most of the traditional utilities have been replaced
with implementations conformant to the POSIX standards.
Almost the entire manual suite has been rewritten to
reflect the POSIX defined interfaces.
In rewriting this software, we have generally
been rewarded with significant performance improvements.
Most of the libraries and header files have been converted
to be compliant with ANSI C.
The system libraries and utilities all compile
with either ANSI or traditional C.
.PP
The Kerberos (version 4) authentication software has been
integrated into much of the system (including NFS) to provide
the first real network authentication on BSD.
.PP
A new implementation of the \fIex/vi\fP text editors is available
in this release.
It is intended as a bug-for-bug compatible version of the editors.
It also has a few new features: 8-bit clean data, lines and files
limited only by memory and disk space, split screens, tags stacks
and left-right scrolling among them.
\fINex/nvi\fP
is not yet production quality; future versions of this software may
be retrieved by anonymous ftp from ftp.cs.berkeley.edu, in the
directory ucb/4bsd.
.PP
The \fIfind\fP
utility has two new options that are important to be aware of if you
intend to use NFS.
The ``fstype'' and ``prune'' options can be used together to prevent
find from crossing NFS mount points.
.NH 2
Additions and changes to the libraries
.PP
The \fIcurses\fP
library has been largely rewritten.
Important additional features include support
for scrolling and \fItermios\fP.
.PP
An application front-end editing library, named libedit, has been
added to the system.
.PP
A superset implementation of the SunOS kernel memory interface library,
\fIlibkvm\fP, has been integrated into the system.
.PP
Nearly the entire C-library has been rewritten.
Some highlights of the changes to the 4.4BSD C-library:
.IP \(bu
The newly added \fIfts\fP
functions will do either physical or logical traversal of
a file hierarchy as well as handle essentially infinite depth
filesystems and filesystems with cycles.
All the utilities in 4.4BSD that traverse file hierarchies
have been converted to use \fIfts\fP.
The conversion has always resulted in a significant performance
gain, often of four or five to one in system time.
.IP \(bu
The newly added \fIdbopen\fP
functions are intended to be a family of database access methods.
Currently, they consist of \fIhash\fP,
an extensible, dynamic hashing scheme,
\fIbtree\fP, a sorted, balanced tree structure (B+tree's), and
\fIrecno\fP, a flat-file interface for fixed or variable length records
referenced by logical record number.
Each of the access methods stores associated key/data pairs and
uses the same record oriented interface for access.
Future versions of this software may be retrieved by anonymous ftp
from ftp.cs.berkeley.edu, in the directory ucb/4bsd.
.IP \(bu
The \fIqsort\fP
function has been rewritten for additional performance.
In addition, three new types of sorting functions,
\fIheapsort\fP, \fImergesort\fP, and \fIradixsort\fP
have been added to the system.
The \fImergesort\fP
function is optimized for data with pre-existing order,
in which case it usually significantly outperforms \fIqsort\fP.
The \fIradixsort\fP
functions are variants of most-significant-byte radix sorting.
They take time linear to the number of bytes to be
sorted, usually significantly outperforming \fIqsort\fP
on data that can be sorted in this fashion.
An implementation of the POSIX 1003.2 standard \fIsort\fP
based on \fIradixsort\fP is included in 4.4BSD.
.IP \(bu
The floating point support in the C-library has been replaced
and is now accurate.
.IP \(bu
The C functions specified by both ANSI C, POSIX 1003.1 and
1003.2 are now part of the C-library.
This includes support for file name matching, shell globbing
and both basic and extended regular expressions.
.IP \(bu
ANSI C multibyte and wide character support has been integrated.
The rune functionality from the Bell Labs' Plan 9 system is provided
as well.
.IP \(bu
The \fItermcap\fP
functions have been generalized and replaced with a general
purpose interface named \fIgetcap\fP.
.IP \(bu
The \fIstdio\fP
routines have been replaced, and are usually much faster.
In addition, the \fIfunopen\fP
interface permits applications to provide their own I/O stream
function support.
.NH 1
Acknowledgements
.PP
We were greatly assisted by the past employees of the Computer Systems
Research Group: Mike Karels, Keith Sklower, and Marc Tietelbaum.
Our distribution coordinator, Pauline Schwartz, has reliably managed
the finances and the mechanics of shipping distributions for
nearly the entire fourteen years of the group's existence.
Without the help of lawyers Mary MacDonald, Joel Linzner,
and Carla Shapiro, the 4.4BSD-Lite distribution would never
have seen the light of day.
Much help was provided by Chris Demetriou in getting bug fixes
from NetBSD integrated back into the 4.4BSD-Lite distribution.
.PP
The vast majority of the 4.4BSD distribution comes from the numerous
people in the UNIX community that provided their time and energy in
creating the software contained in this release.
We dedicate this distribution to them.
.sp 1
.in 4i
.nf
M. K. McKusick
K. Bostic
.fi
.in 0
.sp 3
.nr PS 9
.nr VS 10
.LP
.ne 1i
.ce
\fIPreface to the 4.3 Berkeley distribution\fP
.sp 1
.LP
This update to the 4.2 distribution of August 1983 provides
substantially improved performance, reliability, and security,
the addition of Xerox Network System (NS) to the set of networking domains,
and partial support for the VAX 8600 and MICROVAXII.
.LP
We were greatly assisted by the DEC UNIX Engineering group who
provided two full time employees, Miriam Amos and Kevin Dunlap,
to work at Berkeley. They were responsible for developing and
debugging the distributed domain based name server
and integrating it into the mail system.
Mt Xinu provided the bug list distribution service as well as
donating their MICROVAXII port to 4.3BSD.
Drivers for the MICROVAXII were done by Rick Macklem
at the University of Guelph.
Sam Leffler provided valuable assistance and advice with many projects.
Keith Sklower coordinated with William Nesheim and J. Q. Johnson at Cornell, 
and Chris Torek and James O'Toole at the University of Maryland
to do the Xerox Network Systems implementation.
Robert Elz at the University of Melbourne contributed greatly
to the performance work in the kernel.
Donn Seeley and Jay Lepreau at the University of Utah
relentlessly dealt with a myriad of details;
Donn completed the unfinished performance work on Fortran 77
and fixed numerous C compiler bugs.
Ralph Campbell handled innumerable questions and problem reports
and had time left to write rdist.
George Goble was invaluable in shaking out the bugs on his
production systems long before we were confident enough to
inflict it on our users.
Bill Shannon at Sun Microsystems has been helpful in 
providing us with bug fixes and improvements.
Tom Ferrin, in his capacity as Board Member of Usenix Association,
handled the logistics of large-scale reproduction
of the 4.2BSD and 4.3BSD manuals.
Mark Seiden helped with the typesetting and indexing of the 4.3BSD manuals.
Special mention goes to Bob Henry for keeping ucbvax running
in spite of new and improved software and
an ever increasing mail, news, and uucp load.
.LP
Numerous others contributed their time and energy in creating
the user contributed software for the release.
As always, we are grateful to the UNIX user community for 
encouragement and support. 
.LP
Once again, the financial support of the Defense Advanced Research
Projects Agency is gratefully acknowledged.
.sp 1
.in 4i
.nf
M. K. McKusick
M. J. Karels
J. M. Bloom
.fi
.in 0
.sp 2
.ne 2i
.ce
\fIPreface to the 4.2 Berkeley distribution\fP
.sp 1
This update to the 4.1 distribution of June 1981 provides support
for the VAX 11/730, full networking and interprocess communication
support, an entirely new file system, and many other new features.
It is certainly the most ambitious release of software ever prepared
here and represents many man-years of work.
Bill Shannon (both at DEC and at Sun Microsystems)
and Robert Elz of the University
of Melbourne contributed greatly to this distribution
through new device drivers and painful debugging episodes.
Rob Gurwitz of BBN wrote the initial version of the code upon
which the current networking support is based.
Eric Allman of Britton-Lee donated countless hours to the mail system.
Bill Croft (both at SRI and Sun Microsystems) aided in the
debugging and development of the networking facilities.
Dennis Ritchie of Bell Laboratories also
contributed greatly to this distribution, providing
valuable advise and guidance.  Helge Skrivervik
worked on the device drivers which enabled
the distribution to be delivered with a TU58
console cassette and RX01 console flopppy disk, and
rewrote major portions of the standalone i/o system
to support formatting of non-DEC peripherals.
.LP
Numerous others contributed their time and energy in organizing
the user software for release, while many groups of people on
campus suffered patiently through the low spots of development.
As always, we are grateful to the UNIX user community for 
encouragement and support. 
.LP
Once again, the financial support of the Defense Advanced Research
Projects Agency is gratefully acknowledged.
.sp 1
.in 4i
.nf
S. J. Leffler
W. N. Joy
M. K. McKusick
.fi
.in 0
.sp 2
.ne 1i
.ce
\fIPreface to the 4.1 Berkeley distribution\fP
.sp 1
This update to the fourth distribution of November 1980 provides
support for the VAX 11/750 and for the full interconnect architecture
of the VAX 11/780.  Robert Elz of the University of Melbourne contributed
greatly to this distribution especially in the boot-time system
configuration code;  Bill Shannon of DEC supplied us with the
implementation of DEC standard bad block handling.  The research
group at Bell Laboratories and DEC Merrimack provided us with access
to 11/750's in order to debug its support.
.LP
Other individuals too numerous to mention provided us with bug reports,
fixes and other enhancements which are reflected in the system.  We
are grateful to the UNIX user community for encouragement and
support.
.LP
The financial support of the Defence Advanced Research Projects Agency
in support of this work is gratefully acknowledged.
.sp 1
.in 4i
.nf
W. N. Joy
R. S. Fabry
K. Sklower
.fi
.in 0
.sp 2
.ne 1i
.ce
\fIPreface to the Fourth Berkeley distribution\fP
.sp 1
This manual reflects the Berkeley system mid-October, 1980.
A large amount of tuning has been done in the system since the last release;
we hope this provides as noticeable an improvement for you as it did for us.
This release finds the system in transition; a number of facilities
have been added in experimental versions (job control, resource limits)
and the implementation of others is imminent (shared-segments, higher
performance from the file system, etc.).
Applications which use facilities that are in transition should be aware
that some of the system calls and library routines will change
in the near future.  We have tried to be conscientious and make it
very clear where this is likely.
.LP
A new group has been formed
at Berkeley, to assume responsibility for the future
development and support of a version of UNIX on the VAX.
The group has received funding from the
Defense Advanced Research Projects Agency (DARPA)
to supply a standard version of the system to DARPA contractors.
The same version of the system will be made available to other licensees
of UNIX on the VAX for a duplication charge.
We gratefully acknowledge
the support of this contract.
.LP
We wish to acknowledge the contribution of a number of individuals to
the the system.
.LP
We would especially like to thank
Jim Kulp of IIASA,
Laxenburg Austria and his colleagues,
who first put job control facilities into UNIX;
Eric Allman, Robert Henry, Peter Kessler and Kirk McKusick, who
contributed major new pieces of software;
Mark Horton, who contributed to the improvement of facilities and
substantially improved the quality of our bit-mapped fonts,
our hardware support staff:
Bob Kridle,
Anita Hirsch,
Len Edmondson
and
Fred Archibald,
who helped us to debug a number of new peripherals;
Ken Arnold who did much of the leg-work in getting this version of the
manual prepared, and did the final editing of sections 2-6,
some special individuals within Bell Laboratories:
Greg Chesson,
Stuart Feldman,
Dick Haight,
Howard Katseff,
Brian Kernighan,
Tom London,
John Reiser,
Dennis Ritchie,
Ken Thompson,
and
Peter Weinberger
who helped out by answering questions;
our excellent local DEC field service people,
Kevin Althaus and Frank Chargois
who kept our machine running virtually all the time, and fixed it quickly
when things broke;
and,
Mike Accetta of Carnegie-Mellon University,
Robert Elz of the University of Melbourne,
George Goble of Purdue University,
and
David Kashtan of the Stanford Research Institute
for their technical advice and support.
.LP
Special thanks to Bill Munson of DEC who helped by augmenting
our computing facility
and to Eric Allman for carefully proofreading the
``last'' draft of the manual and finding the bugs which we knew were
there but couldn't see. 
.LP
We dedicate this to the memory of David Sakrison, late chairman of our
department, who gave his support to the establishment of our VAX
computing facility, and to our department as a whole.
.sp 1
.in 4i
.nf
W. N. Joy
\v'-3p'\h'2p'\*:\v'3p'\h'-2p'O. Babao\*~glu
R. S. Fabry
K. Sklower
.fi
.in 0
.sp 2
.ne 1i
.ce
\fIPreface to the Third Berkeley distribution\fP
.sp 1
This manual reflects the state of the Berkeley system, December 1979.
We would like to thank all the people at Berkeley who have contributed to
the system, and particularly thank
Prof. Richard Fateman for creating and administrating a hospitable environment,
Mark Horton who helped prepare this manual, and
Eric Allman, Bob Kridle, Juan Porcar
and Richard Tuck for their contributions to the kernel.
.LP
The cooperation of Bell Laboratories in providing us with an early version of
\s-2UNIX\s0/32V is greatly appreciated.  We would especially like to thank
Dr. Charles Roberts of Bell Laboratories for helping us obtain this release,
and acknowledge
T. B. London,
J. F. Reiser,
K. Thompson,
D. M. Ritchie,
G. Chesson and
H. P. Katseff
for their advice and support.
.sp 1
.in 4i
W. N. Joy
.br
\v'-3p'\h'2p'\*:\v'3p'\h'-2p'O. Babao\*~glu
.in 0
.sp 2
.ne 1i
.ce
\fIPreface to the UNIX/32V distribution\fP
.sp 1
The
.UX
operating system for the VAX*-11
.FS
*VAX and PDP are Trademarks of Digital Equipment Corporation.
.FE
provides substantially the same facilities as the
\s-2UNIX\s0
system for the PDP*-11.
.LP
We acknowledge the work of many who came before us, and particularly thank
G. K. Swanson, W. M. Cardoza, D. K. Sharma, and J. F. Jarvis for assistance
with the implementation for the VAX-11/780.
.sp 1
.in 4i
T. B. London
.br
J. F. Reiser
.in 0
.sp 2
.ne 1i
.ce
\fIPreface to the Seventh Edition\fP
.sp 1
.LP
Although this Seventh Edition no longer bears their byline,
Ken Thompson and Dennis Ritchie remain the fathers
and preceptors of the
\s-2UNIX\s0
time-sharing system.
Many of the improvements here described bear their mark.
Among many, many other people who have contributed to
the further flowering of
\s-2UNIX\s0,
we wish especially to
acknowledge the contributions of
A. V. Aho,
S. R. Bourne,
L. L. Cherry,
G. L. Chesson,
S. I. Feldman,
C. B. Haley,
R. C. Haight,
S. C. Johnson,
M. E. Lesk,
T. L. Lyon,
L. E. McMahon,
R. Morris,
R. Muha,
D. A. Nowitz,
L. Wehr,
and
P. J. Weinberger.
We appreciate also 
the effective advice and criticism of
T. A. Dolotta,
A. G. Fraser,
J. F. Maranzano,
and
J. R. Mashey;
and we remember the important work of
the late Joseph F. Ossanna.
.sp 1
.in 4i
B. W. Kernighan
.br
M. D. McIlroy
.in 0
.if o .bp
\&
.bp
.de IR
\fI\\$1\^\fR\\$2
..
.de RI
\fR\\$1\fI\\$2\^\fR\\$3
..
.ce
\fB\s+4INTRODUCTION\s-4\fP
.sp 1
.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 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 that
exist only to exercise a particular system call.
Finally, there is a list of documents on the inside back cover of each volume.
.SH
HOW TO GET STARTED
.LP
This section sketches the basic information you need to get started on \s-1UNIX\s+1;
how to log in and log out, how to communicate through your terminal,
and how to run a program.
See ``\s-1UNIX\s+1 for Beginners'' in (USD:1) for a
more complete introduction to the system.
.LP
.I
Logging in.\ \ 
.R
Almost any ASCII terminal capable of
full duplex operation and generating
the entire character set can be used.
You must have a valid user name,
which may be obtained from the system administration.
If you will be accessing \s-1UNIX\s+1 remotely, you will also
need to obtain the telephone number for the system that you will be using.
.LP
After a data connection is established,
the login procedure depends on what type of terminal you are using
and local system conventions.
If your terminal is directly connected to the computer,
it generally runs at 9600 or 19200 baud.
If you are using a modem running over a phone line,
the terminal must be set at the speed appropriate for the modem you are using,
typically 1200, 2400, or 9600 baud.
The half/full duplex switch should always be set at full-duplex.
(This switch will often have to be changed
since many other systems require half-duplex).
.LP
When a connection is established, the system types ``login:'';
you type your user name, followed by the ``return'' key.
If you have a password, the system asks for it
and suppresses echo to the terminal so the password will not appear.
After you have logged in, the ``return'', ``new line'', or ``linefeed'' keys
will give exactly the same results.
A message-of-the-day usually greets you before your first prompt.
.LP
If the system types out a few garbage characters
after you have established a data connection
(the ``login:'' message at the wrong speed),
depress the ``break'' (or ``interrupt'') key.
This is a speed-independent signal to \s-1UNIX\s+1
that a different speed terminal is in use.
The system then will type ``login:,'' this time at another speed.
Continue depressing the break key until ``login:'' appears clearly,
then respond with your user name.
.LP
For all these terminals, it is important
that you type your name in lower-case if possible; if you type
upper-case letters,
\s-1UNIX\s+1 will assume that your terminal cannot generate lower-case
letters and will translate all subsequent lower-case letters to upper case.
.LP
The evidence that you have successfully logged in is that a shell program
will type a prompt (``$'' or ``%'') to you.
(The shells are described below under ``How to run a program.'')
.LP
For more information, consult
.IR tset (1),
and
.IR stty (1),
which tell how to adjust terminal behavior;
.IR getty (8)
discusses the login sequence in more detail, and
.IR tty (4)
discusses terminal I/O.
.LP
.I
Logging out.\ \ 
.R
There are three ways to log out:
.IP
By typing ``logout'' or an end-of-file
indication (EOT character, control-D) to the shell.
The shell will terminate and the ``login:'' message will appear again.
.IP
You can log in directly as another user by giving a
.IR login (1)
command.
.IP
If worse comes to worse,
you can simply hang up the phone; but beware \- some machines may
lack the necessary hardware to detect that the phone has been hung up.
Ask your system administrator if this is a problem on your machine.
.LP
.I
How to communicate through your terminal.\ \ 
.R
When you type characters, a gnome deep in the system
gathers your characters and saves them in a secret place.
The characters will not be given to a program
until you type a return (or newline), as described above in
.I
Logging in.
.R
.LP
\s-1UNIX\s+1 terminal I/O is full-duplex.
It has full read-ahead, which means that you can type at any time,
even while a program is typing at you.
Of course, if you type during output, the printed output will
have the input characters interspersed.
However, whatever you type will be saved up and interpreted in correct sequence.
There is a limit to the amount of read-ahead,
but it is generous and not likely to be exceeded unless
the system is in trouble.
When the read-ahead limit is exceeded, the system
throws away all the saved characters (or beeps, if your prompt was a ``%'').
.LP
The ^U (control-U) character in typed input kills all the
preceding characters in the line,
so typing mistakes can be repaired on a single line.
Also, the delete character (DEL) or sometimes the
backspace character (control-H) erases the last character typed.
.IR Tset (1)
or
.IR stty (1)
can be used to change these defaults.
Successive uses of delete (or backspace) erases characters back to, but
not beyond, the beginning of the line.
DEL and ^U (control-U) can be transmitted to a program by preceding them with
^V (control-V).
(So, to erase ^V (control-V), you need two deletes or backspaces).
.LP
An
.I
interrupt signal
.R
is sent to a program by typing ^C (control-C) or the ``break'' key
which is not passed to programs.
This signal generally causes whatever program you are running to terminate.
It is typically used to stop a long printout that you do not want.
However, programs can arrange either to ignore this signal altogether,
or to be notified when it happens (instead of being terminated).
The editor, for example, catches interrupts and stops what it is doing,
instead of terminating, so that an interrupt can
be used to halt an editor printout without losing the file being edited.
The interrupt character can also be changed with
.IR tset (1)
or
.IR stty (1).
.LP
It is also possible to suspend output temporarily using ^S (control-S)
and later resume output with ^Q (control-Q).
Output can be thrown away without interrupting
the program by typing ^O (control-O); see
.IR tty (4).
.LP
The
.IR quit ""
signal is generated by typing the \s8ASCII\s10 FS character.
(FS appears many places on different terminals, most commonly
as control-\e or control-\^|\^.)
It not only causes a running program to terminate
but also generates a file with the core image of the terminated process.
Quit is useful for debugging.
.LP
Besides adapting to the speed of the terminal,
\s-1UNIX\s+1 tries to be intelligent about whether
you have a terminal with the newline function
or whether it must be simulated with carriage-return and line-feed.
In the latter case, all input carriage returns
are turned to newline characters (the standard line delimiter)
and both a carriage return and a line feed are echoed to the terminal.
If you get into the wrong mode, the
.IR reset (1)
command will rescue you.
If the terminal does not appear to be echoing anything that you type,
it may be stuck in ``no-echo'' or ``raw'' mode.
Try typing ``(control-J)reset(control-J)'' to recover.
.LP
Tab characters are used freely in \s-1UNIX\s+1 source programs.
If your terminal does not have the tab function,
you can arrange to have them turned into spaces
during output, and echoed as spaces during input.
The system assumes that tabs are set every eight columns.
Again, the
.IR tset (1)
or
.IR stty (1)
command can be used to change these defaults.
.IR Tset (1)
can be used to set the tab stops automatically when necessary.
.LP
.I
How to run a program; the shells.\ \ 
.R
When you have successfully logged in, a program
called a shell is listening to your terminal.
The shell reads typed-in lines, splits them up
into a command name and arguments, and executes the command.
A command is simply an executable program.
The shell looks in several system directories to find the command.
You can also place commands in your own directory and
have the shell find them there.
There is nothing special about system-provided
commands except that they are kept in a directory where the shell can find them.
.LP
The command name is always the first word on an input line;
it and its arguments are separated from one another by spaces.
.LP
When a program terminates, the shell will ordinarily regain control and type 
a prompt at you to show that it is ready for another command.
.LP
The shells have many other capabilities, that are described in detail in
sections
.IR sh (1)
and
.IR csh (1).
If the shell prompts you with ``$'', then it is an instance of
.IR sh (1),
the original \s-1UNIX\s+1 shell.
If it prompts with ``%'' then it is an instance of
.IR csh (1),
a shell written at Berkeley.
The shells are different for all but the most simple terminal usage.
Most users at Berkeley choose
.IR csh (1)
because of the
.I history
mechanism and the
.I alias
feature, that greatly enhance its power when used interactively.
.I Csh
also supports the job-control facilities;
see
.IR csh (1)
or the Csh introduction in USD:4 for details.
.LP
You can change from one shell to the other by using the
.I chpass (1)
command, which takes effect at your next login.
.LP
.I
The current directory.\ \ 
.R
\s-1UNIX\s+1 has a file system arranged as a hierarchy of directories.
When the system administrator gave you a user name,
they also created a directory for you (ordinarily
with the same name as your user name).
When you log in, any file name you type is by default in this directory.
Since you are the owner of this directory, you have
full permission to read, write, alter, or destroy its contents.
Permissions to have your will with other directories
and files will have been granted or denied to you by their owners.
As a matter of observed fact, few \s-1UNIX\s+1
users protect their files from perusal by other users.
.LP
To change the current directory (but not the set of permissions you
were endowed with at login) use
.IR cd (1).
.LP
.I
Path names.\ \ 
.R
To refer to files not in the current directory, you must use a path name.
Full path names begin with ``/\|'', the name of the root directory of the
whole file system.
After the slash comes the name of each directory containing the next
sub-directory (followed by a ``/\|'') until finally the file name is reached.
For example,
.I
/\^var/\^tmp/\^filex
.R
refers to the file
.I
filex
.R
in the directory
.I
tmp; tmp
.R
is itself a subdirectory of
.I
var; var
.R
springs directly from the root directory.
.LP
If your current directory has subdirectories,
the path names of files therein begin with
the name of the subdirectory with no prefixed ``/\|''.
.LP
A path name may be used anywhere a file name is required.
.LP
Important commands that modify the contents of files are
.IR cp (1),
.IR mv (1),
and
.IR rm (1),
which respectively copy, move (i.e. rename) and remove files.
To find out the status of files or directories, use 
.IR ls (1).
See
.IR mkdir (1)
for making directories and
.IR rmdir (1)
for destroying them.
.LP
For a fuller discussion of the file system, see
``A Fast File System for \s-1UNIX\s+1'' (SMM:5)
by McKusick, Joy, Leffler, and Fabry.
It may also be useful to glance through PRM section 2,
that discusses system calls, even if you do not intend
to deal with the system at that level.
.LP
.I
Writing a program.\ \ 
.R
To enter the text of a source program into a \s-1UNIX\s+1 file,
use the standard display editor
.IR vi (1)
or its \s-1WYSIWYG\s+1 counterparts
.IR jove (1)
and
.IR emacs (1).
(The old standard editor
.IR ed (1)
is also available.)
The principle language in \s-1UNIX\s+1 is provided by the C compiler
.IR cc (1).
User contributed software in the latest
release of the system supports the programming languages perl and C++.
After the program text has been entered through the editor
and written to a file, you can give the file
to the appropriate language processor as an argument.
The output of the language processor
will be left on a file in the current directory named ``a.out''.
If the output is precious, use
.IR mv (1)
to move it to a less exposed name after successful compilation.
.LP
When you have finally gone through this entire process
without provoking any diagnostics, the resulting program
can be run by giving its name to the shell
in response to the shell (``$'' or ``%'') prompt.
.LP
Your programs can receive arguments from the command line
just as system programs do,
see ``\s-1UNIX\s+1 Programming - Second Edition'' (PSD:4),
or for a more terse description
.IR execve (2).
.LP
.I
Text processing.\ \ 
.R
Almost all text is entered through an editor such as
.IR vi (1),
.IR jove (1),
or
.IR emacs (1).
The commands most often used to write text on a terminal are:
.IR cat (1),
.IR more (1),
and
.IR nroff (1).
.LP
The
.IR cat (1)
command simply dumps \s8ASCII\s10 text
on the terminal, with no processing at all.
.IR More (1)
is useful for preventing the output of a command from
scrolling off the top of your screen.
It is also well suited to perusing files.
.IR Nroff (1)
is an elaborate text formatting program.
Used naked, it requires careful forethought, but for
ordinary documents it has been tamed; see
.IR me (7)
and
.IR ms (7).
.LP
.IR Groff (1)
converts documents to postscript for output to a
Laserwriter or Phototypesetter.
It is similar to 
.IR nroff (1),
and often works from exactly the same source text.
It was used to produce this manual.
.LP
.IR Script (1)
lets you keep a record of your session in a file,
which can then be printed, mailed, etc.
It provides the advantages of a hard-copy terminal
even when using a display terminal.
.LP
.I
Status inquiries.\ \ 
.R
Various commands exist to provide you with useful information.
.IR w (1)
prints a list of users currently logged in, and what they are doing.
.IR date (1)
prints the current time and date.
.IR ls (1)
will list the files in your directory or give
summary information about particular files.
.LP
.I
Surprises.\ \ 
.R
Certain commands provide inter-user communication.
Even if you do not plan to use them, it would be
well to learn something about them, because someone else may aim them at you.
.LP
To communicate with another user currently logged in,
.IR write (1)
or
.IR talk (1)
is used;
.IR mail (1)
will leave a message whose presence will be announced
to another user when they next log in.
The write-ups in the manual also suggest how to respond to
the these commands if you are a target.
.LP
If you use
.IR csh (1)
the key ^Z (control-Z) will cause jobs to ``stop''.
If this happens before you learn about it,
you can simply continue by saying ``fg'' (for foreground) to bring
the job back.
.LP
We hope that you will come to enjoy using the BSD system.
Although it is very large and contains many commands,
you can become very productive using only a small subset of them.
As your needs expand to doing new tasks,
you will almost always find that the system has the facilities
that you need to accomplish them easily and quickly.
.LP
Most importantly, the source code to the BSD system
is cheaply available to anyone that wants it.
On many BSD systems, it can be found in the directory
.IR /\|usr/\|src .
You may simply want to find out how something works
or fix some important bug without waiting months for
your vendor to respond.
It is also particularly useful if you
want to grab another piece of code to bootstrap a new project.
Provided that you retain the copyrights and acknowledgements
at the top of each file, you are free to redistribute your
work for fun or profit.
Naturally, we hope that you will allow others to also redistribute
your code, though you are not required to do so unless you
use copyleft code (which is primarily found in the software
contributed from the Free Software Foundation and is
clearly identified).
.LP
Good luck and enjoy BSD.
.OH '''\s10- % -\s0'
.EH '\s10- % -\s0'''
.if o .bp
\&
.bp
.EF '\s9\\\\*(Dt''\\\\*(Ed\s0'
.OF '\s9\\\\*(Ed''\\\\*(Dt\s0'
.ce
\s+4\fBLIST \|OF \|MANUAL \|PAGES\fP\s-4
.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
\f3\s9\\$2. \\$3\s0\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
\&
.bp
\&
.OH '\s9\fIPermuted Index\fP''- % -\s0'
.EH '\s9- % -''\fIPermuted Index\fP\s0'
.ds Ed 4.4BSD
.ds Dt June \|1993
.ce
\s+4\fBPERMUTED \|INDEX\fP\s-4
.sp 1
.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\\$2\ 2 .ds s1 ~~\"
.ds s2 ~~~\"
.ds s3\"
.if \w\ 2\\$4\ 2 .ds s3 ~~\"
.ds s4 ~~\"
.ds s5 ~~\"
.ds y \\*(s4\f3\ 1\fP\\*(s5
.ta 6i-\w\ 2\\*(s5\ 2u
\h"3i-\w\ 2\\$1\\*(s1\\$2\\*(s2\ 2u"\\$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