ONLamp.com    
 Published on ONLamp.com (http://www.onlamp.com/)
 See this if you're having trouble printing code examples


FreeBSD Basics

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:

whatis intro
intro(1) - introduction to general commands (tools and utilities)
intro(2) - introduction to system calls and error numbers
intro(3) - introduction to the C libraries
intro(4) - introduction to devices and device drivers
intro(5) - introduction to file formats
intro(6) - introduction to games
intro(7) - miscellaneous information pages
intro(8) - introduction to system maintenance and operation commands
intro(9) - introduction to system kernel interfaces

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:

man (number) name_of_file

Try this:

man who
WHO(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 utmp
No entry for utmp in section 1 of the manual
man 2 utmp
No entry for utmp in section 2 of the manual
man 3 utmp
No entry for utmp in section 3 of the manual
man 4 utmp
No entry for utmp in section 4 of the manual
man 5 utmp
UTMP(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 who
WHO(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 who
biff(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 i
genisis   ttyp0   Sep 24 10:52
who
genisis   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.

DESCRIPTION
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.

Available options:

am I

Returns the invoker's real user name.

file

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 ls
LS(1)   FreeBSD General Commands Manual   LS(1)

NAME
     ls - list directory contents

SYNOPSIS
     ls [-ABCFGHLPRTWabcdfgiklnoqrstu1] [file...]

Unlike the 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 [] is ls itself; this means that all switches and files are optional. If you just type:

ls

you will still get a listing of your current directory.

Remember that to Unix, everything is a file, including directories. So:

ls /etc

will list the directory contents of /etc.

ls /etc/rc.conf

won't yield much, but

ls -l /etc/rc.conf

will yield information on the rc.conf file.

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:

/ -l

to invoke the search function and receive the following explanation:

-l

(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:

man who

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

or

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
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, 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.

 

Copyright © 2009 O'Reilly Media, Inc.