BSD DevCenter
oreilly.comSafari Books Online.Conferences.


Read The Friendly Manpage! -- A Tutorial
Pages: 1, 2, 3

The headings that follow the DESCRIPTION will vary depending on the manpage you are using. If the manpage you are reading has a FILES heading, it will list the full pathnames to the files (usually configuration files) associated with that command. For example, if we continue with:

man who

we'll see that it uses the following files:


Each file listed will probably have an associated man page in section 5, since this is the section that deals with file formats. In this case,

man 5 utmp


man 5 wtmp

will yield useful information on the formats of these files.

Section 5 of the manpages is useful whenever you need more information on what a particular configuration file does and what type of information should be put into it. For example:

man 5 resolv.conf

will bring you to section 5 of the manpage for resolver, so not only will you learn the syntax for the configuration file, you also learn what command reads this file.

Which brings us to the last heading seen in all manpages, the SEE ALSO heading:

man who
     last(1),  users(1),  getuid(2),  utmp(5)

This heading is indispensable when you are learning a new command as it shows manpages that may shed additional light on the subject at hand.

In this example, last and users are commands related to the who command; getuid explains the system calls or error messages used by the who command, and utmp is the configuration file read by the who command. We know all this thanks to the number placed in () next to each of these names.

If I was researching this topic further, I would try:

man 5 utmp

and scan its SEE ALSO section. This would tell me that this file is also read by the user commands last, login, and w, and by the system commands ac and init. At that point I could do a whatis on any file that sounded intriguing, like this:

whatis ac
ac(8) - connect time accounting

and if that description piqued my curiosity, I could learn more about this system command by doing this:

man 8 ac

You'll find that once you know what to look for in a manpage, there isn't any shortage of useful information. If anything, you may find yourself being side-tracked as you navigate from one interesting manpage to another. I'm constantly amazed at how much other stuff I learn when I thought I was going to research something else.

A couple of notes on navigation within manpages: Besides the handy / search key, you can also use b to go back one page, and once you've found what you are looking for, you can use q to quit and receive your cursor back. To find other navigation tricks, type h while in a manpage to receive the help screen on the summary of commands.

Where are the manpages for the built-in utilities and configuration files actually located on your FreeBSD system? To find out, try:

whereis man
man: /usr/bin/man /usr/share/man/man1/man.1

ls -aF /usr/share/man
./         cat4/       catn/        man4/       mann/
../        cat5/       ja/          man5/       whatis
cat1/      cat6/       man1/        man6/
cat1aout/  cat7/       man1aout/    man7/
cat2/      cat8/       man2/        man8/
cat3/      cat9/       man3/        man9/

I used the a and F switches with the ls command to show all entries in /usr/share/man, and to include the / symbol after directory entries.

Note that the manpages themselves are stored in /usr/share/man. This directory contains subdirectories for all of the commands in each section of the manpages. Since section 1 of the manual contains user commands, there is a separate directory for the newer elf format and older aout format commands.

Many new FreeBSD users despair that they don't know what manpage to read because they don't know which command they need to accomplish a task. Next time you're bored and want to learn more about your FreeBSD system, try a

ls /usr/share/man/man1

to receive a listing of the available manpages for the built-in (elf) utilities that came with your FreeBSD system. If you're half as curious as I am, you'll have several hours of interesting manpage reading ahead of you.

If you want to learn more about the built-in configuration files, try:

ls /usr/share/man/man5

And to find out more about the system utilities that came with your FreeBSD system:

ls /usr/share/man/man8

And my favorite time-killer:

ls /usr/share/man/man6

You're probably better off not trying that last command at work; save it for a lazy Sunday afternoon.

And what about the cat subdirectories? We'll save those til next week when we discuss how the man utility formats and displays manpages and what effect this formatting has on your ability to search within and to print manpages.

Dru Lavigne is a network and systems administrator, IT instructor, author and international speaker. She has over a decade of experience administering and teaching Netware, Microsoft, Cisco, Checkpoint, SCO, Solaris, Linux, and BSD systems. A prolific author, she pens the popular FreeBSD Basics column for O'Reilly and is author of BSD Hacks and The Best of FreeBSD Basics.

Read more FreeBSD Basics columns.

Discuss this article in the Operating Systems Forum.

Return to the BSD DevCenter.


Sponsored by: