5       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.
13       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.
19       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.
29       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.
34       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.
39       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.
44       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.
49       Games  have been relegated to section 6 to keep them from contaminating
50       the more staid information of section 1.
52       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.
56       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.
61       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.
69       All  entries are based on a common format, not all of whose subsections
70       will always appear.
72              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.
76              The synopsis summarizes the use of the program being  described.
77              A few conventions are used, particularly in the Commands subsec‐
78              tion:
80                     Boldface words are considered  literals,  and  are  typed
81                     just as they appear.
83                     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.
87                     Ellipses  `...'  are used to show that the previous argu‐
88                     ment-prototype may be repeated.
90                     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 `-'.
97              The  description  subsection  discusses in detail the subject at
98              hand.
100              The files subsection gives the names of files  which  are  built
101              into the program.
103              A see also subsection gives pointers to related information.
105              A  diagnostics  subsection  discusses the diagnostic indications
106              which may be produced.  Messages which are intended to be  self-
107              explanatory are not listed.
109              The bugs subsection gives known bugs and sometimes deficiencies.
110              Occasionally also the suggested fix is described.
112              In section 2 an assembler subsection carries the  assembly  lan‐
113              guage system interface.
115       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.


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.
130       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.
139       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.
151       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.
163       Hard-wired terminals.   Hard-wired terminals usually begin at the right
164       speed, up to 9600 baud; otherwise the preceding instructions apply.
166       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.
171       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.')
175       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.
179       Logging out.   There are three ways to log out:
181              You can simply hang up the phone.
183              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.
187              You can also log  in  directly  as  another  user  by  giving  a
188              login(1) command.
190       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.
195       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.
204       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.
212       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.
222       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.
228       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.
236       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.
243       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.
252       The  command name is always the first word on an input line; it and its
253       arguments are separated from one another by spaces.
255       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.
258       The Shell has many other capabilities, which are described in detail in
259       section sh(1).
261       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.
272       To  change  the  current  directory (but not the set of permissions you
273       were endowed with at login) use cd(1).
275       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.
283       If your current directory has subdirectories, the path names  of  files
284       therein begin with the name of the subdirectory with no prefixed `/'.
286       A path name may be used anywhere a file name is required.
288       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.
294       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.
299       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.
311       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.
315       Your programs can receive arguments from the command line just as  sys‐
316       tem programs do, see exec(2).
318       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.
322       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.
329       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.
333       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.
338       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.
342       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.
347       When you log in, a message-of-the-day may greet you  before  the  first
348       `$'.


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.
357       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.
363       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.)
369       The sleep(2) entry point is gone; see the more general facility, alarm,
370       plus pause.
372       Few library functions have assembly language  entry  points  any  more.
373       You will have to simulate the C calling sequence.
375       Stty  and gtty.   These system calls have been extensively altered, see
376       ioctl(2) and tty(4).
378       Archive files.   The  format  of  files  produced  by  ar(1)  has  been
379       altered.  To convert to the new style, use arcv(1).
381       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)
390       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.
394       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.
398       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.
402       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.
409       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.
415       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.
421       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.
428       Dsw.  This little-known, but indispensable facility has been taken over
429       by rm -ri.
431       Boot  procedures.   Needless to say, these are all different.  See sec‐
432       tion 8 of this volume, and `Setting up UNIX' in Volume 2.
436                                                   INTRODUCTION TO VOLUME 1(0)