UNIX
User’s Manual
Release 3.0
T. A. Dolotta
S. B. Olsson
A. G. Petruccelli
Editors
June 1980
Laboratory 364
Bell Telephone Laboratories, Incorporated
Murray Hill, NJ 07974
Copyright ©1980 Bell Telephone Laboratories, Inc.
UNIX is a Trademark of Bell Telephone Laboratories, Inc.
This manual was set on an AUTOLOGIC, Inc. APS-5 phototypesetter driven by the TROFF formatter operating under the UNIX system.
ACKNOWLEDGEMENTS
The form and much of the content of this manual come from the UNIX Programmer’s Manual−Seventh Edition (Volume 1), developed by M. D. McIlroy. In addition, parts of the present manual’s contents are descended from the UNIX Programmer’s Manual−Sixth Edition by K. Thompson and D. M. Ritchie (Bell Laboratories, May 1975), the UNIX/TS User’s Manual−Edition 1.1 by T. A. Dolotta and S. B. Olsson, eds. (Bell Laboratories, Jan. 1979), and the PWB/UNIX User’s Manual−Release 2.0 (Bell Laboratories, June 1979). P. E. Cannata and G. C. Vogel rewrote Section 2 for this edition. Many members of Centers 127 and 135, and of Laboratory 364 helped in the creation of this volume; their help is hereby gratefully acknowledged. Murray Hill, New JerseyT.A.D.
S.B.O.
A.G.P.
INTRODUCTION
This manual describes the features of UNIX. It provides neither a general overview of UNIX (for that, see “The UNIX Time-Sharing System,” BSTJ, Vol. 57, No. 6, Part 2, pp. 1905-29, by D. M. Ritchie and K. Thompson), nor details of the implementation of the system (see “UNIX Implementation,” BSTJ, same issue, pp. 1931-46). Not all commands, features, and facilities described in this manual are available in every UNIX system; for example, yacc(1) is usually not available in a UNIX system running on a PDP-11/23. When in doubt, consult your system’s administrator. This manual is divided into eight sections, some containing inter-filed sub-classes:
1.Commands and Application Programs:
1.General-Purpose Commands.
1C.Communications Commands.
1G.Graphics Commands.
1M.System Maintenance Commands.
2.System Calls.
3.Subroutines:
3C.C and Assembler Library Routines.
3M.Mathematical Library Routines.
3S.Standard I/O Library Routines.
3X.Miscellaneous Routines.
4.Special Files.
5.File Formats.
6.Games.
7.Miscellaneous Facilities.
8.System Maintenance Procedures.
Section 1 (Commands and Application Programs) describes programs intended to be invoked directly by the user or by command language procedures, as opposed to subroutines, which are intended to be called by the user’s programs. Commands generally reside in the directory /bin (for binary programs). Some programs also reside in /usr/bin, to save space in /bin. These directories are searched automatically by the command interpreter called the shell. Sub-class 1C contains communication programs such as cu, dpr, fget, etc. These entries may differ from system to system. Sub-class 1M contains system maintenance programs such as fsck, mkfs, etc., which generally reside in the directory /etc; these commands are not intended for use by the ordinary user due to their privileged nature. Some UNIX systems have a directory called /usr/lbin, containing local commands. Section 2 (System Calls) describes the entries into the UNIX supervisor, including the C language interface. Section 3 (Subroutines) describes the available subroutines. Their binary versions reside in various system libraries in the directories /lib and /usr/lib. See intro(3) for descriptions of these libraries and the files in which they are stored. Section 4 (Special Files) discusses the characteristics of each system file that actually refers to an input/output device. The names in this section generally refer to the Digital Equipment Corporation’s device names for the hardware, rather than to the names of the special files themselves. Section 5 (File Formats) documents the structure of particular kinds of files; for example, the format of the output of the link editor is given in a.out(5). Excluded are files used by only one command (for example, the assembler’s intermediate files). In general, the C language struct declarations corresponding to these formats can be found in the directories /usr/include and /usr/include/sys. Section 6 (Games) describes the games and educational programs that, as a rule, reside in the directory /usr/games. Section 7 (Miscellaneous Facilities) contains a variety of things. Included are descriptions of character sets, macro packages, etc. Section 8 (System Maintenance Procedures) discusses crash recovery and boot procedures, etc. Information in this section is not of great interest to most users. Each section consists of a number of independent entries of a page or so each. The name of the entry appears in the upper corners of its pages. Entries within each section are alphabetized, with the exception of the introductory entry that begins each section. The page numbers of each entry start at 1. Some entries may describe several routines, commands, etc. In such cases, the entry appears only once, alphabetized under its “major” name. All entries are based on a common format, not all of whose parts always appear:
The NAME part gives the name(s) of the entry and briefly states its purpose. The SYNOPSIS part summarizes the use of the program being described. A few conventions are used, particularly in Section 1 (Commands):
Boldface strings are literals and are to be typed just as they appear. Italic strings usually represent substitutable argument prototypes and program names found elsewhere in the manual (they are underlined in the typed version of the entries). Square brackets [] around an argument prototype indicate that the argument is optional. When an argument prototype is given as “name” or “file”, it always refers to a file name. Ellipses ... are used to show that the previous argument prototype may be repeated. A final convention is used by the commands themselves. An argument beginning with a minus −, plus +, or equal sign = is often taken to be some sort of flag 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 −, +, or =.
The DESCRIPTION part discusses the subject at hand. The EXAMPLE(S) part gives example(s) of usage, where appropriate. The FILES part gives the file names that are built into the program. The SEE ALSO part gives pointers to related information. The DIAGNOSTICS part discusses the diagnostic indications that may be produced. Messages that are intended to be self-explanatory are not listed. The WARNINGS part points out potential pitfalls. The BUGS part gives known bugs and sometimes deficiencies. Occasionally, the suggested fix is also described.
A table of contents and a permuted index derived from that table precede Section 1. On each index line, the title of the entry to which that line refers is followed by the appropriate section number in parentheses. This is important because there is considerable duplication of names among the sections, arising principally from commands that exist only to exercise a particular system call. On most systems, all entries are available on-line via the man(1) command, q.v.
HOW TO GET STARTED
This discussion provides the basic information you need to get started on UNIX: how to log in and log out, how to communicate through your terminal, and how to run a program. (See UNIX for Beginners by B. W. Kernighan for a more complete introduction to the system.) Logging in. You must dial up UNIX from an appropriate terminal. UNIX supports full-duplex ASCII terminals. You must also have a valid user name, which may be obtained (together with the telephone number(s) of your UNIX system) from the administrator of your system. Common terminal speeds are 10, 15, 30, and 120 characters per second (110, 150, 300, and 1,200 baud); occasionally, speeds of 240, 480, and 960 characters per second (2,400, 4,800, and 9,600 baud) are also available. On some UNIX systems, there are separate telephone numbers for each available terminal speed, while on other systems several speeds may be served by a single telephone number. In the latter case, there is one “preferred” speed; if you dial in from a terminal set to a different speed, you will be greeted by a string of meaningless characters (the login: message at the wrong speed). Keep hitting the “break” or “attention” key until the login: message appears. Hard-wired terminals usually are set to the correct speed. Most terminals have a speed switch that should be set to the appropriate speed and a half-/full-duplex switch that should be set to full-duplex. When a connection (at the speed of the terminal) has been established, the system types login: and you then type your user name followed by the “return” key. If you have a password (and you should!), the system asks for it, but does not print (“echo”) it on the terminal. After you have logged in, the “return”, “new-line”, and “line-feed” keys will give exactly the same result. It is important that you type your login name in lower case if possible; if you type upper-case letters, UNIX will assume that your terminal cannot generate lower-case letters and that you mean all subsequent upper-case input to be treated as lower case. When you have logged in successfully, the shell will type a $ to you. (The shell is described below under How to run a program.) For more information, consult login(1) and getty(8), which discuss the login sequence in more detail, and stty(1), which tells you how to describe the characteristics of your terminal to the system (profile(5) explains how to accomplish this last task automatically every time you log in). Logging out. There are two ways to log out:
1. You can simply hang up the phone.
2. You can log out by typing an end-of-file indication (ASCII EOT character, usually typed as “control-d”) to the shell. The shell will terminate and the login: message will appear again.
How to communicate through your terminal. When you type to UNIX, a gnome deep in the system is gathering your characters and saving them. These characters will not be given to a program until you type a “return” (or “new-line”), as described above in Logging in. UNIX terminal input/output 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 output will have interspersed in it the input characters. However, whatever you type will be saved and interpreted in the 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. On an input line from a terminal, the character @ “kills” all the characters typed before it. The character # erases the last character typed. Successive uses of # will erase characters back to, but not beyond, the beginning of the line; @ and # can be typed as themselves by preceding them with \ (thus, to erase a \, you need two #s). These default erase and kill characters can be changed; see stty(1). The ASCII DC3 (control-s) character can be used to temporarily stop output. It is useful with CRT terminals to prevent output from disappearing before it can be read. Output is resumed when a DC1 (control-q) or a second DC3 (or any other character, for that matter) is typed. The DC1 and DC3 characters are not passed to any other program when used in this manner. The ASCII DEL (a.k.a. “rubout”) character is not passed to programs, but instead generates an interrupt signal, just like the “break”, “interrupt”, or “attention” signal. This signal generally causes whatever program you are running to terminate. It is typically used to stop a long printout that you don’t want. However, programs can arrange either to ignore this signal altogether, or to be notified when it happens (instead of being terminated). The editor ed(1), 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 quit signal is generated by typing the ASCII FS character. 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. Besides adapting to the speed of the terminal, UNIX tries to be intelligent as to whether you have a terminal with the “new-line” function, or whether it must be simulated with a “carriage-return” and “line-feed” pair. In the latter case, all input “carriage-return” characters are changed to “line-feed” characters (the standard line delimiter), and a “carriage-return” and “line-feed” pair is echoed to the terminal. If you get into the wrong mode, the stty(1) command will rescue you. Tab characters are used freely in UNIX source programs. If your terminal does not have the tab function, you can arrange to have tab characters changed into spaces during output, and echoed as spaces during input. Again, the stty(1) command will set or reset this mode. The system assumes that tabs are set every eight character positions. The tabs(1) command will set tab stops on your terminal, if that is possible. How to run a program. When you have successfully logged into UNIX, a program called the shell is listening to your terminal. The shell reads the lines you type, splits them into a command name and its arguments, and executes the command. A command is simply an executable program. Normally, the shell looks first in your current directory (see The current directory below) for a program with the given name, and if none is there, then in system directories. There is nothing special about system-provided commands except that they are kept in directories where the shell can find them. You can also keep commands in your own directories and arrange for the shell to find them there. The command name is the first word on an input line to the shell; the command and its arguments are separated from one another by space and/or tab characters. When a program terminates, the shell will ordinarily regain control and type a $ at you to indicate that it is ready for another command. The shell has many other capabilities, which are described in detail in sh(1). The current directory. UNIX has a file system arranged in a hierarchy of directories. When the system administrator gave you a user name, he or she also created a directory for you (ordinarily with the same name as your user name, and known as your login or home directory). When you log in, that directory becomes your current or working directory, and any file name you type is by default assumed to be in that directory. Because you are the owner of this directory, you have full permissions 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 respective owners, or by the system administrator. To change the current directory use cd(1). Path names. To refer to files not in the current directory, you must use a path name. Full path names begin with /, which is 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 (e.g., /usr/ae/filex refers to file filex in directory ae, while ae is itself a subdirectory of usr; usr springs directly from the root directory). See intro(2) for a formal definition of path name. If your current directory contains subdirectories, the path names of files therein begin with the name of the corresponding subdirectory (without a prefixed /). Without important exception, a path name may be used anywhere a file name is required. Important commands that modify the contents of files are cp(1), mv(1), and rm(1), which respectively copy, move (i.e., rename), and remove files. To find out the status of files or directories, use ls(1). Use mkdir(1) for making directories and rmdir(1) for destroying them. For a fuller discussion of the file system, see the references cited at the beginning of the INTRODUCTION above. It may also be useful to glance through Section 2 of this manual, which discusses system calls, even if you don’t intend to deal with the system at that level. Writing a program. To enter the text of a source program into a UNIX file, use ed(1). The four principal languages available under UNIX are C (see cc(1)), Fortran (see f77(1)), bs (a compiler/interpreter in the spirit of Basic, see bs(1)), and assembly language (see as(1)). After the program text has been entered with the editor and written into a file (whose name has the appropriate suffix), you can give the name of that file to the appropriate language processor as an argument. Normally, the output of the language processor will be left in a file in the current directory named a.out (if that output is precious, use mv(1) to give it a less vulnerable name). If the program is written in assembly language, you will probably need to load with it library subroutines (see ld(1)). Fortran and C call the loader automatically; programs written in bs(1) are interpreted and, therefore, do not need to be loaded. 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 $ prompt. If any execution (run-time) errors occur, you will need adb(1) to examine the remains of your program. On the VAX-11/780, a second debugger sdb(1), which allows you to step through C statements rather than assembler instructions, is available. Your programs can receive arguments from the command line just as system programs do; see exec(2). Text processing. Almost all text is entered through the editor ed(1). The commands most often used to write text on a terminal are cat(1), pr(1), and nroff(1). The cat(1) command simply dumps ASCII text on the terminal, with no processing at all. The pr(1) command paginates the text, supplies headings, and has a facility for multi-column output. Nroff(1) is an elaborate text formatting program, and requires careful forethought in entering both the text and the formatting commands into the input file; it produces output on a typewriter-like terminal. Troff(1) is very similar to nroff(1), but produces its output on a phototypesetter (it was used to typeset this manual). There are several “macro” packages (especially the so-called mm package) that significantly ease the effort required to use nroff(1) and troff(1); Section 7 entries for these packages indicate where you can find their detailed descriptions. Surprises. 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. To communicate with another user currently logged in, write(1) is used; mail(1) will leave a message whose presence will be announced to another user when he or she next logs in. The corresponding entries in this manual also suggest how to respond to these two commands if you are their target. When you log in, a message-of-the-day may greet you before the first $.
May 16, 1980