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:
intro(1) - introduction to general commands (tools and utilities)
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:
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:
man (number) name_of_file
man whoWHO(1) FreeBSD General Commands Manual WHO(1) man utmp UTMP(5) FreeBSD File Formats Manual UTMP(5) man init INIT(8) FreeBSD System Manager's Manual INIT(8)
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 manual
man 2 utmpNo entry for utmp in section 2 of the manual
man 3 utmpNo entry for utmp in section 3 of the manual
man 4 utmpNo entry for utmp in section 4 of the manual
man 5 utmpUTMP(5) FreeBSD File Formats Manual UTMP(5)
If you're really bored, you can try the same exercise with the
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.
The next heading in every manpage is SYNOPSIS:
SYNOPSIS who am I who [file]
Since we are in section 1 of the manpages, this is a very useful heading as it contains the syntax and switches used by the command. Here, the
who command has two possible syntaxes which yield different results:
who am igenisis ttyp0 Sep 24 10:52
whogenisis ttyv0 Sep 24 08:41 genisis ttyv1 Sep 24 08:42 genisis ttyv2 Sep 24 08:42 genisis ttyv3 Sep 24 09:06 genisis ttyv4 Sep 24 09:14
To understand the meaning of all the syntax options, scan the DESCRIPTION heading which immediately follows the SYNOPSIS.
The who utility displays a list of all users currently logged on, showing for each user the login name, tty name, the date and time of login, and hostname if not local.
Returns the invoker's real user name.
By default, who gathers information from the file /var/run/utmp. An alternate file may be specified which is usually /var/run/wtmp (or /var/run/wtmp.[0-6] depending on site policy as wtmp can grow quite large, and daily versions may or may not be kept around after compression by ac(8)). The wtmp file contains a record of every login, logout, crash, shutdown and date change since wtmp was last truncated or created.
The DESCRIPTION heading for who is fairly short and intuitive once you've tried running the command both ways. Let's look at a manpage with a longer DESCRIPTION:
man lsLS(1) FreeBSD General Commands Manual LS(1) NAME ls - list directory contents SYNOPSIS ls [-ABCFGHLPRTWabcdfgiklnoqrstu1] [file...]
who command, which had no switches, the SYNOPSIS for the
ls command looks like the ingredients in alphabet soup. Note that the only part of the synopsis that is not enclosed by
ls itself; this means that all switches and files are optional. If you just type:
you will still get a listing of your current directory.
Remember that to Unix, everything is a file, including directories. So:
will list the directory contents of /etc.
won't yield much, but
ls -l /etc/rc.conf
will yield information on the
The SYNOPSIS shows all legal switches, but the DESCRIPTION heading
explains the usage of each switch, in the order they were listed in the SYNOPSIS. If I wish more information on what
-l does, I can either use my page down key to look for it, or type:
to invoke the search function and receive the following explanation:
(The lowercase letter ``ell.'') List in long format. (See below.) If the output is to a terminal, a total sum for all the file sizes is output on a line before the long listing.
One can then page down and look for the "long format," or keep pressing the
/ key until one finds it:
The Long Format
If the -l option is given, the following information is displayed for each file: file mode, number of links, owner name, group name, number of bytes in the file, abbreviated month, day-of-month file was last modified, hour file last modified, minute file last modified, and the pathname. In addition, for each directory whose contents are displayed, the total number of 512-byte blocks used by the files in the directory is displayed on a line by itself immediately before the information for the files in the directory.
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:
we'll see that it uses the following files:
FILES /var/run/utmp /var/log/wtmp /var/log/wtmp.[0-6]
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:
SEE ALSO 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,
users are commands related to the
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
w, and by the system commands
init. At that point I could do a
whatis on any file that sounded intriguing, like this:
whatis acac(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 manman: /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
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
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:
And to find out more about the system utilities that came with your FreeBSD system:
And my favorite time-killer:
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
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.
Copyright © 2009 O'Reilly Media, Inc.