Silicon Soul

Whether you are new to GNU/Linux or an experienced professional, having access to and knowing how to utilize command documentation is important. If you are using a system with a graphical interface (e.g., GNOME), you will have access to programs like GNOME Help, which help you get up-to-date on navigating your desktop environment.

However, the real power and flexibility of GNU/Linux systems comes from the manifold command line utilities available to them, and learning how to chain these commands together to create custom workflows. This will require continual references to documentation.

Note: If you are not familiar with the GNU/Linux command line interface, or you intend to use a script obtained from this site, review the Conventions page before proceeding.

Internal and External Commands

A GNU/Linux system has internal commands and external commands. Internal commands are those that are built into your system's shell. You can view these commands at the command line by entering help. External commands are those that exist outside of the shell as files on the file system.

For example:

$ type ip
ip is /sbin/ip

In the example above, the type command is used to help determine whether the ip command is an internal or external command. As we can see, ip is an external command that exists on the file system at /sbin/ip.

$ type cd
cd is a shell builtin

Here, we can see that cd is an internal command.

The Linux User's Manual

Most external commands have man pages. A man page is the manual page for the command. All of the man pages for all of your GNU/Linux system's commands make up the Linux User's Manual.

The Manual is divided into eight sections:

1. User commands
2. System calls (kernel functions)
3. Library calls (library functions)
4. Special files (device files found in /dev/)
5. File formats and configuration files
6. Games
7. Miscellaneous (conventions, protocols, standard file system layout, etc.)
8. System management commands (usually, commands reserved for the root user)

You can find out more about these sections by entering man 7 man-pages at the command line.

To determine where man pages are saved on your system, you can use the manpath command. This command will output a colon-delimited list of directory locations where your shell will search for command man pages, from left to right.

The output will look something like this:

$ manpath
/usr/share/man:/usr/local/man:/usr/local/share/man

The man Command

If you know the name of a command, you can view its man page like so:

man ex_command

For example, you can view the man page for the ls command by entering man ls at the command line.

When you are examining man pages, you will often see references that include a number in parentheses, e.g., free(3). This is a suggestion to refer to the free command's man page in section 3 of the Linux User's Manual for more information.

You can view a command's man pages from specific sections of the Manual by using man's -s ex_sections (--section=ex_sections) option:

man -s ex_sections ex_command

ex_sections can be a colon- or comma-separated list of order specific manual sections to search.

Alternatively, you can leave off the -s option:

man ex_sections ex_command

Finally, you can use a dot syntax:

man ex_command.ex_section

For example, man free.3

Not all commands have entries in multiple sections of the Manual. Most often, you will be viewing man pages for commands in section 1.

less Keyboard Shortcuts

man pages are displayed using the less command. less is a paginator program that makes it easy to browse and search text. Before we continue, a primer on how to navigate content piped through less is warranted.

↓ or e or j or Enter

Scroll down one line at a time.

↑ or y or k

Scroll up one line at a time.

f or Space or Page Down

Scroll down one page at a time.

b or Page Up

Scroll up one page at a time.

g or Home

Move to the beginning of the output.

G or End

Move to the end of the output.

/ ex_term

Search forward for a term in the output.

You can move to the next instance of a term by pressing n. You can move to the previous instance of a term by pressing N.

? ex_term

Search backward for a term in the output.

q

Quit.

man pages

man pages are divided into sections, too. Some of the most commonly used sections are:

Title

The first line of a man page.

NAME

Displays the name of the command, file, or utility, and a short abstract.

SYNOPSIS

Provides a brief description of the syntax for using a command/utility.

• Bold text means that the text should be entered exactly as shown.
• Text in square brackets ([]) is for optional mutually exclusive items (delimited by a |).
• Text in curly braces ({}) is for required mutually exclusive items (delimited by a |).
• Underlined or italicized text indicates a placeholder.
• Ellipses (...) after an argument or expression indicate that the argument/expression is repeatable.

DESCRIPTION

Describes how the command, file, or utility works in detail.

OPTIONS

The command's options.

FILES

Auxiliary files.

EXAMPLES

Sample commands.

AUTHOR(S)

Displays the name(s) of the programmer(s) who wrote the command, utility, or service.

BUGS

Known limitations of the command.

REPORTING BUGS

Provides an email address you can use to report any bugs you discover.

COPYRIGHT

