Getting Help in the Shell

The commands you can type in the shell are almost always the names of executable programs elsewhere in the system. Some shell commands are internal and specific to each particular shell (such as alias), but most commands must correspond to some installed program. The trick in using the shell efficiently is knowing which of these programs does what. That's where the built-in "manual" comes in. The manual is invoked using the man command, and you can find information on any known command or program like so:

# man ls

This would give you a full, browseable set of documentation on the ls ("list") command and all its available options. The same method will get you information and syntax for any installed program, whether it came with FreeBSD or was installed after the fact.

You can use the spacebar, the arrow keys, and the Page Up/Page Down keys to review the contents of the manual page, or press / and enter a text string to search for that string. Press Q to exit the manual.

Searching for Manual Pages

Sometimes, you might know what you want to do, but you are not sure of the name of the command to use. In this case, you can use the -k option to the man command to specify a general concept and return a list of possible commands that might help execute it. Sometimes, you have to be fairly creative about what you search for in order for man -k to return the results you want. For example, suppose you want to find out about commands that can search text files for certain words or phrases, and you want to show each place in the text file where a certain word or phrase occurs. You would likely assume that such commands would have "search" in their names or their descriptions. First, you might try the man -k search command, as shown in Listing 8.1. The output of this command is a list of all the relevant entries in the whatis database, a dictionary of programs and their descriptions. (The output on your system may be different depending on what software you have installed.)

Listing 8.1. Using man -k

# man -k search apropos(1), whatis(1) - search the whatis database bios(9), bios_sigsearch(9), bios32_SDlookup(9), bios32(9) - Interact with PC BIO S bsearch(3)               - binary search of a sorted table devclass_find(9)         - search for a devclass device_find_child(9)     - search for a child of a device lkbib(1)                 - search bibliographic databases lookbib(1)               - search bibliographic databases lsearch(3), lfind(3)     - linear searching routines manpath(1)               - determine user's search path for man pages res_query(3), res_search(3), res_mkquery(3), res_send(3), res_init(3), dn_comp(3 ), dn_expand(3) - resolver routines tsearch(3), tfind(3), tdelete(3), twalk(3) - manipulate binary search trees Search::Dict(3), look(3) - search for key in dictionary file

This probably isn't what you had in mind. The results seem to be geared toward search routines for programmers using C. For your next attempt, you try searching for the keyword pattern, as shown in Listing 8.2, because you want a command that finds patterns in text files.

Listing 8.2. Another Attempt with man -k

# man -k pattern gawk(1) - pattern scanning and processing language glob(3), globfree(3)     - generate pathnames matching a pattern grep(1), egrep(1), fgrep(1), zgrep(1) - print lines matching a pattern lptest(1)                - generate lineprinter ripple pattern menu_pattern(3)          - get and set a menu's pattern buffer

Now that looks more usefulespecially the grep series of commands. These seem to be tools for searching for patterns within files, as you hoped. You could now type man grep to read the man page for grep, and you would find that indeed this command does what you need.

Command Summaries

At other times, you might know the name of a command but are not sure what it does (if you are poking around in /usr/bin or /usr/games, for example). You can use the -f option to man to get a short, one-line description of a command. For example, suppose you find the command pom in the /usr/games directory, and you want to know what it does:

# man -f pom pom(6) - display the phase of the moon

The (6) at the end of the command name is the section of the manual that the command comes from.

Manual Sections

The online manuals are divided into nine sections, as detailed in Table 8.1.

Table 8.1. Manual Sections

Section	Description
1: User Commands	Information on user commands such as ls, rm, cp, and grep. This is the section you will probably use most often while working with and learning FreeBSD.
2: System Calls	Contains information on various APIs for FreeBSD. This section is primarily of interest to C programmers.
3: Subroutines	This section contains information on subroutines, also known as library functions. Once again, this is mostly of interest to C programmers.
4: Devices	More stuff for C programmers. Contains information on interfacing with device drivers in FreeBSD.
5: File Formats	Contains information on the formats of various system configuration files, such as the crontab files for the scheduling of regular jobs and the rc scripts for controlling system startup.
6: Games	Naturally, the most important section of the manual. This section contains instructions for playing the various games and other amusements that come with FreeBSD.
7: Miscellaneous	If your topic doesn't fit anywhere else, it will be found here.
8: System Administration	Contains information on commands related to system administration, such as fsck, for checking filesystems.
9: Kernel Interfaces	More information for programmers. This section contains information on interfacing with the kernel in C.

Some commands have more than one entry. For example, the crontab enTRy has an entry in Section 1 for the crontab command and also an entry in Section 5 for the format of the crontab file. If you don't specify a manual section when you use the man command, you'll get the first entry in the manual that matches what you're looking forin the case of man crontab, this means that you get the entry listed in Section 1, describing the command syntax. If you want to see the entry on file formats in Section 5, use man 5 crontab.