Introduction

The online manual

The most comprehensive documentation on FreeBSD is the online manual, usually referred to as the man pages. Nearly every program, file, library function, device or interface on the system comes with a short reference manual explaining the basic operation and various arguments. If you were to print it out, it would run to well over 8,000 pages.

When online, you view the man pages with the command man. For example, to learn more about the command ls, type:

$ man ls
LS(1)   FreeBSD Reference Manual   LS(1)
NAME
   ls - list directory contents
SYNOPSIS
   ls [-ACFLRTacdfiloqrstu1][file ... ]
DESCRIPTION
   For each operand that names a file of a type other than directory, ls
   displays its name as well as any requested, associated information. For
   each operand that names a file of type directory, ls displays the names.
(etc)

In this particular example, with the exception of the first line, the text in constant width bold is not input, it's the way it appears on the screen.

The online manual is divided up into sections numbered:

1. User commands
2. System calls and error numbers
3. Functions in the C libraries
4. Device drivers
5. File formats
6. Games and other diversions
7. Miscellaneous information
8. System maintenance and operation commands
9. Kernel interface documentation

In some cases, the same topic may appear in more than one section of the online manual. For example, there is a user command chmod and a system call chmod(). In this case, you can tell the man command which you want by specifying the section number:

$ man 1 chmod 

This command displays the manual page for the user command chmod. References to a particular section of the online manual are traditionally placed in parentheses in written documentation. For example, chmod(l) refers to the user command chmod, and chmod(2) means the systcode call.

This is fine if you know the name of the command and forgot how to use it, but what if you can't recall the command name? You can use man to search for keywords in the command descriptions by using the -k option, or by starting the program apropos:

$ man -k mail $
apropos mail

Both of these commands do the same thing: they show the names of the man pages that have the keyword mail in their descriptions.

Alternatively, you may browse through the /usr/bin directory, which contains most of the system executables. You'll see lots of file names, but you don't have any idea what they do. To find out, enter one of the lines:

$ cd /usr/bin; man -f * 
$ cd /usr/bin; whatis *

Both of these commands do the same thing: they print out a one-line summary of the purpose of the program:

$ cd /usr/bin; man -f *
a2p(1)        - Awk to Perl translator
addftinfo(l)  - add information to troff font files for use with groff
apply(l)      - apply a command to a set of arguments
apropos(1)    - search the whatis database
...etc

Printing man pages

If you prefer to have man pages in print, rather than on the screen, you can do this in two different ways:

• The simpler way is to redirect the output to the spooler:

  $ man ls | lpr

  This gives you a printed version that looks pretty much like the original on the screen, except that you may not get bold or underlined text.
• You can get typeset output with troff:

  $ man -t ls | lpr
  

  This gives you a properly typeset version of the man page, but it requires that your spooling system understand PostScript—see page 271 for more details of printing PostScript, even on printers that don't understand PostScript.

GNU info

The Free Software Foundation has its own online hypertext browser called info. Many FSF programs come with either no man page at all, or with an excuse for a man page (gcc, for example). To read the online documentation, you need to browse the info files with the info program, or from Emacs with the info mode. To start info,simply type:

$ info

In Emacs, enter CTRL-h i or ALT-x info. Whichever way you start info, you can get brief introduction by typing h, and a quick command reference by typing ?.

Other documentation on FreeBSD

FreeBSD users have access to probably more top-quality documentation than just about any other operating system. Remember that word UNIX is trademarked. Sure, the lawyers tell us that we can't refer to FreeBSD as UNIX, because UNIX belongs to the Open Group. That doesn't make the slightest difference to the fact that nearly every book on UNIX applies more directly to FreeBSD than any other flavour of UNIX. Why?

Commercial UNIX vendors have a problem, and FreeBSD doesn't help them: why should people buy their products when you can get it free from the FreeBSD Project (or, for that matter, from other free UNIX-like operating systems such as NetBSD, OpenBSD and Linux)? One obvious reason would be "value-added features." So they add features or fix weak points in the system, put a copyright on the changes, and help lock their customers in to their particular implementation. As long as the changes are really useful, this is legitimate, but it does make the operating system less compatible with "standard UNIX," and the books about standard UNIX are less applicable.

In addition, many books are written by people with an academic background. In the UNIX world, this means that they are more likely than the average user to have been exposed to BSD. Many general UNIX books handle primarily BSD, possibly with an additional chapter on the commercial System V version.

In Appendix A, Bibliography, you’ll find a list of books that I find worthwhile. I'd like to single out some that I find particularly good, and that I frequently use myself:

• UNIX Power 7oo/s, by Jeny Peek, Tim O'Reilly, and Mike Loukides, is a superb collection of interesting information, including a CD-ROM. Recommended for everybody, from beginners to experts.
• UNIX for the Impatient ,by Paul W. Abrahams and Bruce R. Larson, is more similar to this book, but it includes a lot more material on specific products, such as shells and the Emacs editor.
• The UNIX System Administration Handbook, by Evi Nemeth, Garth Snyder, Scott Seebass, and Trent R. Hein, is one of the best books on systems administration I have seen. It covers a number different UNIX systems, including an older version of FreeBSD.

There are also many active Internet groups that deal with FreeBSD. Read about them in the online handbook.