! "W N   @ &   / e&7 J  j De Ԥ!@eW  8m RW et ZEWue T!eB >5 &     7= ߋpF@E A Ze      @7@ eE "   r t@P ljɋU\` _ \ Y V S P M J ^ [ X U R O L I ] Z W T Q N K H G D A > ; 8 5 2 F C @ = : 7 4 1 E B ? < 9 6 3 0 / , ) & #   . + % "    - * ' ( $ !         ROLIZWTQNKHG]DAP./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abnk -P 3W  P Zcfi" ?UP 괴|lor" >UP 괴Gu" *-" UP 303" UP ]69<" UP ?@" UP hCF" UP ILO" UP R" UP U" UP mAD" ~UP GJM" }UP P" |UP S" |UP VB" {UP EHKN" zUP QT" yUP WX" yUP [^" xUP &a" xUP rd" wUP g" wUP _jmY\" vUP _be" uUP  hknZ" tUP ]`" sUP c" sUP fi" rUP )lo" qUP ps" qUP v" pUP y" oUP |" lUP >qt" kUP wz" kUP +}" jUP " iUP r" hUP u" gUP x" eUP " dUP r" cUP S" bUP  " aUP " `UP " _UP " ^UP @" ]UP v" \UP " [UP " ZUP " YUP " XUP " WUP b" VUP " UUP 񴴁p" TUP 񴴑<" QUP 񴴁" OUP 񴴁v" NUP 񴴁" MUP 񴴁l" MUP 񴴁" LUP 񴴁T" KUP 𴴁h" KUP 𴴁" JUP 𴴁 " JUP 𴴁" IUP 𴴁" HUP 𴴁e" HUP 𴴁" GUP 𴴁" GUP 𴴁" FUP 𴴁!" EUP 𴴁" EUP 𴴁" AUP ;" VP خF" VP خ" VP خ," VP خ" VP خ2   " VP خ  " VP خg " VP خ" VP خ" VP خ  " VP خ{" VP خ" !$'*-" VP خ "%(" VP خ+" VP خx. " VP خ #&),/0" VP ׮{369<" UP ׮`?" UP ׮BE14" UP ׮7:=@" UP ׮m"C" UP ׮:LOR" UP ׮U" UP ׮X" UP ׮P[" UP ׮\lor" UP ׮u" UP ̮ehk" UP ̮n" UP ̮" UP ̮}" UP Ʈ" UP Ʈ~" UP Ʈ0P P " UP Ʈ}y" WP  " UP Ʈ " UP ƮC" UP Ʈ" UP ƮA " UP ƮP ,P cP FP Eu$'*-" UP Ʈ%+0) JP -E" UP Ʈ HKN:=" UP Ʈ}@) JP 9 \_beQTW) JP :eZ]`cfRUX) JP :[" UP Ʈ^a) JP -e dghknq" UP Ʈ(t) JP -?C) JP -") JP -) JP -@) JP -+) JP -0 P DP  P 3P [" UP Ʈ9  " UP Ʈ) JP 9) JP 9 !$" UP ŮN') JP 98;>*-" UP Ů03" UP Ůw6" UP Ů9" UP Ů<?" UP Ů>@) JP 9J" UP ŮMPSV" UP Ů BEHKNQT" UP ŮcW) JP 9XP 9P [^" UP <ad" UP gj" UP  mY\_" UP Wb" UP Gehk" UP nZ" UP ]`" UP cfi" UP l" UP Ir" UP Cux{" UP ~" UP 5" UP S" UP "" UP " UP )) JP & ) JP &) ~JP &') ~JP &K) |JP &-#) yJP & ) xJP &) JP %) xJP %P %P \Sk "k "ADk k E`Uk Kk K\X) %P @[) %P @^lor) %P @0u) %P @"|) %P @?) %P @P) %P @0P MP  ) y%P _2) w%P _6) t%P _) p%P _H6) m%P _ A) g%P _) d%P ^E ) TNP Ne') N%P HoP ^P 0rP HP uP @P 2x- P Sr) JP 4@P RP  ) JP 4G) JP 4) JP 4B) JP 4) JP 4$) JP 42+) JP 4!) JP 4u!) JP 4k k #k k #\P 4P C,P 1P CP 0P PP P )P ԬP jP ӬP jP ҬP jU P ѬP jP ЬP j}P ϬP j$~P άP i= qtwzP ̬P i%vP ˬP ieP ʬP i9RP ȬP i.;>*-0369P ƬP i/P ŬP iW(P ìP iP ¬P i P P i...emanas ctutheled iolibsecurZyacciosysunixostartlbegbcwratcxyacctmgm6eqnbctrtute...dman0cman1bman2aman3`man4_man5^man6]man7\man8xd.e..[basinfchangesYintroXkaaWnaaVptxUtaaTtocStocrcRxxc.e..Qar.1Pas.1Obas.1Nbc.1Mcat.1Lcc.1Kcdb.1Jchdir.1Ichmod.1Hcmp.1Gcomm.1Fcp.1Ecref.1Ddate.1Cdb.1Bdc.1Add.1@diff.1?dsw.1>du.1=echo.1<ed.1;eqn.1:exit.19fc.18file.17find.16goto.15grep.14if.1b.e..break.2chdir.2chmod.2chown.2close.2creat.2csw.2dup.2exec.2exit.2fork.2fstat.2getgid.2getpid.2getuid.2gtty.2indir.2intro.2kill.2link.2mknod.2mount.2nice.2open.2pipe.2profil.2ptrace.2read.2seek.2setgid.2a.e..abort.3abs.3alloc.3atan.3atof.3atoi.3crypt.3ctime.3ecvt.3end.3exp.3floor.3fmod.3fptrap.3gamma.3getarg.3getc.3getchar.3getpw.3hmul.3ierror.3ldiv.3locv.3log.3monitor.3nargs.3nlist.3perror.3pow.3printf.3`.e..vcat.4udc.4tdh.4sdn.4rdp.4qhp.4phs.4oht.4nkl.4mlp.4lmem.4kpc.4jrf.4irk.4hrp.4gtc.4ftm.4-tty.4_.e..,a.out.5+archive.5*ascii.5)core.5(directory.5'dump.5&fs.5%greek.5$group.5#mtab.5"passwd.5!tabs.5 tp.5ttys.5utmp.5wtmp.5^.e..agen.6apl.6azel.6bj.6cal.6catsim.6cb.6chess.6col.6cubic.6factor.6fed.6fget.6form.6fsend.6graf.6 graph.6 gsi.6hyphen.6ibm.6iget.6isend.6kaaishu.6lazarus.6lc.6lex.6m6.6maze.6moo.6nfs.6].e..cr.7ms.7plot.7salloc.7.th WAIT I 4/9/73 .sh NAME wait \*- await completion of process .sh SYNOPSIS .bd wait .sh DESCRIPTION Wait until all processes started with .bd & have completed, and report on abnormal terminations. .s3 Because .it "sys wait" must be executed in the parent process, the Shell itself executes .it wait, without creating a new process. .sh "SEE ALSO" sh (I) .sh BUGS After executing .it wait you are committed to waiting until termination, because interrupts and quits are ignored by all processes concerned. The o.th TTY I 3/15/72 .sh NAME tty \*- get typewriter name .sh SYNOPSIS .bd tty .sh DESCRIPTION .it Tty gives the name of the user's typewriter in the form `tty\fIn\fR' for \fIn\fR a digit or letter. The actual path name is then `/dev/tty\fIn\fR'. .sh DIAGNOSTICS `not a tty' if the standard input file is not a typewriter. .sh BUGS .th WRITE I 8/5/73 .sh NAME write \*- write to another user .sh SYNOPSIS .bd write user [ ttyno ] .sh DESCRIPTION .it Write copies lines from your typewriter to that of another user. When first called, it sends the message .s3 message from yourname... .s3 The recipient of the message should write back at this point. Communication continues until an end of file is read from the typewriter or an interrupt is sent. At that point .it write writes `EOT' on the other terminal and exits. .s3 If you want to nly out, if the process does not terminate, is to .it kill it from another terminal or to hang up. .tc | .tr | .th TROFF I 4/15/75 .sh NAME troff \*- format text .sh SYNOPSIS .bd troff [ \fB+\fIn\fR ] [ \fB\*-\fIn\fR ] [ \fB\-s\fIn\fR ] [ \fB\-n\fIn\fR ] [ \fB\-r\fIan\fR ] [ \fB\-m\fIname\fR ] [ .bd \*-t ] [ .bd \*-f ] [ .bd \*-w ] [ .bd \*-a ] [ \fB\-p\fIn\fR ] files .sh DESCRIPTION .it Troff formats text for a Graphic Systems phototypesetter according to control lines embedded in the text files. It reads the standard input if no file arguments are given. An argument of just ``\-'' refers to the standwrite to a user who is logged in more than once, the .it ttyno argument may be used to indicate the last character of the appropriate typewriter name. .s3 Permission to write may be denied or granted by use of the .it mesg command. At the outset writing is allowed. Certain commands, in particular .it roff and .it pr, disallow messages in order to prevent messy output. .s3 If the character `!' is found at the beginning of a line, .it write calls the shell to execute the rest of the line as a command. .s3 The.th UNIQ I 12/1/72 .sh NAME uniq \*- report repeated lines in a file .sh SYNOPSIS .bd uniq [ .bd \*-udc [ \fB+\fRn ] [ \fB\*-\fRn ] ] [ input [ output ] ] .sh DESCRIPTION .it Uniq reads the input file comparing adjacent lines. In the normal case, the second and succeeding copies of repeated lines are removed; the remainder is written on the output file. Note that repeated lines must be adjacent in order to be found; see sort(I). If the .bd \*-u flag is used, just the lines that are not repeated in the origiard input. The non-file option arguments are interpreted as follows: .s3 .lp +10 10 \fB+\fIn\fR Commence typesetting at the first page numbered \fIn\fR or larger. .s3 .lp +10 10 \fB\*-\fIn\fR Stop after page .it n. .s3 .lp +10 10 \fB\-s\fIn\fR Print output in groups of .it n pages, stopping the typesetter after each group. .s3 .lp +10 10 \fB\-n\fIn\fR First generated (not necessarily printed) page is given the number \fIn;\fR simulates ``.pn|\fIn\fR''. .s3 .lp +10 10 \fB\-r\fIan\fR Set number register .it a following protocol is suggested for using .it write: when you first write to another user, wait for him to write back before starting to send. Each party should end each message with a distinctive signal ( .bd (o) for `over' is conventional) that the other may reply. .bd (oo) (for `over and out') is suggested when conversation is about to be terminated. .sh FILES /etc/utmp to find user .br /bin/sh to execute `!' .sh "SEE ALSO" mesg (I), who (I), mail (I) .sh BUGS nal file are output. The .bd \*-d option specifies that one copy of just the repeated lines is to be written. The normal mode output is the union of the .bd \*-u and .bd \*-d mode outputs. .s3 The .bd \*-c option supersedes .bd \*-u and .bd \*-d and generates an output report in default style but with each line preceded by a count of the number of times it occurred. .s3 The .it n arguments specify skipping an initial portion of each line in the comparison: .s3 .lp +8 4 \fB\*-\fIn\fR The first \fIn\fR fields to the value .it n. .s3 .lp +10 10 \fB\-m\fIname\fR Prepends a standard macro file; simulates ``.so /usr/lib/tmac.\fIname\fR''. .s3 .lp +10 10 \fB\*-t\fR Place output on standard output instead of the phototypesetter. .s3 .lp +10 10 \fB\*-f\fR Refrain from feeding out paper and stopping the phototypesetter at the end. .s3 .lp +10 10 \fB\*-w\fR Wait until phototypesetter is available, if currently busy. .s3 .lp +10 10 \fB\*-a\fR Send a printable approximation of the results to the standard output. .s3 .lp +.th WHO I 3/15/72 .sh NAME who \*- who is on the system .sh SYNOPSIS .bd who [ who-file ] [ .bd "am I" ] .sh DESCRIPTION .it Who, without an argument, lists the name, typewriter channel, and login time for each current UNIX user. .s3 Without an argument, .it who examines the /etc/utmp file to obtain its information. If a file is given, that file is examined. Typically the given file will be /usr/adm/wtmp, which contains a record of all the logins since it was created. Then .it who lists logins, logouts, a together with any blanks before each are ignored. A field is defined as a string of non-space, non-tab characters separated by tabs and spaces from its neighbors. .s3 .lp +8 4 \fB+\fIn\fR The first \fIn\fR characters are ignored. Fields are skipped before characters. .i0 .s3 .sh "SEE ALSO" sort (I), comm (I) .sh BUGS 10 10 \fB\-p\fIn\fR Print all characters with point-size \fIn\fR while retaining all prescribed spacings and motions. .s3 .i0 .sh FILES .dt /usr/lib/suftab suffix hyphenation tables .br /tmp/rtm? temporary .br /usr/lib/tmac.* standard macro files .br .sh "SEE ALSO" TROFF User's Manual (internal memorandum). .br TROFF Made Trivial (internal memorandum). .br nroff (I), eqn (I), catsim (VI) .sh BUGS nd crashes since the creation of the wtmp file. Each login is listed with user name, typewriter name (with `/dev/' suppressed), and date and time. When an argument is given, logouts produce a similar line without a user name. Reboots produce a line with `x' in the place of the device name, and a fossil time indicative of when the system went down. .s3 With two arguments, .it who behaves as if it had no arguments except for restricting the printout to the line for the current typewriter. Thus `who am I' (and.th TYPO I 5/15/74 .sh NAME typo \*- find possible typos .sh SYNOPSIS .bd typo [ .bd \*-1 ] [ .bd \*-n ] file ... .sh DESCRIPTION .it Typo hunts through a document for unusual words, typographic errors, and .it "hapax legomena" and prints them on the standard output. .s3 The words used in the document are printed out in decreasing order of peculiarity along with an index of peculiarity. An index of 10 or more is considered peculiar. Printing of certain very common English words is suppressed. .s3 The stat.th TR I 5/20/74 .sh NAME tr \*- transliterate .sh SYNOPSIS .bd tr [ .bd \*-cds ] [ string1 [ string2 ] ] .sh DESCRIPTION .it Tr copies the standard input to the standard output with substitution or deletion of selected characters. Input characters found in .it string1 are mapped into the corresponding characters of .it string2. Any combination of the options .bd \*-cds may be used. .bd \*-c complements the set of characters in .it string1 with respect to the universe of characters whose ascii codes are 0 also `who are you') tells you who you are logged in as. .sh FILES /etc/utmp .sh "SEE ALSO" login (I), init (VIII) .sh BUGS istics for judging words are taken from the document itself, with some help from known statistics of English. The .bd \*-n option suppresses the help from English and should be used if the document is written in, for example, Urdu. .s3 The .bd \*-1 option causes the final output to appear in a single column instead of three columns. The normal header and pagination is also suppressed. .s3 Roff (I) and nroff (I) control lines are ignored. Upper case is mapped into lower case. Quote marks, vertical bars, hyph01 through 377 octal. .bd \*-d deletes all input characters in .it string1. .bd \*-s squeezes all strings of repeated output characters that are in .it string2 to single characters. .s3 The following abbreviation conventions may be used to introduce ranges of characters or repeated characters into the strings: .s3 \fB[\fIa\*|\fB\*-\fIb\fB\*|]\fR stands for the string of characters whose ascii codes run from character .it a to character .it b. .s3 \fB[\fIa\fB\*|*\fIn\fB\*|]\fR, where .it n is an integer or .th WC I 7/26/74 .sh NAME wc \*- word count .sh SYNOPSIS .bd wc [ name ... ] .sh DESCRIPTION .it Wc counts lines and words in the named files, or in the standard input if no name appears. A word is a maximal string of printing characters delimited by spaces, tabs or newlines. All other characters are simply ignored. .sh BUGS ens, and ampersands within words are equivalent to spaces. Words hyphenated across lines are put back together. .sh FILES /tmp/ttmp?? .br /usr/lib/salt .br /usr/lib/w2006 .sh BUGS Because of the mapping into lower case and the stripping of special characters, words may be hard to locate in the original text. .s3 The escape sequences of troff (I) are not correctly recognized. empty, stands for \fIn\fR-fold repetition of character .it a. .it n is taken to be octal or decimal according as its first digit is or is not zero. A zero or missing .it n is taken to be huge; this facility is useful for padding .it string2. .s3 The escape character `\\' may be used as in .it sh to remove special meaning from any character in a string. In addition, `\\' followed by 1, 2 or 3 octal digits stands for the character whose ascii code is given by those digits. .s3 The following example creates a list of all the words in `file1' one per line in `file2', where a word is taken to be a maximal string of alphabetics. The strings are quoted to protect the special characters from interpretation by the Shell; 012 is the ascii code for newline. .s3 .ti +8 tr \*-cs "[A\*-Z][a\*-z]" "[\\012*]" file2 .sh "SEE ALSO" sh (I), ed (I), ascii (V) .sh BUGS Won't handle ascii NUL in .it string1 or .it string2; always deletes NUL from input. A single file with several links to it is treated like several files. terminal .lp +10 10 \fBhup\fR hang up dataphone on last close. .lp +10 10 \fB\-hup\fR do not hang up dataphone on last close. .lp +10 10 \fB0\fR hang up phone line immediately .lp +10 10 \fB50 75 110 134 150 200 300 600 1200 1800 2400 4800 9600 exta extb\fR .br Set typewriter baud rate to the number given, if possible. (These are the speeds supported by the DH-11 interface). .s3 .i0 .dt The various delay algorithms are tuned to various kinds of terminals. In general the specifications ending in `0' mean no .th TP I 10/15/73 .sh NAME tp \*- manipulate DECtape and magtape .sh SYNOPSIS .bd tp [ key ] [ name ... ] .sh DESCRIPTION .it Tp saves and restores files on DECtape or magtape. Its actions are controlled by the .it key argument. The key is a string of characters containing at most one function letter and possibly one or more function modifiers. Other arguments to the command are file or directory names specifying which files are to be dumped, restored, or listed. In all cases, appearance of a directory na.th TIME I 8/16/73 .sh NAME time \*- time a command .sh SYNOPSIS .bd time command .sh DESCRIPTION The given command is executed; after it is complete, .it time prints the elapsed time during the command, the time spent in the system, and the time spent in execution of the command. .s3 The execution time can depend on what kind of memory the program happens to land in; the user time in MOS is often half what it is in core. .s3 The times are printed on the diagnostic output stream. .sh BUGS Elapsed time is acdelay for the corresponding character. .sh "SEE ALSO" stty (II) .sh BUGS me refers to the files and (recursively) subdirectories of that directory. .s3 The function portion of the key is specified by one of the following letters: .s3 .lp +8 4 \fBr\fR The named files are written on the tape. If files with the same names already exist, they are replaced. `Same' is determined by string comparison, so `./abc' can never be the same as `/usr/dmr/abc' even if `/usr/dmr' is the current directory. If no file argument is given, `\fB.\fR' is the default. .s3 .lp +8 4 \fBu\fR updates the tacurate to the second, while the CPU times are measured to the 60th second. Thus the sum of the CPU times can be up to a second larger than the elapsed time. .th STRIP I 3/15/72 .sh NAME strip \*- remove symbols and relocation bits .sh SYNOPSIS .bd strip name ... .sh DESCRIPTION .it Strip removes the symbol table and relocation bits ordinarily attached to the output of the assembler and loader. This is useful to save space after a program has been debugged. .s3 The effect of .it strip is the the same as use of the .bd \*-s option of .it ld. .sh FILES /tmp/stm? temporary file .sh "SEE ALSO" ld (I), as (I) .sh BUGS pe. .bd u is like .bd r, but a file is replaced only if its modification date is later than the date stored on the tape; that is to say, if it has changed since it was dumped. .bd u is the default command if none is given. .s3 .lp +8 4 \fBd\fR deletes the named files from the tape. At least one name argument must be given. This function is not permitted on magtapes. .s3 .lp +8 4 \fBx\fR extracts the named files from the tape to the file system. The owner and mode are restored. If no file argument is given, .th TEE I 3/6/74 .sh NAME tee \*- pipe fitting .sh SYNOPSIS .bd tee [ name ... ] .sh DESCRIPTION .it Tee transcribes the standard input to the standard output and makes copies in the named files. .sh BUGS .th SPLIT I 1/15/73 .sh NAME split \*- split a file into pieces .sh SYNOPSIS .bd split .bd \*-\fIn [ file [ name ] ] .sh DESCRIPTION .it Split reads .it file and writes it in \fIn\fR-line pieces (default 1000), as many as necessary, onto a set of output files. The name of the first output file is .it name with .bd aa appended, and so on lexicographically. If no output name is given, .bd x is default. .s3 If no input file is given, or if .bd \*- is given in its stead, then the standard input file is used. .the entire contents of the tape are extracted. .s3 .lp +8 4 \fBt\fR lists the names of the specified files. If no file argument is given, the entire contents of the tape is listed. .s3 .i0 The following characters may be used in addition to the letter which selects the function desired. .s3 .lp +10 6 \fBm\fR Specifies magtape as opposed to DECtape. .s3 .lp +10 6 \fB0,...,7\fR This modifier selects the drive on which the tape is mounted. For DECtape, `x' is default; for magtape `0' is the default. .s3 .lp +1.th STTY I 6/12/72 .sh NAME stty \*- set typewriter options .sh SYNOPSIS .bd stty [ option ... ] .sh DESCRIPTION .it Stty sets certain I/O options on the current output typewriter. With no argument, it reports the current settings of the options. The option strings are selected from the following set: .s3 .lp +10 10 \fBeven\fR allow even parity .lp +10 10 \fB\*-even\fR disallow even parity .lp +10 10 \fBodd\fR allow odd parity .lp +10 10 \fB\*-odd\fR disallow odd parity .lp +10 10 \fBraw\fR raw mode input (sh BUGS 0 6 \fBv\fR Normally .it tp does its work silently. The .bd v (verbose) option causes it to type the name of each file it treats preceded by the function letter. With the .bd t function, .bd v gives more information about the tape entries than just the name. .s3 .lp +10 6 \fBc\fR means a fresh dump is being created; the tape directory is zeroed before beginning. Usable only with .bd r and .bd u. This option is assumed with magtape since it is impossible to selectively overwrite magtape. .s3 .lp +10 6 \fBf\fno erase, kill, interrupt, quit, EOT; parity bit passed back) .lp +10 10 \fB\*-raw\fR negate raw mode .lp +10 10 \fBcooked\fR same as `\-raw' .lp +10 10 \fB\*-nl\fR allow carriage return for new-line, and output CR-LF for carriage return or new-line .lp +10 10 \fBnl\fR accept only new-line to end lines .lp +10 10 \fBecho\fR echo back every character typed .lp +10 10 \fB\*-echo\fR do not echo characters .lp +10 10 \fBlcase\fR map upper case to lower case .lp +10 10 \fB\*-lcase\fR do not map case .lp +10 10 \.th SPELL I 4/15/75 .sh NAME spell \*- find spelling errors .sh SYNOPSIS .bd spell [ .bd \*-v ] file ... .sh DESCRIPTION .it Spell collects the words from the named documents, and looks them up in a dictionary. The words not found are printed on the standard output. Words which are reasonable transformations of dictionary entries (e.g. a dictionary entry plus .it s ) are not printed. If no files are given, the input is from the standard input. .s3 If the .bd \*-v flag is given, all words which are not literR causes new entries on tape to be `fake' in that no data is present for these entries. Such fake entries cannot be extracted. Usable only with .bd r and .bd u. .s3 .lp +10 6 \fBi\fR Errors reading and writing the tape are noted, but no action is taken. Normally, errors cause a return to the command level. .s3 .lp +10 6 \fBw\fR causes .it tp to pause before treating each file, type the indicative letter and the file name (as with v) and await the user's response. Response .bd y means `yes', so the file is tfB\*-tabs\fR replace tabs by spaces when printing .lp +10 10 \fBtabs\fR preserve tabs .lp +10 10 \fBek\fR reset erase and kill characters back to normal # and @. .lp +10 10 \fBerase\fI c\fR set erase character to .it c. .lp +10 10 \fBkill\fI c\fR set kill character to .it c. .lp +10 10 \fBcr0 cr1 cr2 cr3\fR .br select style of delay for carriage return (see below) .lp +10 10 \fBnl0 nl1 nl2 nl3\fR .br select style of delay for linefeed (see below) .lp +10 10 \fBtab0 tab1 tab2 tab3\fR .br select style of delaally in the dictionary are printed; those which can be transformed to lie in the dictionary are so marked, and the others are marked with asterisks. .s3 The process takes several minutes. .sh FILES /usr/lib/w2006, /usr/dict/words, /usr/lib/spell[123] .sh "SEE ALSO" typo (I) .sh BUGS .s3 Because of the mapping into lower case and the stripping of special characters, words may be hard to locate in the original text. .s3 The escape sequences of troff (I) are not correctly recognized. .s3 More suffixes, and perreated. Null response means `no', and the file does not take part in whatever is being done. Response .bd x means `exit'; the .it tp command terminates immediately. In the .bd x function, files previously asked about have been extracted already. With .bd "r, u," and .bd d no change has been made to the tape. .s3 .i0 .sh FILES /dev/tap? .br /dev/mt? .sh DIAGNOSTICS Several; the non-obvious one is `Phase error', which means the file changed after it was selected for dumping but before it was dumped. .sh BUGS y for tab (see below) .lp +10 10 \fBff0 ff1\fR .br select style of delay for form feed (see below) .lp +10 10 \fBtty33\fR set all modes suitable for Teletype model 33 .lp +10 10 \fBtty37\fR set all modes suitable for Teletype model 37 .lp +10 10 \fBvt05\fR set all modes suitable for DEC VT05 terminal .lp +10 10 \fBtn300\fR set all modes suitable for GE Terminet 300 .lp +10 10 \fBti700\fR set all modes suitable for Texas Instruments 700 terminal .lp +10 10 \fBtek\fR set all modes suitable for Tektronix 4014 haps some prefixes, should be added. .s3 The dictionary cannot be distributed because of copyright limitations. .th "SORT" I 5/13/75 .sh NAME sort, usort \*- sort or merge files .sh SYNOPSIS .bd sort [ .if t \fB\*-abdnrt\fIx\fR .if n -abdnrt______x ] [ \fB+\fIpos \fR [ \fB\*-\fIpos \fR] ] . . . [ .bd \*-mo ] [ name ] . . . .br .bd usort [ .bd \-umo ] [ name ] . . . .sh DESCRIPTION .it Sort sorts all the named files together and writes the result on the standard output. The name `\*-' means the standard input. The standard input is also used if no input file names are given. Thus .it sort may be used as a filt.th SHIFT I 8/21/73 .sh NAME shift \*- adjust Shell arguments .sh SYNOPSIS .bd shift .sh DESCRIPTION .it Shift is used in Shell command files to shift the argument list left by 1, so that old .bd $2 can now be referred to by .bd $1 and so forth. .it Shift is useful to iterate over several arguments to a command file. For example, the command file .s3 .lp +5 0 : loop .br if $1x = x exit .br pr \*-3 $1 .br shift .br goto loop .s3 .i0 prints each of its arguments in 3-column format. .s3 .it Shift is executed w `&' are given upon receipt of the first command subsequent to the termination of the command, or when a .it wait is executed. The following is a list of the abnormal termination messages: .s3 .nf Bus error Trace/BPT trap Illegal instruction IOT trap EMT trap Bad system call Quit Floating exception Memory violation Killed Broken Pipe .s3 .fi If a core image is produced, `\*- Core dumped' is appended to the appropriate message. .s3 .bd "Redirection of I/O." There are three character sequences thater. .s3 The default sort key is an entire line. Default ordering is lexicographic in ASCII collating sequence, except that lower-case letters are considered the same as the corresponding upper-case letters. Non-ASCII bytes are ignored. The ordering is affected by the flags .if t \fB\*-abdnrt\fR, .if n .it abdnrt, one or more of which may appear: .s3 .lp +4 4 \fBa\fR Do not map lower case letters. .s3 .lp +4 4 \fBb\fR Leading blanks (spaces and tabs) are not included in fields. .s3 .lp+4 4 \fBd\fR `Dictionarithin the Shell. .sh "SEE ALSO" sh (I) .sh BUGS cause the immediately following string to be interpreted as a special argument to the Shell itself. Such an argument may appear anywhere among the arguments of a simple command, or before or after a parenthesized command list, and is associated with that command or command list. .s3 An argument of the form `arg' causes file `arg' to be used as the standard output (file dy' order: only letters, digits and blanks are significant in ASCII comparisons. .s3 .lp +4 4 \fBn\fR An initial numeric string, consisting of optional minus sign, digits and optionally included decimal point, is sorted by arithmetic value. .s3 .lp+4 4 \fBr\fR Reverse the sense of comparisons. .s3 .lp +4 4 \fBt\fIx\fR Tab character between fields is .it x. .s3 .i0 Selected parts of the line, specified by \fB+\fIpos\fR and \fB\*-\fIpos\fR, may be used as sort keys. .it Pos has the form .it m.n, where .it m sescriptor 1) for the associated command. `Arg' is created if it did not exist, and in any case is truncated at the outset. .s3 An argument of the form `>>arg' causes file `arg' to be used as the standard output for the associated command. If `arg' did not exist, it is created; if it did exist, the command output is appended to the file. .s3 For example, either of the command lines .s3 ls >junk; cat tail >>junk .br ( ls; cat tail ) >junk .s3 creates, on file `junk', a listing of the working directory, follpecifies a number of fields to skip, and .it n a number of characters to skip further into the next field. A missing .it \\.n is taken to be 0. \fB+\fIpos\fR denotes the beginning of the key; \fB\*-\fIpos\fR denotes the first position after the key (end of line by default). The ordering rule may be overridden for a particular key by appending one or more of the flags .bd abdnr to \fB+\fIpos\fR. .s3 When no tab character has been specified, a field consists of nonblanks and any preceding blanks. Under the ..th SH I 5/15/74 .sh NAME sh \*- shell (command interpreter) .sh SYNOPSIS .bd sh [ .bd \*-t ] [ .bd \*-c ] [ name [ arg1 ... [ arg9 ] ] ] .sh DESCRIPTION .it Sh is the standard command interpreter. It is the program which reads and arranges the execution of the command lines typed by most users. It may itself be called as a command to interpret files of commands. Before discussing the arguments to the Shell used as a command, the structure of command lines themselves will be given. .s3 .bd "Commands." Eacowed immediately by the contents of file `tail'. .s3 Either of the constructs `>arg' or `>>arg' associated with any but the last command of a pipeline is ineffectual, as is `', and other characters meaningful to the Shell may be passed as part of arguments. A special case of this feature allows the continuation of commands onto more than one line: a new-line preceded by `\\' is translated into a blank. .s3 Sequences of characters enclosed in double (") or single (\*a) quotes are also taken literally. For example: .s3 ls | pr \*-h "My directory" .s3 causes a directory listing to be produced by .it ls, and passed on to .it pr to be printed with the heading `My directory'. Quotes permit the inclusion of blanks in .th ROFF I 11/4/74 .sh NAME roff \*- format text .sh SYNOPSIS .bd roff [ \fB+\fIn\fR ] [ \fB\*-\fIn\fR ] [ .bd \*-s ] [ .bd \*-h ] file ... .sh DESCRIPTION .it Roff formats text according to control lines embedded in the text in the given files. Encountering a nonexistent file terminates printing. Incoming interconsole messages are turned off during printing. The optional flag arguments mean: .s3 .lp +5 5 \fB+\fIn\fR Start printing at the first page with number \fIn\fR. .s3 .lp +5 5 \fB\*-\fIn\fR Stop pri.ig no - Ignore input lines through a line beginning with `\fB..\fR'. .ti 0 .li .in|+n yes - Indent n spaces from left margin. .ti 0 .li .ix +n no - Same as `.in' but without break. .ti 0 .li .li|n no - Literal, treat next n lines as text. .ti 0 .li .ll|+n no n=65 Line length including indent is n characters. .ti 0 .li .ls|+n yes n=1 Line spacing set to n lines per output line. .ti 0 .li .m1|n no n=2 Put n blank lines between the top of page and head title. .ti 0 .li .m2|n no n=2 n blank lines put between hthe heading, which is a single argument to .it pr. .s3 .bd "Argument passing." When the Shell is invoked as a command, it has additional string processing capabilities. Recall that the form in which the Shell is invoked is .s3 sh [ name [ arg1 ... [ arg9 ] ] ] .s3 The .it name is the name of a file which is read and interpreted. If not given, this subinstance of the Shell continues to read the standard input file. .s3 In command lines in the file (not in command input), character sequences of the form `$n'nting at the first page numbered higher than \fIn\fR. .s3 .lp +5 5 \fB\*-s\fR Stop before each page (including the first) to allow paper manipulation; resume on receipt of an interrupt signal. .s3 .lp +5 5 \fB\*-h\fR Insert tabs in the output stream to replace spaces whenever appropriate. .s3 .i0 .dt Input consists of intermixed .it "text lines," which contain information to be formatted, and .it "request lines," which contain instructions about how to format it. Request lines begin with a distinguished .itead title and beginning of text on page. .ti 0 .li .m3|n no n=1 n blank lines put between end of text and foot title. .ti 0 .li .m4|n no n=3 n blank lines put between the foot title and the bottom of page. .ti 0 .li .na yes no Stop adjusting the right margin. .ti 0 .li .ne|n no - Begin new page, if n output lines cannot fit on present page. .ti 0 .li .nn|+n no - The next n output lines are not numbered. .ti 0 .li .n1 no no Add 5 to page offset; number lines in margin from 1 on each page. .ti 0 .li .n2|n no , where .it n is a digit, are replaced by the \fIn\fRth argument to the invocation of the Shell (argn). `$0' is replaced by .it name. .s3 The argument `\*-t,' used alone, causes .it sh to read the standard input for a single line, execute it as a command, and then exit. This facility replaces the older `mini-shell.' It is useful for interactive programs which allow users to execute system commands. .s3 The argument `\*-c' (used with one following argument) causes the next argument to be taken as a command l "control character," normally a period. .s3 Output lines may be .it filled as nearly as possible with words without regard to input lineation. Line .it breaks may be caused at specified places by certain commands, or by the appearance of an empty input line or an input line beginning with a space. .s3 The capabilities of .it roff are specified in the attached Request Summary. Numerical values are denoted there by n or +n, titles by t, and single characters by c. Numbers denoted +n may be signed + or \*-, ino Add 5 to page offset; number lines from n; stop if n=0. .ti 0 .li .ni|+n no n=0 Line numbers are indented n. .ti 0 .li .nf yes no Stop filling output lines. .ti 0 .li .nx|filename - Change to input file `filename'. .ti 0 .li .of|t no t=\*a\*a\*a\*a Odd foot title becomes t. .ti 0 .li .oh|t no t=\*a\*a\*a\*a Odd head title becomes t. .ti 0 .li .pa|+n yes n=1 Same as `.bp'. .ti 0 .li .pl|+n no n=66 Total paper length taken to be n lines. .ti 0 .li .po|+n no n=0 Page offset. All lines are preceded by n spacine and executed. No new-line need be present, but new-line characters are treated appropriately. This facility is useful as an alternative to `\*-t' where the caller has already read some of the characters of the command to be executed. .s3 .bd "End of file." An end-of-file in the Shell's input causes it to exit. A side effect of this fact means that the way to log out from UNIX is to type an EOT. .s3 .bd "Special commands." The following commands are treated specially by the Shell. .s3 .it chdir is done wn which case they signify relative changes to a quantity, otherwise they signify an absolute resetting. Missing n fields are ordinarily taken to be 1, missing t fields to be empty, and c fields to shut off the appropriate special interpretation. .s3 Running titles usually appear at top and bottom of every page. They are set by requests like .s3 .in +10 .if t \&.he \(fmpart1\(fmpart2\(fmpart3\(fm .if n \&.he 'part1'part2'part3' .in -10 .s3 Part1 is left justified, part2 is centered, and part3 is right justifes. .ti 0 .li .ro no arabic Roman page numbers. .ti 0 .li .sk|n no - Produce n blank pages starting next page. .ti 0 .li .sp|n yes - Insert block of n blank lines, except at top of page. .ti 0 .li .ss yes yes Single space output lines, equivalent to `.ls 1'. .ti 0 .li .ta|n|n.. - Pseudotab settings. Initial tab settings are columns 9 17 25 ... .ti 0 .li .tc|c no space Tab replacement character becomes `c'. .ti 0 .li .ti|+n yes - Temporarily indent next output line n spaces. .ti0 .li .tr|cdef.. no - Translaithout spawning a new process by executing .it "sys chdir" (II). .s3 .it login is done by executing /bin/login without creating a new process. .s3 .it wait is done without spawning a new process by executing .it "sys wait" (II). .s3 .it shift is done by manipulating the arguments to the Shell. .s3 `\fB:\fR' is simply ignored. .s3 .bd "Command file errors; interrupts." Any Shell-detected error, or an interrupt signal, during the execution of a command file causes the Shell to cease execution of that file. .sied on the page. Any % sign in a title is replaced by the current page number. Any nonblank may serve as a quote. .s3 ASCII tab characters are replaced in the input by a .it "replacement character," normally a space, according to the column settings given by a .ta command. (See .tr for how to convert this character on output.) .s3 Automatic hyphenation of filled output is done under control of .hy. When a word contains a designated .it "hyphenation character," that character disappears from the output and hte c into d, e into f, etc. .ti0 .li .ul|n no - Underline the letters and numbers in the next n input lines. 3 Processes that are created with `&' ignore interrupts. Also if such a process has not redirected its input with a `<', its input is automatically redirected to the zero length file /dev/null. .sh FILES /etc/glob, which interprets `*', `?', and `['. .br /dev/null as a source of end-of-file. .sh "SEE ALSO" `The UNIX Time-Sharing System', CACM, July, 1974, which gives the theory of operation of the Shell. .br chdir (I), login (I), wait (I), shift (I) .sh BUGS There is no way to redirect the diagnostic outputyphens can be introduced into the word at the marked places only. .sh FILES /usr/lib/suftab suffix hyphenation tables .br /tmp/rtm? temporary .br .sh "SEE ALSO" nroff (I), troff (I) .sh BUGS .it Roff is the simplest of the runoff programs, but is utterly frozen. .bp .tc | .tr | .in 0 .ce REQUEST SUMMARY .s3 .ul .if t .ta .75i 1.5i 2.25i .if n .ta 9 17 25 33 Request Break Initial Meaning .if t .in2.25i .if n .in24 .na .ti 0 .li .ad yes yes Begin adjusting right margins. .ti 0 .li .ar no arabic Arabic page nu.th RMDIR I 3/15/72 .sh NAME rmdir \*- remove directory .sh SYNOPSIS .bd rmdir dir ... .sh DESCRIPTION .it Rmdir removes (deletes) directories. The directory must be empty (except for the standard entries `\fB.\fR' and `\fB..\fR', which .it rmdir itself removes). Write permission is required in the directory in which the directory to be removed appears. .sh BUGS Needs a \fB\*-r\fR flag. .br Actually, write permission in the directory's parent is .it not required. .br Mildly unpleasant consequences can fol. mbers. .ti 0 .li .br yes - Causes a line break \*- the filling of the current line is stopped. .ti 0 .li .bl|n yes - Insert of n blank lines, on new page if necessary. .ti 0 .li .bp|+n yes n=1 Begin new page and number it n; no n means `+1'. .ti 0 .li .cc|c no c=. Control character becomes `c'. .ti 0 .li .ce|n yes - Center the next n input lines, without filling. .ti 0 .li .de|xx no - Define parameterless macro to be invoked by request `.xx' (definition ends on line beginning `\fB..\fR'). .ti 0 .li .ds yeslow removal of your own or someone else's current directory. no Double space; same as `.ls 2'. .ti 0 .li .ef|t no t=\*a\*a\*a\*a Even foot title becomes t. .ti 0 .li .eh|t no t=\*a\*a\*a\*a Even head title becomes t. .ti 0 .li .fi yes yes Begin filling output lines. .ti 0 .li .fo no t=\*a\*a\*a\*a All foot titles are t. .ti 0 .li .hc|c no none Hyphenation character becomes `c'. .ti 0 .li .he|t no t=\*a\*a\*a\*a All head titles are t. .ti 0 .li .hx no - Title lines are suppressed. .ti 0 .li .hy|n no n=1 Hyphenation is done, if n=1; and is not done, if n=0. .ti 0 .li .th RM I 1/20/73 .sh NAME rm \*- remove (unlink) files .sh SYNOPSIS .bd rm [ .bd \*-f ] [ .bd \*-r ] name ... .sh DESCRIPTION .it Rm removes the entries for one or more files from a directory. If an entry was the last link to the file, the file is destroyed. Removal of a file requires write permission in its directory, but neither read nor write permission on the file itself. .s3 If a file has no write permission, .it rm prints the file name and its mode, then reads a line from the standard input. If the line begins with \fBy\fR, the file is removed, otherwise it is not. The question is not asked if option .bd \-f was given or if the standard input is not a typewriter. .s3 If a designated file is a directory, an error comment is printed unless the optional argument .bd \*-r has been used. In that case, .it rm recursively deletes the entire contents of the specified directory. To remove directories \fIper se\fR see rmdir(I). .sh FILES /etc/glob to implement the .bd \*-r flag .sh "SEE ALSO" rmdir (I) .sh BUGS .th PWD I 5/15/74 .sh NAME pwd \*- working directory name .sh SYNOPSIS .bd pwd .sh DESCRIPTION .it Pwd prints the pathname of the working (current) directory. .sh "SEE ALSO" chdir (I) .sh BUGS .th PR I 3/20/74 .sh NAME pr \*- print file .sh SYNOPSIS .bd pr [ .bd \*-h .it header ] [ \fB\*-\fIn\fR ] [ \fB+\fIn\fR ] [ \fB\*-w\fIn\fR ] [ \fB\*-l\fIn\fR ] [ \fB\*-t\fR ] [ .bd \*-s\fIc\fB ] [ .bd \*-m ] name .li . . . .sh DESCRIPTION .it Pr produces a printed listing of one or more files. The output is separated into pages headed by a date, the name of the file or a specified header, and the page number. If there are no file arguments, .it pr prints its standard input, and is thus usable as a filter.When .it rm removes the contents of a directory under the .bd \*-r flag, full pathnames are not printed in diagnostics. .th PS I 3/20/74 .sh NAME ps \*- process status .sh SYNOPSIS .bd ps [ .bd aklx ] [ namelist ] .sh DESCRIPTION .it Ps prints certain indicia about active processes. The .bd a flag asks for information about all processes with typewriters (ordinarily only one's own processes are displayed); .bd x asks even about processes with no typewriter; .bd l asks for a long listing. Ordinarily only the typewriter number (if not one's own), the process number, and an approximation to the command line are given. If the .b .s3 Options apply to all following files but may be reset between files: .s3 .lp +5 5 \fB\*-\fIn\fR produce \fIn\fR-column output .s3 .lp +5 5 \fB+\fIn\fR begin printing with page \fIn\fR .s3 .lp +5 5 \fB\*-h\fR treat the next argument as a header to be used instead of the file name .s3 .lp +5 5 \fB\*-w\fIn\fR for purposes of multi-column output, take the width of the page to be .it n characters instead of the default 72 .s3 .lp +5 5 \fB\*-l\fIn\fR take the length of the page to be .it n lines instead of t.th REV I 4/24/75 .sh NAME rev \*- reverse lines of a file .sh SYNOPSIS .bd rev .sh DESCRIPTION .it Rev copies the standard input to the standard output, reversing the order of characters in every line. .sh BUGS d k flag is specified, the file .it /usr/sys/core is used in place of .it /dev/mem. This is used for postmortem system debugging. If a second argument is given, it is taken to be the file containing the system's namelist. .s3 The long listing is columnar and contains .s3 .lp +5 0 The name of the process's control typewriter. .s3 .lp +5 0 Flags associated with the process. 01: in core; 02: system process; 04: locked in code (e.g. for physical I/O); 10: being swapped; 20: being traced by another process. .s3 he default 66 .s3 .lp +5 5 \fB\*-t\fR do not print the 5-line header or the 5-line trailer normally supplied for each page .s3 .lp +5 5 \fB\*-s\fIc\fR separate columns by the single character .it c instead of by the appropriate amount of white space. A missing .it c is taken to be a tab. .s3 .lp +5 5 \fB\*-m\fR print all files simultaneously, each in one column .s3 .i0 Interconsole messages via write(I) are forbidden during a .it pr. .sh FILES /dev/tty? to suspend messages. .sh "SEE ALSO" cat (I), cp (I) .s.th RC I 5/15/74 .sh NAME rc \*- Ratfor compiler .sh SYNOPSIS .bd rc [ .bd \*-c ] [ .bd \*-r ] [ .bd \*-f ] [ .bd \*-v ] file ... .sh DESCRIPTION .it Rc invokes the Ratfor preprocessor on a set of Ratfor source files. It accepts three types of arguments: .s3 Arguments whose names end with `.r' are taken to be Ratfor source programs; they are preprocessed into Fortran and compiled. Each subroutine or function `name' is placed on a separate file .it name.f, and its object code is left on .it name.o. The main.lp +5 0 The state of the process. 0: nonexistent; S: sleeping; W: waiting; R: running; Z: terminated; T: stopped. .s3 The user ID of the process owner. .s3 The process ID of the process; as in certain cults it is possible to kill a process if you know its true name. .s3 The priority of the process; high numbers mean low priority. .s3 The size in blocks of the core image of the process. .s3 The event for which the process is waiting or sleeping; if blank, the process is running. .s3 The command and its arguh DIAGNOSTICS none; files not found are ignored .sh BUGS routine is on .it MAIN.f and .it MAIN.o; block data subprograms go on .it blockdata?.f and .it blockdata?.o. The files resulting from a `.r' file are loaded into a single object file .it file.o, and the intermediate object and Fortran files are removed. .s3 The following flags are interpreted by .it rc. See .it "ld (I)" for load-time flags. .s3 .lp +6 5 \fB\*-c\fR Suppresses the loading phase of the compilation, as does any error in anything. .s3 .lp +6 5 \fB\*-f\fR Save Fortran intermediate files. This isments. .s3 .i0 .dt .it Ps makes an educated guess as to the file name and arguments given when the process was created by examining core memory or the swap area. The method is inherently somewhat unreliable and in any event a process is entitled to destroy this information, so the names cannot be counted on too much. .sh FILES /unix system namelist .br /dev/mem core memory .br /usr/sys/core alternate core file .br /dev searched to find swap device and typewriter names .sh "SEE ALSO" kill (I) .sh BUGS .th PFE I 11/1/73 .sh NAME pfe \*- print floating exception .sh SYNOPSIS .bd pfe .sh DESCRIPTION .it Pfe examines the floating point exception register and prints a diagnostic for the last floating point exception. .sh "SEE ALSO" signal (II) .sh BUGS Since the system does not save the exception register in a core image file, the message refers to the last error encountered by anyone. Floating exceptions are therefore volatile. primarily for debugging. .s3 .lp +6 5 \fB\*-r\fR Ratfor only; don't try to compile the Fortran. This implies .bd \*-f and .bd \*-c. .s3 .lp +6 5 \fB\*-v\fR Don't list intermediate file names while compiling. .i0 .dt .s3 Arguments whose names end with `.f' are taken to be Fortran source programs; they are compiled in the normal manner. (Only one Fortran routine is allowed in a `.f' file.) Other arguments are taken to be either loader flag arguments, or Fortran-compatible object programs, typically produced .th PROF I 3/12/73 .sh NAME prof \*- display profile data .sh SYNOPSIS .bd prof [ .bd \*-v ] [ .bd \*-a ] [ .bd \*-l ] [ file ] .sh DESCRIPTION .it Prof interprets the file .it mon.out produced by the .it monitor subroutine. Under default modes, the symbol table in the named object file .it (a.out default) is read and correlated with the .it mon.out profile file. For each external symbol, the percentage of time spent executing between that symbol and the next is printed (in decreasing order), together with .th PASSWD I 9/1/72 .sh NAME passwd \*- change login password .sh SYNOPSIS .bd passwd name password .sh DESCRIPTION The .it password becomes associated with the given login name. This can only be done by corresponding user or by the super-user. An explicit null argument ("") for the password argument removes any password. .sh FILES /etc/passwd .sh "SEE ALSO" login (I), passwd (V), crypt (III) .sh BUGS by an earlier .it rc run, or perhaps libraries of Fortran-compatible routines. These programs, together with the results of any compilations specified, are loaded to produce an executable program with name .bd a.out. .i0 .sh FILES ratjunk temporary .br /usr/bin/ratfor preprocessor .br /usr/fort/fc1 Fortran compiler .sh "SEE ALSO" ``RATFOR \*- A Rational Fortran''. .br fc(I) for Fortran error messages. .sh DIAGNOSTICS Yes, both from .it rc itself and from Fortran. .sh BUGS Limit of about 50 arguments, 10 blthe number of times that routine was called and the number of milliseconds per call. .s3 If the .bd \*-a option is used, all symbols are reported rather than just external symbols. If the .bd \*-l option is used, the output is listed by symbol value rather than decreasing percentage. If the .bd \*-v option is used, all printing is suppressed and a profile plot is produced on the 611 display. .s3 In order for the number of calls to a routine to be tallied, the .bd \*-p option of .it cc must have been given w.th OPR I 7/17/74 .sh NAME opr \*- off line print .sh SYNOPSIS .bd opr [ \fB\*-\fRdestination ] [ .bd \*-crm ] [ name ... ] .sh DESCRIPTION .it Opr causes the named files to be printed off line at the specified destination. If no names appear the standard input is assumed. .s3 At the mother system the following destinations are recognized. The default destination is .bd mh. .s3 .lp +4 4 \fBlp\fR Local line printer. .s3 .lp +4 4 \fBmh\fR GCOS at Murray Hill Comp Center. GCOS identification must be registerock data files. .s3 #define and #include lines in ``.f'' files are not processed. hen the file containing the routine was compiled. This option also arranges for the .it mon.out file to be produced automatically. .sh FILES mon.out for profile .br a.out for namelist .br /dev/vt0 for plotting .sh "SEE ALSO" monitor (III), profil (II), cc (I) .sh BUGS Beware of quantization errors. ed in the UNIX password file (see passwd (V)). .s3 .lp +4 4 \fBsp\fR Spider network printer. .s3 .lp +4 4 \fIxx\fR The two-character code .it xx is taken to be a Murray Hill GCOS station id. Useful codes are `r1' for quality print and `q1' for quality print with special ribbon. .i0 .s3 .it Opr uses spooling daemons that do the job when facilities become available. Flag .bd \*-r causes the named files to be removed when spooled. Flag .bd \*-c causes copies to be made so as to insulate the daemons from any intervening changes to the files. .s3 Flag .bd \*-m causes mail to be sent when UNIX is finished transmitting the file. For GCOS jobs the mail includes the snumb. .sh FILES .nf .if t .ta 1.2i .if n .ta 14 /etc/passwd personal ident cards /lib/dpr dataphone spooler /etc/dpd dataphone daemon /usr/dpd/* spool area /lib/lpr line printer spooler /etc/lpd line printer daemon /usr/lpd/* spool area /lib/npr spider network spooler .fi .fi .sh "SEE ALSO" fsend (I), dpd (VIII), lpd (VIII) .sh BUGS Line printer spooler /tmp/rtm? temporary .br /usr/lib/tmac.* standard macro files .br .sh "SEE ALSO" NROFF User's Manual (internal memorandum). .br neqn (I), col (I) .sh BUGS .th NEQN I 4/30/74 .sh NAME neqn \*- typeset mathematics on terminal .sh SYNOPSIS .bd neqn [ file ] ... .sh DESCRIPTION .it Neqn is an nroff (I) preprocessor. The input language is the same as that of eqn (I). Normal usage is almost always .s3 neqn file ... | nroff .s3 Output is meant for terminals with forward and reverse capabilities, such as the Model 37 teletype or GSI terminal. .s3 If no arguments are specified, .it neqn reads the standard input, so it may be used as a filter. .sh "SEE ALSO" eqn (I), doesn't handle flags. .br Spider network spooler doesn't spool. .th NOHUP I 11/1/73 .sh NAME nohup \*- run a command immune to hangups .sh SYNOPSIS .bd nohup command [ arguments ] .sh DESCRIPTION .it Nohup executes .it command with hangups, quits and interrupts all ignored. .sh "SEE ALSO" nice (I), signal (II) .sh BUGS gsi (VI) .sh BUGS Because of some interactions with .it nroff there may not always be enough space left before and after lines containing equations. .th OD I 1/15/73 .sh NAME od \*- octal dump .sh SYNOPSIS .bd od [ .bd \*-abcdho ] [ file ] [ [ .bd + ] offset[ \fB. \fR][ \fBb\fR ] ] .sh DESCRIPTION .it Od dumps .it file in one or more formats as selected by the first argument. If the first argument is missing .bd \*-o is default. The meanings of the format argument characters are: .s3 .lp +3 3 \fBa\fR interprets words as PDP-11 instructions and dis-assembles the operation code. Unknown operation codes print as ???. .s3 .lp +3 3 \fBb\fR interprets bytes.th NM I 8/20/73 .sh NAME nm \*- print name list .sh SYNOPSIS .bd nm [ .bd \-cnrupg ] [ name ] .sh DESCRIPTION .it Nm prints the symbol table from the output file of an assembler or loader run. Each symbol name is preceded by its value (blanks if undefined) and one of the letters \fBU\fR (undefined) \fBA\fR (absolute) \fBT\fR (text segment symbol), \fBD\fR (data segment symbol), \fBB\fR (bss segment symbol), or \fBC\fR (common symbol). If the symbol is local (non-external) the type letter is in lower case.th MV I 8/20/73 .sh NAME mv \*- move or rename a file .sh SYNOPSIS .bd mv name1 name2 .sh DESCRIPTION .it Mv changes the name of .it name1 to .it name2. If .it name2 is a directory, .it name1 is moved to that directory with its original file-name. Directories may only be moved within the same parent directory (just renamed). .s3 If .it name2 already exists, it is removed before .it name1 is renamed. If .it name2 has a mode which forbids writing, .it mv prints the mode and reads the standard input to obta in octal. .s3 .lp +3 3 \fBc\fR interprets bytes in ascii. Unknown ascii characters are printed as \\?. .s3 .lp +3 3 \fBd\fR interprets words in decimal. .s3 .lp +3 3 \fBh\fR interprets words in hex. .s3 .lp +3 3 \fBo\fR interprets words in octal. .s3 .s3 .i0 The \fIfile\fR argument specifies which file is to be dumped. If no file argument is specified, the standard input is used. Thus .it od can be used as a filter. .s3 The offset argument specifies the offset in the file where dumping is to commence. This. The output is sorted alphabetically. .s3 If no file is given, the symbols in .bd a.out are listed. .s3 Options are: .s3 .lp +4 4 \fB\-c\fR list only C-style external symbols, that is those beginning with underscore `\*_'. .s3 .lp +4 4 \fB\-g\fR print only global (external) symbols .s3 .lp +4 4 \fB\-n\fR sort by value instead of by name .s3 .lp +4 4 \fB\-p\fR don't sort; print in symbol-table order .s3 .lp +4 4 \fB\-r\fR sort in reverse order .s3 .lp +4 4 \fB\-u\fR print only undefined symbols. .i0 .sh FILin a line; if the line begins with .bd y, the move takes place; if not, .it mv exits. .s3 If .it name2 would lie on a different file system, so that a simple rename is impossible, .it mv copies the file and deletes the original. .sh BUGS It should take a .bd "\*-f" flag, like .it rm, to suppress the question if the target exists and is not writable. argument is normally interpreted as octal bytes. If `\fB.\fR' is appended, the offset is interpreted in decimal. If `\fBb\fR' is appended, the offset is interpreted in blocks. (A block is 512 bytes.) If the file argument is omitted, the offset argument must be preceded by `\fB+\fR'. .s3 Dumping continues until end-of-file. .sh "SEE ALSO" db (I) .sh BUGS ES a.out .sh BUGS .th MKDIR I 3/15/72 .sh NAME mkdir \*- make a directory .sh SYNOPSIS .bd mkdir dirname ... .sh DESCRIPTION .it Mkdir creates specified directories in mode 777. The standard entries `\fB.\fR' and `\fB..\fR' are made automatically. .sh "SEE ALSO" rmdir (I) .sh BUGS .tc | .tr | .de x .in \\n(inu .if t .ta \\$2 .if n .ta \\$2+1 .in \\$1 .ti -\\$2 \fB\\$3\fP\t\\ .. .th NROFF I 4/15/75 .sh NAME nroff \*- format text .sh SYNOPSIS .bd nroff [ \fB+\fIn\fR ] [ \fB\*-\fIn\fR ] [ \fB\-n\fIn\fR ] [ \fB\-r\fIan\fR ] [ \fB\-m\fIx\fR ] [ .bd \*-s ] [ .bd \*-h ] [ .bd \*-q ] files .sh DESCRIPTION .it Nroff formats text according to control lines embedded in the text files. .it Nroff reads the standard input if no file arguments are given. An argument of just ``\-'' refers to the s.th NICE I 2/8/75 .sh NAME nice \*- run a command at low priority .sh SYNOPSIS .bd nice [ \fB\-\fInumber\fR ] command [ arguments ] .sh DESCRIPTION .it Nice executes .it command with low scheduling priority. If a numerical argument is given, that priority (in the range 1-20) is used; if not, priority 4 is used. .s3 The super-user may run commands with priority higher than normal by using a negative priority, e.g. `\-\-10'. .sh "SEE ALSO" nohup (I), nice (II) .sh BUGS .th MESG I 3/15/72 .sh NAME mesg \*- permit or deny messages .sh SYNOPSIS .bd mesg [ .bd n ] [ .bd y ] .sh DESCRIPTION .it Mesg with argument .bd n forbids messages via .it write by revoking non-user write permission on the user's typewriter. .it Mesg with argument .bd y reinstates permission. All by itself, .it mesg reverses the current permission. In all cases the previous state is reported. .sh FILES /dev/tty? .sh "SEE ALSO" write (I) .sh DIAGNOSTICS `?' if the standard input file is not a typewriter .tandard input. The non-file option arguments are interpreted as follows: .s3 .lp +10 10 \fB+\fIn\fR Output commences at the first page whose page number is .it n or larger. .s3 .lp +10 10 \fB\*-\fIn\fR Printing stops after page .it n. .s3 .lp +10 10 \fB\-n\fIn\fR First generated (not necessarily printed) page is given number \fIn\fR; simulates ``.pn|\fIn\fR''. .s3 .lp +10 10 \fB\-r\fIan\fR Set number register to the value .it n. .s3 .lp +10 10 \fB\-m\fIname\fR Prepends a standard macro file; simulates ``.so.th NEWGRP I 4/8/75 .sh NAME newgrp \*- log in to a new group .sh SYNOPSIS .bd newgrp group .sh DESCRIPTION .it Newgrp changes the group identification of its caller, analogously to .it login. The same person remains logged in, and the current directory is unchanged, but calculations of access permissions to files are performed with respect to the new group ID. .s3 A password is demanded if the group has a password and the user himself does not. .s3 When most users log in, they are members of the group namesh BUGS /usr/lib/tmac.\fIname\fR''. .s3 .lp +10 10 \fB\*-s\fR Stop prior to each page to permit paper loading. Printing is restarted by typing a `newline' character. .s3 .lp +10 10 \fB\*-h\fR Spaces are replaced where possible with tabs to speed up output (or reduce the size of the output file). .s3 .lp +10 10 \fB\*-q\fR Prompt names for insertions are not printed and the bell character is sent instead; the insertion is not echoed. .s3 .lp +10 10 .br .i0 .sh FILES .dt /usr/lib/suftab suffix hyphenation tables .br d `other.' .sh FILES /etc/group, /etc/passwd .sh "SEE ALSO" login (I), group (V) .sh BUGS .th MAN I 8/20/73 .sh NAME man \*- run off section of UNIX manual .sh SYNOPSIS .bd man [ section ] [ title ... ] .sh DESCRIPTION .it Man is a shell command file which locates and prints one or more sections of this manual. .it Section is the section number of the manual, as an Arabic not Roman numeral, and is optional. .it Title is one or more section names; these names bear a generally simple relation to the page captions in the manual. If the .it section is missing, .bd 1 is assumed. For example, .s3 .bd " man man" .s3 would reproduce this page. .sh FILES /usr/man/man?/* .sh BUGS The manual is supposed to be reproducible either on the phototypesetter or on a typewriter. However, on a typewriter some information is necessarily lost. directory; .lp +3 3 \fBb\fR if the entry is a block-type special file; .lp +3 3 \fBc\fR if the entry is a character-type special file; .lp +3 3 \fB\*-\fR if the entry is a plain file. .s3 .i0 The next 9 characters are interpreted as three sets of three bits each. The first set refers to owner permissions; the next to permissions to others in the same user-group; and the last to all others. Within each set the three characters indicate permission respectively to read, to write, or to execute the file as a pr.th LD I 8/16/73 .sh NAME ld \*- link editor .sh SYNOPSIS .bd ld [ .bd \*-sulxrdni ] name ... .sh DESCRIPTION .it Ld combines several object programs into one; resolves external references; and searches libraries. In the simplest case the names of several object programs are given, and .it ld combines them, producing an object module which can be either executed or become the input for a further .it ld run. (In the latter case, the .bd \*-r option must be given to preserve the relocation bits.) The output.th MAIL I 2/21/75 .sh NAME mail \*- send mail to designated users .sh SYNOPSIS .bd mail [ .bd \-yn ] [ person ... ] .sh DESCRIPTION .it Mail with no argument searches for a file called .it .mail, prints it if it is nonempty, then asks if it should be saved. If the answer is .bd y, the mail is added to .it mbox. Finally .it .mail is truncated to zero length. To leave the mailbox untouched, hit `delete.' The question can be answered on the command line with the argument `\-y' or `\-n'. .s3 When .it personsogram. For a directory, `execute' permission is interpreted to mean permission to search the directory for a specified file. The permissions are indicated as follows: .s3 .lp +3 3 \fBr\fR if the file is readable .lp +3 3 \fBw\fR if the file is writable .lp +3 3 \fBx\fR if the file is executable .lp +3 3 \fB\*-\fR if the indicated permission is not granted .s3 .i0 The group-execute permission character is given as .bd s if the file has set-group-ID mode; likewise the user-execute permission character is give of .it ld is left on .bd a.out. This file is made executable only if no errors occurred during the load. .s3 The argument routines are concatenated in the order specified. The entry point of the output is the beginning of the first routine. .s3 If any argument is a library, it is searched exactly once at the point it is encountered in the argument list. Only those routines defining an unresolved external reference are loaded. If a routine from a library references another routine in the library, the refer are named, .it mail takes the standard input up to an end of file and adds it to each .it person's .it .mail file. The message is preceded by the sender's name and a postmark. .s3 A .it person is either a user name recognized by .it login (I), in which case the mail is sent to the default working directory of that user; or the path name of a directory, in which case .it .mail in that directory is used. .s3 When a user logs in he is informed of the presence of mail. No mail will be received from a sender ton as .bd s if the file has set-user-ID mode. .s3 The last character of the mode is normally blank but is printed as ``t'' if the 1000 bit of the mode is on. See .it "chmod (I)" for the current meaning of this mode. .sh FILES /etc/passwd to get user ID's for \fBls \*-l\fR. .sh BUGS enced routine must appear after the referencing routine in the library. Thus the order of programs within libraries is important. .s3 .it Ld understands several flag arguments which are written preceded by a `\*-'. Except for \fB\*-l\fR, they should appear before the file names. .s3 .lp +4 4 \fB\*-s\fR `squash' the output, that is, remove the symbol table and relocation bits to save space (but impair the usefulness of the debugger). This information can also be removed by .it strip. .s3 .lp +4 4 \fB\*-u\fR whom .it .mail is inaccessible or unwritable. .sh FILES /etc/passwd to identify sender and locate persons .br /etc/utmp to identify sender .br .li .mail input mail .br mbox saved mail .br /tmp/m# temp file .sh "SEE ALSO" write (I) .sh BUGS .th LOGIN I 3/15/72 .sh NAME login \*- sign onto UNIX .sh SYNOPSIS .bd login [ username ] .sh DESCRIPTION The .it login command is used when a user initially signs onto UNIX, or it may be used at any time to change from one user to another. The latter case is the one summarized above and described here. See `How to Get Started' for how to dial up initially. .s3 If .it login is invoked without an argument, it asks for a user name, and, if appropriate, a password. Echoing is turned off (if possible) during take the following argument as a symbol and enter it as undefined in the symbol table. This is useful for loading wholly from a library, since initially the symbol table is empty and an unresolved reference is needed to force the loading of the first routine. .s3 .lp +4 4 \fB\*-l\fR This option is an abbreviation for a library name. \fB\*-l\fR alone stands for `/lib/liba.a', which is the standard system library for assembly language programs. \fB\*-l\fIx\fR stands for `/lib/lib\fIx\fR.a' where \fIx\fR is a.th LS I 3/20/74 .sh NAME ls \*- list contents of directory .sh SYNOPSIS .bd ls [ .bd \*-ltasdruifg ] name ... .sh DESCRIPTION For each directory argument, .it ls lists the contents of the directory; for each file argument, .it ls repeats its name and any other information requested. The output is sorted alphabetically by default. When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before direthe typing of the password, so it will not appear on the written record of the session. .s3 After a successful login, accounting files are updated and the user is informed of the existence of .it .mail and message-of-the-day files. .it Login initializes the user and group IDs and the working directory, then executes a command interpreter (usually .it sh (I)) according to specifications found in a password file. .s3 Login is recognized by the Shell and executed directly (without forking). .sh FILES /etc/utmpny character. A library is searched when its name is encountered, so the placement of a \fB\*-l\fR is significant. .s3 .lp +4 4 \fB\*-x\fR do not preserve local (non-.globl) symbols in the output symbol table; only enter external symbols. This option saves some space in the output file. .s3 .lp +4 4 \fB\*-X\fR Save local symbols except for those whose names begin with `L'. This option is used by .it cc to discard internally generated labels while retaining symbols local to routines. .s3 .lp +4 4 \fB\*-r\fR ctories and their contents. There are several options: .s3 .lp +4 4 \fB\*-l\fR list in long format, giving mode, number of links, owner, size in bytes, and time of last modification for each file. (See below.) If the file is a special file the size field will instead contain the major and minor device numbers. .s3 .lp +4 4 \fB\*-t\fR sort by time modified (latest first) instead of by name, as is normal .s3 .lp +4 4 \fB\*-a\fR list all entries; usually those beginning with `\fB.\fR' are suppressed .s3 .lp +4 accounting .br /usr/adm/wtmp accounting .br .li .mail mail .br /etc/motd message-of-the-day .br /etc/passwd password file .sh "SEE ALSO" init (VIII), getty (VIII), mail (I), passwd (I), passwd (V) .sh DIAGNOSTICS `login incorrect,' if the name or the password is bad. `No Shell,', `cannot open password file,' `no directory': consult a UNIX programming counselor. .sh BUGS generate relocation bits in the output file so that it can be the subject of another .it ld run. This flag also prevents final definitions from being given to common symbols, and suppresses the `undefined symbol' diagnostics. .s3 .lp +4 4 \fB\*-d\fR force definition of common storage even if the .bd \*-r flag is present. .s3 .lp +4 4 \fB\*-n\fR Arrange that when the output file is executed, the text portion will be read-only and shared among all users executing the file. This involves moving the data areas 4 \fB\*-s\fR give size in blocks for each entry .s3 .lp +4 4 \fB\*-d\fR if argument is a directory, list only its name, not its contents (mostly used with .bd \*-l to get status on directory) .s3 .lp +4 4 \fB\*-r\fR reverse the order of sort to get reverse alphabetic or oldest first as appropriate .s3 .lp +4 4 \fB\*-u\fR use time of last access instead of last modification for sorting (\fB\*-t\fR) or printing (\fB\*-l\fR) .s3 .lp +4 4 \fB\*-i\fR print i-number in first column of the report for each file li.th LN I 3/15/72 .sh NAME ln \*- make a link .sh SYNOPSIS .bd ln name1 [ name2 ] .sh DESCRIPTION A link is a directory entry referring to a file; the same file (together with its size, all its protection information, etc) may have several links to it. There is no way to distinguish a link to a file from its original directory entry; any changes in the file are effective independently of the name by which the file is known. .s3 .it Ln creates a link to an existing file .it name1. If .it name2 is given, theup the the first possible 4K word boundary following the end of the text. .s3 .lp +4 4 \fB\*-i\fR When the output file is executed, the program text and data areas will live in separate address spaces. The only difference between this option and .bd \-n is that here the data starts at location 0. .i0 .dt .sh FILES /lib/lib?.a libraries .br a.out output file .sh "SEE ALSO" as (I), ar (I) .sh BUGS sted .s3 .lp +4 4 \fB\*-f\fR force each argument to be interpreted as a directory and list the name found in each slot. This option turns off .bd "\*-l, \*-t, \*-s," and .bd \*-r, and turns on .bd \*-a; the order is the order in which entries appear in the directory. .s3 .lp +4 4 \fB\-g\fR Give group ID instead of owner ID in long listing. .s3 .i0 The mode printed under the .bd \*-l option contains 11 characters which are interpreted as follows: the first character is .s3 .lp +3 3 \fBd\fR if the entry is a link has that name; otherwise it is placed in the current directory and its name is the last component of .it name1. .s3 It is forbidden to link to a directory or to link across file systems. .sh "SEE ALSO" rm (I) .sh BUGS There is nothing particularly wrong with .it ln, but .it tp doesn't understand about links and makes one copy for each name by which a file is known; thus if the tape is extracted several copies are restored and the information that links were involved is lost. .th KILL I 2/8/75 .sh NAME kill \*- terminate a process .sh SYNOPSIS .bd kill [ \fB\*-\fRsigno ] processid ... .sh DESCRIPTION Kills the specified processes. The process number of each asynchronous process started with `&' is reported by the Shell. Process numbers can also be found by using \fIps\fR (I). .s3 If process number 0 is used, then all processes belonging to the current user and associated with the same control typewriter are killed. .s3 The killed process must belong to the current user unless he is the super-user. .s3 If a signal number preceded by ``\*-'' is given as first argument, that signal is sent instead of .it kill (see .it "signal (II))." .sh "SEE ALSO" ps (I), sh (I), signal (II) .sh BUGS a do-nothing command that is ignored by the Shell and only serves to place a label. .sh "SEE ALSO" sh (I) .sh BUGS  #&).th IF I 5/2/74 .sh NAME if \*- conditional command .sh SYNOPSIS .bd if expr command [ arg ... ] .sh DESCRIPTION .it If evaluates the expression .it expr, and if its value is true, executes the given .it command with the given arguments. .s3 The following primitives are used to construct the .it expr: .s3 .lp +13 13 \fB\*-r\fR file true if the file exists and is readable. .s3 .lp +13 13 \fB\*-w \fRfile true if the file exists and is writable. .s3 .lp +13 13 s1 \fB= \fRs2 true if the strings .it s1 and .it .th FIND I 5/15/74 .sh NAME find \*- find files .sh SYNOPSIS .bd find pathname expression .sh DESCRIPTION .it Find recursively descends the directory hierarchy from .it pathname seeking files that match a boolean .it expression written in the primaries given below. In the descriptions, the argument .it n is used as a decimal integer where .it +n means more than .it n, .it \*-n means less than .it n and .it n means exactly .it n. .s3 .lp +16 16 \fB\*-name\fR filename True if the .it filename argument matches.th FC I 8/20/73 .sh NAME fc \*- Fortran compiler .sh SYNOPSIS .bd fc [ .bd \*-c ] sfile1.f ... ofile1 ... .sh DESCRIPTION .it Fc is the UNIX Fortran compiler. It accepts three types of arguments: .s3 Arguments whose names end with `.f' are assumed to be Fortran source program units; they are compiled, and the object program is left on the file sfile1.o (i.e. the file whose name is that of the source with `.o' substituted for `.f'). .s3 Other arguments (except for \fB\*-c\fR) are assumed to be either loaders2 are equal. .s3 .lp +13 13 s1 \fB!= \fRs2 true if the strings .it s1 and .it s2 are not equal. .s3 .lp +13 13 \fB{ \fRcommand \fB}\fR The bracketed command is executed to obtain the exit status. Status zero is considered .it true. The command must not be another .it if. .s3 .i0 These primaries may be combined with the following operators: .s3 .lp +13 13 \fB!\fR unary negation operator .s3 .lp +13 13 \fB\*-a\fR binary .it and operator .s3 .lp +13 13 \fB\*-o\fR binary .it or operator .s3 .lp +13 13 \fB( \fR the current file name. Normal .it Shell argument syntax may be used if escaped (watch out for `[', `?' and `*'). .s3 .lp +16 16 \fB\*-perm\fR onum \c True if the file permission flags exactly match the octal number .it onum (see chmod(I)). If .it onum is prefixed by a minus sign, more flag bits (017777, see stat(II)) become significant and the flags are compared: .it "(flags&onum)==onum." .s3 .lp +16 16 \fB\*-type\fI c\fR True if the type of the file is .it c, where .it c is .bd "b, c, d" or .bd f for blo flags, or object programs, typically produced by an earlier .it fc run, or perhaps libraries of Fortran-compatible routines. These programs, together with the results of any compilations specified, are loaded (in the order given) to produce an executable program with name .bd a.out. .s3 The .bd \*-c argument suppresses the loading phase, as does any syntax error in any of the routines being compiled. .s3 The following is a list of differences between .it fc and ANSI standard Fortran (also see the BUGS sectexpr\fB )\fR parentheses for grouping. .s3 .i0 .bd \*-a has higher precedence than .bd \*-o. Notice that all the operators and flags are separate arguments to .it if and hence must be surrounded by spaces. Notice also that parentheses are meaningful to the Shell and must be escaped. .sh "SEE ALSO" sh (I), find (I) .sh BUGS ck special file, character special file, directory or plain file. .s3 .lp +16 16 \fB\*-links\fI n\fR \c True if the file has .it n links. .s3 .lp +16 16 \fB\*-user\fR uname \c True if the file belongs to the user .it uname. .s3 .lp +16 16 \fB\*-group\fR gname \c As it is for .bd \*-user so shall it be for .bd \*-group (someday). .s3 .lp +16 16 \fB\*-size\fI n\fR \c True if the file is .it n blocks long (512 bytes per block). .s3 .lp +16 16 \fB\*-atime\fI n\fR \c True if the file has been accessed in .it n dion): .s3 .lp +4 4 1. Arbitrary combination of types is allowed in expressions. Not all combinations are expected to be supported at runtime. All of the normal conversions involving integer, real, double precision and complex are allowed. .s3 .lp +4 4 2. Two forms of ``implicit'' statements are recognized: .bd "implicit integer /i\*-n/", or .bd "implicit integer (i\-n)." .s3 .lp +4 4 3. The types doublecomplex, logical*1, integer*1, integer*2, integer*4 (same as integer), real*4 (real), and real*8 (double .th GREP I 5/15/74 .sh NAME grep \*- search a file for a pattern .sh SYNOPSIS .bd grep [ .bd \*-v ] [ .bd \*-b ] [ .bd \*-c ] [ .bd \*-n ] expression [ file ] ... .sh DESCRIPTION .it Grep searches the input files (standard input default) for lines matching the regular expression. Normally, each line found is copied to the standard output. If the .bd \*-v flag is used, all lines but those matching are printed. If the .bd \*-c flag is used, only a count of matching lines is printed. If the .bd \*-n flag is usays. .s3 .lp +16 16 \fB\*-mtime\fI n\fR \c True if the file has been modified in .it n days. .s3 .lp +16 16 \fB\*-exec\fR command \c True if the executed command returns exit status zero (most commands do). The end of the command is punctuated by an escaped semicolon. A command argument `{}' is replaced by the current pathname. .s3 .lp +16 16 \fB\*-ok\fR command \c Like .bd \*-exec except that the generated command line is printed with a question mark first, and is executed only if the user responds \fBy\fRprecision) are supported. .s3 .lp +4 4 4. \fB&\fR as the first character of a line signals a continuation card. .s3 .lp +4 4 5. \fBc\fR as the first character of a line signals a comment. .s3 .lp +4 4 6. All keywords are recognized in lower case. .s3 .lp +4 4 7. The notion of `column 7' is not implemented. .s3 .lp +4 4 8. G-format input is free form\*- leading blanks are ignored, the first blank after the start of the number terminates the field. .s3 .lp +4 4 9. A comma in any numeric or logical input fielded, each line is preceded its relative line number in the file. If the .bd \*-b flag is used, each line is preceded by the block number on which it was found. This is sometimes useful in locating disk block numbers by context. .s3 In all cases the file name is shown if there is more than one input file. .s3 For a complete description of the regular expression, see ed (I). Care should be taken when using the characters $ * [ ^ | ( ) and \\ in the regular expression as they are also meaningful to the Shell. I. .s3 .lp +16 16 \fB\*-print\fR \c Always true; causes the current pathname to be printed. .s3 .i0 The primaries may be combined with these operators (ordered by precedence): .s3 .lp +16 16 \fB!\fR prefix .it not .s3 .lp +16 16 \fB\*-a\fR infix .it and, second operand evaluated only if first is true .s3 .lp +16 16 \fB\*-o\fR infix .it or, second operand evaluated only if first is false .s3 .lp +16 16 \fB( \fRexpression\fB )\fR parentheses for grouping. (Must be escaped.) .s3 .i0 To remove files named `a.o terminates the field. .s3 .lp +4 4 10. There is no carriage control on output. .s3 .lp +4 4 11. A sequence of .it n characters in double quotes `"' is equivalent to .it n .bd h followed by those characters. .s3 .lp +4 4 12. In .bd data statements, a hollerith string may initialize an array or a sequence of array elements. .s3 .lp +4 4 13. The number of storage units requested by a binary .bd read must be identical to the number contained in the record being read. .s3 .lp +4 4 14. If the first character in t is generally necessary to enclose the entire .it expression argument in quotes. .sh "SEE ALSO" ed (I), sh (I) .sh BUGS Lines are limited to 256 characters; longer lines are truncated. ut' and `*.o' not accessed for a week: .s3 .lp +.5i 0 find / "(" \*-name a.out \*-o \*-name "*.o" ")" \*-a \*-atime +7 \*-a \*-exec rm {} ";" .i0 .sh FILES /etc/passwd .sh "SEE ALSO" sh (I), if(I), file system (V) .sh BUGS There is no way to check device type. .br Syntax should be reconciled with .it if. an input file is ``#'', a preprocessor identical to the C preprocessor is called, which implements ``#define'' and ``#include'' preprocessor statements. (See the C reference manual for details.) The preprocessor does not recognize Hollerith strings written with \fIn\*|\fBh\fR. .s3 .i0 In I/O statements, only unit numbers 0-19 are supported. Unit number .it n refers to file fort\fInn;\fR (e.g. unit 9 is file `fort09'). For input, the file must exist; for output, it will be created. Unit 5 is permanently asso.th GOTO I 3/15/72 .sh NAME goto \*- command transfer .sh SYNOPSIS .bd goto label .sh DESCRIPTION .it Goto is allowed only when the Shell is taking commands from a file. The file is searched from the beginning for a line beginning with `:' followed by one or more spaces followed by the .it label. If such a line is found, the .it goto command returns. Since the read pointer in the command file points to the line after the label, the effect is to cause the Shell to transfer to the labelled line. .s3 `:' is .th FILE I 1/16/75 .sh NAME file \*- determine file type .sh SYNOPSIS .bd file file ... .sh DESCRIPTION .it File performs a series of tests on each argument in an attempt to classify it. If an argument appears to be ascii, .it file examines the first 512 bytes and tries to guess its language. .sh BUGS ciated with the standard input file; unit 6 with the standard output file. Also see .it setfil (III) for a way to associate unit numbers with named files. .sh FILES .ta 1.5i .nf a.out loaded output f.tmp[123] temporary (deleted) /usr/fort/fc1 compiler proper /lib/fr0.o runtime startoff /lib/filib.a interpreter library /lib/libf.a builtin functions, etc. /lib/liba.a system library .fi .sh "SEE ALSO" rc (I), which announces a more pleasant Fortran dialect; the ANSI standard; ld (I) for loader flags. For some subroutines, try ierror, getarg, setfil (III). .sh DIAGNOSTICS Compile-time diagnostics are given in English, accompanied if possible with the offending line number and source line with an underscore where the error occurred. Runtime diagnostics are given by number as follows: .s3 .lp +5 5 1 invalid log argument .lp +5 5 2 bad arg count to amod .lp +5 5 3 bad arg count to atan2 .lp +5 5 4 excessive argument to cabs .lp +5 5 5 exp too large in cexp .lp +5 5 6 bad arg count to cmplx .lp +5 5 7 bad arg count tade with .bd left and .bd right: .it "left [ x sup 2 + y sup 2 over alpha right ] ~=~1" produces $left [ x sup 2 + y sup 2 over alpha right ] ~=~1$. The .bd right clause is optional. .s3 Vertical piles of things are made with .bd "pile, lpile, cpile," and .bd rpile: .it "pile {a above b above c}" produces $pile {a above b above c}$. There can be an arbitrary number of elements in a pile. .bd lpile left-justifies, .bd pile and .bd cpile center, with different vertical spacing, and .bd rpile right justifiesn specifies a set of strings of characters. A member of this set of strings is said to be .it matched by the regular expression. The regular expressions allowed by .it ed are constructed as follows: .s3 .lp +3 3 1. An ordinary character (not one of those discussed below)\| is a regular expression and matches that character. .s3 .lp +3 3 2. A circumflex `^' at the beginning of a regular expression matches the empty string at the beginning of a line. .s3 .lp +3 3 3. A currency symbol `$' at the end of a regulo dim .lp +5 5 8 excessive argument to exp .lp +5 5 9 bad arg count to idim .lp +5 5 10 bad arg count to isign .lp +5 5 11 bad arg count to mod .lp +5 5 12 bad arg count to sign .lp +5 5 13 illegal argument to sqrt .lp +5 5 14 assigned/computed goto out of range .lp +5 5 15 subscript out of range .lp +5 5 16 real**real overflow .lp +5 5 17 (negative real)**real .lp +5 5 100 illegal I/O unit number .lp +5 5 101 inconsistent use of I/O unit .lp +5 5 102 cannot create output file .lp +5 5 103 cannot open input. .s3 .vs 12p Diacritical marks are made with .bd dot, .bd dotdot, .bd hat, .bd bar: .it "x dot = f(t) bar" is $x dot = f(t) bar$. Default sizes and fonts can be changed with .bd "size n" and various of .bd roman, .bd italic, and .bd bold. .s3 Keywords like .it sum .EQ ( sum ) .EN .it int .EQ ( int ) .EN .it inf .EQ ( inf ) .EN and shorthands like >= .EQ (>=) .EN \*-> .EQ (->), .EN != .EQ ( != ), .EN are recognized. Spell out Greek letters in the desired case, as in .it "alpha, GAMMA." Mathematical words lar expression matches the null character at the end of a line. .s3 .lp +3 3 4. A period `\fB.\fR' matches any character except a new-line character. .s3 .lp +3 3 5. A regular expression followed by an asterisk `*' matches any number of adjacent occurrences (including zero)\| of the regular expression it follows. .s3 .lp +3 3 6. A string of characters enclosed in square brackets `[ ]' matches any character in the string but no others. If, however, the first character of the string is a circumflex `^' the reg file .lp +5 5 104 EOF on input file .lp +5 5 105 illegal character in format .lp +5 5 106 format does not begin with ( .lp +5 5 107 no conversion in format but non-empty list .lp +5 5 108 excessive parenthesis depth in format .lp +5 5 109 illegal format specification .lp +5 5 110 illegal character in input field .lp +5 5 111 end of format in hollerith specification .lp +5 5 112 bad argument to setfil .lp +5 5 120 bad argument to ierror .lp +5 5 999 unimplemented input conversion .i0 .sh BUGS The following ike sin, cos, log are made Roman automatically. Troff (I) four-character escapes like \\(bs (\(bs) can be used anywhere. Strings enclosed in double quotes "..." are passed through untouched. .sh "SEE ALSO" A System for Typesetting Mathematics (Computer Science Technical Report #17, Bell Laboratories, 1974.) .br TROFF Users' Manual (internal memorandum) .br TROFF Made Trivial (internal memorandum) .br troff (I), neqn (I) .sh BUGS Undoubtedly. Watch out for small or large point sizes \*- it's tuned too well fular expression matches any character except new-line and the characters in the string. .s3 .lp +3 3 7. The concatenation of regular expressions is a regular expression which matches the concatenation of the strings matched by the components of the regular expression. .s3 .lp +3 3 8. A regular expression enclosed between the sequences `\\(' and `\\)'is identical to the unadorned expression; the construction has side effects discussed under the .it s command. .s3 .lp +3 3 9. The null regular expression standis a list of those features not yet implemented: .br arithmetic statement functions .br scale factors on input .br .bd Backspace statement. or size 10. Be cautious if inserting horizontal or vertical motions, and of backslashes in general. ing alone is equivalent to the last regular expression encountered. .s3 .i0 Regular expressions are used in addresses to specify lines and in one command (see .it s below)\| to specify a portion of a line which is to be replaced. If it is desired to use one of the regular expression metacharacters as an ordinary character, that character may be preceded by `\\'. This also applies to the character bounding the regular expression (often `/')\| and to `\\' itself. .s3 To understand addressing in .it ed it is n.th EXIT I 3/15/72 .sh NAME exit \*- terminate command file .sh SYNOPSIS .bd exit .sh DESCRIPTION .it Exit performs a .bd seek to the end of its standard input file. Thus, if it is invoked inside a file of commands, upon return from .it exit the shell will discover an end-of-file and terminate. .sh "SEE ALSO" if (I), goto (I), sh (I) .sh BUGS 036"%(+.1478;>ADGJM9<?BEHKN:ecessary to know that at any time there is a \fIcurrent line.\fR Generally speaking, the current line is the last line affected by a command; however, the exact effect on the current line is discussed under the description of the command. Addresses are constructed as follows. .s3 .lp +6 3 1. The character `\fB.\fR' addresses the current line. .s3 .lp +6 3 2. The character `$' addresses the last line of the buffer. .s3 .lp +6 3 3. A decimal number .it n addresses the \fIn\fR-th line of the buffer. .s3 .lp +6.EQ delim $$ .EN .th EQN I 2/22/74 .sh NAME eqn \*- typeset mathematics .sh SYNOPSIS .bd eqn [ file ] ... .sh DESCRIPTION .it Eqn is a troff (I) preprocessor for typesetting mathematics on the Graphics Systems phototypesetter. Usage is almost always .s3 eqn file ... | troff .s3 If no files are specified, .it eqn reads from the standard input. A line beginning with ``.EQ'' marks the start of an equation; the end of an equation is marked by a line beginning with ``.EN''. Neither of these lines is altered .th ED I 1/15/73 .if t .ds q \(aa .if n .ds q ' .sh NAME ed \*- text editor .sh SYNOPSIS .bd ed [ .bd \*- ] [ name ] .sh DESCRIPTION .it Ed is the standard text editor. .s3 If a .it name argument is given, .it ed simulates an .it e command (see below)\| on the named file; that is to say, the file is read into .it ed's buffer so that it can be edited. The optional .bd \*- suppresses the printing of character counts by .it e, .it r, and .it w commands. .s3 .it Ed operates on a copy of any file it is editing; 3 4. `\*q\fIx\fR' addresses the line marked with the mark name character \fIx\fR, which must be a lower-case letter. Lines are marked with the .it k command described below. .s3 .lp +6 3 5. A regular expression enclosed in slashes `/' addresses the first line found by searching toward the end of the buffer and stopping at the first line containing a string matching the regular expression. If necessary the search wraps around to the beginning of the buffer. .s3 .lp +6 3 6. A regular expression enclosed in qor defined by .it eqn, so you can define them yourself to get centering, numbering, etc. All other lines are treated as comments, and passed through untouched. .s3 Spaces, tabs, newlines, braces, double quotes, tilde and circumflex are the only delimiters. Braces ``{}'' are used for grouping. Use tildes ``~'' to get extra spaces in an equation. .s3 .vs 13p Subscripts and superscripts are produced with the keywords .bd sub and .bd sup. Thus .it "x sub i" makes $x sub i$, .it "a sub i sup 2" produces $a subchanges made in the copy have no effect on the file until a \fIw\fR (write)\| command is given. The copy of the text being edited resides in a temporary file called the .it buffer. There is only one buffer. .s3 Commands to .it ed have a simple and regular structure: zero or more .it addresses followed by a single character .it command, possibly followed by parameters to the command. These addresses specify one or more lines in the buffer. Every command which requires addresses has default addresses, so thaueries `?' addresses the first line found by searching toward the beginning of the buffer and stopping at the first line containing a string matching the regular expression. If necessary the search wraps around to the end of the buffer. .s3 .lp +6 3 7. An address followed by a plus sign `+' or a minus sign `\*-' followed by a decimal number specifies that address plus (resp. minus)\| the indicated number of lines. The plus sign may be omitted. .s3 .lp +6 3 8. If an address begins with `+' or `\-' the additi i sup 2$, and .it "e sup {x sup 2 + y sup 2}" gives $e sup {x sup 2 + y sup 2}$. Fractions are made with .bd over. .it "a over b" is $a over b$ and .it "1 over sqrt {ax sup 2 +bx+c}" is $1 over sqrt {ax sup 2 +bx+c}$ . .bd sqrt makes square roots. .s3 The keywords .bd from and .bd to introduce lower and upper limits on arbitrary things: $lim from {n-> inf} sum from 0 to n x sub i$ is made with .it "lim from {n-> inf} sum from 0 to n x sub i." Left and right brackets, braces, etc., of the right height are mt the addresses can often be omitted. .s3 In general, only one command may appear on a line. Certain commands allow the input of text. This text is placed in the appropriate place in the buffer. While .it ed is accepting text, it is said to be in \fIinput mode.\fR In this mode, no commands are recognized; all input is merely collected. Input mode is left by typing a period `\fB.\fR' alone at the beginning of a line. .s3 .it Ed supports a limited form of .it "regular expression" notation. A regular expressioon or subtraction is taken with respect to the current line; e.g. `\-5' is understood to mean `\fB.\fR\-5'. .s3 .lp +6 3 9. If an address ends with `+' or `\-', then 1 is added (resp. subtracted). As a consequence of this rule and rule 8, the address `\-' refers to the line before the current line. Moreover, trailing `+' and `\-' characters have cumulative effect, so `\-\-' refers to the current line less 2. .s3 .lp +6 3 10. To maintain compatibility with earlier version of the editor, the character `^' in addresses is entirely equivalent to `\-'. .s3 .i0 Commands may require zero, one, or two addresses. Commands which require no addresses regard the presence of an address as an error. Commands which accept one or two addresses assume default addresses when insufficient are given. If more addresses are given than such a command requires, the last one or two (depending on what is accepted)\| are used. .s3 Addresses are separated from each other typically by a comma `\fB,\fR'. They may also be separated by a seAn .it l command may follow any other on the same line. .s3 .lp +5 5 ( \fB. \fR, \fB. \fR)\|m\fIa\fR .br The move command repositions the addressed lines after the line addressed by .it a. The last of the moved lines becomes the current line. .s3 .lp +5 5 ( \fB. \fR, \fB. \fR)\|p .br The print command prints the addressed lines. `\fB.\fR' is left at the last line printed. The .it p command may be placed on the same line after any command. .s3 .lp +5 5 q .br The quit command causes .it ed to exit. No automatmmand list, 64 characters per file name, and 128K characters in the temporary file. The limit on the number of lines depends on the amount of core: each line takes 1 word. .sh FILES /tmp/#, temporary; `#' is the process number (in octal). .sh DIAGNOSTICS `?' for errors in commands; `TMP' for temporary file overflow. .sh "SEE ALSO" A Tutorial Introduction to the ED Text Editor (B. W. Kernighan) .sh BUGS The .it s command causes all marks to be lost on lines changed. micolon `\fB;\fR'. In this case the current line `\fB.\fR' is set to the previous address before the next address is interpreted. This feature can be used to determine the starting line for forward and backward searches (`/', `?')\|. The second address of any two-address sequence must correspond to a line following the line corresponding to the first address. .s3 In the following list of .it ed commands, the default addresses are shown in parentheses. The parentheses are not part of the address, but are useic write of a file is done. .s3 .lp +5 5 ($)\|r filename .br The read command reads in the given file after the addressed line. If no file name is given, the remembered file name, if any, is used (see .it e and .it f commands)\|. The remembered file name is not changed unless `filename' is the very first file name mentioned. Address `0' is legal for .it r and causes the file to be read at the beginning of the buffer. If the read is successful, the number of characters read is typed. `\fB.\fR' is left at the.th ECHO I 3/15/72 .sh NAME echo \*- echo arguments .sh SYNOPSIS .bd echo [ arg ... ] .sh DESCRIPTION .it Echo writes its arguments in order as a line on the standard output file. It is mainly useful for producing diagnostics in command files. .sh BUGS d to show that the given addresses are the default. .s3 As mentioned, it is generally illegal for more than one command to appear on a line. However, any command may be suffixed by `p' or by `l', in which case the current line is either printed or listed respectively in the way discussed below. .s3 .lp +5 5 ( \fB. \fR)\|a .lp +5 5 .lp +5 5 .li \fB.\fR .lp +5 5 The append command reads the given text and appends it after the addressed line. `\fB.\fR' is left on the last line input, if there were any, last line read in from the file. .s3 .lp +5 5 ( \fB. \fR, \fB. \fR)\|s/regular expression/replacement/ or, .lp +5 5 ( \fB. \fR, \fB. \fR)\|s/regular expression/replacement/g .br The substitute command searches each addressed line for an occurrence of the specified regular expression. On each line in which a match is found, all matched strings are replaced by the replacement specified, if the global replacement indicator `g' appears after the command. If the global indicator does not appear, only th.th DU I 1/20/73 .sh NAME du \*- summarize disk usage .sh SYNOPSIS .bd du [ .bd \*-s ] [ .bd \*-a ] [ name ... ] .sh DESCRIPTION .it Du gives the number of blocks contained in all files and (recursively) directories within each specified directory or file .it name. If .it name is missing, `\fB.\fR' is used. .s3 The optional argument .bd \*-s causes only the grand total to be given. The optional argument .bd \*-a causes an entry to be generated for each file. Absence of either causes an entry to be generat otherwise at the addressed line. Address `0' is legal for this command; text is placed at the beginning of the buffer. .s3 .lp +5 5 ( \fB. \fR, \fB. \fR)\|c .lp +5 5 .lp +5 5 .li \fB.\fR .lp +5 5 The change command deletes the addressed lines, then accepts input text which replaces these lines. `\fB.\fR' is left at the last line input; if there were none, it is left at the first line not deleted. .s3 .lp +5 5 ( \fB. \fR, \fB. \fR)\| d .br The delete command deletes the addressed lines from the buffe first occurrence of the matched string is replaced. It is an error for the substitution to fail on all addressed lines. Any character other than space or new-line may be used instead of `/' to delimit the regular expression and the replacement. `\fB.\fR' is left at the last line substituted. .s2 An ampersand `&' appearing in the replacement is replaced by the string matching the regular expression. The special meaning of `&' in this context may be suppressed by preceding it by `\\'. As a more general feated for each directory only. .s3 A file which has two links to it is only counted once. .sh BUGS Non-directories given as arguments (not under .bd \*-a option) are not listed. .s3 Removable file systems do not work correctly since i-numbers may be repeated while the corresponding files are distinct. .it Du should maintain an i-number list per root directory encountered. er. The line originally after the last line deleted becomes the current line; if the lines deleted were originally at the end, the new last line becomes the current line. .s3 .lp +5 5 e filename .br The edit command causes the entire contents of the buffer to be deleted, and then the named file to be read in. `\fB.\fR' is set to the last line of the buffer. The number of characters read is typed. `filename' is remembered for possible use as a default file name in a subsequent .it r or .it w command. .s3 .lpure, the characters `\\\fIn\fR', where .it n is a digit, are replaced by the text matched by the \fIn\fR-th regular subexpression enclosed between `\\(' and `\\)'. When nested, parenthesized subexpressions are present, .it n is determined by counting occurrences of `\\(' starting from the left. .s2 Lines may be split by substituting new-line characters into them. The new-line in the replacement string must be escaped by preceding it by `\\'. .s3 .lp +5 5 ( \fB.\fR , \fB.\fR ) t \fIa\fR .br This command acts.th DSW I 3/15/72 .sh NAME dsw \*- delete interactively .sh SYNOPSIS .bd dsw [ directory ] .sh DESCRIPTION For each file in the given directory (`\fB.\fR' if not specified) .it dsw types its name. If .bd y is typed, the file is deleted; if .bd x, .it dsw exits; if new-line, the file is not deleted; if anything else, .it dsw asks again. .sh "SEE ALSO" rm (I) .sh BUGS The name .it dsw is a carryover from the ancient past. Its etymology is amusing. +5 5 f filename .br The filename command prints the currently remembered file name. If `filename' is given, the currently remembered file name is changed to `filename'. .s3 .lp +5 5 (1,$)\|g/regular expression/command list .br In the global command, the first step is to mark every line which matches the given regular expression. Then for every such line, the given command list is executed with `\fB.\fR' initially set to that line. A single command or the first of multiple commands appears on the same line just like the .it m command, except that a copy of the addressed lines is placed after address .it a (which may be 0). `\fB.\fR' is left on the last line of the copy. .s3 .lp +5 5 (1,$)\|v/regular expression/command list .br This command is the same as the global command except that the command list is executed with `\fB.\fR' initially set to every line .it except those matching the regular expression. .s3 .lp +5 5 (1,$)\|w filename .br The write command writes the addressed lines onto the given file. If t.th DIFF I 5/15/74 .sh NAME diff \*- differential file comparator .sh SYNOPSIS .bd diff [ .bd \*- ] name1 name2 .sh DESCRIPTION .it Diff tells what lines must be changed in two files to bring them into agreement. The normal output contains lines of these forms: .s3 .lp +5 0 .it n1 a .it n3,n4 .br .it n1,n2 d .it n3 .br .it n1,n2 c .it n3,n4 .s3 .i0 These lines resemble .it ed commands to convert file .it name1 into file .it name2. The numbers after the letters pertain to file .it name2. In fact, by exchangiwith the global command. All lines of a multi-line list except the last line must be ended with `\\'. .it A, .it i, and .it c commands and associated input are permitted; the `\fB.\fR' terminating input mode may be omitted if it would be on the last line of the command list. The (global)\| commands, .it g, and .it v, are not permitted in the command list. .s3 .lp +5 5 ( \fB. \fR)\|i .lp +5 5 .lp +5 5 .li \fB.\fR .br This command inserts the given text before the addressed line. `\fB.\fR' is left at the file does not exist, it is created mode 666 (readable and writeable by everyone)\|. The remembered file name is .it not changed unless `filename' is the very first file name mentioned. If no file name is given, the remembered file name, if any, is used (see .it e and .it f commands)\|. `\fB.\fR' is unchanged. If the command is successful, the number of characters written is typed. .s3 .lp +5 5 ($)\|= .br The line number of the addressed line is typed. `\fB.\fR' is unchanged by this command. .s3 .lp +5 5 ng `a' for `d' and reading backward one may ascertain equally how to convert file .it name2 into .it name1. As in .it ed, identical pairs where .it n1 = .it n2 or .it n3 = .it n4 are abbreviated as a single number. .s3 Following each of these lines come all the lines that are affected in the first file flagged by `*', then all the lines that are affected in the second file flagged by `\fB.\fR'. .s3 Under the \fB\*-\fR option, the output of .it diff is a script of .it "a, c" and .it d commands for the edhe last line input; if there were none, at the addressed line. This command differs from the .it a command only in the placement of the text. .s3 .lp +5 5 ( \fB. \fR)\|k\fIx\fR .br The mark command marks the addressed line with name .it x, which must be a lower-case letter. The address form `\*q\fIx\fR' then addresses this line. .s3 .lp +5 5 ( \fB. \fR, \fB. \fR)\|l .br The list command prints the addressed lines in an unambiguous way: non-graphic characters are printed in octal, and long lines are folded. !UNIX command .br The remainder of the line after the `!' is sent to UNIX to be interpreted as a command. `\fB.\fR' is unchanged. .s3 .lp +5 5 ( \fB.\fR+1 )\| .br An address alone on a line causes the addressed line to be printed. A blank line alone is equivalent to `.+1p'; it is useful for stepping through text. .s3 .i0 If an interrupt signal (ASCII DEL)\| is sent, .it ed prints a `?' and returns to its command level. .s3 Some size limitations: 512 characters per line, 256 characters per global coitor .it ed, which will change the contents of the first file into the contents of the second. In this connection, the following shell program may help maintain multiple versions of a file. Only an ancestral file ($1) and a chain of version-to-version .it ed scripts ($2,$3,...) made by .it diff need be on hand. A `latest version' appears on the standard output. .s3 .lp +5 0 .tr || (cat $2 ... $9; echo "1,$p") \*v ed \*- $1 .s3 .i0 Except for occasional `jackpots', .it diff finds a smallest sufficient set of file differences. .sh "SEE ALSO" cmp (I), comm (I), ed (I) .sh DIAGNOSTICS `jackpot' \*- To speed things up, the program uses hashing. You have stumbled on a case where there is a chance that this has resulted in a difference being called where none actually existed. Sometimes reversing the order of files will make a jackpot go away. .sh BUGS Editing scripts produced under the \fB\*-\fR option are naive about creating lines consisting of a single `\fB.\fR'. .lp +6 6 number .br The value of the number is pushed on the stack. A number is an unbroken string of the digits 0-9. It may be preceded by an underscore \*_ to input a negative number. Numbers may contain decimal points. .s3 .lp +6 6 + \- * % ^ .br The top two values on the stack are added (+), subtracted (\*-), multiplied (*), divided (/), remaindered (%), or exponentiated (^). The two entries are popped off the stack; the result is pushed on the stack in their place. Any fractional part of an expone.th DB I 8/20/73 .sh NAME db \*- debug .sh SYNOPSIS .bd db [ core [ namelist ] ] [ .bd \*- ] .sh DESCRIPTION Unlike many debugging packages (including DEC's ODT, on which .it db is loosely based), .it db is not loaded as part of the core image which it is used to examine; instead it examines files. Typically, the file will be either a core image produced after a fault or the binary output of the assembler. .it Core is the file being debugged; if omitted \fBcore\fR is assumed. .it Namelist is a file containi.th DD I 5/15/74 .sh NAME dd \*- convert and copy a file .sh SYNOPSIS .bd dd [option=value] ... .sh DESCRIPTION .it Dd copies the specified input file to the specified output with possible conversions. The standard input and output are used by default. The input and output block size may be specified to take advantage of raw physical I/O. .s3 .ft I .lp +15 15 option values .ft R .lp +15 15 if= input file name; standard input is default .lp +15 15 of= output file name; standard output is default .lp +15 15 int is ignored. .s3 .lp +6 6 \fBs\fIx\fR The top of the stack is popped and stored into a register named .it x, where .it x may be any character. If the .bd s is capitalized, .it x is treated as a stack and the value is pushed on it. .s3 .lp +6 6 \fBl\fIx\fR The value in register .it x is pushed on the stack. The register .it x is not altered. All registers start with zero value. If the .bd l is capitalized, register .it x is treated as a stack and its top value is popped onto the main stack. .s3 .lp +6 6 \fng a symbol table. If it is omitted, the symbol table is obtained from the file being debugged, or if not there from .bd a.out. If no appropriate name list file can be found, .it db can still be used but some of its symbolic facilities become unavailable. .s3 For the meaning of the optional third argument, see the last paragraph below. .s3 The format for most .it db requests is an address followed by a one character command. Addresses are expressions built up as follows: .s3 .lp +4 3 1. A name has the valuebs= input block size (default 512) .lp +15 15 obs= output block size (default 512) .lp +15 15 bs= set both input and output block size, superseding .it ibs and .it obs; also, if no conversion is specified, it is particularly efficient since no copy need be done .lp +15 15 cbs=\fIn\fR conversion buffer size .lp +15 15 skip=\fIn\fR skip \fIn\fR input records before starting copy .lp +15 15 count=\fIn\fR copy only \fIn\fR input records .lp +15 15 conv=ascii convert EBCDIC to ASCII .lp +15 10 ebcdic convert ASCBd\fR The top value on the stack is duplicated. .s3 .lp +6 6 \fBp\fR The top value on the stack is printed. The top value remains unchanged. .s3 .lp +6 6 \fBf\fR All values on the stack and in registers are printed. .s3 .lp +6 6 \fBq\fR exits the program. If executing a string, the recursion level is popped by two. If .bd q is capitalized, the top value on the stack is popped and the string execution level is popped by that value. .s3 .lp +6 6 \fBx\fR treats the top element of the stack as a character strin assigned to it when the input file was assembled. It may be relocatable or not depending on the use of the name during the assembly. .s3 .lp +4 3 2. An octal number is an absolute quantity with the appropriate value. .s3 .lp +4 3 3. A decimal number immediately followed by `\fB.\fR' is an absolute quantity with the appropriate value. .s3 .lp +4 3 4. An octal number immediately followed by \fBr\fR is a relocatable quantity with the appropriate value. .s3 .lp +4 3 5. The symbol \fB.\fR indicates the current II to EBCDIC .lp +15 10 lcase map alphabetics to lower case .lp +15 10 ucase map alphabetics to upper case .lp +15 10 swab swap every pair of bytes .lp +15 10 noerror do not stop processing on an error .lp +15 10 sync pad every input record to \fIibs\fR .lp +15 10 .li ... , ... several comma-separated conversions .i0 .s3 .fi Where sizes are specified, a number of bytes is expected. A number may end with .bd "k, b" or .bd w to specify multiplication by 1024, 512, or 2 respectively. Also a pair of numbers mayg and executes it as a string of dc commands. .s3 .lp +6 6 \fB[ ... ]\fR puts the bracketed ascii string onto the top of the stack. .s3 .lp +6 6 \fIx =x\fR .br The top two elements of the stack are popped and compared. Register .it x is executed if they obey the stated relation. .s3 .lp +6 6 \fBv\fR replaces the top element on the stack by its square root. Any existing fractional part of the argument is taken into account, but otherwise the scale factor is ignored. .s3 .lp +6 6 \fB!\fR interprets the pointer of \fIdb\fR. The current pointer is set by many \fIdb\fR requests. .s3 .lp +4 3 6. A \fB*\fR before an expression forms an expression whose value is the number in the word addressed by the first expression. A \fB*\fR alone is equivalent to `\fB*.\fR'. .s3 .lp +4 3 7. Expressions separated by \fB+\fR or blank are expressions with value equal to the sum of the components. At most one of the components may be relocatable. .s3 .lp +4 3 8. Expressions separated by \fB\*-\fR form an expression with value be separated by .bd x to indicate a product. .s3 .it Cbs is used only if .it ascii or .it ebcdic conversion is specified. In the former case .it cbs characters are placed into the conversion buffer, converted to ASCII, and trailing blanks trimmed and new-line added before sending the line to the output. In the latter case ASCII characters are read into the conversion buffer, converted to EBCDIC, and blanks added to make up an output record of size .it cbs. .s3 After completion, .it dd reports the number ofrest of the line as a UNIX command. .s3 .lp +6 6 \fBc\fR All values on the stack are popped. .s3 .lp +6 6 \fBi\fR The top value on the stack is popped and used as the number radix for further input. .s3 .lp +6 6 \fBo\fR The top value on the stack is popped and used as the number radix for further output. .s3 .lp +6 6 \fBk\fR the top of the stack is popped, and that value is used as a non-negative scale factor: the appropriate number of places are printed on output, and maintained during multiplication, divi equal to the difference to the components. If the right component is relocatable, the left component must be relocatable. .s3 .lp +4 3 9. Expressions are evaluated left to right. .s3 .in \n(inu Names for registers are built in: .s3 .bd " r0 ... r5" .bd " sp" .bd " pc" .bd " fr0 ... fr5" .s3 These may be examined. Their values are deduced from the contents of the stack in a core image file. They are meaningless in a file that is not a core image. .s3 If no address is given for a command, the curren whole and partial input and output blocks. .s3 For example, to read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into the ASCII file .it x: .s3 dd if=/dev/rmt0 of=x ibs=800 cbs=80 conv=ascii,lcase .s3 Note the use of raw magtape. .it Dd is especially suited to I/O on the raw physical devices because it allows reading and writing in arbitrary record sizes. .sh "SEE ALSO" cp (I) .sh BUGS The ASCII/EBCDIC conversion tables are taken from the 256 character standard in the CACM Nov, 196sion, and exponentiation. The interaction of scale factor, input base, and output base will be reasonable if all are changed together. .s3 .lp +6 6 \fBz\fR The stack level is pushed onto the stack. .s3 .lp +6 6 \fB?\fR A line of input is taken from the input source (usually the console) and executed. .s3 .i0 An example which prints the first ten values of n! is .nf .s3 .in +3 .bd "[la1+dsa*pla10>y]sy" .bd "0sa1" .bd lyx .i0 .fi .sh "SEE ALSO" bc (I), which is a preprocessor for .it dc providing infix notatit address (also specified by ``\fB.\fR'') is assumed. In general, ``\fB.\fR'' points to the last word or byte printed by .it db. .s3 There are .it db commands for examining locations interpreted as numbers, machine instructions, ASCII characters, and addresses. For numbers and characters, either bytes or words may be examined. The following commands are used to examine the specified file. .s3 .lp +4 3 / The addressed word is printed in octal. .s3 .lp +4 3 \\ The addressed byte is printed in octal. .s3 .lp 8. It is not clear how this relates to real life. .s3 Newlines are inserted only on conversion to ASCII; padding is done only on conversion to EBCDIC. There should be separate options. on and a C-like syntax which implements functions and reasonable control structures for programs. .sh DIAGNOSTICS (x) ? for unrecognized character x. .br (x) ? for not enough elements on the stack to do what was asked by command x. .br `Out of space' when the free list is exhausted (too many digits). .br `Out of headers' for too many numbers being kept around. .br `Out of pushdown' for too many items on the stack. .br `Nesting Depth' for too many levels of nested execution. .sh BUGS +4 3 " The addressed word is printed as two ASCII characters. .s3 .lp +4 3 .tr |\*a | The addressed byte is printed as an ASCII character. .s3 .tr || .lp +4 3 \*g The addressed word is printed in decimal. .s3 .lp +4 3 ? The addressed word is interpreted as a machine instruction and a symbolic form of the instruction, including symbolic addresses, is printed. Often, the result will appear exactly as it was written in the source program. .s3 .lp +4 3 & The addressed word is interpreted as a symbolic address a.th DC I 2/8/75 .sh NAME dc \*- desk calculator .sh SYNOPSIS .bd dc [ file ] .sh DESCRIPTION .it Dc is an arbitrary precision arithmetic package. Ordinarily it operates on decimal integers, but one may specify an input base, output base, and a number of fractional digits to be maintained. The overall structure of .it dc is a stacking (reverse Polish) calculator. If an argument is given, input is taken from that file until its end, then from the standard input. The following constructions are recognized: .s3RUX[^adghknqtwz}ind is printed as the name of the symbol whose value is closest to the addressed word, possibly followed by a signed offset. .s3 .lp +4 3 (i. e., the character ``new line'') This command advances the current location counter ``\fB.\fR'' and prints the resulting location in the mode last specified by one of the above requests. .s3 .lp +4 3 ^ This character decrements ``\fB.\fR'' and prints the resulting location in the mode last selected one of the above requests. It is a converse to . .s3 .lp +4 3 % Exit. .s3 .in \n(inu Odd addresses to word-oriented commands are rounded down. The incrementing and decrementing of ``\fB.\fR'' done by the .bd and .bd ^ requests is by one or two depending on whether the last command was word or byte oriented. .s3 The address portion of any of the above commands may be followed by a comma and then by an expression. In this case that number of sequential words or bytes specified by the expression is printed. ``\fB.\fR'' is advanced so that it points at the last thio examine the registers and other per-process data in a core image; also there should be some way of specifying double-precision addresses. It does not know yet about shared text segments. fR sort output on column 2 .lp +5 3 \fB3\fR sort output on column 3 .s3 .i0 .sh FILES .dt /tmp/crt?? temporaries .br /usr/lib/aign default assembler .it ignore file .br /usr/lib/cign default C .it ignore file .br /usr/bin/crpost post processor .br /usr/bin/upost post processor for .bd \*-u option .br /bin/sort used to sort temporaries .br .s3 .fi .sh "SEE ALSO" as (I), cc (I) .sh BUGS ng printed. .s3 There are two commands to interpret the value of expressions. .s3 .lp +4 3 = When preceded by an expression, the value of the expression is typed in octal. When not preceded by an expression, the value of ``\fB.\fR'' is indicated. This command does not change the value of ``\fB.\fR''. .s3 .lp +4 3 : An attempt is made to print the given expression as a symbolic address. If the expression is relocatable, that symbol is found whose value is nearest that of the expression, and the symbol is ty.th DATE I 11/1/74 .sh NAME date \*- print and set the date .sh SYNOPSIS .bd date [ .bd s ] [ mmddhhmm[yy] ] .sh DESCRIPTION If no argument is given, the current date and time are printed. If an argument is given, the current date is set. The first .it mm is the month number; .it dd is the day number in the month; .it hh is the hour number (24 hour system); the second .it mm is the minute number; .it yy is the last 2 digits of the year number and is optional. For example: .s3 .bd" date 10080045" .s3 se.th CP I 2/8/75 .sh NAME cp \*- copy .sh SYNOPSIS .bd cp file1 file2 .sh DESCRIPTION The first file is copied onto the second. The mode and owner of the target file are preserved if it already existed; the mode of the source file is used otherwise. .s3 If .it file2 is a directory, then the target file is a file in that directory with the file-name of .it file1. .s3 It is forbidden to copy a file onto itself. .sh "SEE ALSO" cat (I), pr (I), mv (I) .sh BUGS ped, followed by a sign and the appropriate offset. If the value of the expression is absolute, a symbol with exactly the indicated value is sought and printed if found; if no matching symbol is discovered, the octal value of the expression is given. .s3 .in \n(inu The following command may be used to patch the file being debugged. .s3 .lp +4 3 ! This command must be preceded by an expression. The value of the expression is stored at the location addressed by the current value of ``\fB.\fR''. The opcodes dots the date to Oct 8, 12:45 AM. The current year is the default if no year is mentioned. The system operates in GMT. .it Date takes care of the conversion to and from local standard and daylight time. .s3 If the argument is ``s,'' .it date calls the network file store via the TIU interface (if present) and sets the clock to the time thereby obtained. .sh DIAGNOSTICS ``No permission'' if you aren't the super-user and you try to change the date; ``bad conversion'' if the date set is syntactically incorrect. ..th COMM I 5/15/74 .sh NAME comm \*- print lines common to two files .sh SYNOPSIS .bd comm [ .bd \*- [ .bd 123 ] ] file1 file2 .sh DESCRIPTION .it Comm reads .it file1 and .it file2, which should be in sort, and produces a three column output: lines only in .it file1; lines only in .it file2; and lines in both files. The filename `\*-' means the standard input. .s3 Flags 1, 2, or 3 suppress printing of the corresponding column. Thus .bd comm .bd \*-12 prints only the lines common to the two files; .bd comm not appear in the symbol table, so the user must assemble them by hand. .s3 .in \n(inu The following command is used after a fault has caused a core image file to be produced. .s3 .lp +4 3 $ causes the fault type and the contents of the general registers and several other registers to be printed both in octal and symbolic format. The values are as they were at the time of the fault. .s3 .in \n(inu For some purposes, it is important to know how addresses typed by the user correspond with locations in the fish FILES /dev/tiu/d0 .sh BUGS .bd \*-23 prints only lines in the first file but not in the second; .bd comm .bd \*-123 is a no-op. .s3 .sh "SEE ALSO" cmp (I), diff (I) .sh BUGS le being debugged. The mapping algorithm employed by .it db is non-trivial for two reasons: First, in an .bd a.out file, there is a 20(8) byte header which will not appear when the file is loaded into core for execution. Therefore, apparent location 0 should correspond with actual file offset 20. Second, addresses in core images do not correspond with the addresses used by the program because in a core image there is a header containing the system's per-process data for the dumped process, and also because .th CREF I 2/5/73 .sh NAME cref \*- make cross reference listing .sh SYNOPSIS .bd cref [ .bd \*-acilostux123 ] name ... .sh DESCRIPTION .it Cref makes a cross reference listing of program files in assembler or C format. The files named as arguments in the command line are searched for symbols in the appropriate syntax. .s3 The output report is in four columns: .nf .s3 (1) (2) (3) (4) symbol file see text as it appears in file below .s3 .fi .it Cref uses either an .it ignore file or an .it only file. If.th CMP I 5/15/74 .sh NAME cmp \*- compare two files .sh SYNOPSIS .bd cmp [ .bd \*-l ] [ .bd \*-s ] file1 file2 .sh DESCRIPTION The two files are compared. (If .it file1 is `\*-', the standard input is used.) Under default options, .it cmp makes no comment if the files are the same; if they differ, it announces the byte and line number at which the difference occurred. If one file is an initial subsequence of the other, that fact is noted. Moreover, return code 0 is yielded for identical files, 1 for differthe stack is stored contiguously with the text and data part of the core image rather than at the highest possible locations. .it Db obeys the following rules: .s3 If exactly one argument is given, and if it appears to be an .bd a.out file, the 20-byte header is skipped during addressing, i.e., 20 is added to all addresses typed. As a consequence, the header can be examined beginning at location \*-20. .s3 If exactly one argument is given and if the file does not appear to be an .bd a.out file, no mapping i the .bd \*-i option is given, the next argument is taken to be an .it ignore file; if the .bd \*-o option is given, the next argument is taken to be an .it only file. .it Ignore and .it only files are lists of symbols separated by new lines. All symbols in an .it ignore file are ignored in columns (1) and (3) of the output. If an .it only file is given, only symbols in that file appear in column (1). At most one of .bd \*-i and .bd \*-o may be used. The default setting is .bd \*-i. Assembler predefined syment files, and 2 for an inaccessible or missing argument. .s3 Options: .s3 .lp +6 3 \fB\*-l\fR Print the byte number (decimal) and the differing bytes (octal) for each difference. .s3 .lp +6 3 \fB\*-s\fR Print nothing for differing files; return codes only. .i0 .dt .sh "SEE ALSO" diff (I), comm (I) .sh BUGS s done. .s3 If zero or two arguments are given, the mapping appropriate to a core image file is employed. This means that locations above the program break and below the stack effectively do not exist (and are not, in fact, recorded in the core file). Locations above the user's stack pointer are mapped, in looking at the core file, to the place where they are really stored. The per-process data kept by the system, which is stored in the first part of the core file, cannot currently be examined (except by \fbols or C keywords are ignored. .s3 The .bd \*-s option causes current symbols to be put in column 3. In the assembler, the current symbol is the most recent name symbol; in C, the current function name. The .bd \*-l option causes the line number within the file to be put in column 3. .s3 The .bd \*-t option causes the next available argument to be used as the name of the intermediate temporary file (instead of /tmp/crt??). The file is created and is not removed at the end of the process. .s3 Options: .s3 ..th CHMOD I 2/8/75 .sh NAME chmod \*- change mode .sh SYNOPSIS .bd chmod octal file ... .sh DESCRIPTION The octal mode replaces the mode of each of the files. The mode is constructed from the OR of the following modes: .s3 .lp +10 7 4000 set user ID on execution .lp +10 7 2000 set group ID on execution .lp +10 7 1000 sticky bit for shared, pure-procedure programs (see below) .lp +10 7 0400 read by owner .lp +10 7 0200 write by owner .lp +10 7 0100 execute (search in directory) by owner .lp +10 7 0070 read, B$\fR). .s3 If one wants to examine a file which has an associated name list, but is not a core image file, the last argument ``\fB\*-\fR'' can be used (actually the only purpose of the last argument is to make the number of arguments not equal to two). This feature is used most frequently in examining the memory file /dev/mem. .sh "SEE ALSO" as (I), core (V), a.out (V), od (I) .sh DIAGNOSTICS ``File not found'' if the first argument cannot be read; otherwise ``\fB?\fR''. .sh BUGS There should be some way tlp +5 3 \fBa\fR assembler format (default) .lp +5 3 \fBc\fR C format input .lp +5 3 \fBi\fR use .it ignore file (see above) .lp +5 3 \fBl\fR put line number in col. 3 (instead of current symbol) .lp +5 3 \fBo\fR use .it only file (see above) .lp +5 3 \fBs\fR current symbol in col. 3 (default) .lp +5 3 \fBt\fR user supplied temporary file .lp +5 3 \fBu\fR print only symbols that occur exactly once .lp +5 3 \fBx\fR print only C external symbols .lp +5 3 \fB1\fR sort output on column 1 (default) .lp +5 3 \fB2\write, execute (search) by group .lp +10 7 0007 read, write, execute (search) by others .s3 .i0 Only the owner of a file (or the super-user) may change its mode. .s3 If an executable file is set up for sharing (``\*-n'' option of .it "ld (I)" ), then mode 1000 prevents the system from abandoning the swap-space image of the program-text portion of the file when its last user terminates. Thus when the next user of the file executes it, the text need not be read from the file system but can simply be swapped in, saving time. Ability to set this bit is restricted to the super-user since swap space is consumed by the images; it is only worth while for heavily used commands. .s3 .sh "SEE ALSO" ls (I), chmod (II) .sh BUGS citly changed again: .lp +8 4 \fBo\fR octal (default) .lp +8 4 \fBi\fR decimal .lp +8 4 \fBf\fR single-precision floating-point .lp +8 4 \fBd\fR double-precision floating-point .s3 .i0 .lp +4 4 \\ Print the specified bytes in octal. .s3 .lp +4 4 = print the value of the addressed expression in octal. .c2 @ .s3 .lp +4 4 \*a print the addressed bytes as characters. Control and non-ASCII characters are escaped in octal. .c2 ' .s3 .lp +4 4 " take the contents of the address as a pointer to a sequence of charact.th CC I 5/15/74 .sh NAME cc \*- C compiler .sh SYNOPSIS .bd cc [ .bd \*-c ] [ .bd \*-p ] [ .bd \-f ] [ .bd \*-O ] [ .bd \*-S ] [ .bd \*-P ] file ... .sh DESCRIPTION .it Cc is the UNIX C compiler. It accepts three types of arguments: .s3 Arguments whose names end with `.c' are taken to be C source programs; they are compiled, and each object program is left on the file whose name is that of the source with `.o' substituted for `.c'. The `.o' file is normally deleted, however, if a single C program is compil.th CHDIR I 5/15/74 .sh NAME chdir \*- change working directory .sh SYNOPSIS .bd chdir directory .sh DESCRIPTION .it Directory becomes the new working directory. The process must have execute (search) permission in .it directory. .s3 Because a new process is created to execute each command, .it chdir would be ineffective if it were written as a normal command. It is therefore recognized and executed by the Shell. .sh "SEE ALSO" sh (I), pwd (I) .sh BUGS ers, and print the characters up to a null byte. Control and non-ASCII characters are escaped as octal. .s3 .lp +4 4 & Try to interpret the contents of the address as a pointer, and print symbolically where the pointer points. The typeout contains the name of an external symbol and, if required, the smallest possible positive offset. Only external symbols are considered. .s3 .lp +4 4 ? Interpret the addressed location as a PDP-11 instruction. .s3 .lp +4 4 $\fIm\fR If no .it m is given, print a stack trace oed and loaded all at one go. .s3 The following flags are interpreted by .it cc. See .it "ld (I)" for load-time flags. .s3 .lp +6 5 \fB\*-c\fR Suppress the loading phase of the compilation, and force an object file to be produced even if only one program is compiled. .s3 .lp +6 5 \fB\*-p\fR Arrange for the compiler to produce code which counts the number of times each routine is called; also, if loading takes place, replace the standard startup routine by one which automatically calls the .it monitor subroutf the terminated or stopped program. The last call made is listed first; the actual arguments to each routine are given in octal. (If this is inappropriate, the arguments may be examined by name in the desired format using ``/''.) If .it m is ``r'', the contents of the PDP-11 general registers are listed. If .it m is ``f'', the contents of the floating-point registers are listed. In all cases, the reason why the program stopped or terminated is indicated. .s3 .lp +4 4 %\fIm\fR According to .it m, set or deline (III) at the start and arranges to write out a .it mon.out file at normal termination of execution of the object program. An execution profile can then be generated by use of .it prof (I). .s3 .lp +6 5 \fB\-f\fR In systems without hardware floating-point, use a version of the C compiler which handles floating-point constants and loads the object program with the floating-point interpreter. Do not use if the hardware is present. .s3 .lp +6 5 \fB\*-O\fR Invoke an object-code optimizer. .s3 .lp +6 5 \fB\*-.th CDB I 2/8/75 .sh NAME cdb \*- C debugger .sh SYNOPSIS .bd cdb [ a.out [ core ] ] .sh DESCRIPTION .it Cdb is a debugger for use with C programs. It is useful for both post-mortem and interactive debugging. An important feature of .it cdb is that even in the interactive case no advance planning is necessary to use it; in particular it is not necessary to compile or load the program in any special way nor to include any special routines in the object file. .s3 The first argument to .it cdb is an object proete a breakpoint, or run or continue the program: .s3 .lp +8 4 \fBb\fR An address within the program must be given; a breakpoint is set there. Ordinarily, breakpoints will be set on the entry points of functions, but any location is possible as long as it is the first word of an instruction. (Labels don't appear in the symbol table yet.) Stopping at the actual first instruction of a function is undesirable because to make symbolic printouts work, the function's save sequence has to be completed; therefore .S\fR Compile the named C programs, and leave the assembler-language output on corresponding files suffixed `.s'. .s3 .lp +6 5 \fB\*-P\fR Run only the macro preprocessor on the named C programs, and leave the output on corresponding files suffixed `.i'. .i0 .dt .s3 Other arguments are taken to be either loader flag arguments, or C-compatible object programs, typically produced by an earlier .it cc run, or perhaps libraries of C-compatible routines. These programs, together with the results of any compilationgram, preferably containing a symbol table; if not given ``a.out'' is used. The second argument is the name of a core-image file; if it is not given, ``core'' is used. The core file need not be present. .s3 Commands to .it cdb consist of an address, followed by a single command character, possibly followed by a command modifier. Usually if no address is given the last-printed address is used. An address may be followed by a comma and a number, in which case the command applies to the appropriate number of sit cdb automatically moves breakpoints at the start of functions down to the first real code. .s3 It is impossible to set breakpoints on pure-procedure programs (\-n flag on cc or ld) because the program text is write-protected. .s3 .lp +8 4 \fBd\fR An address must be given; the breakpoint at that address is removed. .s3 .lp +8 4 \fBr\fR Run the program being debugged. Following the ``%r'', arguments may be given; they cannot specify I/O redirection (``>'', ``<'') or filters. No address is permissible, and s specified, are loaded (in the order given) to produce an executable program with name .bd a.out. .sh FILES file.c input file .br file.o object file .br a.out loaded output .br /tmp/ctm? temporary .br /lib/c[01] compiler .br /lib/fc[01] floating-point compiler .br /lib/c2 optional optimizer .br /lib/crt0.o runtime startoff .br /lib/mcrt0.o runtime startoff of profiling .br /lib/fcrt0.o runtime startoff for floating-point interpretation .br /lib/libc.a C library; see section III. .br /lib/liba.a Assembluccessive addresses. .s3 Addresses are expressions composed of names, decimal numbers, and octal numbers (which begin with ``0'') and separated by ``+'' and ``\*-''. Evaluation proceeds left-to-right. .s3 Names of external variables are written just as they are in C. For various reasons the external names generated by C all begin with an underscore, which is automatically tacked on by .it cdb. Currently it is not possible to suppress this feature, so symbols (defined in assembly-language programs) which do the program is restarted from scratch, not continued. Breakpoints should have been set if any were desired. The program will stop if any signal is generated, such as illegal instruction (including simulated floating point), bus error, or interrupt (see signal(II)); it will also stop when a breakpoint occurs and in any case announce the reason. Then a stack trace can be printed, named locations examined, etc. .s3 .lp +8 4 \fBc\fR Continue after a breakpoint. It is possible but probably useless to continue afer library used by some routines in libc.a .sh "SEE ALSO" ``Programming in C\(em a tutorial,'' C Reference Manual, monitor (III), prof (I), cdb (I), ld (I). .sh DIAGNOSTICS The diagnostics produced by C itself are intended to be self-explanatory. Occasional messages may be produced by the assembler or loader. Of these, the most mystifying are from the assembler, in particular ``m,'' which means a multiply-defined external symbol (function or data). .sh BUGS not begin with underscore are inaccessible. .s3 Variables local to a function (automatic, static, and arguments) are accessible by writing the name of the function, a colon ``:'', and the name of the local variable (e.g. ``main:argc''). There is no notion of the ``current'' function; its name must always be written explicitly. .s3 A number which begins with ``0'' is taken to be octal; otherwise numbers are decimal, just as in C. There is no provision for input of floating numbers. .s3 The construction ``namter an error since there is no way to repair the cause of the error. .s3 .i0 .sh "SEE ALSO" cc (I), db (I), C Reference Manual .sh BUGS Use caution in believing values of register variables at the lowest levels of the call stack; the value of a register is found by looking at the place where it was supposed to have been saved by the callee. .s3 Some things are still needed to make .it cdb uniformly better than .it db: non-C symbols, patching files, patching core images of programs being run. It would be des.th CAT I 1/15/73 .sh NAME cat \*- concatenate and print .sh SYNOPSIS .bd cat file ... .sh DESCRIPTION .it Cat reads each file in sequence and writes it on the standard output. Thus .s3 .bd " cat file" .s3 prints the file, and .s3 .bd " cat file1 file2 >file3" .s3 concatenates the first two files and places the result on the third. .s3 If no input file is given, or if the argument `\-' is encountered, .it cat reads from the standard input file. .s3 .sh "SEE ALSO" pr(I), cp(I) .sh DIAGNOSTICS none; if a e[expression]'' assumes that .it name is a pointer to an integer and is equivalent to the contents of the named cell plus twice the expression. Notice that .it name has to be a genuine pointer and that arrays are not accessible in this way. This is a consequence of the fact that types of variables are not currently saved in the symbol table. .s3 The command characters are: .s3 .lp +4 4 /\fIm\fR print the addressed words. .it m indicates the mode of printout; specifying a mode sets the mode until it is expliirable to have the types of variables around to make the correct style printout more automatic. Structure members should be available. .s3 Naturally, there are all sorts of neat features not handled, like conditional breakpoints, optional stopping on certain signals (like illegal instructions, to allow breakpointing of simulated floating-point programs). file cannot be found it is ignored. .sh BUGS .bd "cat x y >x" and .bd "cat x y >y" cause strange results. .th BC I 2/20/75 .sh NAME bc \*- arbitrary precision interactive language .sh SYNOPSIS .bd bc [ .bd \-l ] [ file ... ] .sh DESCRIPTION .it Bc is an interactive processor for a language which resembles C but provides unlimited precision arithmetic. It takes input from any files given, then reads the standard input. The `\-l' argument stands for the name of a library of mathematical subroutines which contains sine (named `s'), cosine (`c'), arctangent (`a'), natural logarithm (`l'), and exponential (`e'). Thet (that does not have `=' as its highest operator) is printed. .s3 Statements have the following syntax: .s3 .lp +5 5 expression .br The expression is executed for its side effects (assignment or function call) or for printing as described above. .s3 .lp +5 5 .bd comment .li ... .br This statement is ignored. It is used to interject commentary in a program. .s3 .lp +5 5 .bd done .br Return to system level. .s3 .lp +5 5 .bd draw expression expression expression .br A line is drawn on the Tektronix 611 displae result is the negation of the expression. .s3 .lp +5 5 expression operator expression .br Common functions of two arguments are abbreviated by the two arguments separated by an operator denoting the function. A complete list of operators is given below. .s3 .lp +5 5 expression .bd ( [expression [ .bd , expression] ... ] .bd ) .br Functions of an arbitrary number of arguments can be called by an expression followed by the arguments in parentheses separated by commas. The expression evaluates to the line nu syntax for .it bc programs is as follows; E means expression, S means statement. .s3 .lp +6 6 Comments .br are enclosed in /* and */. .s3 .lp +6 6 Names .br letters a\-z .br array elements: letter[E] .br The words `ibase', `obase', and `scale' .s3 .lp +6 6 Other operands .br arbitrarily long numbers with optional sign and decimal point. .br ( E ) .br sqrt ( E ) .br ( E , ... , E ) .s3 .lp +6 6 Operators .br + \- * / % ^ .br ++ \-\- (prefix and postfix; apply to names) .br == <= >y `/dev/vt0' from the current display position to the XY co-ordinates specified by the first two expressions. The scale is zero to one in both X and Y directions. If the third expression is zero, the line is invisible. The current display position is set to the end point. .s3 .lp +5 5 .bd display list .br The list of expressions and strings is concatenated and displayed (i.e. printed) on the 611 starting at the current display position. The current display position is not changed. .s3 .lp +5 5 .bd dump .br mber of the entry of the function in the internally stored statements. This causes the internal statements to be compiled. If the expression evaluates negative, a builtin function is called. The list of builtin functions appears below. .s3 .lp +5 5 name .bd [ expression [ .bd , expression ] ... .bd ] .br Each expression is truncated to an integer and used as a specifier for the name. The result is syntactically identical to a name. .bd a[1,2] is the same as .bd a[1][2]. The truncated expressions are restric= != < > .br = =+ =\- =* =/ =% =^ .br .s3 .lp +6 6 Statements .br E .br { S ; ... ; S } .br if ( E ) S .br while ( E ) S .br for ( E ; E ; E ) S .br null statement .br break .br quit .s3 .lp +6 6 Function definitions are exemplified by .br define ( ,..., ) { .br auto , ... , .br S; ... S .br return ( E ) .br } .s3 .i0 .dt All function arguments are passed by value. .s3 The value of a statement that is an expression is printed unless the main operator iThe name and current value of every variable is printed. .s3 .lp +5 5 .bd edit .br The UNIX editor, .it ed, is invoked with the .it file argument. After the editor exits, this file is recompiled. .s3 .lp +5 5 .bd erase .br The 611 screen is erased. .s3 .lp +5 5 .bd for name .bd = expression expression statement .br .lp +5 5 .bd for name .bd = expression expression .br .li ... .lp +5 5 .bd next .br The .it for statement repetitively executes a statement (first form) or a group of statements (second form) undted to values between 0 and 32767. .s3 .i0 The following is the list of operators: .s3 .lp +5 5 = .br = is the assignment operator. The left operand must be a name or an array element. The result is the right operand. Assignment binds right to left, all other operators bind left to right. .s3 .lp +5 5 & | .br & (logical and) has result zero if either of its arguments are zero. It has result one if both its arguments are non-zero. | (logical or) has result zero if both of its arguments are zero. It has ress an assignment. Either semicolons or newlines may separate statements. Assignment to .it scale influences the number of digits to be retained on arithmetic operations. Assignments to .it ibase or .it obase set the input and output number radix respectively. .s3 The same letter may be used as an array name, a function name, and a simple variable simultaneously. `Auto' variables are saved and restored during function calls. All other variables are global to the program. When using arrays as function argumenter control of a named variable. The variable takes on the value of the first expression, then is incremented by one on each loop, not to exceed the value of the second expression. .s3 .lp +5 5 .bd goto expression .br The expression is evaluated, truncated to an integer and execution goes to the corresponding integer numbered statment. If executed from immediate mode, the internal statements are compiled first. .s3 .lp +5 5 .bd if expression statement .br .lp +5 5 .bd if expression .br .li ... .lp +5 5 [ .bdult one if either of its arguments are non-zero. .s3 .lp +5 5 < <= > >= == <> .br The relational operators (< less than, <= less than or equal, > greater than, >= greater than or equal, == equal to, <> not equal to) return one if their arguments are in the specified relation. They return zero otherwise. Relational operators at the same level extend as follows: a>b>c is the same as a>b&b>c. .s3 .lp +5 5 + \*- .br Add and subtract. .s3 .lp +5 5 * / .br Multiply and divide. .s3 .lp +5 5 ^ .br Exponentiatis or defining them as automatic variables empty square brackets must follow the array name. .s3 For example .s3 .nf scale = 20 define e(x){ auto a, b, c, i, s a = 1 b = 1 s = 1 for(i=1; 1==1; i++){ a = a*x b = b*i c = a/b if(c == 0) return(s) s = s+c } } .s3 .fi defines a function to compute an approximate value of the exponential function and .s3 .nf for(i=1; i<=10; i++) e(i) .fi .s3 prints approximate values of the exponential function of the first ten integers. .sh FILES /usr/lib/lib.b m else .br .li ... ] .lp +5 5 .bd fi .br The statement (first form) or group of statements (second form) is executed if the expression evaluates to non-zero. In the second form, an optional .bd else allows for a group of statements to be executed when the first group is not. .s3 .lp +5 5 .bd list [expression [expression]] .br .br list is used to print out the stored internal statements. If no arguments are given, all internal statements are printed. If one argument is given, only that internal statement is lon. .s3 .i0 The following is a list of builtin functions: .s3 .lp +5 5 .bd arg(i) .br is the value of the \fIi\fR -th actual parameter on the current level of function call. .s3 .lp +5 5 .bd exp(x) .br is the exponential function of \fIx\fR. .s3 .lp +5 5 .bd log(x) .br is the natural logarithm of \fIx\fR. .s3 .lp +5 5 .bd sqr(x) .br is the square root of \fIx\fR. .s3 .lp +5 5 .bd sin(x) .br is the sine of \fIx\fR (radians). .s3 .lp +5 5 .bd cos(x) .br is the cosine of \fIx\fR (radians). .s3 .lp +5 5 .bd atnathematical library .sh "SEE ALSO" .it dc (I), C Reference Manual, ``BC \- An Arbitrary Precision Desk-Calculator Language.'' .sh BUGS No &&, | | yet. .br .it for statement must have all three E's .br .it quit is interpreted when read, not when executed. isted. If two arguments are given, all internal statements inclusively between the arguments are printed. .s3 .lp +5 5 .bd print list .br The list of expressions and strings are concatenated and printed. (A string is delimited by " characters.) .s3 .lp +5 5 .bd prompt list .br .it Prompt is the same as .it print except that no newline character is printed. .s3 .lp +5 5 .bd return [expression] .br The expression is evaluated and the result is passed back as the value of a function call. If no expression is (x) .br is the arctangent of \fIx\fR. Its value is between \*-\(*p/2 and \(*p/2. .s3 .lp +5 5 .bd "rnd( )" .br is a uniformly distributed random number between zero and one. .s3 .lp +5 5 .bd "expr( )" .br is the only form of program input. A line is read from the input and evaluated as an expression. The resultant value is returned. .s3 .lp +5 5 .bd abs(x) .br is the absolute value of \fIx\fR. .s3 .lp +5 5 .bd int(x) .br returns \fIx\fR truncated (towards 0) to an integer. .i0 .sh FILES .dt /tmp/btm? tempogiven, zero is returned. .s3 .lp +5 5 .bd run .br The internal statements are compiled. The symbol table is re-initialized. The random number generator is reset. Control is passed to the lowest numbered internal statement. .s3 .lp +5 5 .bd save [expression [expression]] .br .it Save is like .it list except that the output is written on the .it file argument. If no argument is given on the command, .bd b.out is used. .s3 .i0 Expressions have the following syntax: .s3 .lp +5 5 name .br A name is used to specirary .br b.out save file .sh DIAGNOSTICS Syntax errors cause the incorrect line to be typed with an underscore where the parse failed. All other diagnostics are self explanatory. .sh BUGS Has been known to give core images. .th BAS I 5/15/74 .sh NAME bas \*- basic .sh SYNOPSIS .bd bas [ file ] .sh DESCRIPTION .it Bas is a dialect of Basic. If a file argument is provided, the file is used for input before the console is read. .it Bas accepts lines of the form: .s3 statement integer statement .s3 Integer numbered statements (known as internal statements) are stored for later execution. They are stored in sorted ascending order. Non-numbered statements are immediately executed. The result of an immediate expression statemenfy a variable. Names are composed of a letter followed by letters and digits. The first four characters of a name are significant. .s3 .lp +5 5 number .br A number is used to represent a constant value. A number is written in Fortran style, and contains digits, an optional decimal point, and possibly a scale factor consisting of an .bd e followed by a possibly signed exponent. .s3 .lp +5 5 .bd ( expression .bd ) .br Parentheses are used to alter normal order of evaluation. .s3 .lp +5 5 \*_ expression .br Th.th AS I 1/15/73 .sh NAME as \*- assembler .sh SYNOPSIS .bd as [ .bd \*- ] name ... .sh DESCRIPTION .it As assembles the concatenation of the named files. If the optional first argument .bd \*- is used, all undefined symbols in the assembly are treated as global. .s3 The output of the assembly is left on the file .bd "a.out." It is executable if no errors occurred during the assembly, and if there were no unresolved external references. .sh FILES /lib/as2 pass 2 of the assembler .br /tmp/atm[1-3]? temporary .br a.out object .sh "SEE ALSO" ld (I), nm (I), db (I), a.out (V), `UNIX Assembler Manual'. .sh DIAGNOSTICS When an input file cannot be read, its name followed by a question mark is typed and assembly ceases. When syntactic or semantic errors occur, a single-character diagnostic is typed out together with the line number and the file name in which it occurred. Errors in pass 1 cause cancellation of pass 2. The possible errors are: .s3 .ta 3 ) Parentheses error .br ] Parentheses error .br < String not .th name section date .sh NAME .sh SYNOPSIS .sh DESCRIPTION .sh FILES .sh "SEE ALSO" .sh DIAGNOSTICS .sh BUGS .nf .bp .ce PERMUTED INDEX .sp 1.5 .nf .de xx \\h"3i-\\w'\\$1'u"\\$1 \\$2 .. .so ptxx terminated properly .br * Indirection used illegally .br .li \fB.\fR Illegal assignment to `\fB.\fR' .br A Error in address .br B Branch instruction is odd or too remote .br E Error in expression .br F Error in local (`f' or `b') type symbol .br G Garbage (unknown) character .br I End of file inside an if .br M Multiply defined symbol as label .br O Word quantity assembled at odd address .br P `\fB.\fR' different in pass 1 and 2 .br R Relocation error .br U Undefined symbol .br X Syntax error .br .sh BUGS Sif $2x != x goto both goto $1x : allx sh $0 1 I sh $0 2 II sh $0 3 III sh $0 4 IV sh $0 5 V sh $0 6 VI sh $0 7 VII sh $0 8 VIII : tx cat tocx? >cattoc ptx -t cattoc ptxx rm cattoc ed - tocx1 1,$s/([IV]*) /" "/ 1,$s/.*/.xx "&"/ w toc1 e tocx2 1,$s/([IV]*) /" "/ 1,$s/.*/.xx "&"/ w toc2 e tocx3 1,$s/([IV]*) /" "/ 1,$s/.*/.xx "&"/ w toc3 e tocx4 1,$s/([IV]*) /" "/ 1,$s/.*/.xx "&"/ w toc4 e tocx5 1,$s/([IV]*) /" "/ 1,$s/.*/.xx "&"/ w toc5 e tocx6 1,$s/([IV]*) /" "/ 1,$s/.*/.xx "&"/ w toc6 e tocx7 1,$s/([IV]*) /".nr in 5 .de i0 .in \n(in .. .de lp .i0 .ta \\$2+1 .in \\$1 .ti -\\$2 .. .de s1 .sp 1 .ne 4 .. .de s2 .sp 1 .. .de s3 .sp 1 .. .de fo 'sp 2 'tl ''- % -'' 'bp .. .de th .de x1 'sp 2 'tl '\\$1(\\$2)'\\$3'\\$1(\\$2)' 'sp 2 \\.. .wh -5 fo .wh 0 x1 .in \n(in .. .de sh .s1 .ne 5 .ti 0 \\$1 .br .. .de bd .tr __ .ul \\$1 .. .de bn .tr __ .ul \\$1\\t .. .de it .tr __ .ul .li \\$1 .. .de dt .ta 8 16 24 32 40 48 56 64 .. .ds b B .ds G G .ds a ' .ds - - .ds _ _ .ds v | .ds p J .ds r .ds g ` .ds X X .ds u u .ds ymbol table overflow is not checked. \fBx\fR errors can cause incorrect line numbers in following diagnostics. "/ 1,$s/.*/.xx "&"/ w toc7 e tocx8 1,$s/([IV]*) /" "/ 1,$s/.*/.xx "&"/ w toc8 q exit : 1x sh $0 1 I exit : 2x sh $0 2 II exit : 3x sh $0 3 III exit : 4x sh $0 4 IV exit : 5x sh $0 5 V exit : 6x sh $0 6 VI exit : 7x sh $0 7 VII exit : 8x sh $0 8 VIII exit : x echo usage: sh tocrc "[12345678]" exit : both chdir /usr/man/man$1 ls >xa ed - xa v/\.[12345678]$/d g/intro.2/d g/^/s//e /\ .a\ /NAME/1p w q ed - xb echo "1,$s/ *\\\*- */("$2") /" >xa if $1 != 2 goto 1f echo 0a >>xa echo "intro(II) introduction to> -> .ds | .th AR I 3/15/72 .sh NAME ar \*- archive and library maintainer .sh SYNOPSIS .bd ar key afile name ... .sh DESCRIPTION .it Ar maintains groups of files combined into a single archive file. Its main use is to create and update library files as used by the loader. It can be used, though, for any similar purpose. .s3 .it Key is one character from the set .bd drtux, optionally concatenated with .bd v. .it Afile is the archive file. The .it names are constituent files in the archive file. The meanings of the .it system calls" >>xa echo . >>xa : 1f echo w /usr/man/man0/tocx$1 >>xa ed - xb \(-> .de dt .ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 6i .. .lg 0 ed are replaced. If no names are given, all files in the archive that have been modified are replaced by the modified version. .s3 .bd x extracts the named files. If no names are given, all files in the archive are extracted. In neither case does .bd x alter the archive file. .s3 .bd v means verbose. Under the verbose option, .it ar gives a file-by-file description of the making of a new archive file from the old archive and the constituent files. The following abbreviations are used: .s3 .bd " c" copy .bVII. USER MAINTAINED SUBROUTINES .sp .5 .so toc7 .sp 1.5 .ne .5i VIII. SYSTEM MAINTENANCE .sp .5 .so toc8 .in -1i .lg .ll 6i .lt 6i .ps 10 .vs 12p .de he .tl '-''' 'sp .5i 'ft R .CH 'ft 'ps 'sp .5i .. .de fo 'ft R 'ps 10 'sp .5i .CF 'ft 'ps 'bp .. .wh 0 he .wh -1i fo .de pg .sp .5 .. .tr | .br .sp 3i .ps 18 .ft B .ce UNIX PROGRAMMER'S MANUAL .ps 12 .vs 14p .sp 2 .ft I .ce Sixth Edition .sp 3 .ce 3 K. Thompson .sp .5 D. M. Ritchie .sp 2 .ce May, 1975 .sp 2.5i .ps 10 .vs 12p .ft R .bp .sp 3i .sp 3i .ll 4.7i .in 1.5i .ft R This manual was set by a Graphic Systems phototypesetter driven by the \fItroff\fR formatting prograd " a" append .bd " d" delete .bd " r" replace .bd " x" extract .sh FILES /tmp/vtm? temporary .sh "SEE ALSO" ld (I), archive (V) .sh BUGS Option .bd tv should be implemented as a table with more information. .s3 There should be a way to specify the placement of a new file in an archive. Currently, it is placed at the end. .s3 Since .it ar has not been rewritten to deal properly with the new file system modes, extracted files have mode 666. .s3 For the same reason, only the first 8 characters of file.nr in .5i .de i0 .in \n(inu .. .de lp .tc  .tr  .i0 .ta \\$2/2u .in \\$1/2u .ti -\\$2/2u .. .de s1 .sp .10i .ne 2 .. .de s2 .sp .07i .. .de s3 .sp .07i .ne 2 .. .de fo 'ft R 'ps 10 'sp .50i 'tl ''- % -'' 'ft 'ps 'bp .. .de th .de x1 .tl '-''' 'ft R 'ps 10 'sp .50i 'tl '\\$1\|(\|\\$2\|)'\\$3'\\$1\|(\|\\$2\|)' 'ft 'ps 'sp .50i \\.. .wh -1i fo .wh 0 x1 .ft R .ps 10 .vs 11p .in \n(inu .. .wh 0 x1 .de sh .s1 .ft B .ps 8 .ti 0 \\$1 .ft .ps .br .. .de it 'ft I 'li \\$1 'ft .. .de bd 'ft B \\$1 'ft R .. .de bn 'm operating under the \s8UNIX\s10 system. The text of the manual was prepared using the \fIed\fR text editor. .br .ft R .ll 6i .in 0 .bp 1 .sp 3 .ce 2 PREFACE to the Sixth Edition .sp .de CF .ro .tl ''%'' .ar .. .sp 2 We are grateful to L. L. Cherry, R. C. Haight, S. C. Johnson, B. W. Kernighan, M. E. Lesk, and E. N. Pinson for their contributions to the system software, and to L. E. McMahon for software and for his contributions to this manual. We are particularly appreciative of the invaluable technical, names are significant. .s3 If the same file is mentioned twice in an argument list, it may be put in the archive twice. ft B \\$1 \\fR\\ .. .ds b \(*b .ds _ \(ul .ds - \(mi .ds a \(aa .ds v \(vb .ds p \(*p .ds r \(rg .ds g \(ga .ds | \| .ds X \(mu .ds u \(*m .ds G \(*G .ds > \(-> .de dt .ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 6i .. .lg editorial, and administrative efforts of J. F. Ossanna, M. D. McIlroy, and R. Morris. They all contributed greatly to the stock of \s8UNIX\s10 software and to this manual. Their inventiveness, thoughtful criticism, and ungrudging support increased immeasurably not only whatever success the \s8UNIX\s10 system enjoys, but also our own enjoyment in its creation. .bp .sp 2 .ce INTRODUCTION TO THIS MANUAL .pg .pg This manual gives descriptions of the publicly available features of \s8UNIX\s10. It provides neither a general overview \- see ``The \s8UNIX\s10 Time-sharing System'' (Comm. ACM \fB17\fR 7, July 1974, pp. 365-375) for that \- nor details of the implementation of the system, which remain to be disclosed. .pg Within the area it surveys, this manual attempts to be as complete 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, wf its purpose. .pg The \fIsynopsis\fR summarizes the use of the program being described. A few conventions are used, particularly in the Commands section: .pg .in 1i \fBBoldface\fR words are considered literals, and are typed just as they appear. .pg 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. .pg Ellipses ``.\|.\|.'' are used to show that the previous argument-prototype may be repeated. .pg A finaon terminals. These terminals generally have a speed switch which should be set at ``300'' (or ``30'' for 30 characters per second) and a half/full duplex switch which should be set at full-duplex. (This switch will often have to be changed since many other systems require half-duplex). When a connection is established, the system types ``login:''; you type your user name, followed by the ``return'' key. If you have a password, the system asks for it and turns off the printer on the terminal so the passwordas resisted. Inevitably, this means that many sections will soon be out of date. .pg This manual is divided into eight sections: .pg .nf I. Commands II. System calls III. Subroutines IV. Special files V. File formats and conventions VI. User-maintained programs VII. User-maintained subroutines VIII. Maintenance .pg .fi 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 resil convention is used by the commands themselves. An argument beginning with a minus sign ``_'' is often taken 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 ``_''. .pg .in .5i The \fIdescription\fR section discusses in detail the subject at hand. .pg The \fIfiles\fR section gives the names of files which are built into the program. .pg A .ft I see also .ft R section gives pointers to related in will not appear. After you have logged in, the ``return'', ``new line'', or ``linefeed'' keys will give exactly the same results. .pg .ul \s8TTY\s10 37 terminal:|| When you have established a data connection, the system types out a few garbage characters (the ``login:'' message at the wrong speed). Depress the ``break'' (or ``interrupt'') key; this is a speed-independent signal to \s8UNIX\s10 that a 150-baud terminal is in use. The system then will type ``login:,'' this time at the correct speed; you respode in directory .ft I /bin .ft R (for \fIbin\fR\|ary programs). Some programs also reside in .ft I /\|usr/\|bin, .ft R to save space in \fI/bin.\fR These directories are searched automatically by the command interpreter. .pg System calls are entries into the \s8UNIX\s10 supervisor. In assembly language, they are coded with the use of the opcode \fIsys\fR, a synonym for the \fItrap\fR instruction. In this edition, the C language interface routines to the system calls have been incorporated in section II. .pgformation. .pg A \fIdiagnostics\fR section discusses the diagnostic indications which may be produced. Messages which are intended to be self-explanatory are not listed. .pg The \fIbugs\fR section gives known bugs and sometimes deficiencies. Occasionally also the suggested fix is described. .pg .in 0 At the beginning of this document is a table of contents, organized by section and alphabetically within each section. There is also a permuted index derived from the table of contents. Within each index entry,nd with your user name. From the \s8TTY\s10 37 terminal, and any other which has the ``new-line'' function (combined carriage return and linefeed), terminate each line you type with the ``new-line'' key (\fInot\fR the ``return'' key). .pg .in 0 For all these terminals, it is important that you type your name in lower-case if possible; if you type upper-case letters, \s8UNIX\s10 will assume that your terminal cannot generate lower-case letters and will translate all subsequent upper-case letters to lower cas A small assortment of subroutines is available; they are described in section III. The binary form of most of them is kept in the system library \fI/\|lib/\|liba.a.\fR The subroutines available from C and from Fortran are also included; they reside in \fI/\|lib/\|libc.a\fR and \fI/\|lib/\|libf.a\fR respectively. .pg The special files section IV discusses the characteristics of each system ``file'' which actually refers to an I/O device. The names in this section refer to the DEC device names for the hardwa the title of the writeup to which it refers is followed by the appropriate section number in parentheses. 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. .pg .pg This manual was prepared using the \s8UNIX\s10 text editor \fIed\fR and the formatting program \fItroff\fR. e. .pg The evidence that you have successfully logged in is that the Shell program will type a ``%'' to you. (The Shell is described below under ``How to run a program.'') .pg For more information, consult \fIgetty\fR (VIII), which discusses the login sequence in more detail, and \fItty\fR (IV), which discusses typewriter I/O. .pg .ul Logging out.|| There are three ways to log out: .pg .in .5i You can simply hang up the phone. .pg You can log out by typing an end-of-file indication (EOT character, control `re, instead of the names of the special files themselves. .pg The file formats and conventions section V 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 command, for example the assembler's intermediate files. .pg User-maintained programs and subroutines (sections VI and VII) are not considered part of the \s8UNIX\s10 system, and the principal reason for listing them is to indicate their exis.nf .sp 2i .ps 12 .ft B .vs 14p .ce 100 DOCUMENTS FOR USE WITH THE UNIX TIME-SHARING SYSTEM .sp .ps 11 .ft I Sixth Edition .sp 2i .ps 10 .vs 12p .ft R The enclosed UNIX documentation is supplied in accordance with the Software Agreement you have with the Western Electric Company. .ce 0 .ce .bp .sp 2i .ft B CONTENTS .sp .ft R .in 1i .vs 20p \01. Setting Up UNIX \- Sixth Edition \02. The UNIX Time-Sharing System \03. C Reference Manual \04. Programming in C \- A Tutorial \05. UNIX Assembler Reference Manual \`d'') to the Shell. The Shell will terminate and the ``login: '' message will appear again. .pg You can also log in directly as another user by giving a \fIlogin\fR command (I). .pg .in 0 .ul How to communicate through your terminal.|| When you type to \s8UNIX\s10, a gnome deep in the system is gathering your characters and saving them in a secret place. The characters will not be given to a program until you type a return (or new-line), as described above in .ul Logging in. .pg \s8UNIX\s10 typewriter I/O 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 the input characters interspersed. However, whatever you type will be saved up and interpreted in 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. tence without necessarily giving a complete description. The authors of the individual programs should be consulted for more information. .pg Section VIII discusses commands which are not intended for use by the ordinary user, in some cases because they disclose information in which he is presumably not interested, and in others because they perform privileged functions. .pg .pg Each section consists of a number of independent entries of a page or so each. The name of the entry is in the upper corners of it.tr | .bp .ce HOW TO GET STARTED .sp 1.5 This section provides the basic information you need to get started on \s8UNIX\s10: how to log in and log out, how to communicate through your terminal, and how to run a program. See ``U\s8NIX\s10 for Beginners'' by Brian W. Kernighan for a more complete introduction to the system. .pg .ft I Logging in.|| .ft R You must call \s8UNIX\s10 from an appropriate terminal. \s8UNIX\s10 supports \s8ASCII\s10 terminals typified by the \s8TTY\s10 37, the GE Terminet 300, the Da.pg On a typewriter input line, the character ``@'' kills all the characters typed before it, so typing mistakes can be repaired on a single line. Also, the character ``#'' erases the last character typed. Successive uses of ``#'' erase characters back to, but not beyond, the beginning of the line. ``@'' and ``#'' can be transmitted to a program by preceding them with ``\\''. (So, to erase ``\\'', you need two ``#''s). .pg The \s8ASCII\s10 ``delete'' (a.k.a. ``rubout'') character is not passed to programs bs pages, its preparation date in the upper middle. Entries within each section are alphabetized. The page numbers of each entry start at 1. (The earlier hope for frequent, partial updates of the manual is clearly in vain, but in any event it is not feasible to maintain consecutive page numbering in a document like this.) .pg All entries are based on a common format, not all of whose subsections will always appear. .pg .in .5i The \fIname\fR section repeats the entry name and gives a very short description osi 300, and various graphical terminals. You must also have a valid user name, which may be obtained, together with the telephone number, from the system administrators. The same telephone number serves terminals operating at all the standard speeds. After a data connection is established, the login procedure depends on what kind of terminal you are using. .pg .in .5i .ul 300-baud terminals:|| Such terminals include the GE Terminet 300, most display terminals, Execuport, TI, GSI, and certain Anderson-Jacobsut instead generates an .ul interrupt 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, 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. .pg The \fIquit\fR signal is generated by typing the \s8ASCII\s10 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. .pg Besides adapting to the speed of the terminal, \s8UNIX\s10 tries to be intelligent about whether you have a terminal with the new-line function or whether it must be simulated with carriage-return and line-feed. In the latter case, all input carriage returns are turnede system, see ``The \s8UNIX\s10 Time-Sharing System,'' by the present authors. It may also be useful to glance through section II of this manual, which discusses system calls, even if you don't intend to deal with the system at that level. .pg .ul Writing a program.|| To enter the text of a source program into a \s8UNIX\s10 file, use \fIed\fR (I). The three principal languages in \s8UNIX\s10 are assembly language (see \fIas\fR (I)), Fortran (see \fIfc\fR (I)), and C (see \fIcc\fR (I)). After the program texputc.3~putchar.3}qsort.3|rand.3{reset.3zsetfil.3ysin.3xsqrt.3wttyn.3 to new-line characters (the standard line delimiter) and both a carriage return and a line feed are echoed to the terminal. If you get into the wrong mode, the \fIstty\fR command (I) will rescue you. .pg Tab characters are used freely in \s8UNIX\s10 source programs. If your terminal does not have the tab function, you can arrange to have them turned into spaces during output, and echoed as spaces during input. The system assumes that tabs are set every eight columns. Again, the \fIstty\fR command (I) will t has been entered through the editor and written on a file, you can give the file to the appropriate language processor as an argument. The output of the language processor will be left on a file in the current directory named ``a.out''. (If the output is precious, use \fImv\fR to move it to a less exposed name soon.)| If you wrote in assembly language, you will probably need to load the program with library subroutines; see \fIld \fR(I). The other two language processors call the loader automatically. .setuid.2signal.2sleep.2stat.2stime.2stty.2sync.2time.2times.2umount.2unlink.2wait.2write.2set or reset this mode. Also, there is a file which, if printed on \s8TTY\s10 37 or TermiNet 300 terminals, will set the tab stops correctly (\fItabs\fR (V)). .pg Section \fItty\fR (IV) discusses typewriter I/O more fully. .pg .ul How to run a program; the Shell.|| When you have successfully logged into \s8UNIX\s10, a program called the Shell is listening to your terminal. The Shell reads typed-in lines, splits them up into a command name and arguments, and executes the command. A command is simply an execupg 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. .pg Next, you will need \fIcdb\fR (I) or \fIdb\fR (I) to examine the remains of your program. The former is useful for C programs, the latter for assembly-language. No debugger is much help for Fortran. .pg Your programs can receive arguments from the command line just as system programs do. See \fIexec\fR (II). .pg .ul3kill.12ld.11ln.10login.1/ls.1.mail.1-man.1,mesg.1+mkdir.1*mv.1)neqn.1(newgrp.1'nice.1&nm.1%nohup.1$nroff.1#od.1"opr.1!passwd.1 pfe.1pr.1prof.1ps.1pwd.1rc.1rev.1rm.1rmdir.1roff.1sh.1shift.1size.1table program. The Shell looks first in your current directory (see next section) for a program with the given name, and if none is there, then in a system directory. There is nothing special about system-provided commands except that they are kept in a directory where the Shell can find them. .pg The command name is always the first word on an input line; it and its arguments are separated from one another by spaces. .pg When a program terminates, the Shell will ordinarily regain control and type a ``%'' Text processing.|| Almost all text is entered through the editor. The commands most often used to write text on a terminal are: .ul cat, pr, roff, nroff, and .ul troff, all in section I. .pg The \fIcat\fR command simply dumps \s8ASCII\s10 text on the terminal, with no processing at all. The \fIpr\fR command paginates the text, supplies headings, and has a facility for multi-column output. .ul Troff and .ul nroff are elaborate text formatting programs, and require careful forethought in entering both the tesleep.1sort.1spell.1split.1strip.1stty.1 tee.1 time.1 tp.1 tr.1 troff.1tty.1typo.1uniq.1wait.1wc.1who.1write.1yacc.1at you to indicate that it is ready for another command. .pg The Shell has many other capabilities, which are described in detail in section \fIsh\fR\|(I). .pg .ul The current directory.|| \s8UNIX\s10 has a file system arranged in a hierarchy of directories. When the system administrator gave you a user name, he also created a directory for you (ordinarily with the same name as your user name). When you log in, any file name you type is by default in this directory. Since you are the owner of this directoryxt and the formatting commands into the input file. .ul Troff drives a Graphic Systems phototypesetter; it was used to produce this manual. .ul Nroff produces output on a typewriter terminal. .ul Roff (I) is a somewhat less elaborate text formatting program, and requires somewhat less forethought. .pg .ul 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. .pg To communi.th TM IV 2/21/74 .sh NAME tm \*- TM-11/TU-10 magtape interface .sh DESCRIPTION The files .it "mt0, ..., mt7" refer to the DEC TU10/TM11 magtape. When opened for reading or writing, the tape is rewound. When closed, it is rewound; if it was open for writing, an end-of-file is written first. .s3 A standard tape consists of a series of 512 byte records terminated by an end-of-file. To the extent possible, the system makes it possible, if inefficient, to treat the tape like any other file. Seeks have their usu, 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 owners. As a matter of observed fact, few \s8UNIX\s10 users protect their files from destruction, let alone perusal, by other users. .pg To change the current directory (but not the set of permissions you were endowed with at login) use \fIchdir\fR (I). .pg .ul Path names.|| To refer to files not in the current directory, cate with another user currently logged in, .ul write (I) is used; .ul mail (I) will leave a message whose presence will be announced to another user when he next logs in. The write-ups in the manual also suggest how to respond to the two commands if you are a target. .pg When you log in, a message-of-the-day may greet you before the first ``%''. al meaning and it is possible to read or write a byte at a time. Writing in very small units is inadvisable, however, because it tends to create monstrous record gaps. .s3 The .it mt files discussed above are useful when it is desired to access the tape in a way compatible with ordinary files. When foreign tapes are to be dealt with, and especially when long records are to be read or written, the ``raw'' interface is appropriate. The associated files are named .it "rmt0, ..., rmt7." Each .it read or .it wriyou must use a path name. Full path names begin with ``/'', 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.: .ul /\|usr/\|lem/\|filex refers to the file .ul filex in the directory .ul lem; lem is itself a subdirectory of .ul usr; usr springs directly from the root directory. .pg If your current directory has subdirectories, the path names of files the\.e..ac.8bproc.8chgrp.8chown.8clri.8crash.8cron.8dcheck.8df.8dpd.8dump.8getty.8glob.8icheck.8init.8lpd.8mkfs.8mknod.8mount.8ncheck.8restor.8sa.8su.8sync.8umount.8update.8wall.8te call reads or writes the next record on the tape. In the write case the record has the same length as the buffer given. During a read, the record size is passed back as the number of bytes read, provided it is no greater than the buffer size; if the record is long, an error is indicated. In raw tape I/O, the buffer must begin on a word boundary and the count must be even. Seeks are ignored. An error is returned when a tape mark is read, but another read will fetch the first record of the new tape file. .rein begin with the name of the subdirectory (no prefixed ``/''). .pg Without important exception, a path name may be used anywhere a file name is required. .pg Important commands which modify the contents of files are \fIcp\fR (I), \fImv\fR (I), and \fIrm\fR (I), which respectively copy, move (i.e. rename) and remove files. To find out the status of files or directories, use \fIls\fR (I). See \fImkdir\fR (I) for making directories; \fIrmdir\fR (I) for destroying them. .pg For a fuller discussion of the filpdgen.6plog.6plot.6primes.6ptx.6quiz.6rathole.6searchcpi.6sky.6sno.6speak.6spline.6tbl.6tekstare.6tmg.6tss.6ttt.6units.6wump.6sh FILES /dev/mt?, /dev/rmt? .sh "SEE ALSO" tp (I) .sh BUGS If any non-data error is encountered, it refuses to do anything more until closed. In raw I/O, there should be a way to perform forward and backward record and file spacing and to write an EOF mark. .th TC IV 10/15/73 .sh NAME tc \*- TC-11/TU56 DECtape .sh DESCRIPTION The files .it "tap0 ... tap7" refer to the TC-11/TU56 DECtape drives 0 to 7. .s3 The 256-word blocks on a standard DECtape are numbered 0 to 577. .sh FILES /dev/tap? .sh "SEE ALSO" tp (I) .sh BUGS he buffer must begin on a word boundary, and counts should be a multiple of 512 bytes (a disk block). Likewise .it seek calls should specify a multiple of 512 bytes. .sh FILES /dev/rk?, /dev/rrk? .sh BUGS Care should be taken in using the interleaved files. First, the same drive should not be accessed simultaneously using the ordinary name and as part of an interleaved file, because the same physical blocks have in effect two different names; this fools the system's buffering strategy. Second, the combined .th MEM IV 5/27/74 .sh NAME mem, kmem, null \*- core memory .sh DESCRIPTION .it Mem is a special file that is an image of the core memory of the computer. It may be used, for example, to examine, and even to patch the system using the debugger. .s3 A memory address is an 18-bit quantity which is used directly as a UNIBUS address. References to non-existent locations cause errors to be returned. .s3 Examining and patching device registers is likely to lead to unexpected results when read-only or write-only.th RP IV 2/21/74 .sh NAME rp \*- RP-11/RP03 moving-head disk .sh DESCRIPTION The files .it "rp0 ... rp7" refer to sections of RP disk drive 0. The files .it "rp8 ... rp15" refer to drive 1 etc. This is done since the size of a full RP drive is 81200 blocks and internally the system is only capable of addressing 65536 blocks. Also since the disk is so large, this allows it to be broken up into more manageable pieces. .s3 The origin and size of the pseudo-disks on each drive are as follows: .s3 .br disk stafiles cannot be used for swapping or raw I/O. bits are present. .s3 The file .it kmem is the same as .it mem except that kernel virtual memory rather than physical memory is accessed. In particular, the I/O area of .it kmem is located beginning at 160000 (octal) rather than at 760000. The 1K region beginning at 140000 (octal) is the system's data for the current process. .s3 The file .it null returns end-of-file on .it read and ignores .it write. .sh FILES /dev/mem, /dev/kmem, /dev/null rt length .br 0 0 40600 .br 1 40600 40600 .br 2 0 9200 .br 3 72000 9200 .br 4 0 65535 .br 5 15600 65535 .br 6-7 unassigned .s3 It is unwise for all of these files to be present in one installation, since there is overlap in addresses and protection becomes a sticky matter. Here is a suggestion for two useful configurations: If the root of the file system is on some other device and the RP used as a mounted device, then .it rp0 and .it rp1, which divide the disk into two equal size portions, is a good.th RF IV 10/15/73 .sh NAME rf \*- RF11/RS11 fixed-head disk file .sh DESCRIPTION This file refers to the concatenation of all RS-11 disks. .s3 Each disk contains 1024 256-word blocks. The length of the combined RF file is 1024\*X(minor+1) blocks. That is minor device zero is taken to be 1024 blocks long; minor device one is 2048, etc. .s3 The .it rf0 file accesses the disk via the system's normal buffering mechanism and may be read and written without regard to physical disk records. There is also a ``raw'.th LP IV 5/27/74 .sh NAME lp \*- line printer .sh DESCRIPTION .it Lp provides the interface to any of the standard DEC line printers. When it is opened or closed, a suitable number of page ejects is generated. Bytes written are printed. .s3 An internal parameter within the driver determines whether or not the device is treated as having a 96- or 64-character set. In half-ASCII mode, lower case letters are turned into upper case and certain characters are escaped according to the following table: .s3 .if t idea. Other things being equal, it is advantageous to have two equal-sized portions since one can always be copied onto the other, which is occasionally useful. .s3 If the RP is the only disk and has to contain the root and the swap area, the root can be put on .it rp2 and a mountable file system on .it rp5. Then the swap space can be put in the unused blocks 9200 to 15600 of .it rp0 (or, equivalently, .it rp4). This arrangement puts the root file system, the swap area, and the i-list of the mounted file s' interface which provides for direct transmission between the disk and the user's read or write buffer. A single read or write call results in exactly one I/O operation and therefore raw I/O is considerably more efficient when many words are transmitted. The name of the raw RF file is .it rrf0. The same minor device considerations hold for the raw interface as for the normal interface. .s3 In raw I/O the buffer must begin on a word boundary, and counts should be a multiple of 512 bytes (a disk block). Like.ig .lp +10 5 { (- .lp +10 5 } )- .lp +10 5 \*g \*a- .lp +10 5 | !- .lp +10 5 ~ ^- .. .if n .ig .lp +10 5 { \o"(\*-" .lp +10 5 } \o")\*-" .lp +10 5 \*g \o"\*a\*-" .lp +10 5 | \o"!\*-" .lp +10 5 ~ \o"^\*-" .. .i0 .s3 The driver correctly interprets carriage returns, backspaces, tabs, and form feeds. A sequence of newlines which extends over the end of a page is turned into a form feed. All lines are indented 8 characters. Lines longer than 80 characters are truncated. These numbers are parameters in theystem relatively near each other and thus tends to minimize head movement. .s3 The .it rp files access the disk via the system's normal buffering mechanism and may be read and written without regard to physical disk records. There is also a ``raw'' interface which provides for direct transmission between the disk and the user's read or write buffer. A single read or write call results in exactly one I/O operation and therefore raw I/O is considerably more efficient when many words are transmitted. The nameswise .it seek calls should specify a multiple of 512 bytes. .sh FILES /dev/rf0, /dev/rrf0 .sh BUGS The 512-byte restrictions on the raw device are not physically necessary, but are still imposed. driver; another parameter allows indenting all printout if it is unpleasantly near the left margin. .sh FILES /dev/lp .sh "SEE ALSO" lpr (I) .sh BUGS Half-ASCII mode, the indent and the maximum line length should be settable by a call analogous to stty (II). of the raw RP files begin with .it rrp and end with a number which selects the same disk section as the corresponding .it rp file. .s3 In raw I/O the buffer must begin on a word boundary, and counts should be a multiple of 512 bytes (a disk block). Likewise .it seek calls should specify a multiple of 512 bytes. .sh FILES /dev/rp?, /dev/rrp? .sh BUGS .th PC IV 10/15/73 .sh NAME pc \*- PC-11 paper tape reader/punch .sh DESCRIPTION .it Ppt refers to the PC-11 paper tape reader or punch, depending on whether it is read or written. .s3 When .it ppt is opened for writing, a 100-character leader is punched. Thereafter each byte written is punched on the tape. No editing of the characters is performed. When the file is closed, a 100-character trailer is punched. .s3 When .it ppt is opened for reading, the process waits until tape is placed in the reader and.th KL IV 5/27/74 .sh NAME kl \*- KL-11 or DL-11 asynchronous interface .sh DESCRIPTION The discussion of typewriter I/O given in tty (IV) applies to these devices. .s3 Since they run at a constant speed, attempts to change the speed via stty (II) are ignored. .s3 The on-line console typewriter is interfaced using a KL-11 or DL-11. By appropriate switch settings during a reboot, UNIX will come up as a single-user system with I/O on the console typewriter. .sh FILES /dev/tty8 console .sh "SEE ALSO" tty (IV),.th RK IV 10/15/73 .sh NAME rk \*- RK-11/RK03 (or RK05) disk .sh DESCRIPTION .it Rk? refers to an entire RK03 disk as a single sequentially-addressed file. Its 256-word blocks are numbered 0 to 4871. .s3 Drive numbers (minor devices) of eight and larger are treated specially. Drive 8+\fIx\fR is the \fIx\fR+1 way interleaving of devices rk0 to rk\fIx\fR. Thus blocks on rk10 are distributed alternately among rk0, rk1, and rk2. .s3 The .it rk files discussed above access the disk via the system's normal buff the reader is on-line. Then requests to read cause the characters read to be passed back to the program, again without any editing. This means that several null leader characters will usually appear at the beginning of the file. Likewise several nulls are likely to appear at the end. End-of-file is generated when the tape runs out. .s3 Seek calls for this file are meaningless. .sh FILES /dev/ppt .sh BUGS If both the reader and the punch are open simultaneously, the trailer is sometimes not punched. Sometim init (VIII) .sh BUGS Modem control for the DL-11E is not implemented. ering mechanism and may be read and written without regard to physical disk records. There is also a ``raw'' interface which provides for direct transmission between the disk and the user's read or write buffer. A single read or write call results in exactly one I/O operation and therefore raw I/O is considerably more efficient when many words are transmitted. The names of the raw RK files begin with .it rrk and end with a number which selects the same disk as the corresponding .it rk file. .s3 In raw I/O tes the reader goes into a dead state in which it cannot be opened. .th HT IV 2/9/75 .sh NAME ht \*- RH-11/TU-16 magtape interface .sh DESCRIPTION The files .it "mt0, ..., mt7" refer to the DEC RH/TM/TU16 magtape. When opened for reading or writing, the tape is rewound. When closed, it is rewound; if it was open for writing, a double end-of-file is written first. .s3 A standard tape consists of a series of 512 byte records terminated by a double end-of-file. To the extent possible, the system makes it possible, if inefficient, to treat the tape like any other file. Seeks have their usual meaning and it is possible to read or write a byte at a time. Writing in very small units is inadvisable, however, because it tends to create monstrous record gaps. .s3 The .it mt files discussed above are useful when it is desired to access the tape in a way compatible with ordinary files. When foreign tapes are to be dealt with, and especially when long records are to be read or written, the ``raw'' interface is appropriate. The associated files are named .it "rmt0, ..., rmt7." Each .it rearect transmission between the disk and the user's read or write buffer. A single read or write call results in exactly one I/O operation and therefore raw I/O is considerably more efficient when many words are transmitted. The names of the raw RP files begin with .it rhp and end with a number which selects the same disk section as the corresponding .it hp file. .s3 In raw I/O the buffer must begin on a word boundary, and counts should be a multiple of 512 bytes (a disk block). Likewise .it seek calls shouldtty (IV), stty (II), dh (IV) .sh BUGS d or .it write call reads or writes the next record on the tape. In the write case the record has the same length as the buffer given. During a read, the record size is passed back as the number of bytes read, provided it is no greater than the buffer size; if the record is long, an error is indicated. In raw tape I/O, the buffer must begin on a word boundary and the count must be even. Seeks are ignored. An error is returned when a tape mark is read, but another read will fetch the first record of the new specify a multiple of 512 bytes. .sh FILES /dev/hp?, /dev/rhp? .sh BUGS .th CAT IV 10/27/73 .sh NAME cat \*- phototypesetter interface .sh DESCRIPTION .it Cat provides the interface to a Graphic Systems C/A/T phototypesetter. Bytes written on the file specify font, size, and other control information as well as the characters to be flashed. The coding will not be described here. .s3 Only one process may have this file open at a time. It is write-only. .sh FILES /dev/cat .sh "SEE ALSO" troff (I), Graphic Systems specification (available on request) .sh BUGS tape file. .sh FILES /dev/mt?, /dev/rmt? .sh "SEE ALSO" tp (I) .sh BUGS Raw I/O doesnt work yet. The magtape system is supposed to be able to take 64 drives. Such addressing has never been tried. These bugs will be fixed when we get more experience with this device. .s3 If any non-data error is encountered, it refuses to do anything more until closed. In raw I/O, there should be a way to perform forward and backward record and file spacing and to write an EOF mark. .th DP IV 8/24/73 .sh NAME dp \*- DP-11 201 data-phone interface .sh DESCRIPTION The .it dp0 file is a 201 data-phone interface. .it Read and .it write calls to dp0 are limited to a maximum of 512 bytes. Each write call is sent as a single record. Seven bits from each byte are written along with an eighth odd parity bit. The sync must be user supplied. Each read call returns characters received from a single record. Seven bits are returned unaltered; the eighth bit is set if the byte was not received in odd.th TTYN III 1/15/73 .sh NAME ttyn \*- return name of current typewriter .sh SYNOPSIS .ft B jsr pc,ttyn .s3 ttyn(file) .s3 .ft R .sh DESCRIPTION .it Ttyn hunts up the last character of the name of the typewriter which is the standard input (from \fIas\fR) or is specified by the argument .it file descriptor (from C). If \fIn\fR is returned, the typewriter name is then ``/dev/tty\fIn\fR''. .s3 .bd x is returned if the indicated file does not correspond to a typewriter. .sh BUGS .th HS IV 2/9/75 .sh NAME hs \*- RH11/RS03-RS04 fixed-head disk file .sh DESCRIPTION The files .it "hs0 ... hs7" refer to RJS03 disk drives 0 through 7. The files .it "hs8 ... hs15" refer to RJS04 disk drives 0 through 7. The RJS03 drives are each 1024 blocks long and the RJS04 drives are 2048 blocks long. .s3 The .it hs files access the disk via the system's normal buffering mechanism and may be read and written without regard to physical disk records. There is also a ``raw'' inteface which provides for di parity. A 10 second time out is set and a zero-byte record is returned if nothing is received in that time. .sh FILES /dev/dp0 .sh "SEE ALSO" dn (IV), gerts (III) .sh BUGS .th SQRT III 3/15/72 .sh NAME sqrt \*- square root function .sh SYNOPSIS .br .ft B jsr pc,sqrt .s3 double sqrt(x) .br double x; .ft R .sh DESCRIPTION The square root of fr0 (resp. \fBx\fR) is returned (in fr0). .sh DIAGNOSTICS The c-bit is set on negative arguments and 0 is returned. There is no error return for C programs. .sh BUGS No error return from C. rect transmission between the disk and the user's read or write buffer. A single read or write call results in exactly one I/O operation and therefore raw I/O is considerably more efficient when many words are transmitted. The names of the raw HS files begin with .it rhs. The same minor device considerations hold for the raw interface as for the normal interface. .s3 In raw I/O the buffer must begin on a word boundary, and counts should be a multiple of 512 bytes (a disk block). Likewise .it seek calls shou.th DN IV 3/20/74 .sh NAME dn \*- DN-11 ACU interface .sh DESCRIPTION The .it dn? files are write-only. The permissible codes are: .s3 .lp +8 4 0-9 dial 0-9 .lp +8 4 : dial * .lp +8 4 ; dial # .lp +8 4 \*- 4 second delay for second dial tone .lp +8 4 = end-of-number .s3 .i0 The entire telephone number must be presented in a single .it write system call. .s3 It is recommended that an end-of-number code be given even though not all ACU's actually require it. .dt .sh FILES /dev/dn0 connected to 801 with dp0 .b.th SIN III 3/15/72 .sh NAME sin, cos \*- trigonometric functions .sh SYNOPSIS .nf .ft B jsr pc,sin (cos) .s3 double sin(x) double x; .s3 double cos(x) double x; .fi .ft R .sh DESCRIPTION The sine (cosine) of fr0 (resp. \fBx\fR), measured in radians, is returned (in fr0). .s3 The magnitude of the argument should be checked by the caller to make sure the result is meaningful. .sh BUGS ld specify a multiple of 512 bytes. .sh FILES /dev/hs?, /dev/rhs? .sh BUGS r /dev/dn1 not currently connected .br /dev/dn2 not currently connected .sh "SEE ALSO" dp (IV) .sh BUGS .th SETFIL III 10/29/73 .sh NAME setfil \*- specify Fortran file name .sh SYNOPSIS .ft B call setfil ( \fRunit\fB, \fRhollerith-string\fB ) .ft R .sh DESCRIPTION .it Setfil provides a primitive way to associate an integer I/O .it unit number with a file named by the .it hollerith-string. The end of the file name is indicated by a blank. Subsequent I/O on this unit number will refer to the file whose name is specified by the string. .s3 .it Setfil should be called only before any I/O has been done on the .it.th HP IV 2/9/75 .sh NAME hp \*- RH-11/RP04 moving-head disk .sh DESCRIPTION The files .it "hp0 ... hp7" refer to sections of RP disk drive 0. The files .it "hp8 ... hp15" refer to drive 1 etc. This is done since the size of a full RP drive is 170,544 blocks and internally the system is only capable of addressing 65536 blocks. Also since the disk is so large, this allows it to be broken up into more manageable pieces. .s3 The origin and size of the pseudo-disks on each drive are as follows: .s3 .br disk st.th DH IV 5/27/74 .sh NAME dh \*- DH-11 communications multiplexer .sh DESCRIPTION Each line attached to the DH-11 communications multiplexer behaves as described in tty (IV). Input and output for each line may independently be set to run at any of 16 speeds; see stty (II) for the encoding. .sh FILES /dev/tty[f-u] .sh "SEE ALSO" tty (IV), stty (II) .sh BUGS unit, or just after doing a .bd rewind or .bd endfile. It is ineffective for unit numbers 5 and 6. .sh "SEE ALSO" fc (I) .sh BUGS The exclusion of units 5 and 6 is unwarranted. art length .br 0 0 9614 .br 1 18392 65535 .br 2 48018 65535 .br 3 149644 20900 .br 4 0 40600 .br 5 41800 40600 .br 6 83600 40600 .br 7 125400 40600 .s3 It is unwise for all of these files to be present in one installation, since there is overlap in addresses and protection becomes a sticky matter. .s3 The .it hp files access the disk via the system's normal buffering mechanism and may be read and written without regard to physical disk records. There is also a ``raw'' interface which provides for di.th DC IV 5/27/74 .sh NAME dc \*- DC-11 communications interface .sh DESCRIPTION The discussion of typewriter I/O given in tty (IV) applies to these devices. .s3 The DC-11 typewriter interface operates at any of four speeds, independently settable for input and output. The speed is selected by the same encoding used by the DH (IV) device (enumerated in stty (II)); impossible speed changes are ignored. .sh FILES /dev/tty[01234567abcd] 113B Dataphones (not currently connected\*- see dh (IV)) .sh "SEE ALSO" .th RESET III 5/10/73 .sh NAME reset, setexit \*- execute non-local goto .sh SYNOPSIS .ft B .bd "setexit( )" .s3 .bd "reset( )" .ft R .sh DESCRIPTION These routines are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. .s3 .it Setexit saves its stack environment in a static place for later use by .it reset. .s3 .it Reset restores the environment saved by the last call of .it setexit. It then returns in such a way that execution continues as if the call of .it setexit had just returned. All accessible data have values as of the time .it reset was called. .s3 The routine that called .it setexit must still be active when .it reset is called. .sh "SEE ALSO" signal (II) .sh BUGS n file (mode 666) and sets up the buffer .it iobuf (size 518 bytes); .it putc and .it putw write a byte or word respectively onto the file; .it flush forces the contents of the buffer to be written, but does not close the file. The structure of the buffer is: .nf .ft B .nf struct buf { int fildes; /* File descriptor */ int nunused; /* Remaining slots */ char *xfree; /* Ptr to next free slot */ char buff[512]; /* The buffer */ }; .ft R .s3 .fi Before terminating, a program should call .it flush to force he number of characters indicated by the precision specification is reached; however if the precision is 0 or missing all characters up to a null are printed. .s3 .lp +6 3 l The argument is taken to be an unsigned integer which is converted to decimal and printed (the result will be in the range 0 to 65535). .s3 .i0 If no recognizable character appears after the \fB%\fR, that character is printed; thus \fb%\fR may be printed by use of the string \fB%%\fR. In no case does a non-existent or small field width .th RAND III 1/15/73 .sh NAME rand, srand \*- random number generator .sh SYNOPSIS (seed in r0) .br .ft B jsr pc,srand /to initialize .s3 jsr pc,rand /to get a random number .s3 .nf srand(seed) int seed; .s3 rand( ) .fi .ft R .s3 .sh DESCRIPTION .it Rand uses a multiplicative congruential random number generator to return successive pseudo-random numbers (in r0) in the range from 0 to 2\u\s715\s10\d\*-1. .s3 The generator is reinitialized by calling .it srand with 1 as argument (in r0). It can be set to a rout the last of the output .it (fflush from C). .s3 The user must supply .it iobuf, which should begin on a word boundary. .s3 To write a new file using the same buffer, it suffices to call .it [f]flush, close the file, and call .it fcreat again. .sh "SEE ALSO" creat (II), write (II), getc (III) .sh DIAGNOSTICS .it Fcreat sets the error bit (c-bit) if the file creation failed (from C, returns \*-1). .it Putc and .it putw return their character (word) argument. In all calls .it errno is set appropriately tcause truncation of a field; padding takes place only if the specified field width exceeds the actual width. Characters generated by .it printf are printed by calling .it putchar. .sh "SEE ALSO" putchar (III) .sh BUGS Very wide fields (>128 characters) fail. andom starting point by calling .it srand with whatever you like as argument, for example the low-order word of the time. .sh BUGS The low-order bits are not very random. o 0 or to a system error number. See introduction (II). .sh BUGS .tr | .th POW III 4/30/73 .sh NAME pow \*- floating exponentiation .sh SYNOPSIS .ft B movf x,fr0 .br movf y,fr1 .br jsr pc,pow .s3 .nf double pow(x,y) double x, y; .fi .s3 .ft R .sh DESCRIPTION .it Pow returns the value of \fIx\u\s8y\s10\d\fR (in fr0). .it "Pow(0.0,|y)" is 0 for any .it y. .it "Pow(\*-x,|y)" returns a result only if .it y is an integer. .sh "SEE ALSO" exp (III), log (III) .sh DIAGNOSTICS The carry bit is set on return in case of overflow, .it pow(0.0,|0.0), or .it pow(\*-x,|y) for non-integ.th QSORT III 2/8/75 .sh NAME qsort \*- quicker sort .sh SYNOPSIS .nf .ft B qsort(base, nel, width, compar) char *base; int (*compar)( ); .fi .ft R .sh DESCRIPTION .it Qsort is an implementation of the quicker-sort algorithm. The first argument is a pointer to the base of the data; the second is the number of elements; the third is the width of an element in bytes; the last is the name of the comparison routine. It is called with two arguments which are pointers to the elements being compared. The routine m.th PRINTF III 9/17/73 .sh NAME printf \*- formatted print .sh SYNOPSIS .ft B printf(format, arg\s6\d1\u\s10, ...); .br char *format; .ft R .sh DESCRIPTION .it Printf converts, formats, and prints its arguments after the first under control of the first argument. The first argument is a character string which contains two types of objects: plain characters, which are simply copied to the output stream, and conversion specifications, each of which causes conversion and printing of the next successive argumenral .it y. From C there is no diagnostic. .sh BUGS ust return an integer less than, equal to, or greater than 0 according as the first argument is to be considered less than, equal to, or greater than the second. .sh "SEE ALSO" sort (I) .sh BUGS t to .it printf. .s3 Each conversion specification is introduced by the character \fB%\fR. Following the \fB%\fR, there may be .s3 .lp +6 2 \*- an optional minus sign ``\*-'' which specifies .it "left adjustment" of the converted argument in the indicated field; .s3 .lp +6 2 \*- an optional digit string specifying a .it "field width;" if the converted argument has fewer characters than the field width it will be blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up .th PERROR III 11/5/73 .sh NAME perror, sys\*_errlist, sys\*_nerr, errno \*- system error messages .sh SYNOPSIS .ft B perror(s) .br char *s; .s3 int sys\*_nerr; .br char *sys\*_errlist[]; .s3 int errno; .ft R .br .sh DESCRIPTION .it Perror produces a short error message describing the last error encountered during a call to the system from a C program. First the argument string .it s is printed, then a colon, then the message and a new-line. Most usefully, the argument string is the name of the program whic.th PUTCHAR III 5/10/73 .sh NAME putchar, flush \*- write character .sh SYNOPSIS .ft B putchar(ch) .s3 flush( ) .ft R .sh DESCRIPTION .it Putchar writes out its argument and returns it unchanged. Only the low-order byte is written, and only if it is non-null. Unless other arrangements have been made, .it putchar writes in unbuffered fashion on the standard output file. .s3 Associated with this routine is an external variable .it fout which has the structure of a buffer discussed under putc (III). If the filthe field width; .s3 .lp +6 2 \*- an optional period ``\fB.\fR'' which serves to separate the field width from the next digit string; .s3 .lp +6 2 \*- an optional digit string .it "(precision)" which specifies the number of digits to appear after the decimal point, for e- and f-conversion, or the maximum number of characters to be printed from a string; .s3 .lp +6 2 \*- a character which indicates the type of conversion to be applied. .s3 .i0 The conversion characters and their meanings are .s3 .lp +6 3 d .h incurred the error. The error number is taken from the external variable .it errno, which is set when errors occur but not cleared when non-erroneous calls are made. .s3 To simplify variant formatting of messages, the vector of message strings .it sys\*_errlist is provided; .it errno can be used as an index in this table to get the message string without the newline. .it Sys\*_nerr is the largest message number provided for in the table; it should be checked because new error codes may be added to the syse descriptor part of this structure (first word) is greater than 2, output via .it putchar is buffered. To achieve buffered output one may say, for example, .s3 .nf fout = dup(1); or fout = creat(...); .s3 .fi In such a case .it flush must be called before the program terminates in order to flush out the buffered output. .it Flush may be called at any time. .sh "SEE ALSO" putc (III) .sh BUGS The .it fout notion is kludgy. lp +6 3 o .lp +6 3 x The integer argument is converted to decimal, octal, or hexadecimal notation respectively. .s3 .lp +6 3 f The argument is converted to decimal notation in the style ``[\fB\*-\fR]ddd.ddd'' where the number of d's after the decimal point is equal to the precision specification for the argument. If the precision is missing, 6 digits are given; if the precision is explicitly 0, no digits and no decimal point are printed. The argument should be .it float or .it double. .s3 .lp +6 3 e The argtem before they are added to the table. .sh "SEE ALSO" Introduction to System Calls .sh BUGS .th PUTC III 6/12/72 .sh NAME putc, putw, fcreat, fflush \*- buffered output .sh SYNOPSIS .ft B .nf mov $filename,r0 jsr r5,fcreat; iobuf .s3 fcreat(file, iobuf) char *file; struct buf *iobuf; .s3 .ft R (get byte in r0) .ft B jsr r5,putc; iobuf .s3 putc(c, iobuf) int c; struct buf *iobuf; .s3 .ft R (get word in r0) .ft B jsr r5,putw; iobuf .s3 putw(w, iobuf); .br int w; .br struct buf *iobuf; .s3 jsr r5,flush; iobuf .s3 fflush(iobuf) struct buf *iobuf; .fi .ft R .sh DESCRIPTION .it Fcreat creates the giveument is converted in the style ``[\fB\*-\fR]d\fB.\fRddd\fBe\fR\(+-dd'' where there is one digit before the decimal point and the number after is equal to the precision specification for the argument; when the precision is missing, 6 digits are produced. The argument should be a .it float or .it double quantity. .s3 .lp +6 3 c The argument character is printed. .s3 .lp +6 3 s The argument is taken to be a string (character pointer) and characters from the string are printed until a null character or until t.th NLIST III 6/12/72 .sh NAME nlist \*- get entries from name list .sh SYNOPSIS .ft B .nf .i0 nlist(filename, nl) char *filename; .dt struct { char name[8]; int type; int value; } nl[ ]; .fi .ft R .sh DESCRIPTION .it Nlist examines the name list in the given executable output file and selectively extracts a list of values. The name list consists of a list of 8-character names (null padded) each followed by two words. The list is terminated with a null name. Each name is looked up in the name list of the file. If the name is found, the type and value of the name are placed in the two words following the name. If the name is not found, the type entry is set to \*-1. .s3 This subroutine is useful for examining the system name list kept in the file \fB/unix\fR. In this way programs can obtain system addresses that are up to date. .sh "SEE ALSO" a.out (V) .sh DIAGNOSTICS All type entries are set to \*-1 if the file cannot be found or if it is not a valid namelist. .sh BUGS .th LDIV III 5/7/73 .sh NAME ldiv, lrem \*- long division .sh SYNOPSIS .ft B ldiv(hidividend, lodividend, divisor) .s3 lrem(hidividend, lodividend, divisor) .ft R .sh DESCRIPTION The concatenation of the signed 16-bit .it hidividend and the unsigned 16-bit .it lodividend is divided by \fIdivisor\fR. The 16-bit signed quotient is returned by .it ldiv and the 16-bit signed remainder is returned by .it lrem. Divide check and erroneous results will occur unless the magnitude of the divisor is greater than that the simplest applications; .it getc is better when there are multiple input files. .sh "SEE ALSO" getc (III) .sh DIAGNOSTICS Null character returned on EOF or error. .sh BUGS \*-1 should be returned on EOF; null is a legitimate character. .th NARGS III 5/10/73 .sh NAME nargs \*- argument count .sh SYNOPSIS .bd "nargs( )" .sh DESCRIPTION .it Nargs returns the number of actual parameters supplied by the caller of the routine which calls \fInargs\fR. .s3 The argument count is accurate only when none of the actual parameters is .it float or \fIdouble\fR. Such parameters count as four arguments instead of one. .sh BUGS As indicated. Also, this routine does not work (and cannot be made to work) in programs with separated I and D space. Altogetherof the high-order dividend. .s3 An integer division of an unsigned dividend by a signed divisor may be accomplished by .s3 quo = ldiv(0, dividend, divisor); .s3 and similarly for the remainder operation. .s3 Often both the quotient and the remainder are wanted. Therefore .it ldiv leaves a remainder in the external cell .it ldivr. .sh BUGS No divide check check. .th GETC III 4/30/72 .sh NAME getc, getw, fopen \*- buffered input .sh SYNOPSIS .ft B mov $filename,r0 .br jsr r5,fopen; iobuf .s3 fopen(filename, iobuf) .br char *filename; .br struct buf *iobuf; .s3 jsr r5,getc; iobuf .br .ft R (character in r0) .s3 .ft B getc(iobuf) .br struct buf *iobuf; .s3 jsr r5,getw; iobuf .br .ft R (word in r0) .s3 .ft B getw(iobuf) .br struct buf *iobuf; .ft R .sh DESCRIPTION These routines provide a buffered input facility. .it Iobuf is the address of a 518(10) byte buffer area it is best to avoid using this routine and depend, for example, on passing an explicit argument count. .th IERROR III 10/29/73 .sh NAME ierror \*- catch Fortran errors .sh SYNOPSIS .ft B if ( ierror ( \fIerrno\fB ) .ne. 0 ) goto \fIlabel\fR .sh DESCRIPTION .it Ierror provides a way of detecting errors during the running of a Fortran program. Its argument is a run-time error number such as enumerated in .it fc (I). .s3 When .it ierror is called, it returns a 0 value; thus the .bd goto statement in the synopsis is not executed. However, the routine stores inside itself the call point and invocation level. If a whose contents are maintained by these routines. Its structure is .s3 .nf .ft B struct buf { int fildes; /* File descriptor */ int nleft; /* Chars left in buffer */ char *nextp; /* Ptr to next character */ char buff[512]; /* The buffer */ }; .ft R .s3 .fi .it Fopen may be called initially to open the file. On return, the error bit (c-bit) is set if the open failed. If \fIfopen\fR is never called, \fIget\fR will read from the standard input file. From C, the value is negative if the open failed. .th MONITOR III 2/11/74 .sh NAME monitor \*- prepare execution profile .sh SYNOPSIS .ft B monitor(lowpc, highpc, buffer, bufsize) .br int lowpc( ), highpc( ), buffer[ ], bufsize; .ft R .sh DESCRIPTION .it Monitor is an interface to the system's profile entry (II). .it Lowpc and .it highpc are the names of two functions; .it buffer is the address of a (user supplied) array of .it bufsize integers. .it Monitor arranges for the system to sample the user's program counter periodically and record the execution hnd when the indicated error occurs, a .bd return is simulated from .it ierror with a non-zero value; thus the .bd goto (or other statement) is executed. It is a ghastly error to call .it ierror from a subroutine which has already returned when the error occurs. .s3 This routine is essentially tailored to catching end-of-file situations. Typically it is called just before the start of the loop which reads the input file, and the .bd goto jumps to a graceful termination of the program. .s3 There is a limit of.s3 .it Getc returns the next byte from the file in r0. The error bit is set on end of file or a read error. From C, the character is returned as an integer, without sign extension; it is \*-1 on end-of-file or error. .s3 \fIGetw\fR returns the next word in r0. .it Getc and \fIgetw\fR may be used alternately; there are no odd/even problems. \fIGetw\fR is may be called from C; \*-1 is returned on end-of-file or error, but of course is also a legitimate value. .s3 .it Iobuf must be provided by the user; it muistogram in the buffer. The lowest address sampled is that of .it lowpc and the highest is just below .it highpc. For the results to be significant, especially where there are small, heavily used routines, it is suggested that the buffer be no more than a few times smaller than the range of locations sampled. .s3 To profile the entire program, it is sufficient to use .s3 extern etext; .br ... .br monitor(2, &etext, buf, bufsize); .s3 .it Etext is a loader-defined symbol which lies just above all the prog 5 on the number of different error numbers which can be caught. .sh "SEE ALSO" fc (I) .sh BUGS There is no way to ignore errors. st be on a word boundary. .s3 To reuse the same buffer for another file, it is sufficient to close the original file and call \fIfopen\fR again. .sh "SEE ALSO" open (II), read (II), getchar (III), putc (III) .sh DIAGNOSTICS c-bit set on EOF or error; from C, negative return indicates error or EOF. Moreover, .it errno is set by this routine just as it is for a system call (see introduction (II)). .sh BUGS ram text. .s3 To stop execution monitoring and write the results on the file .it mon.out, use .s3 monitor(0); .s3 Then, when the program exits, prof (I) can be used to examine the results. .s3 It is seldom necessary to call this routine directly; the .bd \*-p option of .it cc is simpler if one is satisfied with its default profile range and resolution. .sh FILES mon.out .sh "SEE ALSO" prof (I), profil (II), cc (I) .th HMUL III 4/7/73 .sh NAME hmul \*- high-order product .sh SYNOPSIS .ft B hmul(x, y) .ft R .sh DESCRIPTION .it Hmul returns the high-order 16 bits of the product of .bd x and .bd y. (The binary multiplication operator generates the low-order 16 bits of a product.) .sh BUGS .th GETARG III 11/24/73 .sh NAME getarg, iargc \*- get command arguments from Fortran .sh SYNOPSIS .ft B call getarg ( i, iarray \fR[ \fB, isize \fR]\fB ) .s3 .li ... = iargc(dummy) .ft R .sh DESCRIPTION The .it getarg entry fills in .it iarray (which is considered to be .it integer) with the Hollerith string representing the .it i th argument to the command in which it it is called. If no .it isize argument is specified, at least one blank is placed after the argument, and the last word affected is blank p.th LOG III 4/30/72 .sh NAME log \*- natural logarithm .sh SYNOPSIS .ft B jsr pc,log .s3 double log(x) .br double x; .ft R .sh DESCRIPTION The natural logarithm of fr0 is returned in fr0. From C, the natural logarithm of \fBx\fR is returned. .sh DIAGNOSTICS The error bit (c-bit) is set if the input argument is less than or equal to zero and the result is a negative number very large in magnitude. From C, there is no error indication. .sh BUGS .th GETPW III 4/7/73 .sh NAME getpw \*- get name from UID .sh SYNOPSIS .ft B getpw(uid, buf) .br char *buf; .ft R .sh DESCRIPTION .it Getpw searches the password file for the (numerical) \fIuid\fR, and fills in \fIbuf\fR with the corresponding line; it returns non-zero if \fIuid\fR could not be found. The line is null-terminated. .sh FILES /etc/passwd .sh "SEE ALSO" passwd (V) .sh DIAGNOSTICS non-zero return on error. .sh BUGS added. The user should make sure that the array is big enough. .s3 If the .it isize argument is given, the argument will be followed by blanks to fill up .it isize words, but even if the argument is long no more than that many words will be filled in. .s3 The blank-padded array is suitable for use as an argument to setfil (III). .s3 The .it iargc entry returns the number of arguments to the command, counting the first (file-name) argument. .sh "SEE ALSO" exec (II), setfil (III) .sh BUGS .th LOCV III 3/9/74 .sh NAME locv \*- long output conversion .sh SYNOPSIS .nf .ft B char *locv(hi, lo) int hi, lo; .fi .ft R .sh DESCRIPTION .it Locv converts a signed double-precision integer, whose parts are passed as arguments, to the equivalent ASCII character string and returns a pointer to that string. .sh BUGS Since .it locv returns a pointer to a static buffer containing the converted result, it cannot be used twice in the same expression; the second result overwrites the first. .th GETCHAR III 4/7/73 .sh NAME getchar \*- read character .sh SYNOPSIS .ft B getchar( ) .br .ft R .sh DESCRIPTION .it Getchar provides the simplest means of reading characters from the standard input for C programs. It returns successive characters until end-of-file, when it returns ``\\0''. .s3 Associated with this routine is an external variable called \fIfin\fR, which is a structure containing a buffer such as described under \fIgetc\fR (III). .s3 Generally speaking, .it getchar should be used only for .th GAMMA III 5/15/74 .sh NAME gamma \*- log gamma function .sh SYNOPSIS .br .ft B jsr pc,gamma .s3 double gamma(x) .br double x; .ft R .sh DESCRIPTION If \fIx\fR is passed (in fr0) .it gamma returns ln |\*|\*G(\*|\fIx\fR\*|)\*|| (in fr0). The sign of \*G(\*|\fIx\fR\*|) is returned in the external integer .it signgam. The following C program might be used to calculate \*G: .s3 y = gamma(x); .br if (y > 88.) .br error( ); .br y = exp(y); .br if(signgam) .br y = \*-y; .sh DIAGNOSTICS The c-bit is set on negative integral arguments and the maximum value is returned. There is no error return for C programs. .sh BUGS No error return from C. -p) option of .it cc. Of course it was for the benefit of such systems that the symbols were invented, and user programs, unless they are in firm control of their environment, are wise not to refer to the absolute symbols directly. .s3 One technique sometimes useful is to call .it sbrk(0), which returns the value of the current program break, instead of referring to .it &end, which yields the program break at the instant execution started. .s3 These symbols are accessible from assembly language if it is red. .s3 A routine named .it ctime is also available from Fortran. Actually it more resembles the .it time (II) system entry in that it returns the number of seconds since the epoch 0000 GMT Jan. 1, 1970 (as a floating-point number). .sh "SEE ALSO" time(II) .sh BUGS .th FPTRAP III 11/18/73 .sh NAME fptrap \*- floating point interpreter .sh SYNOPSIS .ft B sys signal; 4; fptrap .ft R .sh DESCRIPTION .it Fptrap is a simulator of the 11/45 FP11-B floating point unit. It works by intercepting illegal instruction traps and decoding and executing the floating point operation codes. .sh FILES In systems with real floating point, there is a fake routine in /lib/liba.a with this name; when simulation is desired, the real version should be put in liba.a .sh DIAGNOSTICS A break pomembered that they should be prefixed by `\*_' .sh "SEE ALSO" break (II), alloc (III) .sh BUGS .th CRYPT III 4/30/73 .sh NAME crypt \*- password encoding .sh SYNOPSIS .ft B mov $key,r0 .br jsr pc,crypt .s3 char *crypt(key) .br char *key; .ft R .sh DESCRIPTION On entry, r0 points to a string of characters terminated by an ASCII NUL. The routine performs an operation on the key which is difficult to invert (i.e. encrypts it) and leaves the resulting eight bytes of ASCII alphanumerics in a global cell called ``word''. .s3 From C, the .it key argument is a string and the value returned is a pointer to thint trap is given when a real illegal instruction trap occurs. .sh "SEE ALSO" signal (II), cc (I) (`\-f' option) .sh BUGS Rounding mode is not interpreted. It's slow. .th ECVT III 4/30/73 .sh NAME ecvt, fcvt \*- output conversion .sh SYNOPSIS .ft B jsr pc,ecvt .s3 jsr pc,fcvt .s3 char *ecvt(value, ndigit, decpt, sign) .br double value; .br int ndigit, *decpt, *sign; .s3 char *fcvt(value, ndigit, decpt, sign) .br .li ... .ft R .sh DESCRIPTION .it Ecvt is called with a floating point number in fr0. .s3 On exit, the number has been converted into a string of ascii digits in a buffer pointed to by r0. The number of digits produced is controlled by a global variable \fI\*_ndie eight-character result. .s3 This routine is used to encrypt all passwords. .sh "SEE ALSO" passwd(I), passwd(V), login(I) .sh BUGS Short or otherwise simple passwords can be decrypted easily by exhaustive search. Six characters of gibberish is reasonably safe. .th FMOD III 2/13/75 .sh NAME fmod \*- floating modulo function .sh SYNOPSIS .ft B .nf double fmod(x, y) double x, y; .ft R .fi .sh DESCRIPTION .if t .ds L \(<= .if n .ds L <_ .it Fmod returns the number .it f such that .it "x = iy + f," .it i is an integer, and 0 \*L .it f < .it y. .sh BUGS gits\fR. .s3 Moreover, the position of the decimal point is contained in r2: r2=0 means the d.p. is at the left hand end of the string of digits; r2>0 means the d.p. is within or to the right of the string. .s3 The sign of the number is indicated by r1 (0 for +; 1 for \*-). .s3 The low order digit has suffered decimal rounding (i. e. may have been carried into). .s3 From C, the .it value is converted and a pointer to a null-terminated string of \fIndigit\fR digits is returned. The position of the decimal po.th ATOI III 2/8/75 .sh NAME atoi \*- convert ASCII to integer .sh SYNOPSIS .ft B atoi(nptr) .br char *nptr; .ft R .sh DESCRIPTION .it Atoi converts the string pointed to by .it nptr to an integer. The string can contain leading blanks or tabs, an optional `\-', and then an unbroken string of digits. Conversion stops at the first non-digit. .sh "SEE ALSO" atof (III) .sh BUGS There is no provision for overflow. .th FLOOR III 5/15/74 .sh NAME floor, ceil \*- floor and ceiling functions .sh SYNOPSIS .br .ft B double floor(x) .br double x; .s3 double ceil(x) .br double x; .ft R .sh DESCRIPTION The floor function returns the largest integer (as a double precision number) not greater than \fBx\fR. .s3 The ceil function returns the smallest integer not less than \fBx\fR. .sh BUGS int is stored indirectly through \fIdecpt\fR (negative means to the left of the returned digits). If the sign of the result is negative, the word pointed to by \fIsign\fR is non-zero, otherwise it is zero. .s3 \fIFcvt\fR is identical to \fIecvt\fR, except that the correct digit been rounded for F-style output of the number of digits specified by \fI\(*_ndigits\fR. .sh "SEE ALSO" printf (III) .sh BUGS .th ATOF III 4/30/73 .sh NAME atof \*- convert ASCII to floating .sh SYNOPSIS .ft B double atof(nptr) .br char *nptr; .br .ft R .sh DESCRIPTION .it Atof converts a string to a floating number. .it Nptr should point to a string containing the number; the first unrecognized character ends the number. .s3 The only numbers recognized are: an optional minus sign followed by a string of digits optionally containing one decimal point, then followed optionally by the letter \fBe\fR followed by a signed integer. .s.th EXP III 4/30/73 .sh NAME exp \*- exponential function .sh SYNOPSIS .ft B jsr pc,exp .s3 double exp(x) .br double x; .ft R .sh DESCRIPTION The exponential of fr0 is returned in fr0. From C, the exponential of \fIx\fR is returned. .sh DIAGNOSTICS If the result is not representable, the c-bit is set and the largest positive number is returned. From C, no diagnostic is available. .s3 Zero is returned if the result would underflow. .sh BUGS .th CTIME III 10/15/73 .sh NAME ctime, localtime, gmtime \*- convert date and time to ASCII .sh SYNOPSIS .ft B char *ctime(tvec) .br int tvec[2]; .s3 .ft R [from Fortran] .br .ft B double precision ctime .br .li ... = ctime(dummy) .s3 int *localtime(tvec) .br int tvec[2]; .s3 int *gmtime(tvec) .br int tvec[2]; .br .ft R .sh DESCRIPTION .it Ctime converts a time in the vector .it tvec such as returned by time (II) into ASCII and returns a pointer to a character string in the form .s3 Sun Sep 16 01:03:5h DIAGNOSTICS There are none; overflow results in a very large number and garbage characters terminate the scan. .sh BUGS The routine should accept initial \fB+\fR, initial blanks, and \fBE\fR for \fBe\fR. Overflow should be signalled. .th END III 4/28/75 .sh NAME end, etext, edata \*- last locations in program .sh SYNOPSIS .ft B .nf extern end; extern etext; extern edata; .ft R .fi .sh DESCRIPTION These names refer neither to routines nor to locations with interesting contents. Instead, their addresses coincide with the first address above the program text region .it (etext), above the initialized data region .it (edata), or uninitialized data region .it (end). The last is the same as the program break. Values are given to these symbols 2 1973\\n\\0 .s3 All the fields have constant width. .s3 The .it localtime and .it gmtime entries return pointers to integer vectors containing the broken-down time. .it Localtime corrects for the time zone and possible daylight savings time; .it gmtime converts directly to GMT, which is the time UNIX uses. The value is a pointer to an array whose components are .s3 .lp +5 5 0 seconds .lp +5 5 1 minutes .lp +5 5 2 hours .lp +5 5 3 day of the month (1-31) .lp +5 5 4 month (0-11) .lp +5 5 5 year \*- 1900 .lp .th ATAN III 4/30/73 .sh NAME atan, atan2 \*- arc tangent function .sh SYNOPSIS .ft B jsr pc,atan\fR[\fB2\fR]\fB .s3 .br double atan(x) .br double x; .br .s3 double atan2(x, y) .br double x, y; .ft R .sh DESCRIPTION The \fIatan\fR entry returns the arc tangent of fr0 in fr0; from C, the arc tangent of \fIx\fR is returned. The range is \*-\*p/2 to \*p/2. The \fIatan2\fR entry returns the arc tangent of fr0/fr1 in fr0; from C, the arc tangent of \fIx/y\fR is returned. The range is \*-\*p to \(*p. .sh DIAGNby the link editor .it ld (I) when, and only when, they are referred to but not defined in the set of programs loaded. .s3 The usage of these symbols is rather specialized, but one plausible possibility is .s3 .nf extern end; ... ... = brk(&end+...); .fi .s3 (see .it break (II)). The problem with this is that it ignores any other subroutines which may want to extend core for their purposes; these include .it sbrk (see .it break (II)), .it alloc (III), and also secret subroutines invoked by the profile (\+5 5 6 day of the week (Sunday = 0) .lp +5 5 7 day of the year (0-365) .lp +5 5 8 Daylight Saving Time flag if non-zero .i0 .s3 The external variable .it timezone contains the difference, in seconds, between GMT and local standard time (in EST, is 5*60*60); the external variable .it daylight is non-zero iff the standard U.S.A. Daylight Savings Time conversion should be applied. The program knows about the peculiarities of this conversion in 1974 and 1975; if necessary, a table for these years can be extendeOSTIC There is no error return. .sh BUGS .th ALLOC III 3/1/74 .sh NAME alloc, free \*- core allocator .sh SYNOPSIS .ft B .nf char *alloc(size) .s3 free(ptr) char *ptr; .fi .ft R .sh DESCRIPTION .it Alloc and .it free provide a simple general-purpose core management package. .it Alloc is given a size in bytes; it returns a pointer to an area at least that size which is even and hence can hold an object of any type. The argument to .it free is a pointer to an area previously allocated by .it alloc; this space is made available for further allocationmination. A special status (0177) is returned for a stopped process which has not terminated and can be restarted. See ptrace (II). If the 0200 bit of the termination status is set, a core image of the process was produced by the system. .s3 If the parent process terminates without waiting on its children, the initialization process (process ID = 1) inherits the children. .sh "SEE ALSO" exit (II), fork (II), signal (II) .sh DIAGNOSTICS The error bit (c-bit) is set if there are no children not previously wai.th TIME II 8/5/73 .sh NAME time \*- get date and time .sh SYNOPSIS (time = 13.) .br .ft B sys time .s3 time(tvec) .br int tvec[2]; .ft R .sh DESCRIPTION .it Time returns the time since 00:00:00 GMT, Jan. 1, 1970, measured in seconds. From .it as, the high order word is in the r0 register and the low order is in r1. From C, the user-supplied vector is filled in. .sh "SEE ALSO" date (I), stime (II), ctime (III) .sh DIAGNOSTICS \*- . .s3 Needless to say, grave disorder will result if the space assigned by .it alloc is overrun or if some random number is handed to .it free. .s3 The routine uses a first-fit algorithm which coalesces blocks being freed with other blocks already free. It calls .it sbrk (see .it "break (II))" to get more core from the system when there is no suitable space already free. .sh DIAGNOSTICS Returns \*-1 if there is no available core. .sh BUGS Allocated memory contains garbage instead of being cleared. ted for. From C, a returned value of \*-1 indicates an error. .th SYNC II 8/5/73 .sh NAME sync \*- update super-block .sh SYNOPSIS (sync = 36.; not in assembler) .br .ft B sys sync .ft R .sh DESCRIPTION .it Sync causes all information in core memory that should be on disk to be written out. This includes modified super blocks, modified i-nodes, and delayed block I/O. .s3 It should be used by programs which examine a file system, for example .it "icheck, df," etc. It is mandatory before a boot. .sh "SEE ALSO" sync (VIII), update (VIII) .sh DIAGNOSTICS \*- .th ABS III 2/9/75 .sh NAME abs, fabs \*- absolute value .sh SYNOPSIS .ft B abs(i) .br int i; .s3 double fabs(x) .br double x; .ft R .s3 .sh DESCRIPTION .it Abs returns the absolute value of its integer operand; .it fabs is the .it double version. .th UNLINK II 8/5/73 .sh NAME unlink \*- remove directory entry .sh SYNOPSIS (unlink = 10.) .br .ft B sys unlink; name .s3 unlink(name) .br char *name; .ft R .sh DESCRIPTION .it Name points to a null-terminated string. .it Unlink removes the entry for the file pointed to by .it name from its directory. If this entry was the last link to the file, the contents of the file are freed and the file is destroyed. If, however, the file was open in any process, the actual destruction is delayed until it is closed,{~.th ABORT III 4/10/75 .sh NAME abort \*- generate an IOT fault .sh SYNOPSIS .bd abort() .sh DESCRIPTION .it Abort executes the IOT instruction. This is usually considered a program fault by the system and results in termination with a core dump. It is used to generate a core image for debugging. .sh "SEE ALSO" db (I), cdb (I), signal (II) .sh DIAGNOSTICS usually ``IOT trap -- core dumped'' from the Shell. .sh BUGS even though the directory entry has disappeared. .sh "SEE ALSO" rm (I), rmdir (I), link (II) .sh DIAGNOSTICS The error bit (c-bit) is set to indicate that the file does not exist or that its directory cannot be written. Write permission is not required on the file itself. It is also illegal to unlink a directory (except for the super-user). From C, a \*-1 return indicates an error. .th STTY II 12/15/74 .sh NAME stty \*- set mode of typewriter .sh SYNOPSIS (stty = 31.) .br (file descriptor in r0) .br .ft B sys stty; arg .br .li ... .br arg: .byte ispeed, ospeed; .byte erase, kill; mode .s3 .nf stty(fildes, arg) struct { char ispeed, ospeed; char erase, kill; int mode; } *arg; .fi .ft R .s3 .sh DESCRIPTION .it Stty sets mode bits and character speeds for the typewriter whose file descriptor is passed in r0 (resp. is the first argument to the call). First, the system delays until th.th WRITE II 8/5/73 .sh NAME write \*- write on a file .sh SYNOPSIS (write = 4.) .br (file descriptor in r0) .br .ft B sys write; buffer; nbytes .s3 write(fildes, buffer, nbytes) .br char *buffer; .ft R .sh DESCRIPTION A file descriptor is a word returned from a successful .it open, .it creat, .it dup, or .it pipe call. .s3 .it Buffer is the address of .it nbytes contiguous bytes which are written on the output file. The number of characters actually written is returned (in r0). It should be regarded as an.th UMOUNT II 8/5/73 .sh NAME umount \*- dismount file system .sh SYNOPSIS (umount = 22.) .br .ft B sys umount; special .ft R .sh DESCRIPTION .it Umount announces to the system that special file .it special is no longer to contain a removable file system. The file associated with the special file reverts to its ordinary interpretation; see .it mount (II). .s3 .sh "SEE ALSO" umount (VIII), mount (II) .sh DIAGNOSTICS Error bit (c-bit) set if no file system was mounted on the special file or if there are stile typewriter is quiescent. The input and output speeds are set from the first two bytes of the argument structure as indicated by the following table, which corresponds to the speeds supported by the DH-11 interface. If DC-11, DL-11 or KL-11 interfaces are used, impossible speed changes are ignored. .s3 .lp +8 4 0 (hang up dataphone) .lp +8 4 1 50 baud .lp +8 4 2 75 baud .lp +8 4 3 110 baud .lp +8 4 4 134.5 baud .lp +8 4 5 150 baud .lp +8 4 6 200 baud .lp +8 4 7 300 baud .lp +8 4 8 600 baud .lp +8 4 9 1200 error if this is not the same as requested. .s3 Writes which are multiples of 512 characters long and begin on a 512-byte boundary in the file are more efficient than any others. .sh "SEE ALSO" creat (II), open (II), pipe (II) .sh DIAGNOSTICS The error bit (c-bit) is set on an error: bad descriptor, buffer address, or count; physical I/O errors. From C, a returned value of \*-1 indicates an error. l active files on the mounted file system. baud .lp +8 4 10 1800 baud .lp +8 4 11 2400 baud .lp +8 4 12 4800 baud .lp +8 4 13 9600 baud .lp +8 4 14 External A .lp +8 4 15 External B .s3 .i0 In the current configuration, only 110, 150 and 300 baud are really supported on dial-up lines, in that the code conversion and line control required for IBM 2741's (134.5 baud) must be implemented by the user's program, and the half-duplex line discipline required for the 202 dataset (1200 baud) is not supplied. .s3 The next two characters of the argument struct.th WAIT II 2/9/75 .sh NAME wait \*- wait for process to terminate .sh SYNOPSIS (wait = 7.) .br .ft B sys wait .ft R .br (process ID in r0) .br (status in r1) .s3 .ft B wait(status) .br int *status; .ft R .sh DESCRIPTION .it Wait causes its caller to delay until one of its child processes terminates. If any child has died since the last .it wait, return is immediate; if there are no children, return is immediate with the error bit set (resp. with a value of \*-1 returned). The normal return yields the proc.th TIMES II 8/5/73 .sh NAME times \*- get process times .sh SYNOPSIS (times = 43.; not in assembler) .br .ft B sys times; buffer .s3 times(buffer) .br struct tbuffer *buffer; .ft R .sh DESCRIPTION .it Times returns time-accounting information for the current process and for the terminated child processes of the current process. All times are in 1/60 seconds. .s3 After the call, the buffer will appear as follows: .s3 .nf struct tbuffer { int proc\*_user\*_time; int proc\*_system\*_time; int child\*_userure specify the erase and kill characters respectively. (Defaults are # and @.) .s3 The .it mode contains several bits which determine the system's treatment of the typewriter: .s3 .lp +12 7 100000 Select one of two algorithms for backspace delays .lp +12 7 040000 Select one of two algorithms for form-feed and vertical-tab delays .lp +12 7 030000 Select one of four algorithms for carriage-return delays .lp +12 7 006000 Select one of four algorithms for tab delays .lp +12 7 001400 Select one of four algorithess ID of the terminated child (in r0). In the case of several children several .it wait calls are needed to learn of all the deaths. .s3 If no error is indicated on return, the r1 high byte (resp. the high byte stored into .it status ) contains the low byte of the child process r0 (resp. the argument of .it exit ) when it terminated. The r1 (resp. .it status ) low byte contains the termination status of the process. See signal (II) for a list of termination statuses (signals); 0 status indicates normal ter\*_time[2]; int child\*_system\*_time[2]; }; .s3 .fi The children times are the sum of the children's process times and their children's times. .sh "SEE ALSO" time (I) .sh DIAGNOSTICS \*- .sh BUGS The process times should be 32 bits as well. ms for new-line delays .lp +12 7 000200 even parity allowed on input (e. g. for M37s) .lp +12 7 000100 odd parity allowed on input .lp +12 7 000040 raw mode: wake up on all characters .lp +12 7 000020 map CR into LF; echo LF or CR as CR-LF .lp +12 7 000010 echo (full duplex) .lp +12 7 000004 map upper case to lower on input (e. g. M33) .lp +12 7 000002 echo and print tabs as spaces .lp +12 7 000001 hang up (remove `data terminal ready,' lead CD) after last close .i0 .s3 The delay bits specify how long transmission stops to allow for mechanical or other movement when certain characters are sent to the terminal. In all cases a value of 0 indicates no delay. .s3 Backspace delays are currently ignored but will be used for Terminet 300's. .s3 If a form-feed/vertical tab delay is specified, it lasts for about 2 seconds. .s3 Carriage-return delay type 1 lasts about .08 seconds and is suitable for the Terminet 300. Delay type 2 lasts about .16 seconds and is suitable for the VT05 and the TI 700. Delay type 3 is unimpor device number */ int actime[2]; /* +28: time of last access */ int modtime[2]; /* +32: time of last modification */ }; .fi .s3 The flags are as follows: .s3 .lp +10 9 100000 i-node is allocated .lp +10 9 060000 2-bit file type: .lp +15 9 000000 plain file .lp +15 9 040000 directory .lp +15 9 020000 character-type special file .lp +15 9 060000 block-type special file. .lp +10 9 010000 large file .lp +10 9 004000 set user-ID on execution .lp +10 9 002000 set group-ID on execution .lp +10 9 001000 save tenals in the list above cause a core image if not caught or ignored. .s3 The value of the call is the old action defined for the signal. .s3 After a .it fork (II) the child inherits all signals. .it Exec (II) resets all caught signals to default action. .sh "SEE ALSO" kill (I), kill (II), ptrace (II), reset (III) .sh DIAGNOSTICS The error bit (c-bit) is set if the given signal is out of range. In C, a \*-1 indicates an error; 0 indicates success. .sh BUGS lemented and is 0. .s3 New-line delay type 1 is dependent on the current column and is tuned for Teletype model 37's. Type 2 is useful for the VT05 and is about .10 seconds. Type 3 is unimplemented and is 0. .s3 Tab delay type 1 is dependent on the amount of movement and is tuned to the Teletype model 37. Other types are unimplemented and are 0. .s3 Characters with the wrong parity, as determined by bits 200 and 100, are ignored. .s3 In raw mode, every character is passed immediately to the program without xt image after execution .lp +10 9 000400 read (owner) .lp +10 9 000200 write (owner) .lp +10 9 000100 execute (owner) .lp +10 9 000070 read, write, execute (group) .lp +10 9 000007 read, write, execute (others) .i0 .sh "SEE ALSO" ls (I), fstat (II), fs (V) .sh DIAGNOSTICS Error bit (c-bit) is set if the file cannot be found. From C, a \*-1 return indicates an error. .th SETUID II 8/5/73 .sh NAME setuid \*- set process user ID .sh SYNOPSIS (setuid = 23.) .br (user ID in r0) .ft B .br sys setuid .s3 setuid(uid) .ft R .sh DESCRIPTION The user ID of the current process is set to the argument. Both the effective and the real user ID are set. This call is only permitted to the super-user or if the argument is the real user ID. .sh "SEE ALSO" getuid (II) .sh DIAGNOSTICS Error bit (c-bit) is set as indicated; from C, a \*-1 value is returned. waiting until a full line has been typed. No erase or kill processing is done; the end-of-file character (EOT), the interrupt character (DEL) and the quit character (FS) are not treated specially. .s3 Mode 020 causes input carriage returns to be turned into new-lines; input of either CR or LF causes LF-CR both to be echoed (used for GE TermiNet 300's and other terminals without the newline function). .s3 The hangup mode 01 causes the line to be disconnected when the last process with the line open closes it.th SLEEP II 8/5/73 .sh NAME sleep \*- stop execution for interval .sh SYNOPSIS (sleep = 35.; not in assembler) .br (seconds in r0) .br .ft B sys sleep .s3 sleep(seconds) .ft R .sh DESCRIPTION The current process is suspended from execution for the number of seconds specified by the argument. .sh "SEE ALSO" sleep (I) .sh DIAGNOSTICS \*- .th SETGID II 8/5/73 .sh NAME setgid \*- set process group ID .sh SYNOPSIS (setgid = 46.; not in assembler) .br (group ID in r0) .ft B .br sys setgid .s3 setgid(gid) .ft R .sh DESCRIPTION The group ID of the current process is set to the argument. Both the effective and the real group ID are set. This call is only permitted to the super-user or if the argument is the real group ID. .sh "SEE ALSO" getgid (II) .sh DIAGNOSTICS Error bit (c-bit) is set as indicated; from C, a \*-1 value is returned. or terminates. It is useful when a port is to be used for some special purpose; for example, if it is associated with an ACU used to place outgoing calls. .s3 This system call is also used with certain special files other than typewriters, but since none of them are part of the standard system the specifications will not be given. .sh "SEE ALSO" stty (I), gtty (II) .sh DIAGNOSTICS The error bit (c-bit) is set if the file descriptor does not refer to a typewriter. From C, a negative value indicates an error.th SIGNAL II 8/5/73 .sh NAME signal \*- catch or ignore signals .sh SYNOPSIS (signal = 48.) .br .ft B sys signal; sig; label .ft R .br (old value in r0) .s3 .ft B signal(sig, func) .br int (*func)( ); .ft R .sh DESCRIPTION A .it signal is generated by some abnormal event, initiated either by user at a typewriter (quit, interrupt), by a program error (bus error, etc.), or by request of another program (kill). Normally all signals cause termination of the receiving process, but this call allows them either .th SEEK II 8/5/73 .sh NAME seek \*- move read/write pointer .sh SYNOPSIS (seek = 19.) .br (file descriptor in r0) .ft B .br sys seek; offset; ptrname .s3 seek(fildes, offset, ptrname) .ft R .sh DESCRIPTION The file descriptor refers to a file open for reading or writing. The read (resp. write) pointer for the file is set as follows: .s3 .lp +6 3 if .it ptrname is 0, the pointer is set to .it offset. .s3 .lp +6 3 if .it ptrname is 1, the pointer is set to its current location plus .it offset. .s3 .lp +6 3 i. to be ignored or to cause an interrupt to a specified location. Here is the list of signals: .s3 .lp +10 5 1 hangup .lp +10 5 2 interrupt .lp +10 5 3* quit .lp +10 5 4* illegal instruction (not reset when caught) .lp +10 5 5* trace trap (not reset when caught) .lp +10 5 6* IOT instruction .lp +10 5 7* EMT instruction .lp +10 5 8* floating point exception .lp +10 5 9 kill (cannot be caught or ignored) .lp +10 5 10* bus error .lp +10 5 11* segmentation violation .lp +10 5 12* bad argument to system call .lp +f .it ptrname is 2, the pointer is set to the size of the file plus .it offset. .s3 .lp +6 3 if .it ptrname is 3, 4 or 5, the meaning is as above for 0, 1 and 2 except that the offset is multiplied by 512. .s3 .i0 If .it ptrname is 0 or 3, .it offset is unsigned, otherwise it is signed. .sh "SEE ALSO" open (II), creat (II) .sh DIAGNOSTICS The error bit (c-bit) is set for an undefined file descriptor. From C, a \*-1 return indicates an error. .th STIME II 8/5/73 .sh NAME stime \*- set time .sh SYNOPSIS (stime = 25.) .br (time in r0-r1) .br .ft B sys stime .s3 stime(tbuf) .br int tbuf[2]; .ft R .sh DESCRIPTION .it Stime sets the system's idea of the time and date. Time is measured in seconds from 0000 GMT Jan 1 1970. Only the super-user may use this call. .sh "SEE ALSO" date (I), time (II), ctime (III) .sh DIAGNOSTICS Error bit (c-bit) set if user is not the super-user. 10 5 13 write on a pipe with no one to read it .s3 .i0 In the assembler call, if .it label is 0, the process is terminated when the signal occurs; this is the default action. If .it label is odd, the signal is ignored. Any other even .it label specifies an address in the process where an interrupt is simulated. An RTI or RTT instruction will return from the interrupt. Except as indicated, a signal is reset to 0 after being caught. Thus if it is desired to catch every such signal, the catching routine must i.th READ II 8/5/73 .sh NAME read \*- read from file .sh SYNOPSIS (read = 3.) .br (file descriptor in r0) .ft B .br sys read; buffer; nbytes .br .s3 read(fildes, buffer, nbytes) .br char *buffer; .ft R .sh DESCRIPTION A file descriptor is a word returned from a successful .it "open, creat, dup," or .it pipe call. .it Buffer is the location of .it nbytes contiguous bytes into which the input will be placed. It is not guaranteed that all .it nbytes bytes will be read; for example if the file refers to a typewr.th STAT II 8/5/73 .sh NAME stat \*- get file status .sh SYNOPSIS (stat = 18.) .br .ft B sys stat; name; buf .s3 stat(name, buf) .br char *name; .br struct inode *buf; .ft R .sh DESCRIPTION .it Name points to a null-terminated string naming a file; .it buf is the address of a 36(10) byte buffer into which information is placed concerning the file. It is unnecessary to have any permissions at all with respect to the file, but all directories leading to the file must be readable. After .it stat, .it buf has tssue another .it signal call. .s3 In C, if .it func is 0, the default action for signal .it sig (termination) is reinstated. If .it func is 1, the signal is ignored. If .it func is non-zero and even, it is assumed to be the address of a function entry point. When the signal occurs, the function will be called. A return from the function will continue the process at the point it was interrupted. As in the assembler call, .it signal must in general be called again to catch subsequent signals. .s3 When a caughiter at most one line will be returned. In any event the number of characters read is returned (in r0). .s3 If the returned value is 0, then end-of-file has been reached. .sh "SEE ALSO" open (II), creat (II), dup (II), pipe (II) .sh DIAGNOSTICS As mentioned, 0 is returned when the end of the file has been reached. If the read was otherwise unsuccessful the error bit (c-bit) is set. Many conditions can generate an error: physical I/O errors, bad buffer address, preposterous .it nbytes, file descriptor not thhe following structure (starting offset given in bytes): .s3 .if t .ta .5i 1i 2.5i .if n .ta 3 9 24 .nf struct inode { char minor; /* +0: minor device of i-node */ char major; /* +1: major device */ int inumber; /* +2 */ int flags; /* +4: see below */ char nlinks; /* +6: number of links to file */ char uid; /* +7: user ID of owner */ char gid; /* +8: group ID of owner */ char size0; /* +9: high byte of 24-bit size */ int size1; /* +10: low word of 24-bit size */ int addr[8]; /* +12: block numbers t signal occurs during certain system calls, the call terminates prematurely. In particular this can occur during a .it read or .it write on a slow device (like a typewriter; but not a file); and during .sleep or .it wait. When such a signal occurs, the saved user status is arranged in such a way that when return from the signal-catching takes place, it will appear that the system call returned a characteristic error status. The user's program may then, if it wishes, re-execute the call. .s3 The starred sigat of an input file. From C, a \*-1 return indicates the error. uent .it exec (II) calls. .sh "SEE ALSO" wait (II), signal (II), cdb (I) .sh DIAGNOSTICS From assembler, the c-bit (error bit) is set on errors; from C, \-1 is returned and .it errno has the error code. .sh BUGS The request 0 call should be able to specify signals which are to be treated normally and not cause a stop. In this way, for example, programs with simulated floating point (which use ``illegal instruction'' signals at a very high rate) could be efficiently debugged. .s3 Also, it should be possible.th OPEN II 8/5/73 .sh NAME open \*- open for reading or writing .sh SYNOPSIS (open = 5.) .br .ft B sys open; name; mode .br .ft R (file descriptor in r0) .s3 .ft B open(name, mode) .br char *name; .ft R .sh DESCRIPTION .it Open opens the file .it name for reading (if .it mode is 0), writing (if .it mode is 1) or for both reading and writing (if .it mode is 2). .it Name is the address of a string of ASCII characters representing a path name, terminated by a null character. .s3 The returned file descriptor s.th PTRACE II 1/25/75 .sh NAME ptrace \*- process trace .sh SYNOPSIS .nf (ptrace = 26.; not in assembler) (data in r0) .ft B sys ptrace; pid; addr; request .ft R .br (value in r0) .ft B .s3 ptrace(request, pid, addr, data); .ft R .fi .sh DESCRIPTION .it Ptrace provides a means by which a parent process may control the execution of a child process, and examine and change its core image. Its primary use is for the implementation of breakpoint debugging, but it should be adaptable for simulation of non-UNIX to stop a process on occurrence of a system call; in this way a completely controlled environment could be provided. hould be saved for subsequent calls to .it read, .it write, and .it close. .sh "SEE ALSO" creat (II), read (II), write (II), close (II) .sh DIAGNOSTICS The error bit (c-bit) is set if the file does not exist, if one of the necessary directories does not exist or is unreadable, if the file is not readable (resp. writable), or if too many files are open. From C, a \*-1 value is returned on an error. environments. There are four arguments whose interpretation depends on a .it request argument. Generally, .it pid is the process ID of the traced process, which must be a child (no more distant descendant) of the tracing process. A process being traced behaves normally until it encounters some signal whether internally generated like ``illegal instruction'' or externally generated like ``interrupt.'' See signal (II) for the list. Then the traced process enters a stopped state and its parent is notified via .th PROFIL II 5/15/74 .sh NAME profil \*- execution time profile .sh SYNOPSIS (profil = 44.; not in assembler) .br .ft B sys profil; buff; bufsiz; offset; scale .s3 profil(buff, bufsiz, offset, scale) .br char buff[ ]; .br int bufsiz, offset, scale; .ft R .sh DESCRIPTION .it Buff points to an area of core whose length (in bytes) is given by .it bufsiz. After this call, the user's program counter (pc) is examined each clock tick (60th second); .it offset is subtracted from it, and the result multiplied by .i.th NICE II 8/5/73 .sh NAME nice \*- set program priority .sh SYNOPSIS (nice = 34.) .br (priority in r0) .br .ft B sys nice .s3 nice(priority) .ft R .sh DESCRIPTION The scheduling .it priority of the process is changed to the argument. Positive priorities get less service than normal; 0 is default. Only the super-user may specify a negative priority. The valid range of .it priority is 20 to \*-220. The value of 4 is recommended to users who wish to execute long-running programs without flak from the adminis.it wait (II). When the child is in the stopped state, its core image can be examined and modified using .it ptrace. If desired, another .it ptrace request can then cause the child either to terminate or to continue, possibly ignoring the signal. .s3 The value of the .it request argument determines the precise action of the call: .s3 .lp +4 4 0 This request is the only one used by the child process; it declares that the process is to be traced by its parent. All the other arguments are ignored. Peculiar rest scale. If the resulting number corresponds to a word inside .it buff, that word is incremented. .s3 The scale is interpreted as an unsigned, fixed-point fraction with binary point at the left: 177777(8) gives a 1-1 mapping of pc's to words in .it buff; 77777(8) maps each pair of instruction words together. 2(8) maps all instructions onto the beginning of .it buff (producing a non-interrupting core clock). .s3 Profiling is turned off by giving a .it scale of 0 or 1. It is rendered ineffective by giving a .tration. .s3 The effect of this call is passed to a child process by the .it fork system call. The effect can be cancelled by another call to .it nice with a .it priority of 0. .s3 The actual running priority of a process is the .it priority argument plus a number that ranges from 100 to 119 depending on the cpu usage of the process. .sh "SEE ALSO" nice (I) .sh DIAGNOSTICS The error bit (c-bit) is set if the user requests a .it priority outside the range of 0 to 20 and is not the super-user. ults will ensue if the parent does not expect to trace the child. .s3 .lp +4 4 1,2 The word in the child process's address space at .it addr is returned (in r0). Request 1 indicates the data space (normally used); 2 indicates the instruction space (when I and D space are separated). .it addr must be even. The child must be stopped. The input .it data is ignored. .s3 .lp +4 4 3 The word of the system's per-process data area corresponding to .it addr is returned. .it Addr must be even and less than 512. This it bufsiz of 0. Profiling is also turned off when an .it exec is executed but remains on in child and parent both after a .it fork. .sh "SEE ALSO" monitor (III), prof (I) .sh DIAGNOSTICS \*- .th MOUNT II 5/15/74 .sh NAME mount \*- mount file system .sh SYNOPSIS (mount = 21.) .br .ft B sys mount; special; name; rwflag .s3 mount(special, name, rwflag) .br char *special, *name; .br .ft R .sh DESCRIPTION .it Mount announces to the system that a removable file system has been mounted on the block-structured special file .it special; from now on, references to file .it name will refer to the root file on the newly mounted file system. .it Special and .it name are pointers to null-terminated strings space contains the registers and other information about the process; its layout corresponds to the .it user structure in the system. .s3 .lp +4 4 4,5 The given .it data is written at the word in the process's address space corresponding to .it addr, which must be even. No useful value is returned. Request 4 specifies data space (normally used), 5 specifies instruction space. Attempts to write in pure procedure result in termination of the child, instead of going through or causing an error for the parent. .th PIPE II 8/5/73 .sh NAME pipe \*- create an interprocess channel .sh SYNOPSIS (pipe = 42.) .br .ft B sys pipe .br .ft R (read file descriptor in r0) .br (write file descriptor in r1) .s3 .ft B pipe(fildes) .br int fildes[2]; .ft R .sh DESCRIPTION The .it pipe system call creates an I/O mechanism called a pipe. The file descriptors returned can be used in read and write operations. When the pipe is written using the descriptor returned in r1 (resp. fildes[1]), up to 4096 bytes of data are buffered before containing the appropriate path names. .s3 .it Name must exist already. Its old contents are inaccessible while the file system is mounted. .s3 The .it rwflag argument determines whether the file system can be written on; if it is 0 writing is allowed, if non-zero no writing is done. Physically write-protected and magnetic tape file systems must be mounted read-only or errors will occur when access times are updated, whether or not any explicit write is attempted. .sh "SEE ALSO" mount (VIII), umount (II) ..s3 .lp +4 4 6 The process's system data is written, as it is read with request 3. Only a few locations can be written in this way: the general registers, the floating point status and registers, and certain bits of the processor status word. .s3 .lp +4 4 7 The .it data argument is taken as a signal number and the child's execution continues as if it had incurred that signal. Normally the signal number will be either 0 to indicate that the signal which caused the stop should be ignored, or that value fetchethe writing process is suspended. A read using the descriptor returned in r0 (resp. fildes[0]) will pick up the data. .s3 It is assumed that after the pipe has been set up, two (or more) cooperating processes (created by subsequent .it fork calls) will pass data through the pipe with .it read and .it write calls. .s3 The Shell has a syntax to set up a linear array of processes connected by pipes. .s3 Read calls on an empty pipe (no buffered data) with only one end (all write file descriptors closed) return sh DIAGNOSTICS Error bit (c-bit) set if: .it special is inaccessible or not an appropriate file; .it name does not exist; .it special is already mounted; .it name is in use; there are already too many file systems mounted. .sh BUGS \- d out of the process's image indicating which signal caused the stop. .s3 .lp +4 4 8 The traced process terminates. .s3 .i0 As indicated, these calls (except for request 0) can be used only when the subject process has stopped. The .it wait call is used to determine when a process stops; in such a case the ``termination'' status returned by .it wait has the value 0177 to indicate stoppage rather than genuine termination. .s3 To forestall possible fraud, .it ptrace inhibits the set-user-id facility on subseqan end-of-file. Write calls under similar conditions generate a fatal signal (signal (II)); if the signal is ignored, an error is returned on the write. .sh "SEE ALSO" sh (I), read (II), write (II), fork (II) .sh DIAGNOSTICS The error bit (c-bit) is set if too many files are already open. From C, a \*-1 returned value indicates an error. A signal is generated if a write on a pipe with only one end is attempted. .sh BUGS .th MKNOD II 8/5/73 .sh NAME mknod \*- make a directory or a special file .sh SYNOPSIS (mknod = 14.; not in assembler) .br .ft B sys mknod; name; mode; addr .s3 mknod(name, mode, addr) .br char *name; .ft R .sh DESCRIPTION .it Mknod creates a new file whose name is the null-terminated string pointed to by .it name. The mode of the new file (including directory and special file bits) is initialized from .it mode. The first physical address of the file is initialized from .it addr. Note that in the case of a directory, .it addr should be zero. In the case of a special file, .it addr specifies which special file. .s3 .it Mknod may be invoked only by the super-user. .sh "SEE ALSO" mkdir (I), mknod (VIII), fs (V) .sh DIAGNOSTICS Error bit (c-bit) is set if the file already exists or if the user is not the super-user. From C, a \*-1 value indicates an error. it Errno is not cleared on successful calls, so it should be tested only after an error has occurred. There is a table of messages associated with each error, and a routine for printing the message. See .it "perror (III)." .pg The possible error numbers are not recited with each writeup in section II, since many errors are possible for most of the calls. Here is a list of the error numbers, their names inside the system (for the benefit of system-readers), and the messages available using .it perror. A shortty to the TIU special file. .en 23 ENFILE "File table overflow" The system's table of open files is full, and temporarily no more .it opens can be accepted. .en 24 EMFILE "Too many open files" Only 15 files can be open per process. .en 25 ENOTTY "Not a typewriter" The file mentioned in .it stty or .it gtty is not a typewriter or one of the other devices to which these calls apply. .en 26 ETXTBSY "Text file busy" An attempt to execute a pure-procedure program which is currently open for writing (or reading!.th LINK II 8/5/73 .sh NAME link \*- link to a file .sh SYNOPSIS (link = 9.) .br .ft B sys link; name1; name2 .s3 link(name1, name2) .br char *name1, *name2; .ft R .sh DESCRIPTION A link to .it name1 is created; the link has the name .it name2. Either name may be an arbitrary path name. .sh "SEE ALSO" link (I), unlink (II) .sh DIAGNOSTICS The error bit (c-bit) is set when .it name1 cannot be found; when .it name2 already exists; when the directory of .it name2 cannot be written; when an attempt is made to lt explanation is also provided. .en 0 \(mi (unused) .en 1 EPERM "Not owner and not super-user" Typically this error indicates an attempt to modify a file in some way forbidden except to its owner. It is also returned for attempts by ordinary users to do things allowed only to the super-user. .en 2 ENOENT "No such file or directory" This error occurs when a file name is specified and the file should exist but doesn't, or when one of the directories in a path name does not exist. .en 3 ESRCH "No such process"). Also an attempt to open for writing a pure-procedure program that is being executed. .en 27 EFBIG "File too large" An attempt to make a file larger than the maximum of 32768 blocks. .en 28 ENOSPC "No space left on device" During a .it write to an ordinary file, there is no free space left on the device. .en 29 ESPIPE "Seek on pipe" A .it seek was issued to a pipe. This error should also be issued for other non-seekable devices. .en 30 EROFS "Read-only file system" An attempt to modify a file or directoryink to a directory by a user other than the super-user; when an attempt is made to link to a file on another file system; when more than 127 links are made. From C, a \*-1 return indicates an error, a 0 return indicates success. The process whose number was given to .it signal does not exist, or is already dead. .en 4 EINTR "Interrupted system call" An asynchronous signal (such as interrupt or quit), which the user has elected to catch, occurred during a system call. If execution is resumed after processing the signal, it will appear as if the interrupted system call returned this error condition. .en 5 EIO "I/O error" Some physical I/O error occurred during a .it read or .it write. This error may in some cases occur on a call fol was made on a device mounted read-only. .en 31 EMLINK "Too many links" An attempt to make more than 127 links to a file. .en 32 EPIPE "Write on broken pipe" A write on a pipe for which there is no process to read the data. This condition normally generates a signal; the error is returned if the signal is ignored. .th KILL II 12/15/74 .sh NAME kill \*- send signal to a process .sh SYNOPSIS (kill = 37.; not in assembler) .br (process number in r0) .br .ft B sys kill; sig .s3 kill(pid, sig); .ft R .sh DESCRIPTION .it Kill sends the signal .it sig to the process specified by the process number in r0. See signal (II) for a list of signals. .s3 The sending and receiving processes must have the same effective user ID, otherwise this call is restricted to the super-user. .s3 If the process number is 0, the signal is sent lowing the one to which it actually applies. .en 6 ENXIO "No such device or address" I/O on a special file refers to a subdevice which does not exist, or beyond the limits of the device. It may also occur when, for example, a tape drive is not dialled in or no disk pack is loaded on a drive. .en 7 E2BIG "Arg list too long" An argument list longer than 512 bytes (counting the null at the end of each argument) is presented to .it exec. .en 8 ENOEXEC "Exec format error" A request is made to execute a file whic.th INDIR II 8/5/73 .sh NAME indir \*- indirect system call .sh SYNOPSIS (indir = 0.; not in assembler) .br .ft B sys indir; syscall .ft R .sh DESCRIPTION The system call at the location .it syscall is executed. Execution resumes after the .it indir call. .s3 The main purpose of .it indir is to allow a program to store arguments in system calls and execute them out of line in the data segment. This preserves the purity of the text segment. .s3 If .it indir is executed indirectly, it is a no-op. If the instrto all other processes which have the same controlling typewriter and user ID. .s3 In no case is it possible for a process to kill itself. .sh "SEE ALSO" signal (II), kill (I) .sh DIAGNOSTICS The error bit (c-bit) is set if the process does not have the same effective user ID and the user is not super-user, or if the process does not exist. From C, \-1 is returned. h, although it has the appropriate permissions, does not start with one of the magic numbers 407 or 410. .en 9 EBADF "Bad file number" Either a file descriptor refers to no open file, or a read (resp. write) request is made to a file which is open only for writing (resp. reading). .en 10 ECHILD "No children" .it Wait and the process has no living or unwaited-for children. .en 11 EAGAIN "No more processes" In a .it fork, the system's process table is full and no more processes can for the moment be created. uction at the indirect location is not a system call, the executing process will get a fault. .sh "SEE ALSO" \*- .sh DIAGNOSTICS \*- .en 12 ENOMEM "Not enough core" During an .it exec or .it break, a program asks for more core than the system is able to supply. This is not a temporary condition; the maximum core size is a system parameter. The error may also occur if the arrangement of text, data, and stack segments is such as to require more than the existing 8 segmentation registers. .en 13 EACCES "Permission denied" An attempt was made to access a file in a way forbidden by the protection system. .en 14 \(mi (unused) .en 15 ENOTBLK "B.th GTTY II 8/5/73 .sh NAME gtty \*- get typewriter status .sh SYNOPSIS (gtty = 32.) .br (file descriptor in r0) .ft B .br sys gtty; arg .br .li ... .br arg: .=.+6 .s3 gtty(fildes, arg) .br int arg[3]; .ft R .sh DESCRIPTION .it Gtty stores in the three words addressed by .it arg the status of the typewriter whose file descriptor is given in r0 (resp. given as the first argument). The format is the same as that passed by .it stty. .sh "SEE ALSO" stty (II) .sh DIAGNOSTICS Error bit (c-bit) is set if the fil.th INTRO II 11/5/73 .de pg .sp .. .de en .pg .in 3 .ti 0 \\$1\t\\$2\t\\$3 .br .. .sp 2 .in 0 .if t .ta 3 10 .ce INTRODUCTION TO SYSTEM CALLS .sp Section II of this manual lists all the entries into the system. In most cases two calling sequences are specified, one of which is usable from assembly language, and the other from C. Most of these calls have an error return. From assembly language an erroneous call is always indicated by turning on the c-bit of the condition codes. The presence of an error is mlock device required" A plain file was mentioned where a block device was required, e.g. in .it mount. .en 16 EBUSY "Mount device busy" An attempt to mount a device that was already mounted or an attempt was made to dismount a device on which there is an open file or some process's current directory. .en 17 EEXIST "File exists" An existing file was mentioned in an inappropriate context, e.g. .it link. .en 18 EXDEV "Cross-device link" A link to a file on another device was attempted. .en 19 ENODEV "No such de descriptor does not refer to a typewriter. From C, a \*-1 value is returned for an error, 0, for a successful call. ost easily tested by the instructions .it bes and .it bec (``branch on error set (or clear)''). These are synonyms for the .it bcs and .it bcc instructions. .pg From C, an error condition is indicated by an otherwise impossible returned value. Almost always this is \(mi1; the individual sections specify the details. .pg In both cases an error number is also available. In assembly language, this number is returned in r0 on erroneous calls. From C, the external variable .it errno is set to the error number. .evice" An attempt was made to apply an inappropriate system call to a device; e.g. read a write-only device. .en 20 ENOTDIR "Not a directory" A non-directory was specified where a directory is required, for example in a path name or as an argument to .it chdir. .en 21 EISDIR "Is a directory" An attempt to write on a directory. .en 22 EINVAL "Invalid argument" Some invalid argument: currently, dismounting a non-mounted device, mentioning an unknown signal in .it signal, and giving an unknown request in .it s.th GETUID II 5/15/74 .sh NAME getuid \*- get user identifications .sh SYNOPSIS (getuid = 24.) .br .ft B sys getuid .ft B .s3 getuid( ) .ft R .sh DESCRIPTION .it Getuid returns a word (in r0), the low byte of which contains the real user ID of the current process. The high byte contains the effective user ID of the current process. The real user ID identifies the person who is logged in, in contradistinction to the effective user ID, which determines his access permission at the moment. It is thus useful to programs which operate using the ``set user ID'' mode, to find out who invoked them. .sh "SEE ALSO" setuid (II) .sh DIAGNOSTICS \*- ated because of lack of process space. From C, a return of \*-1 (not just negative) indicates an error. t be followed by a 0 pointer. .s3 When a C program is executed, it is called as follows: .s3 main(argc, argv) .br int argc; .br char **argv; .s3 where \fIargc\fR is the argument count and \fIargv\fR is an array of character pointers to the arguments themselves. As indicated, \fIargc\fR is conventionally at least one and the first member of the array points to a string containing the name of the file. .s3 .it Argv is not directly usable in another .it execv, since .it argv[argc] is \*-1 and not 0. .sh "SE.th GETPID II 2/8/75 .sh NAME getpid \*- get process identification .sh SYNOPSIS (getpid = 20.; not in assembler) .br .ft B sys getpid .ft R .br (pid in r0) .ft B .s3 getpid( ) .ft R .sh DESCRIPTION .it Getpid returns the process ID of the current process. Most often it is used to generate uniquely-named temporary files. .sh "SEE ALSO" \*- .sh DIAGNOSTICS \*- .th EXIT II 8/5/73 .sh NAME exit \*- terminate process .s3 .sh SYNOPSIS (exit = 1.) .br (status in r0) .br .ft B sys exit .s3 exit(status) .br int status; .ft R .sh DESCRIPTION .it Exit is the normal means of terminating a process. .it Exit closes all the process's files and notifies the parent process if it is executing a .it wait. The low byte of r0 (resp. the argument to \fIexit\fR) is available as status to the parent process. .s3 This call can never return. .sh "SEE ALSO" wait (II) .sh DIAGNOSTICS NoneE ALSO" fork (II) .sh DIAGNOSTICS If the file cannot be found, if it is not executable, if it does not have a valid header (407, 410, or 411 octal as first word), if maximum memory is exceeded, or if the arguments require more than 512 bytes a return from .it exec constitutes the diagnostic; the error bit (c-bit) is set. Even for the super-user, at least one of the execute-permission bits must be set for a file to be executed. From C the returned value is \*-1. .sh BUGS Only 512 characters of arguments are .th GETGID II 5/15/74 .sh NAME getgid \*- get group identifications .sh SYNOPSIS (getgid = 47.; not in assembler) .br .ft B sys getgid .ft B .s3 getgid( ) .ft R .sh DESCRIPTION .it Getgid returns a word (in r0), the low byte of which contains the real group ID of the current process. The high byte contains the effective group ID of the current process. The real group ID identifies the group of the person who is logged in, in contradistinction to the effective group ID, which determines his access permissi. allowed. on at the moment. It is thus useful to programs which operate using the ``set group ID'' mode, to find out who invoked them. .sh "SEE ALSO" setgid (II) .sh DIAGNOSTICS \*- .th EXEC II 8/5/73 .sh NAME exec, execl, execv \*- execute a file .sh SYNOPSIS (exec = 11.) .br .ft B sys exec; name; args .br .li ... .br name: <...\\0> .br .li ... .br args: arg0; arg1; ...; 0 .br arg0: <...\\0> .br arg1: <...\\0> .br ... .s3 execl(name, arg0, arg1, ..., argn, 0) .br char *name, *arg0, *arg1, ..., *argn; .s3 execv(name, argv) .br char *name; .br char *argv[ ]; .ft R .sh DESCRIPTION .it Exec overlays the calling process with the named file, then transfers to the beginning of the core .th DUP II 8/5/73 .sh NAME dup \*- duplicate an open file descriptor .sh SYNOPSIS (dup = 41.; not in assembler) .br (file descriptor in r0) .br .ft B sys dup .s3 dup(fildes) .br int fildes; .ft R .sh DESCRIPTION Given a file descriptor returned from an .it open, .it pipe, or .it creat call, .it dup will allocate another file descriptor synonymous with the original. The new file descriptor is returned in r0. .s3 .it Dup is used more to reassign the value of file descriptors than to genuinely duplicate a file.th FSTAT II 8/5/73 .sh NAME fstat \*- get status of open file .s3 .sh SYNOPSIS (fstat = 28.) .br (file descriptor in r0) .ft B .br sys fstat; buf .s3 fstat(fildes, buf) .br struct inode *buf; .ft R .sh DESCRIPTION This call is identical to .it stat, except that it operates on open files instead of files given by name. It is most often used to get the status of the standard input and output files, whose names are unknown. .sh "SEE ALSO" stat (II) .sh DIAGNOSTICS The error bit (c-bit) is set if the file deimage of the file. There can be no return from the file; the calling core image is lost. .s3 Files remain open across .it exec calls. Ignored signals remain ignored across .it exec, but signals that are caught are reset to their default values. .s3 Each user has a .it real user ID and group ID and an .it effective user ID and group ID. The real ID identifies the person using the system; the effective ID determines his access privileges. .it Exec changes the effective user and group ID to the owner of the ex descriptor. Since the algorithm to allocate file descriptors returns the lowest available value, combinations of .it dup and .it close can be used to manipulate file descriptors in a general way. This is handy for manipulating standard input and/or standard output. .sh "SEE ALSO" creat (II), open (II), close (II), pipe (II) .sh DIAGNOSTICS The error bit (c-bit) is set if: the given file descriptor is invalid; there are already too many open files. From C, a \*-1 returned value indicates an error. scriptor is unknown; from C, a \*-1 return indicates an error, 0 indicates success. ecuted file if the file has the ``set-user-ID'' or ``set-group-ID'' modes. The real user ID is not affected. .s3 The form of this call differs somewhat depending on whether it is called from assembly language or C; see below for the C version. .s3 The first argument to .it exec is a pointer to the name of the file to be executed. The second is the address of a null-terminated list of pointers to arguments to be passed to the file. Conventionally, the first argument is the name of the file. Each pointer addr.th CSW II 8/5/73 .sh NAME csw \*- read console switches .sh SYNOPSIS (csw = 38.; not in assembler) .br .ft B sys csw .s3 getcsw( ) .ft R .sh DESCRIPTION The setting of the console switches is returned (in r0). .th FORK II 8/5/73 .sh NAME fork \*- spawn new process .sh SYNOPSIS (fork = 2.) .br .ft B sys fork .br .ft R (new process return) .br (old process return) .s3 .ft B fork( ) .ft R .sh DESCRIPTION .it Fork is the only way new processes are created. The new process's core image is a copy of that of the caller of .it fork. The only distinction is the return location and the fact that r0 in the old (parent) process contains the process ID of the new (child) process. This process ID is used by .it wait. .s3 Theesses a string terminated by a null byte. .s3 Once the called file starts execution, the arguments are available as follows. The stack pointer points to a word containing the number of arguments. Just above this number is a list of pointers to the argument strings. The arguments are placed as high as possible in core. .s3 sp\*> nargs .br arg0 .br ... .br argn .br \*-1 .s3 arg0: .br ... .br argn: .s3 From C, two interfaces are available. .it execl is useful when a known file with.th CREAT II 8/5/73 .sh NAME creat \*- create a new file .sh SYNOPSIS (creat = 8.) .br .ft B sys creat; name; mode .br .ft R (file descriptor in r0) .ft B .s3 creat(name, mode) .br char *name; .ft R .sh DESCRIPTION .it Creat creates a new file or prepares to rewrite an existing file called .it name, given as the address of a null-terminated string. If the file did not exist, it is given mode .it mode. See .it chmod (II) for the construction of the .it mode argument. .s3 If the file did exist, its mode an two returning processes share all open files that existed before the call. In particular, this is the way that standard input and output files are passed and also how pipes are set up. .s3 From C, the child process receives a 0 return, and the parent receives a non-zero number which is the process ID of the child; a return of \*-1 indicates inability to create a new process. .sh "SEE ALSO" wait (II), exec (II) .sh DIAGNOSTICS The error bit (c-bit) is set in the old process if a new process could not be cre known arguments is being called; the arguments to .it execl are the character strings constituting the file and the arguments; as in the basic call, the first argument is conventionally the same as the file name (or its last component). A 0 argument must end the argument list. .s3 The .it execv version is useful when the number of arguments is unknown in advance; the arguments to .it execv are the name of the file to be executed and a vector of strings containing the arguments. The last argument string musd owner remain unchanged but it is truncated to 0 length. .s3 The file is also opened for writing, and its file descriptor is returned (in r0). .s3 The .it mode given is arbitrary; it need not allow writing. This feature is used by programs which deal with temporary files of fixed names. The creation is done with a mode that forbids writing. Then if a second instance of the program attempts a .it creat, an error is returned and the program knows that the name is unusable for the moment. .sh "SEE ALSO" write (II), close (II), stat (II) .sh DIAGNOSTICS The error bit (c-bit) may be set if: a needed directory is not searchable; the file does not exist and the directory in which it is to be created is not writable; the file does exist and is unwritable; the file is a directory; there are already too many files open. .s3 From C, a \*-1 return indicates an error. s an error, 0 indicates success. .th WALL VIII 4/10/75 .sh NAME wall \*- write to all users .sh SYNOPSIS .bd /etc/wall .sh DESCRIPTION .it Wall reads its standard input until an end-of-file. It then sends this message to all currently logged in users preceded by ``Broadcast Message ...''. It is used to warn all users, typically prior to shutting down the system. .s3 The sender should be super-user to override any protections the users may have invoked. .sh FILES /dev/tty? .sh "SEE ALSO" mesg (I), write (I) .sh DIAGNOSTICS ``Cannot send t.th CLOSE II 8/5/73 .sh NAME close \*- close a file .sh SYNOPSIS (close = 6.) .br (file descriptor in r0) .br .ft B sys close .s3 close(fildes) .s3 .ft R .sh DESCRIPTION Given a file descriptor such as returned from an .it open, .it creat, or .it pipe call, .it close closes the associated file. A close of all files is automatic on .it exit, but since processes are limited to 15 simultaneously open files, .it close is necessary for programs which deal with many files. .sh "SEE ALSO" creat (II), open (II), .th BREAK II 8/5/73 .sh NAME break, brk, sbrk \*- change core allocation .sh SYNOPSIS (break = 17.) .br .ft B sys break; addr .s3 char *brk(addr) .s3 char *sbrk(incr) .ft R .sh DESCRIPTION .it Break sets the system's idea of the lowest location not used by the program (called the break) to .it addr (rounded up to the next multiple of 64 bytes). Locations not less than .it addr and below the stack pointer are not in the address space and will thus cause a memory violation if accessed. .s3 From C, .it brk wilo ...'' when the open on a user's tty file fails. .sh BUGS pipe (II) .sh DIAGNOSTICS The error bit (c-bit) is set for an unknown file descriptor. From C a \*-1 indicates an error, 0 indicates success. l set the break to .it addr. The old break is returned. .s3 In the alternate entry .it sbrk, .it incr more bytes are added to the program's data space and a pointer to the start of the new area is returned. .s3 When a program begins execution via .it exec the break is set at the highest location defined by the program and data storage areas. Ordinarily, therefore, only programs with growing data areas need to use .it break. .sh "SEE ALSO" exec (II), alloc (III), end (III) .sh DIAGNOSTICS The c-bit is set if.th UPDATE VIII 11/1/73 .sh NAME update \*- periodically update the super block .sh SYNOPSIS .bd update .sh DESCRIPTION .it Update is a program that executes the .it sync primitive every 30 seconds. This insures that the file system is fairly up to date in case of a crash. This command should not be executed directly, but should be executed out of the initialization shell command file. See sync (II) for details. .sh "SEE ALSO" sync (II), init (VIII) .sh BUGS With .it update running, if the CPU is halted jus.th CHOWN II 12/15/74 .sh NAME chown \*- change owner and group of a file .sh SYNOPSIS (chmod = 16.) .br .ft B sys chown; name; owner .s3 chown(name, owner) .br char *name; .ft R .sh DESCRIPTION The file whose name is given by the null-terminated string pointed to by .it name has its owner and group changed to the low and high bytes of .it owner respectively. Only the super-user may execute this call, because if users were able to give files away, they could defeat the (nonexistent) file-space accounting pr the program requests more memory than the system limit or if more than 8 segmentation registers would be required to implement the break. From C, \*-1 is returned for these errors. .sh BUGS Setting the break in the range 0177700 to 0177777 is the same as setting it to zero. t as the .it sync is executed, a file system can be damaged. This is partially due to DEC hardware that writes zeros when NPR requests fail. A fix would be to have .it "sync" temporarily increment the system time by at least 30 seconds to trigger the execution of .it update. This would give 30 seconds grace to halt the CPU. ocedures. .sh "SEE ALSO" chown (VIII), chgrp (VIII), passwd (V) .sh DIAGNOSTICS The error bit (c-bit) is set on illegal owner changes. From C a \*-1 returned value indicates error, 0 indicates success. .th YACC I 11/25/74 .sh NAME yacc \*- yet another compiler-compiler .sh SYNOPSIS .bd yacc [ .bd \*-vor ] [ grammar ] .sh DESCRIPTION .it Yacc converts a context-free grammar into a set of tables for a simple automaton which executes an LR(1) parsing algorithm. The grammar may be ambiguous; specified precedence rules are used to break ambiguities. .s3 The output is .it y.tab.c, which must be compiled by the C compiler and loaded with any other routines required (perhaps a lexical analyzer) and the Yacc libra.th UMOUNT VIII 10/31/73 .sh NAME umount \*- dismount file system .sh SYNOPSIS .bd /etc/umount special .sh DESCRIPTION .it Umount announces to the system that the removable file system previously mounted on special file .it special is to be removed. .sh "SEE ALSO" mount (VIII), umount (II), mtab (V) .sh FILES /etc/mtab mounted device table .sh DIAGNOSTICS It complains if the special file is not mounted or if it is busy. The file system is busy if there is an open file on it or if someone has his current dir.th CHMOD II 12/15/74 .sh NAME chmod \*- change mode of file .sh SYNOPSIS (chmod = 15.) .br .ft B sys chmod; name; mode .s3 chmod(name, mode) .br char *name; .ft R .sh DESCRIPTION The file whose name is given as the null-terminated string pointed to by .it name has its mode changed to .it mode. Modes are constructed by ORing together some combination of the following: .s3 .in +3 4000 set user ID on execution 2000 set group ID on execution 1000 save text image after execution 0400 read by owner 0200 wriry: .s3 cc y.tab.c other.o \*-ly .s3 If the .bd \*-v flag is given, the file .it y.output is prepared, which contains a description of the parsing tables and a report on conflicts generated by ambiguities in the grammar. .s3 The .bd \*-o flag calls an optimizer for the tables; the optimized tables, with parser included, appear on file .it y.tab.c .s3 The .bd \*-r flag causes Yacc to accept grammars with Ratfor actions, and produce Ratfor output on .it y.tab.r; .bd \*-r implies the .bd \*-o flag. Typical usectory there. .sh BUGS te by owner 0100 execute (search on directory) by owner 0070 read, write, execute (search) by group 0007 read, write, execute (search) by others .in -3 .s3 Only the owner of a file (or the super-user) may change the mode. Only the super-user can set the 1000 mode. .sh "SEE ALSO" chmod (I) .sh DIAGNOSTIC Error bit (c-bit) set if .it name cannot be found or if current user is neither the owner of the file nor the super-user. From C, a \*-1 returned value indicates an error, 0 indicates success. age is then .s3 rc y.tab.r other.o .s3 .sh "SEE ALSO" ``LR Parsing'', by A. V. Aho and S. C. Johnson, Computing Surveys, June, 1974. ``The YACC Compiler-compiler'', internal memorandum. .sh AUTHOR S. C. Johnson .sh FILES y.output .br y.tab.c .br y.tab.r when ratfor output is obtained .br yacc.tmp when optimizer is called .br /lib/liby.a runtime library for compiler .br /usr/yacc/fpar.r ratfor parser .br /usr/yacc/opar.c parser for optimized tables .br /usr/yacc/yopti optimizer postpass .sh DIAGNOSTICS.th SYNC VIII 11/1/73 .sh NAME sync \*- update the super block .sh SYNOPSIS .bd sync .sh DESCRIPTION .it Sync executes the .it sync system primitive. If the system is to be stopped, .it sync must be called to insure file system integrity. See sync (II) for details. .sh "SEE ALSO" sync (II) .sh BUGS .th CHDIR II 8/5/73 .sh NAME chdir \*- change working directory .sh SYNOPSIS (chdir = 12.) .br .ft B sys chdir; dirname .s3 chdir(dirname) .br char *dirname; .ft R .sh DESCRIPTION .it Dirname is the address of the pathname of a directory, terminated by a null byte. .it Chdir causes this directory to become the current working directory. .sh "SEE ALSO" chdir (I) .sh DIAGNOSTICS The error bit (c-bit) is set if the given name is not that of a directory or is not readable. From C, a \*-1 returned value indicate The number of reduce-reduce and shift-reduce conflicts is reported on the standard output; a more detailed report is found in the .it y.output file. .sh BUGS Because file names are fixed, at most one Yacc process can be active in a given directory at a time. .th SU VIII 10/31/73 .sh NAME su \*- become privileged user .sh SYNOPSIS .bd su .sh DESCRIPTION .it Su allows one to become the super-user, who has all sorts of marvelous (and correspondingly dangerous) powers. In order for \fIsu\fR to do its magic, the user must supply a password. If the password is correct, \fIsu\fR will execute the Shell with the UID set to that of the super-user. To restore normal UID privileges, type an end-of-file to the super-user Shell. .s3 The password demanded is that of the entry ``root'' in the system's password file. .s3 To remind the super-user of his responsibilities, the Shell substitutes `#' for its usual prompt `%'. .sh "SEE ALSO" sh (I) the next argument file instead of the tape. .s3 .lp +5 3 \fBi\fR All read and checksum errors are reported, but will not cause termination. .s3 .lp +5 3 \fBw\fR In conjunction with the .bd x option, before each file is extracted, its i-number is typed out. To extract this file, you must respond with .bd y. .s3 .i0 The .bd x option is used to retrieve individual files. If the i-number of the desired file is not known, it can be discovered by following the file system directory search algorithm. First retrie.th MKNOD VIII 2/11/75 .sh NAME mknod \*- build special file .sh SYNOPSIS .bd /etc/mknod name [ .bd c ] [ .bd b ] major minor .sh DESCRIPTION .it Mknod makes a directory entry and corresponding i-node for a special file. The first argument is the .it name of the entry. The second is .bd b if the special file is block-type (disks, tape) or .bd c if it is character-type (other devices). The last two arguments are numbers specifying the .it major device type and the .it minor device (e.g. unit, drive, or line .th SA VIII 6/1/74 .sh NAME sa \*- Shell accounting .sh SYNOPSIS sa [ .bd \*-abcjlnrstuv ] [ file ] .sh DESCRIPTION When a user logs in, if the Shell is able to open the file .it /usr/adm/sha, then as each command completes the Shell writes at the end of this file the name of the command, the user, system, and real time consumed, and the user ID. .it Sa reports on, cleans up, and generally maintains this and other accounting files. To turn accounting on and off, the accounting file must be created or destrove the .it root directory whose i-number is 1. List this file with .it "ls \*-fi 1." This will give names and i-numbers of sub-directories. Iterating, any file may be retrieved. .s3 The .bd r option should only be used to restore a complete dump tape onto a clear file system or to restore an incremental dump tape onto this. Thus .s3 /etc/mkfs /dev/rp0 40600 .br restor r /dev/rp0 .s3 is a typical sequence to restore a complete dump. Another .it restor can be done to get an incremental dump in on top of thinumber). .s3 The assignment of major device numbers is specific to each system. They have to be dug out of the system source file .it conf.c. .sh "SEE ALSO" mknod (II) .sh BUGS yed externally. .s3 .it Sa is able to condense the information in .it /usr/adm/sha into a summary file .it /usr/adm/sht which contains a count of the number of times each command was called and the time resources consumed. This condensation is desirable because on a large system .it sha can grow by 100 blocks per day. The summary file is read before the accounting file, so the reports include all available information. .s3 If a file name is given as the last argument, that file will be treated as the accouns. .s3 A .it dump followed by a .it mkfs and a .it restor is used to change the size of a file system. .sh FILES /dev/mt0 .sh "SEE ALSO" ls (I), dump (VIII), mkfs (VIII), clri (VIII) .sh DIAGNOSTICS There are various diagnostics involved with reading the tape and writing the disk. There are also diagnostics if the i-list or the free list of the file system is not large enough to hold the dump. .s3 If the dump extends over more than one tape, it may ask you to change tapes. Reply with a new-line when the nex.th MKFS VIII 11/1/73 .sh NAME mkfs \*- construct a file system .sh SYNOPSIS .bd /etc/mkfs special proto .sh DESCRIPTION .it Mkfs constructs a file system by writing on the special file .it special according to the directions found in the prototype file .it proto. The prototype file contains tokens separated by spaces or new lines. The first token is the name of a file to be copied onto block zero as the bootstrap program (see boot procedures (VIII)). The second token is a number specifying the size of the ting file; .it sha is the default. There are zillions of options: .s3 .de qq .s3 .lp +3 3 \fB\\$1\fR \\ .. .qq a Place all command names containing unprintable characters and those used only once under the name ``***other.'' .qq b Sort output by sum of user and system time divided by number of calls. Default sort is by sum of user and system times. .qq c Besides total user, system, and real time for each command print percentage of total time over all commands. .qq j Instead of total minutes time for each ct tape has been mounted. .sh BUGS There is redundant information on the tape that could be used in case of tape reading problems. Unfortunately, .it restor's approach is to exit if anything is wrong. created file system. Typically it will be the number of blocks on the device, perhaps diminished by space for swapping. The next token is the i-list size in blocks (remember there are 16 i-nodes per block). The next set of tokens comprise the specification for the root file. File specifications consist of tokens giving the mode, the user-id, the group id, and the initial contents of the file. The syntax of the contents field depends on the mode. .s3 The mode token for a file is a 6 character string. The firategory, give seconds per call. .qq l Separate system and user time; normally they are combined. .qq n Sort by number of calls. .qq r Reverse order of sort. .qq s Merge accounting file into summary file .it /usr/adm/sht when done. .qq t For each command report ratio of real time to the sum of user and system times. .qq u Superseding all other flags, print for each command in the accounting file the day of the year, time, day of the week, user ID and command name. .qq v If the next character is a digit .it n.th NCHECK VIII 2/8/75 .sh NAME ncheck \*- generate names from i-numbers .sh SYNOPSIS .bd ncheck [ .bd \*-i numbers ] [ .bd \*-a ] [ filesystem ] .sh DESCRIPTION .it Ncheck with no argument generates a pathname vs. i-number list of all files on a set of default file systems. The .bd \*-i flag reduces the report to only those files whose i-numbers follow. .bd \*-a allows printing of the names `.' and `..', which are ordinarily suppressed. A file system may be specified. .s3 The full report is in no usefust character specifies the type of the file. (The characters .bd \*-bcd specify regular, block special, character special and directory files respectively.) The second character of the type is either .bd u or .bd \*- to specify set-user-id mode or not. The third is .bd g or .bd \*- for the set-group-id mode. The rest of the mode is a three digit octal number giving the owner, group, and other read, write, execute permissions (see .it chmod (I)). .s3 Two decimal number tokens come after the mode; they specif, then type the name of each command used .it n times or fewer. Await a reply from the typewriter; if it begins with ``y'', add the command to the category ``**junk**.'' This is used to strip out garbage. .i0 .dt .sh FILES /usr/adm/sha accounting .br /usr/adm/sht summary .sh "SEE ALSO" ac (VIII) .sh BUGS l order, and probably should be sorted. .sh "SEE ALSO" dcheck (VIII), icheck (VIII), sort (I) .sh BUGS y the user and group ID's of the owner of the file. .s3 If the file is a regular file, the next token is a pathname whence the contents and size are copied. .s3 If the file is a block or character special file, two decimal number tokens follow which give the major and minor device numbers. .s3 If the file is a directory, .it mkfs makes the entries \fB.\fR and \fB..\fR and then reads a list of names and (recursively) file specifications for the entries in the directory. The scan is terminated with the token .th RESTOR VIII 11/24/73 .sh NAME restor \*- incremental file system restore .sh SYNOPSIS .bd restor key [ arguments ] .sh DESCRIPTION .it Restor is used to read magtapes dumped with the .it dump command. The .it key argument specifies what is to be done. .it Key is a character from the set .bd trxw. .s3 .lp +5 3 \fBt\fR The date that the tape was made and the date that was specified in the .it dump command are printed. A list of all of the i-numbers on the tape is also given. .s3 .lp +5 3 \fBr\fR The tape .th MOUNT VIII 10/31/73 .sh NAME mount \*- mount file system .sh SYNOPSIS .bd /etc/mount special file [ .bd \*-r ] .sh DESCRIPTION .it Mount announces to the system that a removable file system is present on the device corresponding to special file .it special (which must refer to a disk or possibly DECtape). The .it file must exist already; it becomes the name of the root of the newly mounted file system. .s3 .it Mount maintains a table of mounted devices; if invoked without an argument it prints the tabl\fB$\fR. .s3 If the prototype file cannot be opened and its name consists of a string of digits, .it mkfs builds a file system with a single empty directory on it. The size of the file system is the value of .it proto interpreted as a decimal number. The i-list size is the file system size divided by 43 plus the size divided by 1000. (This corresponds to an average size of three blocks per file for a 4000 block file system and six blocks per file at 40,000.) The boot program is left uninitialized. .s3 A samis read and loaded into the file system specified in .it arguments. This should not be done lightly (see below). .s3 .lp +5 3 \fBx\fR Each file on the tape is individually extracted into a file whose name is the file's i-number. If there are .it arguments, they are interpreted as i-numbers and only they are extracted. .s3 .lp +5 3 \fBc\fR If the tape overflows, increment the last character of its name and continue on that drive. (Normally it asks you to change tapes.) .s3 .lp +5 3 \fBf\fR Read the dump frome. .s3 The optional last argument indicates that the file is to be mounted read-only. Physically write-protected and magnetic tape file systems must be mounted in this way or errors will occur when access times are updated, whether or not any explicit write is attempted. .sh "SEE ALSO" mount (II), mtab (V), umount (VIII) .sh BUGS Mounting file systems full of garbage will crash the system. ple prototype specification follows: .s3 .nf .in +5 /usr/mdec/uboot 4872 55 d\*-\*-777 3 1 usr d\*-\*-777 3 1 sh \*-\*-\*-755 3 1 /bin/sh ken d\*-\*-755 6 1 $ b0 b\*-\*-644 3 1 0 0 c0 c\*-\*-644 3 1 0 0 $ $ .in -5 .fi .sh "SEE ALSO" file system (V), directory (V), boot procedures (VIII) .sh BUGS It is not possible to initialize a file larger than 64K bytes. .br The size of the file system is restricted to 64K blocks. .br There should be some way to specify links. .th LPD VIII 6/1/74 .sh NAME lpd \*- line printer daemon .sh SYNOPSIS .bd /etc/lpd .sh DESCRIPTION .it Lpd is the line printer daemon (spool area handler) invoked by .it opr. It uses the directory .it /usr/lpd. The file .it lock in that directory is used to prevent two daemons from becoming active simultaneously. After the daemon has successfully set the lock, it scans the directory for files beginning with ``df.'' Lines in each .it df file specify files to be printed in the same way as is done by the data-.th ICHECK VIII 2/9/75 .sh NAME icheck \*- file system storage consistency check .sh SYNOPSIS .bd icheck [ .bd \*-s ] [ .bd \*-b numbers ] [ filesystem ] .sh DESCRIPTION .it Icheck examines a file system, builds a bit map of used blocks, and compares this bit map against the free list maintained on the file system. If the file system is not specified, a set of default file systems is checked. The normal output of .it icheck includes a report of .s3 .lp +4 0 The number of blocks missing; i.e. not in any filriter line. Arguments other than `0' can be used to make .it getty treat the line specially. Normally, it sets the speed of the interface to 300 baud, specifies that raw mode is to be used (break on every character), that echo is to be suppressed, and either parity allowed. It types the ``login:'' message, which includes the characters which put the Terminet 300 terminal into full-duplex and return the GSI terminal to non-graphic mode. Then the user's name is read, a character at a time. If a null characterphone daemon dpd (VIII). .sh FILES /usr/lpd/* spool area .br /dev/lp printer .sh "SEE ALSO" dpd (VIII), opr (I) .sh BUGS e nor in the free list, .lp +4 0 The number of special files, .lp +4 0 The total number of files, .lp +4 0 The number of large and huge files, .lp +4 0 The number of directories, .lp +4 0 The number of indirect blocks, and the number of double-indirect blocks in huge files, .lp +4 0 The number of blocks used in files, .lp +4 0 The number of free blocks. .s3 .i0 The .bd \*-s flag causes .it icheck to ignore the actual free list and reconstruct a new one by rewriting the super-block of the file system. The fi is received, it is assumed to be the result of the user pushing the ``break'' (``interrupt'') key. The speed is then changed to 150 baud and the ``login:'' is typed again, this time including the character sequence which puts a Teletype 37 into full-duplex. If a subsequent null character is received, the speed is changed back to 300 baud. .s3 The user's name is terminated by a new-line or carriage-return character. The latter results in the system being set to treat carriage returns appropriately (see .it .th INIT VIII 2/22/74 .sh NAME init \*- process control initialization .sh SYNOPSIS .bd /etc/init .sh DESCRIPTION .it Init is invoked inside UNIX as the last step in the boot procedure. Generally its role is to create a process for each typewriter on which a user may log in. .s3 First, .it init checks to see if the console switches contain 173030. (This number is likely to vary between systems.) If so, the console typewriter .bd /dev/tty8 is opened for reading and writing and the Shell is invoked immediatle system should be dismounted while this is done; if this is not possible (for example if the root file system has to be salvaged) care should be taken that the system is quiescent and that it is rebooted immediately afterwards so that the old, bad in-core copy of the super-block will not continue to be used. Notice also that the words in the super-block which indicate the size of the free list and of the i-list are believed. If the super-block has been curdled these words will have to be patched. The .bd stty (II)). .s3 The user's name is scanned to see if it contains any lower-case alphabetic characters; if not, and if the name is nonempty, the system is told to map any future upper-case characters into the corresponding lower-case characters. .s3 Finally, login is called with the user's name as argument. .sh "SEE ALSO" init (VIII), login (I), stty (II), ttys (V) .sh BUGS ely. This feature is used to bring up a single-user system. When the system is brought up in this way, the .it getty and .it login routines mentioned below and described elsewhere are not used. If the Shell terminates, .it init starts over looking for the console switch setting. .s3 Otherwise, \fIinit\fR invokes a Shell, with input taken from the file .it /etc/rc. This command file performs housekeeping like removing temporary files, mounting file systems, and starting daemons. .s3 Then .it init reads the f\*-s flag causes the normal output reports to be suppressed. .s3 Following the .bd \-b flag is a list of block numbers; whenever any of the named blocks turns up in a file, a diagnostic is produced. .s3 .it Icheck is faster if the raw version of the special file is used, since it reads the i-list many blocks at a time. .sh FILES Currently, /dev/rrk2 and /dev/rrp0 are the default file systems. .sh "SEE ALSO" dcheck (VIII), ncheck (VIII), fs (V), clri (VIII), restor(VIII) .sh DIAGNOSTICS For duplicate blocks .th DUMP VIII 11/24/73 .sh NAME dump \*- incremental file system dump .sh SYNOPSIS .bd dump [ key [ arguments ] filesystem ] .sh DESCRIPTION .it Dump makes an incremental file system dump on magtape of all files changed after a certain date. The .it key argument specifies the date and other options about the dump. .it Key consists of characters from the set .bd abcfiu0hds. .s3 .lp +5 5 \fBa\fR Normally files larger than 1000 blocks are not incrementally dump; this flag forces them to be dumped. .s3 .lp +5 5ile .it /etc/ttys and forks several times to create a process for each typewriter specified in the file. Each of these processes opens the appropriate typewriter for reading and writing. These channels thus receive file descriptors 0 and 1, the standard input and output. Opening the typewriter will usually involve a delay, since the \fIopen\fR is not completed until someone is dialed up and carrier established on the channel. Then .it /etc/getty is called with argument as specified by the last character ofand bad blocks (which lie outside the file system) .it icheck announces the difficulty, the i-number, and the kind of block involved. If a read error is encountered, the block number of the bad block is printed and .it icheck considers it to contain 0. ``Bad freeblock'' means that a block number outside the available space was encountered in the free list. ``\fIn\fR dups in free'' means that \fIn\fR blocks were found in the free list which duplicate blocks either in some file or in the earlier part of the f \fBb\fR The next argument is taken to be the maximum size of the dump tape in blocks (see \fBs\fR). .s3 .lp +5 5 \fBc\fR If the tape overflows, increment the last character of its name and continue on that drive. (Normally it asks you to change tapes.) .s3 .lp +5 5 \fBf\fR Place the dump on the next argument file instead of the tape. .s3 .lp +5 5 \fBi\fR the dump date is taken from the entry in the file /etc/dtab corresponding to the last time this file system was dumped with the .bd -u option. .s3 .lp +5 the .it ttys file line. .it Getty reads the user's name and invokes .it login (q.v.) to log in the user and execute the Shell. .s3 Ultimately the Shell will terminate because of an end-of-file either typed explicitly or generated as a result of hanging up. The main path of \fIinit\fR, which has been waiting for such an event, wakes up and removes the appropriate entry from the file \fIutmp\fR, which records current users, and makes an entry in \fI/usr/adm/wtmp\fR, which maintains a history of logins and loree list. .sh BUGS Since .it icheck is inherently two-pass in nature, extraneous diagnostics may be produced if applied to active file systems. .br It believes even preposterous super-blocks and consequently can get core images. 5 \fBu\fR the date just prior to this dump is written on /etc/dtab upon successful completion of this dump. This file contains a date for every file system dumped with this option. .s3 .lp +5 5 \fB0\fR the dump date is taken as the epoch (beginning of time). Thus this option causes an entire file system dump to be taken. .s3 .lp +5 5 \fBh\fR the dump date is some number of hours before the current date. The number of hours is taken from the next argument in .it arguments. .s3 .lp +5 5 \fBd\fR the dump date gouts. Then the appropriate typewriter is reopened and .it getty is reinvoked. .s3 .it Init catches the .it hangup signal (signal #1) and interprets it to mean that the switches should be examined as in a reboot: if they indicate a multi-user system, the .it /etc/ttys file is read again. The Shell process on each line which used to be active in .it ttys but is no longer there is terminated; a new process is created for each added line; lines unchanged in the file are undisturbed. Thus it is possible to drop.th GLOB VIII 9/19/73 .sh NAME glob \*- generate command arguments .sh SYNOPSIS .bd /etc/glob command [ arguments ] .sh DESCRIPTION .it Glob is used to expand arguments to the shell containing ``*'', ``['', or ``?''. It is passed the argument list containing the metacharacters; .it glob expands the list and calls the indicated command. The actions of .it glob are detailed in the Shell writeup. .sh SEE ALSO" sh (I) .sh BUGS is some number of days before the current date. The number of days is taken from the next argument in .it arguments. .s3 .lp +5 5 \fBs\fR the size of the dump tape is specified in feet. The number of feet is taken from the next argument in .it arguments. It is assumed that there are 9 standard UNIX records per foot. When the specified size is reached, the dump will wait for reels to be changed. The default size is 2200 feet. .s3 .i0 .dt .dt If no arguments are given, the .it key is assumed to be .bd i and t or add phone lines without rebooting the system by changing the .it ttys file and sending a .it hangup signal to the .it init process: use ``kill \*-1 1.'' .sh FILES /dev/tty?, /etc/utmp, /usr/adm/wtmp, /etc/ttys, /etc/rc .sh "SEE ALSO" login (I), kill (I), sh (I), ttys (V), getty (VIII) .th GETTY VIII 2/11/75 .sh NAME getty \*- set typewriter mode .sh SYNOPSIS .bd /etc/getty [ char ] .sh DESCRIPTION .it Getty is invoked by .it init (VIII) immediately after a typewriter is opened following a dial-up. It reads the user's name and invokes the .it login command (I) with the name as argument. While reading the name .it getty attempts to adapt the system to the speed and type of terminal being used. .s3 .it Init calls .it getty with an argument specified by the .it ttys file entry for the typewhe file system is assumed to be /dev/rp0. .s3 Full dumps should be taken on quiet file systems as follows: .s3 dump 0u /dev/rp0 .br ncheck /dev/rp0 .s3 The .it ncheck will come in handy in case it is necessary to restore individual files from this dump. Incremental dumps should then be taken when desired by: .s3 dump .s3 When the incremental dumps get cumbersome, a new complete dump should be taken. In this way, a restore requires loading of the complete dump tape and only the latest incremental tape. .sh DIAGNOSTICS If the dump requires more than one tape, it will ask you to change tapes. Reply with a new-line when this has been done. If the first block on the new tape is not writable, e.g. because you forgot the write ring, you get a chance to fix it. Generally, however, read or write failures are fatal. .sh FILES /dev/mt0 magtape .br /dev/rp0 default file system .br /etc/dtab .sh "SEE ALSO" restor (VIII), ncheck (VIII), dump (V) .sh BUGS ccurs when there are more entries than links; if entries are removed, so the link-count drops to 0, the remaining entries point to thin air. They should be removed. When there are more links than entries, or there is an allocated file with neither links nor entries, some disk space may be lost but the situation will not degenerate. .sh "SEE ALSO" icheck (VIII), fs (V), clri (VIII), ncheck (VIII) .sh BUGS Since .it dcheck is inherently two-pass in nature, extraneous diagnostics may be produced if applied to ss 44, and start. This should write a copy of all of core on the tape with an EOF mark. Caution: Any error is taken to mean the end of core has been reached. This means that you must be sure the ring is in, the tape is ready, and the tape is clean and new. If the dump fails, you can try again, but some of the registers will be lost. See below for what to do with the tape. .s3 In restarting after a crash, always bring up the system single-user. This is accomplished by following the directions in .it "boot pr.th DPD VIII 3/15/72 .sh NAME dpd \*- data phone daemon .sh SYNOPSIS .bd /etc/dpd .sh DESCRIPTION .it Dpd is the 201 data phone daemon. It is designed to submit jobs to the Honeywell 6070 computer via the GRTS interface. .s3 .it Dpd uses the directory .it /usr/dpd. The file .it lock in that directory is used to prevent two daemons from becoming active. After the daemon has successfully set the lock, it forks and the main path exits, thus spawning the daemon. The directory is scanned for files beginning withactive file systems. ocedures" (VIII) as modified for your particular installation; a single-user system is indicated by having a particular value in the switches (173030 unless you've changed .it init) as the system starts executing. When it is running, perform a .it dcheck and .it icheck (VIII) on all file systems which could have been in use at the time of the crash. If any serious file system problems are found, they should be repaired. When you are satisfied with the health of your disks, check and set the date if necessar .bd df. Each such file is submitted as a job. Each line of a job file must begin with a key character to specify what to do with the remainder of the line. .s3 .lp +5 3 \fBS\fR directs .it dpd to generate a unique snumb card. This card is generated by incrementing the first word of the file .it /usr/dpd/snumb and converting that to three-digit octal concatenated with the station ID. .s3 .lp +5 3 \fBL\fR specifies that the remainder of the line is to be sent as a literal. .s3 .lp +5 3 \fBB\fR specifies that.th CRON VIII 10/25/74 .sh NAME cron \*- clock daemon .sh SYNOPSIS .bd /etc/cron .sh DESCRIPTION .it Cron executes commands at specified dates and times according to the instructions in the file /usr/lib/crontab. Since .it cron never exits, it should only be executed once. This is best done by running .it cron from the initialization process through the file /etc/rc; see .it init (VIII). .s2 Crontab consists of lines of six fields each. The fields are separated by spaces or tabs. The first five are integer y, then come up multi-user. This is most easily accomplished by changing the single-user value in the switches to something else, then logging out by typing an EOT. .s3 To even boot \s8UNIX\s10 at all, three files (and the directories leading to them) must be intact. First, the initialization program .it /etc/init must be present and executable. If it is not, the CPU will loop in user mode at location 6. For .it init to work correctly, .it /dev/tty8 and .it /bin/sh must be present. If either does not exist, the rest of the line is a file name. That file is to be sent as binary cards. .s3 .lp +5 3 \fBF\fR is the same as \fBB\fR except a form feed is prepended to the file. .s3 .lp +5 3 \fBU\fR specifies that the rest of the line is a file name. After the job has been transmitted, the file is unlinked. .s3 .lp +5 3 \fBM\fR is followed by a user ID; after the job is sent, the snumb number and the first line of information in the file is mailed to the user to verify the sending of the job. .s3 .i0 Any error encounpatterns to specify the minute (0-59), hour (0-23), day of the month (1-31), month of the year (1-12), and day of the week (1-7 with 1=monday). Each of these patterns may contain a number in the range above; two numbers separated by a minus meaning a range inclusive; a list of numbers separated by commas meaning any of the numbers; or an asterisk meaning all legal values. The sixth field is a string that is executed by the Shell at the specified times. A percent character in this field is translated to a ne the symptom is best described as thrashing. .it Init will go into a .it fork/exec loop trying to create a Shell with proper standard input and output. .s3 If you cannot get the system to boot, a runnable system must be obtained from a backup medium. The root file system may then be doctored as a mounted file system as described below. If there are any problems with the root file system, it is probably prudent to go to a backup system to avoid working on a mounted file system. .s3 .it "Repairing disks.||" Ttered will cause the daemon to drop the call, wait up to 20 minutes and start over. This means that an improperly constructed \fIdf\fR file may cause the same job to be submitted every 20 minutes. .s3 While waiting, the daemon checks to see that the .it lock file still exists. If it is gone, the daemon will exit. .sh FILES /dev/dn0, /dev/dp0, /usr/dpd/* .sh "SEE ALSO" opr (I) w-line character. Only the first line (up to a % or end of line) of the command field is executed by the Shell. The other lines are made available to the command as standard input. .s2 Crontab is examined by .it cron every hour. Thus it could take up to an hour for entries to become effective. If it receives a hangup signal, however, the table is examined immediately; so `kill \-1 ...' can be used. .sh FILES /usr/lib/crontab .sh "SEE ALSO" init(VIII), sh(I), kill (I) .sh DIAGNOSTICS None \- illegal lines inhe first rule to keep in mind is that an addled disk should be treated gently; it shouldn't be mounted unless necessary, and if it is very valuable yet in quite bad shape, perhaps it should be dumped before trying surgery on it. This is an area where experience and informed courage count for much. .s3 The problems reported by .it icheck typically fall into two kinds. There can be problems with the free list: duplicates in the free list, or free blocks also in files. These can be cured easily with an .it "ic.th DF VIII 1/20/73 .sh NAME df \*- disk free .sh SYNOPSIS .bd df [ filesystem ] .sh DESCRIPTION .it Df prints out the number of free blocks available on a file system. If the file system is unspecified, the free space on all of the normally mounted file systems is printed. .sh FILES /dev/rf?, /dev/rk?, /dev/rp? .sh "SEE ALSO" icheck (VIII) .sh BUGS crontab are ignored. .sh BUGS A more efficient algorithm could be used. The overhead in running .it cron is about one percent of the machine, exclusive of any commands executed. heck \*-s." If the same block appears in more than one file or if a file contains bad blocks, the files should be deleted, and the free list reconstructed. The best way to delete such a file is to use .it clri (VIII), then remove its directory entries. If any of the affected files is really precious, you can try to copy it to another device first. .s3 .it Dcheck may report files which have more directory entries than links. Such situations are potentially dangerous; .it clri discusses a special case of the .th DCHECK VIII 2/8/75 .sh NAME dcheck \*- file system directory consistency check .sh SYNOPSIS .bd dcheck [ .bd \*-i numbers ] [ filesystem ] .sh DESCRIPTION .it Dcheck reads the directories in a file system and compares the link-count in each i-node with the number of directory entries by which it is referenced. If the file system is not specified, a set of default file systems is checked. .s3 The .bd \*-i flag is followed by a list of i-numbers; when one of those i-numbers turns up in a directory, the nuF258;>ADGHKNQTWZ]Iproblem. All the directory entries for the file should be removed. If on the other hand there are more links than directory entries, there is no danger of spreading infection, but merely some disk space that is lost for use. It is sufficient to copy the file (if it has any entries and is useful) then use .it clri on its inode and remove any directory entries that do exist. .s3 Finally, there may be inodes reported by .it dcheck that have 0 links and 0 entries. These occur on the root device when the system mber, the i-number of the directory, and the name of the entry are reported. .s3 The program is fastest if the raw version of the special file is used, since the i-list is read in large chunks. .sh FILES Currently, /dev/rrk2 and /dev/rrp0 are the default file systems. .sh DIAGNOSTICS When a file turns up for which the link-count and the number of directory entries disagree, the relevant facts are reported. Allocated files which have 0 link-count and no entries are also listed. The only dangerous situation o.th CRASH VIII 2/12/75 .tr | .sh NAME crash \*- what to do when the system crashes .sh DESCRIPTION This section gives at least a few clues about how to proceed if the system crashes. It can't pretend to be complete. .s3 .it "How to bring it back up.||" If the reason for the crash is not evident (see below for guidance on `evident') you may want to try to dump the system if you feel up to debugging. At the moment a dump can be taken only on magtape. With a tape mounted and ready, stop the machine, load addreis stopped with pipes open, and on other file systems when the system stops with files that have been deleted while still open. A .it clri will free the inode, and an .it "icheck -s" will recover any missing blocks. .s3 .it "Why did it crash?||" UNIX types a message on the console typewriter when it voluntarily crashes. Here is the current list of such messages, with enough information to provide a hope at least of the remedy. The message has the form `panic: ...', possibly accompanied by other information. Left unstated in all cases is the possibility that hardware or software error produced the message in some unexpected way. .s3 .lp +5 5 blkdev .br The .it getblk routine was called with a nonexistent major device as argument. Definitely hardware or software error. .s3 .lp +5 5 devtab .br Null device table entry for the major device used as argument to .it getblk. Definitely hardware or software error. .s3 .lp +5 5 iinit .br An I/O error reading the super-block for the root file system during initializationof system debugging is impossible here. .sh "SEE ALSO" clri, icheck, dcheck, boot procedures (VIII) .sh BUGS into location zero and executed there, it will type `=' on the console, read in a .it tp entry name, load that entry into core, and transfer to zero. Thus one way to run UNIX is to maintain the system code on a tape using .it tp. Caution: the file /usr/mdec/tboot (DECtape) or /usr/mdec/mboot (magtape) must be present when the tape is made! When a boot is required, execute (somehow) a program which reads in and jumps to the first block of the tape. In response to the `=' prompt, type the entry name of the s. .s3 .lp +5 5 out of inodes .br A mounted file system has no more i-nodes when creating a file. Sorry, the device isn't available; the .it icheck should tell you. .s3 .lp +5 5 no fs .br A device has disappeared from the mounted-device table. Definitely hardware or software error. .s3 .lp +5 5 no imt .br Like `no fs', but produced elsewhere. .s3 .lp +5 5 no inodes .br The in-core inode table is full. Try increasing NINODE in param.h. Shouldn't be a panic, just a user error. .s3 .lp +5 5 no clock .br During .th CLRI VIII 10/31/73 .sh NAME clri \*- clear i-node .sh SYNOPSIS .bd clri i-number [ filesystem ] .sh DESCRIPTION .it Clri writes zeros on the 32 bytes occupied by the i-node numbered .it i-number. If the .it "file system" argument is given, the i-node resides on the given device, otherwise on a default file system. The file system argument must be a special file name referring to a device containing a file system. After .it clri, any blocks in the affected file will show up as ``missing'' in an .it ichecystem on the tape (we use plain `unix'). It is strongly recommended that a current version of the system be maintained in this way, even if it is usually booted from disk. .s3 The standard DEC ROM which loads DECtape is sufficient to read in .it tboot, but the magtape ROM loads block one, not zero. If no suitable ROM is available, magtape and DECtape programs are presented below which may be manually placed in core and executed. .s3 The system can also be booted from a disk file with the aid of the .it ubooinitialization, neither the line nor programmable clock was found to exist. .s3 .lp +5 5 swap error .br An unrecoverable I/O error during a swap. Really shouldn't be a panic, but it is hard to fix. .s3 .lp +5 5 unlink \- iget .br The directory containing a file being deleted can't be found. Hardware or software. .s3 .lp +5 5 out of swap space .br A program needs to be swapped out, and there is no more swap space. It has to be increased. This really shouldn't be a panic, but there is no easy fix. .s3 .lp +5 k of of the file system. .s3 Read and write permission is required on the specified file system device. The i-node becomes allocatable. .s3 The primary purpose of this routine is to remove a file which for some reason appears in no directory. If it is used to zap an i-node which does appear in a directory, care should be taken to track down the entry and remove it. Otherwise, when the i-node is reallocated to some new file, the old entry will still point to that file. At that point removing the old entry wit program. When read into location 0 and executed, .it uboot reads a single character (either .bd p or .bd k for RP or RK, both drive 0) to specify which device is to be searched. Then it reads a UNIX pathname from the console, finds the corresponding file on the given device, loads that file into core location zero, and transfers to it. .it Uboot operates under very severe space constraints. It supplies no prompts, except that it echoes a carriage return and line feed after the .bd p or .bd k. No diagnosti5 out of text .br A pure procedure program is being executed, and the table for such things is full. This shouldn't be a panic. .s3 .lp +5 5 trap .br An unexpected trap has occurred within the system. This is accompanied by three numbers: a `ka6', which is the contents of the segmentation register for the area in which the system's stack is kept; `aps', which is the location where the hardware stored the program status word during the trap; and a `trap type' which encodes which trap occurred. The trap typesll destroy the new file. The new entry will again point to an unallocated i-node, so the whole cycle is likely to be repeated again and again. .sh BUGS Whatever the default file system is, it is likely to be wrong. Specify the file system explicitly. .s3 If the file is open, .it clri is likely to be ineffective. c is provided if the indicated file cannot be found, nor is there any means of correcting typographical errors in the file name except to start the program over. If it fails to find the file, however, it jumps back to its start, so another try can be attempted, starting again with the .bd p or .bd k. Notice that .it uboot will only load a file from drive 0, and the file system it searches must start at the beginning of the disk. .it Uboot itself usually resides in the otherwise unused block 0 of the disk, s are: .s3 .lp +10 5 0 bus error .lp +10 5 1 illegal instruction .lp +10 5 2 BPT/trace .lp +10 5 3 IOT .lp +10 5 4 power fail .lp +10 5 5 EMT .lp +10 5 6 recursive system call (TRAP instruction) .lp +10 5 7 11/70 cache parity, or programmed interrupt .lp +10 5 10 floating point trap .lp +10 5 11 segmentation violation .i0 .s3 In some of these cases it is possible for octal 20 to be added into the trap type; this indicates that the processor was in user mode when the trap occurred. If you wish to examine the .th CHOWN VIII 2/8/75 .sh NAME chown \*- change owner .sh SYNOPSIS .bd chown owner file ... .sh DESCRIPTION The user-ID of the files is changed to .it owner. The owner may be either a decimal UID or a login name found in the password file. .s3 Only the super-user is allowed to change the owner of a file, in order to simplify as yet unimplemented accounting procedures. .sh FILES /etc/passwd .sh "SEE ALSO" chgrp (VIII) .sh BUGS o it can be loaded by ROM program; .it mkfs can be used to put it there when the file system is created. It can also be loaded from a .it tp tape as described above. .s3 .it "The switches.||" The console switches play an important role in the use and especially the booting of UNIX. During operation, the console switches are examined 60 times per second, and the contents of the address specified by the switches are displayed in the display register. (This is not true on the 11/40 since there is no display restack after such a trap, either dump the system, or use the console switches to examine core; the required address mapping is described below. .s3 .it "Interpreting dumps.||" All file system problems should be taken care of before attempting to look at dumps. The dump should be read into the file .it /usr/sys/core; .it cp (I) will do. At this point, you should execute .it "ps \*-alxk" and .it who to print the process table and the users who were on at the time of the crash. You should dump ( .it od (I)) the.th CHGRP VIII 2/8/75 .sh NAME chgrp \*- change group .sh SYNOPSIS .bd chgrp group file ... .sh DESCRIPTION The group-ID of the files is changed to .it group. The group may be either a decimal GID or a group name found in the group-ID file. .s3 Only the super-user is allowed to change the group of a file, in order to simplify as yet unimplemented accounting procedures. .sh "SEE ALSO" chown (VIII) .sh FILES /etc/group .sh BUGS gister on that machine.) If the switch address is even, the address is interpreted in kernel (system) space; if odd, the rounded-down address is interpreted in the current user space. .s3 If any diagnostics are produced by the system, they are printed on the console only if the switches are non-zero. Thus it is wise to have a non-zero value in the switches at all times. .s3 During the startup of the system, the .it init program (VIII) reads the switches and will come up single-user if the switches are set t first 30 bytes of .it /usr/sys/core. Starting at location 4, the registers R0, R1, R2, R3, R4, R5, SP and KDSA6 (KISA6 for 11/40s) are stored. If the dump had to be restarted, R0 will not be correct. Next, take the value of KA6 (location 22(8) in the dump) multiplied by 100(8) and dump 1000(8) bytes starting from there. This is the per-process data associated with the process running at the time of the crash. Relabel the addresses 140000 to 141776. R5 is C's frame or display pointer. Stored at (R5) is the ^JMPSVY\_`cfio 173030. .s3 It is unwise to have a non-existent address in the switches. This causes a bus error in the system (displayed as 177777) at the rate of 60 times per second. If there is a transfer of more than 16ms duration on a device with a data rate faster than the bus error timeout (about 10\*us) then a permanent disk non-existent-memory error will occur. .s3 .it "ROM programs.||" Here are some programs which are suitable for installing in read-only memories, or for manual keying into core if no ROM is preold R5 pointing to the previous stack frame. At (R5)+2 is the saved PC of the calling procedure. Trace this calling chain until you obtain an R5 value of 141756, which is where the user's R5 is stored. If the chain is broken, you have to look for a plausible R5, PC pair and continue from there. Each PC should be looked up in the system's name list using .it db (I) and its `:' command, to get a reverse calling order. In most cases this procedure will give an idea of what is wrong. A more complete discussion .tr | .th "BOOT PROCEDURES" VIII 2/11/75 .sh NAME boot procedures \*- UNIX startup .sh DESCRIPTION .it "How to start UNIX.||" UNIX is started by placing it in core at location zero and transferring to zero. Since the system is not reenterable, it is necessary to read it in from disk or tape. .s3 The .it tp command places a bootstrap program on the otherwise unused block zero of the tape. The DECtape version of this program is called .it tboot, the magtape version .it mboot. If .it tboot or .it mboot is readsent. Each program is position-independent but should be placed well above location 0 so it will not be overwritten. Each reads a block from the beginning of a device into core location zero. The octal words constituting the program are listed on the left. .s3 .ne 5 .nf DECtape (drive 0) from endzone: .if n .ta 3 11 15 23 38 .if t .ta .3i 1i 1.4i 2i 3.5i 012700 mov $tcba,r0 177346 010040 mov r0,\*-(r0) / use tc addr for wc 012710 mov $3,(r0) / read bn forward 000003 105710 1: tstb (r0) / wait for ready 002376 bge 1b 112710 movb $5,(r0) / read (forward) 000005 000777 br \fB.\fR / loop; now halt and start at 0 .s3 DECtape (drive 0) with search: 012700 1: mov $tcba,r0 177346 010040 mov r0,\*-(r0) / use tc addr for wc 012740 mov $4003,\*-(r0) / read bn reverse 004003 005710 2: tst (r0) 002376 bge 2b / wait for error 005760 tst \*-2(r0) / loop if not end zone 177776 002365 bge 1b 012710 mov $3,(r0) / read bn forward 000003 105710 2: tstb (r0) / wait for ready 002376 bge 2b .th SALLOC VII 6/15/72 .sh NAME salloc \*- string allocation and manipulation .sh SYNOPSIS .nf (get size in r0) .bd "jsr pc,allocate" (header address in r1) .s3 (get source header address in r0, destination header address in r1) .bd "jsr pc,copy" .s3 .bd "jsr pc,wc" .s3 (all following routines assume r1 contains header address) .s3 .bd "jsr pc,release" .s3 (get character in r0) .bd "jsr pc,putchar" .s3 .bd "jsr pc,lookchar" (character in r0) .s3 .bd "jsr pc,getchar" (character in r0) .s3 (get character in rine called with bad header pointer. .br `cannot open output file' \*- temp file .it alloc.d cannot be created or opened. .br `out of space' \*- no sufficiently large block or no header is available for a new or growing block. .sh BUGS 112710 movb $5,(r0) / read (forward) 000005 105710 2: tstb (r0) / wait for ready 002376 bge 2b 005007 clr pc / transfer to zero .s3 .fi Caution: both of these DECtape programs will (literally) blow a fuse if 2 drives are dialed to zero. .s3 .nf Magtape from load point: 012700 mov $mtcma,r0 172526 010040 mov r0,\*-(r0) / usr mt addr for wc 012740 mov $60003,\*-(r0) / read 9\*-track 060003 000777 br \fB.\fR / loop; now halt and start at 0 .s3 RK (drive 0): 012700 mov $rkda,r0 177412 00500) .bd "jsr pc,alterchar" .s3 (get position in r0) .bd "jsr pc,seekchar" .s3 .bd "jsr pc,backspace" (character in r0) .s3 (get word in r0) .bd "jsr pc,putword" .s3 .bd "jsr pc,lookword" (word in r0) .s3 .bd "jsr pc,getword" (word in r0) .s3 (get word in r0) .bd "jsr pc,alterword" .s3 .bd "jsr pc,backword" (word in r0) .s3 .bd "jsr pc,length" (length in r0) .s3 .bd "jsr pc,position" (position in r0) .s3 .bd "jsr pc,rewind" .s3 .bd "jsr pc,create" .s3 .bd "jsr pc,fsfile" .s3 .bd "jsr pc,zero" .fi .sh DESCRIPT.th PLOT VII 2/25/75 .sh NAME plot: openpl et al. \*- graphics interface .sh SYNOPSIS .nf .ft B openpl( ) .s3 erase( ) .s3 label(s) char s[ ]; .s3 line(x1, y1, x2, y2) .s3 circle(x, y, r) .s3 arc(x, y, x0, y0, x1, y1) .s3 dot(x, y, dx, n, pattern) int pattern[ ]; .s3 move(x, y) .s3 point(x, y) .s3 linemod(s) char s[ ]; .s3 space(x0, y0, x1, y1) .s3 closepl( ) .fi .s3 .ft R .sh DESCRIPTION These subroutines generate graphic output in a relatively device-independent manner. See .it plot (VI) for a description40 clr \*-(r0) / rkda cleared by start 010040 mov r0,\*-(r0) 012740 mov $5,\*-(r0) 000005 105710 1: tstb (r0) 002376 bge 1b 005007 clr pc .s3 .ne 11 RP (drive 0) 012700 mov $rpmr,r0 176726 005040 clr \*-(r0) 005040 clr \*-(r0) 005040 clr \*-(r0) 010040 mov r0,\*-(r0) 012740 mov $5,\*-(r0) 000005 105710 1: tstb (r0) 002376 bge 1b 005007 clr pc .dt .sh FILES /unix \*- UNIX code .br /usr/mdec/mboot \*- \fItp\fR magtape bootstrap .br /usr/mdec/tboot \*- \fItp\fR DECtape bootstrap .ION This package is a complete set of routines for dealing with almost arbitrary length strings of words and bytes. It lives in .it /lib/libs.a. The strings are stored on a disk file, so the sum of their lengths can be considerably larger than the available core. A small buffer cache makes for reasonable speed. .s3 For each string there is a header of four words, namely a write pointer, a read pointer and pointers to the beginning and end of the block containing the string. Initially the read and write poin of the meaning of the subroutines. .s3 There are four libraries containing these routines, one that produces general graphics commands on the standard output, and one each for the vt0 storage scope, the Diablo plotting terminal and the Tektronix 4014 terminal. .it Openpl must be used before any of the others to open the device for writing. .it Closepl flushes the output. .sh FILES /usr/lib/plot.a produces output for plotting filters .br /usr/lib/vt0.a produces output on vt0 storage scope .br /usr/lib/gsip.br /usr/mdec/uboot \*- file system bootstrap .sh "SEE ALSO" tp (I), init (VIII) ters point to the beginning of the string. All routines that refer to a string require the header address in r1. Unless the string is destroyed by the call, upon return r1 will point to the same string, although the string may have grown to the extent that it had to be be moved. .s3 .it Allocate obtains a string of the requested size and returns a pointer to its header in r1. .s3 .it Release releases a string back to free storage. .s3 .it Putchar and .it putword write a byte or word respectively into the sta produces output on Diablo terminal .br /usr/lib/tek.a produces output for the Tektronix 4014 terminal .sh "SEE ALSO" plot (VI), graph (VI) .sh BUGS .th AC VIII 2/20/74 .sh NAME ac \*- login accounting .sh SYNOPSIS .bd ac [ .bd \*-w wtmp ] [ .bd \*-p ] [ .bd \*-d ] people .sh DESCRIPTION .it Ac produces a printout giving connect time for each user who has logged in during the life of the current .it wtmp file. A total is also produced. .bd \*-w is used to specify an alternate \fIwtmp\fR file. .bd \*-p prints individual totals; without this option, only totals are printed. .bd \*-d causes a printout for each midnight to midnight period. Any .it people wiring and advance the write pointer. .s3 .it Lookchar and .it lookword read a byte or word respectively from the string but do not advance the read pointer. .s3 .it Getchar and .it getword read a byte or word respectively from the string and advance the read pointer. .s3 .it Alterchar and .it alterword write a byte or word respectively into the string where the read pointer is pointing and advance the read pointer. .s3 .it Backspace and .it backword read the last byte or word written and decrement the write qtwx{~ll limit the printout to only the specified login names. If no \fIwtmp\fR file is given, .it /usr/adm/wtmp is used. .s3 The accounting file .it /usr/adm/wtmp is maintained by .it init and .it login. Neither of these programs creates the file, so if it does not exist no connect-time accounting is done. To start accounting, it should be created with length 0. On the other hand if the file is left undisturbed it will grow without bound, so periodically any information desired should be collected and the file tpointer. .s3 All write operations will automatically get a larger block if the current block is exceeded. All read operations return with the error bit set if attempting to read beyond the write pointer. .s3 .it Seekchar moves the read pointer to the offset specified in r0. .s3 .it Length returns the current length of the string (beginning pointer to write pointer) in r0. .s3 .it Position returns the current offset of the read pointer in r0. .s3 .it Rewind moves the read pointer to the beginning of the stri.hc % .th MS VII 11/6/74 .sh NAME ms \*- macros for formatting manuscripts .sh SYNOPSIS .bd "nroff \*-ms" [ options ] file ... .br .bd "troff \*-ms" [ options ] file ... .sh DESCRIPTION This package of .it nroff and .it troff macro definitions provides a canned formatting .li facility for tech%nical papers. When producing 2-column output on a terminal, its output should be filtered through .it col (I). .s3 The package supports three different formats: BTL technical memorandum with cover sheet, released pruncated. .sh FILES /usr/adm/wtmp .sh "SEE ALSO" init (VIII), login (I), wtmp (V). .sh BUGS ng. .s3 .it Create returns the read and write pointers to the beginning of the string. .s3 .it Fsfile moves the read pointer to the current position of the write pointer. .s3 .it Zero zeros the whole string and sets the write pointer to the beginning of the string. .s3 .it Copy copies the string whose header pointer is in r0 to the string whose header pointer is in r1. Care should be taken in using the copy instruction since r1 will be changed if the contents of the source string is bigger than the destinataper with cover sheet, and an abbreviated `debugging' form without cover sheet. .s3 The macro requests are defined in the attached Request Reference. Many .it nroff and .it troff requests are unsafe in conjunction with this package, however the requests listed below may be used with impunity after the first .PP. .s3 .lp +8 0 .ta 5n .nf .li .bp begin new page .li .br break output line here .li .sp n insert n spacing lines .li .ls n (line spacing) n=1 single, n=2 double space .li .na no alignment of right maradgjmpsvbion string. .s3 .it Wc forces the contents of the internal buffers and the header blocks to be written on disc. .s3 An in-core version of this allocator exists in .it dc (I), and a permanent-file version exists in .it form and .it fed (VI). .sh FILES .if t .ta 1i .if n .ta 13 /lib/libs.a library, accessed by .it "ld ... -ls" .br alloc.d temporary file for string storage .sh "SEE ALSO" alloc (III) .sh DIAGNOSTICS `error in copy' \*- disk write error encountered in .it copy. .br `error in allocator' \*- routgin .fi .i0 .s3 Output of the .it eqn, .it neqn and .it tbl (I) preprocessors for equations and tables is acceptable as input. .sh FILES /usr/lib/tmac.s .sh "SEE ALSO" eqn (I), nroff (I), troff (I), tbl (VI) .sh BUGS .bp .in0 .tr &. .in0 .ce REQUEST REFERENCE .if t .ta .75i 1.5i 2i .if n .ta 10 18 24 .if t .in 2i .if n .in 23 .if n .na .s3 .ti0 Request Initial Cause .ti0 Form Value Break Explanation .ps 9 .vs 11p .s3 .ti0 .li .1C yes yes One column format on a new page. .ti0 .li .2C no yes Two column format. .ti0 .li .AB no yes Begin abstract. .ti0 .li .AE - yes End abstract. .ti0 .li .AI no yes Author's institution follows. Suppressed in TM. .ti0 .li .AU \fIx y\fR no yes Author's name follows. \fIx\fR is location and \fIy\fR is extension, ignored except in TM. .ti0 .li .B no no Boldface text follows. .ti0 .li .CS \fIx...\fR - yes Cover sheet info if TM format, suppressed otherwise. Arguments are number of text pages, other pages, total pages, figures, tables, references. .ti0 .li .DA \fIx\fR nroff no `Date lse functions are named by analogy to .it "fork, exit, read, write" (II). They establish and synchronize `coroutines', which behave in many respects like a set of processes working in the same address space. The functions live in .it /usr/lib/cr.a. .s3 Coroutines are placed on queues to indicate their state of readiness. One coroutine is always distinguished as `running'. Coroutines that are runnable but not running are registered on a `ready queue'. The head member of the ready queue is started whenever no expressions and arguments of further calls, regardless of actual need. There is no checking for stack overflow. .br Under /usr/lib/scr.a stack overflow checking is not rigorous. ine' at bottom of page is \fIx\fR. Default is today. .ti0 .li .DE - yes End displayed text. Implies .KE. .ti0 .li .DS \fIx\fR no yes Start of displayed text, to appear verbatim line-by-line. \fIx\fR=I for indented display (default), \fIx\fR=L for left-justified on the page, \fIx\fR=C for centered. Implies .KS. .ti0 .li .EN - yes Space after equation produced by .it eqn or .it neqn. .ti0 .li .EQ \fIx\fR - yes Space before equation. Equation number is \fIx\fR. .ti0 .li .FE - yes End footnote. .ti0 .li .FS no other coroutine is specifically caused to be running. .s3 Each connector heads two queues: .it Connector[0] is the queue of unsatisfied .it crreads outstanding on the connector. .it Connector[1] is the queue of .it crwrites. All queues must start empty, .it i.e. with heads set to zero. .s3 .it Crfork is normally called with no arguments. It places the running coroutine at the head of the ready queue, creates a new coroutine, and starts the new one running. .it Crfork returns immediately in the new corout.th WUMP VI 11/25/73 .sh NAME wump \*- the game of hunt-the-wumpus .sh SYNOPSIS .bd /usr/games/wump .sh DESCRIPTION .it Wump plays the game of ``Hunt the Wumpus.'' A Wumpus is a creature that lives in a cave with several rooms connected by tunnels. You wander among the rooms, trying to shoot the Wumpus with an arrow, meanwhile avoiding being eaten by the Wumpus and falling into Bottomless Pits. There are also Super Bats which are likely to pick you up and drop you in some random room. .s3 The program asks vno Start footnote. The note will be moved to the bottom of the page. .ti0 .li .HO - no `Bell Laboratories, Holmdel, New Jersey 07733'. .ti0 .li .I no no Italic text follows. .ti0 .li .IP \fIx y\fR no yes Start indented paragraph, with hanging tag \fIx\fR. Indentation is \fIy\fR ens (default 5). .ti0 .li .KE - yes End keep. Put kept text on next page if not enough room. .ti0 .li .KF no yes Start floating keep. If the kept text must be moved to the next page, float later text back to this page. .ti0 .li .KS nine with value 0, and upon restarting of the old coroutine with value 1. .s3 .it Crexit stops the running coroutine and does not place it in any queue. .s3 .it Crread copies characters from the .it buffer of the .it crwrite at the head of the .it connector's write queue to the .it buffer of .it crread. If the write queue is empty, copying is delayed and the running coroutine is placed on the read queue. The number of characters copied is the minimum of .it nbytes and the number of characters remaining inarious questions which you answer one per line; it will give a more detailed description if you want. .s3 This program is based on one described in .it "People's Computer Company," .it 2, 2 (November 1973). .sh BUGS It will never replace Space War. o yes Start keeping following text. .ti0 .li .LG no no Make letters larger. .ti0 .li .LP yes yes Start left-blocked paragraph. .ti0 .li .MH - no `Bell Laboratories, Murray Hill, New Jersey 07974'. .ti0 .li .ND troff no No date line at bottom of page. .ti0 .li .NH \fIn\fR - yes Same as .SH, with section number supplied automatically. Numbers are multilevel, like 1.2.3, where \fIn\fR tells what level is wanted (default is 1). .ti0 .li .NL yes no Make letters normal size. .ti0 .li .OK - yes `Other keywords' fo the write .it buffer, and is returned as the value of .it crread. After copying, the location of the write .it buffer and the corresponding .it nbytes are updated appropriately. If zero characters remain, the coroutine of the .it crwrite is moved to the head of the ready queue. If the write queue remains nonempty, the head member of the read queue is moved to the head of the ready queue. .s3 .it Crwrite queues the running coroutine on the .it connector's write queue, and records the fact that .it nbytes (z.if n .ds / / .if t .ds / \z/\h'\w'*'u' .th UNITS VI 8/30/74 .sh NAME units \*- conversion program .sh SYNOPSIS .it Units converts quantities expressed in various standard scales to their equivalents in other scales. It works interactively in this fashion: .s3 .it " You have:" inch .br .it " You want:" cm .br .it " * 2.54000e+00 .br .it " \*/ 3.93701e\-01 .s3 A quantity is specified as a multiplicative combination of units optionally preceded by a numeric multiplier. Powers are indicated by suffixed positr TM cover sheet follow. .ti0 .li .PP no yes Begin paragraph. First line indented. .ti0 .li .R yes no Roman text follows. .ti0 .li .RE - yes End relative indent level. .ti0 .li .RP no - Cover sheet and first page for released paper. Must precede other requests. .ti0 .li .RS - yes Start level of relative indentation. Following .IP's measured from current indentation. .ti0 .li .SG \fIx\fR no yes Insert signature(s) of author(s), ignored except in TM. \fIx\fR is the reference line (initials of author and typisero or more) characters in the string .it buffer are available to .it crreads. If the read queue is not empty, its head member is started running. .s3 .it Crexch exchanges the read queues of connectors .it conn1 and .it conn2 if \fIi\fR=0; and it exchanges the write queues if \fIi\fR=1. If a nonempty read queue that had been paired with an empty write queue becomes paired with a nonempty write queue, .it crexch moves the head member of that read queue to the head of the ready queue. .s3 .it Crprior sets a ive integers, division by the usual sign: .s3 .it " You have:" 15 pounds force/in2 .br .it " You want:" atm .br .it " * 1.02069e+00" .br .it " \*/ 9.79730e\-01" .s3 .it Units only does multiplicative scale changes. Thus it can convert Kelvin to Rankine, but not Centigrade to Fahrenheit. Most familiar units, abbreviations, and metric prefixes are recognized, together with a generous leavening of exotica and a few constants of nature including: .s3 .nf pi ratio of circumference to diameter c speed of ligt). .ti0 .li .SH - yes Section head follows, font automatically bold. .ti0 .li .SM no no Make letters smaller. .ti0 .li .TL no yes Title follows. .ti0 .li .TM \fIx y z\fR no - BTL TM cover sheet and first page, \fIx\fR=TM number, \fIy\fR=(quoted list of) case number(s), \fIz\fR=file number. Must precede other requests. .ti0 .li .WH - no `Bell Laboratories, Whippany, New Jersey 07981'. priority on the running coroutine to control the queuing of .it crreads and .it crwrites. When queued, the running coroutine will take its place before coroutines whose priorities exceed its own priority and after others. Priorities are compared as logical, .it i.e. unsigned, quantities. Initially each coroutine's priority is set as large as possible, so default queuing is .nh FIFO. .hy .s3 .bd "Storage allocation." The old and new coroutine share the same activation record in the function that invoked .itht e charge on an electron g acceleration of gravity force same as g mole Avogadro's number water pressure head per unit height of water au astronomical unit .s3 .fi `Pound' is a unit of mass. Compound names are run together, e.g. `lightyear'. British units that differ from their US counterparts are prefixed thus: `brgallon'. For a complete list of units, `cat /usr/lib/units'. .sh FILES /usr/lib/units .sh BUGS y|z crfork, so only one may return from the invoking function, and then only when the other has completed execution in that function. .s3 The activation record for each function execution is dynamically allocated rather than stacked; a factor of 3 in running time overhead can result if function calls are very frequent. The overhead may be overcome by providing a separate stack for each coroutine and dispensing with dynamic allocation. The base (lowest) address and size of the new coroutine's stack are supplied.th TTT VI 11/1/73 .sh NAME ttt \*- the game of tic-tac-toe .sh SYNOPSIS .bd /usr/games/ttt .sh DESCRIPTION .it Ttt is the X and O game popular in the first grade. This is a learning program that never makes the same mistake twice. .s3 Although it learns, it learns slowly. It must lose nearly 80 games to completely know the game. .sh FILES /usr/games/ttt.k learning file .sh BUGS .th CR VII 1/4/75 .sh NAME crfork, crexit, crread, crwrite, crexch, crprior \*- coroutine scheme .sh SYNOPSIS .nf .ft B int crfork( \fR[\fB stack, nwords \fR]\fB ) int stack[]; int nwords; .s3 crexit() .s3 int crread(connector, buffer, nbytes) int *connector[2]; char *buffer; int nbytes; .s3 crwrite(connector, buffer, nbytes) int *connector[2]; char *buffer; int nbytes; .s3 crexch(conn1, conn2, i) int *conn1[2], *conn2[2]; int i; .s3 #define logical char * crprior(p) logical p; .fi .ft R .sh DESCRIPTION The to .it crfork as optional arguments .it stack and .it nwords. Stacked allocation and dynamic allocation cannot be mixed in one run. For stacked operation, obtain the coroutine functions from .it /usr/lib/scr.a instead of .it /usr/lib/cr.a. .sh FILES /usr/lib/cr.a .br /usr/lib/scr.a .sh DIAGNOSTICS `rsave doesn't work' \*- an old C compilation has called `rsave'. It must be recompiled to work with the coroutine scheme. .sh BUGS Under /usr/lib/cr.a each function has just 12 words of anonymous stack for hard ...as.th TMG VI 10/21/72 .sh NAME tmg \*- compiler-compiler .sh SYNOPSIS .bd tmg name .sh DESCRIPTION .it Tmg produces a translator for the language whose parsing and translation rules are described in file \fIname\fB.t\fR. The new translator appears in a.out and may be used thus: .s3 .bd a.out input [ output ] .s3 Except in rare cases input must be a randomly addressable file. If no output file is specified, the standard output file is assumed. .sh FILES .nf \fIname\fB.s\fR: assembly language version of \fInamegether. .pg The output of the assembler is placed on the file \fIa.out\fR in the current directory. If there were no unresolved external ref%er%ences, and no errors detected, \fIa.out\fP is made executable; otherwise, if it is produced at all, it is made non-executable. .ul 2. Lexical conventions .et Assembler tokens include identifiers (alternatively, ``symbols'' or ``names''), temporary symbols, constants, and operators. .ms 2.1 Identifiers .pg An identifier consists of a sequence of alphanumeric charace, the data segment begins at the lowest 8K byte boundary after the text segment. .pg The bss segment may not contain any explicitly initialized code or data. The length of the bss segment (like that of text or data) is determined by the high-water mark of the location counter within it. The bss segment is actually an extension of the data segment and begins immediately after it. At the start of execution of a program, the bss segment is set to 0. Typically the bss segment is set up by state%ments exemplifi\fB.t\fR /usr/lib/tmg: the compiler-compiler /usr/lib/tmg[abc], /lib/libs.a: libraries alloc.d: scratch file for table storage .fi .sh "SEE ALSO" A Manual for the Tmg Compiler-writing Language, internal memorandum. .sh DIAGNOSTICS Syntactic errors result in "???" followed by the offending line. .br Situations such as space overflow with which the Tmg processor or a Tmg-produced processor can not cope result in a descriptive comment and a dump. .sh AUTHOR M. D. McIlroy .sh BUGS Footnote 1 of Section 9.2 of ters (including period ``\|\fB.\fR\|'', underscore ``\(ul'', and tilde ``~'' as alphanumeric) of which the first may not be numeric. Only the first eight characters are significant. When a name begins with a tilde, the tilde is discarded and that occurrence of the identifier generates a unique entry in the symbol table which can match no other occurrence of the identifier. This feature is used by the C compiler to place names of local variables in the output symbol table without having to worry about makined by .sp lab\fB: .\fR = \fB.\fR+10 .sp The advantage in using the bss segment for storage that starts off empty is that the initialization information need not be stored in the output file. See also \fILocation counter\fP and \fIAssignment state%ments\fP below. .ul 4. The location counter .et One special symbol, ``\|\fB.\fP\|'', is the location counter. Its value at any time is the offset within the appropriate segment of the start of the state%ment in which it appears. The location counter may be assignTmg Manual is not enforced, causing trouble. .br Restrictions (7.) against mixing bundling primitives should be lifted. .br Certain hidden reserved words exist: gpar, classtab, trans, goto, alt, salt. .br Octal digits include 8=10 and 9=11. g them unique. .ms 2.2 Temporary symbols .pg A temporary symbol consists of a digit followed by ``f\|'' or ``b''. Temporary symbols are discussed fully in \(sc5.1. .ms 2.3 Constants .pg An octal constant consists of a sequence of digits; ``8'' and ``9'' are taken to have octal value 10 and 11. The constant is truncated to 16 bits and interpreted in two's complement notation. .pg A decimal constant consists of a sequence of digits terminated by a decimal point ``\fB.\fR''. The magnitude of the constant shed to, with the restriction that the current segment may not change; furthermore, the value of ``\|\fB.\fP\|'' may not decrease. If the effect of the assignment is to increase the value of ``\|\fB.\fP\|'', the required number of null bytes are generated (but see \fISegments\fP above). .ul 5. Statements .et A source program is composed of a sequence of \fIstate%ments\fP. Statements are separated either by new-lines or by semicolons. There are five kinds of state%ments: null state%ments, expression state%menould be representable in 15 bits; i.e., be less than 32,768. .pg A single-character constant consists of a single quote ``\|\(fm\|'' followed by an \s8ASCII\s10 character not a new-line. Certain dual-character escape sequences are acceptable in place of the \s8ASCII\s10 character to represent new-line and other non-graphics (see \fIString state%ments\fP, \(sc5.5). The constant's value has the code for the given character in the least significant byte of the word and is null-padded on the left. .pg A double-ts, assignment state%ments, string state%ments, and keyword state%ments. .pg Any kind of state%ment may be preceded by one or more labels. .ms 5.1 Labels .pg There are two kinds of label: name labels and numeric labels. A name label consists of a name followed by a colon (\|:\|). The effect of a name label is to assign the current value and type of the location counter ``\|\fB.\fP\|'' to the name. An error is indicated in pass 1 if the name is already defined; an error is indicated in pass 2 if the ``\|\fB.pl 11i .hc % .ll 6.5i .ps 16 .vs 18p .sp 1.5i .ce UNIX Assembler Reference Manual .sp 1.5 .ft I .ps 12 .ce Dennis M. Ritchie .ce 2 .sp .5 Bell Laboratories Murray Hill, New Jersey .sp 2 .ps 10 .vs 11p .ft R .de pg .sp .5 .. .de et .ft .pg .. .de ms .ne 3 .sp .. .de ul .ne 4 .sp .ft B .. .de fo 'bp .. .de he 'tl '-''' 'sp 0.5i .ft I .if o .tl '''Assembler Manual - %' .if e .tl 'Assembler Manual - %''' .ft 'sp 0.4i .ns .. .wh -1i fo .wh 0 he .ul 0. Introduction .et This document describes the usage and inpucharacter constant consists of a double quote ``\|"\|'' followed by a pair of \s8ASCII\s10 characters not including new-line. Certain dual-character escape sequences are acceptable in place of either of the \s8ASCII\s10 characters to represent new-line and other non-graphics (see \fIString state%ments\fR, \(sc5.5). The constant's value has the code for the first given character in the least significant byte and that for the second character in the most significant byte. .ms 2.4 Operators .pg There are seve.\fP\|'' value assigned changes the definition of the label. .pg A numeric label consists of a digit \fI0\fR to \fI9\fR followed by a colon (\|:\|). Such a label serves to define temporary symbols of the form ``\fIn\fR\|b'' and ``\fIn\fR\|f\|'', where \fIn\fR is the digit of the label. As in the case of name labels, a numeric label assigns the current value and type of ``\|\fB.\fP\|'' to the temporary symbol. However, several numeric labels with the same digit may be used within the same assembly. Ref%er%ent syntax of the \s8UNIX PDP\s10-11 assembler \fIas\fP. The details of the \s8PDP\s10-11 are not described; consult the \s8DEC\s10 documents ``\s8PDP\s10-11/20 Handbook'' and ``\s8PDP\s10-11/45 Handbook.'' .pg The input syntax of the \s8UNIX\s10 assembler is generally similar to that of the \s8DEC\s10 assembler \s8PAL\s10-11\s8R\s10, although its internal workings and output format are unrelated. It may be useful to read the publication \s8DEC\s10-11-\s8ASDB\s10-\s8D\s10, which describes \s8PAL\s10-11\s8R\ral single- and double-character operators; see \(sc6. .ms 2.5 Blanks .pg Blank and tab characters may be interspersed freely between tokens, but may not be used within tokens (except character constants). A blank or tab is required to separate adjacent identifiers or constants not otherwise separated. .ms 2.6 Comments .pg The character ``\|/\|'' introduces a comment, which extends through the end of the line on which it appears. Comments are ignored by the assembler. .ul 3. Segments .et Assembled code aces of the form ``\fIn\fR\|f\|'' refer to the first numeric label ``\fIn\|\fR:'' \fIf\fR\|orward from the ref%er%ence; ``\fIn\fRb'' symbols refer to the first ``\fIn\fR\|:'' label \fIb\fRackward from the ref%er%ence. This sort of temporary label was introduced by Knuth [\fIThe Art of Computer Programming, Vol I: Fundamental Algorithms\|\fR]. Such labels tend to conserve both the symbol table space of the assembler and the inventive powers of the programmer. .ms 5.2 Null state%ments .pg A null state%ment iss10, although naturally one must use care in assuming that its rules apply to \fIas\fP. .pg \fIAs\fP is a rather ordinary two-pass assembler without macro capabilities. It produces an output file which contains relocation information and a complete symbol table; thus the output is acceptable to the \s8UNIX\s10 link-editor \fIld\fP, which may be used to combine the outputs of several assembler runs and to obtain object programs from libraries. The output format has been designed so that if a program containsnd data fall into three segments: the text segment, the data segment, and the bss segment. The text segment is the one in which the assembler begins, and it is the one into which instructions are typically placed. The \s8UNIX\s10 system will, if desired, enforce the purity of the text segment of programs by trapping write operations into it. Object programs produced by the assembler must be processed by the link-editor \fIld\fR (using its ``_n'' flag) if the text segment is to be write-protected. A single c an empty state%ment (which may, however, have labels). A null state%ment is ignored by the assembler. Common examples of null state%ments are empty lines or lines containing only a label. .ms 5.3 Expression state%ments .pg An expression state%ment consists of an arithmetic expression not beginning with a keyword. The assembler computes its (16-bit) value and places it in the output stream, together with the appropriate relocation bits. .ms 5.4 Assignment state%ments .pg An assignment state%ment consists no unresolved ref%er%ences to external symbols, it is executable without further processing. .ul 1. Usage .et \fIas\fP is used as follows: .sp .ft B as \fR[\fB _ \fR] \fIfile\s6\d1\u\s10 .\|.\|. .sp .ft R If the optional ``_'' argument is given, all undefined symbols in the current assembly will be made undefined-external. See the \fB.globl\fR directive below. .pg The other arguments name files which are concatenated and assembled. Thus programs may be written in several pieces and assembled toopy of the text segment is shared among all processes executing such a program. .pg The data segment is available for placing data or instructions which will be modified during execution. Anything which may go in the text segment may be put into the data segment. In programs with write-protected, sharable text segments, data segment contains the initialized but variable parts of a program. If the text segment is not pure, the data segment begins immediately after the text segment; if the text segment is purof an identifier, an equals sign (\|=\|), and an expression. The value and type of the expression are assigned to the identifier. It is not required that the type or value be the same in pass 2 as in pass 1, nor is it an error to redefine any symbol by assignment. .pg Any external attribute of the expression is lost across an assignment. This means that it is not possible to declare a global symbol by assigning to it, and that it is impossible to define a symbol to be offset from a non-locally defined global symbol. .pg As mentioned, it is permissible to assign to the location counter ``\|\fB.\fP\|''. It is required, however, that the type of the expression assigned be of the same type as ``\|\fB.\fP\|'', and it is forbidden to decrease the value of ``\fB\|.\|\fR''. In practice, the most common assignment to ``\|\fB.\fP\|'' has the form ``.\|=\|.\|+\|\fIn\fR'' for some number \fIn;\fR this has the effect of generating \fIn\fR null bytes. .ms 5.5 String state%ments .pg A string state%ment generates a sequencected by any possible future applications of the link-editor to the output file. .pg .ti 3 text .br The value of a text symbol is measured with respect to the beginning of the text segment of the program. If the assembler output is link-edited, its text symbols may change in value since the program need not be the first in the link editor's output. Most text symbols are defined by appearing as labels. At the start of an assembly, the value of ``\|\fB.\fP\|'' is text 0. .pg .ti 3 data .br The value of a data apply these operators to any but absolute symbols. .in 0 .ul 7. Pseudo-operations .et The keywords listed below introduce state%ments which generate data in unusual forms or influence the later operations of the assembler. The metanotation .pg [ stuff ] .\|.\|. .pg means that 0 or more instances of the given stuff may appear. Also, boldface tokens are literals, italic words are substitutable. .ms 7.1 \fB.byte \fIexpression \fR[ \fB, \fIexpression \fR] .\|.\|. .pg The \fIexpression\fRs in the comma-s of bytes containing \s8ASCII\s10 characters. A string state%ment consists of a left string quote ``<'' followed by a sequence of \s8ASCII\s10 characters not including newline, followed by a right string quote ``>''. Any of the \s8ASCII\s10 characters may be replaced by a two-character escape sequence to represent certain non-graphic characters, as follows: .sp .ta .5i 1.5i 2.0i .ne 9 .nf \\n \s8NL\s10 (012) \\t \s8HT\s10 (011) \\e \s8EOT\s10 (004) \\0 \s8NUL\s10 (000) \\r \s8CR\s10 (015) \\a \s8ACK\ssymbol is measured with respect to the origin of the data segment of a program. Like text symbols, the value of a data symbol may change during a subsequent link-editor run since previously loaded programs may have data segments. After the first \fB.data\fR state%ment, the value of ``\|\fB.\fP\|'' is data 0. .pg .ti 3 bss .br The value of a bss symbol is measured from the beginning of the bss segment of a program. Like text and data symbols, the value of a bss symbol may change during a subsequent link-editeparated list are truncated to 8 bits and assembled in successive bytes. The expressions must be absolute. This state%ment and the string state%ment above are the only ones which assemble data one byte at at time. .ms 7.2 \fB.even\fR .pg If the location counter ``\|\fB.\fP\|'' is odd, it is advanced by one so the next state%ment will be assembled at a word boundary. .ms 7.3 \fB.if \fIexpression\fR .pg The \fIexpression\fR must be absolute and defined in pass 1. If its value is nonzero, the \fB.if\fR is i10 (006) \\p \s8PFX\s10 (033) \\\\ \\ \\> > .sp .fi .in 0 The last two are included so that the escape character and the right string quote may be represented. The same escape sequences may also be used within single- and double-character constants (see \(sc2.3 above). .ms 5.6 Keyword state%ments .pg Keyword state%ments are numerically the most common type, since most machine instructions are of this sort. A keyword state%ment begins with one of the many predefined keywords of the assembler; the syntax or run, since previously loaded programs may have bss segments. After the first \fB.bss\fR state%ment, the value of ``\|\fB.\fP\|'' is bss 0. .pg .ti 3 external absolute, text, data, or bss .br symbols declared \fB.globl\fR but defined within an assembly as absolute, text, data, or bss symbols may be used exactly as if they were not declared \fB.globl\fR; however, their value and type are available to the link editor so that the program may be loaded with others that ref%er%ence these symbols. .pg .ti 3 reggnored; if zero, the state%ments between the \fB.if\fR and the matching \fB.endif\fR (below) are ignored. .li \fB.if\fR may be nested. The effect of \fB.if\fR cannot extend beyond the end of the input file in which it appears. (The state%ments are not totally ignored, in the following sense: \fB.if\fRs and \fB.endif\fRs are scanned for, and moreover all names are entered in the symbol table. Thus names occurring only inside an \fB.if\fR will show up as undefined if the symbol table is listed.) .ms 7.4 \fB.of the remainder depends on the keyword. All the keywords are listed below with the syntax they require. .ul 6. Expressions .et An expression is a sequence of symbols representing a value. Its constituents are identifiers, constants, temporary symbols, operators, and brackets. Each expression has a type. .pg All operators in expressions are fundamentally binary in nature; if an operand is missing on the left, a 0 of absolute type is assumed. Arithmetic is two's complement and has 16 bits of precision. All ister .br The symbols .ta 6 .pg .nf \fBr0\fR .\|.\|. \fBr5 fr0\fR .\|.\|. \fBfr5 sp pc .ft R .fi .pg are predefined as register symbols. Either they or symbols defined from them must be used to refer to the six general-purpose, six floating-point, and the 2 special-purpose machine registers. The behavior of the floating register names is identical to that of the corresponding general register names; the former are provided as a mnemonic aid. .pg .ti 3 other types .br Each keyword known to the assembleendif\fR .pg This state%ment marks the end of a conditionally-assembled section of code. See \fB.if\fR above. .ms 7.5 \fB.globl \fIname \fR[ \fB,\fI name \fR] .\|.\|. .pg This state%ment makes the \fInames\fR external. If they are otherwise defined (by assignment or appearance as a label) they act within the assembly exactly as if the \fB.globl\fR state%ment were not given; however, the link editor \fIld\fR may be used to combine this routine with other routines that refer these symbols. .pg Converseoperators have equal precedence, and expressions are evaluated strictly left to right except for the effect of brackets. .ms 6.1 Expression operators .pg The operators are: .sp .in 8 .ta 3 8 .ti 0 (blank) when there is no operator between operands, the effect is exactly the same as if a ``+'' had appeared. .pg .ti 0 + addition .pg .ti 0 _ subtraction .pg .ti 0 * multiplication .pg .ti 0 \\\(sl division (note that plain ``\|/\|'' starts a comment) .pg .ti 0 & bitwise \fBand\fR .pg .ti 0 \|\|\(bv bitwr has a type which is used to select the routine which processes the associated keyword state%ment. The behavior of such symbols when not used as keywords is the same as if they were absolute. .in 0 .ms 6.3 Type propagation in expressions .pg When operands are combined by expression operators, the result has a type which depends on the types of the operands and on the operator. The rules involved are complex to state but were intended to be sensible and predictable. For purposes of expression evaluation thly, if the given symbols are not defined within the current assembly, the link editor can combine the output of this assembly with that of others which define the symbols. .pg As discussed in \(sc1, it is possible to force the assembler to make all otherwise undefined symbols external. .ms .ne 5 7.6 \fB.text\fR .br 7.7 \fB.data\fR .br 7.8 \fB.bss\fR .br .pg These three pseudo-operations cause the assembler to begin assembling into the text, data, or bss segment respectively. Assembly starts in the text sise \fBor\fR .pg .ti 0 >> logical right shift .pg .ti 0 << logical left shift .pg .hc .ti 0 % modulo .pg .hc % .ti 0 ! \fIa\fR\|!\|\fIb\fR is \fIa \fBor \fR(\|\fBnot \fIb\fR\|); i.e., the \fBor\fR of the first operand and the one's complement of the second; most common use is as a unary. .pg .ti 0 ^ result has the value of first operand and the type of the second; most often used to define new machine instructions with syntax identical to existing instructions. .sp .in 0 Expressions may be grouped by ue important types are .pg .ta 1i .nf undefined absolute text data bss undefined external other .fi .pg The combination rules are then: If one of the operands is undefined, the result is undefined. If both operands are absolute, the result is absolute. If an absolute is combined with one of the ``other types'' mentioned above, or with a register expression, the result has the register or other type. As a consequence, one can refer to r3 as ``r0+3''. If two operands of ``other type'' are combined, the egment. It is forbidden to assemble any code or data into the bss segment, but symbols may be defined and ``\|\fB.\fP\|'' moved about by assignment. .ms 7.9 \fB.comm\fI name \fB, \fIexpression\fR .pg Provided the \fIname\fR is not defined elsewhere, this state%ment is equivalent to .pg .ti 6 .li .globl name .ti 6 name = expression ^ name .pg That is, the type of \fIname\fR is ``undefined external'', and its value is \fIexpression\fR. In fact the \fIname\fR behaves in the current assembly just like an use of square brackets ``\|[\|\|]\|''. (Round parentheses are reserved for address modes.) .ms 6.2 Types .pg The assembler deals with a number of types of expressions. Most types are attached to keywords and used to select the routine which treats that keyword. The types likely to be met explicitly are: .sp 1 .in 6 .ti 3 undefined .br Upon first encounter, each symbol is undefined. It may become undefined if it is assigned an undefined expression. It is an error to attempt to assemble an undefined expressresult has the numerically larger type (not that this fact is very useful, since the values are not made public). An ``other type'' combined with an explicitly discussed type other than absolute acts like an absolute. .pg Further rules applying to particular operators are: .sp .in 7 .ta 3 7 .ti 0 + If one operand is text-, data-, or bss-segment relocatable, or is an undefined external, the result has the postulated type and the other operand must be absolute. .pg .ti 0 _ If the first operand is a relocatandefined external. However, the link-editor \fIld\fR has been special-cased so that all external symbols which are not otherwise defined, and which have a non-zero value, are defined to lie in the bss segment, and enough space is left after the symbol to hold \fIexpression\fR bytes. All symbols which become defined in this way are located before all the explicitly defined bss-segment locations. .ul 8. Machine instructions .et Because of the rather complicated instruction and addressing structure of the \sion in pass 2; in pass 1, it is not (except that certain keywords require operands which are not undefined). .pg .ti 3 undefined external .br A symbol which is declared \fB.globl\fR but not defined in the current assembly is an undefined external. If such a symbol is declared, the link editor \fIld\fR must be used to load the assembler's output with another routine that defines the undefined ref%er%ence. .pg .ti 3 absolute .br An absolute symbol is one defined ultimately from a constant. Its value is unaffeble text-, data-, or bss-segment symbol, the second operand may be absolute (in which case the result has the type of the first operand); or the second operand may have the same type as the first (in which case the result is absolute). If the first operand is external undefined, the second must be absolute. All other combinations are illegal. .pg .ti 0 ^ This operator follows no other rule than that the result has the value of the first operand and the type of the second. .pg .ti 0 others It is illegal to8PDP\s10-11, the syntax of machine instruction state%ments is varied. Although the following sections give the syntax in detail, the 11/20 and 11/45 handbooks should be consulted on the semantics. .ms 8.1 Sources and Destinations .pg The syntax of general source and destination addresses is the same. Each must have one of the following forms, where \fIreg\fR is a register symbol, and \fIexpr\fR is any sort of expression: .sp .ne 17 .nf .ta .75i 1.825i 2.75i syntax words mode .ta .75i 2.75i+\w'0+reg'u .lc \(ru 8 \(ru9 .ft R .ta .75i 2.0i 2.75i \fIreg\fR 0 0+\fIreg\fB (\|\fIreg\fB\|)\|+ \fR0 2+\fIreg\fB _\|(\|\fIreg\fB\|) \fR0 4+\fIreg\fR \fIexpr\|\fB(\|\fIreg\fB\|) \fR1 6+\fIreg\fB (\|\fIreg\fB\|) \fR0 1+\fIreg\fB *\|\fIreg\fB \fR0 1+\fIreg\fB *\|(\|\fIreg\fB\|)\|+ \fR0 3+\fIreg\fB *\|_\|(\|\fIreg\fB\|) \fR0 5+\fIreg\fB *\|(\|\fIreg\fB\|) \fR1 7+\fIreg\fB *\|\fIexpr\fB\|(\|\fIreg\fB\|) \fR1 7+\fIreg\fB \fIexpr \fR1 67 \fB$\|\fIexpr \fR1 27 \fB*\|\fIexpr \fR1 77 \fB*\|$\|\fIexpr \fR1 37 .spft R .fi \fBsys\fR is another name for the \fBtrap\fR instruction. It is used to code system calls. Its operand is required to be expressible in 6 bits. The alternative forms for \fBash\fR, \fBashc\fR, \fBmul\fR, and \fBdiv\fR are provided to avoid conflict with \s8EAE\s10 register names should they be needed. .pg The expression in \fBmark\fR must be expressible in six bits, and the expression in \fBsob\fR must be in the same segment as ``\fB\|.\|\fR'', must not be external-undefined, must be less than ``\|8 F\s10 error in local (``f\|'' or ``b'') type symbol \s8 G\s10 garbage (unknown) character \s8 I\s10 end of file inside an \fB.if\fR \s8 M\s10 multiply defined symbol as label \s8 O\s10 word quantity assembled at odd address \s8 P\s10 phase error_ ``\|\fB.\fP\|'' different in pass 1 and 2 \s8 R\s10 relocation error \s8 U\s10 undefined symbol \s8 X\s10 syntax error .fi .fi The \fIwords\fR column gives the number of address words generated; the \fImode\fR column gives the octal address-mode number. The syntax of the address forms is identical to that in \s8DEC\s10 assemblers, except that ``*'' has been substituted for ``@'' and ``$'' for ``#''; the \s8UNIX\s10 typing conventions make ``@'' and ``#'' rather inconvenient. .br .pg Notice that mode ``*reg'' is identical to ``(reg)''; that ``*(reg)'' generates an index word (namely, 0); and that addresses consisting of an unad\fB.\fR\|'', and must be within 510 bytes of ``\|\fB.\fR\|''. .ms 8.9 Floating-point unit instructions .pg The following floating-point operations are defined, with syntax as indicated: .pg .nf \fB cfcc \fB setf \fB setd \fB seti \fB setl \fB clrf \fIfdst \fB negf \fIfdst \fB absf \fIfdst \fB tstf \fIfsrc \fB movf \fIfsrc,\|freg \fR(= ldf\fR\|) \fB movf \fIfreg,\|fdst \fR(= stf\fR\|) \fB movif \fIsrc,\|freg \fR(= ldcif\fR\|) \fB movfi \fIfreg,\|dst \fR(= stcfi\fR\|) \fB movof \fIfsrc,\|freg \fR(= ldcdf\fR\orned expression are assembled as pc-relative ref%er%ences independent of the type of the expression. To force a non-relative ref%er%ence, the form ``*$expr'' can be used, but notice that further indirection is impossible. .ms 8.3 Simple machine instructions .pg The following instructions are defined as absolute symbols: .pg .ta 1i 2.5i 3i .ne 8 .nf .ft B clc clv clz cln sec sev sez sen .pg .fi .ft R They therefore require no special syntax. The \s8PDP\s10-11 hardware allows more than one of the `|) \fB movfo \fIfreg,\|fdst \fR(= stcfd\fR\|) \fB movie \fIsrc,\|freg \fR(= ldexp\fR) \fB movei \fIfreg,\|dst \fR(= stexp\fR) \fB addf \fIfsrc,\|freg \fB subf \fIfsrc,\|freg \fB mulf \fIfsrc,\|freg \fB divf \fIfsrc,\|freg \fB cmpf \fIfsrc,\|freg \fB modf \fIfsrc,\|freg \fB ldfps \fIsrc \fB stfps \fIdst \fB stst \fIdst .fi .ft R .pg \fIfsrc\fR, \fIfdst\fR, and \fIfreg\fR mean floating-point source, destination, and register respectively. Their syntax is identical to that for their non-floating counterparts, .th TBL VI 2/2/75 .sh NAME tbl \*- format tables for nroff or troff .sh SYNOPSIS .bd tbl [ files ] ... .sh DESCRIPTION .it Tbl is an nroff (I) or troff(I) preprocessor for formatting tables. The input files are copied to the standard output, except for lines between .TS and .TE command lines, which are assumed to describe tables and reformatted. The first line after .TS specifies the various columns: it consists of a list of column describers separated by blanks or tabs. Each column describer is a character`clear'' class, or alternatively more than one of the ``set'' class to be \fBor\fR-ed together; this may be expressed as follows: .pg clc\|\|\|\(bv\|\|clv .ms 8.4 Branch .pg The following instructions take an expression as operand. The expression must lie in the same segment as the ref%er%ence, cannot be undefined-external, and its value cannot differ from the current location of ``\|\fB.\fP\|'' by more than 254 bytes: .pg .ne 10 .nf .ft B br blos bne bvc beq bvs bge bhis blt bec \fR(=\fB bcc\fR)\fB but note that only floating registers 0_3 can be a \fIfreg\fR. .pg The names of several of the operations have been changed to bring out an analogy with certain fixed-point instructions. The only strange case is \fBmovf\fR, which turns into either \fBstf\fR or \fBldf\fR depending respectively on whether its first operand is or is not a register. Warning: \fBldf\fR sets the floating condition codes, \fBstf\fR does not. .ul 9. Other symbols .et .ti 0 9.1 \fB.\|.\fR .pg The symbol ``\fB\|.\|.\|\fR'' is the string made up of the letters `n', `r', `c', `l' and `s', which mean: .lp +4 4 .sp c center within the column .lp +4 4 .if n .sp 1 .if t .sp .3 r right-adjust .lp +4 4 .if n .sp 1 .if t .sp .3 l left-adjust .lp +4 4 .if n .sp 1 .if t .sp .3 n numerical adjustment: the units digits of numbers are aligned. .lp +4 4 .if n .sp 1 .if t .sp .3 s span the previous entry over this column. .if n .sp 1 .if t .sp .3 .i0 .s3 The column describer may be followed by an integer giving the number of spaces between this c bgt bcc ble blo bpl bcs bmi bes \fR(=\fB bcs\fR)\fB bhi .pg .fi .ft R \fBbes\fR (``branch on error set'') and \fBbec\fR (``branch on error clear'') are intended to test the error bit returned by system calls (which is the c-bit). .ms 8.5 Extended branch instructions .pg The following symbols are followed by an expression representing an address in the same segment as ``\|\fB.\|\fP''. If the target address is close enough, a branch-type instruction is generated; if the address is too far away, a \fBjm\fIrelocation counter\fR. Just before each assembled word is placed in the output stream, the current value of this symbol is added to the word if the word refers to a text, data or bss segment location. If the output word is a pc-relative address word which refers to an absolute location, the value of ``\fB\|.\|.\|\fR'' is subtracted. .pg Thus the value of ``\fB\|.\|.\|\fR'' can be taken to mean the starting core location of the program. In \s8UNIX\s10 systems with relocation hardware, the initial value ofolumn and the next; 3 is default. The describer `ccr5' indicates that the first two lines in this column are centered; the third and remaining lines are right-adjusted; and the column should be separated from the column to the right by 5 spaces. Letting \\t represent a tab (which must be typed as a genuine tab) the input .s3 .nf .TS cccl sccn sscn Household Population Town\\tHouseholds \\tNumber\\tSize Bedminster\\t789\\t3.26 Bernards Twp.\\t3087\\t3.74 Bernardsville\\t2018\\t3.30 Bound Brook\\t342p\fR will be used. .pg .ne 10 .nf .ft B jbr jlos jne jvc jeq jvs jge jhis jlt jec jgt jcc jle jlo jpl jcs jmi jes jhi .pg .fi .ft R \fBjbr\fR turns into a plain \fBjmp\fR if its target is too remote; the others (whose names are contructed by replacing the ``b'' in the branch instruction's name by ``j''\|) turn into the converse branch over a \fBjmp\fR to the target address. .ms 8.6 Single operand instructions .pg The following symbols are names of single-operand machine instructions. The form of ``\|\fB.\|.\fR\|'' is 0. .pg The value of ``\|\fB.\|.\fR\|'' may be changed by assignment. Such a course of action is sometimes necessary, but the consequences should be carefully thought out. It is particularly ticklish to change ``\|\fB.\|.\fR\|'' midway in an assembly or to do so in a program which will be treated by the loader, which has its own notions of ``\|\fB.\|.\fR\|''. .ms 9.2 System calls .pg The following absolute symbols may be used to code calls to the \s8UNIX\s10 system (see the \fBsys\fR 5\\t3.04 Branchburg\\t1644\\t3.49 Bridgewater\\t7897\\t3.81 Far Hills\\t240\\t3.19 .TE .fi yields .nf .TS .nr 49 0 .nr 50 0 .nr 47 \n(49+\w'Town'+1n .if \n(47-\n(50 .nr 50 \n(47 .nr 47 \n(49+\w''+1n .if \n(47-\n(50 .nr 50 \n(47 .nr 47 \n(49+\w'Bedminster'+1n .if \n(47-\n(50 .nr 50 \n(47 .nr 47 \n(49+\w'Bernards Twp.'+1n .if \n(47-\n(50 .nr 50 \n(47 .nr 47 \n(49+\w'Bernardsville'+1n .if \n(47-\n(50 .nr 50 \n(47 .nr 47 \n(49+\w'Bound Brook'+1n .if \n(47-\n(50 .nr 50 \n(47 .nr 47 \n(49+\w'Branchburg'+1n .iaddress expected is discussed in \(sc8.1 above. .pg .ft B .nf clr sbcb clrb ror com rorb comb rol inc rolb incb asr dec asrb decb asl neg aslb negb jmp adc swab adcb tst sbc tstb .br .ft R .fi .ms 8.7 Double operand instructions .pg The following instructions take a general source and destination (\(sc8.1), separated by a comma, as operands. .pg .ne 12 .ft B .nf mov movb cmp cmpb bit bitb bic bicb bis bisb add sub .fi .ft R .ms 8.8 Miscellaneous instructions .pg The following instinstruction above). .pg .ft B .nf .ta 1i 2.5i break nice chdir open chmod read chown seek close setuid creat signal exec stat exit stime fork stty fstat tell getuid time gtty umount link unlink makdir wait mdate write mount .fi .ft R .pg Warning: the \fBwait\fR system call is not the same as the \fBwait\fR instruction, which is not defined in the assembler. .ul 10. Diagnostics .et When an input file cannot be read, its name followed by a question mark is typed and assembly ceases. When syntf \n(47-\n(50 .nr 50 \n(47 .nr 47 \n(49+\w'Bridgewater'+1n .if \n(47-\n(50 .nr 50 \n(47 .nr 47 \n(49+\w'Far Hills'+1n .if \n(47-\n(50 .nr 50 \n(47 .nr 30 \n(49+\w'Household Population'+1n .nr 51 0 .nr 47 \n(50+\w'789'+4n .if \n(47-\n(51 .nr 51 \n(47 .nr 47 \n(50+\w'3087'+4n .if \n(47-\n(51 .nr 51 \n(47 .nr 47 \n(50+\w'2018'+4n .if \n(47-\n(51 .nr 51 \n(47 .nr 47 \n(50+\w'3425'+4n .if \n(47-\n(51 .nr 51 \n(47 .nr 47 \n(50+\w'1644'+4n .if \n(47-\n(51 .nr 51 \n(47 .nr 47 \n(50+\w'7897'+4n .if \n(47-\n(51 .nr 5ructions have more specialized syntax. Here \fIreg\fR is a register name, \fIsrc\fR and \fIdst\fR a general source or destination (\(sc8.1), and \fIexpr\fR is an expression: .pg .nf .ta 1.0i 1.5i 3i \fB jsr\fI reg,dst \fB rts\fI reg \fB sys\fI expr .ft B ash \fIsrc\|,\|reg \fR(or, \fBals\fR)\fB ashc \fIsrc\|,\|reg \fR(or, \fBalsc\fR)\fB mul \fIsrc\|,\|reg \fR(or, \fBmpy\fR)\fB div \fIsrc\|,\|reg \fR(or, \fBdvd\fR)\fR \fB xor \fIreg\|,\|dst\fB sxt \fIdst\fB mark \fIexpr\fB sob \fIreg\|,\|expr\fB .pg .actic or semantic errors occur, a single-character diagnostic is typed out together with the line number and the file name in which it occurred. Errors in pass 1 cause cancellation of pass 2. The possible errors are: .sp .nf .ta .5i .8i ) parentheses error ] parentheses error > string not terminated properly * indirection (\|*\|) used illegally \fB.\fR illegal assignment to ``\|\fB.\fP\|'' \s8 A\s10 error in address \s8 B\s10 branch address is odd or too remote \s8 E\s10 error in expression \s1 \n(47 .nr 47 \n(50+\w'240'+4n .if \n(47-\n(51 .nr 51 \n(47 .nr 31 \n(50+\w'Households'+4n .nr 52 0 .nr 48 \n(50+\w'Households'+0n .if \n(48-\n(52 .nr 52 \n(48 .nr 48 \n(50+\w'Number'+0n .if \n(48-\n(52 .nr 52 \n(48 .nr 47 \n(51+\w''+1n .if \n(47-\n(52 .nr 52 \n(47 .nr 47 \n(51+\w''+1n .if \n(47-\n(52 .nr 52 \n(47 .nr 47 \n(51+\w''+1n .if \n(47-\n(52 .nr 52 \n(47 .nr 47 \n(51+\w''+1n .if \n(47-\n(52 .nr 52 \n(47 .nr 47 \n(51+\w''+1n .if \n(47-\n(52 .nr 52 \n(47 .nr 47 \n(51+\w''+1n .if \n(47-\n(52 .nr 52 \n(47 .nr 47 \n(51+\w''+1n .if \n(47-\n(52 .nr 52 \n(47 .nr 47 \n(51+\w''+1n .if \n(47-\n(52 .nr 52 \n(47 .nr 53 0 .nr 47 \n(52+\w'3'+4n .if \n(47-\n(53 .nr 53 \n(47 .nr 47 \n(52+\w'3'+4n .if \n(47-\n(53 .nr 53 \n(47 .nr 47 \n(52+\w'3'+4n .if \n(47-\n(53 .nr 53 \n(47 .nr 47 \n(52+\w'3'+4n .if \n(47-\n(53 .nr 53 \n(47 .nr 47 \n(52+\w'3'+4n .if \n(47-\n(53 .nr 53 \n(47 .nr 47 \n(52+\w'3'+4n .if \n(47-\n(53 .nr 53 \n(47 .nr 47 \n(52+\w'3'+4n .if \n(47-\n(53 .nr 53 \n(47 .nr 54 0 .nr 48 \n(52+\w'Size'+0n .if \n( \n(12+\n(13+\w'\s8\|' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|=\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "ky\(fm\(fm .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\*' .nr 12 \w'\*(12' 'ps 8 .ds 13 "n\|\(mi\|\fR1\fP .nr 13 \w'\*(13' .as 12 \v'18u'\s8\*(13\|\s10\v'-18u' 'ps 10 .nr 12 \n(12+\n(13+\w'\s8\|' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 11 \x'0'\fI\*(11\s\n(9m. The vocabulary option substitutes a different file for .it /usr/lib/speak.m. Other vocabularies, to be used with option \fB\*-e\fR, exist in /usr/vs/latin.m and /usr/vs/polish.m. .s3 A set of single letter options may appear in any order preceded by .bd \*-. Their meanings are: .s3 .lp +8 4 \fBe\fR suppress English preprocessing .lp +8 4 \fBf\fR equivalent to `f1, f2,...' .lp +8 4 \fBp\fR suppress pronunciation by rule .lp +8 4 \fBs\fR suppress spelling .lp +8 4 \fBv\fR suppress voice output .s3 .i0 The 48-\n(54 .nr 54 \n(48 .nr 47 \n(53+\w''+1n .if \n(47-\n(54 .nr 54 \n(47 .nr 47 \n(53+\w'.26'+1n .if \n(47-\n(54 .nr 54 \n(47 .nr 47 \n(53+\w'.74'+1n .if \n(47-\n(54 .nr 54 \n(47 .nr 47 \n(53+\w'.30'+1n .if \n(47-\n(54 .nr 54 \n(47 .nr 47 \n(53+\w'.04'+1n .if \n(47-\n(54 .nr 54 \n(47 .nr 47 \n(53+\w'.49'+1n .if \n(47-\n(54 .nr 54 \n(47 .nr 47 \n(53+\w'.81'+1n .if \n(47-\n(54 .nr 54 \n(47 .nr 47 \n(53+\w'.19'+1n .if \n(47-\n(54 .nr 54 \n(47 .if \n(30-\n(54 .nr 54 \n(30 .if \n(31-\n(54 .nr 54 \n(31 .fc  @ .ta9\f\n(98 .ne 78u \*(11 'ps \n(99 .ft \n(98 .EN .. .if t .ig .ce (2nd deriv. at end) = k*(2nd deriv. next to end) .. .s3 .br is set by the next argument. By default \fIk\fR = 0. .s3 .lp +5 5 \fBn\fR Space output points so that approximately .it n points occur between the lower and upper .it x limits. (Default .it n = 100.) .s3 .lp +5 5 \fBp\fR Make output periodic, i.e. match derivatives at ends. First and last input values should normally agree. .s3 .lp +5 5 \fBx\fR Next 1 (or 2) arguments are lower (and ufollowing input will reconstitute a coded vocabulary, `speak.m', from an ascii listing, `speak.v', that was created using \fB!l\fR. .s3 .lp +8 0 (cat speak.v; echo !w speak.m) \*v speak \*-v /dev/null .s3 .i0 .sh FILES /usr/lib/speak.m .sh "SEE ALSO" M. D. McIlroy, ``Synthetic English Speech by Rule,'' Computing Science Technical Report #14, Bell Laboratories, 1973 .br vs (V), vs (IV) .sh BUGS Excessively long words cause dumps. .br Space is not reclaimed from changed entries; use \fB!w\fR and \fB!r\fR to e \n(54u @Household Population@ .ta \n(50u \n(54u @Town@ @Households@ .ta \n(50u \n(52u \n(54u @@ @Number@ @Size@ .ta \n(50u \n(51u \n(52u \n(53u \n(54u Bedminster@ @789@ @3.26@ Bernards Twp.@ @3087@ @3.74@ Bernardsville@ @2018@ @3.30@ Bound Brook@ @3425@ @3.04@ Branchburg@ @1644@ @3.49@ Bridgewater@ @7897@ @3.81@ Far Hills@ @240@ @3.19@ .fc .TE .fi .s3 .s3 If pper) .it x limits. Normally these limits are calculated from the data. Automatic abcissas start at lower limit (default 0). .i0 .sh "SEE ALSO" plot (I) .sh AUTHOR M. D. McIlroy .sh BUGS A limit of 1000 input points is enforced silently. ffect reclamation. .br \fB!p\fR doesn't always work as advertised. no arguments are given, .it tbl reads the standard input, so it may be used as a filter. When it is used with .it eqn or .it neqn the .it tbl command should be first, to minimize the volume of data passed through pipes. .sh BUGS No column describer may end with `s'. .th SPEAK VI 4/26/75 .if t .ds A \o"a\(ga" .if n .ds A a` .if t .ds v \|\(bv .sh NAME speak \*- word to voice translator .sh SYNOPSIS .bd speak [ .bd \*-efpsv ] [ vocabulary [ output ] ] .sh DESCRIPTION .it Speak turns a stream of words into utterances and outputs them to a voice synthesizer, or to the specified .it output. It has facilities for maintaining a vocabulary. It receives, from the standard input .s3 .lp +5 3 \*- working lines: text of words separated by blanks .lp +5 3 \*- phonetic lines: str.th SNO VI 2/9/73 .sh NAME sno \*- Snobol interpreter .sh SYNOPSIS .bd sno [ file ] .sh DESCRIPTION .it Sno is a Snobol III (with slight differences) compiler and interpreter. .it Sno obtains input from the concatenation of .it file and the standard input. All input through a statement containing the label `end' is considered program and is compiled. The rest is available to `syspit'. .s3 .it Sno differs from Snobol III in the following ways. .s3 There are no unanchored searches. To get the same effect: .s3.th SPLINE VI 5/15/74 .sh NAME spline \*- interpolate smooth curve .sh SYNOPSIS .bd spline [ option ] ... .sh DESCRIPTION .it Spline takes pairs of numbers from the standard input as abcissas and ordinates of a function. It produces a similar set, which is approximately equally spaced and includes the input set, on the standard output. The cubic spline output (R. W. Hamming, .ft I Numerical Methods for Scientists and Engineers, .ft R 2nd ed., 349ff) has two continuous derivatives, and sufficiently many poinings of phonemes for one word preceded and separated by commas. The phonemes may be followed by comma-percent then a `replacement part' \*- an ASCII string with no spaces. The phonetic code is given in .it vs (V). .lp +5 3 \*- empty lines .lp +5 3 \*- command lines: beginning with .bd !. The following command lines are recognized: .s3 .lp +15 10 \fB!r\fR file replace coded vocabulary from file .lp +15 10 \fB!w\fR file write coded vocabulary on file .lp +15 10 \fB!p\fR print phonetics for working word .lp + a ** b unanchored search for b .br a *x* b = x c unanchored assignment .s3 There is no back referencing. .s3 x = "abc" .br a *x* x is an unanchored search for `abc' .s3 .i0 Function declaration is different. The function declaration is done at compile time by the use of the label `define'. Thus there is no ability to define functions at run time and the use of the name `define' is preempted. There is also no provision for automatic variables other than the parameters. For example: .s3 .lp +8 8 .bd "dts to look smooth when plotted, for example by .it plot (I). .s3 The following options are recognized, each as a separate argument. .s3 .lp +5 5 \fBa\fR Supply abscissas automatically (they are missing from the input); spacing is given by the next argument, or is assumed to be 1 if next argument is not a number. .s3 .lp +5 5 \fBk\fR The constant \fIk\fR used in the boundary value computation .s3 .if n .ig .ti +1.5i .ds ' \h'-\w'\(fm\(fm'u' .EQ .nr 99 \n(.s .nr 98 \n(.f 'ps 10 .ft I .ds 11 "y\(fm\(fm .nr 11 15 10 \fB!l\fR list vocabulary on standard output with phonetics .lp +15 10 \fB!c\fR word copy phonetics from working word to specified word .lp +15 10 \fB!d\fR print decomposition of working word into substrings .lp +15 10 \fB!f\fI n\fR turn off (or on) English preprocessing rule number .it n (see listing for meaning of .it n) .s3 .i0 Each working line replaces its predecessor. Its first word is the `working word'. Each phonetic line replaces the phonetics stored for the working word. In particular, a phonefine f( )" .s3 .i0 or .s3 .lp +8 8 .bd "define f(a,b,c)" .s3 .i0 All labels except `define' (even `end') must have a non-empty statement. .s3 If `start' is a label in the program, program execution will start there. If not, execution begins with the first executable statement. `define' is not an executable statement. .s3 There are no builtin functions. .s3 Parentheses for arithmetic are not needed. Normal precedence applies. Because of this, the arithmetic operators `/' and `*' must be set off by space. .s\w'\*(11' .ds 12 "\*' .nr 12 \w'\*(12' 'ps 8 .ds 13 "\fR0\fP .nr 13 \w'\*(13' .as 12 \v'18u'\s8\*(13\|\s10\v'-18u' 'ps 10 .nr 12 \n(12+\n(13+\w'\s8\|' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|=\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "ky\(fm\(fm .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\*' .nr 12 \w'\*(12' 'ps 8 .ds 13 "\fR1\fP .nr 13 \w'\*(13' .as 12 \v'1etic line of comma only deletes the entry for the working word. Each working line, phonetic line or empty line causes the working line to be uttered. The process terminates at the end of input. .s3 Unknown words are pronounced by rules, and failing that, are spelled. For the builtin part of the rules, see the reference. Spelling is done by taking each character of the word, prefixing it with `*', and looking it up. Unspellable words burp. .s3 Words not found verbatim in the vocabulary are pronounced piecewi3 The right side of assignments must be non-empty. .s3 Either \*a or " may be used for literal quotes. .s3 The pseudo-variable `sysppt' is not available. .sh "SEE ALSO" Snobol III manual. (JACM; Vol. 11 No. 1; Jan 1964; pp 21) .sh BUGS 8u'\s8\*(13\|\s10\v'-18u' 'ps 10 .nr 12 \n(12+\n(13+\w'\s8\|' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 ", .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\|\| .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "y\(fm\(fm .nr 12 \w'\*(12' .as 11 "\*(12 .nr 11 \w'\*(11' .ds 12 "\*' .nr 12 \w'\*(12' 'ps 8 .ds 13 "n .nr 13 \w'\*(13' .as 12 \v'18u'\s8\*(13\|\s10\v'-18u' 'ps 10 .nr 12se. First the word is bracketed by sharps: `#...#'. The vocabulary is then searched for the longest fragment that matches the beginning of the word. The phonetic part of the phonetic string is uttered, and the matched fragment is replaced by the replacement part of the phonetic string, if any. The process is repeated until the word is exhausted. A fragment is entered into the vocabulary as a working word prefixed by `%'. .s3 .it Speak is initialized with a coded vocabulary stored in file .it /usr/lib/speak..th SKY VI 9/22/73 .sh NAME sky \*- obtain ephemerides .sh SYNOPSIS .bd sky [ .bd \-l ] .sh DESCRIPTION .it Sky predicts the apparent locations of the Sun, the Moon, the planets out to Saturn, stars of magnitude at least 2.5, and certain other celestial objects. .it Sky reads the standard input to obtain a GMT time typed on one line with blanks separating year, month number, day, hour, and minute; if the year is missing the current year is used. If a blank line is typed the current time is used. The program prints the azimuth, elevation, and magnitude of objects which are above the horizon at the ephemeris location of Murray Hill at the indicated time. The `\-l' flag causes it to ask for another location. .s3 Placing a ``1'' input after the minute entry causes the program to print out the Greenwich Sidereal Time at the indicated moment and to print for each body its topographic right ascension and declination as well as its azimuth and elevation. Also, instead of the magnitude, the semidiameter of the body, if files by name; and some elementary formatting and translating routines. The remainder of this memorandum lists the portable and non-portable library routines and explains some of the programming aids available. .PP The I/O routines in the C library fall into several classes. Files are addressed through intermediate numbers called .I file-descriptors .R which are described in section 2. Several default file-descriptors are provided by the system; other aspects of the system environment are explained in se characters per word. On \*sUNIX\*S \*sASCII\*S character code is used. Characters range from \(mi128 to +127 in numeric value, there is sign extension when characters are assigned to integers, and right shifts are arithmetic. The ``first'' character in a word is stored in the right half word. .PP More serious problems of compatibility are caused by the loaders on the different operating systems. .PP \*sUNIX\*S permits external names to be in upper and lower case, up to seven characters long. There may be n seconds of arc, is reported. .s3 A ``2'' after the minute entry makes the coordinate system geocentric. .s3 The effects of atmospheric extinction on magnitudes are not included; the brightest magnitudes of variable stars are marked with ``*''. .s3 For all bodies, the program takes into account precession and nutation of the equinox, annual (but not diurnal) aberration, diurnal parallax, and the proper motion of stars. In no case is refraction included. .s3 The program takes into account perturbations of tction 3. .PP Basic character-stream input and output involves the reading or writing of files considered as streams of characters. The C library includes facilities for this, discussed in section 4. Higher-level character stream operations permit translation of internal binary representations of numbers to and from character representations, and formatting or unpacking of character data. These operations are performed with the subprograms in section 5. Binary input and output routines permit data transmissimultiple external definitions (uninitialized) of the same name. .PP The C alphabet for identifier names includes the upper and lower case letters, the digits, and the underline. It is not possible for C programs to communicate with \*sFORTRAN\*S programs. .SH 4. BASIC CHARACTER STREAM ROUTINES .PP These routines transfer streams of characters in and out of C programs. Interpretation of the characters is left to the user. Facilities for interpreting numerical strings are presented in section 5; and routineshe Earth due to the Moon, Venus, Mars, and Jupiter. The expected accuracies are: for the Sun and other stellar bodies a few tenths of seconds of arc; for the Moon (on which particular care is lavished) likewise a few tenths of seconds. For the Sun, Moon and stars the accuracy is sufficient to predict the circumstances of eclipses and occultations to within a few seconds of time. The planets may be off by several minutes of arc. .s3 There are lots of special options not described here, which do things like son without the cost of translation to or from readable \*sASCII\*S character representations. Such data transmission should only be directed to files or tapes, and not to printers or terminals. As is usual with such routines, the only simple guarantee that can be made to the programmer seeking portability is that data written by a particular sequence of binary writes, if read by the exactly matching sequence of binary reads, will restore the previous contents of memory. Other reads or writes have system-de to transfer binary data to and from files or devices are discussed in section 6. In the following routine descriptions, the optional argument .ft I fd .ft P represents a file-descriptor; if not present, it is taken to be 0 for input and 1 for output. When your program starts, remember that these are associated with the ``standard'' input and output files. .sn COPEN (filename, type) .sN \fICopen\fR initiates activity on a file; if necessary it will create the file too. Up to 10 files may be open at one timubstituting named star catalogs, smoothing nutation and aberration to aid generation of mean places of stars, and making conventional adjustments to the Moon to improve eclipse predictions. .s3 For the most accurate use of the program it is necessary to know that it actually runs in Ephemeris time. .sh FILES /usr/lib/startab, /usr/lib/moontab .sh "SEE ALSO" azel (VI) .br .ft I American Ephemeris and Nautical Almanac, .ft R for the appropriate years; also, the .ft I Explanatory Supplement to the American Ephpendent effects. See section 6 for a discussion of binary input and output. Section 7 describes some further routines in the portable library. These include a storage allocator and some other control and conversion functions. .SH 2. FILE DESCRIPTORS .PP Except for the standard input and output files, all files must be explicitly opened before any I/O is performed on them. When files are opened for writing, they are created if not already present. They must be closed when finished, although the normal .I cexe. When called as described here, .ft I copen .ft R returns a filedescriptor for a character stream file. Values less than zero returned by .I copen .R indicate an error trying to open the file. Other calls to .ft I copen .ft R are described in sections 6 and 7. .sp 3p Arguments : .sp 3p .ft I Filename: .ft P a string representing a file name, according to the local operating system conventions. All accept a string of letters and digits as a legal file name, although leading digits are not recommended on \*emeris and Nautical Almanac. .ft R .sh AUTHOR R. Morris .sh BUGS it .R routine will take care of that. When opened a disc file or device is associated with a file descriptor, an integer between 0 and 9. This file descriptor is used for further I/O to the file. .PP Initially you are given three file descriptors by the system: 0, 1, and 2. File 0 is the standard input; it is normally the teletype in time-sharing or input data cards in batch. File 1 is the standard output; it is normally the teletype in time-sharing or the line printer in batch. File 2 is the error file; itsGCOS\*S. .br .ft I Type: .ft R a character `r', `w', or `a' meaning read, write, or append. Note that the type is a single character, whereas the file name must be a string. .sn CGETC ( fd ) .sN .ft I Cgetc .ft R returns the next character from the input unit associated with \fIfd\fR. On end of file \fIcgetc\fR returns `\\0'. To signal end of file from the teletype, type the special symbol appropriate to \*sUNIX\*S: EOT (control-D) .sn CPUTC (ch , fd ) .sN .ft I Cputc .ft R writes a character onto the giv...xappenc0c1c2c3c4c5c6catcm5tcm6titpag is an output file, normally the same as file 1, except that when file 1 is diverted via a command line '>' operator, file 2 remains attached to the original destination, usually the terminal. It is used for error message output. These popular \*sUNIX\*S conventions are considered part of the C library specification. By closing 0 or 1, the default input or output may be re-directed; this can also be done on the command line by .ft I >file .ft P for output or .ft I \fIidentifier .ed .dp 2 lvalue: identifier primary \fG[ \fIexpression \fG]\fI lvalue \fG. \fIidentifier primary \fG\(em>\fI identifier \** \fI expression \fG( \fIlvalue \fG)\fR .ed .fi .sp .7 The primary-expression operators .dp .ft G (^) [^] . \(em> .sp .5 .ed have highest priority and group left-to-right. The unary operators .dp .ft G \* & \(mi ! \*~ \fR++ \(mi\(mi \fG items being read. .sn CCLOSE (fd) .sN The same description applies as for character-stream files. .SH 7. OTHER PORTABLE ROUTINES .LP .sn REW (fd) .sN Rewinds unit .I fd. .R Buffers are emptied properly and the file is left open. .sn SYSTEM (string) .sN The given .I string .R is executed as if it were typed at the terminal. .sn NARGS (\|) .sN A subroutine can call this function to try to find out how many arguments it was called with. Normally, .I nargs() .R returns the number of arguments plus 3 for every ternate = empty \*v alternate primary primary = character \*v `[' category `]' \*v option option = `{' category `}' .s3 .i0 .fi The first category on each line of an index file names an information file. The remaining categories specify the order and contents of the data in each line of the information file. Information files have the same syntax. Backslash `\\' is used as with .it sh (I) to quote syntactically significant characters or to insert transparent newlines into a line. When either a question or isizeof .ed .sp .5 have priority below the primary operators but higher than any binary operator, and group right-to-left. Binary operators and the conditional operator all group left-to-right, and have priority decreasing as indicated: .dp .ft I binop: .ft G \** / % + \(mi >> << < > <= >= == != & .tr ^^ ^ .tr ^\| \(or && \(or\(or ? : .tr ^^ .sp .4 .fi .ft R Assignment operators all have the same priority, and all group right-to-left. .dp 3 .ft I asgnop: .ft G.I float .R or .I double .R argument and plus one for every .I long .R argument. If the new \*sUNIX\*S feature of separated instruction and data space areas is used, .I nargs() .R doesn't work at all. .sn CALLOC (n, sizeof(object)) .sN .I Calloc .R returns a pointer to new storage, allocated in space obtained from the operating system. The space obtained is well enough aligned for any use, i.e. for a double-precision number. Enough space to store .I n .R objects of the size indicated by the second argument ts answer is empty, .it quiz will refrain from asking it. .sh FILES /usr/lib/quiz/index .br /usr/lib/quiz/* .sh BUGS = =+ =\(mi =\** =/ =% =>> =<< =& =^ =\(or .ed .tr ^\| .sp .4 .ft R The comma operator has the lowest priority, and groups left-to-right. .sp .7 2. Declarations. .dp 2 declaration: decl-specifiers declarator-list\*(op \fG; .ed .dp 5 decl-specifiers: type-specifier sc-specifier type-specifier sc-specifier sc-specifier type-specifier .ed .dp 4 sc-specifier: .ft G auto static extern register .ed .dp 6 type-specifier: \fGint \fGchar \fGfloat \fGdouble struct { \fItyis provided. The .I sizeof .R is executed at compile time; it is not in the library. A returned value of \(mi1 indicates failure to obtain space. .sn CFREE (ptr, n, sizeof(*ptr)) .sN .I Cfree .R returns to the operating system memory starting at .I ptr .R and extending for .I n .R units of the size given by the third argument. The space should have been obtained through \fIcalloc\fR. On \*sUNIX\*S you can only return the exact amount of space obtained by .I calloc; .R the second and third arguments are ign36"%(+.1478;>ADGJM9<?Bpe-decl-list }\fG struct \fIidentifier { type-decl-list }\fG struct \fIidentifier\fG .ed .dp 2 declarator-list: declarator declarator \fG,\fI declarator-list .ed .dp 6 declarator: identifier \** \fIdeclarator declarator \fG( )\fI declarator \fG[\fI constant-expression\*(op \fG]\fI \fG( \fIdeclarator \fG) .ed .dp 2 type-decl-list: type-declaration type-declaration type-decl-list .ed .dp 2 type-declaration: type-specifier declarator-list \fG; .ed .sp 1.5 3. Statements. .dp 1 statored. .sn FTOA (floating-number, char-string, precision, format\|) .sN .ft I Ftoa .ft R (floating to \*sASCII\*S conversion) converts floating point numbers to character strings. The .ft I format .ft R argument should be either `f' or `e'; `e' is default. See the explanation of .ft I printf .ft R in section 5 for a description of the result. .sn ATOF (char-string) .sN Returns a floating value equal to the value of the \*sASCII\*S character string argument, interpreted as a decimal floating point number. .sn.pn 26 .fp 3 G 'tr ^\| 'hc $ 'tr @ 'll 6.5i 'ps 10 .ds op \s6\d\fIopt\fP\u\s10 .ds * \fR\v'.2'*\fP\v'-.2' .ds ~ \v'.5'\s14~\s10\v'-.5' 'vs 11p .de pg .sp .4 .ti 1 .. .de et .sp .2 .ft R .ti 1 .. .de dp .sp .7 .ne \\$1 .ft I .nf .. .de ed .fi .br .ft R .. .de ul .sp 1.5 .ne 4 .ft G .. .de ms .sp 1 .ne 4 .. .de fo 'bp .. .de he .po 0 .tl '-''' .po 'sp 0.5i .ft I .if o .tl '''C Reference Manual - %' .if e .tl 'C Reference Manual - %''' .ft 'sp 0.4i .. .de bG .br .fp 3 G .ft G .. .de eG .br .ft R .. .de itement: expression \fG; .se { \fIstatement-list } .se \fGif ( \fIexpression \fG) \fIstatement .se \fGif ( \fI expression \fG) \fIstatement \fGelse \fIstatement .se \fGwhile ( \fIexpression \fG) \fIstatement .se \fGfor ( \fIexpression\*(op \fG; \fIexpression\*(op \fG; \fIexpression\*(op \fG) statement .se \fGswitch ( \fIexpression \fG) \fIstatement .se \fGcase \fIconstant-expression \fG:\fI statement .se \fGdefault : \fIstatement .se \fGbreak ; .se \fGcontinue ; .se .ft G return ; .se TMPNAM (str) .sN This routine places in the character array expected as its argument a string which is legal to use as a file name and which is guaranteed to be unique among all jobs executing on the computer at the same time. It is thus appropriate for use as a temporary file name, although the user may wish to move it into an appropriate directory. The value of the function is the address of the string. .sn ABORT (code) .sN Causes your program to terminate abnormally, which typically results in a dump b .ft I \\$1 .ft R .. .de bd .ft G \\$1 .ft R .. .de se .br .ft I .. .wh 0 he .wh -1i fo .sp 2 .ce REFERENCES .sp 1.5 .ta 2 .tc @ .in 2 .ti 0 1. Johnson, S. C., and Kernighan, B. W. ``The Programming Language B.'' Comp. Sci. Tech. Rep. #8., Bell Laboratories, 1972. .sp .6 .ti 0 2. Ritchie, D. M., and Thompson, K. L. ``The \s8UNIX\s10 Time-sharing System.'' C. ACM \fG7, \fR17, July, 1974, pp. 365-375. .sp .6 .ti 0 3. Peterson, T. G., and Lesk, M. E. ``A User's Guide to the C Language on the IBM 370.'' Interna.ft G return ( \fIexpression \fG) ; .se .ft G goto \fIexpression \fG; .se \fIidentifier \fG: \fIstatement .se \fG; .ed .dp 2 statement-list: statement statement statement-list .sp 1.5 .ft R 4. External definitions. .dp 2 program: external-definition external-definition program .dp 2 external-definition: function-definition data-definition .ed .dp 2 function-definition: type-specifier\*(op \fIfunction-declarator function-body .ed .dp 2 function-declarator: declarator \fG( \fI parameter-list\*(op \fG) .ed .dp 1 parameter-list: identifier identifier \fG,\fI parameter-list .ed .dp 1 function-body: type-decl-list function-statement .ed .dp 2 function-statement: { declaration-list\*(op statement-list } .ed .dp 2 data-definition: \fGextern\fI\*(op type-specifier\*(op init-declarator-list\*(op \fG; .ed .dp 2 init-declarator-list: init-declarator init-declarator \fG,\fI init-declarator-list .ed .dp 2 init-declarator: declarator initializer\*(op .ed .dp 5 initializerefore type). .ti0 g C.3) Externals on \*sGCOS\*n must have a type (not defaulted to \fGint\fR). .ti0 u C.4) \*sGCOS\*n allows initialization of internal \fGstatic\fR (same syntax as for external definitions). .ti0 g C.5) integer\(mi>... is not allowed on \*sGCOS\*n. .ti0 g C.6) Some operators on pointers are illegal on \*sGCOS\*n (<, >). .ti0 g C.7) \fGregister\fR storage class means something on \*sUNIX\*n, but is not accepted on \*sGCOS\*n. .ti0 g C.8) Scope holes: ``int x; f^(^^)^{int x;}'' is illegal oncounter-clockwise. This command is not necessarily implemented on all (or even any) of the output devices. .s3 .lp +3 3 c circle: The first four bytes specify the center of the circle, the next two the radius. .s3 .lp +3 3 e erases the screen .s3 .lp +3 3 f linemod: takes the following string as the type for all future lines. The types are `dotted,' `solid,' `longdashed,' `shortdashed,' and `dotdashed.' This instruction is effective only with the Tektronix terminal. .s3 .lp +3 3 d dotline: takes the first f: constant { constant-expression-list } .ed .dp 5 constant-expression-list: constant-expression constant-expression \fG,\fI constant-expression-list .ed .dp 2 constant-expression: expression .ed .sp .4 5. Preprocessor .dp 1 \fG# define \fIidentifier token-string .ed .dp 1 \fG# include "\fIfilename^\fG" .ed .in 0 .bp .ds s \\s8 .ds n \\s10 .ft R .fi .sp 1 .ce 2 APPENDIX 2 Implementation Peculiarities .sp 2 This Appendix briefly summarizes the differences between the implementations of C on the \*sUNIX\*n but defines two variables on \*sGCOS\*n. .ti0 g C.9) When function names are used as arguments on \*sUNIX\*n, either ``fname'' or ``&fname'' may be used to get a pointer to the function; on \*sGCOS\*n ``&fname'' generates a doubly-indirect pointer. (Note that both are wrong since the ``&'' is supposed to be supplied for free.) .sp .ne 5 .ti0 .ft I D. Operating System Dependencies .sp .ft R .ti0 d D.1) \*sGCOS\*n allocates external scalars by SYMREF; \*sUNIX\*n allocates external scalars as labelour bytes as the coordinates of the beginning of a dotted line. The next two are a signed x-increment, and the next two are a word count. Following are the indicated number of byte-pairs representing words. For each bit in this list of words a point is plotted which is visible if the bit is `1,' invisible if not. Each point is offset rightward by the x-increment. The instruction is effective only on the vt0 scope. .s3 .i0 .sh "SEE ALSO" plot (VII), graph (VI) .sh BUGS \*sPDP\*n-11 under \*sUNIX\*n and on the \*sHIS\*n 6070 under \*sGCOS\*n; it includes some known bugs in each implementation. Each entry is keyed by an indicator as follows: .sp .ta .4i .8i .nf h hard to fix g \*sGCOS\*n version should probably be changed u \*sUNIX\*n version should probably be changed d Inherent difference likely to remain .sp .fi This list was prepared by M. E. Lesk, S. C. Johnson, E. N. Pinson, and the author. .sp 2 .fi .ta .4i 1.2i .in 1.2i .ti0 .ft I A. Bugs or differences from C led common; as a result there may be many uninitialized external definitions of the same variable on \*sUNIX\*n but only one on \*sGCOS\*n. .ti0 d D.2) External names differ in allowable length and character set; on \*sUNIX\*n, 7 characters and both cases; on \*sGCOS\*n 6 characters and only one case. .sp .ne 5 .ft I .ti0 E. Semantic Differences .ft R .sp .ti0 hg E.1) ``int i, *p; p=i; i=p;'' does nothing on \*sUNIX\*n, does something on \*sGCOS\*n (destroys right half of i) . .ti0 d E.2) ``>>'' means arithCFILOPSVYlanguage specifications .ft R .sp .ti0 hg A.1) \*sGCOS\*n does not do type conversions in ``?:''. .ti0 hg A.2) \*sGCOS\*n has a bug in \fGint\fR and \fGreal\fR comparisons; the numbers are compared by subtraction, and the difference must not overflow. .ti 0 g A.3) When \fIx\fR is a \fGfloat\fR, the construction ``test ? \(mix : x'' is illegal on \*sGCOS\*n. .ti0 hg A.4) ``p1\(mi>p2 =+ 2'' causes a compiler error, where p1 and p2 are pointers. .ti0 u A.5) On \*sUNIX\*n, the expression in a \fGreturn\fR statemetic shift on \*sUNIX\*n, logical on \*sGCOS\*n. .ti0 d E.3) When a \fGchar\fR is converted to integer, the result is always positive on \*sGCOS\*n but can be negative on \*sUNIX\*n. .ti0 d E.4) Arguments of subroutines are evaluated left-to-right on \*sGCOS\*n, right-to-left on \*sUNIX\*n. .H1 Change and Insert \(mi ``c'' and ``i'' .H2 .PG This section discusses the .ul change command .X1 c .X2 which is used to change or replace a group of one or more lines, and the .ul insert command .X1 i .X2 which is used for inserting a group of one or more lines. .PG ``Change'', written as .X1 c .X2 is used to replace a number of lines with different lines, which are typed in at the terminal. For example, to change lines ``\*.+1'' through ``$'' to something else, type .X1 .+1,$c . . . \fItype the linesment is \fInot\fR converted to the type of the function, as promised. .ti0 hug A.6) \fGentry\fR statement is not implemented at all. .sp .ne 5 .ft I .ti0 .ft I B. Implementation differences .ft R .sp .ti0 d B.1) Sizes of character constants differ; \*sUNIX\*n: 2, \*sGCOS\*n: 4. .ti0 d B.2) Table sizes in compilers differ. .ti0 d B.3) \fGchar\fRs and \fGint\fRs have different sizes; \fGchar\fRs are 8 bits on \*sUNIX\*n, 9 on \*sGCOS\*n; words are 16 bits on \*sUNIX\*n and 36 on \*sGCOS\*n. There are correspo.th PRIMES VI 4/10/75 .sh NAME primes \*- print all primes larger than somewhat .sh SYNOPSIS .bd primes .sh DESCRIPTION When .it primes is invoked, it waits for a number to be typed in. If you type in a positive number less than 2\u\s756\s0\d (about .if n 7.2e16) .if t 7.2\(mu10\u\s716\s0\d\|) it will print all primes greater than or equal to this number. .sh DIAGNOSTICS `Ouch.' for input out of range or for garbage input. .sh BUGS of text you want here\fP . . . \fB.\fR .X2 The lines you type between the ``c'' command and the ``\*.'' will take the place of the original lines between start line and end line. This is most useful in replacing a line or several lines which have errors in them. .PG If only one line is specified in the ``c'' command, then just that line is replaced. (You can type in as many replacement lines as you like.) Notice the use of ``\*.'' to end the input \(mi this works just like the ``\*.'' in the append commannding differences in representations of \fGfloat\fRs and \fGdouble\fRs. .ti0 d B.4) Character arrays stored left to right in a word in \*sGCOS\*n, right to left in \*sUNIX\*n. .ti0 g B.5) Passing of floats and doubles differs; \*sUNIX\*n passes on stack, \*sGCOS\*n passes pointer (hidden to normal user). .ti0 g B.6) Structures and strings are aligned on a word boundary in \*sUNIX\*n, not aligned in \*sGCOS\*n. .ti0 g B.7) \*sGCOS\*n preprocessor supports #rename, #escape; \*sUNIX\*n has only #define, #inclu.th PLOT VI 3/10/75 .sh NAME plot: tek, gsip, vt0 \*- graphics filters .sh SYNOPSIS source | .bd tek .br source | .bd gsip .br source | .bd vt0 .sh DESCRIPTION These commands produce graphical output on the Tektronix 4014 terminal, the GSI or other Diablo-mechanism terminals, and the on-line storage scope respectively. They read the standard input to obtain plotting instructions, which are usually generated by a program calling the graphics subroutines described in .it plot (VII). Each instruction consists d and must appear by itself on a new line. If no line number is given, line dot is replaced. The value of dot is set to the last line you typed in. .PG ``Insert'' is similar to append \(mi for instance .X1 /string/i .li . . . \fItype the lines to be inserted here\fP . . . .li \fB.\fR .X2 will insert the given text .ul before the next line that contains ``string''. The text between ``i'' and ``\*.'' is .ul inserted before the specified line. If no line number is specified dot is used. Dot is set to the last de. .ti0 u B.8) Preprocessor is not invoked on \*sUNIX\*n unless first character of file is ``#''. .ti0 u B.9) The external definition ``static int .^.^.'' is legal on \*sGCOS\*n, but gets a diagnostic on \*sUNIX\*n. (On \*sGCOS\*n it means an identifier global to the routines in the file but invisible to routines compiled separately.) .ti 0 g B.10) A compound statement on \*sGCOS\*n must contain one ``;'' but on \*sUNIX\*n may be empty. .ti 0 g B.11) On \*sGCOS\*n case distinctions in identifiers and keywoof an ASCII letter usually followed by binary information. A plotting coordinate is transmitted as four bytes representing the .it x and .it y values; each value is a signed number transmitted low-order byte first. The assumed plotting space is set by request. The instructions are taken from .s3 .lp +3 3 m move: the next four bytes specify the coordinates of a point to move to. This is used before writing a label. .s3 .lp +3 3 p point: the next four bytes specify the coordinates at which a point is drawn. .line inserted. .H1 Exercise 7: .H2 .PG ``Change'' is rather like a combination of delete followed by insert. Experiment to verify that .X1 \fIstart, end\fP d i .ul . . . text . . . .li \fB.\fR .X2 is almost the same as .X1 \fIstart, end\fP c .ul . . . text . . . .li \fB.\fR .X2 These are not .ul precisely the same if line ``$'' gets deleted. Check this out. What is dot? .PG Experiment with ``a'' and ``i'', to see that they are similar, but not the same. You will observe that .X1 \fIline-number\fP a .li . rds are ignored; on \*sUNIX\*n case is significant everywhere, with keywords in lower case. .sp .ne 5 .ti0 .ft I C. Syntax Differences .ft R .sp .ti0 g C.1) \*sUNIX\*n allows broader classes of initialization; on \*sGCOS\*n an initializer must be a constant, name, or string. Similarly, \*sGCOS\*n is much stickier about wanting braces around initializers and in particular they must be present for array initialization. .ti0 g C.2) ``int extern'' illegal on \*sGCOS\*n; must have ``extern int'' (storage class bs3 .lp +3 3 l line: the next eight bytes are taken as two pairs of coordinates specifying the endpoints of a line to be drawn. .s3 .lp +3 3 t label: the bytes up to a new-line are written as ASCII starting at the last point drawn or moved to. .s3 .lp +3 3 a arc: the first four bytes specify the center, the next four specify the starting point, and the last four specify the end point of a circular arc. The least significant coordinate of the end point is used only to determine the quadrant. The arc is drawn . . \fItext\fP . . . .li \fB.\fR .X2 appends .ul after the given line, while .X1 \fIline-number\fP i .li . . . \fItext\fP . . . .li \fB.\fR .X2 inserts .ul before it. Observe that if no line number is given, ``i'' inserts before line dot, while ``a'' appends after line dot. .H1 Moving text around: the ``m'' command .H2 .PG The move command ``m'' is used for cutting and pasting \(mi it lets you move a group of lines from one place to another in the buffer. Suppose we want to put the first three lines of the buffer at the end instead. We could do it by saying: .X1 1,3w temp $r temp 1,3d .X2 (Do you see why?) but we can do it a lot easier with the ``m'' command: .X1 1,3m$ .X2 The general case is .X1 \fIstart line, end line\fP m \fIafter this line\fP .X2 Notice that there is a third line to be specified \(mi the place where the moved stuff gets put. Of course the lines to be moved can be specified by context searches; if we had .X1 First paragraph .li . . . end of first paragraph. Second paragraph .li . . . end oring1' in specified lines. If no line is specified, make substitution in line dot. Dot is set to last line in which a substitution took place, which means that if no substitution took place, dot is not changed. .ul s changes only the first occurrence of string1 on a line; to change all of them, type a ``g'' after the final slash. .sp 4p .ul v (exclude) .ul v/---/commands executes ``commands'' on those lines that .ul do not contain ``---''. .sp 4p .ul w (write) Write out buffer onto a file. Dot is not changemand where it means ``whatever was matched on the left-hand side''. It is used to save typing. Suppose the current line contained .X1 Now is the time .X2 and we wanted to put parentheses around it. We could just retype the line, but this is tedious. Or we could say .X1 s/^/(/ s/$/)/ .X2 using our knowledge of ``^'' and ``$''. But the easiest way uses the ``&'': .X1 s/\*.*/(&)/ .X2 This says ``match the whole line, and replace it by itself surrounded by parens.''~ The ``&'' can be used several times in a linf second paragraph. .X2 we could reverse the two paragraphs like this: .X1 /Second/,/second/m/First/\(mi1 .X2 Notice the ``\(mi1'' \(mi the moved text goes .ul after the line mentioned. Dot gets set to the last line moved. .H1 The global commands ``g'' and ``v'' .H2 .PG The .ul global command ``g'' is used to execute one or more .ul ed commands on all those lines in the buffer that match some specified string. For example .X1 g/peling/p .X2 prints all lines that contain ``peling''. More usefully, .X1 g/peld. .sp 4p .ul .li .= (dot value) Print value of dot. (``='' by itself prints the value of ``$''.) .sp 4p .ul ! (temporary escape) Execute this line as a UNIX command. .sp 4p .ul /-----/ Context search. Search for next line which contains this string of characters. Print it. Dot is set to line where string found. Search starts at ``\*.+1'', wraps around from ``$'' to 1, and continues to dot, if necessary. .sp 4p .ul ?-----? Context search in reverse direction. Start search at ``\*.\(mi1'', scan to 1, wrape; consider using .X1 s/\*.*/&? &!!/ .X2 to produce .X1 Now is the time? Now is the time!! .X2 .PG We don't have to match the whole line, of course: if the buffer contains .X1 the end of the world .X2 we could type .X1 /world/s//& is at hand/ .X2 to produce .X1 the end of the world is at hand .X2 Observe this expression carefully, for it illustrates how to take advantage of .ul ed to save typing. The string ``/world/'' found the desired line; the shorthand ``//'' found the same word in the line; and the `ing/s//pelling/gp .X2 makes the substitution everywhere on the line, then prints each corrected line. Compare this to .X1 1,$s/peling/pelling/gp .X2 which only prints the last line substituted. Another subtle difference is that the ``g'' command does not give a ``?'' if ``peling'' is not found where the ``s'' command will. .PG There may be several commands (including ``a'', ``c'' ``i'' ``r'', ``w'', but not ``g''); in that case, every line except the last must end with a backslash ``\\'': .X1 g/xxx/\*.-1s/a around to ``$''. .in 0 `&'' saved us from typing it again. .PG The ``&'' is a special character only within the replacement text of a substitute command, and has no special meaning elsewhere. We can turn off the special meaning of ``&'' by preceding it with a ``\\'': .X1 s/ampersand/\\&/ .X2 will convert the word ``ampersand'' into the literal symbol ``&'' in the current line. bc/def/\\ .li \fB.\fR+2s/ghi/jkl/\\ .li \fB.\fR-2,\fB.\fRp .X2 makes changes in the lines before and after each line that contains ``xxx'', then prints all three lines. .PG The ``v'' command is the same as ``g'', except that the commands are executed on every line that does .ul not match the string following ``v'': .X1 v/ /d .X2 deletes every line that does not contain a blank. .H1 Special Characters .H2 .PG You may have noticed that things just don't work right when you used some characters like ``.'', ``*'', ``$'', and others in context searches and the substitute command. The reason is rather complex, although the cure is simple. Basically, .ul ed treats these characters as special, with special meanings. For instance, .ul in a context search or the first string of the substitute command only, \*. means ``any character,'' not a period, so .X1 /x\*.y/ .X2 means ``a line with an .th MOO VI 11/1/73 .sh NAME moo \*- guessing game .sh SYNOPSIS .bd /usr/games/moo .sh DESCRIPTION .it Moo is a guessing game imported from England. The computer picks a number consisting of four distinct decimal digits. The player guesses four distinct digits being scored on each guess. A `cow' is a correct digit in an incorrect position. A `bull' is a correct digit in a correct position. The game continues until the player guesses the number (a score of four bulls). .sh BUGS .sp 2 .H1 Summary of Commands and Line Numbers .H2 .PG The general form of .ul ed commands is the command name, perhaps preceded by one or two line numbers, and, in the case of .ul e, r and .ul w, followed by a file name. Only one command is allowed per line, but a .ul p command may follow any other command (except for .ul e, r, w and .ul q). .sp .ul a (append) Add lines to the buffer (at line dot, unless a different line is specified). Appending continues until ``\*.'' is typed on a new line. Dot is set to x, .ul any character, and a y,'' .ul not just ``a line with an x, a period, and a y.''~ A complete list of the special characters that can cause trouble is the following: .X1 ^ \*. $ [ * \\ .X2 .ul Warning: The backslash character \\ is special to .ul ed. For safety's sake, avoid it where possible. If you have to use one of the special characters in a substitute command, you can turn off its magic meaning temporarily by preceding it with the backslash. Thus .X1 s/\\\\\\\*.\\*/backslash dot .fp 3 G .tr ^\| .hc $ .tr @ .br .po 0 .tl '-''' .po .pl 11i .ll 6.5i .ps 18 .vs 18p .sp 1.4i .ce C Reference Manual .sp 2 .ps 10 .vs 11p .ce 3 .ft I Dennis M. Ritchie .sp .25 Bell Telephone Laboratories Murray Hill, New Jersey 07974 .ps 10 .ft R .vs 11p .sp 3 .de pg .sp .4 .ti 1 .. .de et .sp .2 .ft R .ti 1 .. .de dp .sp .7 .ne \\$1 .ft I .nf .. .de ed .fi .sp .7 .ft R .. .de ul .sp 1.5 .ne 4 .ft G .. .de ms .sp 1 .ne 4 .. .de fo 'bp .. .de he .po 0 .tl '-''' .po 'sp 0.5i .ft I .if o .tl '''C Reference M the last line appended. .sp 4p .ul c (change) Change the specified lines to the new text which follows. .li The new lines are terminated by a ``\*.''. If no lines are specified, replace line dot. Dot is set to last line changed. .sp 4p .ul d (delete) Delete the lines specified. If none are specified, delete line dot. Dot is set to the first undeleted line, unless ``$'' is deleted, in which case dot is set to ``$''. .sp 4p .ul e (edit) Edit new file. Any previous contents of the buffer are thrown away, so istar/ .X2 will change ``\\\*.*'' into ``backslash dot star''. .PG Here is a hurried synopsis of the other special characters. First, the circumflex `` ^ '' signifies the beginning of a line. Thus .X1 /^string/ .X2 finds ``string'' only if it is at the beginning of a line: it will find .X1 string .X2 but not .X1 the string... .X2 The dollar-sign ``$'' is just the opposite of the circumflex; it means the end of a line: .X1 /string$/ .X2 will only find an occurrence of ``string'' that is at the end of some linanual - %' .if e .tl 'C Reference Manual - %''' .ft 'sp 0.4i .. .de bG .br .ft G .. .de eG .br .ft R .. .de it .ft I \\$1 .ft R .. .de bd .ft G \\$1 .ft R .. .wh -1i fo .wh 0 he .ds op \s6\d\fIopt\fP\u\s10 .ds * \fR\v'.2'*\fP\v'-.2' .ds ~ \v'.5'\s14~\s10\v'-.5' ssue a .ul w beforehand if you want to save them. .sp 4p .ul f (file) Print remembered filename. If a name follows .ul f the remembered name will be set to it. .sp 4p .ul g (global) .ul g/---/commands will execute the commands on those lines that contain ``---'', which can be any context search expression. .sp 4p .ul i (insert) Insert lines before specified line (or dot) .li until a ``\*.'' is typed on a new line. Dot is set to last line inserted. .sp 4p .ul m (move) Move lines specified to after the line ne. This implies, of course, that .X1 /^string$/ .X2 will find only a line that contains just ``string'', and .X1 /^\*.$/ .X2 finds a line containing exactly one character. .PG The character ``\*.'', as we mentioned above, matches anything; .X1 /x\*.y/ .X2 matches any of .X1 x+y x-y x y x\*.y .X2 This is useful in conjunction with ``*'', which is a repetition character; ``a*'' is a shorthand for ``any number of a's,'' so ``\*.*'' matches any number of anythings. This is used like this: .X1 s/\*.*/stuff/ .X2 .th M6 VI 2/19/74 .sh NAME m6 \*- general purpose macroprocessor .sh SYNOPSIS .bd m6 [ name ] .sh DESCRIPTION .it M6 copies the standard input to the standard output, with substitutions for any macro calls that appear. When a file name argument is given, that file is read before the standard input. .s3 The processor is as described in the reference with these exceptions: .s3 .lp +2 0 .it #def,arg1,arg2,arg3: causes \fIarg1\fP to become a macro with defining text \fIarg2\fP and (optional) built-in serial numamed after .ul m. Dot is set to the last line moved. .sp 4p .ul p (print) Print specified lines. If none specified, print line dot. A single line number is equivalent to ``line-number p''. A single newline prints ``\*.+1'', the next line. .sp 4p .ul q (quit) Exit from ed. Wipes out all text in buffer!! .sp 4p .ul r (read) Read a file into buffer (at end unless specified elsewhere.) Dot set to last line read. .sp 4p .ul s (substitute) .ul s/string1/string2/ will substitute the characters of `string2' for `stwhich changes an entire line, or .X1 s/\*.*,// .X2 which deletes all characters in the line up to and including the last comma. (Since ``\*.*'' finds the longest possible match, this goes up to the last comma.) .PG ``['' is used with ``]'' to form ``character classes''; for example, .X1 /[1234567890]/ .X2 matches any single digit _ any one of the characters inside the braces will cause a match. .PG Finally, the ``&'' is another shorthand character - it is used only on the right-hand part of a substitute comber \fIarg3\fP. .s3 .it #del,arg1: deletes the definition of macro \fIarg1\fP. .s3 .it #end: is not implemented. .s3 .it #list,arg1: sends the name of the macro designated by \fIarg1\fP to the current destination without recognition of any warning characters; \fIarg1\fP is 1 for the most recently defined macro, 2 for the next most recent, and so on. The name is taken to be empty when \fIarg1\fP doesn't make sense. .s3 .it #warn,arg1,arg2: replaces the old warning character \fIarg1\fP by the new warning character \fIarg2\fP. .s3 .it #quote,arg1: sends the definition text of macro \fIarg1\fP to the current destination without recognition of any warning characters. .s3 .it #serial,arg1: delivers the built-in serial number associated with macro \fIarg1\fP. .s3 .it #source,arg1: is not implemented. .s3 .it #trace,arg1: with \fIarg1\fP = `1' causes a reconstruction of each later call to be placed on the standard output with a call level number; other values of \fIarg1\fP turn tracing off. .i0 .s3 The built-in `warn other separators. In general blanks, tabs, newlines, and comments as described below are ignored except as they serve to separate tokens. At least one of these characters is required to separate otherwise adjacent identifiers, constants, and certain operator-pairs. .pg If the input stream has been parsed into tokens up to a given character, the next token is taken to include the longest string of characters which could possibly constitute a token. .ms 2.1 Comments .et The characters ^^\fG/\**\fR^^ introdu the subscript ``opt,'' so that .dp { expression\*(op } .ed would indicate an optional expression in braces. .ul 4. What's in a Name? .et C bases the interpretation of an identifier upon two attributes of the identifier: its .ft I storage class .ft R and its .ft I type. .ft R The storage class determines the location and lifetime of the storage associated with an identifier; the type determines the meaning of the values found in the identifier's storage. .pg There are four declarable storage classes: auto' may be used to replace inconvenient warning characters. The example below replaces `#' `:' `<' `>' by `[' `]' `{' `}'. .s3 .lp +10 0 .nf #warn,<#>,[: [warn,<:>,]: [warn,[substr,<<>>,1,1\fB;\fP,{] [warn,[substr,{{>>,2,1\fB;\fP,}] [now,{calls look like this}] .fi .i0 .s3 Every built-in function has a serial number, which specifies the action to be performed before the defining text is expanded. The serial numbers are: 1 gt, 2 eq, 3 ge, 4 lt, 5 ne, 6 le, 7 seq, 8 sne, 9 add, 10 sub, 11 mpy, 12 div, 13 exp, 2ce a comment, which terminates with the characters^^ \fG\**/\fR. .ms 2.2 Identifiers (Names) .et An identifier is a sequence of letters and digits; the first character must be alphabetic. The underscore ``\(ru'' counts as alphabetic. Upper and lower case letters are considered different. No more than the first eight characters are significant, and only the first seven for external identifiers. .ms 2.3 Keywords .et The following identifiers are reserved for use as keywords, and may not be used otherwise: .matic, static, external, and register. Automatic variables are local to each invocation of a function, and are discarded on return; static variables are local to a function, but retain their values independently of invocations of the function; external variables are independent of any function. Register variables are stored in the fast registers of the machine; like automatic variables they are local to each function and disappear on return. .pg C supports four fundamental types of objects: characters, inte0 if, 21 def, 22 copy, 23 warn, 24 size, 25 substr, 26 go, 27 gobk, 28 del, 29 dnl, 32 quote, 33 serial, 34 list, 35 trace. Serial number 0 specifies no built-in action. .sh "SEE ALSO" A. D. Hall, M6 Reference Manual. Computer Science Technical Report #2, Bell Laboratories, 1969. .sh DIAGNOSTICS Various table overflows and ``impossible'' conditions result in comment and dump. There are no diagnostics for poorly formed input. .sh AUTHOR M. D. McIlroy .sh BUGS Provision should be made to extend tables as needsp .7 .in .5i .ta 2i .nf .ne 10 .ft G int break char continue float if double else struct for auto do extern while register switch static case goto default return entry sizeof .sp .7 .ft R .fi .in 0 The .bd entry keyword is not currently implemented by any compiler but is reserved for future use. .ms 2.3 Constants .et There are several kinds of constants, as follows: .ms 2.3.1 Integer constants .et An integer constant is a sequence of digits. An integer is taken to be octal if it begins with \fG0\fR, decigers, single-, and double-precision floating-point numbers. .sp .7 .in .5i Characters (declared, and hereinafter called, \fGchar\fR) are chosen from the \s8ASCII\s10 set; they occupy the right-most seven bits of an 8-bit byte. It is also possible to interpret \fGchar\fRs as signed, 2's complement 8-bit numbers. .sp .4 Integers (\fGint\fR) are represented in 16-bit 2's complement notation. .sp .4 Single precision floating point (\fGfloat\fR) quantities have magnitude in the range approximately 10\u\s7\(+-38\ed, instead of wasting a big fixed core allocation. You get what the PDP11 gives you for arithmetic. mal otherwise. The digits \fG8\fR and \fG9\fR have octal value 10 and 11 respectively. .ms 2.3.2 Character constants .et A character constant is 1 or 2 characters enclosed in single quotes ``\fG^\(aa^\fR''. Within a character constant a single quote must be preceded by a back-slash ``\\''. Certain non-graphic characters, and ``\\'' itself, may be escaped according to the following table: .sp .7 .ta .5i 1.25i .nf \s8BS\s10 \\b \s8NL\s10 \\n \s8CR\s10 \\r \s8HT\s10 \\t \fIddd\fR \\\fIddd\fR \\ \\\\ .fis10\d or 0; their precision is 24 bits or about seven decimal digits. .sp .4 Double-precision floating-point (\fGdouble\fR) quantities have the same range as \fGfloat\fRs and a precision of 56 bits or about 17 decimal digits. .sp .7 .in 0 .pg Besides the four fundamental types there is a conceptually infinite class of derived types constructed from the fundamental types in the following ways: .sp .7 .in .5i .ft I arrays .ft R of objects of most types; .sp .4 .ft I functions .ft R which return objects of a gwz}ilorux{~jmpsvy| .sp .7 The escape ``\\\fIddd\fR'' consists of the backslash followed by 1, 2, or 3 octal digits which are taken to specify the value of the desired character. A special case of this construction is ``\\0'' (not followed by a digit) which indicates a null character. .pg Character constants behave exactly like integers (not, in particular, like objects of character type). In conformity with the addressing structure of the \s8PDP\s10-11, a character constant of length 1 has the code for the given character iniven type; .sp .4 .ft I pointers .ft R to objects of a given type; .sp .4 .ft I structures .ft R containing objects of various types. .sp .7 .in 0 In general these methods of constructing objects can be applied recursively. .ul 5. Objects and lvalues .et An object is a manipulatable region of storage; an lvalue is an expression referring to an object. An obvious example of an lvalue expression is an identifier. There are operators which yield lvalues: for example, if E is an expression of pointer type, the.ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i .ul 1. Introduction .et C is a computer language based on the earlier language B [1]. The languages and their compilers differ in two major ways: C introduces the notion of types, and defines appropriate extra syntax and semantics; also, C on the \s8PDP\s10-11 is a true compiler, producing machine code where B produced interpretive code. .pg Most of the software for the \s8UNIX\s10 time-sharing system [2] is written in C, as is the operating system itself. C is also avail the low-order byte and 0 in the high-order byte; a character constant of length 2 has the code for the first character in the low byte and that for the second character in the high-order byte. Character constants with more than one character are inherently machine-dependent and should be avoided. .ms 2.3.3 Floating constants .et A floating constant consists of an integer part, a decimal point, a fraction part, an \fGe\fR, and an optionally signed integer exponent. The integer and fraction parts both consin \**E is an lvalue expression referring to the object to which E points. The name ``lvalue'' comes from the assignment expression ``E1@=@E2'' in which the left operand E1 must be an lvalue expression. The discussion of each operator below indicates whether it expects lvalue operands and whether it yields an lvalue. .ul 6. Conversions .et A number of operators may, depending on their operands, cause conversion of the value of an operand from one type to another. This section explains the result to be expecable on the \s8HIS\s10 6070 computer at Murray Hill and and on the \s8IBM\s10 System/370 at Holmdel [3]. This paper is a manual only for the C language itself as implemented on the \s8PDP\s10-11. However, hints are given occasionally in the text of implementation-dependent features. .pg The \s8UNIX\s10 Programmer's Manual [4] describes the library routines available to C programs under \s8UNIX\s10, and also the procedures for compiling programs under that system. ``The \s8GCOS\s10 C Library'' by Lesk and Bast of a sequence of digits. Either the integer part or the fraction part (not both) may be missing; either the decimal point or the \fGe\fR and the exponent (not both) may be missing. Every floating constant is taken to be double-precision. .ms 2.4 Strings .et A string is a sequence of characters surrounded by double quotes ``^\fG"\fR^''. A string has the type array-of-characters (see below) and refers to an area of storage initialized with the given characters. The compiler places a null byte (^\\0^) at tted from such conversions. .ms 6.1 Characters and integers .et A \fGchar\fR object may be used anywhere an \fGint\fR may be. In all cases the \fGchar\fR is converted to an \fGint\fR by propagating its sign through the upper 8 bits of the resultant integer. This is consistent with the two's complement representation used for both characters and integers. (However, the sign-propagation feature disappears in other implementations.) .ms 6.2 Float and double .et All floating arithmetic in C is carried out in drres [5] describes routines available under that system as well as compilation procedures. Many of these routines, particularly the ones having to do with I/O, are also provided under \s8UNIX\s10. Finally, ``Programming in C\(mi A Tutorial,'' by B. W. Kernighan [6], is as useful as promised by its title and the author's previous introductions to allegedly impenetrable subjects. .ul 2. Lexical conventions .et There are six kinds of tokens: identifiers, keywords, constants, strings, expression operators, andhe end of each string so that programs which scan the string can find its end. In a string, the character ``^\fG"\fR^'' must be preceded by a ``\\''^; in addition, the same escapes as described for character constants may be used. .ul 3. Syntax notation .et In the syntax notation used in this manual, syntactic categories are indicated by \fIitalic\fR type, and literal words and characters in \fGgothic.\fR Alternatives are listed on separate lines. An optional terminal or non-terminal symbol is indicated byouble-precision; whenever a \fGfloat\fR appears in an expression it is lengthened to \fGdouble\fR by zero-padding its fraction. When a \fGdouble\fR must be converted to \fGfloat\fR, for example by an assignment, the \fGdouble\fR is rounded before truncation to \fGfloat\fR length. .ms 6.3 Float and double; integer and character .et All \fGint\fRs and \fGchar\fRs may be converted without loss of significance to \fGfloat\fR or \fGdouble\fR. Conversion of \fGfloat\fR or \fGdouble\fR to \fGint\fR or \fGchar\fR takes place with truncation towards 0. Erroneous results can be expected if the magnitude of the result exceeds 32,767 (for \fGint\fR) or 127 (for \fGchar\fR). .ms 6.4 Pointers and integers .et Integers and pointers may be added and compared; in such a case the \fGint\fR is converted as specified in the discussion of the addition operator. .pg Two pointers to objects of the same type may be subtracted; in this case the result is converted to an integer as specified in the discussion of the subtraction operpe of the result is ``^.^.^.^''. The expression ``E1[E2]'' is identical (by definition) to ``\**^(^^(^E1^)^+^(^E2^)^^)^''. All the clues needed to understand this notation are contained in this section together with the discussions in \(sc\(sc 7.1.1, 7.2.1, and 7.4.1 on identifiers, \fG\**\fR, and \fG+\fR respectively; \(sc14.3 below summarizes the implications. .ms 7.1.6 \fIprimary-expression \fG( \fIexpression-list\*(op \fG) .et A function call is a primary expression followed by parentheses containing ad the result is \fGint\fR. .ms 7.2.6 ++ \fIlvalue-expression\fR .et The object referred to by the lvalue expression is incremented. The value is the new value of the lvalue expression and the type is the type of the lvalue. If the expression is \fGint\fR or \fGchar\fR, it is incremented by 1; if it is a pointer to an object, it is incremented by the length of the object. ++ is applicable only to these types. (Not, for example, to \fGfloat\fR or \fGdouble\fR.) .ms 7.2.7 \fR\(mi\(mi\fI lvalue-expression\fR ator. possibly empty, comma-separated list of expressions which constitute the actual arguments to the function. The primary expression must be of type ``function returning .^.^.'', and the result of the function call is of type ``^.^.^.^''. As indicated below, a hitherto unseen identifier followed immediately by a left parenthesis is contextually declared to represent a function returning an integer; thus in the most common case, integer-valued functions need not be declared. .pg Any actual arguments of type \f.et The object referred to by the lvalue expression is decremented analogously to the ++ operator. .ms 7.2.8 \fIlvalue-expression ++ .et The result is the value of the object referred to by the lvalue expression. After the result is noted, the object referred to by the lvalue is incremented in the same manner as for the prefix ++ operator: by 1 for an \fGint\fR or \fGchar\fR, by the length of the pointed-to object for a pointer. The type of the result is the same as the type of the lvalue-expression. .ms 7Gfloat\fR are converted to \fGdouble\fR before the call; any of type \fGchar\fR are converted to \fGint\fR. .pg In preparing for the call to a function, a copy is made of each actual parameter; thus, all argument-passing in C is strictly by value. A function may change the values of its formal parameters, but these changes cannot possibly affect the values of the actual parameters. On the other hand, it is perfectly possible to pass a pointer on the understanding that the function may change the value of th.2.9 \fIlvalue-expression \(mi\(mi .et The result of the expression is the value of the object referred to by the the lvalue expression. After the result is noted, the object referred to by the lvalue expression is decremented in a way analogous to the postfix ++ operator. .ms 7.2.10 \fGsizeof \fIexpression .et The \fGsizeof\fR operator yields the size, in bytes, of its operand. When applied to an array, the result is the total number of bytes in the array. The size is determined from the declarations of .ul 7. Expressions .et The precedence of expression operators is the same as the order of the major subsections of this section (highest precedence first). Thus the expressions referred to as the operands of \fG+\fR (\(sc7.4) are those expressions defined in \(sc\(sc7.1_7.3. Within each subsection, the operators have the same precedence. Left- or right-associativity is specified in each subsection for the operators discussed therein. The precedence and associativity of all the expression operators is summae object to which the pointer points. .pg Recursive calls to any function are permissible. .ms 7.1.7 \fIprimary-lvalue \fG.\fI member-of-structure\fR .et An lvalue expression followed by a dot followed by the name of a member of a structure is a primary expression. The object referred to by the lvalue is assumed to have the same form as the structure containing the structure member. The result of the expression is an lvalue appropriately offset from the origin of the given lvalue whose type is that of the the objects in the expression. This expression is semantically an integer constant and may be used anywhere a constant is required. Its major use is in communication with routines like storage allocators and I/O systems. .ms 7.3 Multiplicative operators .et The multiplicative operators \fG\**\fR, \fG/\fR, and \fG%\fR group left-to-right. .ms 7.3.1 \fIexpression\fG \** \fIexpression\fR .et The binary \fG\**\fR operator indicates multiplication. If both operands are \fGint\fR or \fGchar\fR, the result is \frized in an appendix. .pg Otherwise the order of evaluation of expressions is undefined. In particular the compiler considers itself free to compute subexpressions in the order it believes most efficient, even if the subexpressions involve side effects. .ms 7.1 Primary expressions .et Primary expressions involving \fG.\fR^, \fG\(mi>\fR, subscripting, and function calls group left to right. .ms 7.1.1 \fIidentifier\fR .et An identifier is a primary expression, provided it has been suitably declared as discnamed structure member. The given lvalue is not required to have any particular type. .pg Structures are discussed in \(sc8.5. .ms 7.1.8 \fIprimary-expression \fG\(mi>\fI member-of-structure\fR .et The primary-expression is assumed to be a pointer which points to an object of the same form as the structure of which the member-of-structure is a part. The result is an lvalue appropriately offset from the origin of the pointed-to structure whose type is that of the named structure member. The type of the primGint\fR; if one is \fGint\fR or \fGchar\fR and one \fGfloat\fR or \fGdouble\fR, the former is converted to \fGdouble\fR, and the result is \fGdouble\fR; if both are \fGfloat\fR or \fGdouble\fR, the result is \fGdouble\fR. No other combinations are allowed. .ms 7.3.2 \fIexpression \fG/\fI expression\fR .et The binary \fG/\fR operator indicates division. The same type considerations as for multiplication apply. .ms 7.3.3 \fIexpression \fG%\fI expression\fR .et The binary \fG%\fR operator yields the remaindeussed below. Its type is specified by its declaration. However, if the type of the identifier is ``array of .^.^.'', then the value of the identifier-expression is a pointer to the first object in the array, and the type of the expression is ``pointer to .^.^.''. Moreover, an array identifier is not an lvalue expression. .pg Likewise, an identifier which is declared ``function returning .^.^.'', when used except in the function-name position of a call, is converted to ``pointer to function returning .^.^.''ary-expression need not in fact be pointer; it is sufficient that it be a pointer, character, or integer. .pg Except for the relaxation of the requirement that E1 be of pointer type, the expression ``E1\(mi>MOS'' is exactly equivalent to ``(\**E1).MOS''. .ms 7.2 Unary operators .et Expressions with unary operators group right-to-left. .ms 7.2.1 \fG\**\fI expression\fR .et The unary \fG\**\fR operator means .ft I indirection: .ft R the expression must be a pointer, and the result is an lvalue referring to r from the division of the first expression by the second. Both operands must be \fGint\fR or \fGchar\fR, and the result is \fGint\fR. In the current implementation, the remainder has the same sign as the dividend. .ms 7.4 Additive operators .et The additive operators \fG+\fR and \fG\(mi\fR group left-to-right. .ms 7.4.1 \fIexpression \fG+\fI expression\fR .et The result is the sum of the expressions. If both operands are \fGint\fR or \fGchar\fR, the result is \fGint\fR. If both are \fGfloat\fR or \fGdoub. .ms 7.1.2 \fIconstant\fR .et A decimal, octal, character, or floating constant is a primary expression. Its type is \fGint\fR in the first three cases, \fGdouble\fR in the last. .ms 7.1.3 \fIstring\fR .et A string is a primary expression. Its type is originally ``array of \fGchar\fR''; but following the same rule as in \(sc7.1.1 for identifiers, this is modified to ``pointer to \fGchar\fR'' and the result is a pointer to the first character in the string. .ms 7.1.4 \fG(\fI expression \fG)\fR .et A parethe object to which the expression points. If the type of the expression is ``pointer to .^.^.'', the type of the result is ``^.^.^.^''. .ms 7.2.2 \fG&\fI lvalue-expression\fR .et The result of the unary \fG&\fR operator is a pointer to the object referred to by the lvalue-expression. If the type of the lvalue-expression is ``^.^.^.^'', the type of the result is ``pointer to .^.^.''. .ms 7.2.3 \fG\(mi\fI expression\fR .et The result is the negative of the expression, and has the same type. The type of thele\fR, the result is \fGdouble\fR. If one is \fGchar\fR or \fGint\fR and one is \fGfloat\fR or \fGdouble\fR, the former is converted to \fGdouble\fR and the result is \fGdouble\fR. If an \fGint\fR or \fGchar\fR is added to a pointer, the former is converted by multiplying it by the length of the object to which the pointer points and the result is a pointer of the same type as the original pointer. Thus if P is a pointer to an object, the expression ``P+1'' is a pointer to another object of the same type asnthesized expression is a primary expression whose type and value are identical to those of the unadorned expression. The presence of parentheses does not affect whether the expression is an lvalue. .ms 7.1.5 \fIprimary-expression\fG [\fI expression \fG]\fR .et A primary expression followed by an expression in square brackets is a primary expression. The intuitive meaning is that of a subscript. Usually, the primary expression has type ``pointer to .^.^.'', the subscript expression is \fGint\fR, and the ty expression must be \fGchar\fR, \fGint\fR, \fGfloat\fR, or \fGdouble\fR. .ms 7.2.4 \fG!\fI expression\fR .et The result of the logical negation operator \fG!\fR is 1 if the value of the expression is 0, 0 if the value of the expression is non-zero. The type of the result is \fGint\fR. This operator is applicable only to \fGint\fRs or \fGchar\fRs. .ms 7.2.5 \fG\*~\fI expression\fR .et The \*~ operator yields the one's complement of its operand. The type of the expression must be \fGint\fR or \fGchar\fR, an the first and immediately following it in storage. .pg No other type combinations are allowed. .ms 7.4.2 \fIexpression \fG\(mi \fIexpression\fR .et The result is the difference of the operands. If both operands are \fGint\fR, \fGchar\fR, \fGfloat\fR, or \fGdouble\fR, the same type considerations as for \fG+\fR apply. If an \fGint\fR or \fGchar\fR is subtracted from a pointer, the former is converted in the same way as explained under \fG+\fR above. .pg If two pointers to objects of the same type are subtracted, the result is converted (by division by the length of the object) to an \fGint\fR representing the number of objects separating the pointed-to objects. This conversion will in general give unexpected results unless the pointers point to objects in the same array, since pointers, even to objects of the same type, do not necessarily differ by a multiple of the object-length. .ms 7.5 Shift operators .et The shift operators \fG<<\fR and \fG>>\fR group left-to-right. .ms 7.5.1 \fIexpression \fG<< \fIexpnd and third operand are the same, the result has their common type; otherwise the same conversion rules as for \fG+\fR apply. Only one of the second and third expressions is evaluated. .ms 7.14 Assignment operators .et There are a number of assignment operators, all of which group right-to-left. All require an lvalue as their left operand, and the type of an assignment expression is that of its left operand. The value is the value stored in the left operand after the assignment has taken place. .ms 7.14.1he function in which they are declared. .pg There are some severe restrictions on .bd register identifiers: there can be at most 3 register identifiers in any function, and the type of a register identifier can only be .bd int, .bd char, or pointer (not .bd float, .bd double, structure, function, or array). Also the address-of operator .bd & cannot be applied to such identifiers. .a Except for these restrictions (in return for which one is rewarded with faster, smaller code), register identifiers behave as ression\fR .br 7.5.2 \fIexpression \fG>> \fIexpression\fR .et Both operands must be \fGint\fR or \fGchar\fR, and the result is \fGint\fR. The second operand should be non-negative. The value of ``E1<>E2'' is E1 (interpreted as a two's complement, 16-bit quantity) arithmetically right-shifted E2 bit positions. Vacated bits are filled by a copy of the sign bit of E1. [Note: the use of ar \fIlvalue \fG= \fIexpression\fR .et The value of the expression replaces that of the object referred to by the lvalue. The operands need not have the same type, but both must be \fGint\fR, \fGchar\fR, \fGfloat\fR, \fGdouble\fR, or pointer. If neither operand is a pointer, the assignment takes place as expected, possibly preceded by conversion of the expression on the right. .pg When both operands are \fGint\fR or pointers of any kind, no conversion ever takes place; the value of the expression is simply sif they were automatic. In fact implementations of C are free to treat .bd register as synonymous with .bd auto. .pg If the sc-specifier is missing from a declaration, it is generally taken to be \fGauto\fR. .ms 8.2 Type specifiers .et The type-specifiers are .dp 6 type-specifier: \fGint\fR \fGchar\fR \fGfloat \fGdouble struct \fI{ type-decl-list }\fG struct \fIidentifier { type-decl-list }\fG struct \fIidentifier .ed The \fGstruct\fR specifier is discussed in \(sc8.5. If the type-specifier ithmetic rather than logical shift does not survive transportation between machines.] .ms 7.6 Relational operators .et The relational operators group left-to-right, but this fact is not very useful; ``a\fI expression\fR .br .ne 4 7.6.3 \fIexpression \fG<=\fI expression\fR .br .ne 4 7.6.4 \fIexpression \fG>=\fI expression\fR .et The operators < (less than), > (greater than), <= (less thtored into the object referred to by the lvalue. Thus it is possible to generate pointers which will cause addressing exceptions when used. .ms .ta \w'0.00.00 'u 7.14.2 \fIlvalue \fG=+ \fIexpression\fR .br 7.14.3 \fIlvalue \fG=\(mi \fIexpression\fR .br 7.14.4 \fIlvalue \fG=\** \fIexpression\fR .br 7.14.5 \fIlvalue \fG=/ \fIexpression\fR .br 7.14.6 \fIlvalue \fG=% \fIexpression\fR .br 7.14.7 \fIlvalue \fG=>> \fIexpression\fR .br 7.14.8 \fIlvalue \fG=<< \fIexpression\fR .br 7.14.9 \fIlvalue \fG=& \fIexpressiois missing from a declaration, it is generally taken to be \fGint\fR. .ms 8.3 Declarators .et The declarator-list appearing in a declaration is a comma-separated sequence of declarators. .dp 2 declarator-list: declarator declarator \fG,\fI declarator-list .ed The specifiers in the declaration indicate the type and storage class of the objects to which the declarators refer. Declarators have the syntax: .dp 6 declarator: identifier \fG\**\fI declarator declarator \fG( )\fI declarator \fG[ \fIcan or equal to) and >= (greater than or equal to) all yield 0 if the specified relation is false and 1 if it is true. Operand conversion is exactly the same as for the \fG+\fR operator except that pointers of any kind may be compared; the result in this case depends on the relative locations in storage of the pointed-to objects. It does not seem to be very mean$ing$ful to compare pointers with integers other than 0. .ms .ti 0 7.7 Equality operators .et .ne 4 .ti 0 7.7.1 \fIexpression \fG==\fI expression\fn\fR .br .tr ^^ 7.14.10 \fIlvalue \fG=^ \fIexpression\fR .br .tr ^\| 7.14.11 \fIlvalue \fG=^\(or \fIexpression\fR .et The behavior of an expression of the form ``E1@=op@E2'' may be inferred by taking it as equivalent to ``E1@=@E1@op@E2''; however, E1 is evaluated only once. Moreover, expressions like ``i@=+@p'' in which a pointer is added to an integer, are forbidden. .ms 7.15 \fIexpression \fG,\fI expression\fR .et A pair of expressions separated by a comma is evaluated left-to-right and the value of the onstant-expression\*(op \fG] \fG( \fIdeclarator \fG) .ed The grouping in this definition is the same as in expressions. .ms 8.4 Meaning of declarators .et Each declarator is taken to be an assertion that when a construction of the same form as the declarator appears in an expression, it yields an object of the indicated type and storage class. Each declarator contains exactly one identifier; it is this identifier that is declared. .pg If an unadorned identifier appears as a declarator, then it has the tyR .br .ne 4 7.7.2 \fIexpression \fG!=\fI expression\fR .et The \fG==\fR (equal to) and the \fG!=\fR (not equal to) operators are exactly analogous to the relational operators except for their lower precedence. (Thus ``a^b^)? a^:^b^ot explicitly initialized is guaranteed to be 0. .ul 11. Scope rules .et A complete C program need not all be compiled at the same time: the source text of the program may be kept in several files, and precompiled routines may be loaded from libraries. Communication among the functions of a program may be carried out both through explicit calls and through manipulation of external data. .pg Therefore, there are two kinds of scope to consider: first, what may be called the \fIlexical scope\fR of an identifiscanning of the replacement string is attempted. This facility is most valuable for definition of ``manifest constants'', as in .sp .7 .nf .bG # define tabsize 100 .^.^. int table[tabsize]; .sp .7 .eG .fi .ms 12.2 File inclusion .et Large C programs often contain many external data definitions. Since the lexical scope of external definitions extends to the end of the program file, it is good practice to put all the external definitions for data at the start of the program file, so that the functions def; return^(^m^>^c? m^:^c^)^; } .sp .7 .eG .fi Here ``int'' is the type-specifier; ``max(a,@b,@c)'' is the function-declarator; ``int@a,@b,@c;'' is the type-decl-list for the formal parameters; ``{@.^.^.@}'' is the function-statement. .pg C converts all \fGfloat\fR actual parameters to \fGdouble\fR, so formal parameters declared \fGfloat\fR have their declaration adjusted to read \fGdouble\fR. Also, since a reference to an array in any context (in particular as an actual parameter) is taken to mean a pointer, which is essentially the region of a program during which it may be used without drawing ``undefined identifier'' diagnostics; and second, the scope associated with external identifiers, which is characterized by the rule that references to the same external identifier are references to the same object. .ms 11.1 Lexical scope .et C is not a block-structured language; this may fairly be considered a defect. The lexical scope of names declared in external definitions extends from their definition throughined within the file need not repeat tedious and error-prone declarations for each external identifier they use. It is also useful to put a heavily used structure definition at the start and use its structure tag to declare the \fGauto\fR pointers to the structure used within functions. To further exploit this technique when a large C program consists of several files, a compiler control line of the form .dp 1 \fG# include "\fIfilename^\fG" .ed results in the replacement of that line by the entire contentser to the first element of the array, declarations of formal parameters declared ``array of ...'' are adjusted to read ``pointer to ...''. Finally, because neither structures nor functions can be passed to a function, it is useless to declare a formal parameter to be a structure or function (pointers to structures or functions are of course permitted). .pg A free \fGreturn\fR statement is supplied at the end of each function definition, so running off the end causes control, but no value, to be returned to the end of the file in which they appear. The lexical scope of names declared at the head of functions (either as formal parameters or in the declarations heading the statements constituting the function itself) is the body of the function. .pg It is an error to redeclare identifiers already declared in the current context, unless the new declaration specifies the same type and storage class as already possessed by the identifiers. .ms 11.2 Scope of externals .et If a function declares an identifier to be of the file \fIfilename\fR. .pg .ul 13. Implicit declarations .et It is not always necessary to specify both the storage class and the type of identifiers in a declaration. Sometimes the storage class is supplied by the context: in external definitions, and in declarations of formal parameters and structure members. In a declaration inside a function, if a storage class but no type is given, the identifier is assumed to be \fGint\fR; if a type but no storage class is indicated, the identifier is assumed tthe caller. .ms 10.2 External data definitions .et An external data definition has the form .dp 2 data-definition: \fGextern\*(op \fItype-specifier\*(op init-declarator-list\*(op \fG; .ed The optional .ft G extern .ft R specifier is discussed in \(sc 11.2. If given, the init-declarator-list is a comma-separated list of declarators each of which may be followed by an initializer for the declarator. .dp 2 init-declarator-list: init-declarator init-declarator \fG, \fIinit-declarator-list .ed .dp 2 in \fGextern\fR, then somewhere among the files or libraries constituting the complete program there must be an external definition for the identifier. All functions in a given program which refer to the same external identifier refer to the same object, so care must be taken that the type and extent specified in the definition are compatible with those specified by each function which references the data. .pg In \s8PDP\s10-11 C, it is explicitly permitted for (compatible) external definitions of the same ideo be \fGauto\fR. An exception to the latter rule is made for functions, since \fGauto\fR functions are mean$ing$less (C being incapable of compiling code into the stack). If the type of an identifier is ``function returning ...'', it is implicitly declared to be \fGextern\fR. .pg In an expression, an identifier followed by \fG(\fR and not currently declared is contextually declared to be ``function returning \fGint\fR''. .pg Undefined identifiers not followed by \fG(\fR are assumed to be labels which will bit-declarator: declarator initializer\*(op .ed Each initializer represents the initial value for the corresponding object being defined (and declared). .dp 5 initializer: constant { constant-expression-list } .ed .dp 3 constant-expression-list: constant-expression constant-expression \fG,\fI constant-expression-list .ed Thus an initializer consists of a constant-valued expression, or comma-separated list of expressions, inside braces. The braces may be dropped when the expression is just a plainntifier to be present in several of the separately-compiled pieces of a complete program, or even twice within the same program file, with the important limitation that the identifier may be initialized in at most one of the definitions. In other operating systems, however, the compiler must know in just which file the storage for the identifier is allocated, and in which file the identifier is merely being referred to. In the implementations of C for such systems, the appearance of the .ft G extern .ft R ke defined later in the function. (Since a label is not an lvalue, this accounts for the ``Lvalue required'' error message sometimes noticed when an undeclared identifier is used.) Naturally, appearance of an identifier as a label declares it as such. .pg For some purposes it is best to consider formal parameters as belonging to their own storage class. In practice, C treats parameters as if they were automatic (except that, as mentioned above, formal parameter arrays and \fGfloat\fRs are treated specially). constant. The exact meaning of a constant expression is discussed in \(sc15. The expression list is used to initialize arrays; see below. .pg The type of the identifier being defined should be compatible with the type of the initializer: a \fGdouble\fR constant may initialize a \fGfloat\fR or \fGdouble\fR identifier; a non-floating-point expression may initialize an \fGint\fR, \fGchar\fR, or pointer. .pg An initializer for an array may contain a comma-separated list of compile-time expressions. The length eyword before an external definition indicates that storage for the identifiers being declared will be allocated in another file. Thus in a multi-file program, an external data definition without the .ft G extern .ft R specifier must appear in exactly one of the files. Any other files which wish to give an external definition for the identifier must include the .ft G extern .ft R in the definition. The identifier can be initialized only in the file where storage is allocated. .pg In \s8PDP\s10-11 C none of .ul 14. Types revisited .et This section summarizes the operations which can be performed on objects of certain types. .ms 14.1 Structures .et There are only two things that can be done with a structure: pick out one of its members (by means of the \fG^.^\fR or \fG\(mi>\fR operators); or take its address (by unary \fG&\fR). Other operations, such as assigning from or to it or passing it as a parameter, draw an error message. In the future, it is expected that these operations, but not necessarily others,of the array is taken to be the maximum of the number of expressions in the list and the square-bracketed constant in the array's declarator. This constant may be missing, in which case 1 is used. The expressions initialize successive members of the array starting at the origin (subscript 0) of the array. The acceptable expressions for an array of type ``array of ...'' are the same as those for type ``...''. As a special case, a single string may be given as the initializer for an array of \fGchar\fRs; in tthis nonsense is necessary and the .ft G extern .ft R specifier is ignored in external definitions. .ul 12. Compiler control lines .et When a line of a C program begins with the character \fG#\fR, it is interpreted not by the compiler itself, but by a preprocessor which is capable of replacing instances of given identifiers with arbitrary token-strings and of inserting named files into the source program. In order to cause this preprocessor to be invoked, it is necessary that the very first line of the pro will be allowed. .ms 14.2 Functions .et There are only two things that can be done with a function: call it, or take its address. If the name of a function appears in an expression not in the function-name position of a call, a pointer to the function is generated. Thus, to pass one function to another, one might say .bG .sp .7 .nf int f(^^); ... g(^f^); .sp .7 .eG .ft R Then the definition of \fIg \fRmight read .sp .7 .bG g^(^funcp^) int (\**funcp)^(^^); { .^.^. (\**funcp)^(^^); .^.^. } .sp his case, the characters in the string are taken as the initializing values. .pg Structures can be initialized, but this operation is incompletely implemented and machine-dependent. Basically the structure is regarded as a sequence of words and the initializers are placed into those words. Structure initialization, using a comma-separated list in braces, is safe if all the members of the structure are integers or pointers but is otherwise ill-advised. .pg The initial value of any externally-defined object ngram begin with \fG#\fR. Since null lines are ignored by the preprocessor, this line need contain no other information. .ms 12.1 Token replacement .et A compiler-control line of the form .dp 1 \fG# define \fIidentifier token-string .ed (note: no trailing semicolon) causes the preprocessor to replace subsequent instances of the identifier with the given string of tokens (except within compiler control lines). The replacement token-string has comments removed from it, and it is surrounded with blanks. No re.7 .eG .fi Notice that \fIf\fR was declared explicitly in the calling routine since its first appearance was not followed by \fG(\fR^. .ms 14.3 Arrays, pointers, and subscripting .et Every time an identifier of array type appears in an expression, it is converted into a pointer to the first member of the array. Because of this conversion, arrays are not lvalues. By definition, the subscript operator \fG[^]\fR is interpreted in such a way that ``E1[E2]'' is identical to ``\**(^(^E1)^+^(E2^)^)''. Because of the conversion rules which apply to \fG+\fR, if E1 is an array and E2 an integer, then E1[E2] refers to the E2-th member of E1. Therefore, despite its asymmetric appearance, subscripting is a commutative operation. .pg A consistent rule is followed in the case of multi-dimensional arrays. If E is an \fIn^\fR-dimensional array of rank .ft I i^\(mu^j^\(mu^.^.^.^\(muk, .ft R then E appearing in an expression is converted to a pointer to an (\fIn\fR\(mi1)-dimensional array with rank .ft I j^\(mu^.^.^.^\(muk. .f.ul 16. Examples. .et These examples are intended to illustrate some typical C constructions as well as a serviceable style of writing C programs. .ms 16.1 Inner product .et This function returns the inner product of its array arguments. .sp .7 .nf .bG double inner^(^v1, v2, n^)^ double v1^[^^]^, v2^[^^]^; { double sum^; int i^; sum = 0.0^; for ^(^i=0^; itword^)^; p\(mi>count = 1^; p\(mi>right = p\(mi>left = 0^; return^(^p^)^; } /\** Is word repeated? \**/ if ^(^^(^cond=compar^(^p\(mi>tword, word^)^^)^ \fR==\fG 0^)^ { p\(mi>count\fR++\fG^; return^(^p^)^; } /\** Sort into left or right \**/ if ^(^cond<0^)^ p\(mi>left = tree^(^p\(mi>left, word^)^; else p\(mi>right = tree^(^p\(mi>right, word^)^; return^(^p^)^; } /\** \** Print the tree by printing the left subtree, the \ given node, and the right subtree. \**/ tprint^(^p^)^t R If the \fG\**\fR operator, either explicitly or implicitly as a result of subscripting, is applied to this pointer, the result is the pointed-to (\fIn\fR\(mi1)-dimensional array, which itself is immediately converted into a pointer. .pg For example, consider .sp .7 .bG int x[3][5]; .sp .7 .eG Here \fIx\fR is a 3\(mu5 array of integers. When \fIx\fR appears in an expression, it is converted to a pointer to (the first of three) 5-membered arrays of integers. In the expression ``x[^i^]'', which is equivalt, but perhaps a little less clear. It uses the facts that parameter arrays are really pointers, and that all parameters are passed by value. .sp .7 .nf .bG double inner^(^v1, v2, n^)^ double \**v1, \**v2^; { double sum^; sum = 0.0^; while^(^n\fR\fR\(mi\(mi\fG\fG^)^ sum \fR=+\fG \**v1\fR++\fG \** \**v2\fR++\fG^; return^(^sum^)^; } .fi .eG .sp .7 The declarations for the parameters are really exactly the same as in the last example. In the first case array declarations ``^[^^^]^'' were given struct tnode \**p^; { while ^(^p^)^ { tprint^(^p\(mi>left^)^; printf^(^"%d: %s\\n", p\(mi>count, p\(mi>tword^)^; p = p\(mi>right^; } } /\** \** String comparison: return number ^(^>, =, <^)^ 0 \** according as s1 ^(^>, =, <^)^ s2. \**/ compar^(^s1, s2^)^ char \**s1, \**s2^; { int c1, c2^; .sp .5 while^(^^(^c1 = \**s1\fR++\fG^)^ \fR==\fG ^(^c2 = \**s2\fR++\fG^)^^)^ if ^(^c1\fR==\fG\(aa\\0\(aa^)^ return^(^0^)^; return^(^c2\(mic1^)^; } /\** \** String copy: copy s1 into s2 until the null ent to ``\**(x+i)'', \fIx\fR is first converted to a pointer as described; then \fIi\fR is converted to the type of \fIx\fR, which involves multiplying \fIi\fR by the length the object to which the pointer points, namely 5 integer objects. The results are added and indirection applied to yield an array (of 5 integers) which in turn is converted to a pointer to the first of the integers. If there is another subscript the same argument applies again; this time the result is an integer. .pg It follows from all to emphasize that the parameters would be referred to as arrays; in the second, pointer declarations were given because the indirection operator and ++ were used. .ms 16.2 Tree and character processing .et Here is a complete C program ^(^courtesy of R. Haight^)^ which reads a document and produces an alphabetized list of words found therein together with the number of occurrences of each word. The method keeps a binary tree of words such that the left descendant tree for each word has all the words lexico \** character appears. \**/ copy^(^s1, s2^)^ char \**s1, \**s2^; { while^(^\**s2\fR++\fG = \**s1\fR++\fG^)^; } /\** \** Node allocation: return pointer to a free node. \** Bomb out when all are gone. Just for fun, there \** is a mechanism for using nodes that have been \** freed, even though no one here calls "free." \**/ struct tnode \**alloc^(^^)^ { struct tnode \**t^; .sp .5 if ^(^freep^)^ { t = freep^; freep = freep\(mi>left^; return^(^t^)^; } if ^(^\fR\(mi\(mi\fGnnodes < 0^)^ { pri this that arrays in C are stored row-wise (last subscript varies fastest) and that the first subscript in the declaration helps determine the amount of storage consumed by an array but plays no other part in subscript calculations. .ms 14.4 Labels .et Labels do not have a type of their own; they are treated as having type ``array of \fGint\fR''. Label variables should be declared ``pointer to \fGint\fR''; before execution of a \fGgoto\fR referring to the variable, a label (or an expression deriving from agraphically smaller than the given word, and the right descendant has all the larger words. Both the insertion and the printing routine are recursive. .pg The program calls the library routines \fIgetchar\fR to pick up characters and \fIexit\fR to terminate execution. \fIPrintf\fR is called to print the results according to a format string. A version of \fIprintf\fR is given below ^(^\(sc16.3^)^. .pg Because all the external definitions for data are given at the top, no \fGextern\fR declarations are necessantf^(^"Out of space\\n"^)^; exit^(^^)^; } return^(^spacep\fR++\fG^)^; } /\** \** The uncalled routine which puts a node on the free list. \**/ free^(^p^)^ struct tnode \**p^; { p\(mi>left = freep^; freep = p^; } .sp .7 .fi .eG .in 0 To illustrate a slightly different technique of handling the same problem, we will repeat fragments of this example with the tree nodes treated explicitly as members of an array. The fundamental change is to deal with the subscript of the array member under discussion, i label) should be assigned to the variable. .pg Label variables are a bad idea in general; the \fGswitch\fR statement makes them almost always unnecessary. .ul 15. Constant expressions .et In several places C requires expressions which evaluate to a constant: after .ft G case, .ft R as array bounds, and in initializers. In the first two cases, the expression can involve only integer constants, character constants, and .ft G sizeof .ft R expressions, possibly connected by the binary operators .tr ^^ .dp + ry within the functions. To stay within the rules, a type declaration is given for each non-integer function when the function is used before it is defined. However, since all such functions return pointers which are simply assigned to other pointers, no actual harm would result from leaving out the declarations; the supposedly \fGint\fR function values would be assigned without error or complaint. .sp .7 .nf .in .5i .bG .ta .5i 1i 3i # define nwords 100 /\** number of different words \**/ # define wsize 20nstead of a pointer to it. The \fGstruct\fR declaration becomes .sp .7 .nf .bG struct tnode { char tword^[^wsize^]^; int count; int left; int right; }; .fi .eG .sp .7 and \fIalloc\fR becomes .sp .7 .nf .bG alloc^(^^)^ { int t; .sp .5 t = \fR\(mi\(mi\fGnnodes; if ^(^t<=0^)^ { printf^(^"Out of space\\n"^)^; exit^(^^)^; } return^(^t^)^; } .fi .eG .sp .7 The \fIfree\fR stuff has disappeared because if we deal with exclusively with subscripts some sort of map has to be kept, which is \(mi \** / % & \(or ^ << >> .ed or by the unary operators .dp \(mi \*~ .ed .tr ^\| Parentheses can be used for grouping, but not for function calls. .pg A bit more latitude is permitted for initializers; besides constant expressions as discussed above, one can also apply the unary \fG&\fR operator to external scalars, and to external arrays subscripted with a constant expression. The unary \fG&\fR can also be applied implicitly by appearance of unsubscripted external arrays. The rule he /\** max chars per word \**/ struct tnode { /\** the basic structure \**/ char tword^[^wsize^]^; int count^; struct tnode \**left^; struct tnode \**right^; }^; .sp .7 struct tnode space^[^nwords^]^; /\** the words themselves \**/ int nnodes nwords^; /\** number of remaining slots \**/ struct tnode \**spacep space^; /\** next available slot \**/ struct tnode \**freep^; /\** free list \**/ /\** \** The main routine reads words until end-of-file \ ^(^\(aa\\0\(aa returned from "getchar"^)^ \** "tree" is too much trouble. .pg Now the \fItree\fR routine returns a subscript also, and it becomes: .sp .7 .nf .bG tree^(^p, word^)^ char word^[^^]^; { int cond; .sp .5 if ^(^p\fR==\fG0^)^ { p = alloc^(^^)^; copy^(^word, space^[^p^]^.tword^)^; space^[^p^]^.count = 1; space^[^p^]^.right = space^[^p^]^.left = 0; return^(^p^)^; } if ^(^^(^cond=compar^(^space^[^p^]^.tword, word^)^^)^ \fR==\fG 0^)^ { space^[^p^]^.count\fR++\fG; return^(^p^)^; } if ^(^cond<0^)^ space^[^p^]^.left = tre is that initializers must evaluate either to a constant or to the address of an external identifier plus or minus a constant. called to sort each word into the tree. \**/ .ta .5i 1i 1.5i 2i 2.5i 3i main^(^^)^ { struct tnode \**top, \**tree^(^^)^; char c, word^[^wsize^]^; int i^; .sp .5 i = top = 0^; while ^(^c=getchar^(^^)^^)^ if ^(^\(aaa\(aa<=c && c<=\(aaz\(aa \(or\(or \(aaA\(aa<=c && c <=\(aaZ\(aa^)^ { if ^(^i>3^)^&017777^)^; putchar^(^^(^n&07^)^+\(aa0\(aa^)^; } .br .fi .eG .in 0 on of space to move right before plotting. .s3 .lp +5 5 \fBu\fR Next argument is fraction of space to move up before plotting. .s3 .i0 Points are connected by straight line segments in the order they appear in input. If a specified lower limit exceeds the upper limit, or if the automatic increment is negative, the graph is plotted upside down. Automatic abscissas begin with the lower \fIx\fR limit, or with 0 if no limit is specified. Grid lines and automatically determined limits fall on round values, howevnd. .PG We can do both the search for the desired line .ul and a substitution all at once, like this: .X1 /their/s/their/the/p .X2 which will yield .X1 to come to the aid of the party. .X2 There were three parts to that last command: context search for the desired line, make the substitution, print the line. .PG The expression ``/their/'' is a context search expression. In their simplest form, all context search expressions are like this \(mi a string of characters surrounded by slashes. Context searches ar ...ioliber roundness may be subverted by giving an inappropriately rounded lower limit. Plotting symbols specified by .bd c are placed so that a small initial letter, such as + o x, will fall approximately on the plotting point. .sh "SEE ALSO" spline (VI), plot (VI) .sh BUGS A limit of 1000 points is enforced silently. e interchangeable with line numbers, so they can be used by themselves to find and print a desired line, or as line numbers for some other command, like ``s''. We used them both ways in the examples above. .PG Suppose the buffer contains the three familiar lines .X1 Now is the time for all good men to come to the aid of their party. .X2 Then the .ul ed line numbers .X1 /Now/+1 /good/ /party/\(mi1 .X2 are all context search expressions, and they all refer to the same line (line 2). To make a change in line 2 ...xct1ct2ct3ct4ct5ct6ct7ct8ct9ct0instructionsnmacpipepipe.cprintxct1xct2xct3xct4xct5xct6xct7xct8xct9xct0xx  , we could say .X1 /Now/+1s/good/bad/ .X2 or .X1 /good/s/good/bad/ .X2 or .X1 /party/\(mi1s/good/bad/ .X2 The choice is dictated only by convenience. We could print all three lines by, for instance .X1 /Now/,/party/p .X2 or .X1 /Now/,/Now/+2p .X2 or by any number of similar combinations. The first one of these might be better if we don't know how many lines are involved. (Of course, if there were only three lines in the buffer, we'd use .X1 1,$p .X2 but not if there were several hundred.) .PG The basic rule is: a context search expression is .ul the same as a line number, so it can be used wherever a line number is needed. .H1 Exercise 6: .H2 .PG Experiment with context searching. Try a body of text with several occurrences of the same string of characters, and scan through it using the same context search. .PG Try using context searches as line numbers for the substitute, print and delete commands. (They can also be used with ``r'', ``w'', and ``a''.) .PG Try context searching using ``?text?'' instead of ``/mmarize some things about the ``p'' command and dot. Essentially ``p'' can be preceded by 0, 1, or 2 line numbers. If there is no line number given, it prints the ``current line'', the line that dot refers to. If there is one line number given (with or without the letter ``p''), it prints that line (and dot is set there); and if there are two line numbers, it prints all the lines in that range (and sets dot to the last line printed.) If two line numbers are specified the first can't be bigger than the seconlers!) .PG If no line numbers are given, the ``s'' command assumes we mean ``make the substitution on line dot'', so it changes things only on the current line. This leads to the very common sequence .X1 s/something/something else/p .X2 which makes some correction on the current line, and then prints it, to make sure it worked out right. If it didn't, we can try again. (Notice that we put a print command on the same line as the substitute. With few exceptions, ``p'' can follow any command; no other multi-cotext/''. This scans lines in the buffer in reverse order rather than normal. This is sometimes useful if you go too far while looking for some string of characters \(mi it's an easy way to back up. .PG (If you get funny results with any of the characters .X1 ^ \*. $ [ * \\ .X2 read the section on ``Special Characters''.) .PG .ul Ed provides a shorthand for repeating a context search for the same string. For example, the .ul ed line number .X1 /string/ .X2 will find the next occurrence of ``std (see Exercise 2.) .PG Typing a single newline will cause printing of the next line \(mi it's equivalent to ``\*.+1p''. Try it. Try typing ``^'' \(mi it's equivalent to ``\*.\(mi1p''. .H1 Deleting lines: the ``d'' command .H2 .PG Suppose we want to get rid of the three extra lines in the buffer. This is done by the .ul delete command .X1 d .X2 Except that ``d'' deletes lines instead of printing them, its action is similar to that of ``p''. The lines to be deleted are specified for ``d'' exactly as they aremmand lines are legal.) .PG It's also legal to say .X1 s/ . . . // .X2 which means ``change the first string of characters to \fInothing\fR'', i.e., remove them. This is useful for deleting extra words in a line or removing extra letters from words. For instance, if we had .X1 Nowxx is the time .X2 we can say .X1 s/xx//p .X2 to get .X1 Now is the time .X2 Notice that ``//'' here means ``no characters'', not a blank. There .ul is a difference! (See below for another meaning of ``//''.) ring''. It often happens that this is not the desired line, so the search must be repeated. This can be done by typing merely .X1 // .X2 This shorthand stands for ``the most recently used context search expression.'' It can also be used as the first string of the substitute command, as in .X1 /string1/s//string2/ .X2 which will find the next occurrence of ``string1'' and replace it by ``string2''. This can save a lot of typing. Similarly .X1 ?? .X2 means ``scan backwards for the same expression.'' for ``p'': .X1 \fIstarting line, ending line\fP d .X2 Thus the command .X1 4,$d .X2 deletes lines 4 through the end. There are now three lines left, as we can check by using .X1 1,$p .X2 And notice that ``$'' now is line 3! Dot is set to the next line after the last line deleted, unless the last line deleted is the last line in the buffer. In that case, dot is set to ``$''. .H1 Exercise 4: .H2 .PG Experiment with ``a'', ``e'', ``r'', ``w'', ``p'', and ``d'' until you are sure that you know what they do, an.th FORM VI 6/15/72 .sh NAME form \*- form letter generator .sh SYNOPSIS .bd form proto arg ... .sh DESCRIPTION .it Form generates a form letter from a prototype letter, an associative memory, arguments and in a special case, the current date. .s3 If .it form is invoked with the .it proto argument \fIx\fR, the associative memory is searched for an entry with name \fIx\fR and the contents filed under that name are used as the prototype. If the search fails, the message `[\fIx\fR]:' is typed on the console an"% #&d until you understand how dot, ``$'', and line numbers are used. .PG If you are adventurous, try using line numbers with ``a'', ``r'', and ``w'' as well. You will find that ``a'' will append lines .ul after the line number that you specify (rather than after dot); that ``r'' reads a file in .ul after the line number you specify (not necessarily at the end of the buffer); and that ``w'' will write out exactly the lines you specify, not necessarily the whole buffer. These variations are sometimes handy. For d whatever text is typed in from the console, terminated by two new lines, is used as the prototype. If the prototype argument is missing, `{letter}' is assumed. .s3 Basically, .it form is a copy process from the prototype to the output file. If an element of the form [\fIn\fR] (where \fIn\fR is a digit from 1 to 9) is encountered, the \fIn\fR-th .it arg is inserted in its place, and that argument is then rescanned. If [0] is encountered, the current date is inserted. If the desired argument has not been .H1 The current line \(mi ``Dot'' or ``.'' .H2 .PG Suppose our buffer still contains the six lines as above, that we have just typed .X1 1,3p .X2 and .ul ed has printed the three lines for us. Try typing just .X1 p (no line numbers). .X2 This will print .X1 to come to the aid of their party. .X2 which is the third line of the buffer. In fact it is the last (most recent) line that we have done anything with. (We just printed it!) We can repeat this ``p'' command without line numbers, and it will continue to instance you can insert a file at the beginning of a buffer by saying .X1 0r filename .X2 and you can enter lines at the beginning of the buffer by saying .X1 0a .li . . . \fItext\fP . . . .li \fB.\fR .X2 Notice that ``\*.w'' is .ul very different from .X1 .li \fB.\fR w .X2 .H1 Modifying text: the Substitute command ``s'' .H2 .PG We are now ready to try one of the most important of all commands \(mi the substitute command .X1 s .X2 This is the command that is used to change individual words or letters withigiven, a message of the form `[\fIn\fR]:' is typed. The response typed in then is used for that argument. .s3 If an element of the form [\fIname\fR] or {\fIname\fR} is encountered, the \fIname\fR is looked up in the associative memory. If it is found, the contents of the memory under this \fIname\fR replaces the original element (again rescanned). If the \fIname\fR is not found, a message of the form `[\fIname\fR]:' is typed. The response typed in is used for that element. The response is entered in the print line 3. .PG The reason is that .ul ed maintains a record of the last line that we did anything to (in this case, line 3, which we just printed) so that it can be used instead of an explicit line number. This most recent line is referred to by the shorthand symbol .X1 .li \fB.\fR (pronounced ``dot''). .X2 Dot is a line number in the same way that ``$'' is; it means exactly ``the current line'', or loosely, ``the line we most recently did something to.'' We can use it in several ways \(mi one possibilitn a line or group of lines. It is what we use, for example, for correcting spelling mistakes and typing errors. .PG Suppose that by a typing error, line 1 says .X1 Now is th time .X2 \(mi the ``e'' has been left off ``the''. We can use ``s'' to fix this up as follows: .X1 1s/th/the/ .X2 This says: ``in line 1, substitute for the characters `th' the characters `the'.'' To verify that it works (\fIed\fR will not print the result automatically) we say .X1 p .X2 and get .X1 Now is the time .X2 which is what we memory under the name if the name is enclosed in [ ]. The response is not entered in the memory but is remembered for the duration of the letter if the name is enclosed in {}. Brackets and braces may be nested. .s3 In both of the above cases, the response is typed in by entering arbitrary text terminated by two new lines. Only the first of the two new lines is passed with the text. .s3 If one of the special characters [{]}\\ is preceded by a \\, it loses its special character. .s3 If a file named `forma' ay is to say .X1 .li \fB.\fR,$p .X2 This will print all the lines from (including) the current line to the end of the buffer. In our case these are lines 3 through 6. .PG Some commands change the value of dot, while others do not. The print command sets dot to the number of the last line printed; by our last command, we would have ``\*.'' = ``$'' = 6. .PG Dot is most useful when used in combinations like this one: .X1 .li \fB.\fR+1 (or equivalently, \*.+1p) .X2 This means ``print the next line'' and gives uswanted. Notice that dot must have been set to the line where the substitution took place, since the ``p'' command printed that line. Dot is always set this way with the ``s'' command. .PG The general way to use the substitute command is .X1 \fIstarting-line, ending-line\fP s/\fIchange this\fP/\fIto this\fP/ .X2 Whatever string of characters is between the first pair of slashes is replaced by whatever is between the second pair, in .ul all the lines between starting line and ending line. Only the first occurlready exists in the user's directory, `formb' is used as the output file and so forth to `formz'. .s3 The file `form.m' is created if none exists. Because form.m is operated on by the disc allocator, it should only be changed by using .it fed, the form letter editor, or .it form. .s3 .sh FILES form.m associative memory .br form? output file (read only) .sh "SEE ALSO" fed (VI), roff (I) .sh BUGS An unbalanced ] or } acts as an end of file but may add a few strange entries to the associative memory. a handy way to step slowly through a buffer. We can also say .X1 .li \fB.\fR\(mi1 (or \*.\(mi1p ) .X2 which means ``print the line .ul before the current line.'' This enables us to go backwards if we wish. Another useful one is something like .X1 .li \fB.\fR\(mi3,\*.\(mi1p .X2 which prints the previous three lines. .PG Don't forget that all of these change the value of dot. You can find out what dot is at any time by typing .X1 .li \fB.\fR= .X2 .ul Ed will respond by printing the value of dot. .PG Let's surence on each line is changed, however. If you want to change .ul every occurrence, see Exercise 5. The rules for line numbers are the same as those for ``p'', except that dot is set to the last line changed. (But there is a trap for the unwary: if no substitution took place, dot is .ul not changed. This causes an error ``?'' as a warning.) .PG Thus we can say .X1 1,$s/speling/spelling/ .X2 and correct the first spelling mistake on each line in the text. (This is useful for people who are consistent misspel(+.147:=),/25.H1 Writing text out as a file \(mi the Write command ``w'' .H2 .PG It's likely that we'll want to save our text for later use. To write out the contents of the buffer onto a file, we use the .ul write command .X1 w .X2 followed by the filename we want to write on. This will copy the buffer's contents onto the specified file (destroying any previous information on the file). To save the text on a file named ``junk'', for example, type .X1 w junk .X2 Leave a space between ``w'' and the file name. .ul Ed willed the file name wrong. Try alternately reading and appending to see that they work similarly. Verify that .X1 ed filename .X2 is exactly equivalent to .X1 ed e filename .X2 What does .X1 f filename .X2 do? .H1 Printing the contents of the buffer \(mi the Print command ``p'' .H2 .PG To .ul print or list the contents of the buffer (or parts of it) on the terminal, we use the print command .X1 p .X2 The way this is done is as follows. We specify the lines where we want printing to begin and where we want it t contents of the strings with names given by the arguments. .s3 .lp +3 3 .bd q .br returns to the system. .s3 .lp +3 3 .bd c [ .bd p ] [ .bd f ] .br checks the associative memory file for consistency and reports the number of free headers and blocks. The optional arguments do the following: .s3 .lp +6 3 \fBp\fR causes any unaccounted-for string to be printed. .s3 .lp +6 3 \fBf\fR fixes broken memories by adding unaccounted-for headers to free storage and removing references to released headers from associ respond by printing the number of characters it wrote out. In our case, .ul ed would respond with .X1 68 .X2 (Remember that blanks and the newline character at the end of each line are included in the character count.) Writing a file just makes a copy of the text \(mi the buffer's contents are not disturbed, so we can go on adding lines to it. This is an important point. .ul Ed at all times works on a copy of a file, not the file itself. No change in the contents of a file takes place until you give a ``w'o end, separated by a comma, and followed by the letter ``p''. Thus to print the first two lines of the buffer, for example, (that is, lines 1 through 2) we say .X1 1,2p (starting line=1, ending line=2 p) .X2 .ul Ed will respond with .X1 Now is the time for all good men .X2 .PG Suppose we want to print .ul all the lines in the buffer. We could use ``1,3p'' as above if we knew there were exactly 3 lines in the buffer. But in general, we don't know how many there are, so what do we use for the ending line numative memory. .br .i0 .dt .sh FILES /tmp/ftmp? temporary .br form.m associative memory .sh "SEE ALSO" form (VI), ed (I), sh (I) .sh WARNING It is legal but unwise to have string names with blanks, `*' or `?' in them. .sh BUGS ' command. (Writing out the text onto a file from time to time as it is being created is a good idea, since if the system crashes or if you make some horrible mistake, you will lose all the text in the buffer but any text that was written onto a file is relatively safe.) .H1 Leaving ed \(mi the Quit command ``q'' .H2 .PG To terminate a session with .ul ed, save the text you're working on by writing it onto a file using the ``w'' command, and then type the command .X1 q .X2 which stands for .ul quit. The sysber? .ul Ed provides a shorthand symbol for ``line number of last line in buffer'' \(mi the dollar sign ``$''. Use it this way: .X1 1,$p .X2 This will print .ul all the lines in the buffer (line 1 to last line.) If you want to stop the printing before it is finished, push the DEL or Delete key; .ul ed will type .X1 ? .X2 and wait for the next command. .PG To print the .ul last line of the buffer, we could use .X1 $,$p .X2 but .ul ed lets us abbreviate this to .X1 $p .X2 We can print any single line by typin.th FACTOR VI 1/15/73 .sh NAME factor \*- discover prime factors of a number .sh SYNOPSIS .bd factor [ number ] .sh DESCRIPTION When .it factor is invoked without an argument, it waits for a number to be typed in. If you type in a positive number less than 2\u\s756\s0\d (about .if n 7.2e16) .if t 7.2\(mu10\u\s716\s0\d\|) it will factor the number and print its prime factors; each one is printed the proper number of times. Then it waits for another number. It exits if it encounters a zero or any non-numeric tem will respond with ``%''. At this point your buffer vanishes, with all its text, which is why you want to write it out before quitting. .H1 Exercise 1: .H2 .PG Enter .ul ed and create some text using .X1 a .li . . . text . . . .li \fB.\fR .X2 Write it out using ``w''. Then leave .ul ed with the ``q'' command, and print the file, to see that everything worked. (To print a file, say .X1 pr filename .X2 or .X1 cat filename .X2 in response to ``%''. Try both.) .H1 Reading text from a file \(mi the Edit commag the line number followed by a ``p''. Thus .X1 1p .X2 produces the response .X1 Now is the time .X2 which is the first line of the buffer. .PG In fact, .ul ed lets us abbreviate even further: we can print any single line by typing .ul just the line number \(mi no need to type the letter ``p''. So if we say .X1 $ .X2 .ul ed will print the last line of the buffer for us. .PG We can also use ``$'' in combinations like .X1 $\(mi1,$p .X2 which prints the last two lines of the buffer. This helps when we want to character. .s3 If .it factor is invoked with an argument, it factors the number as above and then exits. .s3 Maximum time to factor is proportional to .if n sqrt(n) .if t \(sr\o'\fIn\fR\(rn' and occurs when .it n is prime or the square of a prime. It takes 1 minute to factor a prime near 10\u\s713\s0\d. .sh DIAGNOSTICS `Ouch.' for input out of range or for garbage input. .sh BUGS nd ``e'' .H2 .PG A common way to get text into the buffer is to read it from a file in the file system. This is what you do to edit text that you saved with the ``w'' command in a previous session. The .ul edit command ``e'' fetches the entire contents of a file into the buffer. So if we had saved the three lines ``Now is the time'', etc., with a ``w'' command in an earlier session, the .ul ed command .X1 e junk .X2 would fetch the entire contents of the file ``junk'' into the buffer, and respond .X1 68 .see how far we got in typing. .H1 Exercise 3: .H2 .PG .H2 As before, create some text using the append command and experiment with the ``p'' command. You will find, for example, that you can't print line 0 or a line beyond the end of the buffer, and that attempts to print a buffer in reverse order by saying .X1 3,1p .X2 don't work. .th CUBIC VI 11/1/73 .sh NAME cubic \*- three dimensional tic-tac-toe .sh SYNOPSIS .bd /usr/games/cubic .sh DESCRIPTION .it Cubic plays the game of three dimensional 4\*X4\*X4 tic-tac-toe. .hc ~ Moves are given by the three ~digits (each 1-4) specifying the coordinate of the square to be played. .sh WARNING Too much playing of the game will cause it to disappear. .sh BUGS X2 which is the number of characters in ``junk''. .ul If anything was already in the buffer, it is deleted first. .PG If we use the ``e'' command to read a file into the buffer, then we need not use a file name after a subsequent ``w'' command; .ul ed remembers the last file name used in an ``e'' command, and ``w'' will write on this file. Thus a common way to operate is .X1 ed e file [editing session] w q .X2 .PG You can find out at any time what file name .ul ed is remembering by typing the .ul file comm.th FED VI 1/15/73 .sh NAME fed \*- edit form letter memory .sh SYNOPSIS .bd fed .sh DESCRIPTION .it Fed is used to edit a form letter associative memory file, .bd form.m, which consists of named strings. Commands consist of single letters followed by a list of string names separated by a single space and ending with a new line. The conventions of the Shell with respect to `*' and `?' hold for all commands but \fBm\fR. The commands are: .s3 .lp +3 3 \fBe\fR name ... .br .it Fed writes the string whose name .th COL VI 5/20/74 .sh NAME col \*- filter reverse line feeds .sh SYNOPSIS .bd col .sh DESCRIPTION .it Col reads the standard input and writes the standard output. It performs the line overlays implied by reverse line feeds (ascii code ESC-7). .it Col is particularly useful for filtering multicolumn output made with the `.rt' command of .it nroff. .sh "SEE ALSO" nroff (I) .sh BUGS Can't back up more than 102 lines. and ``f''. In our case, if we typed .X1 f .X2 .ul ed would reply .X1 junk .X2 .H1 Reading text from a file \(mi the Read command ``r'' .H2 .PG Sometimes we want to read a file into the buffer without destroying anything that is already there. This is done by the .ul read command ``r''. The command .X1 r junk .X2 will read the file ``junk'' into the buffer; it adds it to the end of whatever is already in the buffer. So if we do a read after an edit: .X1 e junk r junk .X2 the buffer will contain .ul two copieis .it name onto a temporary file and executes .it ed. On exit from the \fIed\fR the temporary file is copied back into the associative memory. Each argument is operated on separately. Be sure to give an editor .it w command (without a filename) to rewrite .it fed's temporary file before quitting out of .it ed. .s3 .lp +3 3 .bd d [ name ... ] .br deletes a string and its name from the memory. When called with no arguments .bd d operates in a verbose mode typing each string name and deleting only if a .bd y.th CHESS VI 11/1/73 .sh NAME chess \*- the game of chess .sh SYNOPSIS .bd /usr/games/chess .sh DESCRIPTION .it Chess is a computer program that plays class D chess. Moves may be given either in standard (descriptive) notation or in algebraic notation. The symbol `+' is used to specify check; `o-o' and `o-o-o' specify castling. To play black, type `first'; to print the board, type an empty line. .s3 Each move is echoed in the appropriate notation followed by the program's reply. .sh FILES /usr/lib/book opes of the text (six lines). .X1 Now is the time for all good men to come to the aid of their party. Now is the time for all good men to come to the aid of their party. .X2 Like the ``w'' and ``e'' commands, ``r'' prints the number of characters read in, after the reading operation is complete. .PG Generally speaking, ``r'' is much less used than ``e''. .H1 Exercise 2: .H2 .PG Experiment with the ``e'' command \(mi try reading and printing various files. You may get an error ``?'', typically because you spell is typed. A .bd q response returns to \fIfed\fR's command level. Any other response does nothing. .s3 .lp +3 3 .bd m name1 name2 ... .br (move) changes the name of name1 to name2 and removes previous string name2 if one exists. Several pairs of arguments may be given. Literal strings are expected for the names. .s3 .lp +3 3 .bd n [ name ... ] .br (names) lists the string names in the memory. If called with the optional arguments, it just lists those requested. .s3 .lp +3 3 .bd p name ... .br prints thening `book' .sh DIAGNOSTICS The most cryptic diagnostic is `eh?' which means that the input was syntactically incorrect. .sh WARNING Over-use of this program will cause it to go away. .sh BUGS Pawns may be promoted only to queens. CFILORUADGt means ``append (or add) text lines to the buffer, as I type them in.'' Appending is rather like writing fresh material on a piece of paper. .PG So to enter lines of text into the buffer, we just type an ``a'' followed by a newline, followed by the lines of text we want, like this: .X1 a Now is the time for all good men to come to the aid of their party. .li \fB.\fR .X2 .PG The only way to stop appending is to type a line that contains only a period. The ``\*.'' is used to tell .ul ed that we have finished.tr | .th AZEL VI 6/3/74 .sh NAME azel \*- satellite predictions .sh SYNOPSIS .bd azel [ .bd \-d ] [ .bd \-l ] satellite1 [ .bd \-d ] [ .bd \-l ] satellite2 ... .sh DESCRIPTION .it Azel predicts, in convenient form, the apparent trajectories of Earth satellites whose orbital elements are given in the argument files. If a given satellite name cannot be read, an attempt is made to find it in a directory of satellites maintained by the programs's author. The .bd \-d option causes .it azel to ask for a date and.TL A Tutorial Introduction to the \s-2UNIX\s+2 Text Editor .sp .AU B. W. Kernighan .sp .AI Bell Laboratories, Murray Hill, N. J. .nr PS 9 .nr VS 11 .if t .2C .H1 Introduction .H2 .PG .ul Ed is a ``text editor'', that is, an interactive program for creating and modifying ``text'', using directions provided by a user at a terminal. The text is often a document like this one, or a program or perhaps data for a program. .PG This introduction is meant to simplify learning .ul ed. The recommended way to learn .u appending. (Even experienced users forget that terminating ``\*.'' sometimes. If .ul ed seems to be ignoring you, type an extra line with just ``\*.'' on it. You may then find you've added some garbage lines to your text, which you'll have to take out later.) .PG After the append command has been done, the buffer will contain the three lines .X1 Now is the time for all good men to come to the aid of their party. .X2 The ``a'' and ``\*.'' aren't there, because they are not text. .PG To add more text to what read line|1 data (see below) from the standard input. The .bd \-l option causes .it azel to ask for the observer's latitude, west-longitude, and height above sea level. .s3 For each satellite given the program types its full name, the date, and a sequence of lines each containing a time, an azimuth, an elevation, a distance, and a visual magnitude. Each such line indicates that: at the indicated time, the satellite may be seen from Murray Hill (or provided location) at the indicated azimuth and elevation, l ed is to read this document, simultaneously using .ul ed to follow the examples, then to read the description in section I of the .S1 UNIX .S2 manual, all the while experimenting with .ul ed. (Solicitation of advice from experienced users is also useful.) .PG Do the exercises! They cover material not completely discussed in the actual text. An appendix summarizes the commands. .H1 Disclaimer .H2 .PG This is an introduction and a tutorial. For this reason, no attempt is made to cover more than a part of th we already have, just issue another ``a'' command, and continue typing. .H1 Error Messages \(mi ``?'' .H2 .PG If at any time you make an error in the commands you type to .ul ed, it will tell you by typing .X1 ? .X2 This is about as cryptic as it can be, but with practice, you can usually figure out how you goofed. and that its distance and apparent magnitude are as given. Predictions are printed only when the sky is dark (sun more than 5 degrees below the horizon) and when the satellite is not eclipsed by the earth's shadow. Satellites which have not been seen and verified will not have had their visual magnitude level set correctly. .s3 All times input and output by .it azel are GMT (Universal Time). .s3 The satellites for which elements are maintained are: .s3 .lp +10 10 sla,b,e,f,k Skylab A through Skylab K. Skylae facilities that .ul ed offers (although this fraction includes the most useful and frequently used parts). Also, there is not enough space to explain basic .S1 UNIX .S2 procedures. We will assume that you know how to log on to .S1 UNIX, .S2 and that you have at least a vague understanding of what a file is. .PG You must also know what character to type as the end-of-line on your particular terminal. This is a ``newline'' on Model 37 Teletypes, and ``return'' on most others. Throughout, we will refer to th.th CAL VI 11/1/73 .sh NAME cal \*- print calendar .sh SYNOPSIS .bd cal [ month ] year .sh DESCRIPTION .it Cal prints a calendar for the specified year. If a month is also specified, a calendar just for that month is printed. .it Year can be between 1 and 9999. The .it month is a number between 1 and 12. The calendar produced is that for England and her colonies. .s3 Try September 1752. .sh BUGS The year is always considered to start in January even though this is historically naive. b A is the laboratory; B was the rocket but it has crashed. A and probably K have been verified. .s3 .lp +10 10 cop Copernicus I. Never verified. .s3 .lp +10 10 oao Orbiting Astronomical Observatory. Seen and verified. .s3 .lp +10 10 pag Pageos I. Seen and verified; fairly dim (typically 2nd-3rd magnitude), but elements are extremely accurate. .s3 .lp +10 10 exp19 Explorer 19; seen and verified, but quite dim (4th-5th magnitude) and fast-moving. .s3 .lp +10 10 c103b, c156b, c184b, c206b, c220b, c461b, c500bis character, whatever it is, as ``newline''. .H1 Getting Started .H2 .PG We'll assume that you have logged in to .S1 UNIX .S2 and it has just said ``%''. The easiest way to get .ul ed is to type .X1 ed (followed by a newline) .X2 You are now ready to go \(mi .ul ed is waiting for you to tell it what to do. .H1 Creating Text \(mi the Append command ``a'' .H2 .PG As our first problem, suppose we want to create some text starting from scratch. Perhaps we are typing the very first draft of a paper; clearly it .th BJ VI 3/15/72 .sh NAME bj \*- the game of black jack .sh SYNOPSIS .bd /usr/games/bj .sh DESCRIPTION .it Bj is a serious attempt at simulating the dealer in the game of black jack (or twenty-one) as might be found in Reno. The following rules apply: .s3 .lp +5 5 The bet is $2 every hand. .s3 A player `natural' (black jack) pays $3. A dealer natural loses $2. Both dealer and player naturals is a `push' (no money exchange). .s3 If the dealer has an ace up, the player is allowed to make an `insurance' bet a .br Various of the USSR Cosmos series; none seen. .s3 .lp +10 10 7276a Unnamed (satellite # 72-76A); not seen. .s3 .i0 The element files used by .it azel contain five lines. The first line gives a year, month number, day, hour, and minute at which the program begins its consideration of the satellite, followed by a number of minutes and an interval in minutes. If the year, month, and day are 0, they are taken to be the current date (taken to change at 6 A.M. local time). The output report starts at the indwill have to start somewhere, and undergo modifications later. This section will show how to get some text in, just to get started. Later we'll talk about how to change it. .PG When .ul ed is first started, it is rather like working with a blank piece of paper \(mi there is no text or information present. This must be supplied by the person using .ul ed; it is usually done by typing in the text, or by reading it into .ul ed from a file. We will start by typing in some text, and return shortly to how to readgainst the chance of a dealer natural. If this bet is not taken, play resumes as normal. If the bet is taken, it is a side bet where the player wins $2 if the dealer has a natural and loses $1 if the dealer does not. .s3 If the player is dealt two cards of the same value, he is allowed to `double'. He is allowed to play two hands, each with one of these cards. (The bet is doubled also; $2 on each hand.) .s3 If a dealt hand has a total of ten or eleven, the player may `double down'. He may double the bet ($2icated epoch and prints the position of the satellite for the indicated number of minutes at times separated by the indicated interval. This line is ended by two numbers which specify options to the program governing the completeness of the report; they are ordinarily both ``1''. The first option flag suppresses output when the sky is not dark; the second supresses output when the satellite is eclipsed by the earth's shadow. The next line of an element file is the full name of the satellite. The next three files. .PG First a bit of terminology. In .ul ed jargon, the text being worked on is said to be ``kept in a buffer.'' Think of the buffer as a work space, if you like, or simply as the information that you are going to be editing. In effect the buffer is like the piece of paper, on which we will write things, then change some of them, and finally file the whole thing away for another day. .PG The user tells .ul ed what to do to his text by typing instructions called ``commands.'' Most commands consist of a to $4) and receive exactly one more card on that hand. .s3 Under normal play, the player may `hit' (draw a card) as long as his total is not over twenty-one. If the player `busts' (goes over twenty-one), the dealer wins the bet. .s3 When the player `stands' (decides not to hit), the dealer hits until he attains a total of seventeen or more. If the dealer busts, the player wins the bet. .s3 If both player and dealer stand, the one with the largest total wins. A tie is a push. .s3 .i0 The machine deals and kare the elements themselves (including certain derivatives of the elements). .sh FILES /usr/jfo/el/* \*- orbital element files .sh "SEE ALSO" sky (VI) .sh AUTHOR J. F. Ossanna .sh BUGS single letter, which must be typed in lower case. Each command is typed on a separate line. (Sometimes the command is preceded by information about what line or lines of text are to be affected \(mi we will discuss these shortly.) .ul Ed makes no response to most commands \(mi there is no prompting or typing of messages like ``ready''. (This silence is preferred by experienced users, but sometimes a hangup for beginners.) .PG The first command is .ul append, written as the letter .X1 a .X2 all by itself. Ieeps score. The following questions will be asked at appropriate times. Each question is answered by .bd y followed by a new line for `yes', or just new line for `no'. .s3 ? (means, ``do you want a hit?'') .br Insurance? .br Double down? .s3 Every time the deck is shuffled, the dealer so states and the `action' (total bet) and `standing' (total won or lost) is printed. To exit, hit the interrupt key (DEL) and the action and standing will be printed. .sh BUGS .ds . \fB.\fP .tr~ .ds . \fB.\fR . S1 - smaller in text .de S1 .nh .ps -1 .. . S2 - reverse S1 .de S2 .ps +1 .hy .. .de WS .sp \\$1 .. . H1 - start new section .de H1 .SH .. . H2 - after H1 title .de H2 .. . X1 - start of example .de X1 .nf .in +.3i .sp 4p .if t .tr -\(en .. . X2 - end of example .de X2 .sp 4p .tr -- .in -.3i .fi .. .de PG .PP .. ...e0e1e2e3 e4e5e6e7intabsentry. Each entry has the following format: .s3 .lp +24 20 path name 32 bytes .lp +24 20 mode 2 bytes .lp +24 20 uid 1 byte .lp +24 20 gid 1 byte .lp +24 20 unused 1 byte .lp +24 20 size 3 bytes .lp +24 20 time modified 4 bytes .lp +24 20 tape address 2 bytes .lp +24 20 unused 16 bytes .lp +24 20 check sum 2 bytes .s3 .i0 The path name entry is the path name of the file when put on the tape. If the pathname starts with a zero word, the entry is empty. It is at most 32 bytes long and ends in a null byte. Mods table is present only so people can look at it. It does not matter to .it mount if there are duplicated entries nor to .it umount if a name cannot be found. .sh FILES /etc/mtab .sh "SEE ALSO" mount (VIII), umount (VIII) .sh BUGS .th WTMP V 2/22/74 .sh NAME wtmp \*- user login history .sh DESCRIPTION This file records all logins and logouts. Its format is exactly like utmp (V) except that a null user name indicates a logout on the associated typewriter. Furthermore, the typewriter name `~' indicates that the system was rebooted at the indicated time; the adjacent pair of entries with typewriter names `|' and `}' indicate the system-maintained time just before and just after a .it date command has changed the system's idea of the time, uid, gid, size and time modified are the same as described under i-nodes (file system (V)). The tape address is the tape block number of the start of the contents of the file. Every file starts on a block boundary. The file occupies (size+511)/512 blocks of continuous tape. The checksum entry has a value such that the sum of the 32 words of the directory entry is zero. .s3 Blocks 25 (resp. 63) on are available for file storage. .s3 A fake entry (see tp (I)) has a size of zero. .sh "SEE ALSO" file system .th GROUP V 2/10/75 .sh NAME group \*- group file .sh DESCRIPTION .it Group contains for each group the following information: .s3 .lp +10 5 group name .lp +10 5 encrypted password .lp +10 5 numerical group ID .lp +10 5 a comma separated list of all users allowed in the group .s3 .i0 This is an ASCII file. The fields are separated by colons; Each group is separated from the next by a new-line. If the password field is null, no password is demanded. .s3 This file resides in directory /etc. Because of the ence. .s3 .it Wtmp is maintained by login (I) and init (VIII). Neither of these programs creates the file, so if it is removed record-keeping is turned off. It is summarized by ac (VIII). .sh FILES /usr/adm/wtmp .sh "SEE ALSO" utmp (V), login (I), init (VIII), ac (VIII), who (I) (V), tp (I) rypted passwords, it can and does have general read permission and can be used, for example, to map numerical group ID's to names. .sh FILES /etc/group .sh "SEE ALSO" newgrp (I), login (I), crypt (III), passwd (I) .th UTMP V 9/10/73 .sh NAME utmp \*- user information .sh DESCRIPTION This file allows one to discover information about who is currently using UNIX. The file is binary; each entry is 16(10) bytes long. The first eight bytes contain a user's login name or are null if the table slot is unused. The low order byte of the next word contains the last character of a typewriter name. The next two words contain the user's login time. The last word is unused. .sh FILES /etc/utmp .sh "SEE ALSO" init (VIII) and login .th TABS V 6/15/72 .sh NAME tabs \*- set tab stops .sh SYNOPSIS .bd "cat /usr/pub/tabs" .sh DESCRIPTION Printing this file on a suitable terminal sets tab stops every 8 columns. Suitable terminals include the Teletype model 37 and the GE TermiNet 300. .s3 These tab stop settings are desirable because UNIX assumes them in calculating delays. .th GREEK V 10/31/72 .sh NAME greek \*- graphics for extended TTY-37 type-box .sh SYNOPSIS .bd "cat /usr/pub/greek" .sh DESCRIPTION .it Greek gives the mapping from ascii to the ``shift out'' graphics in effect between SO and SI on model 37 Teletypes with a 128-character type-box. It contains: .s3 .nf .if n .ig .ta 1i .3i .75i 1i .3i .75i 1i .3i alpha \(*a A beta \(*b B gamma \(*g \\ GAMMA \(*G G delta \(*d D DELTA \(*D W epsilon \(*e S zeta \(*z Q eta \(*y N THETA \(*H T theta \(*h O lambda \(*l L LAMBDA(I), which maintain the file; who (I), which interprets it. .th PASSWD V 9/10/73 .sh NAME passwd \*- password file .sh DESCRIPTION .it Passwd contains for each user the following information: .s3 .lp +10 5 name (login name, contains no upper case) .lp +10 5 encrypted password .lp +10 5 numerical user ID .lp +10 5 numerical group ID (for now, always 1) .lp +10 5 GCOS job number, box number, optional GCOS user-id .lp +10 5 initial working directory .lp +10 5 program to use as Shell .s3 .i0 This is an ASCII file. Each field within each user's entry is separated from t \(*L E mu \(*m M nu \(*n @ xi \(*c X pi \(*p J PI \(*P P rho \(*r K sigma \(*s Y SIGMA \(*S R tau \(*t I phi \(*f U PHI \(*F F psi \(*q V PSI \(*Q H omega \(*w C OMEGA \(*W Z nabla \(gr [ not \(no \*_ partial \(pd ] integral \(is ^ .. .if t .ig .nf alpha A A | beta B B | gamma \\ \\ GAMMA G G | delta D D | DELTA W W epsilon S S | zeta Q Q | eta N N theta T T | THETA O O | lambda L L LAMBDA E E | mu M M | nu @ @ xi X X | pi J J | PI .th TTYS V 2/11/75 .sh NAME ttys \*- typewriter initialization data .sh DESCRIPTION The .it ttys file is read by the .it init program and specifies which typewriter special files are to have a process created for them which will allow people to log in. It consists of lines of 3 characters each. .s3 The first character is either `0' or `1'; the former causes the line to be ignored, the latter causes it to be effective. The second character is the last character in the name of a typewriter; e.g. \fIx\fR referhe next by a colon. The GCOS field is used only when communicating with that system, and in other installations can contain any desired information. Each user is separated from the next by a new-line. If the password field is null, no password is demanded; if the Shell field is null, the Shell itself is used. .s3 This file resides in directory /etc. Because of the encrypted passwords, it can and does have general read permission and can be used, for example, to map numerical user ID's to names. .sh FILES /eP P rho K K | sigma Y Y | SIGMA R R tau I I | phi U U | PHI F F psi V V | PSI H H | omega C C OMEGA Z Z | nabla [ [ | not _ _ partial ] ] | integral ^ ^ .. .sh "SEE ALSO" ascii (VII) s to the file `/dev/tty\fIx\fR'. The third character is used as an argument to the .it getty program, which performs such tasks as baud-rate recognition, reading the login name, and calling .it login. For normal lines, the character is `0'; other characters can be used, for example, with hard-wired terminals where speed recognition is unnecessary or which have special characteristics. (Getty will have to be fixed in such cases.) .sh FILES /etc/ttys .sh "SEE ALSO" init (VIII), getty (VIII), login (I) tc/passwd .sh "SEE ALSO" login (I), crypt (III), passwd (I), group (V) opsvy|qtwz}.th TP V 9/10/73 .sh NAME tp \*- DEC/mag tape formats .sh DESCRIPTION The command .it tp dumps files to and extracts files from DECtape and magtape. The formats of these tapes are the same except that magtapes have larger directories. .s3 Block zero contains a copy of a stand-alone bootstrap program. See boot procedures (VIII). .s3 Blocks 1 through 24 for DECtape (1 through 62 for magtape) contain a directory of the tape. There are 192 (resp. 496) entries in the directory; 8 entries per block; 64 bytes per .th MTAB V 1/6/74 .sh NAME mtab \*- mounted file system table .sh DESCRIPTION .it Mtab resides in directory .it /etc and contains a table of devices mounted by the .it mount command. .it Umount removes entries. .s3 Each entry is 64 bytes long; the first 32 are the null-padded name of the place where the special file is mounted; the second 32 are the null-padded name of the special file. The special file has all its directories stripped away; that is, everything through the last ``/'' is thrown away. .s3 Thi.th "FILE SYSTEM" V 2/9/75 .sh NAME fs \*- format of file system volume .sh DESCRIPTION Every file system storage volume (e.g. RF disk, RK disk, RP disk, DECtape reel) has a common format for certain vital information. Every such volume is divided into a certain number of 256 word (512 byte) blocks. Block 0 is unused and is available to contain a bootstrap program, pack label, or other information. .s3 Block 1 is the .it "super block." Starting from its first word, the format of a super-block is .s3 .nf struct { int isize; int fsize; int nfree; int free[100]; int ninode; int inode[100]; char flock; char ilock; char fmod; int time[2]; }; .s3 .fi .it Isize is the number of blocks devoted to the i-list, which starts just after the super-block, in block 2. .it Fsize is the first block not potentially available for allocation to a file. These numbers are used by the system to check for bad block numbers; if an ``impossible'' block number is allocated from the free list or is freed, a diagnostic is writtep +15 9 020000 character-type special file .lp +15 9 060000 block-type special file. .lp +10 9 010000 large file .lp +10 9 004000 set user-ID on execution .lp +10 9 002000 set group-ID on execution .lp +10 9 000400 read (owner) .lp +10 9 000200 write (owner) .lp +10 9 000100 execute (owner) .lp +10 9 000070 read, write, execute (group) .lp +10 9 000007 read, write, execute (others) .s3 .i0 Special files are recognized by their flags and not by i-number. A block-type special file is basically one which can pnumber, to aid in (unimplemented) recovery after tape errors. The number of data blocks per file is directly specified by the control word for the file and indirectly specified by the size in the i-node. If these numbers differ, the file was dumped with a `phase error'. .sh "SEE ALSO" dump (VIII), restor (VIII), file system(V) n on the on-line console. Moreover, the free array is cleared, so as to prevent further allocation from a presumably corrupted free list. .s3 The free list for each volume is maintained as follows. The .it free array contains, in .it "free[1], ... , free[nfree\*-1]," up to 99 numbers of free blocks. .it Free[0] is the block number of the head of a chain of blocks constituting the free list. The first word in each free-chain block is the number (up to 100) of free-block numbers listed in the next 100 words ootentially be mounted as a file system; a character-type special file cannot, though it is not necessarily character-oriented. For special files the high byte of the first address word specifies the type of device; the low byte specifies one of several devices of that type. The device type numbers of block and character special files overlap. .s3 The address words of ordinary files and directories contain the numbers of the blocks in the file (if it is small) or the numbers of indirect blocks (if the file i.th DIRECTORY V 9/10/73 .sh NAME dir \*- format of directories .sh DESCRIPTION A directory behaves exactly like an ordinary file, save that no user may write into a directory. The fact that a file is a directory is indicated by a bit in the flag word of its i-node entry. Directory entries are 16 bytes long. The first word is the i-number of the file represented by the entry, if non-zero; if zero, the entry is empty. .s3 Bytes 2-15 represent the (14-character) file name, null padded on the right. These bytesf this chain member. The first of these 100 blocks is the link to the next member of the chain. To allocate a block: decrement .it nfree, and the new block is .it free[nfree]. If the new block number is 0, there are no blocks left, so give an error. If .it nfree became 0, read in the block named by the new block number, replace .it nfree by its first word, and copy the block numbers in the next 100 words into the .it free array. To free a block, check if .it nfree is 100; if so, copy .it nfree and the .it fs large). Byte number .it n of a file is accessed as follows. .it N is divided by 512 to find its logical block number (say .it b ) in the file. If the file is small (flag 010000 is 0), then .it b must be less than 8, and the physical block number is .it addr[b]. .s3 If the file is large, .it b is divided by 256 to yield .it i. If .it i is less than 7, then .it addr[i] is the physical block number of the indirect block. The remainder from the division yields the word in the indirect block which contains th are not cleared for empty slots. .s3 By convention, the first two entries in each directory are for ``\fB.\fR'' and ``\fB..\fR''. The first is an entry for the directory itself. The second is for the parent directory. The meaning of ``\fB..\fR'' is modified for the root directory of the master file system and for the root directories of removable file systems. In the first case, there is no parent, and in the second, the system does not permit off-device references. Therefore in both cases ``\fB..\fR'' hree array into it, write it out, and set .it nfree to 0. In any event set .it free[nfree] to the freed block's number and increment .it nfree. .s3 .it Ninode is the number of free i-numbers in the .it inode array. To allocate an i-node: if .it ninode is greater than 0, decrement it and return .it inode[ninode]. If it was 0, read the i-list and place the numbers of all free inodes (up to 100) into the .it inode array, then try again. To free an i-node, provided .it ninode is less than 100, place its number ie number of the block for the sought-for byte. .s3 If .it i is equal to 7, then the file has become extra-large (huge), and .it addr[7] is the address of a first indirect block. Each word in this block is the number of a second-level indirect block; each word in the second-level indirect blocks points to a data block. Notice that extra-large files are not marked by any mode bit, but only by having .it addr[7] non-zero; and that although this scheme allows for more than 256\*X256\*X512 = 33,554,432 bytes peras the same meaning as ``\fB.\fR''. .sh "SEE ALSO" file system (V) nto .it inode[ninode] and increment .it ninode. If .it ninode is already 100, don't bother to enter the freed i-node into any table. This list of i-nodes is only to speed up the allocation process; the information as to whether the inode is really free or not is maintained in the inode itself. .s3 .it Flock and .it ilock are flags maintained in the core copy of the file system while it is mounted and their values on disk are immaterial. The value of .it fmod on disk is likewise immaterial; it is used as a f file, the length of files is stored in 24 bits so in practice a file can be at most 16,777,216 bytes long. .s3 For block .it b in a file to exist, it is not necessary that all blocks less than .it b exist. A zero block number either in the address words of the i-node or in an indirect block indicates that the corresponding block has never been allocated. Such a missing block reads as if it contained all zero words. .sh "SEE ALSO" icheck, dcheck (VIII) .th CORE V 2/11/75 .sh NAME core \*- format of core image file .sh DESCRIPTION UNIX writes out a core image of a terminated process when any of various errors occur. See .it "signal (II)" for the list of reasons; the most common are memory violations, illegal instructions, bus errors, and user-generated quit signals. The core image is called ``core'' and is written in the process's working directory (provided it can be; normal access controls apply). .s3 The first 1024 bytes of the core image are a copy of lag to indicate that the super-block has changed and should be copied to the disk during the next periodic update of file system information. .s3 .it Time is the last time the super-block of the file system was changed, and is a double-precision representation of the number of seconds that have elapsed since 0000 Jan. 1 1970 (GMT). During a reboot, the .it time of the super-block for the root file system is used to set the system's idea of the time. .s3 I-numbers begin at 1, and the storage for i-nodes begi.th DUMP V 2/11/75 .sh NAME dump \*- incremental dump tape format .sh DESCRIPTION The .it dump and .it restor commands are used to write and read incremental dump magnetic tapes. .s3 The dump tape consists of blocks of 512-bytes each. The first block has the following structure. .s3 .nf struct { int isize; int fsize; int date[2]; int ddate[2]; int tsize; }; .s3 .fi .it Isize, and .it fsize are the corresponding values from the super block of the dumped file system. (See file system (V).) .it Date is ththe system's per-user data for the process, including the registers as they were at the time of the fault. The remainder represents the actual contents of the user's core area when the core image was written. If the text segment is write-protected and shared, it is not dumped; otherwise the entire address space is dumped. .s3 The format of the information in the first 1024 bytes is described by the .it user structure of the system. The important stuff not detailed therein is the locations of the registers. ns in block 2. .tr | Also, i-nodes are 32 bytes long, so 16 of them fit into a block. Therefore, i-node .it i is located in block (\fIi\fR|+|31)|/|16, and begins 32\u\fB.\fR\d((\fIi\fR|+|31)|(mod 16) bytes from its start. I-node 1 is reserved for the root directory of the file system, but no other i-number has a built-in meaning. Each i-node represents one file. The format of an i-node is as follows. .s3 .nf .if t .ta .5i 1.i 2.5i struct { int flags; /* +0: see below */ char nlinks; /* +2: number of linkse date of the dump. .it Ddate is the incremental dump date. The incremental dump contains all files modified between .it ddate and .it date. .it Tsize is the number of blocks per reel. This block checksums to the octal value 031415. .s3 Next there are enough whole tape blocks to contain one word per file of the dumped file system. This is .it isize divided by 16 rounded to the next higher integer. The first word corresponds to i-node 1, the second to i-node 2, and so forth. If a word is zero, then the correHere are their offsets. The parenthesized numbers for the floating registers are used if the floating-point hardware is in single precision mode, as indicated in the status register. .s3 .lp +10 7 fpsr 0004 .lp +10 7 fr0 0006 (0006) .lp +10 7 fr1 0036 (0022) .lp +10 7 fr2 0046 (0026) .lp +10 7 fr3 0056 (0032) .lp +10 7 fr4 0016 (0012) .lp +10 7 fr5 0026 (0016) .lp +10 7 r0 1772 .lp +10 7 r1 1766 .lp +10 7 r2 1750 .lp +10 7 r3 1752 .lp +10 7 r4 1754 .lp +10 7 r5 1756 .lp +10 7 sp 1764 .lp +10 7 pc 1774 to file */ char uid; /* +3: user ID of owner */ char gid; /* +4: group ID of owner */ char size0; /* +5: high byte of 24-bit size */ int size1; /* +6: low word of 24-bit size */ int addr[8]; /* +8: block numbers or device number */ int actime[2]; /* +24: time of last access */ int modtime[2]; /* +28: time of last modification */ }; .dt .fi .s3 The flags are as follows: .s3 .lp +10 9 100000 i-node is allocated .lp +10 9 060000 2-bit file type: .lp +15 9 000000 plain file .lp +15 9 040000 directory .lsponding file exists, but was not dumped. (Was not modified after .it ddate) If the word is \*-1, the file does not exist. Other values for the word indicate that the file was dumped and the value is one more than the number of blocks it contains. .s3 The rest of the tape contains for each dumped file a header block and the data blocks from the file. The header contains an exact copy of the i-node (see file system (V)) and also checksums to 031415. The next-to-last word of the block contains the tape block .lp +10 7 ps 1776 .s3 .i0 In general the debuggers .it "db (I)" and .it "cdb (I)" are sufficient to deal with core images. .sh "SEE ALSO" cdb (I), db (I), signal (II) .th ASCII V 6/12/72 .sh NAME ascii \*- map of ASCII character set .sh SYNOPSIS .bd "cat /usr/pub/ascii" .sh DESCRIPTION .it Ascii is a map of the ASCII character set, to be printed as needed. It contains: .in 2 .nf .cs R 20 |000 nul|001 soh|002 stx|003 etx|004 eot|005 enq|006 ack|007 bel| |010 bs |011 ht |012 nl |013 vt |014 np |015 cr |016 so |017 si | |020 dle|021 dc1|022 dc2|023 dc3|024 dc4|025 nak|026 syn|027 etb| |030 can|031 em |032 sub|033 esc|034 fs |035 gs |036 rs |037 us | |040 sp |041 ! |042 "n have been removed by .it strip. .s3 The header always contains 8 words: .s3 .lp +5 3 1 A magic number (407, 410, or 411(8)) .lp +5 3 2 The size of the program text segment .lp +5 3 3 The size of the initialized portion of the data segment .lp +5 3 4 The size of the uninitialized (bss) portion of the data segment .lp +5 3 5 The size of the symbol table .lp +5 3 6 The entry location (always 0 at present) .lp +5 3 7 Unused .lp +5 3 8 A flag indicating relocation bits have been suppressed .s3 .i0 The sizes ofby the text or data word associated with the relocation word: .s3 .lp +6 3 00 indicates the reference is absolute .lp +6 3 02 indicates the reference is to the text segment .lp +6 3 04 indicates the reference is to initialized data .lp +6 3 06 indicates the reference is to bss (uninitialized data) .lp +6 3 10 indicates the reference is to an undefined external symbol. .i0 .s3 Bit 0 of the relocation word indicates if .it on that the reference is relative to the pc (e.g. ``clr x''); if .it off, that the refe |043 # |044 $ |045 % |046 & |047 \*a | |050 ( |051 ) |052 * |053 + |054 , |055 \*- |056 . |057 / | |060 0 |061 1 |062 2 |063 3 |064 4 |065 5 |066 6 |067 7 | |070 8 |071 9 |072 : |073 ; |074 < |075 = |076 > |077 ? | |100 @ |101 A |102 B |103 C |104 D |105 E |106 F |107 G | |110 H |111 I |112 J |113 K |114 L |115 M |116 N |117 O | |120 P |121 Q |122 R |123 S |124 T |125 U |126 V |127 W | |130 X |131 Y |132 Z |133 [ |134 \\ |135 ] |136 ^ |137 \*_ | each segment are in bytes but are even. The size of the header is not included in any of the other sizes. .s3 When a file produced by the assembler or loader is loaded into core for execution, three logical segments are set up: the text segment, the data segment (with uninitialized data, which starts off as all 0, following initialized), and a stack. The text segment begins at 0 in the core image; the header is not loaded. If the magic number (word 0) is 407, it indicates that the text segment is not to berence is to the actual symbol (e.g., ``clr *$x''). .s3 The remainder of the relocation word (bits 15-4) contains a symbol number in the case of external references, and is unused otherwise. The first symbol is numbered 0, the second 1, etc. .sh "SEE ALSO" as (I), ld (I), strip (I), nm (I) |140 \*g |141 a |142 b |143 c |144 d |145 e |146 f |147 g | |150 h |151 i |152 j |153 k |154 l |155 m |156 n |157 o | |160 p |161 q |162 r |163 s |164 t |165 u |166 v |167 w | |170 x |171 y |172 z |173 { |174 | |175 } |176 ~ |177 del| .fi .i0 .cs R .sh FILES found in /usr/pub write-protected and shared, so the data segment is immediately contiguous with the text segment. If the magic number is 410, the data segment begins at the first 0 mod 8K byte boundary following the text segment, and the text segment is not writable by the program; if other processes are executing the same file, they will share the text segment. If the magic number is 411, the text segment is again pure, write-protected, and shared, and moreover instruction and data space are separated; the text and data s.th ARCHIVE V 9/10/73 .sh NAME ar \*- archive (library) file format .sh DESCRIPTION The archive command .it ar is used to combine several files into one. Archives are used mainly as libraries to be searched by the link-editor .it ld. .s3 A file produced by .it ar has a magic number at the start, followed by the constituent files, each preceded by a file header. The magic number is 177555(8) (it was chosen to be unlikely to occur anywhere else). The header of each file is 16 bytes long: .s3 .lp +13 8 0-7 filegment both begin at location 0. See the 11/45 handbook for restrictions which apply to this situation. .s3 The stack will occupy the highest possible locations in the core image: from 177776(8) and growing downwards. The stack is automatically extended as required. The data segment is only extended as requested by the .it break system call. .s3 The start of the text segment in the file is 20(8); the start of the data segment is 20+S\s6\dt\u\s10 (the size of the text) the start of the relocation information.th TTY IV 5/27/74 .sh NAME tty \*- general typewriter interface .sh DESCRIPTION This section describes both a particular special file, and the general nature of the typewriter interface. .s3 The file .it /dev/tty is, in each process, a synonym for the control typewriter associated with that process. It is useful for programs or Shell sequences which wish to be sure of writing messages on the typewriter no matter how output has been redirected. It can also be used for programs which demand a file name for oe name, null padded on the right .lp +13 8 8-11 modification time of the file .lp +13 8 12 user ID of file owner .lp +13 8 13 file mode .lp +13 8 14-15 file size .s3 .i0 Each file begins on a word boundary; a null byte is inserted between files if necessary. Nevertheless the size give reflects the actual size of the file exclusive of padding. .s3 Notice there is no provision for empty areas in an archive file. .sh "SEE ALSO" ar (I), ld (I) .sh BUGS Names are only 8 characters, not 14. More important, there is 20+S\s6\dt\u\s10+S\s6\dd\u\s10; the start of the symbol table is 20+2(S\s6\dt\u\s10+S\s6\dd\u\s10) if the relocation information is present, 20+S\s6\dt\u\s10+S\s6\dd\u\s10 if not. .s3 The symbol table consists of 6-word entries. The first four words contain the ASCII name of the symbol, null-padded. The next word is a flag indicating the type of symbol. The following values are possible: .s3 .lp +6 3 00 undefined symbol .lp +6 3 01 absolute symbol .lp +6 3 02 text segment symbol .lp +6 3 03 data segmenutput, when typed output is desired and it is tiresome to find out which typewriter is currently in use. .s3 As for typewriters in general: all of the low-speed asynchronous communications ports use the same general interface, no matter what hardware is involved. The remainder of this section discusses the common features of the interface; the KL, DC, and DH writeups (IV) describe peculiarities of the individual devices. .s3 When a typewriter file is opened, it causes the process to wait until a connection isn't enough room to store the proper mode, so .it ar always extracts in mode 666. t symbol .lp +6 3 37 file name symbol (produced by ld) .lp +6 3 04 bss segment symbol .lp +6 3 40 undefined external (.globl) symbol .lp +6 3 41 absolute external symbol .lp +6 3 42 text segment external symbol .lp +6 3 43 data segment external symbol .lp +6 3 44 bss segment external symbol .i0 .s3 Values other than those given above may occur if the user has defined some of his own instructions. .s3 The last word of a symbol table entry contains the value of the symbol. .s3 If the symbol's type is undefineis established. In practice user's programs seldom open these files; they are opened by .it init and become a user's input and output file. The very first typewriter file open in a process becomes the .it "control typewriter" for that process. The control typewriter plays a special role in handling quit or interrupt signals, as discussed below. The control typewriter is inherited by a child process during a .it fork. .s3 A terminal associated with one of these files ordinarily operates in full-duplex mode.d external, and the value field is non-zero, the symbol is interpreted by the loader .it ld as the name of a common region whose size is indicated by the value of the symbol. .s3 The value of a word in the text or data portions which is not a reference to an undefined external symbol is exactly that value which will appear in core when the file is executed. If a word in the text or data portion involves a reference to an undefined external symbol, as indicated by the relocation bits for that word, then the Characters may be typed at any time, even while output is occurring, and are only lost when the system's character input buffers become completely choked, which is rare, or when the user has accumulated the maximum allowed number of input characters which have not yet been read by some program. Currently this limit is 256 characters. When the input limit is reached all the saved characters are thrown away without notice. .s3 These special files have a number of modes which can be changed by use of the .it.th A.OUT V 9/9/73 .sh NAME a.out \*- assembler and link editor output .sh DESCRIPTION .it A.out is the output file of the assembler .it as and the link editor .it ld. Both programs make .it a.out executable if there were no errors and no unresolved external references. .s3 This file has four sections: a header, the program and data text, a symbol table, and relocation bits (in that order). The last two may be empty if the program was loaded with the ``\*-s'' option of .it ld or if the symbols and relocatiovalue of the word as stored in the file is an offset from the associated external symbol. When the file is processed by the link editor and the external symbol becomes defined, the value of the symbol will be added into the word in the file. .s3 If relocation information is present, it amounts to one word per word of program text or initialized data. There is no relocation information if the ``suppress relocation'' flag in the header is on. .s3 Bits 3-1 of a relocation word indicate the segment referred to stty system call (II). When first opened, the interface mode is 300 baud; either parity accepted; 10 bits/character (one stop bit); and newline action character. Modes that can be changed by .it stty include the interface speed (if the hardware permits); acceptance of even parity, odd parity, or both; a raw mode in which all characters may be read one at a time; a carriage return (CR) mode in which CR is mapped into newline on input and either CR or line feed (LF) cause echoing of the sequence LF-CR; mapping of upper case letters into lower case; suppression of echoing; a variety of delays after function characters; and the printing of tabs as spaces. See .it getty (VIII) for the way that terminal speed and type are detected. .s3 Normally, typewriter input is processed in units of lines. This means that a program attempting to read will be suspended until an entire line has been typed. Also, no matter how many characters are requested in the read call, at most one line will be returned. It is not however need on output. The EOT character is not transmitted (except in raw mode) to prevent terminals which respond to it from hanging up. .sh FILES /dev/tty .sh "SEE ALSO" dc (IV), kl (IV), dh (IV), getty (VIII), stty (I, II), gtty (I, II), signal (II) .sh BUGS Half-duplex terminals are not supported. On raw-mode output, parity should be transmitted as specified in the characters written. hie). Bell Laboratories internal memorandum. An excellent reference, but a bit heavy going for the beginner, especially one who has never used a language like C. .if t .sp 5p .I Others: .R .if t .sp 5p D. M. Ritchie, UNIX Assembler Reference Manual. .sp 2p B. W. Kernighan and L. L. Cherry, A System for Typesetting Mathematics, Computing Science Tech. Rep. 17. .sp 2p M. E. Lesk and B. A. Barres, The GCOS C Library. Bell Laboratories internal memorandum. .sp 2p K. Thompson and D. M. Ritchie, Setting Up UNIX. cessary to read a whole line at once; any number of characters may be requested in a read, even one, without losing information. .s3 During input, erase and kill processing is normally done. By default, the character `#' erases the last character typed, except that it will not erase beyond the beginning of a line or an EOT. By default, the character `@' kills the entire line up to the point where it was typed, but not beyond an EOT. Both these characters operate on a keystroke basis independently of any ba.sp 3 .SH Index Index .LP .sp 2 .nf & (asynchronous process) 8 ; (multiple processes) 8 * (pattern match) 5 [ ] (pattern match) 6 ? (pattern match) 6 <> (redirect I/O) 7 >> (file append) 12 backslash (\\) 2 cat (concatenate files) 4 cdb (C debugger) 12 chdir (change directory) 7 chmod (change protection) 7 command arguments 4 command files 8 cp (copy files) 5 cref (cross reference) 11 date 2 db (assembly debugger) 13 delete (DEL) 2 diff (file comparison) 11 directories 7 document format.sp 2p M. D. McIlroy, UNIX Summary. .sp 2p D. M. Ritchie, The UNIX I/O System. .sp 2p A. D. Hall, The M6 Macro Processor, Computing Science Tech. Rep. 2. .sp 2p J. F. Ossanna, NROFF User's Manual _ Second Edition, Bell Laboratories internal memorandum. .sp 2p D. M. Ritchie and K. Thompson, Regenerating System Software. .sp 2p B. W. Kernighan, Ratfor_A Rational Fortran, Bell Laboratories internal memorandum. .sp 2p M. D. McIlroy, Synthetic English Speech by Rule, Computing Science Tech. Rep. 14. .sp 2p M. D.ckspacing or tabbing that may have been done. Either `@' or `#' may be entered literally by preceding it by `\\'; the erase or kill character remains, but the `\\' disappears. These two characters may be changed to others. .s3 When desired, all upper-case letters are mapped into the corresponding lower-case letter. The upper-case letter may be generated by preceding it by `\\'. In addition, the following escape sequences are generated on output and accepted on input: .s3 .lp +14 7 for use .lp +15 7 \*g \\\*ting 9 ed (editor) 3 editor programming 11 EOT (end of file) 3 eqn (mathematics) 11 erase character (#) 2 file system structure 6 filenames 5 file protection 7 goto 12 grep (pattern matching) 11 if (condition test) 12 index 14 kill a program 8 kill a character (@) 2 lil (high-level assembler) 13 login 1 logout 2 ls (list file names) 4 macro for formatting 10 mail 2 multi-columns printing (pr) 5 mv (move files) 5 nroff 9 on-line manual 3 opr (offline print) 5 pathname 6 pattern mat McIlroy, Bell Laboratories internal memorandum. .sp 2p J. F. Ossanna, TROFF Users' Manual, Bell Laboratories internal memorandum. .sp 2p B. W. Kernighan, TROFF Made Trivial, Bell Laboratories internal memorandum. .sp 2p R. H. Morris and L. L. Cherry, Computer Detection of Typographical Errors, Computing Science Tech. Rep. 18. .sp 2p S. C. Johnson, YACC (Yet Another Compiler-Compiler), Bell Laboratories internal memorandum. .sp 2p P. J. Plauger, Programming in LIL: A Tutorial, Bell Laboratories internal mema .lp +15 7 .br | \\! .br .tr ?? .lp +15 7 ~ \\^ .lp +15 7 { \\( .lp +15 7 } \\) .s3 .i0 In raw mode, the program reading is awakened on each character. No erase or kill processing is done; and the EOT, quit and interrupt characters are not treated specially. The input parity bit is passed back to the reader, but parity is still generated for output characters. .s3 The ASCII EOT (control-D) character may be used to generate an end of file from a typewriter. When an EOT is received, all the characters waitinch in filenames 5 pipes ( | ) 8 pr (print files) 4 prof (run-time monitor) 13 protection 7 ptx (permuted index) 11 pwd (working directory) 7 quotes 6 ratfor (decent Fortran) 13 readahead 2 reading list 13 redirect I/O (<>) 7 RETURN key 1 rm (remove files) 5 rmdir (remove directory) 7 roff (text formatting) 9 root (of file system) 6 shell (command interpreter) 8 shell arguments ($) 12 shell programming 12 shift (shell arguments) 12 sleep 12 sort 11 spell (find spelling mistakes) stoppiorandum. g to be read are immediately passed to the program, without waiting for a new-line, and the EOT is discarded. Thus if there are no characters waiting, which is to say the EOT occurred at the beginning of a line, zero characters will be passed back, and this is the standard end-of-file indication. The EOT is passed back unchanged in raw mode. .s3 When the carrier signal from the dataset drops (usually because the user has hung up his terminal) a .it hangup signal is sent to all processes with the typewriter ng a program 2 stty (set terminal options) 2 tabs (set tab stops) 2 terminal types 1 time (time programs) 13 tr (translate characters) 11 troff (typesetting) 9 typo (find spelling mistakes) 11 wc (word count) 11 who (who is looged in) 2 write (to a user) 3 yacc (compiler-compiler) 13 as control typewriter. Unless other arrangements have been made, this signal causes the processes to terminate. If the hangup signal is ignored, any read returns with an end-of-file indication. Thus programs which read a typewriter and test for end-of-file on their input can terminate appropriately when hung up on. .s3 Two characters have a special meaning when typed. The ASCII DEL character (sometimes called `rubout') is not passed to a program but generates an .it interrupt signal which is sent to all pro.SH .tr ~ V.~~UNIX READING LIST .PP .ti 0 .br .I General: .R .if t .sp 5p .UC UNIX Programmer's Manual (Ken Thompson, Dennis Ritchie, and a cast of thousands). Lists commands, system routines and interfaces, file formats, and some of the maintenance procedures. You can't live without this, although you will probably only read section I. .if t .sp 5p The .UC UNIX Time-sharing System (Ken Thompson, Dennis Ritchie). CACM, July 1974. An overview of the system, for people interested in operating systems. Worth r.SH IV. PROGRAMMING .PP .UC UNIX is a marvelously pleasant and productive system for writing programs; productivity seems to be an order of magnitude higher than on other interactive systems. .PP There will be no attempt made to teach any of the programming languages available on .UC UNIX , but a few words of advice are in order. First, .UC UNIX is written in C, as is most of the applications code. If you are undertaking anything substantial, C is the only reasonable choice. More on that in a moment. But rcesses with the associated control typewriter. Normally each such process is forced to terminate, but arrangements may be made either to ignore the signal or to receive a trap to an agreed-upon location. See .it signal (II). .s3 The ASCII character FS generates the .it quit signal. Its treatment is identical to the interrupt signal except that unless a receiving process has made other arrangements it will not only be terminated but a core image file will be generated. If you find it hard to type this characeading by anyone who programs. Contains a remarkable number of one-sentence observations on how to do things right. .if t .sp 5p .I Document Preparation: .R .if t .sp 5p A Tutorial Introduction to the .UC UNIX Text Editor. (Brian Kernighan). Bell Laboratories internal memorandum. Weak on the more esoteric uses of the editor, but still probably the easiest way to learn .C ed . .if t .sp 5p Typing Documents on .UC UNIX. (Mike Lesk). Bell Laboratories internal memorandum. A macro package to isolate the novice emember that there are quite a few programs already written, some of which have substantial power. .PP The editor can be made to do things that would normally require special programs on other systems. For example, to list the first and last lines of each of a set of files, say a book, you could laboriously type .B1 ed e chap1.1 1p $p e chap1.2 1p $p etc. .B2 But instead you can do the job once and for all. Type .B1 ls chap* >temp .B2 to get the list of filenames into a file. Then edit this file to make thter, try control-\\ or control-shift-L. .s3 When one or more characters are written, they are actually transmitted to the terminal as soon as previously-written characters have finished typing. Input characters are echoed by putting them in the output queue as they arrive. When a process produces characters more rapidly than they can be typed, it will be suspended when its output queue exceeds some limit. When the queue has drained down to some threshold the program is resumed. Even parity is always generatfrom the vagaries of the formatting programs. If this specific package isn't available on your system, something similar probably is. This one works with both .C nroff and .C troff . .if t .sp 5p .I Programming: .R .if t .sp 5p Programming in C: A Tutorial (Brian Kernighan). Bell Laboratories internal memorandum. The easiest way to start learning C, but it's no help at all with the interface to the system beyond the simplest IO. Should be read in conjunction with .if t .sp 5p C Reference Manual (Dennis Ritce necessary series of editing commands (using the global commands of .C ed ), and write it into ``script''. Now the command .B1 ed