Provides details about who owns the copyright to the command, utility, or service.

SEE ALSO

Provides a list of man pages or other resources that are related to the current man page.

Version Number and Revision Date

The last line of the man page.

All of these sections, other than NAME, are optional.

man Options

The man command has many options you can use to adjust its output. Here are a few of the most useful ones:

-a, --all

Display all man pages for the given command in all Manual sections, e.g., man -a printf.

After issuing this command, you will brought into the first Manual section for the command you specified. After you press q, you will be presented with options to view the man page for your command in the next Manual section (Enter), to skip the man page for your command in the next Manual section (Ctrl+d), or to quit (Ctrl+c).

-f, --whatis

Provides a short description of a command, e.g., man -f sed.

This provides the same output as the whatis command.

-k, --apropos

Searches for a term across all of the Manual's man pages, e.g., man -k awk.

When using the -k option, man does not just search the man page NAME sections, but also the DESCRIPTION sections for the term you specified. man returns the NAME lines for any commands that contain your specified term.

This provides the same output as the apropos command.

-t

Formats a man page's output into the default troff or groff format, which is usually PostScript.

You can use this command with the ps2pdf command to generate a PDF file of a command's man page, e.g., man -t ls | ps2pdf - 'ls.pdf'.

Online man Pages

If you want to peruse GNU/Linux man pages from your browser, die.net is a great resource. A Google custom search will help you find the command you are looking for, or you can browse the man pages by name.

Also, Computer Hope provides an excellent resource for GNU/Linux commands. The command pages they provide are not man pages, but they are nicely formatted with useful examples.

GNU Info

Information for a GNU/Linux command may be spread across several sections of the Linux User's Manual. This can become unwieldy when dealing with a complicated command that has extensive documentation.

This is one reason why Richard Stallman and Bob Chassell created GNU Info. GNU Info provides a single source file to produce output in myriad formats, both online and printed (e.g., html, info, pdf). GNU Info is the GNU project's standard documentation format (info), which it prefers as an alternative to man.

The info system is more free-form than the man system and supports linked sub-sections. Different topics are connected using links, and information can be viewed through either a command line interface (CLI) or a graphical user interface (GUI), printed, or viewed online.

Info pages that contain topics are referred to as nodes. Nodes are like sections/subsections in written documentation. With keyboard shortcuts, you can move between nodes or view each node sequentially.

Each node may contain menus and linked subtopics, or items. Items are like Internet hyperlinks. They are defined by an asterisk (*) at the beginning of the item name. Name items are denoted with double-colons (::) at the end of the item name. Items can refer to other nodes within a file, or to other files.

Unlike man pages, GNU Info may not be installed on your GNU/Linux distribution, but you should be able to find it in your distribution's repository. Here is a brief summary on how to get started with GNU Info.

info

Displays an index of available topics.

info ex_topic

View help for a particular topic (e.g., info ls).

GNU Info Keyboard Shortcuts

↓

Scroll down one line at a time.

↑

Scroll up one line at a time.

Page Down or Space

Scroll down one page at a time.

Page Up or Back

Scroll up one page at a time.

Home or b

Move to the beginning of the node.

End

Move to the end of the node.

n

Move to the next sibling node.

p

Move to the previous sibling node.

u

Move up to the parent node.

l

Move to the last visited node.

t

Move to the top node in the file.

i ex_entry.

Search for Index entry (e.g., i cat)

Ctrl+s, ex_term

Search for a term in a GNU Info node.

You can jump to the next instance of your term by pressing Ctrl+s again.

q

Quit.

Internal Command Documentation

As previously stated, internal commands are commands that are built into the shell itself. There are no man pages for internal commands, but you can view a comparable document with the help command.

help ex_internal_command

Example:

help shopt

Keep in mind, some commands may have both an internal and external version installed on your system, and thus have both help and man page documentation, e.g., echo. You can tell which version of a command your shell will use with the type command:

$ type echo
echo is a shell builtin

The above output is the shell telling you that when you use the echo command at the command line, it will be using the internal version of the command.

If you want to force the use of an external version of a command, you can specify the full path to the command:

'/bin/echo' 'Hi there!'

If you want to force the use of an internal command, you can use the builtin command, e.g., builtin echo 'Hi there!' . This is useful when you want to redefine an internal command as a custom function, and you want to use the internal command within your function.