How do I read `man` pages?

UNIX systems traditionally come with a built-in manual. How do we read it?

The manual is accessed with a command called man. You will probably have seen that you can read about a UNIX command by prepending it with man. For example, to learn about ls, we run:

man ls

This shows a page like:

LS(1)                     BSD General Commands Manual                    LS(1)

NAME
     ls -- list directory contents

SYNOPSIS
     ls [-ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1] [file ...]

DESCRIPTION
     For each operand that names a file of a type other than directory, ls
     displays its name as well as any requested, associated information.  For
     each operand that names a file of type directory, ls displays the names of
     files contained within that directory, as well as any requested, associated
     information.

[...]

SEE ALSO
     chflags(1), chmod(1), sort(1), xterm(1), compat(5), termcap(5), symlink(7), sticky(8)

[...]

The man command is essentially a file viewer. The manual contents are stored on your machine as files. It has some logic to find the “man page” for ls, then displays that page. You can use --path to skip the second step and just print where the page is located:

% man --path ls
/usr/share/man/man1/ls.1

What does that file look like?

% cat /usr/share/man/man1/ls.1
.\" Copyright (c) 1980, 1990, 1991, 1993, 1994
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Institute of Electrical and Electronics Engineers, Inc.
[...]
.\"     @(#)ls.1	8.7 (Berkeley) 7/29/94
.\" $FreeBSD: src/bin/ls/ls.1,v 1.69 2002/08/21 17:32:34 trhodes Exp $
.\"
.Dd May 19, 2002
.Dt LS 1
.Os
.Sh NAME
.Nm ls
.Nd list directory contents
.Sh SYNOPSIS
.Nm ls
.Op Fl ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1
.Op Ar
.Sh DESCRIPTION
For each operand that names a
.Ar file
of a type other than
directory,
.Nm ls
displays its name as well as any requested,
associated information.
[...]

This is troff format; it is consumed by a program called troff. The GNU version is groff. You can show the man page in its familiar format by running:

% groff -man -T utf8 /usr/share/man/man1/ls.1

LS(1)                     BSD General Commands Manual                    LS(1)

NAME
     ls — list directory contents

SYNOPSIS
     ls [−ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1] [file ...]
[...]

How did man determine that the page for ls was in the file at /usr/share/man/man1/ls.1? man has a search path, which you can see with man --path:

% man --path
/Users/jhf/.opam/system/share/man:/Users/jhf/bin/depot_tools/man:/Users/jhf/Library/Haskell/share/man:/usr/local/share/man:/usr/share/man:/Applications/Xcode.app/Contents/Developer/usr/share/man:/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/man:/Users/jhf/.opam/system/man

There are lots of extra directories in my setup. The important one for now is /usr/share/man. Here’s the top level of it:

% ls /usr/share/man
man1   man2   man3   man4   man5   man6   man7   man8   man9   mann   whatis

All paths in the man search path have this top-level structure: man1, man2, etc. These numbers are the sections of the manual. You can see that ls is in section 1 because it’s in /usr/share/man/man1/..., and when man displays it, the header shows LS(1).

The manual’s sections are:

Section   Content                 Examples    Notes
========  ======================  ==========  =====
1         Commands                ls(1)       The familiar section; man looks here first
2         System calls            mmap(2)     My machine has 245 system calls
3         Library functions       malloc(3)   By far the largest, with 13K entries
4         Special files; drivers  random(4)   46
5         File formats            utf(5)      196
6         Games and screensavers  banner(6)   Ignore this section
7         Miscellaneous           ascii(7)    52
8         Sysadmin commands       ping(8)     Unclear distinction with section 1

man searches each section in order. If there is an entry in an earlier section, this takes priority. For example, there is an entry random(4), but you can’t access it using man random, because there is a C library function called random, and this is documented in section 3. To access a page in a specific section, run:

man 4 random    # gets page "random" from section 4 of the manual

Each section has an “intro” page. For example, man 3 intro gives an introduction to C library functions.

Tagged #man, #posix, #c, #documentation, #programming.

More by Jim

What does the dot do in JavaScript?

foo.bar, foo.bar(), or foo.bar = baz - what do they mean? A deep dive into prototypical inheritance and getters/setters. 2020-11-01

Smear phishing: a new Android vulnerability

Trick Android to display an SMS as coming from any contact. Convincing phishing vuln, but still unpatched. 2020-08-06

A probabilistic pub quiz for nerds

A “true or false” quiz where you respond with your confidence level, and the optimal strategy is to report your true belief. 2020-04-26

Time is running out to catch COVID-19

Simulation shows it’s rational to deliberately infect yourself with COVID-19 early on to get treatment, but after healthcare capacity is exceeded, it’s better to avoid infection. Includes interactive parameters and visualizations. 2020-03-14

The inception bar: a new phishing method

A new phishing technique that displays a fake URL bar in Chrome for mobile. A key innovation is the “scroll jail” that traps the user in a fake browser. 2019-04-27

The hacker hype cycle

I got started with simple web development, but because enamored with increasingly esoteric programming concepts, leading to a “trough of hipster technologies” before returning to more productive work. 2019-03-23

Project C-43: the lost origins of asymmetric crypto

Bob invents asymmetric cryptography by playing loud white noise to obscure Alice’s message, which he can cancel out but an eavesdropper cannot. This idea, published in 1944 by Walter Koenig Jr., is the forgotten origin of asymmetric crypto. 2019-02-16

How Hacker News stays interesting

Hacker News buried my post on conspiracy theories in my family due to overheated discussion, not censorship. Moderation keeps the site focused on interesting technical content. 2019-01-26

My parents are Flat-Earthers

For decades, my parents have been working up to Flat-Earther beliefs. From Egyptology to Jehovah’s Witnesses to theories that human built the Moon billions of years in the future. Surprisingly, it doesn’t affect their successful lives very much. For me, it’s a fun family pastime. 2019-01-20

The dots do matter: how to scam a Gmail user

Gmail’s “dots don’t matter” feature lets scammers create an account on, say, Netflix, with your email address but different dots. Results in convincing phishing emails. 2018-04-07

The sorry state of OpenSSL usability

OpenSSL’s inadequate documentation, confusing key formats, and deprecated interfaces make it difficult to use, despite its importance. 2017-12-02

I hate telephones

I hate telephones. Some rational reasons: lack of authentication, no spam filtering, forced synchronous communication. But also just a visceral fear. 2017-11-08

The Three Ts of Time, Thought and Typing: measuring cost on the web

Businesses often tout “free” services, but the real costs come in terms of time, thought, and typing required from users. Reducing these “Three Ts” is key to improving sign-up flows and increasing conversions. 2017-10-26

Granddad died today

Granddad died. The unspoken practice of death-by-dehydration in the NHS. The Liverpool Care Pathway. Assisted dying in the UK. The importance of planning in end-of-life care. 2017-05-19

How do I call a program in C, setting up standard pipes?

A C function to create a new process, set up its standard input/output/error pipes, and return a struct containing the process ID and pipe file descriptors. 2017-02-17

Your syntax highlighter is wrong

Syntax highlighters make value judgments about code. Most highlighters judge that comments are cruft, and try to hide them. Most diff viewers judge that code deletions are bad. 2014-05-11

Want to build a fantastic product using LLMs? I work at Granola where we're building the future IDE for knowledge work. Come and work with us! Read more or get in touch!

This page copyright James Fisher 2017. Content is not associated with my employer. Found an error? Edit this page.

How do I read man pages?

Similar posts

More by Jim

How do I read `man` pages?