Linux - Getting Help

Part 1: man Pages

As previously mentioned, UNIX was the operating system from which the Linux foundation was built. The developers of UNIX created help documents called man pages (man stands for manual).

Man pages are used to describe the features of commands. They will provide you with a basic description of the purpose of the command, as well as provide details regarding the options of the command.

 

1. Viewing man pages

To view a man page for a command, execute man command in a terminal window. For example, the command man cal will display the man page for thecal command:

 

2. Controlling the man Page Display

The man command uses a "pager" to display documents. Normally this pager is the less command, but on some distributions it may be the more command.

If you want to view the various movement commands that are available, you can type the letter h while viewing a man page. This will display a help page (note: If you are working on a Linux distribution that uses the more command as a pager, your output will be different than the example shown here):

If your distribution uses the less command, you might be a bit overwhelmed with the large number of "commands" that are available. The following table provides a summary of the more useful commands:

Command	Function
Return (or Enter)	Go down one line
Space	Go down one page
/term	Search for term
n	Find next search item
1G	Go to beginning
G	Go to end
h	Display help
q	Quit man page

 

3. Sections of the man Page

Man pages are broken into sections. Each section is designed to provide specific information about a command. While there are common sections that you will see in most man pages, some developers also create sections that you will only see in a specific man page.

The following table describes some of the more common sections that you will find in man pages:

Section name	Purpose
NAME	Provides the name of the command and a very brief description.
SYNOPSIS	Provides examples of how the command is executed. See below for more information.
DESCRIPTION	Provides a more detailed description of the command.
OPTIONS	Lists the options for the command as well as a description of how they are used. Often this information will be found in the DESCRIPTION section and not in a separate OPTIONS section.
FILES	Lists the files that are associated with the command as well as a description of how they are used. These files may be used to configure the command's more advanced features. Often this information will be found in the DESCRIPTION section and not in a separate OPTIONS section.
AUTHOR	The name of the person who created the man page and (sometimes) how to contact the person.
REPORTING BUGS	Provides details on how to report problems with the command.
COPYRIGHT	Provides basic copyright information.
SEE ALSO	Provides you with an idea of where you can find additional information. This also will often include other commands that are related to this command.

 

 

Part 2: man Pages Categrized by Sections

Until now, we have been displaying man pages for commands. However, sometimes configuration files also have man pages. Configuration files (sometimes called system files) contain information that is used to store information about the Operating System or services.

Additionally, there are several different types of commands (user commands, system commands, and administration commands) as well as other features that require documentation, such as libraries and Kernel components.

As a result, there are thousands of man pages on a typical Linux distribution. To organize all of these man pages, the pages are categorized by sections, much like each individual man page is broken into sections.

By default there are nine default sections of man pages:

1. Executable programs or shell commands
2. System calls (functions provided by the kernel)
3. Library calls (functions within program libraries)
4. Special files (usually found in /dev)
5. File formats and conventions, e.g. /etc/passwd
6. Games
7. Miscellaneous (including macro packages and conventions), e.g.man(7), groff(7)
8. System administration commands (usually only for root)
9. Kernel routines [Non standard]

When you use the man command, it searches each of these sections in order until it finds the first "match". For example, if you execute the command man cal, the first section (Executable programs or shell commands) is searched for a man page called cal. If not found, then the second section is searched. If no man page is found after searching all sections, you will receive an error message:

 

 

1. Determining Which Section

To determine which section a specific man page belongs to, look at the numeric value on the first line of the output of the man page. For example, if you execute the command man cal, you will see that the cal command belongs to the first section of man pages:

 

 

2. Sepcifying a Section

In some cases you will need to specify the section in order to display the correct man page. This is necessary because sometimes there will be man pages with the same name in different sections.

For example, there is a command called passwd that allows you to change your password. There is also a file called passwd that stores account information. Both the command and the file have a man page.

The passwd command is a "user" command, so the command man passwd will display the man page for the passwd command by default:

To specify a different section, provide the number of the section as the first argument of the man command. For example, the command man 5 passwd will look for the passwd man page just in section 5:

 

3. Searching Sections

Sometimes it isn't clear what section a man page is stored in. In cases like this, you can search for a man page by name.

The -f option to the man command will display man pages that match, or partially match, a specific name and provide a brief description of each man page:

Note that on most Linux distributions, the whatis command does the same thing as man -f. On those distributions, both will produce the same output.

 

4. Searching man Pages by Keyword

Unfortunately, you won't always remember the exact name of the man page that you want to view. In these cases you can search for man pages that match a keyword by using the -k option to the man command.

For example, what if you knew you wanted a man page that displays how to change your password, but you didn't remember the exact name? You could run the command man -k password:

When you use this option, you may end up with a large amount of output. The preceding command, for example, provided over 60 results.

Recall that there are thousands of man pages, so when you search for a keyword, be as specific as possible. Using a generic word, such as "the" could result in hundreds or even thousands of results.

Note that on most Linux distributions, the apropos command does the same thing as man -k. On those distributions, both will produce the same output.

 

Part 2: info Command

Man pages are great sources of information, but they do tend to have a few disadvantages. One example of a disadvantage is that each man page is a separate document, not related to any other man page. While some man pages have a SEE ALSO section that may refer to other man pages, they really tend to be unrelated sources of documentation.

The info command also provides documentation on operating system commands and features. The goal of this command is slightly different from man pages: to provide a documentation resource that provides a logical organizational structure, making reading documentation easier.

