Contents

The man Command

As mention in Part 1 of this post, the man command is the utility that locates, formats, and displays man-pages. This post highlights the operation of the man command and common options.

The number of options and system-specific implementation differences are large and can only be touched on. This is explicitly neither a survey of all man implementation, nor a tutorial, but more of a stroll through features with detours into their origins. Implementations of man outside the major Unix, BSD, or Linux lineage are not considered. Interoperability products like the MKS Toolkit or the z/OS UNIX System Services have their own variants of man that may be subtly different.

The versions of the man command that resulted in significant change and that will be appear repeatedly in describing the command are:

  • the Research Unix Shell script (1972)
  • the 3BSD C-version (1980)
  • the 4.3BSD-Tahoe version (1988)
  • the GNU implementation (1990)
  • the Shell re-implementation of the GNU version (2010)

Some proprietary versions of Unix, especially Sun (later Oracle) Solaris, improved upon the man command in an attempt to modernize it. This example in particular will be returned to in the final part of this series.

Introduced in Unix Second Edition (1972) man was a Shell script throughout its life in Research Unix as well as in commercial Unix up to and including System V (1983). Options to the early man command focused on different output devices and selecting formatting filters. The paper An Introduction to the UNIX Shell in Unix Seventh Edition (1979) that describes the Bourne Shell lists a simple Shell script that acts as the man command.

The man command was re-implemented in C in 3BSD (1980) and this alternate version shipped under the /usr/ucb path in System V Release 4 (1989). A free implementation of the man command by John Eaton in 1990 became a GNU project and was the default on Linux as well as FreeBSD. A move back to implementing man as a Shell script happened for licensing reasons in 2010 in some BSD-derived systems, which had been using the GNU implementation. Both FreeBSD and macOS use this Shell script.

In the POSIX standard, the man utility specification is extremely limited. It was initially included as part of the User Portability Extension (POSIX.2a) but not marked as optional until POSIX.1-2024 (Issue 8). That is when it was added to the User Portability Utilities option alongside other interactive utilities like vi or more.

POSIX man does not specify the use of manual sections or page formatting. It only requires support for (non-optional) standard utilities, but allows for other man-pages to be available on an implementation-specific basis. The only information expected to be provided is: “[…] the syntax used by the standard utility, its options, operands, environment variables affecting its execution, and its list of exit status codes.” The Rationale for the utility acknowledges that this is of limited usefulness, but also highlights that specifying at least some minimal documentation system aids portability.

Basic man Command Usage

The most common way to call the man command interactively is simply by listing the desired page or pages like so (e.g., for the ls utility):

man ls

If multiple names (or “titles” as they are sometimes referred to) are listed, each of the corresponding page is output:

man ls cp rm

Each manual page will then be shown one screenful at a time (see pagination.)

Section Selection

Already since the very earliest versions of the man command, the section for the man-page to be displayed could be optionally specified along with the title:

man 1 ls

Prior to 4th Edition (1973) that order was reversed. In the absence of a section number, prior to 7th Edition (1979) the man-page for the listed name in section 1 would be displayed if available. In 7th Edition and onward, all matching manual pages from any section would be displayed.

The 3BSD re-implementation of the man command changed that logic by looking through the sections in a defined search order and only displaying the first match. This was described as “an intelligent man command which obviates the need to know section numbers in the manual” (man.c source code, Bill Joy, 1977). This behavior continues to be the default for other man command implementation.

Some systems, most notably Solaris and OpenBSD, use the -s option to indicate which section or sections to search for a particular man-page.

A number of versions of the man command adopted a -a option to show all matching manual pages, similar to 7th Edition. 4.3BSD-Tahoe (1988) was likely the earliest and the GNU man (1990) supported it as well. BSD-derived systems like FreeBSD, NetBSD, OpenBSD, and macOS acquired or retained that option through different paths:

  • FreeBSD re-implemented the man command as a Shell script in FreeBSD 9.0 (2012) for licensing reasons and cloned the GNU functionality
  • OpenBSD uses a man from the mandoc project to which it switched in OpenBSD 4.8 (2010)
  • NetBSD retains a 4.4BSD man implementation based on 4.4BSD Lite Version 2.0 (1995)
  • macOS 13.0 Ventura (2022) switched to the FreeBSD man Shell script

Command options for many utilities tend to converge around a common set, although sometimes slowly. Solaris had the -a option since Solaris 2.1 (1992), but IBM AIX for example did not add it until 5L 5.3 (2004).

Interestingly, System V Release 4 (1989) incorporated the man command from 4.3BSD and did not have the changes from the later Tahoe release, which did affect other System V-based proprietary Unix distributions.

Section Search Order

