BSD DevCenter
oreilly.comSafari Books Online.Conferences.


FreeBSD Basics

Read The Friendly Manpage! -- A Tutorial


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.

  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.

Pages: 1, 2, 3

Next Pagearrow

Sponsored by: