The UNIX operating system was one of the first to include online documentation. It's not the best in the world--most
users who haven't internalized the manual set curse it once a week--but it has proven surprisingly resilient. What's
particularly interesting about UNIX's online documentation is that, unlike other early help systems, it isn't an
adjunct to another set of printed documentation that contains the "real" truth. The online manual is
complete, authoritative, and usually more current than any printed documentation.
The basis for UNIX's online documentation is the man command. Most simply, you use it as follows:
% man topic
where topic is usually the name of some command; but it can also be the name of a system call, a library routine,
an I/O device, or an administrative file (or file type). The output from man is usually sent to a pager like more
which allows you to page through.
The manual pages are grouped into a number of categories. Unfortunately, there are three slightly different groupings:
one for Berkeley based systems, one for System V, and one for systems derived for XENIX.
|
Category |
BSD |
System V |
Xenix |
| User commands |
1 |
1 |
u_man |
| System calls |
2 |
2 |
p_man |
| Library routines |
3 |
3 |
p_man |
| I/O and special files |
4 |
7 |
p_man |
| Administrative files |
5 |
4 |
a_man |
| Games |
6 |
6 or 1 |
u_man |
| Miscellaneous |
7 |
5 |
anything goes |
| Administrative commands |
8 |
8 |
a_man |
| Maintenance commands |
8 |
1M |
u_man or a_man |
| Local commands |
l (letter) |
-- |
-- |
| Obsolete commands |
o (letter) |
-- |
-- |
As you can see, System V makes a strange distinction between ''administration" and "maintenance";
if you can figure out what they really mean, please let us know! To a poor Berkeley soul, this has never made sense.
Some of these categories are subdivided further; for example, you may see section 3S (the standard I/O library),
3M (the mathematics library), lG (Berkeley graphics), lV (commands derived from system V), and so on.
If you want to refer to a manual entry in a specific section of the manual, you can give a command of the form:
% man section topic
For example, if you want to read documentation about the /etc/passwd file (rather than the sswd command) on a System
V machine, give the command:
% man 4 passwd
This is an easy way to distinguish between topics with the same name, but in different groups.
The biggest problem with the UNIX manual set is finding what you want, given that you don't already know what
you're looking for. For example: you want to search for a string in a file. If you don't remember that the command
you want is called grep, how will you ever find it?
The apropos command, which is equivalent to man -k (and sometimes just an alias for man -k) helps to solve this
problem. It's not always successful, but it's better than nothing. It looks through headings of all the "man
pages" and prints any that match a given keyword. For example, to figure out how to search for a
string, try the command:
%apropos string
. . .
gets, fgets (3S) get a string from a stream
getsubopt (3) parse sub options from a string
gettext, textdomain (3) retrieve a message string, get & set text domain
grep, egrep, fgrep (lV) search a file for a string or regular expression
puts, fputs (3S) put a string on a stream
. . .
whatis is almost identical to apropos, but it requires a command name as an argument--rather than an arbitrary
string. Why is this useful? Well, let's say you forget what cat does. On a SunOS 4.1 system, apropos cat gives
you several screen fulls of output. You may not want to read the entire manual page. But whatis cat gives you a
nice on-line summary:
% whatis cat
cat (lV) concatenate and display
The whereis command helps you to locate the executable file, source code, and manual pages for a program. I
use it primarily as a sanity check; if I type more useless.txt, and get the message "more: command not found,"
I immediately try whereis more. This gives me a lot of information about what went wrong: someone may have removed
more from the system, or my PATH environment variable may be set incorrectly, etc.
Output from where is typically looks like this:
% whereis more
more: /usr/ucb/more /usr/lib/more.help /usr/man/manl/more.l
This says that the executable file is /usr/ucb/more, the command's internal help file is /usr/lib/more.help, and
the manual page is /usr/man/manl/more.l.
The which command is a real life saver. It has become increasingly important in the last few years. Many vendors
(like Sun) are providing separate directories of BSD-compatible and System V-compatible commands. For example:
% which sort
/bin/sort
tells me exactly which version of the sort program I'm using. You'll find that which comes in handy in lots of
other situations.