The original man Shell script in Research Unix simply used Shell filename pattern completion for the directories under /usr/man to determine section search order.

The 3BSD version of man implemented a hard-coded search order of:

l u n 1 6 8 2 3 4 5 7 p s j

Interestingly, it also mapped a section selection of 1 to lun16pj, which would result in finding commands across all sections in that list where they could appear. Manual pages for sub-sections, for example 3m for math library routines, were not in separate directories and could be found by specifying just the section number.

The default section search order can be overridden by changing the man command’s configuration (see below) and in some implementations by a command option or environment variable. The GNU man command and its Shell re-implementation as widely used on Linux, macOS, and FreeBSD support this feature: a -S option or the MANSECT environment variable (in this order of precedence) can be set to a colon-separated list of sections to search.

The default search order for each man command is often outlined in its own manual page. In some implementations, it is hard-coded in the utility. If the version of man supports configuration, the config file usually can define it.

As an example, the default setting for an Ubuntu 24.04 (2024) Linux system is:

1 n l 8 3 0 2 3type 3posix 3pm 3perl 3am 5 4 9 6 7

And on an example macOS Sequoia 15.3 (2025) system it is:

1 1p 8 2 3 3p 4 5 6 7 9 0p tcl n l p o

These section search orders are almost certainly going to be different on other systems, even with a similar operating system version, depending on what packages or languages are installed.

Finding Manual Pages

Manual pages were originally stored in /usr/man. When the comprehensive file system reorganization happened for System V Release 4, the manual pages went to /usr/share/man. By the late 1980s networked Unix workstation had become common and network mounting a /usr file systems read-only was frequently used to work around small and expensive hard disk drives. The share part of the path suggested platform-independent files, like the manual pages. Both BSD with 4.3BSD-Reno (1990) and Linux use /usr/share as the default manual page location. POSIX does not standardize this.

The original Linux Filesystem Structure standards (v1.0, 1994 until Release 1.2, 1995) still used /usr/man. By the next major revision, the Filesystem Hierarchy Standard (FHS) (Version 2.0, 1997) /usr/share/man was specified. The most recent version of the FHS (Version 3.0, 2015) continues to use that.

Starting in 4.3BSD (1986) a MANPATH environment variable or the -M option could be used to change the hard-coded search path for manual pages. The format is identical to the PATH variable, a colon-separated list of directories. The -M option overrides MANPATH.

Assuming a hypothetical vendor-provided ls command is installed in /opt/vendor, then its accompanying manual pages could be accessed with:

man -M /opt/vendor/man ls

If this is needed regularly, setting MANPATH in the Shell start-up files for a user is more convenient. Modern man command implementations like the GNU man or its Shell re-implementation will additionally construct a MANPATH from the PATH environment variable if not explicitly specified. The manpath utility that is part of these implementations shows the path man will search and it itself was used by the man command as a helper tool in the GNU version.

A -w option that lists which manual page(s) would be shown was part of Unix 7th Edition, then 4.3BSD-Tahoe, and finally in the GNU implementation of man and its Shell re-implementation. It is functionally related to the BSD whereis utility, which lists a program’s executable and manual page locations in the file system.

A slightly less common option to set the MANPATH is -m (introduced in 4.3BSD-Reno and still extant in NetBSD and OpenBSD) that adds to the MANPATH instead of replacing it. The directories specified with -m will be searched before others.

The -m option conflicts with an architecture (“machine”) flag that is used in the GNU man and the Shell versions of it. OpenBSD uses the -S flag for this purpose.

The PAGER

The operation expected by a user on a non-printing terminal is that the man command shows one screenful of text at a time and then waits for the user to confirm the display of the next page. This was not the case for the early Shell script versions of man, which simply would output the whole formatted page. The 3BSD re-implementation of man then prepared the output for terminal display and piped it to more as the standard paginator.

In 4.3BSD (1986) an environment variable called PAGER was introduced in the Berkeley Mail program to let users select a different paginator than the BSD default more when displaying email messages. When System V Release 3 (1987) included Berkeley Mail as mailx, it checked the environment variable PAGER, but would default to the System V-specific pg paginator instead of more. By 4.3BSD-Tahoe (1988), the man command used PAGER and with the merging of BSD features into System V Release 4, this version of man became standard in System V.

The POSIX-standardized man (and mailx) use PAGER, but if that variable is unset, it may default to more or a system-specific paginator. At the time of this standardization, which began in 1989, more was the most commonly used paginator and this approach was chosen to support the System V convention of defaulting to pg. The POSIX standard version of more is most closely modeled after the contemporaneous 4.4BSD version.

