UNIX PROGRAMMER'S MANUAL K. Thompson D. M. Ritchie November 3, 1971 INTRODUCTION This manual gives complete descriptions of all the publicly available features of UNIX. It provides neither a general over- view (see "The UNIX Time-sharing System" for that) nor details of the implementation of the system (which remain to be disclosed). Within the area it surveys, this manual attempts to be as com- plete and timely as possible. A conscious decision was made to describe each program in exactly the state it was in at the time its manual section was prepared. In particular, the desire to describe something as it should be, not as it is, was resisted. Inevitably, this means that many sections will soon be out of date. (The rate of change of the system is so great that a dis- mayingly large number of early sections had to be modified while the rest were being written. The unbounded effort required to stay up-to-date is best indicated by the fact that several of the programs described were written specifically to aid in prepara- tion of this manual!) This manual is divided into seven sections: I. Commands II. System calls III. Subroutines IV. Special files V. File formats VI. User-maintained programs VII. Miscellaneous Commands are programs intended to be invoked directly by the user, in contradistinction to subroutines, which are intended to be called by the user's programs. Commands generally reside in directory /bin (for binary programs). This directory is searched automatically by the command line interpreter. Some programs classified as commands are located elsewhere; this fact is indi- cated in the appropriate sections. System calls are entries into the UNIX supervisor. In assembly language, they are coded with the use of the opcode "sys", a syn- onym for the trap instruction. The special files section discusses the characteristics of each system "file" which actually refers to an I/O device. The file formats section documents the structure of particular kinds of files; for example, the form of the output of the loader and assembler is given. Excluded are files used by only one com- mand, for example the assembler's intermediate files. User-maintained programs are not considered part of the UNIX sys- tem, and the principal reason for listing them is o indicate their existence without necessarily giving a complte description. The author should be consulted for information. The miscellaneous section gathers odds and ends. Each section consists of a number of independent entries of a page or so each. The name of the entry is in the upper right corner of its pages, its preparation date in the upper left. En- tries within each section are alphabetized. It was thought bet- ter to avoid running page numbers, since it is hoped that the manual will be updated frequently. All entries have a common format. The name section repeats the entry name and gives a very short description of its purpose. The synopsis summarizes the use of the program being de- scribed. A few conventions are used, particularly in the Commands section: Underlined words are considered literals, and are typed just as they appear. Square brackets ([]) around an argument indicate that the argument is optional. When an argument is given as "name", 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 sign "-" is often tak- en to mean 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 "-". The description section discusses in detail the subject at hand. The files section gives the names of files which are built into the program. A see also section gives pointers to related information. A diagnostics section discusses the diagnostics that may be produced. This section tends to be as terse as the diagnos- tics themselves. The bugs section gives known bugs and sometimes deficien- cies. Occasionally also the suggested fix is described. The owner section gives the name of the person or persons to be consulted in case of difficulty. The rule has been that the last one to modify something owns it, so the owner is not necessarily the author. The owner's initials stand for: ken K. Thompson dmr D. M. Ritchie jfo J. F. Ossanna rhm R. Morris These three-character names also happen to be UNIX user ID's, so messages may be transmitted by the mail command or, if the addressee is logged in, by write. At the beginning of this document is a table of contents, orga- nized by section and alphabetically within each section. There is also a permuted index derived from the table of contents. Within each index entry, the title of the writeup to which it refers is followed by the appropriate section number in parenthe- ses. This fact is important because there is considerable name duplication among the sections, arising principally from commands which exist only to exercise a particular system call. This manual was prepared using the UNIX text editor ed and the formatting program roff. TABLE OF CONTENTS I. COMMANDS ar ........................... archive (combine) files as ........................... assembler b ............................ compile B program bas .......................... BASIC dialect bcd .......................... convert ASCII to BCD boot ......................... reboot system cat .......................... concatenate (or print) files chdir ........................ change working directory check ........................ check consistency of file system chmod ........................ change access mode of files chown ........................ change owner of files cmp .......................... compare file contents cp ........................... copy file date ......................... get date and time of day db ........................... symbolic debugger dbppt ........................ write binary paper tape dc ........................... desk calculator df ........................... find free disk space dsw .......................... delete files interactively dtf .......................... format DECtape du ........................... find disk usage ed ........................... text editor find ......................... find file with given name for .......................... compile Fortran program form ......................... generate form letter hup .......................... hang up typewriter lbppt ........................ read binary paper tape ld ........................... link editor (loader) ln ........................... link to file ls ........................... list contents of directory mail ......................... send mail to another user mesg ......................... permit or deny messages mkdir ........................ create directory mkfs ......................... initialize file system mount ........................ mount removable file system mv ........................... move or rename file nm ........................... print namelist od ........................... octal dump of file pr ........................... print file with headings rew .......................... rewind DECtape rkd .......................... dump disk to tape rkf .......................... format RK disk rkl .......................... load disk from tape rm ........................... remove (delete) file rmdir ........................ remove (delete) directory roff ......................... format text for printing sdate ........................ adjust date and time sh ........................... command interpreter stat ......................... get file status strip ........................ remove symbols, relocation bits su ........................... become super-user sum .......................... sum file tap .......................... manipulate DECtape tm ........................... get time information tty .......................... find name of terminal type ......................... print file page-by-page umount ....................... dismount removable file system un ........................... find undefined symbols wc ........................... get (English) word count who .......................... who is on the system write ........................ write to another user II. SYSTEM CALLS break ........................ set program break cemt ......................... catch EMT traps chdir ........................ change working directory chmod ........................ change mode of file chown ........................ change owner of file close ........................ close open file creat ........................ create file exec ......................... execute program file exit ......................... terminate execution fork ......................... create new process fstat ........................ status of open file getuid ....................... get user ID gtty ......................... get typewriter mode ilgins ....................... catch illegal instruction trap intr ......................... catch or inhibit interrupts link ......................... link to file mkdir ........................ create directory mount ........................ mount file system open ......................... open file quit ......................... catch or inhibit quits read ......................... read file rele ......................... release processor seek ......................... move read or write pointer setuid ....................... set user ID smdate ....................... set date modified of file stat ......................... get file status stime ........................ set system time stty ......................... set mode of typewriter tell ......................... find read or write pointer time ......................... get time of year umount ....................... dismount file system unlink ....................... remove (delete) file wait ......................... wait for process write ........................ write file III. SUBROUTINES atof ......................... convert ASCII to floating atoi ......................... convert ASCII to integer ctime ........................ convert time to ASCII exp .......................... exponential function fptrap ....................... floating-point simulator ftoa ......................... convert floating to ASCII get .......................... get character itoa ......................... convert integer to ASCII log .......................... logarithm base e mesg ......................... print string on typewriter ptime ........................ print time putc ......................... write character or word sin .......................... sine, cosine switch ....................... transfer depending on value IV. SPECIAL FILES mem .......................... core memory as file ppt .......................... punched paper tape rf0 .......................... RF disk file rk0 .......................... RK disk file tap0,...,tap7 ................ DECtape file tty .......................... console typewriter tty0,...,tty5 ................ remote typewriter V. FILE FORMATS a.out ........................ assembler and loader output archive ...................... archive file bppt ......................... binary paper tape format core ......................... core image file directory .................... directory format file system .................. file system format passwd ....................... password file uids ......................... map names to user ID's utmp ......................... logged-in user information VI. USER MAINTAINED PROGRAMS basic ........................ DEC supplied BASIC bj ........................... the game of blackjack cal .......................... print calender chess ........................ the game of chess das .......................... disassembler dli .......................... load DEC binary paper tapes dpt .......................... read DEC ASCII paper tapes moo .......................... the game of MOO sort ......................... sort a file ttt .......................... the game of tic-tac-toe VII. MISCELLANEOUS as2 .......................... assembler's pass 2 ascii ........................ map of ASCII ba ........................... B assembler bc ........................... B compiler bilib ........................ B interpreter library bproc ........................ boot procedure brt1,brt2 .................... B start and finish f1,f2,f3,f4 .................. Fortran compiler passes glob ......................... argument expander init ......................... initializer process kbd .......................... map of TTY 37 keyboard liba ......................... standard assembly-language library libb ......................... standard B library libf ......................... standard Fortran library login, logout ................ logging on and logging off the system msh .......................... mini Shell suftab ....................... roff's suffix table tabs ......................... set tab stops on typewriter INDEX as2(VII): assembler's pass 2 kbd(VII): map of TTY 37 keyboard chmod(I): change access mode of files sdate(I): adjust date and time mail(I): send mail to another user write(I): write to another user a.out(V): assembler and loader output ar(I): archive (combine) files archive(V): archive file archive(V): archive file glob(VII): argument expander ar(I): archive (combine) files as2(VII): assembler's pass 2 dpt(VI): read DEC ASCII paper tapes bcd(I): convert ASCII to BCD atof(III): convert ASCII to floating atoi(III): convert ASCII to integer ascii(VII): map of ASCII ctime(III): convert time to ASCII ftoa(III): convert floating to ASCII itoa(III): convert integer to ASCII ascii(VII): map of ASCII as(I): assembler a.out(V): assembler and loader output as(I): assembler ba(VII): B assembler as2(VII): assembler's pass 2 liba(VII): standard assembly-language library atof(III): convert ASCII to floating atoi(III): convert ASCII to integer ba(VII): B assembler bc(VII): B compiler bilib(VII): B interpreter library libb(VII): standard B library b(I): compile B program brt1,brt2(VII): B start and finish log(III): logarithm base e bas(I): BASIC dialect bas(I): BASIC dialect basic(VI): DEC supplied BASIC basic(VI): DEC supplied BASIC ba(VII): B assembler bcd(I): convert ASCII to BCD bcd(I): convert ASCII to BCD bc(VII): B compiler su(I): become super-user b(I): compile B program bilib(VII): B interpreter library bppt(V): binary paper tape format dbppt(I): write binary paper tape lbppt(I): read binary paper tape dli(VI): load DEC binary paper tapes strip(I): remove symbols, relocation bits bj(VI): the game of blackjack bj(VI): the game of blackjack bproc(VII): boot procedure boot(I): reboot system bppt(V): binary paper tape format bproc(VII): boot procedure break(II): set program break break(II): set program break brt1,brt2(VII): B start and finish dc(I): desk calculator cal(VI): print calender cal(VI): print calender cemt(II): catch EMT traps ilgins(II): catch illegal instruction trap intr(II): catch or inhibit interrupts quit(II): catch or inhibit quits cat(I): concatenate (or print) files cemt(II): catch EMT traps chmod(I): change access mode of files chmod(II): change mode of file chown(II): change owner of file chown(I): change owner of files chdir(I): change working directory chdir(II): change working directory putc(III): write character or word get(III): get character chdir(I): change working directory chdir(II): change working directory check(I): check consistency of file system check(I): check consistency of file system chess(VI): the game of chess chess(VI): the game of chess chmod(I): change access mode of files chmod(II): change mode of file chown(I): change owner of files chown(II): change owner of file close(II): close open file close(II): close open file cmp(I): compare file contents ar(I): archive (combine) files sh(I): command interpreter cmp(I): compare file contents b(I): compile B program for(I): compile Fortran program f1,f2,f3,f4(VII): Fortran compiler passes bc(VII): B compiler cat(I): concatenate (or print) files check(I): check consistency of file system tty(IV): console typewriter ls(I): list contents of directory cmp(I): compare file contents bcd(I): convert ASCII to BCD atof(III): convert ASCII to floating atoi(III): convert ASCII to integer ftoa(III): convert floating to ASCII itoa(III): convert integer to ASCII ctime(III): convert time to ASCII cp(I): copy file core(V): core image file mem(IV): core memory as file core(V): core image file sin(III): sine, cosine wc(I): get (English) word count cp(I): copy file mkdir(I): create directory mkdir(II): create directory creat(II): create file fork(II): create new process creat(II): create file ctime(III): convert time to ASCII das(VI): disassembler date(I): get date and time of day sdate(I): adjust date and time smdate(II): set date modified of file date(I): get date and time of day date(I): get date and time of day db(I): symbolic debugger dbppt(I): write binary paper tape dc(I): desk calculator db(I): symbolic debugger dpt(VI): read DEC ASCII paper tapes dli(VI): load DEC binary paper tapes basic(VI): DEC supplied BASIC tap0,...,tap7(IV): DECtape file dtf(I): format DECtape rew(I): rewind DECtape tap(I): manipulate DECtape rmdir(I): remove (delete) directory rm(I): remove (delete) file dsw(I): delete files interactively unlink(II): remove (delete) file mesg(I): permit or deny messages switch(III): transfer depending on value dc(I): desk calculator df(I): find free disk space bas(I): BASIC dialect directory(V): directory format chdir(I): change working directory chdir(II): change working directory ls(I): list contents of directory mkdir(I): create directory mkdir(II): create directory rmdir(I): remove (delete) directory directory(V): directory format das(VI): disassembler rf0(IV): RF disk file rk0(IV): RK disk file rkl(I): load disk from tape df(I): find free disk space rkd(I): dump disk to tape du(I): find disk usage rkf(I): format RK disk umount(II): dismount file system umount(I): dismount removable file system dli(VI): load DEC binary paper tapes dpt(VI): read DEC ASCII paper tapes dsw(I): delete files interactively dtf(I): format DECtape du(I): find disk usage rkd(I): dump disk to tape od(I): octal dump of file ed(I): text editor ld(I): link editor (loader) ed(I): text editor log(III): logarithm base e cemt(II): catch EMT traps wc(I): get (English) word count exec(II): execute program file exec(II): execute program file exit(II): terminate execution exit(II): terminate execution glob(VII): argument expander exp(III): exponential function exp(III): exponential function f1,f2,f3,f4(VII): Fortran compiler passes cmp(I): compare file contents type(I): print file page-by-page stat(I): get file status stat(II): get file status file system(V): file system format check(I): check consistency of file system mkfs(I): initialize file system mount(I): mount removable file system mount(II): mount file system umount(I): dismount removable file system umount(II): dismount file system file system(V): file system format find(I): find file with given name pr(I): print file with headings archive(V): archive file chmod(II): change mode of file chown(II): change owner of file close(II): close open file core(V): core image file cp(I): copy file creat(II): create file exec(II): execute program file fstat(II): status of open file link(II): link to file ln(I): link to file mem(IV): core memory as file mv(I): move or rename file od(I): octal dump of file open(II): open file passwd(V): password file read(II): read file rf0(IV): RF disk file rk0(IV): RK disk file rm(I): remove (delete) file dsw(I): delete files interactively ar(I): archive (combine) files cat(I): concatenate (or print) files chmod(I): change access mode of files chown(I): change owner of files smdate(II): set date modified of file sort(VI): sort a file sum(I): sum file tap0,...,tap7(IV): DECtape file unlink(II): remove (delete) file write(II): write file du(I): find disk usage find(I): find file with given name df(I): find free disk space tty(I): find name of terminal tell(II): find read or write pointer un(I): find undefined symbols find(I): find file with given name brt1,brt2(VII): B start and finish ftoa(III): convert floating to ASCII atof(III): convert ASCII to floating fptrap(III): floating-point simulator for(I): compile Fortran program fork(II): create new process form(I): generate form letter dtf(I): format DECtape rkf(I): format RK disk roff(I): format text for printing bppt(V): binary paper tape format directory(V): directory format file system(V): file system format form(I): generate form letter f1,f2,f3,f4(VII): Fortran compiler passes libf(VII): standard Fortran library for(I): compile Fortran program fptrap(III): floating-point simulator df(I): find free disk space rkl(I): load disk from tape fstat(II): status of open file ftoa(III): convert floating to ASCII exp(III): exponential function bj(VI): the game of blackjack chess(VI): the game of chess moo(VI): the game of MOO ttt(VI): the game of tic-tac-toe form(I): generate form letter get(III): get character date(I): get date and time of day wc(I): get (English) word count stat(I): get file status stat(II): get file status tm(I): get time information time(II): get time of year gtty(II): get typewriter mode getuid(II): get user ID get(III): get character getuid(II): get user ID find(I): find file with given name glob(VII): argument expander gtty(II): get typewriter mode hup(I): hang up typewriter pr(I): print file with headings hup(I): hang up typewriter getuid(II): get user ID setuid(II): set user ID uids(V): map names to user ID's ilgins(II): catch illegal instruction trap ilgins(II): catch illegal instruction trap core(V): core image file tm(I): get time information utmp(V): logged-in user information intr(II): catch or inhibit interrupts quit(II): catch or inhibit quits mkfs(I): initialize file system init(VII): initializer process init(VII): initializer process ilgins(II): catch illegal instruction trap itoa(III): convert integer to ASCII atoi(III): convert ASCII to integer dsw(I): delete files interactively bilib(VII): B interpreter library sh(I): command interpreter intr(II): catch or inhibit interrupts intr(II): catch or inhibit interrupts itoa(III): convert integer to ASCII kbd(VII): map of TTY 37 keyboard kbd(VII): map of TTY 37 keyboard lbppt(I): read binary paper tape ld(I): link editor (loader) form(I): generate form letter liba(VII): standard assembly-language library libb(VII): standard B library libf(VII): standard Fortran library bilib(VII): B interpreter library liba(VII): standard assembly-language library libb(VII): standard B library libf(VII): standard Fortran library ld(I): link editor (loader) link(II): link to file ln(I): link to file link(II): link to file ls(I): list contents of directory ln(I): link to file dli(VI): load DEC binary paper tapes rkl(I): load disk from tape a.out(V): assembler and loader output ld(I): link editor (loader) log(III): logarithm base e utmp(V): logged-in user information log(III): logarithm base e ls(I): list contents of directory mail(I): send mail to another user mail(I): send mail to another user tap(I): manipulate DECtape uids(V): map names to user ID's ascii(VII): map of ASCII kbd(VII): map of TTY 37 keyboard mem(IV): core memory as file mem(IV): core memory as file mesg(I): permit or deny messages mesg(III): print string on typewriter mesg(I): permit or deny messages mkdir(I): create directory mkdir(II): create directory mkfs(I): initialize file system chmod(II): change mode of file chmod(I): change access mode of files stty(II): set mode of typewriter gtty(II): get typewriter mode smdate(II): set date modified of file moo(VI): the game of MOO moo(VI): the game of MOO mount(II): mount file system mount(I): mount removable file system mount(I): mount removable file system mount(II): mount file system mv(I): move or rename file seek(II): move read or write pointer mv(I): move or rename file tty(I): find name of terminal find(I): find file with given name nm(I): print namelist uids(V): map names to user ID's fork(II): create new process nm(I): print namelist od(I): octal dump of file od(I): octal dump of file close(II): close open file fstat(II): status of open file open(II): open file open(II): open file cat(I): concatenate (or print) files a.out(V): assembler and loader output chown(II): change owner of file chown(I): change owner of files type(I): print file page-by-page bppt(V): binary paper tape format dbppt(I): write binary paper tape lbppt(I): read binary paper tape ppt(IV): punched paper tape dli(VI): load DEC binary paper tapes dpt(VI): read DEC ASCII paper tapes as2(VII): assembler's pass 2 f1,f2,f3,f4(VII): Fortran compiler passes passwd(V): password file passwd(V): password file mesg(I): permit or deny messages seek(II): move read or write pointer tell(II): find read or write pointer ppt(IV): punched paper tape pr(I): print file with headings cal(VI): print calender type(I): print file page-by-page pr(I): print file with headings cat(I): concatenate (or print) files nm(I): print namelist mesg(III): print string on typewriter ptime(III): print time roff(I): format text for printing bproc(VII): boot procedure fork(II): create new process init(VII): initializer process rele(II): release processor wait(II): wait for process break(II): set program break exec(II): execute program file b(I): compile B program for(I): compile Fortran program ptime(III): print time ppt(IV): punched paper tape putc(III): write character or word quit(II): catch or inhibit quits quit(II): catch or inhibit quits lbppt(I): read binary paper tape dpt(VI): read DEC ASCII paper tapes read(II): read file seek(II): move read or write pointer tell(II): find read or write pointer read(II): read file boot(I): reboot system rele(II): release processor rele(II): release processor strip(I): remove symbols, relocation bits tty0,...,tty5(IV): remote typewriter mount(I): mount removable file system umount(I): dismount removable file system rmdir(I): remove (delete) directory rm(I): remove (delete) file unlink(II): remove (delete) file strip(I): remove symbols, relocation bits mv(I): move or rename file rew(I): rewind DECtape rew(I): rewind DECtape rf0(IV): RF disk file rf0(IV): RF disk file rk0(IV): RK disk file rkf(I): format RK disk rk0(IV): RK disk file rkd(I): dump disk to tape rkf(I): format RK disk rkl(I): load disk from tape rmdir(I): remove (delete) directory rm(I): remove (delete) file roff(I): format text for printing sdate(I): adjust date and time seek(II): move read or write pointer mail(I): send mail to another user smdate(II): set date modified of file stty(II): set mode of typewriter break(II): set program break stime(II): set system time setuid(II): set user ID setuid(II): set user ID sh(I): command interpreter fptrap(III): floating-point simulator sin(III): sine, cosine sin(III): sine, cosine smdate(II): set date modified of file sort(VI): sort a file sort(VI): sort a file df(I): find free disk space liba(VII): standard assembly-language library libb(VII): standard B library libf(VII): standard Fortran library brt1,brt2(VII): B start and finish stat(I): get file status stat(II): get file status fstat(II): status of open file stat(I): get file status stat(II): get file status stime(II): set system time mesg(III): print string on typewriter strip(I): remove symbols, relocation bits stty(II): set mode of typewriter su(I): become super-user sum(I): sum file sum(I): sum file su(I): become super-user basic(VI): DEC supplied BASIC switch(III): transfer depending on value db(I): symbolic debugger strip(I): remove symbols, relocation bits un(I): find undefined symbols file system(V): file system format stime(II): set system time boot(I): reboot system check(I): check consistency of file system mkfs(I): initialize file system mount(I): mount removable file system mount(II): mount file system umount(I): dismount removable file system umount(II): dismount file system file system(V): file system format who(I): who is on the system tap0,...,tap7(IV): DECtape file bppt(V): binary paper tape format dbppt(I): write binary paper tape lbppt(I): read binary paper tape ppt(IV): punched paper tape rkd(I): dump disk to tape rkl(I): load disk from tape dli(VI): load DEC binary paper tapes dpt(VI): read DEC ASCII paper tapes tap(I): manipulate DECtape tell(II): find read or write pointer tty(I): find name of terminal exit(II): terminate execution ed(I): text editor roff(I): format text for printing ttt(VI): the game of tic-tac-toe tm(I): get time information date(I): get date and time of day time(II): get time of year ctime(III): convert time to ASCII time(II): get time of year ptime(III): print time sdate(I): adjust date and time stime(II): set system time tm(I): get time information switch(III): transfer depending on value ilgins(II): catch illegal instruction trap cemt(II): catch EMT traps ttt(VI): the game of tic-tac-toe kbd(VII): map of TTY 37 keyboard tty0,...,tty5(IV): remote typewriter tty(I): find name of terminal tty(IV): console typewriter type(I): print file page-by-page gtty(II): get typewriter mode hup(I): hang up typewriter mesg(III): print string on typewriter stty(II): set mode of typewriter tty0,...,tty5(IV): remote typewriter tty(IV): console typewriter uids(V): map names to user ID's umount(I): dismount removable file system umount(II): dismount file system un(I): find undefined symbols un(I): find undefined symbols unlink(II): remove (delete) file du(I): find disk usage getuid(II): get user ID setuid(II): set user ID uids(V): map names to user ID's utmp(V): logged-in user information mail(I): send mail to another user write(I): write to another user utmp(V): logged-in user information switch(III): transfer depending on value wait(II): wait for process wait(II): wait for process wc(I): get (English) word count who(I): who is on the system who(I): who is on the system find(I): find file with given name pr(I): print file with headings wc(I): get (English) word count putc(III): write character or word chdir(I): change working directory chdir(II): change working directory dbppt(I): write binary paper tape putc(III): write character or word write(II): write file seek(II): move read or write pointer tell(II): find read or write pointer write(I): write to another user write(I): write to another user write(II): write file time(II): get time of year