Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Posting-Version: version B 2.10.1 6/24/83; site udenva.UUCP Path: utzoo!watmath!clyde!burl!ulysses!mhuxl!ihnp4!drutx!houxe!hogpc!houti!ariel!vax135!cornell!uw-beaver!tektronix!hplabs!hao!denelcor!udenva!jkcohen From: jkcohen@udenva.UUCP Newsgroups: net.general Subject: Critique of 4.2BSD Documentation (Vol I) Message-ID: <231@udenva.UUCP> Date: Thu, 2-Aug-84 00:23:22 EDT Article-I.D.: udenva.231 Posted: Thu Aug 2 00:23:22 1984 Date-Received: Sun, 22-Jul-84 03:16:15 EDT Organization: U of Denver Lines: 1651 CRITIQUE of the BERKELEY 4.2 UNIX DOCUMENTATION - Volume I by Jack K. Cohen July 19, 1984 Copyright 1984 by Jack K. Cohen BSD4.2 -1- Permission to copy all or part of this material is granted provided that the copies are not made or distributed for direct commercial advantage, the author's copyright notice and the title of the article and its date appear, and notice is given that copying is by permission of the author. To copy otherwise, or to republish, requires a fee and/or specific permission. J. K. Cohen BSD4.2 -2- _I_n_t_r_o_d_u_c_t_i_o_n Just when you thought it was safe to forget "The Berkeley Critique", here comes the second, improved, giant economy size version! More importantly, this edition concerns the BSD4.2 distribution, whereas last year's version was about BSD4.1. Once more let me state that this Critique emphasizes documentation problems rather than BSD4.2 software problems. However, suggestions about possible improvements to the latter are jabbed in here and there. The Critique will appear in two parts, corresponding to Volume I and Volume IIc (there is a limit to what I can risk nroffing in one shot without losing the super-user's good will). My purpose is not to denigrate the work of the people at Berkeley or at Bell (though I am not above teasing at times), but only to provide local enhancement to their splendid efforts. Since I can report on only what I know, be aware that the effects recorded herein are descriptions of the local University of Denver implementation of BSD4.2. In cases where I know our implementation to be specialized (e.g. effects caused by the local choices for Mailrc), I will make that clear. I can only hope that my local readers have caught any remaining instances of erroneously attributing 'mis-documentation' instead of 'local variation.' For maximum enjoyment, I recommend having a hard copy manual near at hand while reading these notes. You will notice that there is lots of good stuff there in addition to the nits picked by this Critique. Being of impulsive cast, no doubt I have amply displayed my ignorance below. I have never been troubled by being wrong; life is too short to stand on ceremony. I await your blunt refutations and explanations. For several years, my first source of technical UNIX/C information has been Andrew Burt, a graduate student at the University of Denver. He has been kind enough to continue tracking down puzzling items which cropped up during the writing of these notes. I have also gotten valuable ideas from several other students: Craig Ruff, Brian Sumner and Matt Taylor. Also among the contributors to and critics of these notes are various present and past members of the University of Denver Computing Services including the 'Three Bobs' (Shafer, Stocker and Ware), Carol Ward, and especially, my first UNIX teacher, Howard Lasus. However, none of my consultants are to be blamed for the remaining errors in these notes; they rest (light-heartedly) with me. J. K. Cohen BSD4.2 -3- _P_r_o_g_r_a_m_m_e_r'_s _M_a_n_u_a_l: _S_e_c_t_i_o_n _1 adb On page 1 the last word - ADDRESSES - in the DESCRIPTION should be enlarged to: "For further details of address mapping see ADDRESSES." (The reference is to a later section on page 5 of "man adb"). On page 4, the parenthetical in the description of $c - (broken on the VAX) - is either opaque or incomplete. What has happened to the adb tutorial? The only remaining hint of its existence is in /usr/doc/run. basename Calling the shell example, 'base' and evoking it with the suggested argument, 'base /usr/src/bin/cat.c', produced: 0: No source file /usr/src/bin/cat.c mv: cannot access a.out Since /usr/src is a 'Permission denied' directory, I could not investigate further. Since source code is unlikely to be available to the vast majority of UNIX users, a different example argument should be given. binmail Why is this command included in BSD4.2? cal See Kernighan and Pike's "The UNIX Programming Environment" for a shell providing a friendly interface to this utility. calendar Calendar service is erratic locally. If you want to get daily reminders, you might start an infinite loop of your own. Prepare a file, 'earlyam': #! /bin/sh # From K & P # To start this infinite loop: earlyam # To stop this process: edit the /usr/spool/at file, to cause an abort file=/usr/tmp/cal.$$ /usr/bin/calendar >$file if /bin/test -s $file then /usr/ucb/mail jkcohen <$file fi /bin/rm $file /bin/echo earlyam | at 5am J. K. Cohen BSD4.2 -4- and issue the command: % earlyam to launch your service. The first time it comes right back, but thereafter, the service sends you mail once a day at 5 am. Remember, you have to prepare a 'calendar file' as described on the manual page. cat The command line "cat a b >a" mentioned in the BUG now evokes the error message: "cat: input is output." But, of course, the shell gets there first and file a is still wiped out. Similarly for "cat a b >b". Even the dreaded "cat * >>x" now does no harm to the system. Cat with no arguments does not echo back to the terminal at each newline. The manual says that when the standard output is a terminal, the output is line buffered. I take that to mean that each line input, should be echoed after the NEWLINE. Since 'cat -u' _d_o_e_s echo back to the terminal, the problem is likely that some undocumented buffering is going on. Perhaps usages such as 'cat -vt file ...' should be acceptable as per Kernighan and Ritchie, page 112-113. In fact, this flexible acceptance of flag arguments should be uniformly extended to all appropriate commands. cb It seems inconsistent with the vast majority of UNIX software that this command does not accept command line arguments. cc I don't understand why some of the options accepted on the command line by 'cc' are not discussed on the 'cc' manual page, but instead are deferred to the 'ld' page. In particular the -s option should be mentioned. There may well be some distinction apparent to the expert, but I vote for all the items which may be on the 'cc' command line being discussed on the 'cc' manual page. chfn Should be made more universally applicable. compact Compact violates the UNIX rule about not being "chatty." This seems like a case of the author being so proud of the algorithm's effectiveness that he must brag each and every time about the degree of compaction. Seems harmless? Well, suppose the system is overloaded, so just before logout you go: nohup compact file1 file2 file2 & J. K. Cohen BSD4.2 -5- and log out. Next login, you find the files: file1 file1.C file2 file3 In addition to the "strange" failure of file2 and file3 to get compacted, the file1.C which _l_o_o_k_s like it is the compaction of file1, really will _n_o_t be recognized by 'uncompact' as a compacted file! Thus if the naive user deletes file1 before checking, he's in real trouble. Even online the messages can be a nuisance. If you go: compact file1 file2 & when file1 finishes compacting, the action stops until you bring it into foreground to deliver its message. Then the second compaction launches off in foreground, so you have to stop it and stick it in background so you can continue with your real foreground job. If you still remember what that was. The "RESTRICTION" of keeping files less than 13 characters, so as to have room for the .C is quaint. In BSD4.2, less than 254 characters would be more like it. Thus, I think we could safely delete the RESTRICTION section. Uncompact and ccat should be forgiving when you fail to type the final .C. Also, "compact" is a lot to type, why not something like "pack"? (Yes, you could use "alias", but every alias slows down your C shells.) csh The header line: #! /bin/csh unambiguously specifies that a shell program is to be executed in C shell. It also serves as an important comment to the same effect. See execve(2). On page 14, "then" is omitted from the list of built- ins. On page 17, "term" and "user" are omitted from the list of pre-defined and environmental variables. The discussion of the "prompt" variable seems wrong to me. If you want just the event number as a prompt, J. K. Cohen BSD4.2 -6- then as per the discussion: set prompt=! does the job. But set prompt= also gives the same prompt, whereas the manual implies that you will _n_o_t get the event number in this case. Similarly, the command set prompt='\!: ' gives a prompt consisting of event number, colon, space. Moreover, in the immortal phrasing from Bell: set prompt='!: ' _n_o_t have the effect intended.' One subtle point in all this is that if ! is followed by a blank, tab, newline, equal sign or left parenthesis then it loses its history connotation. So, for example, set prompt='! ' works just fine. In the BUGS subsection, the alias facility is deprecated vs. the use of Shell files. The user is left uncertain whether something like 'alias del rm -i' is a good or bad way to proceed. It's time someone wrote an essay on what aliases and such cost in response time (and yours truly just might throw caution to the winds and attempt it). For now, a small tip: things you use only in your login shell, should go in .login instead of .cshrc. Even if (like aliases) they "logically" seem associated with C shell. Request: provide some way of turning off history's echoing of the interpreted command. My personal need for this concerns sending my serial printer a local escape sequence to toggle it on. I send that sequence after the command line, but before hitting the carriage return. If I forget and use a history abbreviation in the command, then the first line of my hard copy shows the interpreted command. I am sure others will have other reasons why they'd like to suppress the echoing. Request: Provide some version of 'set' which shows the value of the variable. Maybe 'set var?' would be a good choice. Of course, 'echo $var' works, but this seems unnatural in this context. J. K. Cohen BSD4.2 -7- Request: Extend 'repeat' to compound commands. The shell program shown in the critique of the "Introduction to the C Shell" below gives such an extension. checknr This command should be extended to cover -mm too. And also to include the 'checkeq' command's duties. chsh Neither /bin/oldcsh nor /usr/new/csh exist, so I doubt that they can be useful as possible second arguments to 'chsh.' cp BSD4.2 has a new -r recursion option. Thank you! crypt No command line arguments. deroff The macro package -me throws deroff into a tizzy. It's fun to watch deroff on a file headed by '.so /usr/lib/tmac/tmac.e'. For example, on the file: .so /usr/lib/tmac/tmac.e gives: You are using the wrong version of NROFF/TROFF!! This macro package works only on the version seven release of NROFF and TROFF. which is not likely to provide the user with a clear idea of what's going on. More fun is the input file: .so /usr/lib/tmac/tmac.e speling erroers It is fun to run 'deroff' and 'spell' on this file. The effects are discussed in my documentation critique. which yields: Produced for your edification and enjoyment by: J. K. Cohen BSD4.2 -8- Eric Allman Electronics Research Laboratory Berkeley. VERSION First Release: Sept See file for revision history Documentation available. This version has had comments stripped; unstripped version available. You are using the wrong version NROFF/TROFF!! This macro package works only the version seven release NROFF and TROFF. which is not more illuminating, but gives, in addition to the above text, a nifty cursor display (not reproduced here). The inability of deroff to cope with such files means that utilities such as 'spell' and 'diction' which rely on deroff, cannot be used on this type of file (unless it is nroffed first or unless the .so line is temporarily removed). At the least, this defect should be noted as a deroff BUG. diction It is time that the BUG was removed. That is, diction should 'grok' -me (or a phasing out of -me should begin). It is not nice to suck users into a macro package for which tools like 'spell' and 'diction' can't be used. ed There seem to be an incredible number of documentation errors. The manual describes an 'ex' like editor, but all we seem to have is a barebones Bell 'ed' from the year one. A sampling of the discrepencies noted follow. The manual says that '%' abbreviates '1,$', but %p produces an error message. Likewise, despite the manual page, trailing delimiters are needed on the 's' command. Especially serious is the false claim that there is an 'u' undo command. The described command 'wq' is absent. J. K. Cohen BSD4.2 -9- The manual description of q is incomplete: 'ed' flags as an error a 'q' if a 'w' has not been done on a changed file. Alas, the error message is just the usual '?', which is likely to be too subtle to prevent the user from issuing an immediate repeat of 'q' which, as per standard Bell, is accepted. Good old 'silent ed.' There's not much point in going on. Perhaps I have the wrong manual page (3rd Berkeley Distribution 14 September 1979). Interestingly enough, the manual page I had from the BSD4.1 distribution had the same date (3rd Berkeley Distribution 9/14/79). However, the pages are not identical. The earlier page had documented a -p option which provided a * prompt for 'ed' at the command level. Of course, that didn't work either and the current distribution has fixed that bug by removing the option from the documentation! Surely there is some explanation for this radical discrepency of what I read and what I experience. Please, gentle reader, try some of these things and write to assure me that I haven't slipped a cog somewhere. In the meantime, my only advice is to expect nothing more than what is described in the Kernighan tutorials. It would be nice if 'ed' _w_e_r_e jazzed up a bit along the lines described in the documentation. Even though 'vi/ex' largely supercede 'ed', there are times on a busy system when one does not want to wait for 'vi' to start up. error This is a marvelous command for the reasonably sophisticated user. A word of advice about using the -v option: be sure to redirect standard output to a file, because if vi starts up fast, the errors which are written to standard output will vanish too quickly to read before the screen clears. Note that even the 'floodgate' effect noted under BUGS is not all that serious a drawback: the inserts made by 'error' are so distinctive that they can be eradicated by a single global editor command. ex Appending to a line and inserting at the beginning of a line are such common operations that vi's 'A', 'I' should be added to the 'ex' command set (one does get trapped on a teletype terminal once in awhile). The BUG entry concerning the inability to scan ignoring case should be deleted, since the ex option 'ic' solves that problem. J. K. Cohen BSD4.2 -10- explain This page is a repeat of the 'diction' page. But I am not complaining. It's really frustrating to look up 'checkeq' and not find it, etc. expr The last example is a little tough on the eyes. But I tried it and got the error messages 'Variable syntax' (csh) and 'syntax error' (sh). Maybe I screwed something up. My 'csh' attempt was: set x=/a/b/c expr $x: '.*/)' '|' $x while my 'sh' attempt was: x=/a/b/c expr $x: '.*/)' '|' $x Someday someone should write a supplement explaining these convoluted examples concocted by the 'Boys from Bell.' eyacc The word 'old' in the first sentence seems to contradict the same word in the last sentence. If this version is an improvement over yacc, it should be called 'yacc'. Otherwise, clearer guidelines are needed as to when to use which. f77 The subheading -o is missing. find The bug cited is an understatement. It took me a month to figure out how to find and print the files in my subdirectories which matched a regular expression. To alleviate the pain, why not give half a dozen simple examples? finger The initial letter, 'f', is a valid abbreviation. gprof When I went: cc -pg t.c gprof I got: hertz(): Permission denied open("/dev/kmem", 0)gmon.out: No such file or directory The same response was obtained for several programs, all of whose 'a.out' files performed normally. J. K. Cohen BSD4.2 -11- grep The command 'grep \\ filename' does not fail gracefully. At least that's what the Bell Lab documenters would say. In the interest of the system, I'll be explicit about what it does: RE botch RE botch RE botch RE botch RE botch RE botch RE botch RE botch RE botch RE botch RE botch RE botch RE botch ^C Is there a way to get fgrep to search for multiple strings without using the -f file option? indent What is the relation of this program to 'cb'? iostat When I innocently typed 'iostat', I got the response: 'cannot open /dev/kmem.' This is a local implementation problem connected with security considerations. learn Attention: 'learn vi' is available locally. If it's any good this should be one of the most valuable things on the system. ln Compacting or uncompacting breaks links (quasi-bug). lock Not available locally. look My first reaction was: "Do we need this, if we have 'grep'?" On second glance, I noticed that the default file was the spelling dictionary! This command allows one to get correct spellings by searching through the dictionary's list of words which begin with the desired initial string. Why not spend a moment on this short manual page, to explain this use of 'look'? Note that homespun shells like: #! /bin/sh # lookup - check spelling dictionary for pattern J. K. Cohen BSD4.2 -12- # Usage: lookup 'pattern' /usr/bin/egrep $1 /usr/dict/words while more general, do not take advantage of the sorted, one word to a line, structure of the dictionary (after "lookup '^aa'", there is a _l_o_n_g pause while the entire dictionary is searched, "look aa" terminates promptly when the "aa's" end). ls The discussion of permissions for directories is inadequate. Instead of the vague word 'search' in connection with the x permission for directories, why not say: r gives permission to 'ls' the directory; w gives permission to create files in the directory; x gives permission to 'cd' to the directory and to use (e.g., 'cat' or execute) files whose names we know in the directory. Comment: Despite the claims of an over-abundance of options, this version is inflexible. For example, one cannot view the protections without seeing all the info in -l. This has annoyed me enough to write a shell: #! /bin/sh # lsp - list files with protections # Usage: lsp /bin/ls -l | /bin/sed 's/ *.* / /' | exec /u/nosupport/p mail The local /usr/lib/Mail.rc is (5/6/84): set append dot save these three options mean: (1) new mail is appended (the default is first in last out) (2) a line consisting of just a '.' signals that you wish to launch your completed message (the default is ^D; if you like dot, you might also like 'ignoreeof'). (3) letters killed by two breaks are saved in ~/dead.letter The ~b escape is not documented (it gives a 'bcc' - 'blind carbon copy'). The option 'quiet' has the undocumented effect of also suppressing the current message number (unfortunately). J. K. Cohen BSD4.2 -13- On the last line of page 5, 'the' is misspelled. A possible BUG entry: ex/vi cannot be aimed at the headers of a message you are typing. Given the content of the first BUG entry, the option, 'debug' with its confusing reference could be deleted. Mail's help file still talks about /usr/mail (instead of /usr/spool/mail) and .sendrc (instead of .mailrc). A helpful usage hint. You can make mail customized by putting mail commands in a login directory file, called .mailrc. For an subject prompt and a cc prompt, enter the lines: set ask set askcc To suppress all those machine-generated mail headers, put the following line in your .mailrc: ignore Received Date From Message-Id Status Since if you have 'vi', you have 'ex' via the 'Q' command, you might consider specifying 'ed' as your line editor within mail. Recall that 'vi' starts up very slowly on a busy system and even the primitive 'ed' supplied by BSD4.2 (see above under 'ed') is often adequate for mail messages. To obtain 'ed' when you ~e and 'vi' when you ~v, place the following lines in your .mailrc file: set EDITOR=/bin/ed set VISUAL=/usr/ucb/vi man The related commands 'apropos' and 'whatis' should be mentioned. Possible BUG. Is there a way to get the new subsection introductions, such as intro(3S)? mkdir In the online manual, the default protection level cited as 777 is actually (at least locally) 755. The command: mkdir evokes the error message: J. K. Cohen BSD4.2 -14- mkdir: arg count The user who does not program in C will not find this useful. Either a "Usage:" error message or an interactive prompt for the directory name would be preferable. more This command needs an option to suppress its prompt message. Yes, even on a CRT. Much local effort has been expended in writing shells and C programs to avoid having this prompt mess up hardcopy being output on slaved serial printers. The underlining done by "more" is often erratic. Sometimes it extends to the end of the line when it should not. When using "more" and advancing to a new page by hitting the space bar, the visual attribute of the terminal you are using will change. In mail if you type ~v it will do the same thing. ms Comment: Looks like a utility to convert text from -ms to the newer -me would be easy to write. Then one could make use of me's greater power without doing gobs of preliminary editing on old text. msgs Is currently off-limits locally (Permission denied). pr It would be helpful to have options to set left margin and the top margin. Also it would be useful to get paginated output without a heading. prof Sometimes 'mon.out' is not produced. I have hard copy examples of a 'cc -p file.c' command, followed by a 'prof' which yielded: mon.out: No such file or directory whereas some time later the same command sequence worked fine. In both cases, 'a.out' was produced and functioned normally. This certainly smells like a local or a personal problem, but I report it in case others have had the same experience. The 'SEE ALSO' should reference 'gprof.' ps Needs an option to suppress the header line. ratfor Should reference 'RATFOR A Preprocessor for a Rational Fortran' by Brian W. Kernighan (in /usr/doc). J. K. Cohen BSD4.2 -15- refer In the description of -a, the letter following -a should be 'n' instead of 'r.' In the description of -f I think the intent is to set the _i_n_i_t_i_a_l footnote number, but this is not clear from the text. Hooray! This revison gives an example. It is a good example. It's contents belong in 'SEE ALSO.' I suspect -me will drive "refer" as insane as "deroff", "style", etc. rev Give some examples of when this command would serve a useful purpose. rmdir Again this is a duplicate of another manual page (rm) and again this is not a complaint. script If you try "script", you get the following error message: %script out of pty's terminated sed Should reference the manual in /usr/doc. Possibly (in the future), also Kernighan and Pike for a tutorial. sh The 'new' comment symbol, '#', is not mentioned. I am not familiar enough with the history of Bourne shell development to be able to tell what else is missing. If you are, be warned that the documentation is not up to the minute. The header line: #! /bin/sh unambiguously specifies that a shell program is to be executed in Bourne shell. It also serves as an important comment to the same effect. See execve(2). Should reference the tutorial in /usr/doc. And _d_e_f_i_n_i_t_e_l_y (in the future) Kernighan and Pike as the place to learn Bourne Shell programming. spell Here we are, back at Murray Hill, trying to get laughs J. K. Cohen BSD4.2 -16- from cute examples. The little terminal sequence near the bottom of the page creates 56 blocks of hashed dictionary in the user's directory. Most systems can't tolerate every novice maintaining their own 56 block dictionary. Besides, following the method shown, you wipe out out 'myhist' each time you add a new word. Thus your 56 block dictionary would perpetually differ from the system's by only one word. Finally, while the association of 'hookey' with the filename, 'huckfinn', may be obvious when one is composedly reading through the manual, it may be totally opaque when one is harried. Below, I shall show a first cut at a shell program (following an example in Bourne's 'The UNIX System') which employs an auxiliary personal spelling list whose entries are not to be flagged as misspellings. The discussion of -d, -s, -h, will have to be greatly expanded before this reader will understand it. For a moment, I thought that -d provided an easy way to maintain an exception list. But spellin myhist.hash seems to create an _a_l_t_e_r_n_a_t_e hashed spelling list (56 blocks, of course), _n_o_t an _a_u_x_i_l_i_a_r_y list. What is needed is an option to specify a small extra list of exceptions (hashed or not) which are NOT to be flagged as spelling errors. If we demand that the list be in a sorted, one word per line file, then the following C shell program accomplishes this: #! /bin/sh # Usage: sp [-eexceptionlist] [-spelloptions] filename ... # spell command with exception list # NOTE: The exception list is assumed to be sorted: # sort -o exclist exclist # NOTE to other users: Change the defaultlist below (yours might # contain the names of you and yours, etc.) # Caveat: Revise to ccat a compacted exception list if it's large. cmd=`/usr/bin/basename $0` typos=/usr/tmp/$$.dict case $# in 0) echo Usage: $cmd [-eexclist] [-spelloptions] files 1>&2; exit 1 esac defaultlist=/u/mathf/jkcohen/Wds/words # CHANGE THIS! for i do case $i in -e*) # User supplied exception list. J. K. Cohen BSD4.2 -17- exceptions=`/bin/echo $i | /bin/sed 's/^-e//'` ;; -*) # Collect user-supplied spell options option="$option $i" ;; *) # Collect filenames files="$files $i" ;; esac done exceptions=${exceptions-$defaultlist} trap '/bin/rm $typos' 0 1 2 15 /usr/bin/spell $option $files >$typos # spell sorts with -f option; but comm demands ASCII collating sequence! /usr/bin/sort -o $typos $typos /usr/bin/comm -23 $typos $exceptions exit 0 The inclusion of .so lines such as '.so /usr/lib/tmac/tmac.s' in your text utterly defeats 'spell.' The effects are different from those noted in the 4.1 Critique, but are still unsatisfactory. Here is the story for our two most commonly used nroff macro systems. For 'tmac.e', you do not get the spelling errors. For 'tmac.s', you get the spelling errors, but also get 107 two letter nroff-type commands: AB AE AI AJ AU BD BG bp br BT . . . The 'SEE ALSO' for 'spell' should reference 'look.' struct When I go: struct prog.f J. K. Cohen BSD4.2 -18- or struct >$file /bin/time $* 1>/dev/null 2>>$file tip The next to the last word on the last page should be 'pared' not 'paired.' This is generally an excellent manual page about a very difficult subject. Someone who has used 'tip' asks for additional information on how to get auto-dialers to work with it. tr On one occasion, I found the BUG to actually be a useful feature. Once, after transferring a file, I wound up with a file loaded with NULs. The command, 'tr nicefile', was very useful (the version of 'vi' I had then simply did not like files with NULs; J. K. Cohen BSD4.2 -20- probably the current version doesn't either). tset The alias given on page 2 proved deadly when I inserted it into my .cshrc (unless you are a UNIX adept, don't play around with this - if you can't resist, remember to make a backup copy of your '.cshrc', so you can get this file restored without use of 'vi'). The option '-s', used in our local /usr/skel/.login, is not documented. Locally, you get reasonable terminal characteristics without using 'tset.' (As an experiment, I moved my .login to another name and logged in on a CRT. My backspace key worked fine.) ul The sentence describing the -i option contains the mystifying phrase: 'underlining onto ...' uucp Is there a relation between 'tip' and the 'uu' commands? users The initial letter, 'u', is a valid abbreviation. wall Should document effect of 'mesg' on this command. write The concept of 'write back' should be elucidated (i.e. describe how you do that). yacc SEE ALSO should reference 'eyacc'. yes Give some examples of when this command would serve a useful purpose. (No, I haven't lost my sense of humor, it's just that infinite loops on a busy system may not be all that funny.) J. K. Cohen BSD4.2 -21- _P_r_o_g_r_a_m_m_e_r'_s _M_a_n_u_a_l: _S_e_c_t_i_o_n _2 intro Should tell us where to find the values of {PROC_MAX} etc. Again under 'File Access Permissions' we have only a vague hint of what x permission for a directory implies (see above ls(1) discussion). In the last paragraph on page 6, the 'and' at the end of the first line should be 'but' as in the next paragraph. However, both these paragraphs could be simplified by removing their opening clauses. creat Last word in NOTES is misspelled. execve Near the top of page 2, argv is described as an array, but envp as a pointer to an array. Their descriptions should be identical, since their declarations are identical. fcntl Last item under F_DUPFD should refer to execve, not exec (or section 3, not section 2). There's an extra blank line before FAPPEND. gethostid RETURN VALUE and ERRORS sections are missing. The hostid is not set on Eos. gethostname The hostname on Eos is 'udenva.' getpriority The file must also be included, without it, the include file, , evokes: "/usr/include/sys/resource.h", line 21: unknown size "/usr/include/sys/resource.h", line 22: unknown size "/usr/include/sys/resource.h", line 39: unknown size "/usr/include/sys/resource.h", line 39: unknown size The defines shown are already in resource.h and should not be given here. J. K. Cohen BSD4.2 -22- _P_r_o_g_r_a_m_m_e_r'_s _M_a_n_u_a_l: _S_e_c_t_i_o_n _3 A request for a missing utility from a local C whiz: "Put itoa() back in. Sprintf is a bit much for just converting one integer." bstring The BUGS are respectively non-existent and inexcusable. Bcmp cannot take its parameters 'backwards' from strcmp, because bcmp is _s_y_m_m_e_t_r_i_c in its first two arguments. Unlike strcmp, bcmp does not return <0 and >0 when the strings differ. Bcmp only promises to return 'non-zero' when the strings differ. On the basis of a very small sample, bcmp seems to return the length of the strings when they differ. On the other hand, having bcopy take its parameters in the opposite order from strcpy is the pits. ctime The function, time(2), referred to in the DESCRIPTION is non-existent. There is a gettimeofday(2). The function, time(3), referred to in the DESCRIPTION is non-existent. There is an obsolescent time(3c). Page 2 has lots of room for usage examples. ctype In the definition of isprint, I think the '(8)' is superfluous. directory The include file, , should be in the synopsis. Give the returns from 'seekdir', 'rewinddir' and 'closedir' or, if none, state that the functions are void. The quantities, d_namlen, d_name mentioned in the example, as well as others in 'struct direct' need to be defined. Probably, the include file should be cited. execl If the second sentence of the description is saying that the details of execl, execv are given on the manual page for execve(2), it lies. I think the FILES entry would be clearer as: '/bin/sh, or whatever shell is invoked when a command file is found by execlp or execvp' J. K. Cohen BSD4.2 -23- getlogin The description says the correct procedure to get a login name involves a call to 'getpw.' However, 'getpw' is deemed 'obsolescent.' A call to such a function doesn't sound 'correct' to me. And 'getpw(3C)' is cited as having two arguments, not one, as indicated here. In the SEE ALSO, 'getpw(3)' is cited, but doesn't exist (the correct reference is 'getpw(3C).' malloc In the last phrase on the page omit the apostrophe. random The SEE ALSO should refer to rand(3C) instead of rand(3). qsort(3F) The NAME says 'quick sort' instead of 'quicker sort.' Is this intentional, i.e., is this algorithm different than qsort(3)? syslog(3F) The header line should have (3F) instead of (3). getfsent(3X) Why gratuitously make things harder by omitting the comments in the copy of 'struct fstab'? printf(3S) In the second paragraph of the description, the phrase, 'the first argument', should be replaced by, 'the _f_o_r_m_a_t argument.' In the bullet item about field width, discuss effect of insufficient or missing field width (i.e. move the next to the last sentence of the description here). In fourth bullet item, omit the first comma. The X conversion is not defined. In the paragraph on 's' conversion, put a comma after the word, 'missing.' J. K. Cohen BSD4.2 -24- _P_r_o_g_r_a_m_m_e_r'_s _M_a_n_u_a_l: _S_e_c_t_i_o_n_s _4-_7 Not a chance your roving reporter can understand much of this. I am even incompetent at the games! intro(4) The first entry in the SEE ALSO sets up an infinite loop. General comment on section 5: this would be the right place to have a complete set of documented #include files. disktab(5) In the first sentence, 'date' should be 'data.' termcap(5) Last sentence of next to last paragraph doesn't parse well. aardvark(6) We don't have it. boggle(6) Attempts to invoke produce the message: 'can't open /usr/games/bogdict.' This is truly a shame. /usr/games/bogdict exists (mode 600) and is of very healthy size, 256 blocks. Even /usr/dict/hlista is only 56 blocks. chase(6) We don't have it. doctor(6) When invoked, pauses for a long time and then says: 'Can't open file ./doctor' and dies. me(7) None of the writer aids that depend on deroff (like 'spell') work, if you include a '.so /usr/lib/tmac/tmac.e' line in your file. Nroffing with -me causes variable length pages. One cure is to specify the -Tlpr option. Another is to filter the output through 'col.' Both of these fixes nullify the advanced capabilities of the printer. J. K. Cohen