Read The Friendly Manpage! -- A Tutorial

10/04/2000

There are few things more frustrating to the FreeBSD novice than to be told to RTFM (Read The Friendly Manual), especially since the "F" does not always represent the word Friendly. Everyone quickly learns that they should always RTFM, but there are very few resources available to tell a novice "how" to find the information they need in the manual. Unless you've managed to befriend a very patient Unix guru, the fine art of manpage reading is learned through painful trial and error.

Most of the files that came with your FreeBSD system have explanations of their usage in the manual, which has been divided into sections to help categorize the different types of files. The man utility is used to format and display the section pertaining to the file in question. To find out what sections are available, type:

Here you can see that the manual has been divided into 9 sections or
categories. For example, section (1) deals with commands used by users, whereas section (8) deals with the commands or daemons used by your FreeBSD system. If you wish to read a bit more detail on the sections, type:

man 1 intro
man 2 intro

and so on for a quick explanation of what types of information are contained in each section of the manual.

Knowing the different sections of the manual is important, as some files have information in more than one section of the manual. Unfortunately, if you just type:

man name_of_file

you will only be taken to the first section that exists for that file; if that file has entries in more than one section of the manual, they will not be displayed unless you specify the section for the man utility, like this:

Here we did not specify which section to open for the above three files, but the man utility automatically displayed the first section dealing with each file. It would appear that the first section dealing with utmp is section 5; to prove this to yourself, try:

man 1 utmpNo entry for utmp in section 1 of the manualman 2 utmpNo entry for utmp in section 2 of the manualman 3 utmpNo entry for utmp in section 3 of the manualman 4 utmpNo entry for utmp in section 4 of the manualman 5 utmpUTMP(5) FreeBSD File Formats Manual UTMP(5)

If you're really bored, you can try the same exercise with the init file.

When the man utility displays a section of the manual for a specified file, it uses distinct headings that are formatted in boldface print. Let's open up a manpage and examine these headings in more detail:

man whoWHO(1) FreeBSD General Commands Manual WHO(1)

Again, notice that the very first line in every manpage indicates which
section of the manual you are reading.

NAME
who - display who is logged in

The first heading of every manpage is NAME. Whenever you use the whatis command, every NAME heading in the manual is scanned and those files whose NAME matches your query are displayed on your terminal like this:

whatis whobiff(1) - be notified if mail arrives and who it is from
from(1) - print names of those who have sent mail
rusers(1) - who is logged in to machines on local network
rwho(1) - who is logged in on local machines
w(1) - display who is logged in and what they are doing
who(1) - display who is logged in

Note that our query for who matched both the name and description of every manpage containing the word "who" in the NAME heading.