The widely available and more capable less utility is the default on numerous systems, most notably Linux distributions (less predates the Linux project.) Some distributions may use the Debian Alternatives system (introduced in Debian 2.0 (hamm), 1995) which uses a command name of pager and a symbolic link from that name to the preferred utility.

Other operating systems have switched to less like FreeBSD 9.0 (2012), Solaris 11.3 (2015), and macOS since at least Mac OS X 10.4 Tiger (2005).

Because the PAGER environment variable is used by at least the command line mail program, several man implementations allow to override that setting with the environment variable MANPAGER. Alternatively, each invocation of the command can take a -P option (or --pager in GNU utilities.) These options are not POSIX-compliant and for example neither Solaris 11.4 nor AIX 7.3 support them.

The -P option originated in GNU man, which is why it has been available in FreeBSD and Linux since the earliest releases. The origin of the MANPAGER variable, which didn’t appear in GNU man until 2007, appears to have been in NexTSTEP (pre-release sources, 1988.) NeXTSTEP’s commands came from 4.3BSD and the man command was modified to support MANPAGER. 4.3BSD-Tahoe sources that supported the PAGER option weren’t imported into NeXTSTEP until 1989. It is unclear if there is a different, earlier source for MANPAGER though or if this is original to NeXTSTEP.

Need For Pagination

For almost a decade, the man command did not use pagination. This may seem odd from a modern perspective, but needs to be understood in the context of the hardware used by Unix users. Pagination on a printing terminal is unnecessary, output can easily be interrupted. The user is less likely to casually peruse man-pages, but rather would wait for the whole page to be printed out and then save the paper copy.

When CRT-terminals replaced printing terminals, their speed of up to 9600 to 19200 bps was much faster compared to the previous 110 to 300 bps. In theory, at 19200 bps a full 80 column by 24 line terminal screen could be filled in one second; in practice these speeds were rarely achieved in the 1970s. Even for a man-page, which isn’t using all character positions, that still gave the user time to manually pause output using software flow control.

Configuring The man Command

The ability to change the man command’s system-wide defaults has become more useful as the command has gained new features. That’s why some implementation use a central configuration file that, e.g., set default section search order.

An early example of this is SCO XENIX System V 2.3 (1988), which used /etc/default/man, a typical location for a file like this since at least XENIX 3.0 (1983). MANPATH could be set there, as well as the section search path called ORDER. As Unix by System V Release 4 had merged in XENIX features, the /etc/default convention was used by some utilities, but not for the man command, which came in via 4.3BSD.

Of the major System V-based proprietary Unix distributions, Solaris (1992) used a config file approach for man with the man.cf file, usually located in /usr/share/man. In that file MANPATH lists a colon-separated search path and MANSECTS a comma-separated section list.

Neither IBM’s AIX nor HP’s HP-UX used a config file for the man command.

Both 4.3BSD-Reno and the GNU man command introduced config files. The format of the BSD /etc/man.conf is somewhat unusual. Each line is either a mapping of section name to directory list or a keyword like _default for the MANPATH or _subdir to list the section directories in search order. While NetBSD continues to use this format, OpenBSD abandoned it for a simpler one with OpenBSD 5.8 (2015).

The GNU man command initially used a different approach to configuration. It used the manpath utility as a helper and the associated manpath.config to build a MANPATH; the section search order was hard-coded however. In a later version of the tool (2001), a SECTION directive could be used the specify section search order.

The format of the GNU man command’s config file (usually under /etc/manpath.config) and the Shell re-implementation’s /etc/man.conf are simple lists of all-caps variable names that mirror the environment variables used and the value associated with those variables. In the GNU version multiple values are space-separated, in the Shell version colon-separated. The two examples from Section Search Order are configured like so:

  • GNU man
SECTION		1 n l 8 3 0 2 3posix 3pm 3perl 3am 5 4 9 6 7
  • Shell man (macOS)
MANSECT         1:1p:8:2:3:3p:4:5:6:7:9:0p:tcl:n:l:p:o

The GNU man command will also read a ~/.manpath configuration file or accept a -C option with a config file name. The Shell version will look for additional configuration files under /usr/local/etc/man.d and supports a MANCONFIG directive in its main configuration file.

A further peculiarity exists under macOS due to the way Shell sessions interact with the GUI. The special utility path_helper was introduced in Mac OS X 10.5 Leopard (2007) to simplify setting PATH and MANPATH variables by reading a set of files in /etc. The system default paths can be changed in the /etc/paths and /etc/manpaths files. Installed packages can add their specific, e.g., MANPATH setting under /etc/manpaths.d.

Coming Up…

After this excursion into the man command’s features and capabilities, the final post in this series will look at two related utilities, apropos and whatis, and then explain the purpose of catman. It will then conclude by discussing alternative documentation formats and sources in Unix, Linux, and related systems.