With seemingly countless commands available from the UNIX command line—a
quick, cursory accounting yields more than 1,500—and each of those with a raft
of features, it's impossible to remember every option, nuance, and permutation. Worse,
because the universe of UNIX commands evolved over a 40-year period, there are few
punctilios. For example,
-l means "long format" in
ls, but other file-related utilities do not assign the same
meaning to the option, if that option is available at all. Further, and ironically, some
command-line programs support
--help, which prints a
terse usage hint, but not all do. As powerful as the command line is, the learning curve
can be proportionally maddening.
At least at first. Over time, like learning any skill, oft-used command permutations become instinctual and part of muscle memory. Moreover, depending on the shell you use, you can commit a frequently used command-line combination to an alias or a shell script, reducing the burden on your memory. Some shells also maintain lengthy histories that persist previously used commands session over session.
Alas, memory fades and new challenges arise. To truly master the command line, you can't fight the man. The man system, that is, UNIX's built-in, online reference system. In fact, the UNIX community has a longstanding mantra reserved for the most confounding problems: "RTFM!" or "Read the frickin' man page!"
The man system
The UNIX man system is composed of two parts: a collection of online documents
and an accompanying document reader. Each document is called a man page;
a man page can be very brief or quite lengthy, depending on the topic. The
document reader is simply another command-line utility, aptly named
To read the documentation for a piece of software installed on your system, simply
man component, where component
is the name of the software. For example, to read about the
$ man ls
You can even read about
$ man man
component is installed and has
a man page, you should see a display like Figure 1, which
shows the page for
ls. If the man page you name
No manual entry for component. (There are
other techniques to find a suitable man page besides naming it. More on that
in a moment.)
Figure 1. The man document reader running within a terminal window
Typically, every significant piece of software found on a UNIX machine—including each command-line utility, each system call, each callable function of a programming library, and each file format—includes a complementary man page. Indeed, it's considered proper etiquette to write and provide man pages when you build new software.
Historically, the repository for man pages has been anchored at /usr/man. More recently, the central store has moved to /usr/share/man, although the exact location can differ from one UNIX vendor to the next. Additionally, it's not uncommon for a software package to store its man pages in a subdirectory of its root. For instance, some releases of the MySQL database engine store man pages in /usr/local/mysql/man. Any of these strategies is permitted, albeit some extra configuration is required if man pages are allocated among many repositories.
Regardless of its location, each repository is subdivided into one or more sections. Each section is realized as an independent subdirectory, and each is named by convention. There's man1, man2, and so on, up through man8, and each one represents a class of commands. Table 1 lists the section names and their contents.
Table 1. Man repository sections and their contents
|man1||General commands. Typically, the commands found in this section do
not require superuser, or administrative, privileges. |
|man2||System calls, or functions that access services provided by the UNIX kernel.
|man4||Special files, such as devices and drivers.|
|man5||File formats. UNIX uses text configuration files almost exclusively to customize the operation of the system. There are lots of configuration files, from the list of network services (/etc/services) to the list of available shells (/etc/shells).|
|man6||Games and screensavers.|
|man7||Miscellaneous files. This is a catch-all category. On a traditional system, you can learn about glob operators, regular expressions, and more.|
|man8||System administration commands, or those that the superuser is likely to use.|
In some instances, components in different sections may share the same name. This
happens regularly, especially when a software package has multiple parts that
work together. For example, the
which submits jobs to be scheduled, is found in section 1. Meanwhile, the crontab
file format, which describes jobs to run, can be found in section 5.
To differentiate between a component in one section or another, provide the section number as the first argument:
$ man 1 crontab $ man 5 crontab
The former command details the command; the latter command shows the file format.
If software exists in multiple sections and you do not specify the section number,
man shows the matching occurrence from the lowest
The contents of a man page
Although options may vary wildly from command to command, the contents of a man page are highly regular. Indeed, man pages are invaluable because of the conventions. After reading just a handful, you can quickly jump to the right portion of the document to find the information you seek.
A minimal man page includes five segments: a name, a synopsis, a description, some examples, and references to other pertinent material. You can see the first three segments shown in Figure 1.
- The name field lists the name of the command or function or file format and a precise, one-line description of what the software does.
- The synopsis provides a terse shorthand to describe how to use
the software. If the topic of the man page is a command, this field
shows the mandatory and optional switches, the format of the arguments,
and the argument order. If the topic at hand is a system call or a library
function, this field shows the formal arguments of the function and what,
if any, header files are required to use the function.
For example, here is the synopsis for the
ducommand on BSD UNIX.
du [-H | -L | -P] [-a | -s | -d depth] [-c] [-h | -k | -m | -g] [-x] [-I mask] [file ...]
The notation used in a command synopsis is one of the helpful conventions found in the man system (and extends to the usage hints provided by late
-model utilities). Here, the notation reads, "Type
du; optionally, follow with one of
-P; again, optionally, follow by one of
-d, but if you use the latter, specify a depth; provide
-cor not; optionally, follow with one of
-g; and specify
-xor not; specify
-Iand a mask or omit; and finally, provide the name of one or more files to operate on. The ellipsis (
...) indicates more than one.
Options grouped together, such as the first batch of
-P, work like radio buttons in a graphical user interface (GUI): You choose one of several formats mutually exclusively. The independent options, such as
-x, work like check boxes: on or off. Reading this notation and translating it into action becomes second nature very quickly.
And here is the synopsis for the
open()system call on BSD UNIX:
#include <fcntl.h> int open(const char *path, int oflag, ...);
This synopsis indicates that the
fcntl.hheader file is required,
open()returns an integer, and you must specify the path to the file to open and a batch of flags that determine the mode (read-only, read/write, open and truncate, and so on).
- The description segment is a protracted discussion about features,
usage, and all the options available on the command
-line. If you want to know what
du -Hdoes, you would read the text in the description.
- The examples section shows common uses of the utility and often special cases along with an explanation.
- The last section, titled See Also, points to further reading, such as other, related commands, important system files, industry-standard specifications, and more.
In addition to the aforementioned sections, you may find a host of other ad hoc sections
within a man page. One important variant is titled "Environment." It lists environment
variables you can set to affect the operation of the utility. For example, the man page
man names some 10 environment variables you can
alter to customize
man. One is MANPATH, which lists
directories to search for man pages.
Stupid man tricks
So, how do you use
man effectively? Here are some helpful tips:
- Customize with MANPATH. If you recall, the shell variable
PATH lists directories to search for executables. For example, if
you set PATH to /usr/bin:/bin:/usr/local/bin, the shell would search
those three directories in the order listed to find command-line programs.
Similarly, you can set MANPATH to a colon-separated list of directories
to find man pages. For instance, if you set MANPATH to
/usr/share/man:/usr/local/mysql/man (each is the root of a repository),
manwould search both directories for a matching man page.
- Search the man page repositories for content. The
manutility can search man pages for strings. To search, type
man -k patternto find all pages that contain pattern. One caveat: This operation can be very slow. One alternative is to use
apropos. It's an adjunct to
manbut searches only the one-line name fields of each page. It does not search as far and wide as
man -k, but it's very fast.
- Use your favorite pager. The
manutility recognizes a number of environment variables to customize output. Set the environment variable PAGER to use your favorite paging application, such as
less. Some systems provide Hypertext Markup Language (HTML) versions of man pages; on those systems, set your favorite browser with the BROWSER environment variable.
- Hunt for content. Use the search capabilities of your PAGER to quickly find
the content you want. For example, if you're browsing the man page for
man and your pager is
lessand you want to learn more about MANPATH, type
/MANPATH(the forward slash is the command to search), and then press Return. The
lesspager highlights all occurrences of the string; you can use
?to find the next occurrence and previous occurrence of the string, respectively.
- Tune out the noise. Use the MANSECT environment variable to list the sections you want to search for man pages (that is, 1, 2, 3, up to 8). Any section that does not appear in MANSECT is ignored. For example, if you want to ignore section 1 and concentrate on section 5, set MANSECT to 5.
- Read a man page file. If you're writing a new man page or have
downloaded some files from the Internet, you can read a single man page
man's Immediate mode. To read a specific file, run
man filename, where filename is a fully qualified path to the file. For example, if you are writing stocks.1—a new command in section 1 to show stock quotes—you can preview it with the command
man ./stocks.1. (If you omit the leading path,
manlooks for a man page called stocks.1 in your MANPATH.)
- Help your fellow with
man. If you install a batch of man pages on your system, you can change the global MANPATH to include the new directory and provide those man pages to every user who shares your system. The text file /etc/manpaths lists repositories one per line. You can also establish entire subsystems by creating new lists in the directory /etc/manpaths.d. Type
man man.conffor more information.
By the way, if you want to list the system-wide man page repositories defined for your
system, simply type
$ manpath /usr/local/man:/usr/local/share/man:/usr/share/man:/usr/man
However, some versions of
man go further and search directories
beyond those shown by
manpath. On BSD UNIX, for instance,
man also searches each directory listed in PATH as well as
the parent directory of each path listed in PATH. Thus, if you have /usr/mysql/bin in
man would search that specific path and
look for /usr/mysql/man.
Man, what a relief!
UNIX systems vary from vendor to vendor, so your man page system may differ (for better or worse) from the features described here. However, now that you know the ins and outs, you can tackle the variations on your own.
Just be sure to mind the mantra: Read the frickin' man page.
- History of man: Read the history of the UNIX man page system.
- FreeBSD man pages: Search for topics in this vast repository of man pages from many versions of UNIX and Linux.
- Speaking UNIX: Check out other parts in this series.
- Learn more about UNIX shells.
- The AIX and UNIX developerWorks zone provides a wealth of information relating to all aspects of AIX systems administration and expanding your UNIX skills.
- New to AIX and UNIX? Visit the New to AIX and UNIX page to learn more.
- Browse the technology bookstore for books on this and other technical topics.
- Check out developerWorks blogs and get involved in the developerWorks community.
- Participate in the AIX and UNIX forums:
Dig deeper into AIX and Unix on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.