Next Up Previous Contents Index
On Line Help

7.1 On Line Help

When you are looking for general help on commands and error messages, the best place to start is right on your system. There are several different sources of information at your fingertips:

Let's take a look at each information source.

7.1.1 Man Pages

Almost every command on your system has an associated ``man'' page. This is documentation that you can get to instantly should you have questions or problems. For example, if you were having trouble with the ls command, you could use man to get more information by entering man ls. This will bring up the man page for ls.

The man page is viewed through the less program (which makes it easy to page forward and backward screen by screen), so all of the options to less will work while in a man page. The more important keystrokes for less are:

There are times when it's just a lot more convenient to read something from a sheet of paper. Providing you have a working printer, you can print man pages as well. If you don't have Postscript printing capability and just want to print ASCII, you can print man pages with:

man COMMAND | lpr

If you do have a postscript printer, you will probably want to print with:

man -t COMMAND | lpr

In both of those commands substitute ``COMMAND'' for the command you are trying to get help for.

Sometimes you'll find that certain system components have more than one man page. Here is a table showing the sections that are used to divide man pages:

Section Contents
1 user commands
8 system commands
2 system calls
3 library calls
4 devices
5 file formats
6 games
7 miscellaneous
9 kernel internals
n Tcl/Tk commands

This is also the order in which the sections are searched. This can be important; here's an example:

Let's say that you want to see the man page for the swapon system call. So, you type man swapon. You will actually get the man page for swapon(8), which is the command used to control swapping. Using the chart above, you can see that what you want is a ``system call'' and is located in section 2. You can then type man 2 swapon. All of this is because man searches the man directories in the order shown above, which means that the swapon(8) man page would be found before the swapon(2) man page.

You can also search the man pages for strings. You do this using
man -k string_to_search_for. This won't work, however, unless the makewhatis database has been created. Under Red Hat Linux, this is done by a cron job overnight. If you don't leave your system running overnight the database won't get created. If that is the case, run the following command as the root user:

/etc/cron.weekly/makewhatis.cron

Once you've done that (note that it might take a while), you could enter man -k swapon. That command would return:

# man -k swapon
swapon, swapoff (2) - start/stop swapping to file/device
swapon, swapoff (8) - enable/disable devices and files for
                      paging and swapping

So you can see that there are pages in section 2 and 8 both referring to swapon (and swapoff in this case).

7.1.1.1 How to Read a Man Page

Man pages provide a great deal of information in very little space. Because of this, they can be difficult to read. Here's a quick overview of the major sections in most man pages:

If you are new to Linux, don't expect to be able to use man pages as tutorials; they are meant as concise reference material. Trying to learn about Linux using the man pages is similar to trying to learn how to speak English from reading a dictionary. But there are other sources of information that may be more useful to those people just starting out with Linux; let's continue our search for documentation...

7.1.2 Package Documentation

Many packages have README files and other documentation as part of the source package. Packages built for Red Hat Linux define a standard place to install those documents so that you don't have to search through the sources to find the documents. Every package containing documentation (other than man pages, and files that need to be in specific locations) places their documentation in a subdirectory of /usr/doc.

The name of the subdirectory depends on the package name and version number. For example, the tin package might be at version 1.22. Therefore, the path to its documentation would be
/usr/doc/tin-1.22.

For the most part, the documents in /usr/doc are in ASCII. You can view them with more filename or less filename.

Having this special documentation area can be handy, but what if you're looking for documentation on a specific command (or file), and you don't know what package that command came from? No problem! Take, for example, the file /usr/bin/rtin. You're not sure what package it's part of, but you'd like to learn a bit more about it. Simply enter:

rpm -qdf /usr/bin/rtin

This command will return a listing of all the documentation (including man pages) from the package containing the file /usr/bin/rtin. RPM is capable of a lot more than this simple example. For more information on RPM, turn to Chapter 9.

Of course, maybe this kind of information is not exactly what you're looking for. Maybe you're more interested in task-oriented documentation. If so, read on...

7.1.3 HOWTOs and FAQs

If you elected to install it, most of the contents of the Linux Documentation Project (LDP) are available in /usr/doc on your system.

The directory /usr/doc/HOWTO contains the ASCII versions of all the available HOWTOs at the time your Red Hat Linux CD-ROM was mastered. These files are viewable by using the less command.

less Installation-HOWTO

You may also encounter files that end with .gz. They are compressed with gzip to save space, so you'll need to decompress them before reading. One way of reading compressed HOWTOs without cluttering your disk with uncompressed versions is to use zless:

zless 3Dfx-HOWTO.gz

The zless command uses the same keystrokes as less, so you can easily move back and forth through a HOWTO.

/usr/doc/HOWTO/mini contains the ASCII versions of all the available mini-HOWTOs. They are not compressed and can be viewed with more or less.
/usr/doc/HOWTO/other-formats/html contains the HTML versions of all the HOWTOs and the Linux Installation and Getting Started guide. To view things here, just use the web browser of your choice.

/usr/doc/FAQ contains ASCII versions (and some HTML versions) of some popular FAQs, including the RedHat-FAQ. They can be viewed using more or less, or (in the case of HTML files) with the web browser of your choice.

7.1.4 The ``locate'' Command

When you don't know the full name of a command or file, but need to find it, you can usually find it with locate. locate uses a database to find all files on your system. Normally, this database gets built from a cron job every night. This won't happen, however, if your machine isn't booted into Linux all the time. So, if that is the case, you may occasionally want to run the following command:

/etc/cron.daily/updatedb.cron

You will need to be root on your system when doing that. That will allow locate to work properly.

So, if you know you need to find all the ``finger'' files, you could run:

locate finger

It should return something like:

/usr/bin/finger
/usr/lib/irc/script/finger
/usr/man/man1/finger.1
/usr/man/man8/in.fingerd.8
/usr/sbin/in.fingerd

One thing to note, however, is that locate not only returns hits based on file name, but also on path name. So if you have a /home/djb/finger/ directory on your system, it would get returned along with all files in the directory.

7.1.5 ``info'' Pages

While man is the most ubiquitous documentation format, info is much more powerful. It provides hypertext links to make reading large documents much easier and many features for the documentation writer. There are some very complete info documents on various aspects of Red Hat (especially the portions from the GNU project).

To read info documentation, use the info program without any arguments. It will present you with a list of available documentation. If it can't find something, it's probably because you don't have the package installed that includes that documentation. Install it with RPM and try again.

If you're comfortable using emacs, it has a built in browser for info documentation. Use the [Ctrl-h] [i] key sequence to see it.

The info system is a hypertext based system. Any highlighted text that appears is a link leading to more information. Use [Tab] to move the cursor to the link, and press [Enter] to follow the link. Pressing [p] returns you to the previous page, [n] moves you to the next page, and [u] goes up one level of documentation. To exit info, press [Ctrl-x] [Ctrl-c] (control-x followed by control-c).

The best way to learn how to use info is to read the info documentation on it. If you read the first screen that info presents you'll be able to get started.


Next Up Previous Contents Index