Speaking UNIX: Man oh man

A guide to the UNIX man pages system

UNIX® has hundreds if not thousands of commands, and it's impossible to remember every option and nuance. But, happily, you don't have to: man, UNIX's built-in, online reference system, is man's best friend.

Martin Streicher, Web developer, 自由职业者

Photo of Martin StreicherMartin 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.


developerWorks Contributing author
        level

28 July 2009

Also available in Chinese

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

Figure 1. The man document reader running within a terminal window
The man document reader

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
SectionContent
man1General commands. Typically, the commands found in this section do not require superuser, or administrative, privileges. ls, cat, and passwd are found here, as are the shells. For instance, try man bash.
man2System calls, or functions that access services provided by the UNIX kernel. The fork system, which spawns a new process from an existing process, is one example. man fork reveals the page. Programmers working on system software refer to this section often.
man3C library functions. Many software packages provide extensive libraries of code so developers can create new software to augment existing features or invent entirely new ones. Each library is usually documented in a man page; some libraries, such as the system's libc, is so extensive that individual functions or a small subset of related functions are documented separately.
man4Special files, such as devices and drivers.
man5File 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).
man6Games and screensavers.
man7Miscellaneous files. This is a catch-all category. On a traditional system, you can learn about glob operators, regular expressions, and more.
man8System 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 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.


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.


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.


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

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into AIX and Unix on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX
ArticleID=416630
ArticleTitle=Speaking UNIX: Man oh man
publish-date=07282009