| blob | ce0bfb8ec59da51794089c81bf26406d76ce4d9b |
1 .\" $NetBSD: title.prm,v 1.3 2003/05/06 10:46:41 jmmv Exp $
2 .\"
3 .\" Copyright (c) 1980, 1993, 1994 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.prm 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 Reference Manual
48 .nr PS 24
49 .nr VS 32
50 .LP
51 .ft B
52 .ce 1
53 (PRM)
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 Reference Manual
109 .nr PS 24
110 .nr VS 32
111 .LP
112 .ft B
113 .ce 1
114 (PRM)
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.2i
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
155 .LP
156 Copyright 1979, 1980, 1983, 1986, 1993, 1994
157 The Regents of the University of California. All rights reserved.
158 .sp 1
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
195 .LP
196 The Institute of Electrical and Electronics Engineers and the American
197 National Standards Committee X3, on Information Processing Systems have
198 given us permission to reprint portions of their documentation.
199 .sp 0.5
200 .LP
201 In the following statement, the phrase ``this text'' refers to portions
202 of the system documentation.
203 .LP
204 ``Portions of this text are reprinted and reproduced in
205 electronic form in 4.4BSD from IEEE Std 1003.1-1988, IEEE
206 Standard Portable Operating System Interface for Computer Environments
207 (POSIX), copyright 1988 by the Institute of Electrical and Electronics
208 Engineers, Inc. In the event of any discrepancy between these versions
209 and the original IEEE Standard, the original IEEE Standard is the referee
210 document.''
211 .sp 0.5
212 .LP
213 In the following statement, the phrase ``This material'' refers to portions
214 of the system documentation.
215 .LP
216 ``This material is reproduced with permission from American National
217 Standards Committee X3, on Information Processing Systems. Computer and
218 Business Equipment Manufacturers Association (CBEMA), 311 First St., NW,
219 Suite 500, Washington, DC 20001-2178. The developmental work of
220 Programming Language C was completed by the X3J11 Technical Committee.''
221 .sp 1
222 .LP
223 Manual pages ptrace.2, ecvt.3, mp.3, plot.3, L-devices.5, L-dialcodes.5,
224 L.aliases.5, L.cmds.5, L.sys.5, USERFILE.5, dump.5, and plot.5
225 are copyright 1979, AT&T Bell Laboratories, Incorporated.
226 Holders of \x'-1p'UNIX\v'-4p'\s-3TM\s0\v'4p'/32V,
227 System III, or System V software licenses are
228 permitted to copy these documents, or any portion of them,
229 as necessary for licensed use of the software,
230 provided this copyright notice and statement of permission
231 are included.
232 .sp 1
233 .LP
234 The views and conclusions contained in this manual are those of the
235 authors and should not be interpreted as representing official policies,
236 either expressed or implied, of the Regents of the University of California.
237 .sp 1
238 .LP
239 The 4.4BSD Daemon used on the cover is
240 copyright 1994 by Marshall Kirk McKusick
241 and is reproduced with permission.
242 .br
243 This book was printed and bound in the United States of America.
244 .br
245 Distributed by O'Reilly & Associates, Inc.
246 .sp 1
247 .IP "[recycle logo]" 16
248 This book is printed on acid-free paper with 50% recycled content,
249 10-13% post-consumer waste. O'Reilly & Associates is committed to
250 using paper with the highest recycled content available consistent
251 with high quality.
252 .LP
253 .sp 1
254 ISBN: 1-56592-078-3
255 .bp
256 \&
257 .sp |1.5i
258 .nr PS 24
259 .nr VS 26
260 .LP
261 .ce 1
262 \fBContents\fP
263 .sp 1
264 .nr PS 14
265 .nr VS 17
266 .LP
267 .TS
268 expand;
269 l r.
270 Introduction vii
271 List of Manual Pages ix
272 Permuted Index xxix
273 Reference Manual Sections 2, 3, 4, 5 tabbed pages
274 List of Documents inside back cover
275 .TE
276 .if o .bp
277 \&
278 .EH ''''
279 .OH ''''
280 .bp
281 .OH '\s10Introduction''- % -\s0'
282 .EH '\s10- % -''Introduction\s0'
283 .de IR
284 \fI\\$1\^\fR\\$2
285 ..
286 .de RI
287 \fR\\$1\fI\\$2\^\fR\\$3
288 ..
289 .ce
290 \fB\s24Introduction\s0\fP
291 .sp 2
292 .nr PS 10
293 .nr VS 12
294 .LP
295 The documentation for 4.4BSD is in a format similar
296 to the one used for the 4.2BSD and 4.3BSD manuals.
297 It is divided into three sets; each set consists of one or more volumes.
298 The abbreviations for the volume names are listed in square brackets;
299 the abbreviations for the manual sections are listed in parenthesis.
300 .DS
301 I. User's Documents
302 User's Reference Manual [URM]
303 Commands (1)
304 Games (6)
305 Macro packages and language conventions (7)
306 User's Supplementary Documents [USD]
307 Getting Started
308 Basic Utilities
309 Communicating with the World
310 Text Editing
311 Document Preparation
312 Amusements
314 II. Programmer's Documents
315 Programmer's Reference Manual [PRM]
316 System calls (2)
317 Subroutines (3)
318 Special files (4)
319 File formats and conventions (5)
320 Programmer's Supplementary Documents [PSD]
321 Documents of Historic Interest
322 Languages in common use
323 Programming Tools
324 Programming Libraries
325 General Reference
327 III. System Manager's Manual [SMM]
328 Maintenance commands (8)
329 System Installation and Administration
330 .DE
331 .LP
332 References to individual documents are given as ``volume:document'',
333 thus USD:1 refers to the first document in the ``User's Supplementary
334 Documents''.
335 References to manual pages are given as ``\fIname\fP(section)'' thus
336 .IR sh (1)
337 refers to the shell manual entry in section 1.
338 .LP
339 The manual pages give descriptions of the features of the
340 4.4BSD system, as developed at the University of California at Berkeley.
341 They do not attempt to provide perspective or tutorial information about the
342 4.4BSD operating system, its facilities, or its implementation.
343 Various documents on those topics are contained in the
344 ``\s-1UNIX\s+1 User's Supplementary Documents'' (USD), the
345 ``\s-1UNIX\s+1 Programmer's Supplementary Documents'' (PSD),
346 and ``\s-1UNIX\s+1 System Manager's Manual'' (SMM).
347 In particular, for an overview see ``The \s-1UNIX\s+1 Time-Sharing System'' (PSD:1)
348 by Ritchie and Thompson; for a tutorial see
349 ``\s8\s-1UNIX\s+1\s10 for Beginners'' (USD:1) by Kernighan,
350 and for an guide to the new features of this latest version, see
351 ``Berkeley Software Architecture Manual (4.4 Edition)'' (PSD:5).
352 .LP
353 Within the area it surveys, this volume attempts to be timely, complete
354 and concise. Where the latter two objectives conflict,
355 the obvious is often left unsaid in favor of brevity.
356 It is intended that each program be described as it is, not as it should be.
357 Inevitably, this means that various sections will soon be out of date.
358 .LP
359 Commands are programs intended to be invoked directly by
360 the user, in contrast to subroutines, that are
361 intended to be called by the user's programs.
362 User commands are described in URM section 1.
363 Commands generally reside in directory
364 .I /bin
365 (for
366 .IR bin \|ary
367 programs).
368 Some programs also reside in
369 .I
370 /\|usr/\|bin,
371 .R
372 to save space in
373 .I /\|bin.
374 .R
375 These directories are searched automatically by the command interpreters.
376 Additional directories that may be of interest include
377 .I
378 /\|usr/\|contrib/\|bin,
379 .R
380 which has contributed software
381 .I
382 /\|usr/\|old/\|bin,
383 .R
384 which has old but sometimes still useful software and
385 .I
386 /\|usr/\|local/\|bin,
387 .R
388 which contains software local to your site.
389 .LP
390 Games have been relegated to URM section 6 and
391 .I
392 /\|usr/\|games,
393 .R
394 to keep them from contaminating
395 the more staid information of URM section 1.
396 .LP
397 Miscellaneous collection of information necessary for
398 writing in various specialized languages such as character codes,
399 macro packages for typesetting, etc is contained in URM section 7.
400 .LP
401 System calls are entries into the BSD kernel.
402 The system call interface is identical to a C language
403 procedure call; the equivalent C procedures are described in PRM section 2.
404 .LP
405 An assortment of subroutines is available;
406 they are described in PRM section 3.
407 The primary libraries in which they are kept are described in
408 .IR intro (3).
409 The functions are described in terms of C.
410 .LP
411 PRM section 4 discusses the characteristics of
412 each system ``file'' that refers to an I/O device.
413 The names in this section refer to the HP300 device names for the hardware,
414 instead of the names of the special files themselves.
415 .LP
416 The file formats and conventions (PRM section 5)
417 documents the structure of particular kinds of files;
418 for example, the form of the output of the loader and
419 assembler is given. Excluded are files used by only one command,
420 for example the assembler's intermediate files.
421 .LP
422 Commands and procedures intended for use primarily by the
423 system administrator are described in SMM section 8.
424 The files described here are almost all kept in the directory
425 .I /\|etc.
426 The system administration binaries reside in
427 .I
428 /\|sbin,
429 .R
430 and
431 .I
432 /\|usr/\|sbin.
433 .LP
434 Each section consists of independent entries of a page or so each.
435 The name of the entry is in the upper corners of its pages,
436 together with the section number.
437 Entries within each section are alphabetized.
438 The page numbers of each entry start at 1;
439 it is infeasible to number consecutively the pages of
440 a document like this that is republished in many variant forms.
441 .LP
442 All entries are based on a common format;
443 not all subsections always appear.
444 .RS
445 .LP
446 The
447 .I name
448 subsection lists the exact names of the commands and subroutines
449 covered under the entry and gives a short description of their purpose.
450 .LP
451 The
452 .IR synopsis ""
453 summarizes the use of the program being described.
454 A few conventions are used, particularly in the Commands subsection:
455 .LP
456 .RS
457 .B Boldface
458 words are considered literals, and are typed just as they appear.
459 .LP
460 Square brackets [ ] around an argument show that the argument is optional.
461 When an argument is given as ``name'', it always refers to a file name.
462 .LP
463 Ellipses ``.\|.\|.'' are used to show that the previous argument-prototype
464 may be repeated.
465 .LP
466 A final convention is used by the commands themselves.
467 An argument beginning with a minus sign ``\-'' usually means that it is an
468 option-specifying argument, even if it appears in a position where
469 a file name could appear. Therefore, it is unwise to have files whose
470 names begin with ``\-''.
471 .LP
472 .RE
473 The
474 .IR description ""
475 subsection discusses in detail the subject at hand.
476 .LP
477 The
478 .IR files ""
479 subsection gives the names of files that are built into the program.
480 .LP
481 A
482 .I
483 see also
484 .R
485 subsection gives pointers to related information.
486 .LP
487 A
488 .I diagnostics
489 subsection discusses the diagnostic indications that may be produced.
490 Messages that are intended to be self-explanatory are not listed.
491 .LP
492 The
493 .IR bugs ""
494 subsection gives known bugs and sometimes deficiencies.
495 Occasionally the suggested fix is also described.
496 .LP
497 .RE
498 At the beginning of URM, PRM, and SSM is a List of Manual Pages,
499 organized by section and alphabetically within each section, and a
500 Permuted Index derived from that List.
501 Within each index entry, the title of the writeup to which
502 it refers is followed by the appropriate section number in parentheses.
503 This fact is important because there is considerable
504 name duplication among the sections, arising principally from commands that
505 exist only to exercise a particular system call.
506 Finally, there is a list of documents on the inside back cover of each volume.
507 .if o .bp
508 \&
509 .EH ''''
510 .OH ''''
511 .bp
512 .OH '\s10Manual Pages''- % -\s0'
513 .EH '\s10- % -''Manual Pages\s0'
514 .EF '\s10\\\\*(Dt''\\\\*(Ed\s0'
515 .OF '\s10\\\\*(Ed''\\\\*(Dt\s0'
516 .nr PS 10
517 .nr VS 12
518 .LP
519 .ce
520 \s24\fBList \|of \|Manual \|Pages\fP\s0
521 .nr x 0.5
522 .in +\nxi
523 .nf
524 .ta \n(.lu-\nxuR
525 .de xx
526 \\$1\f3 \a \fP\\$2
527 ..
528 .de t
529 .sp 1v
530 .ne .5i
531 .cs 3
532 .ti -\\nxi
533 .ss 18
534 \fB\\$2. \\$3\fP
535 .ss 12
536 .if t .sp .5v
537 .cs 3 36
538 .ds Ed Section \\$2
539 .ds Dt \\$3
540 .so \\$1
541 ..
542 .t toc1 1 "Commands and Application Programs"
543 .t toc2 2 "System Calls"
544 .t toc3 3 "C Library Subroutines"
545 .t toc4 4 "Special Files"
546 .t toc5 5 "File Formats"
547 .t toc6 6 "Games"
548 .t toc7 7 "Miscellaneous"
549 .t toc8 8 "System Maintenance"
550 .in -\nxi
551 .cs 3
552 .ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i 6i 6.5i
553 .if o .bp
554 \&
555 .EH ''''
556 .OH ''''
557 .bp
558 \&
559 .OH '\s10Permuted Index''- % -\s0'
560 .EH '\s10- % -''Permuted Index\s0'
561 .ds Ed 4.4BSD
562 .ds Dt April \|1994
563 .ce
564 \s24\fBPermuted \|Index\fP\s0
565 .sp 2
566 .nr PS 8
567 .nr VS 9
568 .LP
569 .\" backup from slotput 1, slot, 2
570 .tr ~
571 .nf
572 .cs 3 36
573 .de xx
574 .ds s1\"
576 .ds s2 ~~~\"
577 .ds s3\"
579 .ds s4 ~~\"
580 .ds s5 ~~\"
581 .ds y \\*(s4\f3\x01\fP\\*(s5
584 ..
585 .so ptxx
586 .cs 3
587 .ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i 6i 6.5i