Man Pages (Part 2)
Contents
- The
man
Command - Basic
man
Command Usage - Section Selection
- Finding Manual Pages
- The
PAGER
- Configuring The
man
Command
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 themandoc
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.