Understanding Man Pages ⋆ integralist

Introduction

Your operating system provides manual pages that explain what specific commands do and where they can be located on your computer.

Most of us are at least familiar with opening a terminal and typing:

man <some_command>

But you might be confused, when you see a manual page informing you to check out <another_command>(2). For example, you might be shown the message at the end of a man page that says See also: chmod(2).

If you try that, it won’t work:

man chmod(2)

So let’s understand why that is and what it means.

Sections

So the manual pages are separated into ‘sections’. This is what the number within the parentheses represents (i.e. chmod(2) represents the chmod command from section 2 of the OS manual).

To find where your manual pages are stored:

cd /usr/share/man

A simple ls will show that on my OS (macOS) I have nine manuals:

man1/   man2/   man3/   man4/   man5/   man6/   man7/   man8/   man9/

Each manual section has an introduction page † that explains what the section covers. These (taken from my OS) are as follows:

man1: introduction to general commands (tools and utilities)
man2: introduction to system calls and error numbers
man3: introduction to the C libraries
man4: contains documentation on special files and sockets
man5: introduction to file formats
man6: contains documentation about games and other miscellaneous fun programs
man7: miscellaneous information pages
man8: introduction to system maintenance and operation commands
man9: introduction to system kernel interfaces

† except for manual sections 4 and 6. I had to go to the online reference for macOS in order to find out what they contained

If you wanted to know ‘at a glance’ what commands were available, then you could install the tree command and execute it at the current directory (/usr/share/man) and this would show you something like the following (cut short for brevity):

.
├── man1
│   ├── ab.1
│   ├── accesstool.1
│   ├── addftinfo.1
│   ├── afconvert.1
│   ├── afhash.1
│   ├── afida.1
│   ├── afinfo.1
├── man2
│   ├── accept.2
│   ├── access.2
│   ├── acct.2
│   ├── adjtime.2
│   ├── aio_cancel.2
│   ├── aio_error.2
│   ├── aio_read.2

Sub sections

You’ll notice that most page files within each manual section have an extension that matches the section they’re contained within (e.g. ab.1 for ab command inside manual 1 or aio_read.2 for aio_read command inside manual 2).

What’s interesting is that there are some files, such as httpdstat.d.1m (which is inside manual section 1) that have a different extension (d.1m) or asn1parse.1ssl (1ssl).

By looking back at the online macOS manual pages reference I noticed there were additional sub sections:

Section 1m: contains documentation for tools built on top of DTrace
Section 1ssl: contains documentation on tools that are part of OpenSSL
Section 1tcl: contains documentation on tools that are part of Tcl
Section 3cc: contains documentation on the Common Crypto API
Section 3pcap: contains documentation on the packet capture library, libpcap
Section 3pm: contains documentation on Perl modules
Section 3ssl: contains documentation on OpenSSL C library routines
Section 3tcl: contains documentation on Tcl/Tk C library routines
Section 3x: contains documentation on curses-related C library routines
Section 5ssl: contains documentation on SSL-specific configuration file formats
Section 7ssl: miscellaneous SSL documentation section
Section n: contains documentation about Tcl/Tk
Section ntcl: contains documentation about Tcl/Tk

Accessing different sections

Typically when we type man <some_command>, the man command will search all the sections looking for the specified command.

It stops at the first match it finds. So there could be a scenario where you search for a command and you get the user space (top-level) entry command and not the ‘system call’ version that actually interacts with your OS.

The chmod command is a good example of that scenario.

If you want to see the actual system call manual page for chmod, you need to search inside the specific section (which in this case is 2):

man 2 chmod

Alternatively, you can search multiple specific sections:

man -S 1:2 chmod

The above command will search through only sections 1 and 2, but it will still stop at the first match it finds so the above command is no different in outcome than just man chmod.

But if you know for sure that the command you’re looking for is somewhere within either the system call or C library manual pages, then man -S 2:3 <your_command> would prevent a command from manual section 1 getting matched first.

Note: to see the intro page for a section use man <n> intro

Searching by phrase

In case you’re unsure where to find a specific piece of information, you can use the -K flag which will search all manuals for the given search term/phrase. This can be slow, so it’s best to also provide a manual to scope the search down to.

For example, I wanted to lookup refspec in the git manual. I didn’t know where to look so I ran the following lookup:

man -K "refspec" git

This then presented a manual name along with the options of y/n/q.

If I type y then the listed manual page would be opened. Once I ‘quit’ the page (e.g. q) then the next manual page found to contain the phrase refspec would be listed along with the y/n/q options. Anytime you want to stop going through the list of matches, you type q.