| blob | 1655df6c3e74bb7e5c9db80ef2e601c91a3324ff |
1 .\" $NetBSD: Title,v 1.2 1998/01/09 06:54:38 perry Exp $
2 .\"
3 .\" Copyright (c) 1986, 1993, 1994 The Regents of the University of California.
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)Title 8.4 (Berkeley) 8/8/94
31 .\"
32 .af % i
33 .nr LL 6.5i
34 .EH ''''
35 .OH ''''
36 .EF ''''
37 .OF ''''
38 \&
39 .sp |1.5i
40 .nr PS 36
41 .nr VS 39
42 .LP
43 .ft B
44 .ce 3
45 4.4BSD
46 Programmer's
47 Supplementary Documents
48 .nr PS 24
49 .nr VS 32
50 .LP
51 .ft B
52 .ce 1
53 (PSD)
54 .bp
55 \&
56 .sp |0.83i
57 .nr PS 14
58 .nr VS 16.5
59 .LP
60 Now in its twentieth year, the USENIX Association,
61 the UNIX and Advanced Computing Systems professional and technical organization,
62 is a not-for-profit membership association of individuals and
63 institutions with an interest in UNIX and UNIX-like systems,
64 and, by extension, C++, X windows, and other advanced tools and technologies.
65 .LP
66 USENIX and its members are dedicated to:
67 .IP \(bu
68 fostering innovation and communicating research and technological developments,
69 .IP \(bu
70 sharing ideas and experience relevant to UNIX,
71 UNIX-related, and advanced computing systems, and
72 .IP \(bu
73 providing a neutral forum for the exercise of critical
74 thought and airing of technical issues.
75 .LP
76 USENIX publishes a journal (\fBComputing Systems\fP),
77 a newsletter (\fI;login:\fP),
78 Proceedings from its frequent Conferences and Symposia,
79 and a Book Series.
80 .LP
81 SAGE, The Systems Administrators Guild, a Special Technical Group with
82 the USENIX Association, is dedicated to the advancement of system
83 administration as a profession.
84 .LP
85 SAGE brings together systems managers and administrators to:
86 .IP \(bu
87 propagate knowledge of good professional practice,
88 .IP \(bu
89 recruit talented individuals to the profession,
90 .IP \(bu
91 recognize individuals who attain professional excellence,
92 .IP \(bu
93 foster technical development and share solutions to technical
94 problems, and
95 .IP \(bu
96 communicate in an organized voice with users, management, and vendors
97 on system administration topics.
98 .bp
99 \&
100 .sp |1i
101 .nr PS 36
102 .nr VS 39
103 .LP
104 .ft B
105 .ce 3
106 4.4BSD
107 Programmer's
108 Supplementary Documents
109 .nr PS 24
110 .nr VS 32
111 .LP
112 .ft B
113 .ce 1
114 (PSD)
115 .sp 1i
116 .nr PS 24
117 .nr VS 26
118 .LP
119 .ft B
120 .ce 1
121 Berkeley Software Distribution
122 .nr PS 18
123 .nr VS 26
124 .LP
125 .ft B
126 .ce 1
127 April, 1994
128 .sp 1i
129 .nr PS 18
130 .nr VS 20
131 .LP
132 .ft B
133 .ce 2
134 Computer Systems Research Group
135 University of California at Berkeley
136 .sp 2.25i
137 .nr PS 12
138 .nr VS 14.5
139 .LP
140 .ft B
141 .ce 4
142 A USENIX Association Book
143 O'Reilly & Associates, Inc.
144 103 Morris Street, Suite A
145 Sebastopol, CA 94572
146 .bp
147 .hy 0
148 .nr PS 9
149 .nr VS 11
150 .LP
151 First Printing, 1994
152 .br
153 Second Printing, 1995
154 .sp 1.6
155 .LP
156 Copyright 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
157 The Regents of the University of California. All rights reserved.
158 .sp 1.6
159 .LP
160 Other than the specific manual pages and documents listed below
161 as copyrighted by AT&T,
162 redistribution and use of this manual in source and binary forms,
163 with or without modification, are permitted provided that the
164 following conditions are met:
165 .IP 1)
166 Redistributions of this manual must retain the copyright
167 notices on this page, this list of conditions and the following disclaimer.
168 .IP 2)
169 Software or documentation that incorporates part of this manual must
170 reproduce the copyright notices on this page, this list of conditions and
171 the following disclaimer in the documentation and/or other materials
172 provided with the distribution.
173 .IP 3)
174 All advertising materials mentioning features or use of this software
175 must display the following acknowledgement:
176 ``This product includes software developed by the University of
177 California, Berkeley and its contributors.''
178 .IP 4)
179 Neither the name of the University nor the names of its contributors
180 may be used to endorse or promote products derived from this software
181 without specific prior written permission.
182 .LP
183 \fB\s-1THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
184 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
185 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
186 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
187 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
188 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
189 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
190 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
191 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
192 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
193 SUCH DAMAGE.\s+1\fP
194 .sp 1.6
195 .LP
196 Documents PSD:1, 2, 3, 4, 6, 11, 15, 16, and 17
197 are copyright 1979, AT&T Bell Laboratories, Incorporated.
198 Document PSD:8 is a modification of an earlier document that
199 is copyrighted 1979 by AT&T Bell Laboratories, Incorporated.
200 Holders of \x'-1p'UNIX\v'-4p'\s-3TM\s0\v'4p'/32V,
201 System III, or System V software licenses are
202 permitted to copy these documents, or any portion of them,
203 as necessary for licensed use of the software,
204 provided this copyright notice and statement of permission
205 are included.
206 .sp 1.6
207 Document PSD:10 is part of the user contributed software and is
208 copyright 1992 by the Free Software Foundation, Inc.
209 Permission is granted to make and distribute verbatim copies of
210 this document provided the copyright notice and this permission notice
211 are preserved on all copies.
212 .sp 1.6
213 Document PSD:13 is part of the user contributed software and is
214 copyright 1983 by Walter F. Tichy.
215 Permission to copy the RCS documentation or any portion thereof as
216 necessary for licensed use of the software is granted to licensees
217 of this software, provided this copyright notice is included.
218 .sp 1.6
219 .LP
220 The views and conclusions contained in this manual are those of the
221 authors and should not be interpreted as representing official policies,
222 either expressed or implied, of the Regents of the University of California.
223 .sp 1.6
224 .LP
225 The 4.4BSD Daemon used on the cover is
226 copyright 1994 by Marshall Kirk McKusick
227 and is reproduced with permission.
228 .br
229 This book was printed and bound in the United States of America.
230 .br
231 Distributed by O'Reilly & Associates, Inc.
232 .sp 1
233 .IP "[recycle logo]" 16
234 This book is printed on acid-free paper with 50% recycled content,
235 10-13% post-consumer waste. O'Reilly & Associates is committed to
236 using paper with the highest recycled content available consistent
237 with high quality.
238 .LP
239 .sp 1
240 ISBN: 1-56592-079-1
241 .bp
242 .OH '\s10Contents''- % -\s0'
243 .EH '\s10- % -''Contents\s0'
244 \&
245 .sp |1.5i
246 .nr PS 24
247 .nr VS 26
248 .LP
249 .ce 1
250 \fBContents\fP
251 .sp 1
252 .nr PS 12
253 .nr VS 14
254 .IP
255 .tl 'Introduction''ix'
256 .sp
257 .SH
258 Documents of Historical Interest
259 .sp
260 .IP
261 .tl 'The Unix Time\-Sharing System''tabbed 1'
262 .QP
263 Dennis Ritchie and Ken Thompson's original paper about UNIX, reprinted
264 from Communications of the ACM.
265 .sp
266 .IP
267 .tl 'Unix Implementation''tabbed 2'
268 .QP
269 Ken Thompson's description of the implementation of the Version 7
270 kernel and file system.
271 .sp
272 .IP
273 .tl 'The Unix I/O System''tabbed 3'
274 .QP
275 Dennis Ritchie's overview of the I/O System of Version 7; still helpful for
276 those writing device drivers.
277 .sp
278 .IP
279 .tl 'Unix Programming \- Second Edition ''tabbed 4'
280 .QP
281 Describes the programming interface to the UNIX version 7 operating
282 system and the standard I/O library. Should be supplemented by
283 Kernighan and Pike, ``The UNIX Programming Environment'',
284 Prentice-Hall, 1984 and especially by the Programmer Reference Manual
285 section 2 (system calls) and 3 (library routines).
286 .sp
287 .IP
288 .tl 'Berkeley Software Architecture Manual (4.4 Edition)''tabbed 5'
289 .QP
290 A concise and terse description of the system call interface
291 provided in Berkeley Unix, as revised for 4.4BSD.
292 This will never be a best seller.
293 .sp
294 .SH
295 Languages in common use
296 .sp
297 .IP
298 .tl 'The C Programming Language \- Reference Manual''tabbed 6'
299 .QP
300 Official statement of the syntax of C.
301 Should be supplemented by ``The C Programming Language,''
302 B.W. Kernighan and D.M. Ritchie, Prentice-Hall, 1978, that
303 contains a tutorial introduction and many examples.
304 .sp
305 .ne 1i
306 .IP
307 .tl 'Berkeley Pascal User\'s Manual''tabbed 7'
308 .QP
309 An implementation of this language popular for learning to program.
310 .sp
311 .IP
312 .tl 'A Portable Fortran 77 Compiler''tabbed 8'
313 .QP
314 A revised version of the document which originally appeared in
315 Volume 2b of the Bell Labs documentation;
316 this version reflects the work done at Berkeley.
317 .sp
318 .IP
319 .tl 'Introduction to the f77 I/O Library''tabbed 9'
320 .QP
321 A description of the revised input/output library for Fortran 77,
322 reflecting work carried out at Berkeley.
323 .sp
324 .SH
325 Programming Tools
326 .sp
327 .IP
328 .tl 'Debugging with GDB: The GNU Source-Level Debugger''tabbed 10'
329 .QP
330 How to debug programs using the source level \fIgdb\fP debugger
331 (or how to debug programs without having to know much about machine language).
332 .sp
333 .IP
334 .tl 'A Tutorial Introduction to ADB''tabbed 11'
335 .QP
336 How to debug programs using the assembly-language level \fIadb\fP debugger.
337 .sp
338 .IP
339 .tl 'Make \- A Program for Maintaining Computer Programs''tabbed 12'
340 .QP
341 Indispensable tool for making sure large programs are properly
342 compiled with minimal effort.
343 .sp
344 .IP
345 .tl 'An Introduction to the Revision Control System''tabbed 13'
346 .QP
347 RCS is a user-contributed tool for working together with other people
348 without stepping on each other's toes.
349 An alternative to \fIsccs\fR for controlling software changes.
350 .sp
351 .IP
352 .tl 'An Introduction to the Source Code Control System''tabbed 14'
353 .QP
354 A useful introductory article for those users with
355 installations licensed for SCCS.
356 .sp
357 .IP
358 .tl 'YACC: Yet Another Compiler-Compiler''tabbed 15'
359 .QP
360 Converts a BNF specification of a language and semantic actions
361 written in C into a compiler for that language.
362 .sp
363 .IP
364 .tl 'LEX \- A Lexical Analyzer Generator''tabbed 16'
365 .QP
366 Creates a recognizer for a set of regular expressions:
367 each regular expression can be followed by arbitrary C code
368 to be executed upon finding the regular expression.
369 .sp
370 .ne 1i
371 .IP
372 .tl 'The M4 Macro Processor''tabbed 17'
373 .QP
374 M4 is a macro processor useful in its own right and as a
375 front-end for C, Ratfor, and Cobol.
376 .sp
377 .IP
378 .tl 'gprof: a Call Graph Execution Profiler''tabbed 18'
379 .QP
380 A program to show the call graph and execution time of a program.
381 Indispensable aid for improving the running time of almost everything.
382 .sp
383 .SH
384 Programming Libraries
385 .sp
386 .IP
387 .tl 'Screen Updating and Cursor Movement Optimization''tabbed 19'
388 .QP
389 Describes the \fIcurses\fP package, an aid for writing screen-oriented,
390 terminal-independent programs.
391 .sp
392 .SH
393 General Reference
394 .sp
395 .IP
396 .tl 'An Introductory 4.4BSD Interprocess Communication Tutorial''tabbed 20'
397 .QP
398 How to write programs that use the Interprocess Communication Facilities
399 of 4.4BSD.
400 .sp
401 .IP
402 .tl 'An Advanced 4.4BSD Interprocess Communication Tutorial''tabbed 21'
403 .QP
404 The reference document (with some examples) for the Interprocess Communication
405 Facilities of 4.4BSD.
406 .sp
407 .IP
408 .tl 'List of Documents''inside back cover'
409 .EH ''''
410 .OH ''''
411 .if o .bp
412 \&
413 .bp
414 .OH '\s10Introduction''- % -\s0'
415 .EH '\s10- % -''Introduction\s0'
416 .de IR
417 \fI\\$1\^\fR\\$2
418 ..
419 .de RI
420 \fR\\$1\fI\\$2\^\fR\\$3
421 ..
422 .ce
423 \fB\s24Introduction\s0\fP
424 .sp 2
425 .nr PS 10
426 .nr VS 12
427 .LP
428 The documentation for 4.4BSD is in a format similar
429 to the one used for the 4.2BSD and 4.3BSD manuals.
430 It is divided into three sets; each set consists of one or more volumes.
431 The abbreviations for the volume names are listed in square brackets;
432 the abbreviations for the manual sections are listed in parenthesis.
433 .DS
434 I. User's Documents
435 User's Reference Manual [URM]
436 Commands (1)
437 Games (6)
438 Macro packages and language conventions (7)
439 User's Supplementary Documents [USD]
440 Getting Started
441 Basic Utilities
442 Communicating with the World
443 Text Editing
444 Document Preparation
445 Amusements
447 II. Programmer's Documents
448 Programmer's Reference Manual [PRM]
449 System calls (2)
450 Subroutines (3)
451 Special files (4)
452 File formats and conventions (5)
453 Programmer's Supplementary Documents [PSD]
454 Documents of Historic Interest
455 Languages in common use
456 Programming Tools
457 Programming Libraries
458 General Reference
460 III. System Manager's Manual [SMM]
461 Maintenance commands (8)
462 System Installation and Administration
463 .DE
464 .LP
465 References to individual documents are given as ``volume:document'',
466 thus USD:1 refers to the first document in the ``User's Supplementary
467 Documents''.
468 References to manual pages are given as ``\fIname\fP(section)'' thus
469 .IR sh (1)
470 refers to the shell manual entry in section 1.
471 .LP
472 The manual pages give descriptions of the features of the
473 4.4BSD system, as developed at the University of California at Berkeley.
474 They do not attempt to provide perspective or tutorial information about the
475 4.4BSD operating system, its facilities, or its implementation.
476 Various documents on those topics are contained in the
477 ``\s-1UNIX\s+1 User's Supplementary Documents'' (USD), the
478 ``\s-1UNIX\s+1 Programmer's Supplementary Documents'' (PSD),
479 and ``\s-1UNIX\s+1 System Manager's Manual'' (SMM).
480 In particular, for an overview see ``The \s-1UNIX\s+1 Time-Sharing System'' (PSD:1)
481 by Ritchie and Thompson; for a tutorial see
482 ``\s8\s-1UNIX\s+1\s10 for Beginners'' (USD:1) by Kernighan,
483 and for an guide to the new features of this latest version, see
484 ``Berkeley Software Architecture Manual (4.4 Edition)'' (PSD:5).
485 .LP
486 Within the area it surveys, this volume attempts to be timely, complete
487 and concise. Where the latter two objectives conflict,
488 the obvious is often left unsaid in favor of brevity.
489 It is intended that each program be described as it is, not as it should be.
490 Inevitably, this means that various sections will soon be out of date.
491 .LP
492 Commands are programs intended to be invoked directly by
493 the user, in contrast to subroutines, that are
494 intended to be called by the user's programs.
495 User commands are described in URM section 1.
496 Commands generally reside in directory
497 .I /bin
498 (for
499 .IR bin \|ary
500 programs).
501 Some programs also reside in
502 .I
503 /\|usr/\|bin,
504 .R
505 to save space in
506 .I /\|bin.
507 .R
508 These directories are searched automatically by the command interpreters.
509 Additional directories that may be of interest include
510 .I
511 /\|usr/\|contrib/\|bin,
512 .R
513 which has contributed software
514 .I
515 /\|usr/\|old/\|bin,
516 .R
517 which has old but sometimes still useful software and
518 .I
519 /\|usr/\|local/\|bin,
520 .R
521 which contains software local to your site.
522 .LP
523 Games have been relegated to URM section 6 and
524 .I
525 /\|usr/\|games,
526 .R
527 to keep them from contaminating
528 the more staid information of URM section 1.
529 .LP
530 Miscellaneous collection of information necessary for
531 writing in various specialized languages such as character codes,
532 macro packages for typesetting, etc is contained in URM section 7.
533 .LP
534 System calls are entries into the BSD kernel.
535 The system call interface is identical to a C language
536 procedure call; the equivalent C procedures are described in PRM section 2.
537 .LP
538 An assortment of subroutines is available;
539 they are described in PRM section 3.
540 The primary libraries in which they are kept are described in
541 .IR intro (3).
542 The functions are described in terms of C.
543 .LP
544 PRM section 4 discusses the characteristics of
545 each system ``file'' that refers to an I/O device.
546 The names in this section refer to the HP300 device names for the hardware,
547 instead of the names of the special files themselves.
548 .LP
549 The file formats and conventions (PRM section 5)
550 documents the structure of particular kinds of files;
551 for example, the form of the output of the loader and
552 assembler is given. Excluded are files used by only one command,
553 for example the assembler's intermediate files.
554 .LP
555 Commands and procedures intended for use primarily by the
556 system administrator are described in SMM section 8.
557 The files described here are almost all kept in the directory
558 .I /\|etc.
559 The system administration binaries reside in
560 .I
561 /\|sbin,
562 .R
563 and
564 .I
565 /\|usr/\|sbin.
566 .LP
567 Each section consists of independent entries of a page or so each.
568 The name of the entry is in the upper corners of its pages,
569 together with the section number.
570 Entries within each section are alphabetized.
571 The page numbers of each entry start at 1;
572 it is infeasible to number consecutively the pages of
573 a document like this that is republished in many variant forms.
574 .LP
575 All entries are based on a common format;
576 not all subsections always appear.
577 .RS
578 .LP
579 The
580 .I name
581 subsection lists the exact names of the commands and subroutines
582 covered under the entry and gives a short description of their purpose.
583 .LP
584 The
585 .IR synopsis ""
586 summarizes the use of the program being described.
587 A few conventions are used, particularly in the Commands subsection:
588 .LP
589 .RS
590 .B Boldface
591 words are considered literals, and are typed just as they appear.
592 .LP
593 Square brackets [ ] around an argument show that the argument is optional.
594 When an argument is given as ``name'', it always refers to a file name.
595 .LP
596 Ellipses ``.\|.\|.'' are used to show that the previous argument-prototype
597 may be repeated.
598 .LP
599 A final convention is used by the commands themselves.
600 An argument beginning with a minus sign ``\-'' usually means that it is an
601 option-specifying argument, even if it appears in a position where
602 a file name could appear. Therefore, it is unwise to have files whose
603 names begin with ``\-''.
604 .LP
605 .RE
606 The
607 .IR description ""
608 subsection discusses in detail the subject at hand.
609 .LP
610 The
611 .IR files ""
612 subsection gives the names of files that are built into the program.
613 .LP
614 A
615 .I
616 see also
617 .R
618 subsection gives pointers to related information.
619 .LP
620 A
621 .I diagnostics
622 subsection discusses the diagnostic indications that may be produced.
623 Messages that are intended to be self-explanatory are not listed.
624 .LP
625 The
626 .IR bugs ""
627 subsection gives known bugs and sometimes deficiencies.
628 Occasionally the suggested fix is also described.
629 .LP
630 .RE
631 At the beginning of URM, PRM, and SSM is a List of Manual Pages,
632 organized by section and alphabetically within each section, and a
633 Permuted Index derived from that List.
634 Within each index entry, the title of the writeup to which
635 it refers is followed by the appropriate section number in parentheses.
636 This fact is important because there is considerable
637 name duplication among the sections, arising principally from commands that
638 exist only to exercise a particular system call.
639 Finally, there is a list of documents on the inside back cover of each volume.
640 .if o .bp
641 \&
642 .EH ''''
643 .OH ''''