jkcohen@udenva.UUCP (08/02/84)
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 >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 <prog.f
I get:
trap: Command not found
I looked, and 'struct' is a shell file from Berkeley.
My favorite guru points out that UCB added a header
saying that UCB wrote it. The header line is a comment
line. You can tell because it begins with a #. Alas,
there is an archaic convention that if the first line
of a shell file begins with a # line, then the file is
handed over to the C shell interpreter. The problem is
that the shell is actually a Bourne script! The
solution is either to delete the header line or use the
modern convention of first line beginning with '#!
/bin/sh.' (The system is smart enough to look past the
initial '#' to see if '!' is the next character; thus
both the archaic and the modern convention live on
together.)
stty Section 39 in Volume IIc, 'Bug Fixes and changes',
gives different defaults for erase, kill and interrupt
characters.
style
The BUG should be removed to the extent of dealing with
-me. Alternatively, -me should be withdrawn.
sysline
I got the error message:
Can't open kmem
One of my gurus tells me this is a local implementation
problem involving a fix to UNIX security. Whatever, we
don't have access to this command.
su Section 39 in Volume IIc, 'Bug Fixes and changes',
gives a new option, -f, which is omitted here.
Similarly, the extra arguments extension is not
discussed here.
tabs The BUG should be explained in greater detail: Why?
How?
talk Talk doesn't work. According to a local expert:
'undoubtedly something to do with /etc/hosts not having
udenva listed in it.'
J. K. Cohen
BSD4.2 -19-
tbl There is an nroff mistake in the 'tbl' page! It causes
a missing line in the description and is due to a . at
the beginning of the line which was not protected by
the \& escape. The cute thing is that 'checknr' would
have found this error, because the line begins with .TS
and had no .TE to match it. Now you and I forget to
run 'spell' and 'checknr', but not the pros. Not much.
Recently, I was looking at a 'brand X' derivative of
BSD4.2 and the ms(7) manual page similarly left out a
raft of \&'s and most of the first manual page was
omitted after nroffing. By the time you read this, the
online manual may be fixed. In case not, here is the
correct description:
_T_b_l is a preprocessor for formatting tables for
_n_r_o_f_f or _t_r_o_f_f (1). 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 are reformatted.
Details are given in the _t_b_l (1) reference
manual.
tee Here is this big empty space (on the manual page). I
have an idea: let's use some of it to give examples.
time You may think that /bin/time is anachronistic, but
think about how you would get the effect of the
following shell using the C shell's built-in 'time'
command.
#! /bin/sh
# cpu - put timing data into the file "timedata" (and throw output away).
# Usage: cpu command
file=timedata
/bin/echo -n $*: >>$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 <file >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 <sys/time.h> must also be included, without
it, the include file, <sys/resource.h>, 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, <sys/types.h>, 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