Within info documents, information is broken down into categories that work much like a table of contents that you would find in a book. Hyperlinks are provided to pages with information on individual topics for a specific command or feature. In fact, all of the documentation is merged into a single "book" in which you can go to the top level of documentation and view the table of contents representing all of the documentation available.

Another advantage of info over man pages is that the writing style of info documents is typically more conducive to learning a topic. Consider man pages to be more of a reference resource and info documents to be more of a learning guide.

 

1. Displaying info Documentation for a Command

To display the info documentation for a command, execute info command(replace command with the name of the command that you are seeking information about). For example, the following demonstrates the output of the command info ls:

Notice that the first line provides some information that tells you where you are in the info documentation. This documentation is broken up into "nodes" and in the example above you are currently in the "ls invocation" node. If you went to the next node (like going to the next chapter in a book), you would be in the "dir invocation" node. If you went up one level you would be in the "Directory listing" node.

 

2. Moving Around While Viewing an info Document

Like the man command, you can get a listing of movement commands by typing the letter h while reading the info documentation:

Note that if you want to close the help screen, you type the letter l. This brings you back to your document and allows you to continue reading. To quit entirely, you type the letter q.

The following table provides a summary of useful commands:

Command	Function
Down arrow	Go down one line
Space	Go down one page
s	Search for term
[	Go to previous node
]	Go to next node
u	Go up one level
TAB	Skip to next hyperlink
HOME	Go to beginning
END	Go to end
h	Display help
L	Quit help page
q	Quit info command

If you scroll though the document, you will eventually see the menu for the lscommand:

The items under the menu are hyperlinks that can take you to nodes that describe more about the ls command. For example, if you placed your cursor on the line "* Sorting the output::" and pressed the Enter key, you would be taken to a node that describes sorting the output of the ls command:

Note that by going into the node about sorting, you essentially went into a sub-node of the one in which you originally started. To go back to your previous node, you can use the u key. While u will take you to the start of the node one level up, you could also use the l key to return you exactly to the previous location that you were before entering the sorting node.

 

 

Part 3: Additional Sources of Help

In many cases, you will find that either man pages or info documentation will provide you with the answers you need. However, in some cases, you may need to look in other locations.

 

1. Using the --help Option

Many commands will provide you basic information, very similar to the SYNOPSIS found in man pages, when you apply the --help option to the command. This is useful to learn the basic usage of a command:

 

2. Additional System Documentation

On most systems, there is a directory where additional documentation is found. This will often be a place where vendors who create additional (third party) software can store documentation files.

Typically, this will be a place where system administrators will go to learn how to set up more complex software services. However, sometimes regular users will also find this documentation to be useful.

These documentation files are often called "readme" files, since the files typically have names such as README or readme.txt. The location of these files can vary depending on the distribution that you are using. Typical locations include/usr/share/doc and /usr/doc.

 

Part 4: Finding Commands and Documentation

Recall that the whatis command (or man -f) will tell you which section a man page is stored in. If you use this command often enough, you will likely come across an unusual output, such as the following:

Based on this output, there are two commands that list directory contents. The simple answer to why there are two ls commands is that UNIX had two main variants, which resulted in some commands being developed "in parallel". This resulted in some commands behaving differently on different variants of UNIX. Many modern distributions of Linux include commands from both UNIX variants.

This does, however, pose a bit of a problem: when you run the ls command, which command is executed? The focus of the next few sections will be to answer this question as well as to provide you with the tools to find where these files reside on the system.

 

1. Where are These Commands Located?

To search for the location of a command or the man pages for a command, use the whereis command. This command searches for commands, source files and man pages in specific locations where these files are typically stored:

Man pages are normally easily distinguished between commands as they are normally compressed with a command called gzip, resulting in a filename that ends in .gz.

The interesting note is that you see there are two man pages listed, but only one command (/bin/ls). This is because the ls command can be used with the options/features that are described by either man page. So, when you are learning what you can do with the ls command, you can explore both man pages. Fortunately, this is more of an exception as most commands only have one man page.

 

 

2. Find Any File or Directory

The whereis command is designed to specifically find commands and man pages. While this is useful, there are times where you want to find a file or directory, not just files that are commands or man pages.

To find any file or directory, you can use the locate command. This command will search a database of all files and directories that were on the system when the database was created. Typically, the command to generate this database is run nightly.

Any files that you created today will not normally be searchable with the locatecommand. If you have access to the system as the root user (the system administrator account), you can manually update the locate database by running the updatedb command. Regular users cannot update the database file.

Also note that when you use the locate command as a regular user, your output may be limited due to file permissions. Essentially, if you don't have access to a file or directory on the filesystem due to permissions, the locate command won't return those names. This is a security feature designed to keep users from "exploring" the filesystem by using the locate database. The root user can search for any file in the locate database.

 

3. Count the Number of Files

The output of the locate command can be quite large. When you search for a filename, such as passwd, the locate command will produce every file that contains the string passwd, not just files named passwd.

In many cases, you may want to start by listing how many files will match. You can do this by using the -c option to the locate command:

 

4. Limiting the Output

You can limit the output produced by the locate command by using the -boption. This option will only include listings that have the search term in thebasename of the filename. The basename is the portion of the filename not including the directory names.

As you can see from the previous output, there will still be many results when you use the -b option. To limit the output even further, you place a \character in front of the search term. This character limits the output to filenames that exactly match the term: