With hundreds, if not thousands, of commands, it is beyond the capacity of the average human mind to remember all of this information. There is not a shortage of documentation about Linux commands. The basic sources of information are:
- The man (manual) pages provide a condensed statement of the syntax for a command. They are not always complete and accurate, but they are the starting point for command syntax. The man command provides access to these pages. Shell builtin commands are documented in the man page for the shell.
- The info command provides an expanded tutorial for many commands. If such a tutorial does not exist, the info command displays the man page.
- The /usr/share/doc directory contains documentation for many commands.
- Most commands support a -h or --help option that gives a quick overview of the command syntax
- The Linux Documentation Project is the source for HOWTO's. Guides, FAQs, and man pages.
- The GNU Project provides Online Manuals for many packages.
- Each Linux distro provides documentation, wikis, FAQs, and forums
- A Google search is a gateway to all sorts of Linux documentation
The man page is the core of the documentation for the CLI (Command Line Interface). The man pages are divided into eight sections:
- General - Commands executable by a normal user
- System Calls - Documentation for C library routines that generate system calls
- Subroutines - Documentation for C library routines that do not generate system calls
- Special Files - Documentation for many of the special files in the /dev directory
- File Formats - Documents the file for many of the system files
- Games - Documents the CLI oriented games
- Macros and Conventions - This section used to be called Miscellaneous, but the new title is more descriptive
- Maintenance Commands - As the name implies, this section contains the documentation for commands oriented towards system maintenance
If the POSIX man pages are installed on your system, each section will have a corresponding set of POSIX man pages. They appear with the 'p' appended to the section name, such as 1p or 8p. While the Linux commands are largely POSIX (Portable Operating System Interface) compliant. POSIX is a standard for Unix and Unix-like commands, including the shell. Actual commands may have extensions to the POSIX standard that are only documented in the man page for that command.
The man pages, themselves, have a standard layout, as follows:
- NAME - The name, or names, for the command along with a short description
- SYNOPSIS - This section specifies the command syntax
- CONFIGURATION - Rarely present, but describes any configuration options
- DESCRIPTION - Usually a brief description, but some are quite long
- OPTIONS - A brief description of each option
- EXIT STATUS - For commands, this value indicates if there was an error. An exit value of zero means no errors.
- RETURN VALUE - Usually appears on man pages for library functions
- ERRORS - Describes the error codes returned in the EXIT STATUS.
- ENVIRONMENT - Describes any environmental variables used by the command
- FILES - Usually refers to related configuration files
- NOTES - If present, contains any special notes that do not fit within another section
- BUGS - In practice, this section contains information about special limitations, as true bugs are fixed through new versions
- EXAMPLE - When present, provides useful examples of how to use the command
- AUTHOR - The authors who wrote the man page
- SEE ALSO - A handy reference to any other man pages that are related to the current man page
The man command is the primary tool for displaying man pages. The man command has a lot of options. However, for this course, we can keep it simple. The day-to-day syntax for the command is as follows:
man [section] NAME
where NAME is the name of the page you wish to display. If the name exists in multiple sections, you will be prompted for the section that you wish to display. You can declare the section, in advance, by specifying the section name on the command line. For example, if both the GNU and POSIX man pages are installed, the man command will prompt you as in the following:
$ man cat Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this) * cat (1) cat (1p) Man: What manual page do you want? Man:
You can either select the man page that you wish, or just wait a few seconds for the man command to display the default page, as indicated by the asterisk. The following command indicates the desired section in advance:
$ man 1 cat
By default, man sends the output to the less command for display and pagination. We will cover the less command later in this chapter. For now you need to know that that space bar takes you forward a page, the 'b' key takes you back a page, and 'q' quits. You can also send the output to a Web browser with the following command:
$ man -Hfirefox cat
It is important that you not put a space between the -H and the browser command. While the above example uses the Firefox browser, you can use any browser. From the CLI, you can launch as graphical program. If you are using a console connection, you will have to start the graphical server before running the command. From the terminal emulation window, there is no problem.
To see all the options for the man command, just type:
$ man man
Linux distributions do vary regarding the man pages installed, and available in the repository. Of the distros covered in this course, you will find that:
- The only man pages on Fedora are those installed by various packages. There are no man pages for the core utilities. The best you can do is install the man-pages package, which contains the POSIX compliant man-pages.
- Ubuntu, and its derivatives, do not provide man pages for any of the built-in commands that do not have a born shell counterpart. For example, the cd command is a built-in command for both Bourne Shell and BASH. Thus there is no man page for the cd command. You need to read the documentation for the command in the bash man page.
There are several Web resources for man pages:
- The bash man page is long, and the section on built-in commands is not anywheres close to the front. Rather than scrolling through the bash man page, you can find the documentation for the built-in commands at the GNU Project Documentation.
- http://linuxmanpages.com/ provides a complete set of Linux man pages, as does Linux Man Pages Online.
If you are not sure of the name of the command that you need to use, you can search through the database of the SYNOPSIS section using either of the following commands:
apropos <keyword> man -k <keyword>
$ man -k concatenate cat (1) - concatenate files and print on the standard output cat (1p) - concatenate and print files pnmcat (1) - concatenate Netpbm images strcat (3) - concatenate two strings strcat (3p) - concatenate two strings strncat (3) - concatenate two strings strncat (3p) - concatenate a string with part of another tac (1) - concatenate and print files in reverse tccat (1) - concatenate multimedia streams from medium and print on the standard output wcscat (3) - concatenate two wide-character strings wcscat (3p) - concatenate two wide-character strings wcsncat (3) - concatenate two wide-character strings wcsncat (3p) - concatenate a wide-character string with part of another zcat 1p) - expand and concatenate data
If the command complains about a missing database, you need to run the following command to initialize the database:
$ sudo mandb
The sudo command will ask for your user password. If you are authorized to run the command, the mandb command will update the database
While the man pages are oriented towards quick reference, the info command provides information that is more tutorial in nature. When info does not have a page in its library, it will display the man page. For those new to the info command, you can start with just typing:
This presents a screen similar to the following:
This is not a graphical window. It is purely text based. The info command has its own set of commands for navigating through it is collection of documents. The most important keys to remember is the space bar move you forward a page, the 'q' key quits the info command, the 'h' key gives you an quick summary of the info commands, and the 'H' key links to a tutorial on the info command. If you have never went through the entire list of information available, just page through the index by continually pressing the space bar.