Man Page Facts

Why man?

man pages are the traditional command line tool for finding information about implementing programs, system calls, functions and other system usage and maintenance tools. Darwin, and by extension Mac OS X, do provide other documentation as well. Tools like HeaderDoc, HOWTO documents, the Developer Help Center within Project Builder, and the Apple Developer Connection documentation site all provide additional sources of reference. Often though these references are more in depth, or detailed than is needed for a quick reference. In the case of web sites, the information may not be available due to a lack of network access.

man pages are designed to be accessed quickly from the shell. They provide the basic tools that a user needs to accomplish the task at hand, without requiring them to invoke anything more complicated than the simple man program. Should a user want to view the man pages within a web browser or another tool, there are translators for man pages that allow this.

man pages are included in Darwin and Mac OS X because they are the de facto standard of documentation in the UNIX community. This is important not only for maintaining users' familiarity with the tools available in Darwin, but it also allows for compatibility between Darwin and other UNIX-like operating systems. For tools that are ported to Darwin, there is no need for a proprietary documentation system.

Any utility accessed from the command line should have a man page.

Where are they?

In Darwin, the man pages are stored in /usr/share/man. There, they are stored within subdirectories according to their purpose as follows:

  • /man1 - general commands (tools and utilities)

  • /man2 - system calls and error numbers

  • /man3 - libraries

  • /man4 - devices and device drivers

  • /man5 - file formats

  • /man6 - games

  • /man7 - miscellaneous information pages

  • /man8 - system maintenance and operation commends

  • /man9 - system kernel interfaces

Naming conventions

man pages are usually named with the name of the program or function followed by a suffix that designates the page's category. This is of the form, man_page.1, where the suffix is the name of the subdirectory in which the page is stored. Multiple man pages may exist with the same base name. For example, a library and a user command may share the same name. In this case the suffix and the location of the man page are used to determine which page to display when man is invoked. This is important to keep in mind when documenting a project. Unless properly named, the man page will not display as expected.

For example:

A man page for the library would be named man_page.3 and stored in /usr/share/man/man3.

A man page for the user command would be named man_page.1 and stored in /usr/share/man/man1.

% man 3 man_page displays the library's manual page.

% man 1 man_page displays the user command's documentation.

% man man_page may return either page.

When referring to man pages in text, the form man_page(1) is generally used to designate that a man page is being referred to as well as what category it belongs to.