Page Body

GNU/Linux Documentation

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, 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 filesystem.

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 filesystem 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 filesystem 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

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

man example_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 page from a specific section of the Manual by entering:

man -s example_section example_command

Or, you can leave off the -s option:

man example_section example_command

Finally, you can use a dot syntax:

man example_command.example_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
/ example_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.

? example_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
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
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 (Control+d), or to quit (Control+c).
-f
Provides a short description of a command, e.g., man -f sed. This provides the same output as the whatis command.
-k
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 example_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 example_entry
Search for Index entry (e.g., i cat)
Control+s, example_term
Search for a term in a GNU Info node

You can jump to the next instance of your term by pressing Control+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 example_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.

Command Precedence

The order of precedence for commands when entered at the command line is:

  1. Aliases
  2. Keywords (e.g., if, for)
  3. Functions
  4. Internal commands (e.g., cd, type)
  5. Scripts and external commands

Keeping this rule in mind will help you understand what to expect when you execute commands on your shell.

Avatar

Enjoyed this post?

Subscribe to the feed for the latest updates.