Man Pages — The Complete Guide (2024)

Introduction

If you use the command line in UNIX-like systems, you probably know the man command. It’s a powerful tool for finding documentation for any program or library.

But do you know where “man pages” come from, how they are structured, tips and tricks to read them better, and what other tools are available to help you?

This guide will take you on a journey through the fascinating world of man pages.

You can even read this guide as a man page on your own system by running this command:

curl -o- https://gist.githubusercontent.com/sebastiancarlos/a7fb89f73b4617ccc2ea9445abf62f90/raw/8edec5fbd1019c4df0c13fc79d2cc514d7f60735/man-guide.1 | man -l -

If you already know the basics, you can scan the headlines and see if anything catches your eye. If something piques your interest, feel free to deep dive.

1. What is a “man page”?

“Man page” is short for “manual page.” Man pages are a well-known form of software documentation usually found on UNIX-like operating systems.

Like any tool, your operating system comes with a manual — In this case, it’s a virtual manual that you can read from within the operating system itself.

2. How to read man pages?

You can read man pages by typing the man command on your terminal, followed by the name of the “man page” you want.

For example, type man ls to read the man page for the ls command.

Note: There are several implementations of the man command. The most popular ones are “man-db” and “mandoc.” They both follow the POSIX specification. We’ll take a closer look at all of this later.

3. How are man pages organized?

The virtual manual is usually split into sections. Each section contains entries describing a specific topic. A single entry is called a “man page.”

There are some conventions:

• The section names are usually numbers (1, 2, 3, etc.). Each number has a specific meaning (“1” is for executable programs, “2” is for system calls, etc.)
• Every “man page” usually follows a known structure (“Name”, “Synopsis”, “Description”, etc.).
• Man pages are usually designated by its name followed by its section within parentheses (For example ls(1) and null(4))

4. Are there man pages for every program?

Man pages aim to document the operating system and every software in it. Thereby, the software you install is expected to add its own man pages.

But, with the rise of the internet and competing forms of documentation, some programs (and even some operating systems) have their main documentation elsewhere. Some don’t provide “man pages” at all!

Still, man pages continue to be the canonical way to document software in UNIX, particularly when it’s “close to the metal” or accessible through the command line.

5. What are man pages actually made of?

Man pages are usually written in the “roff” markup language — A tradition that started with the first edition of the UNIX manual.

This markup language is versatile: We can use the source files to create man pages in different formats — Not only text for the terminal, but also PDFs or web pages. We’ll explain how later.

Some man page authors use other markup languages such as Markdown or reStructuredText to write their documentation. They are usually converted to roff before being included in the final man page file.

6. What are the sections of the manual pages?

The common sections are:

