![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to intro.ms CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / man / man0|
Return to intro.ms CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / man / man0 |
1.1 root 1: .\" Copyright (c) 1980 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)intro.ms 6.3 (Berkeley) 5/14/86
6: .\"
7: .de IR
8: \fI\\$1\^\fR\\$2
9: ..
10: .de RI
11: \fR\\$1\fI\\$2\^\fR\\$3
12: ..
13: .TL
14: INTRODUCTION TO USER'S REFERENCE MANUAL
15: .OH 'Introduction''- % -'
16: .EH '- % -''Introduction'
17: .af % i
18: .pn 6
19: .LP
20: The documentation has been reorganized for 4.3BSD in a format similar
21: to the one used for the Usenix 4.2BSD manuals.
22: It is divided into three sets; each set consists of one or more volumes.
23: The abbreviations for the volume names are listed in square brackets;
24: the abbreviations for the manual sections are listed in parenthesis.
25: .DS
26: I. User's Documents
27: User's Reference Manual [URM]
28: Commands (1)
29: Games (6)
30: Macro packages and language conventions (7)
31: User's Supplementary Documents [USD]
32: Getting Started
33: Basic Utilities
34: Communicating with the World
35: Text Editing
36: Document Preparation
37: Amusements
38:
39: II. Programmer's Documents
40: Programmer's Reference Manual [PRM]
41: System calls (2)
42: Subroutines (3)
43: Special files (4)
44: File formats and conventions (5)
45: Programmer's Supplementary Documents, Volume 1 [PS1]
46: Languages in common use
47: General Reference
48: Programming Tools
49: Programming Libraries
50: Programmer's Supplementary Documents, Volume 2 [PS2]
51: Documents of Historic Interest
52: Other Languages
53: Database Management
54:
55: III. System Manager's Manual [SMM]
56: Maintenance commands (8)
57: System Installation and Administration
58: Supporting Documentation
59: .DE
60: .LP
61: References to individual documents are given as ``volume:document'',
62: thus USD:1 refers to the first document in the ``User's Supplementary
63: Documents''.
64: References to manual pages are given as ``\fIname\fP(section)'' thus
65: .IR sh (1)
66: refers to the shell manual entry in section 1.
67: .LP
68: The manual pages give descriptions of the publicly available features of the
69: .UX \s-2/32V\s0
70: system, as extended to provide a virtual memory environment
71: and other enhancements at the University of California.
72: They do not attempt to provide perspective or tutorial information about the
73: .UX
74: operating system, its facilities, or its implementation.
75: Various documents on those topics are contained in the
76: ``UNIX User's Supplementary Documents'' (USD), the
77: ``UNIX Programmer's Supplementary Documents'' (PS1 and PS2),
78: and ``UNIX System Manager's Manual'' (SMM).
79: In particular, for an overview see ``The UNIX Time-Sharing System'' (PS2:1)
80: by Ritchie and Thompson; for a tutorial see
81: ``\s8UNIX\s10 for Beginners'' (USD:1) by Kernighan,
82: and for an guide to the new features of this virtual version, see
83: ``Berkeley Software Architecture Manual (4.3 Edition)'' (PS1:6).
84: .LP
85: Within the area it surveys, this volume attempts to be timely, complete
86: and concise. Where the latter two objectives conflict,
87: the obvious is often left unsaid in favor of brevity.
88: It is intended that each program be described as it is, not as it should be.
89: Inevitably, this means that various sections will soon be out of date.
90: .LP
91: Commands are programs intended to be invoked directly by
92: the user, in contrast to subroutines, that are
93: intended to be called by the user's programs.
94: User commands are described in URM section 1.
95: Commands generally reside in directory
96: .I /bin
97: (for
98: .IR bin \|ary
99: programs).
100: Some programs also reside in
101: .I
102: /\|usr/\|bin,
103: .R
104: .I
105: /\|usr/\|ucb,
106: .R
107: or
108: .I
109: /\|usr/\|new,
110: .R
111: to save space in
112: .I /\|bin.
113: These directories are searched automatically by the command interpreters.
114: .LP
115: Games have been relegated to URM section 6 and
116: .I
117: /\|usr/\|games,
118: .R
119: to keep them from contaminating
120: the more staid information of URM section 1.
121: .LP
122: Miscellaneous collection of information necessary for
123: writing in various specialized languages such as character codes,
124: macro packages for typesetting, etc is contained in URM section 7.
125: .LP
126: System calls are entries into the
127: .UX
128: supervisor. The system call interface is identical to a C language
129: procedure call; the equivalent C procedures are described in PRM section 2.
130: .LP
131: An assortment of subroutines is available;
132: they are described in PRM section 3.
133: The primary libraries in which they are kept are described in
134: .IR intro (3).
135: The functions are described in terms of C;
136: those that will work with Fortran are described in
137: .IR intro (3f).
138: .LP
139: PRM section 4 discusses the characteristics of
140: each system ``file'' that refers to an I/O device.
141: The names in this section refer to the DEC device names for the hardware,
142: instead of the names of the special files themselves.
143: .LP
144: The file formats and conventions (PRM section 5)
145: documents the structure of particular kinds of files;
146: for example, the form of the output of the loader and
147: assembler is given. Excluded are files used by only one command,
148: for example the assembler's intermediate files.
149: .LP
150: Commands and procedures intended for use primarily by the
151: system administrator are described in SMM section 8.
152: The commands and files described here are almost all kept in the directory
153: .I /\|etc.
154: .LP
155: Each section consists of independent entries of a page or so each.
156: The name of the entry is in the upper corners of its pages,
157: together with the section number, and sometimes a
158: letter characteristic of a subcategory, e.g. graphics is 1G,
159: and the math library is 3M.
160: Entries within each section are alphabetized.
161: except for PRM section 3f which appears after the rest of PRM section 3.
162: The page numbers of each entry start at 1;
163: it is infeasible to number consecutively the pages of
164: a document like this that is republished in many variant forms.
165: .LP
166: All entries are based on a common format;
167: not all subsections always appear.
168: .RS
169: .LP
170: The
171: .I name
172: subsection lists the exact names of the commands and subroutines
173: covered under the entry and gives a short description of their purpose.
174: .LP
175: The
176: .IR synopsis ""
177: summarizes the use of the program being described.
178: A few conventions are used, particularly in the Commands subsection:
179: .LP
180: .RS
181: .B Boldface
182: words are considered literals, and are typed just as they appear.
183: .LP
184: Square brackets [ ] around an argument show that the argument is optional.
185: When an argument is given as ``name'', it always refers to a file name.
186: .LP
187: Ellipses ``.\|.\|.'' are used to show that the previous argument-prototype
188: may be repeated.
189: .LP
190: A final convention is used by the commands themselves.
191: An argument beginning with a minus sign ``\-'' usually means that it is an
192: option-specifying argument, even if it appears in a position where
193: a file name could appear. Therefore, it is unwise to have files whose
194: names begin with ``\-''.
195: .LP
196: .RE
197: The
198: .IR description ""
199: subsection discusses in detail the subject at hand.
200: .LP
201: The
202: .IR files ""
203: subsection gives the names of files that are built into the program.
204: .LP
205: A
206: .I
207: see also
208: .R
209: subsection gives pointers to related information.
210: .LP
211: A
212: .I diagnostics
213: subsection discusses the diagnostic indications that may be produced.
214: Messages that are intended to be self-explanatory are not listed.
215: .LP
216: The
217: .IR bugs ""
218: subsection gives known bugs and sometimes deficiencies.
219: Occasionally the suggested fix is also described.
220: .LP
221: .RE
222: At the beginning of URM is a table of contents,
223: organized by section and alphabetically within each section.
224: There is also a permuted index derived from the table of contents.
225: Within each index entry, the title of the writeup to which
226: it refers is followed by the appropriate section number in parentheses.
227: This fact is important because there is considerable
228: name duplication among the sections, arising principally from commands that
229: exist only to exercise a particular system call.
230: .SH
231: HOW TO GET STARTED
232: .LP
233: This section sketches the basic information you need to get started on UNIX;
234: how to log in and log out, how to communicate through your terminal,
235: and how to run a program.
236: See ``\c
237: .UX
238: for Beginners'' in (USD:1) for a more complete introduction to the system.
239: .LP
240: .I
241: Logging in.\ \
242: .R
243: Almost any ASCII terminal capable of
244: full duplex operation and generating
245: the entire character set can be used.
246: You must have a valid user name,
247: which may be obtained from the system administration.
248: If you will be accessing UNIX remotely, you will also
249: need to obtain the telephone number for the system that you will be using.
250: .LP
251: After a data connection is established,
252: the login procedure depends on what type of terminal you are using
253: and local system conventions.
254: If your terminal is directly connected to the computer,
255: it generally runs at 9600 or 19200 baud.
256: If you are using a modem running over a phone line,
257: the terminal must be set at the speed appropriate for the modem you are using,
258: typically 300, 1200, or 2400 baud.
259: The half/full duplex switch should always be set at full-duplex.
260: (This switch will often have to be changed
261: since many other systems require half-duplex).
262: .LP
263: When a connection is established, the system types ``login:'';
264: you type your user name, followed by the ``return'' key.
265: If you have a password, the system asks for it
266: and suppresses echo to the terminal so the password will not appear.
267: After you have logged in, the ``return'', ``new line'', or ``linefeed'' keys
268: will give exactly the same results.
269: A message-of-the-day usually greets you before your first prompt.
270: .LP
271: If the system types out a few garbage characters
272: after you have established a data connection
273: (the ``login:'' message at the wrong speed),
274: depress the ``break'' (or ``interrupt'') key.
275: This is a speed-independent signal to
276: .UX
277: that a different speed terminal is in use.
278: The system then will type ``login:,'' this time at another speed.
279: Continue depressing the break key until ``login:'' appears clearly,
280: then respond with your user name.
281: .LP
282: For all these terminals, it is important
283: that you type your name in lower-case if possible; if you type
284: upper-case letters,
285: .UX
286: will assume that your terminal cannot generate lower-case
287: letters and will translate all subsequent lower-case letters to upper case.
288: .LP
289: The evidence that you have successfully logged in is that a shell program
290: will type a prompt (``$'' or ``%'') to you.
291: (The shells are described below under ``How to run a program.'')
292: .LP
293: For more information, consult
294: .IR tset (1),
295: and
296: .IR stty (1),
297: which tell how to adjust terminal behavior;
298: .IR getty (8)
299: discusses the login sequence in more detail, and
300: .IR tty (4)
301: discusses terminal I/O.
302: .LP
303: .I
304: Logging out.\ \
305: .R
306: There are three ways to log out:
307: .IP
308: By typing ``logout'' or an end-of-file
309: indication (EOT character, control-D) to the shell.
310: The shell will terminate and the ``login:'' message will appear again.
311: .IP
312: You can log in directly as another user by giving a
313: .IR login (1)
314: command.
315: .IP
316: If worse comes to worse,
317: you can simply hang up the phone; but beware \- some machines may
318: lack the necessary hardware to detect that the phone has been hung up.
319: Ask your system administrator if this is a problem on your machine.
320: .LP
321: .I
322: How to communicate through your terminal.\ \
323: .R
324: When you type characters, a gnome deep in the system
325: gathers your characters and saves them in a secret place.
326: The characters will not be given to a program
327: until you type a return (or newline), as described above in
328: .I
329: Logging in.
330: .R
331: .LP
332: .UX
333: terminal I/O is full-duplex.
334: It has full read-ahead, which means that you can type at any time,
335: even while a program is typing at you.
336: Of course, if you type during output, the printed output will
337: have the input characters interspersed.
338: However, whatever you type will be saved up and interpreted in correct sequence.
339: There is a limit to the amount of read-ahead,
340: but it is generous and not likely to be exceeded unless
341: the system is in trouble.
342: When the read-ahead limit is exceeded, the system
343: throws away all the saved characters (or beeps, if your prompt was a ``%'').
344: .LP
345: The delete (DEL) character in typed input kills all the
346: preceding characters in the line,
347: so typing mistakes can be repaired on a single line.
348: Also, the backspace character (control-H) erases the last character typed.
349: .IR Tset (1)
350: or
351: .IR stty (1)
352: can be used to change these defaults.
353: Successive uses of backspace erases characters back to, but
354: not beyond, the beginning of the line.
355: DEL and backspace can be transmitted to a program by preceding them with ``\e''.
356: (So, to erase ``\e'', you need two backspaces).
357: .LP
358: An
359: .I
360: interrupt signal
361: .R
362: is sent to a program by typing control-C or the ``break'' key
363: which is not passed to programs.
364: This signal generally causes whatever program you are running to terminate.
365: It is typically used to stop a long printout that you do not want.
366: However, programs can arrange either to ignore this signal altogether,
367: or to be notified when it happens (instead of being terminated).
368: The editor, for example, catches interrupts and stops what it is doing,
369: instead of terminating, so that an interrupt can
370: be used to halt an editor printout without losing the file being edited.
371: The interrupt character can also be changed with
372: .IR tset (1)
373: or
374: .IR stty (1).
375: .LP
376: It is also possible to suspend output temporarily using ^S (control-S)
377: and later resume output with ^Q (control-Q).
378: Output can be thrown away without interrupting
379: the program by typing ^O (control-O); see
380: .IR tty (4).
381: .LP
382: The
383: .IR quit ""
384: signal is generated by typing the \s8ASCII\s10 FS character.
385: (FS appears many places on different terminals, most commonly
386: as control-\e or control-\^|\^.)
387: It not only causes a running program to terminate
388: but also generates a file with the core image of the terminated process.
389: Quit is useful for debugging.
390: .LP
391: Besides adapting to the speed of the terminal,
392: .UX
393: tries to be intelligent about whether
394: you have a terminal with the newline function
395: or whether it must be simulated with carriage-return and line-feed.
396: In the latter case, all input carriage returns
397: are turned to newline characters (the standard line delimiter)
398: and both a carriage return and a line feed are echoed to the terminal.
399: If you get into the wrong mode, the
400: .IR reset (1)
401: command will rescue you.
402: If the terminal does not appear to be echoing anything that you type,
403: it may be stuck in ``no-echo'' or ``raw'' mode.
404: Try typing ``(control-J)reset(control-J)'' to recover.
405: .LP
406: Tab characters are used freely in
407: .UX
408: source programs.
409: If your terminal does not have the tab function,
410: you can arrange to have them turned into spaces
411: during output, and echoed as spaces during input.
412: The system assumes that tabs are set every eight columns.
413: Again, the
414: .IR tset (1)
415: or
416: .IR stty (1)
417: command can be used to change these defaults.
418: .IR Tset (1)
419: can be used to set the tab stops automatically when necessary.
420: .LP
421: .I
422: How to run a program; the shells.\ \
423: .R
424: When you have successfully logged in, a program
425: called a shell is listening to your terminal.
426: The shell reads typed-in lines, splits them up
427: into a command name and arguments, and executes the command.
428: A command is simply an executable program.
429: The shell looks in several system directories to find the command. You can also
430: place commands in your own directory and have the shell find them there.
431: There is nothing special about system-provided
432: commands except that they are kept in a directory where the shell can find them.
433: .LP
434: The command name is always the first word on an input line;
435: it and its arguments are separated from one another by spaces.
436: .LP
437: When a program terminates, the shell will ordinarily regain control and type
438: a prompt at you to show that it is ready for another command.
439: .LP
440: The shells have many other capabilities, that are described in detail in
441: sections
442: .IR sh (1)
443: and
444: .IR csh (1).
445: If the shell prompts you with ``$'', then it is an instance of
446: .IR sh (1)
447: the standard shell provided by Bell Labs.
448: If it prompts with ``%'' then it is an instance of
449: .IR csh (1),
450: a shell written at Berkeley.
451: The shells are different for all but the most simple terminal usage.
452: Most users at Berkeley choose
453: .IR csh (1)
454: because of the
455: .I history
456: mechanism and the
457: .I alias
458: feature, that greatly enhance its power when used interactively.
459: .I Csh
460: also supports the job-control facilities;
461: see
462: .IR csh (1)
463: or the Csh introduction in USD:4 for details.
464: .LP
465: You can change from one shell to the other by using the
466: .I chsh (1)
467: command, which takes effect at your next login.
468: .LP
469: .I
470: The current directory.\ \
471: .R
472: .UX
473: has a file system arranged as a hierarchy of directories.
474: When the system administrator gave you a user name,
475: they also created a directory for you (ordinarily
476: with the same name as your user name).
477: When you log in, any file name you type is by default in this directory.
478: Since you are the owner of this directory, you have
479: full permission to read, write, alter, or destroy its contents.
480: Permissions to have your will with other directories
481: and files will have been granted or denied to you by their owners.
482: As a matter of observed fact, few
483: .UX
484: users protect their files from perusal by other users.
485: .LP
486: To change the current directory (but not the set of permissions you
487: were endowed with at login) use
488: .IR cd (1).
489: .LP
490: .I
491: Path names.\ \
492: .R
493: To refer to files not in the current directory, you must use a path name.
494: Full path names begin with ``/\|'', the name of the root directory of the
495: whole file system.
496: After the slash comes the name of each directory containing the next
497: sub-directory (followed by a ``/\|'') until finally the file name is reached.
498: For example,
499: .I
500: /\^usr/\^tmp/\^filex
501: .R
502: refers to the file
503: .I
504: filex
505: .R
506: in the directory
507: .I
508: tmp; tmp
509: .R
510: is itself a subdirectory of
511: .I
512: usr; usr
513: .R
514: springs directly from the root directory.
515: .LP
516: If your current directory has subdirectories,
517: the path names of files therein begin with
518: the name of the subdirectory with no prefixed ``/\|''.
519: .LP
520: A path name may be used anywhere a file name is required.
521: .LP
522: Important commands that modify the contents of files are
523: .IR cp (1),
524: .IR mv (1),
525: and
526: .IR rm (1),
527: which respectively copy, move (i.e. rename) and remove files.
528: To find out the status of files or directories, use
529: .IR ls (1).
530: See
531: .IR mkdir (1)
532: for making directories and
533: .IR rmdir (1)
534: for destroying them.
535: .LP
536: For a fuller discussion of the file system, see
537: ``A Fast File System for UNIX'' (SMM:14)
538: by McKusick, Joy, Leffler, and Fabry.
539: It may also be useful to glance through PRM section 2,
540: that discusses system calls, even if you do not intend
541: to deal with the system at that level.
542: .LP
543: .I
544: Writing a program.\ \
545: .R
546: To enter the text of a source program into a
547: .UX
548: file, use the editor
549: .IR ex (1)
550: or its display editing alias
551: .IR vi (1).
552: (The old standard editor
553: .IR ed (1)
554: is also available.)
555: The principal languages in
556: .UX
557: are provided by the C compiler
558: .IR cc (1),
559: the Fortran compiler
560: .IR f77 (1),
561: and its derivatives
562: .IR efl (1)
563: and
564: .IR ratfor (1),
565: the Pascal compiler
566: .IR pc (1),
567: and interpreter
568: .IR pi (1),
569: and the Lisp system
570: .IR lisp (1).
571: User contributed software in the latest
572: release of the system supports
573: APL, B, the Functional Programming language, and Icon.
574: Refer to
575: .IR apl (1),
576: .IR b (1),
577: .IR fp (1),
578: and
579: .IR icon (1),
580: respectively for more information about each.
581: After the program text has been entered through the editor
582: and written to a file, you can give the file
583: to the appropriate language processor as an argument.
584: The output of the language processor
585: will be left on a file in the current directory named ``a.out''.
586: If the output is precious, use
587: .IR mv (1)
588: to move it to a less exposed name after successful compilation.
589: .LP
590: When you have finally gone through this entire process
591: without provoking any diagnostics, the resulting program
592: can be run by giving its name to the shell
593: in response to the shell (``$'' or ``%'') prompt.
594: .LP
595: Your programs can receive arguments from the command line
596: just as system programs do,
597: see ``UNIX Programming - Second Edition'' (PS2:3),
598: or for a more terse description
599: .IR execve (2).
600: .LP
601: .I
602: Text processing.\ \
603: .R
604: Almost all text is entered through the editor
605: .IR ex (1)
606: (often entered via
607: .IR vi (1)).
608: The commands most often used to write text on a terminal are:
609: .IR cat (1),
610: .IR more (1),
611: and
612: .IR nroff (1).
613: .LP
614: The
615: .IR cat (1)
616: command simply dumps \s8ASCII\s10 text
617: on the terminal, with no processing at all.
618: .IR More (1)
619: is useful for preventing the output of a command from
620: scrolling off the top of your screen.
621: It is also well suited to perusing files.
622: .IR Nroff (1)
623: is an elaborate text formatting program.
624: Used naked, it requires careful forethought, but for
625: ordinary documents it has been tamed; see
626: .IR me (7)
627: and
628: .IR ms (7).
629: .LP
630: .IR Troff (1)
631: prepares documents for a Graphics Systems phototypesetter
632: or a Versatec Plotter;
633: it is similar to
634: .IR nroff (1),
635: and often works from exactly the same source text.
636: It was used to produce this manual.
637: .LP
638: .IR Script (1)
639: lets you keep a record of your session in a file,
640: which can then be printed, mailed, etc.
641: It provides the advantages of a hard-copy terminal
642: even when using a display terminal.
643: .LP
644: .I
645: Status inquiries.\ \
646: .R
647: Various commands exist to provide you with useful information.
648: .IR w (1)
649: prints a list of users currently logged in, and what they are doing.
650: .IR date (1)
651: prints the current time and date.
652: .IR ls (1)
653: will list the files in your directory or give
654: summary information about particular files.
655: .LP
656: .I
657: Surprises.\ \
658: .R
659: Certain commands provide inter-user communication.
660: Even if you do not plan to use them, it would be
661: well to learn something about them, because someone else may aim them at you.
662: .LP
663: To communicate with another user currently logged in,
664: .IR write (1)
665: or
666: .IR talk (1)
667: is used;
668: .IR mail (1)
669: will leave a message whose presence will be announced
670: to another user when they next log in.
671: The write-ups in the manual also suggest how to respond to
672: the these commands if you are a target.
673: .LP
674: If you use
675: .IR csh (1)
676: the key ^Z (control-Z) will cause jobs to ``stop''.
677: If this happens before you learn about it,
678: you can simply continue by saying ``fg'' (for foreground) to bring
679: the job back.
680: .SH
681: CONVERTING FROM 4.2BSD SYSTEMS
682: .LP
683: A detailed list of changes from the 4.2BSD to the 4.3BSD distributions
684: is contained in ``Bug Fixes and Changes in 4.3BSD'' (SMM:12),
685: and ``Changes to the Kernel in 4.3BSD'' (SMM:13).
686: Detailed conversion procedures are described in
687: ``Installing and Operating 4.3BSD on the VAX'' (SMM:1);
688: it also discusses changes from pre-4.2BSD systems.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.