Tuesday Tiny Techie Tip

RTFM and mindset

This week is more of a meta-tip. For those who don't know, RTFM stands for

Read The Fine Manual

(though other words are often substituted for the F). This phrase is usually offered in response to a frequently asked question (or FAQ (pronounced Fah-queue ;-)) which is easily answered by consulting the available documentation.

Another useful interpretation of the M in RTFM is the word Message, since often the answer to a question is inherent in the error message which inspired it. Take this one for example:

/: write failed, file system is full

That message often sends people yelling to sys or vobadm that some disk has filled up. Which is true, but without seeing the message, there's no way of knowing which disk. But if you read the message carefully, noting that there is a /: at the beginning of it, it becomes clear that the disk which is full is the "slash" partition on the system where the error occurred, and hence /tmp probably has too much junk in it.

So, Read The Fine Message.

If the message isn't the problem, then look to the Manual. The command "man <subject>" will display the UNIX manual page for the given subject if one exists. Unfortunately the man command isn't very smart, and can't figure out that if you said "man dir" you're a DOS weenie and you really want to know about ls(1) (instead you'll get the page from section 5 of the manual which describes the file format of UNIX directories which may be interesting, but isn't exactly what you had in mind).

The -k argument (k for keyword) to man will show you a list of the man pages which have a string in their description, so

% man -k dir

would give you the (long) list of pages that have dir in their descriptions. You might be able to figure out from the list that ls(1) is the command you're looking for.

That number in parentheses indicates in which section of the manual the entry for ls is to be found. The standard sections for the UNIX man pages are as follows:

1	- user commands
2	- system calls
3	- user-level library functions
4	- device drivers, protocols, and network interfaces
5	- file formats used or read by various programs
6	- games and demos
7	- miscellaneous useful information pages
8	- system maintenance and operation commands
l	- local commands and stuff
n	- new commands
o	- old commands
p	- public commands and stuff

To ask for the man page for ls from section 2 of the manual, you just put the 2 before the topic like: "man 2 ls" That page would tell you about the ls UNIX system call.

Often when you finally get to the man page which should answer your question, the page is written in such a terse coder fashion that the answer still isn't clear.

This is where mindset comes in. I tell people that they should read UNIX man pages as they would read a mystery or science fiction novel. This is a two-part mindset:

Suspend your disbelief
Accept whatever is written in the man page as gospel truth even if it doesn't seem to make sense in the real world. After all, this isn't the real world we're talking about, it's UNIX.
Trust the author
Assume that all of the information you need to answer your question is there somewhere, because nine times out of ten it is. You just have to see it the right way, or accumulate enough clues to make it clear.

The other piece of advice I give is to browse through all the man pages (at least section 1) once every year or so. You don't have to read the whole thing, just read the SYNOPSIS section and the first paragraph of the DESCRIPTION section. More if it looks like the command is something you might use once in a while.

I did this for the first few years I was working in UNIX, and it was invaluable in helping me to know whether there was a tool out there to help me do something, and if there was, to give me a clue about how to find it. I haven't done it in a while so I'm probably about due.

I've written a script to allow you to browse through all the man pages in a section. It's called "browseman" and lives in /tools/public/bin. It browses section 1 by default. It displays each man page in the section using your default pager (probably more(1), maybe less(1)).

Once you've started browseman, you can skip the rest of the current page and go on to the next page by hitting "q". To quit completely, type ctrl-C (followed by q if your pager is less(1))

Tuesday Tiny Techie Tip -- 19 November 1996
Forward to (11/26/96)
Back to (11/12/96)
Written by Jeff Youngstrom

Up to the TTTT index