Man Pages

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:

† 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:

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


Links