• 1 — Executable programs or shell commands (ls, grep, vim, etc.)
• 2 — System calls (Functions which wrap operations performed by the OS kernel.)
• 3 — Library calls (Functions within libraries. That is, functions meant to be called by other programs, not by the end user. They are usually defined in terms of a particular programming language, like C.
• 4 — Special files (Aka “devices.” Usually files found in /dev, which allow access to devices through the kernel. “Device” is a term used mostly for hardware-related stuff that belongs to the system, like disks or printers. There are also “pseudo-devices” which emulate the behaviour of a device in software, like /dev/null and /dev/random)
• 5 — File formats and configuration files (Describes various human-readable file formats and configuration files, e.g. /etc/passwd)
• 6 — Games
• 7 — Miscellaneous (Overviews or descriptions of various topics, conventions, and protocols, character set standards, the standard filesystem layout, and miscellaneous other things.)
• 8 — System administration commands (Commands which either can be or are normally used only by the superuser, like system-administration commands, daemons, and hardware-related commands.)

You might find some deprecated sections in the wild (9, o, n, l), but they shouldn’t be used.

Sometimes additional characters are appended to the section number. For example, Debian uses “1posix” to store the “POSIX documentation” for some commands. The intent is to “namespace” or to indicate that some man pages belongs to a specific project.

7. What’s the difference between System calls (2) and Library calls (3)?

In a sense, “system calls” are also “library calls:” They are functions, written in C, meant to be used by other programs.

But they are special enough to deserve their own section: They are very thin wrappers around kernel operations.

Many library calls also wrap around system calls to make them easier or more convenient to use. They are higher-level than their section two counterparts. For example, the fopen() library call (3) wraps around the open() system call (2).

8. What are the sections within a manual page?

The conventional sections are:

NAME

This section has a standardized format consisting of the program or function name, followed by a dash, followed by a short one-line description. For example:

ls - list directory contents

SYNOPSIS

A brief summary of the command or function’s interface.

The SYNOPSIS usually contains no prose. It just illustrates the command or function in a way that matches all possible invocations.

In some cases, it’s recommended to illustrate several exclusive invocations instead of clamping all the possibilities into one, as shown in the SYNOPSIS section of man-db’s man(1).

The following conventions apply to this section:

• bold text — Type exactly as shown.
• italic text — Replace with appropriate argument.
• [optional] — Any or all arguments within [] are optional.
• this | that — The vertical bars (|) separate choices
• argument… — Argument is repeatable

Exact rendering may vary depending on the output device. For instance, man will usually not be able to render italics when running in a terminal, and will typically use underlined or coloured text instead.

DESCRIPTION

An explanation of what the program, function, or format does. It shows how it interacts with files and standard input, and what it produces on standard output or standard error.

It should omit internals and implementation details unless they’re critical for understanding the interface.

It should only describe the usual case — information about command-line options should go in the OPTIONS section.

ENVIRONMENT

A list of all environment variables that affect the program or function and how they affect it.

FILES

A list of the files the program or function uses, such as configuration files, startup files, and files the program directly operates on.

These are meant to be full pathnames of these files. In fact, it is expected that these paths on the man page were dynamically generated during the program’s installation to match the user preferences.

In short, you can expect the file paths in this section to be both factual and actual.

STANDARDS

A description of any standards or conventions that relate to the function or command. Commonly just a list of standards.

If the API is not governed by any standards but commonly exists on other systems, it should be noted. This is also the place to note if the function or command is Linux-specific or GNU-specific. If it’s available in the BSDs, it should be noted here too.

HISTORY

A brief summary of the versions where a system command or function appeared, or changed significantly in its operation.

NOTES

Miscellaneous notes.

CAVEATS

Warnings about typical user misuse that doesn’t constitute a bug or design defect.

BUGS

A list of limitations or known defects.

EXAMPLES

One or more examples demonstrating how this function, file, or command is used.

Note: An innovative project in the man pages space, mankier.com, shows an EXAMPLES section right after the NAME section. This author encourages this non-standard practice, particularly in view of the success of example-first documentation projects such as “tldr pages.”

AUTHORS

A list of authors of the documentation or program.

Some people discourage this section as it tends towards clutter.

SEE ALSO

A comma-separated list of related man pages, possibly followed by other related documents.

The list should be ordered by section number and then alphabetically by name.

Given the distributed, autonomous nature of FOSS projects and their documentation, it is sometimes desirable that the SEE ALSO section includes references to manual pages provided by other projects.

9. Extra sections for commands (Only in sections 1 and 8)

Besides the generic sections mentioned so far, some sections are exclusive to commands:

OPTIONS

A description of the command-line options accepted by a program and how they change its behavior.

EXIT STATUS

A list of the possible exit status values of a program and the conditions that cause these values to be returned.

10. Extra sections for functions (Only in sections 2 and 3)

The following sections are exclusive to functions:

LIBRARY

The library providing a symbol. It shows the common name of the library, and in parentheses, the name of the library file.

RETURN VALUE

A list of the values the library function will return to the caller and the conditions that cause these values to be returned.

ERRORS

A list of the values that may be placed in errno in the event of an error, along with information about the cause of the errors. (errno is a variable that holds the number of the last error that occurred in a system call or a library function. You can use the errno command to look up the meaning of an error number or an error name.)

ATTRIBUTES

A summary of various attributes of the function. Mostly related to memory and thread safety.

VERSIONS

A summary of systems where the API performs differently, or where there’s a similar API.

11. RUNOFF

While it’s usual to think of man pages as something you read on a screen, its origins lay in the physical world of printing.

The oldest ancestor of man pages is a program called RUNOFF from the legendary CTSS operating system. The name RUNOFF comes from the idiomatic expression “run off,” meaning “to print or make a photocopy.” It’s one of the earliest text formatting (or “typesetting”) programs.

RUNOFF was one of a pair of programs, TYPSET and RUNOFF, designed by Jerome Saltzer in 1964 to format his doctoral thesis. TYPSET was used to create and edit the source text files, which contain English text and some control words to describe formatting instructions (justification, alignment, and so on). RUNOFF would print out the formatted text, excluding the control words.

12. RUNOFF as a markup language

If the idea of a file containing both natural-language and specific formatting commands sounds a lot like a “markup language” like HTML, LaTeX, or Markdown, that’s because it is. In fact, RUNOFF and other early text formatting programs are the origins of markup languages.

The word “markup” comes from the millennial art of “marking up” a manuscript, which involves adding handwritten printing instructions in the margins. These instructions are then read by the person or system tasked with creating the final version of the document.

13. From RUNOFF to troff/groff

RUNOFF was eventually rewritten as roff (1971) for UNIX. Notably, “roff” was used to format the first edition of the UNIX Manual, which had a similar structure to the man page layout used today.

See Also

man Command in Linux {With Examples} | phoenixNAP KB

Next came nroff (new roff), which supported both monospace printing and displaying on terminals. Then troff (typesetter roff), featuring proportional fonts and other advanced features used in state-of-the-art photographic typesetters.

Although troff was eventually replaced by other programs and markup languages, it is still used to format UNIX documentation, and some people continue to use it for other tasks due to its reliability and wide availability.

The GNU troff (groff) is considered the most popular troff variation in modern UNIX installations.

14. The first “man” command

While the first edition of UNIX didn’t have a dedicated “man” command. The second edition, a few months later, introduced it:

That “man” command was a shell script that expected the title of the required manual page and, optionally, a section number.

Its job was to find the source file for the manual page, and pass it to roff, which does the heavy lifting of processing it for displaying to the user. (In those days, displaying involved printing on paper.)

Not much has changed. These days, the implementations of the “man” command work in a similar way.

15. The “man” specification

“man” is one of the utilities defined by POSIX, a family of standards designed to maintain compatibility between UNIX-like operating systems.

Both “man-db” and “mandoc” conform to the “man” POSIX specification.

The POSIX people discussed at length how much or how little should be required of “man” implementations to be conformant. Eventually they settled on minimalism: POSIX specifies a simple usage without options and with the option -k, plus a few environmental variables.

16. The “man” command without options

When calling man without options (for example, man name), POSIX says the following:

“If name is the name of a standard utility, man at a minimum shall write a message describing the syntax used by the standard utility, its options, and operands (arguments).”

Note that POSIX doesn’t say anything about the format of the final message, or about the markup of the source files, or about roff/groff — That’s considered an implementation detail. You can go ahead and write your own POSIX-conformant “man” command in Markdown and COBOL and no one can stop you!

Indeed, “mandoc” is an implementation that doesn’t call groff at all, although it does expect the source files to be in either the “man” or “mdoc” macros, which are built on top of the roff language.

17. The “man” command with the “-k” option, or “apropos”

When calling man with the -k option (man -k name), POSIX says that man should search for “name” in a “utilities summary database” that contains a “brief description of the purpose of each utility”, and it should write all the matching results.

In other words, man -k name should be equivalent to grep -Ei ‘name’ summary-database (the -i flag means case-insensitive and the -E flag means that ‘name’ can be a regular expression.)

This assumes that the “summary-database” is a text file with a single entry per line — POSIX says that this organization is not required, it’s just an illustrative example of the type of search intended. Indeed, older man implementations used to have a text file just like this, but “man-db” uses an actual database.

There are two important details about man -k not mentioned by POSIX:

• Man implementations generally use the text from the “Name” section of a man page as its entry in the summary database.
• man -k is equivalent to the command apropos, which is provided by both “man-db” and “mandoc.”

18. The “man” command with the “-f” option, or “whatis”

While POSIX doesn’t define the -f option (or the equivalent whatis command), it says that “the -f option was considered, but due to implementation differences, it was not included in this volume of POSIX.1–2017”, so it’s likely to be included eventually.

The actual implementation differences between “man-db” and “mandoc” are trivial.

whatis name is just like apropos name, except that man searches for “name” only in the manual page names, not in the full description. If a match is found, the returned value is the same as in apropos.

In other words, man -f name should be equivalent to grep -Ei ‘^name ’ summary-database (same as before, but it looks for lines beginning with “name” followed by a space.)

19. The “man” environmental variables

POSIX also defines the following environmental variables:

• LANG, LC_ALL, LC_CTYPE, LC_MESSAGES and NLSPATH: The usual UNIX variables for internationalization.
• PAGER: An output filtering command to write the output to a terminal. The page output is to be piped through this command. This defaults to the “more” pager (the POSIX pager), although these days the “less” pager is almost universally preferred.

There’s one more environmental variable mentioned but not defined by POSIX: MANPATH. Both “man-db” and “mandoc” define it as a sequence of directory names separated by colons (just like PATH). It’s one of the ways to override the default root where the man page source files are located on the system. But most users should not need to set it.

With this, we cover everything that POSIX has to say about the man command. Now let’s move into the most popular man implementation: man-db.

20. Regular use of the “man” command.

In regular use, the manual page associated with each of the page arguments is found and displayed.

A section, if provided, directs man to look only in that section. The default action is to search in all of the available sections following an order defined during man-db’s installation, and to show only the first page found.

Some valid alternative spellings of man 7 man are:

• man man.7
• man 'man(7)'

21. The “-K” option, or “ — global-apropos”

global-apropos searches not just the short description (like apropos), but the full text in all manual pages.

This is a brute-force search, and is likely to take some time — if you can, you should specify a section. Search terms may be simple strings (the default), or regular expressions if the --regex option is used.

Note that this searches the “roff” sources of the manual pages, not the rendered text, and so may include false positives due to things like comments in source files.

Note also that “global apropos” will actually try to render every found match, so if you expect many results you might want to also add the -w flag (which we’ll see later) to make it manageable.

22. The ‘-l” option, or “local file mode”

In local mode, -l or --local-file , man formats and displays local manual files instead of searching through the system’s manual page collection.

Each manual page argument will be interpreted as a “roff” source file.

If - is passed as the argument, input will be taken from stdin.

When this option is not used, and man fails to find the page required, before displaying the error message, it attempts to act as if this option was supplied, using the name as a file-name and looking for an exact match.

23. The “-w” option, or “ — where”

The -w option (also--where,--path, and--location) prints the location of the source roff file instead of displaying it.

24. Cat pages, and the “-W” or “ — where-cat” option.

When using modern man-db, it’s possible to store the formatted manual pages on disk so that future requests do not have to be formatted again.

These pre-formatted man pages are known as “cat pages.”

Although cat pages require some megabytes of disk space, they substantially increase speed. Indeed, cat pages might load two or three times faster!

The increase in computer performance since the 90s has considerably reduced the need for cat pages, so you probably won’t even notice the milliseconds of speed improvement. But it’s worthwhile if you want to squeeze every bit of performance out of your system.

The hierarchy of cat pages is created in a separate folder from the hierarchy of man pages — It mirrors the folders and file names of the man hierarchy. In short, it’s a cache.

Whether or not cat pages are created on your system depends on several factors, not least how man-db was installed. So make sure to read its manual (man-db-manual.{ps/txt}), its configuration file (/etc/man_db.conf), and — naturally — the man page for man.

You will find that in most systems, by default, cat pages are created only if you try to run man with a column width set to 80 (easily done with the env variable MANWIDTH=80), which after all is a beautiful looking default for any screen size!

You might also need to manually run the commands mandb and catman, usually as root, to create the cat pages hierarchy for all your man pages.

You can verify if there is a cat page for a given man page by running man -W ls. That is, with the flag -W (also --where-cat or --location-cat). It should print the location of the cat page for the ls command. It’s purrtastic!

25. The “-L” option, or “ — locale”

The -L or --locale option allows you to specify the locale used. This overrides env variables that we’ve seen before such as LC_MESSAGES and LANG.

It looks for a page in the provided language, and falls back to English.

26. The “-M” option, or “ — manpath”

The -M or --manpath=path option allows you to specify an alternate man path to use. It overrides the MANPATH env variable that we’ve seen before, or the settings on your configuration file (/etc/man_db.conf). The value should be a colon-delimited list of directories, just like PATH.

A directory within MANPATH must be the root of a manual page hierarchy structured into sections as the ones used by man-db.

Your system can have multiple man page hierarchies at the same time, and when you run man you are searching in all of them. Most likely, your system has man pages on several hierarchies. To verify that, you can run the manpath command which prints the current manpath value.

The -M option could be useful if you want to roll up your own documentation system on top of the man command. If you just want to view man pages from a different location, you can use the -l option.

27. The “ — regex,” “ — wildcard,” and “ — names-only” options

The --regex option allows you to see all pages with any part of either their names or their descriptions matching the argument as a regular expression (same as the apropos command). Since it’s not possible to choose a “best” page when searching for a regular expression, this option implies -a (--all).

The --wildcard option shows all pages with any part of either their names or their descriptions matching the page argument using shell-style wildcards (same as --apropos -wildcard). Like --regex, it also implies -a (--all).

The --names-only option, when used with the --regex or --wildcard option, matches only the page names and not the page descriptions (same as whatis). If neither the --regex nor the --wildcard option is used, this option has no effect because man does “names-only” search by default.

28. The “all” option, or “ — all”

By default, man exits after displaying the most suitable manual page it finds. To force man to display all matching manual pages, use the -a or --all option.

Now, this option is a bit inconvenient because it works by showing you the first match, and, when you close it, it asks if you want to see the next one. A better option might be to run man -a -w to show all the matching files at the same time.

29. The “ — no-subpages” option

By default, man tries to interpret pairs of manual page names given on the command line as equivalent to a single manual page name containing a hyphen or an underscore.

In short, if a command has a subcommand (like git diff), then, by convention, it’s manual page will have the name git-diff, but you can still access it by typing man git diff. The no-subpages option disables this behavior.

30. The “ — pager” and “ — prompt” options

Using the -P or --pager option, you can specify the output pager to use. By default, man uses less. This option overrides the MANPAGER and PAGER env variables.

The -r or --prompt option is useful when a recent version of less is used as the pager. The default prompt used by man shows this on the bottom of the less screen: Manual page name(section) line x.

I really like this less feature, it allows anyone to set a custom prompt. man makes good use of it.

31. The “ — no-hyphenation” and “ — no-justification” options

The --no-hyphenation or --nh option disables automatic hyphenation at line breaks. This is useful for searching text in the less pager without worrying about possible hyphenation of the search term.

Have you noticed that man pages have fully-justified text? That’s the secret to its smoothness! The --no-justification or --nj option disables full justification, leaving the text justified only to the left margin. This can be useful when you want to copy-paste directly from less.

32. The “-t” option — Output to PostScript and PDF

Using the -t or --troff option puts you in the “troff mode” of groff, which means that the output is no longer targeted at a terminal (“nroff mode”). By default, it generates PostScript, which is the language that PDF files are built on.

To convert a manual page to PostScript, run man -t ls > ls.ps and to convert it to a PDF, you can use man -T pdf ls > ls.pdf. Keep in mind that the formatted pdf is directed to the standard output, so you can use the (>) operator to create a file.

The PDF output usually looks quite good, but it’s limited to the Times New Roman font with some hard-coded things. And some manual pages in the wild might not render correctly, especially if there are long tables or unconventional formatting.

33. Output to HTML — Here be dragons

Converting manual pages to HTML using man -H is generally not recommended with man-db because the resulting output can be of poor quality. Complex formatting is often converted into low-resolution images, which doesn’t look appealing or accessible.

Some developers who build online manual pages have resorted to creating their own roff-to-HTML converters to generate cleaner and better-looking HTML outputs.

Some people use mandoc for HTML conversion, which in my opinion generates a better layout and, more importantly, doesn’t generate those weird low-resolution images.

34. Apropos database and init script

Man-db is actually called like that because it uses an actual database, usually Berkeley DB, to store and maintain the manual pages. To keep this database up to date, man-db has an init script that runs the mandb command. Depending on your system and installation, it might be set to run periodically in systemd.

Running this script creates and updates the indices for the database, which allows to use the apropos and whatis commands. In different modes of operations, the database updates can be automatic or done manually using mandb. You can consult the man-db manual (man-db-manual.{ps/txt}) for more information.

35. Man page alternatives — tldr, cheat.sh, GNU Info

In addition to man pages, there are some alternatives.

Tldr

The tldr project provides concise and practical examples for command-line tools. Tldr pages are community-driven and can be a great companion to the more comprehensive man pages.

You can invoke them using the tldr command. For example, tldr ls.

There are several implementations of the tldr command. The classic one is good, but I personally recommend the Rust version, tealdeer, because it’s actually really fast.

Cheat.sh

There is also “cheat.sh”, which integrates several cheatsheet providers, including “tldr,” plus other services like StackOverflow. While it’s an admirable project, this author prefers to use tldr directly, which is faster and is the largest project of its kind anyway.

Texinfo (GNU Info)

The GNU Project provides an alternative to man pages for their software, called “Texinfo.” While most GNU software also provides man pages, the Texinfo documents tend to be more comprehensive.

The files use the “Texinfo” typesetting syntax. They have a tree-like structure with nodes that can link to each other. Unlike man pages, they do not have all the information on one page, but spread across different nodes. You can read read it through Emacs or using the stand-alone info command.

GNU info is a bit quirky. If you need to read the documentation for GNU software, there are two alternatives:

• Read the HTML version instead, hosted at the GNU website.
• Pipe it to less (for example info groff | less). That way you get to read the entire manual in one go, without having to deal with info’s tree node navigation.

If you want to use plain GNU Info, check this guide.

Other

Another source of documentation on your system is the /usr/share/doc directory. It contains files from many installed software packages. These files are usually in plain text, PDF, or HTML.

These days you might as well ask an AI how to do something on the terminal. This is available, for example, with Copilot for CLI.

36. Online man pages

There are several nice online man pages. Some are associated with OSs and distros, like Arch Man Pages.

Others, like manned.org, contain man pages for different versions of OSs and host the source “roff” files too.

Innovative resources like ManKier include the “tldr” information as the first section of the man page, table of contents on the side, and internal hyperlinks.

I would also like to point out that some of the old-school online man pages, like OpenBSD’s and Void Linux, actually show you the native “roff” tags as you hover around!

37. Creating man pages

There are various ways to create man pages, the old-school way being to write them in “roff” format. There are several resources available, such as “Practical Unix Manuals: mdoc” and the Groff manual.

Man pages can also be generated from other sources, such as Markdown, with tools like pandoc, and ronn from the Ruby world.

38. The “man-pages” project

Despite its generic name, the man-pages project actually provides a wealth of information in the form of man pages about the Linux kernel. It also includes “intro” pages for every section of the manual, reinforcing the concept of sections being part of one single manual.

Recently, it has expanded to include man pages for other generic Linux tools, not only for the kernel.

This project also contains a nice guideline for the generic sections within man pages on its man-pages(7).

39. The international man-pages project

Man pages are also available in different languages, thanks in part to the man-pages internationalization project.

This project aims to translate and maintain man pages in various languages, making the documentation more accessible to users around the world.

Closing thoughts

These tips should get your man page senses tingling. You’ll find that the techniques covered here are enough to bring all the men to the yard, and to powers all you Linux documentation needs.

Stay tuned for part two, in which we’ll cover man page authoring with Groff.

Thanks for reading! If you enjoy humorous tech stories like these and want to support me to keep writing forever, consider signing up to become a Medium member. It’s $5 a month, giving you unlimited access to stories on Medium. If you sign up using my link, I’ll earn a small commission. You can also follow me on Medium and Twitter.