the people paid to help you frequently know little more than you do.

FreeBSD, on the other hand, is completely open, allowing you to learn exactly how things behave, in intimate detail. As an open operating system, you can read the source code for commands, as well as the kernel. And people in the FreeBSD community overwhelmingly want to learn. The community welcomes people who want to learn, and will be delighted to help you if you're willing.

There are other parts of the FreeBSD community that you should be aware of: segments who are not as interested in learning how FreeBSD works. These include a group that doesn't care how FreeBSD works, just that it works well. For example, many ISPs don't care what serves up their Web pages; they just care that their Web pages are being served reliably. Embedded systems programmers as a group are often not as interested in FreeBSD's inner workings; for the most part, they are attracted by FreeBSD's power and its commerce−friendly license. This is not to say that there is anything wrong with these groups whatsoever, just that these people aren't likely to be found hanging around FreeBSD mailing lists answering user questions.

As a grossly overgeneralized rule, people help those like themselves. As a FreeBSD user, you should make the jump from eating what you're served to reading the cookbook and creating your own dinner. If you're willing to learn what really goes on in your computer, you will be welcomed with open arms. If you just want to know which box to click, read the Handbook and FAQ. The general FreeBSD community simply isn't motivated to help those who won't help themselves or who can't follow instructions. If you need more hand−holding than the community provides, you'd do best to invest in a commercial support contract. (Several good support vendors are available; check the FreeBSD Web site for details.)

The fact is, the number of people familiar with everything that FreeBSD offers are few enough to be counted on one hand. Just the week before I wrote this chapter, I saw one of the FreeBSD Project's founders express surprise when he learned that a program worked in a particular way. That made me feel good; even the masters are still learning.

The first part of your homework, then, will be to learn what resources the FreeBSD Project has available.

Man Pages

Man pages, short for "manual," are the original UNIX documentation. While they have the reputation of being obtuse, difficult, or even impossible to read, they're quite user−friendly—for particular users. When man pages were first created, the average systems administrator was a C programmer and, as a result, they're written by programmers, for programmers. If you can think like a programmer, man pages are perfect for you. I've tried thinking like a programmer but have only achieved real success after remaining awake for two days straight. (A high fever helps, too, and lots of Coke.)

Over the last several years, the skill level required for systems administration has dropped, and you no longer need to be a programmer. Similarly, man pages have become more and more readable. As such, they should be your first line of attack in learning how something works. If you send a message to a mailing list without checking the man page, you're likely to get a terse "man whatever" in response.

39

The FreeBSD Manual

The FreeBSD manual is divided into nine sections. Each man page (page of the manual) appears in only one section. Roughly speaking, these sections are:

1General commands

2System calls and error numbers

3The C libraries

4Devices and device drivers

5File formats

6Game instructions

7Miscellaneous information

8System maintenance commands

9Kernel system interfaces

When reading man pages, you'll usually see the section number in parentheses after the command, like this: reboot(8). This represents both the name of the command (reboot) and the man page

(8). When you see something in this format, you can check the man page for detailed information. (You can view a manual page with the man(1) command.)

Almost every topic has a man page. For example, to see the man page for the editor vi, enter this command:

...............................................................................................

#man vi

...............................................................................................

In response, you should see the following:

...............................................................................................

VI(1) VI(1)

NAME

ex, vi, view − text editors

SYNOPSIS

ex [−eFGRrSsv] [−c cmd] [−t tag] [−w size] [file ...] vi [−eFGlRrSv] [−c cmd] [−t tag] [−w size] [file ...] view [−eFGRrSv] [−c cmd] [−t tag] [−w size] [file ...]

LICENSE

The vi program is freely redistributable. You are welcome to copy, modify and share it with others under the condi− tions listed in the LICENSE file. If any company (not individual!) finds vi sufficiently useful that you would have purchased it, or if any company wishes to redis− tribute it, contributions to the authors would be appreci− ated.

DESCRIPTION

Vi is a screen oriented text editor. Ex is a line−ori−

:

...............................................................................................

40

The first bit of information shown on the top line gives the title of the man page and the relevant section number. (The title isn't necessarily the same as what you typed; for example, man ex would also lead you to the vi man page.)

Man Page Headings

Man pages have a variety of headings. While just about any section name can appear in a man page, several are standard. (See mdoc(7) for a partial list and other man page standards.) Like book authors, man page authors generally arrange their content in a manner that makes sense for the program they're discussing. Still, there are standard headings you will see:

∙NAME tells you the commands' various names. In this case, vi, ex, and view are all intertwined, and share a man page. (A little digging would show that they're the same program whose behavior depends on how they're activated.) The NAME also includes a brief description of the program.

∙SYNOPSIS lists the possible command−line options and their arguments. Frequently, you'll find that this header is enough to spark your memory and remind you of a flag you've used before that caused the program to behave appropriately.

∙DESCRIPTION contains a brief synopsis of the item described by the man page. The contents of this section vary depending on what the man page covers—programs, files, and kernel interfaces all have very disparate requirements.

∙OPTIONS describes a program's various command−line options and their effects.

Further discussion of the program generally follows these basic headings. Two sections that commonly follow are BUGS and SEE ALSO.

The BUGS section describes known problems with the code and can frequently save a lot of headaches. How many times have you wrestled with a computer problem, only to find out that it doesn't work the way one would expect from the happy, cheerful documentation? The goal of the BUGS section is to describe known errors and other weird behavior.[1]

SEE ALSO is traditionally the last section. Remember, UNIX is like a language, and the system is an interrelated whole. Like the Force from Star Wars, or duct tape, the SEE ALSO links will show you how everything holds together.

Sometimes, too, one name will appear in multiple sections of the manual. For example, there's a man page for amd, the AMD SCSI driver, in section 4 of the manual, and a man page for amd(8), a program that automatically mounts file systems. To read a page from a particular section of the manual, put the number between the man command and the name of the page, like this: man 4 amd. (This is the first thing to look for when you get a page that seems completely irrelevant.)

To see all man pages related to a particular subject, use man −k to do a keyword search on all the man page titles. You can also use the apropos(1) command to do the same thing, which may be easier to remember if you already know what "apropos" means.

To search a man page for a word, type / followed by the word. You'll jump down to the first

41