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 man.

To read the documentation for a piece of software installed on your system, simply type man component, where component is the name of the software. For example, to read about the ls utility, type:

$ man ls

You can even read about man itself:

$ man man

Assuming that 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 doesn't exist, man reports No manual entry for component. (There are other techniques to find a suitable man page besides naming it. More on that in a moment.)

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.

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 crontab command, 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 numbered section.

Back to top

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 du command 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 -H, -L, or -P; again, optionally, follow by one of -a, -s, or -d, but if you use the latter, specify a depth; provide -c or not; optionally, follow with one of -h, -k, -m, or -g; and specify -x or not; specify -I and 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 -H, -L, and -P, work like radio buttons in a graphical user interface (GUI): You choose one of several formats mutually exclusively. The independent options, such as -c and -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.h header 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 -H does, 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 for man names some 10 environment variables you can alter to customize man. One is MANPATH, which lists directories to search for man pages.

Back to top

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), man would search both directories for a matching man page.
• Search the man page repositories for content. The man utility can search man pages for strings. To search, type man -k pattern to 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 man but 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 man utility 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 less and you want to learn more about MANPATH, type /MANPATH (the forward slash is the command to search), and then press Return. The less pager highlights all occurrences of the string; you can use n and ? 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 using 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, man looks 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.conf for more information.

By the way, if you want to list the system-wide man page repositories defined for your system, simply type manpath:

$ 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 your PATH, man would search that specific path and look for /usr/mysql/man.

Back to top

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.

Resources

Learn

• 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.
  
  

Discuss

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  
• Participate in the AIX and UNIX forums:
  • AIX Forum
  • AIX Forum for developers
  • Cluster Systems Management
  • IBM Support Assistant Forum
  • Performance Tools Forum
  • Virtualization Forum
  • More AIX and UNIX Forums
  
  

About the author

Martin Streicher is a freelance Ruby on Rails developer and the former Editor-in-Chief of Linux Magazine. Martin holds a Masters of Science degree in computer science from Purdue University and has programmed UNIX-like systems since 1986. He collects art and toys.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The man system
• The contents of a man page
• Stupid man tricks
• Man, what a relief!
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into AIX and UNIX on developerWorks

Try IBM Cognos 8 Business Intelligence

Use reports, analysis, dashboards and scorecards to monitor business performance, analyze trends and measure results.

Special offers