1INTRODUCTION TO VOLUME 1(0) INTRODUCTION TO VOLUME 1(0)
2 This volume gives descriptions of the publicly available features of
6 the UNIX system. It does not attempt to provide perspective or tuto‐
7 rial information upon the UNIX operating system, its facilities, or its
8 implementation. Various documents on those topics are contained in
9 Volume 2. In particular, for an overview see `The UNIX Time-Sharing
10 System' by Ritchie and Thompson; for a tutorial see `UNIX for Begin‐
11 ners' by Kernighan.
12 Within the area it surveys, this volume attempts to be timely, complete
14 and concise. Where the latter two objectives conflict, the obvious is
15 often left unsaid in favor of brevity. It is intended that each pro‐
16 gram be described as it is, not as it should be. Inevitably, this
17 means that various sections will soon be out of date.
18 The volume is divided into eight sections: 1. Commands 2. System
20 calls 3. Subroutines 4. Special files 5. File formats and conven‐
21 tions 6. Games 7. Macro packages and language conventions
22 8. Maintenance Commands are programs intended to be invoked directly
23 by the user, in contradistinction to subroutines, which are intended to
24 be called by the user's programs. Commands generally reside in direc‐
25 tory /bin (for binary programs). Some programs also reside in
26 /usr/bin, to save space in /bin. These directories are searched auto‐
27 matically by the command interpreter.
28 System calls are entries into the UNIX supervisor. Every system call
30 has one or more C language interfaces described in section 2. The
31 underlying assembly language interface, coded with opcode sys, a syn‐
32 onym for trap, is given as well.
33 An assortment of subroutines is available; they are described in sec‐
35 tion 3. The primary libraries in which they are kept are described in
36 intro(3). The functions are described in terms of C, but most will
37 work with Fortran as well.
38 The special files section 4 discusses the characteristics of each sys‐
40 tem `file' that actually refers to an I/O device. The names in this
41 section refer to the DEC device names for the hardware, instead of the
42 names of the special files themselves.
43 The file formats and conventions section 5 documents the structure of
45 particular kinds of files; for example, the form of the output of the
46 loader and assembler is given. Excluded are files used by only one
47 command, for example the assembler's intermediate files.
48 Games have been relegated to section 6 to keep them from contaminating
50 the more staid information of section 1.
51 Section 7 is a miscellaneous collection of information necessary to
53 writing in various specialized languages: character codes, macro pack‐
54 ages for typesetting, etc.
55 The maintenance section 8 discusses procedures not intended for use by
57 the ordinary user. These procedures often involve use of commands of
58 section 1, where an attempt has been made to single out peculiarly
59 maintenance-flavored commands by marking them 1M.
60 Each section consists of a number of independent entries of a page or
62 so each. The name of the entry is in the upper corners of its pages,
63 together with the section number, and sometimes a letter characteristic
64 of a subcategory, e.g. graphics is 1G, and the math library is 3M.
65 Entries within each section are alphabetized. The page numbers of each
66 entry start at 1; it is infeasible to number consecutively the pages of
67 a document like this that is republished in many variant forms.
68 All entries are based on a common format, not all of whose subsections
70 will always appear.
71 The name subsection lists the exact names of the commands and
73 subroutines covered under the entry and gives a very short
74 description of their purpose.
75 The synopsis summarizes the use of the program being described.
77 A few conventions are used, particularly in the Commands subsec‐
78 tion:
79 Boldface words are considered literals, and are typed
81 just as they appear.
82 Square brackets [ ] around an argument indicate that the
84 argument is optional. When an argument is given as
85 `name', it always refers to a file name.
86 Ellipses `...' are used to show that the previous argu‐
88 ment-prototype may be repeated.
89 A final convention is used by the commands themselves.
91 An argument beginning with a minus sign `-' is often
92 taken to mean some sort of option-specifying argument
93 even if it appears in a position where a file name could
94 appear. Therefore, it is unwise to have files whose
95 names begin with `-'.
96 The description subsection discusses in detail the subject at
98 hand.
99 The files subsection gives the names of files which are built
101 into the program.
102 A see also subsection gives pointers to related information.
104 A diagnostics subsection discusses the diagnostic indications
106 which may be produced. Messages which are intended to be self-
107 explanatory are not listed.
108 The bugs subsection gives known bugs and sometimes deficiencies.
110 Occasionally also the suggested fix is described.
111 In section 2 an assembler subsection carries the assembly lan‐
113 guage system interface.
114 At the beginning of the volume is a table of contents, organized by
116 section and alphabetically within each section. There is also a per‐
117 muted index derived from the table of contents. Within each index
118 entry, the title of the writeup to which it refers is followed by the
119 appropriate section number in parentheses. This fact is important
120 because there is considerable name duplication among the sections,
121 arising principally from commands which exist only to exercise a par‐
122 ticular system call.
123
125 This section sketches the basic information you need to get started on
126 : how to log in and log out, how to communicate through your terminal,
127 and how to run a program. See `UNIX for Beginners' in Volume 2 for a
128 more complete introduction to the system.
129 Logging in. You must call UNIX from an appropriate terminal. UNIX
131 terminals are typified by the TTY 43, the GE Terminet 300, the DASI
132 300S and 450, and most video terminals such as the Datamedia 5120 or HP
133 2640. You must also have a valid user name, which may be obtained,
134 together with the telephone number, from the system administrators.
135 The same telephone number serves terminals operating at all the stan‐
136 dard speeds. After a data connection is established, the login proce‐
137 dure depends on what kind of terminal you are using.
138 300-baud terminals: Such terminals include the GE Terminet 300 and
140 most display terminals run with popular modems. These terminals gener‐
141 ally have a speed switch which should be set at `300' (or `30' for 30
142 characters per second) and a half/full duplex switch which should be
143 set at full-duplex. (This switch will often have to be changed since
144 many other systems require half-duplex). When a connection is estab‐
145 lished, the system types `login:'; you type your user name, followed by
146 the `return' key. If you have a password, the system asks for it and
147 turns off the printer on the terminal so the password will not appear.
148 After you have logged in, the `return', `new line', or `linefeed' keys
149 will give exactly the same results.
150 1200- and 150-baud terminals: If there is a half/full duplex switch,
152 set it at full-duplex. When you have established a data connection,
153 the system types out a few garbage characters (the `login:' message at
154 the wrong speed). Depress the `break' (or `interrupt') key; this is a
155 speed-independent signal to UNIX that a different speed terminal is in
156 use. The system then will type `login:,' this time at another speed.
157 Continue depressing the break key until `login:' appears in clear, then
158 respond with your user name. From the TTY 37 terminal, and any other
159 which has the `newline' function (combined carriage return and line‐
160 feed), terminate each line you type with the `new line' key, otherwise
161 use the `return' key.
162 Hard-wired terminals. Hard-wired terminals usually begin at the right
164 speed, up to 9600 baud; otherwise the preceding instructions apply.
165 For all these terminals, it is important that you type your name in
167 lower-case if possible; if you type upper-case letters, UNIX will
168 assume that your terminal cannot generate lower-case letters and will
169 translate all subsequent upper-case letters to lower case.
170 The evidence that you have successfully logged in is that the Shell
172 program will type a `$' to you. (The Shell is described below under
173 `How to run a program.')
174 For more information, consult stty(1), which tells how to adjust termi‐
176 nal behavior, getty(8), which discusses the login sequence in more
177 detail, and tty(4), which discusses terminal I/O.
178 Logging out. There are three ways to log out:
180 You can simply hang up the phone.
182 You can log out by typing an end-of-file indication (EOT charac‐
184 ter, control-d) to the Shell. The Shell will terminate and the
185 `login: ' message will appear again.
186 You can also log in directly as another user by giving a
188 login(1) command.
189 How to communicate through your terminal. When you type characters, a
191 gnome deep in the system gathers your characters and saves them in a
192 secret place. The characters will not be given to a program until you
193 type a return (or newline), as described above in Logging in.
194 UNIX terminal I/O is full-duplex. It has full read-ahead, which means
196 that you can type at any time, even while a program is typing at you.
197 Of course, if you type during output, the printed output will have the
198 input characters interspersed. However, whatever you type will be
199 saved up and interpreted in correct sequence. There is a limit to the
200 amount of read-ahead, but it is generous and not likely to be exceeded
201 unless the system is in trouble. When the read-ahead limit is
202 exceeded, the system throws away all the saved characters.
203 The character `@' in typed input kills all the preceding characters in
205 the line, so typing mistakes can be repaired on a single line. Also,
206 the character `#' erases the last character typed. Successive uses of
207 `#' erase characters back to, but not beyond, the beginning of the
208 line. `@' and `#' can be transmitted to a program by preceding them
209 with `\'. (So, to erase `\', you need two `#'s). These conventions
210 can be changed by the stty(1) command.
211 The `break' or `interrupt' key causes an interrupt signal, as does the
213 The ASCII `delete' (or `rubout') character, which is not passed to pro‐
214 grams. This signal generally causes whatever program you are running
215 to terminate. It is typically used to stop a long printout that you
216 don't want. However, programs can arrange either to ignore this signal
217 altogether, or to be notified when it happens (instead of being termi‐
218 nated). The editor, for example, catches interrupts and stops what it
219 is doing, instead of terminating, so that an interrupt can be used to
220 halt an editor printout without losing the file being edited.
221 The quit signal is generated by typing the ASCII FS character. (FS
223 appears many places on different terminals, most commonly as control-\
224 or control-|.) It not only causes a running program to terminate but
225 also generates a file with the core image of the terminated process.
226 Quit is useful for debugging.
227 Besides adapting to the speed of the terminal, UNIX tries to be intel‐
229 ligent about whether you have a terminal with the newline function or
230 whether it must be simulated with carriage-return and line-feed. In
231 the latter case, all input carriage returns are turned to newline char‐
232 acters (the standard line delimiter) and both a carriage return and a
233 line feed are echoed to the terminal. If you get into the wrong mode,
234 the stty(1) command will rescue you.
235 Tab characters are used freely in UNIX source programs. If your termi‐
237 nal does not have the tab function, you can arrange to have them turned
238 into spaces during output, and echoed as spaces during input. The sys‐
239 tem assumes that tabs are set every eight columns. Again, the stty(1)
240 command will set or reset this mode. Also, the command tabs(1) will
241 set the tab stops automatically on many terminals.
242 How to run a program; the Shell. When you have successfully logged
244 in, a program called the Shell is listening to your terminal. The
245 Shell reads typed-in lines, splits them up into a command name and
246 arguments, and executes the command. A command is simply an executable
247 program. The Shell looks first in your current directory (see below)
248 for a program with the given name, and if none is there, then in a sys‐
249 tem directory. There is nothing special about system-provided commands
250 except that they are kept in a directory where the Shell can find them.
251 The command name is always the first word on an input line; it and its
253 arguments are separated from one another by spaces.
254 When a program terminates, the Shell will ordinarily regain control and
256 type a `$' at you to indicate that it is ready for another command.
257 The Shell has many other capabilities, which are described in detail in
259 section sh(1).
260 The current directory. UNIX has a file system arranged in a hierarchy
262 of directories. When the system administrator gave you a user name, he
263 also created a directory for you (ordinarily with the same name as your
264 user name). When you log in, any file name you type is by default in
265 this directory. Since you are the owner of this directory, you have
266 full permission to read, write, alter, or destroy its contents. Per‐
267 missions to have your will with other directories and files will have
268 been granted or denied to you by their owners. As a matter of observed
269 fact, few UNIX users protect their files from destruction, let alone
270 perusal, by other users.
271 To change the current directory (but not the set of permissions you
273 were endowed with at login) use cd(1).
274 Path names. To refer to files not in the current directory, you must
276 use a path name. Full path names begin with `/', the name of the root
277 directory of the whole file system. After the slash comes the name of
278 each directory containing the next sub-directory (followed by a `/')
279 until finally the file name is reached. For example, /usr/lem/filex
280 refers to the file filex in the directory lem; lem is itself a subdi‐
281 rectory of usr; usr springs directly from the root directory.
282 If your current directory has subdirectories, the path names of files
284 therein begin with the name of the subdirectory with no prefixed `/'.
285 A path name may be used anywhere a file name is required.
287 Important commands which modify the contents of files are cp(1), mv(1),
289 and rm(1), which respectively copy, move (i.e. rename) and remove
290 files. To find out the status of files or directories, use ls(1). See
291 mkdir(1) for making directories and rmdir (in rm(1)) for destroying
292 them.
293 For a fuller discussion of the file system, see `The UNIX Time-Sharing
295 System,' by Ken Thompson and Dennis Ritchie. It may also be useful to
296 glance through section 2 of this manual, which discusses system calls,
297 even if you don't intend to deal with the system at that level.
298 Writing a program. To enter the text of a source program into a UNIX
300 file, use the editor ed(1). The three principal languages in UNIX are
301 provided by the C compiler cc(1), the Fortran compiler f77(1), and the
302 assembler as(1). After the program text has been entered through the
303 editor and written on a file, you can give the file to the appropriate
304 language processor as an argument. The output of the language proces‐
305 sor will be left on a file in the current directory named `a.out'. (If
306 the output is precious, use mv to move it to a less exposed name
307 soon.) If you wrote in assembly language, you will probably need to
308 load the program with library subroutines; see ld(1). The other two
309 language processors call the loader automatically.
310 When you have finally gone through this entire process without provok‐
312 ing any diagnostics, the resulting program can be run by giving its
313 name to the Shell in response to the `$' prompt.
314 Your programs can receive arguments from the command line just as sys‐
316 tem programs do, see exec(2).
317 Text processing. Almost all text is entered through the editor ed(1).
319 The commands most often used to write text on a terminal are: cat, pr,
320 roff and nroff, all in section 1.
321 The cat command simply dumps ASCII text on the terminal, with no pro‐
323 cessing at all. The pr command paginates the text, supplies headings,
324 and has a facility for multi-column output. Nroff is an elaborate text
325 formatting program. Used naked, it requires careful forethought, but
326 for ordinary documents it has been tamed; see ms(7). Roff is a simpler
327 text formatting program, and requires somewhat less forethought.
328 Troff prepares documents for a Graphics Systems phototypesetter; it is
330 very similar to nroff, and often works from exactly the same source
331 text. It was used to produce this manual.
332 Status inquiries. Various commands exist to provide you with useful
334 information. Who(1) prints a list of users presently logged in.
335 Date(1) prints the current time and date. Ls(1) will list the files in
336 your directory or give summary information about particular files.
337 Surprises. Certain commands provide inter-user communication. Even
339 if you do not plan to use them, it would be well to learn something
340 about them, because someone else may aim them at you.
341 To communicate with another user currently logged in, write(1) is used;
343 mail(1) will leave a message whose presence will be announced to
344 another user when he next logs in. The write-ups in the manual also
345 suggest how to respond to the two commands if you are a target.
346 When you log in, a message-of-the-day may greet you before the first
348 `$'.
349
351 There follows a catalogue of significant, mostly incompatible, changes
352 that will affect old users converting to the 7th edition. No attempt
353 is made to list all new facilities, or even all minor, but easily spot‐
354 ted changes, just the bare essentials without which it will be almost
355 impossible to do anything.
356 Addressing files. Byte addresses in files are now long (32-bit) inte‐
358 gers. Accordingly seek has been replaced by lseek(2). Every program
359 that contains a seek must be modified. Stat and fstat(2) have been
360 affected similarly, since file lengths are now 32- rather than 24-bit
361 quantities.
362 Assembly language. System entry points are no longer built in sym‐
364 bols. Their values must be obtained from /usr/include/sys.s, see
365 intro(2). All system calls modify r0. This means that sequences like
366 mov file,r0 sys lseek,0,0,2 sys write,buf,n will no longer work.
367 (In fact, lseek now modifies r1 as well, so be doubly cautious.)
368 The sleep(2) entry point is gone; see the more general facility, alarm,
370 plus pause.
371 Few library functions have assembly language entry points any more.
373 You will have to simulate the C calling sequence.
374 Stty and gtty. These system calls have been extensively altered, see
376 ioctl(2) and tty(4).
377 Archive files. The format of files produced by ar(1) has been
379 altered. To convert to the new style, use arcv(1).
380 C language, lint. The official syntax for initialization requires an
382 equal sign = before an initializer, and brackets { } around compound
383 initial values; arrays and structures are now initialized honestly.
384 Two-address operators, such as =+ and =-, are now written += and -= to
385 avoid ambiguities, although the old style is still accepted. You will
386 also certainly want to learn about long integers type definitions casts
387 (for type conversion) unions (for more honest storage sharing) #include
388 <filename> (which searches in standard places)
389 The program lint(1) checks for obsolete syntax and does strong type
391 checking of C programs, singly or in groups that are expected to be
392 loaded together. It is indispensable for conversion work.
393 Fortran. The old fc is replaced by f77, a true compiler for Fortran
395 77, compatible with C. There are substantial changes in the language;
396 see `A Portable Fortran 77 Compiler' in Volume 2.
397 Stream editor. The program sed(1) is adapted to massive, repetitive
399 editing jobs of the sort encountered in converting to the new system.
400 It is well worth learning.
401 Standard I/O. The old fopen, getc, putc complex and the old -lp pack‐
403 age are both dead, and even getchar has changed. All have been
404 replaced by the clean, highly efficient, stdio(3) package. The first
405 things to know are that getchar(3) returns the integer EOF (-1), which
406 is not a possible byte value, on end of file, that 518-byte buffers are
407 out, and that there is a defined FILE data type.
408 Make. The program make(1) handles the recompilation and loading of
410 software in an orderly way from a `makefile' recipe given for each
411 piece of software. It remakes only as much as the modification dates
412 of the input files show is necessary. The makefiles will guide you in
413 building your new system.
414 Shell, chdir. F. L. Bauer once said Algol 68 is the Everest that must
416 be climbed by every computer scientist because it is there. So it is
417 with the shell for UNIX users. Everything beyond simple command invo‐
418 cation from a terminal is different. Even chdir is now spelled cd.
419 You will want to study sh(1) long and hard.
420 Debugging. Adb(1) is a far more capable replacement for the debugger
422 db. The first-time user should be especially careful about distin‐
423 guishing / and ? in adb commands, and watching to make sure that the x
424 whose value he asked for is the real x, and not just some absolute
425 location equal to the stack offset of some automatic x. You can always
426 use the `true' name, _x, to pin down a C external variable.
427 Dsw. This little-known, but indispensable facility has been taken over
429 by rm -ri.
430 Boot procedures. Needless to say, these are all different. See sec‐
432 tion 8 of this volume, and `Setting up UNIX' in Volume 2.
433 INTRODUCTION TO VOLUME 1(0)