Linux Manual Pages

Linux comes with a large manual in (almost) every installation. You can access the manual using the man shell command, but you’ll need to know a few tricks to find the information you want and navigate once you’ve found it.

The simplest way to use man is to run it with an argument that is the name of a shell command or function you want to learn more about. For example, here we’ll look at the manual page for the ls command:

$ man ls
LS(1)                                User Commands                                LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List  information  about the FILEs (the current directory by default).  Sort en‐
       tries alphabetically if none of -cftuvSUX nor --sort is specified.
Manual page ls(1) line 2 (press h for help or q to quit)

When you run this command it will take over your whole terminal window, so you won’t see the man ls command you typed or anything above that in your terminal window. Don’t worry though, when you quit with the q key the terminal will go back to where it was.

As you might expect, you can use arrow keys to navigate up and down. The page up and page down keys also work as you’d expect.

Manpages can be quite long, so sometimes you’ll want to search for specific words. For example, let’s imagine we want to find out how to get ls to sort its output by the size of each file. To do this, type in /sort and hit enter. The viewer will take you to the first occurrence of the word “sort” and highlight the match. The first hit isn’t very helpful, so we can move to the next by typing in / and hitting enter without entering a new search term. Keep doing this until you reach the documentation for the --sort flag, which appears on an indented line that begins with --sort=WORD. If you go too far, you can search backward using ? instead of /.

Sections

The Linux manual pages are broken into numbered sections. The ls command appears in section 1, which covers general-purpose command-line programs that you can run in the terminal. When you run man SOMETHING you’ll get the page called “SOMETHING” in the lowest-numbered section that has a matching page. The command man exit will return a match from section 1, but what if you want an entry that describes the C function exit()?

You’ll find C functions in sections 2 and 3 of the manpages. Section 2 covers what are called system calls, which you can think of as the functions that directly ask the operating system to do something for you; these functions tend to be a little less user friendly so we won’t use them often in this class. Section 3 is where you’ll find the C standard library functions, which is likely where you’ll want to go if you aren’t looking for a command-line utility in section 1. We might wander into later sections of the manpages, but sections 1 and 3 (with occasional visits to section 2) will likely be enough for almost everything you need to look up.

To open the manpage for exit in section 3, run:

$ man 3 exit

Manpages for C functions follow a standard format you can use to quickly find information. The SYNOPSIS section will list any #include lines you need to add to use these functions, followed by the signature of each function in this manpage. Related functions are often grouped together on a single manpage, and the documentation will often discuss one function in detail, while the rest are described in terms of their differences from the first function. If a function returns anything, you’ll find a RETURN VALUE section that explains how you should interpret the result you get back when calling the function. You’ll develop an intuition for the other useful sections in manpages as you use them.

You might be wondering where these section numbers come from. They actually correspond to the sections of a printed manual that was provided with the UNIX operating system. You can find PDF versions of that original manual at https://www.bell-labs.com/usr/dmr/www/1stEdman.html if you’re curious.