Man Pages

RTF(ull)M

This makes me think of the the paper manuals that came inside of a box with the game cartridge back in the day. They taught one about the game, how to play, and gave helpful information to make one’s questing more enjoyable. Well, the “man pages” are like those manuals, but for commands/packages/software on a Linux system.

Using The Manual

You can view pages from the manual using:

man <page>

Where <page> is the name of the page you want. For instance:

man ls
man cat
man find

Besides just man <page> one may often find themselves wanting to search the manual for something or specify a particular section to read.

Specify Section

Per man(1):

The default action is to search in all of the available sections following a pre-defined order (“1 n l 8 3 2 5 4 9 6 7”…)

But what if I’m searching for a particular command (let’s call it foo) that has pages in section 1 as well as section 7. Invoking man foo brings up foo(1) from the manual. If I want to see the page from section 7 I’d use man 7 foo. Supposedly I should also be able to use man foo.7 but I can’t seem to get that to work (Fedora 24). Not sure why yet.

There are a couple of options. The ones I like are man -f also known as whatis and man -k also known as apropos.

What I like about man -f is that it displays a concise description of a command from the description of each section. The handy part is that it lets me know which sections are available for a given command.

Then man -k allows a full text search of the names and descriptions. This can be used to look up pages about a particular topic, such as http for instance.

One could also invoke man -K (capital K) for a full text search of the entirety of every man page. Could take awhile to get a result out of this one if you’ve got a lot of pages in the manual.

Sections

The manual has several sections:

  1. Executable programs or shell commands
  2. System calls (functions provided by the kernel)
  3. Library calls (functions within program libraries)
  4. Special files (usually found in /dev)
  5. File formats and conventions eg /etc/passwd
  6. Games
  7. Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
  8. System administration commands (usually only for root)
  9. Kernel routines [Non standard]

Page Anatomy

Each page also has its own sections taken from this list:

  • NAME
  • SYNOPSIS
  • CONFIGURATION
  • DESCRIPTION
  • OPTIONS
  • EXIT STATUS
  • RETURN VALUE
  • ERRORS
  • ENVIRONMENT
  • FILES
  • VERSIONS
  • CONFORMING TO
  • NOTES
  • BUGS
  • EXAMPLE
  • AUTHORS
  • SEE ALSO

They’re not all required, some have many, I don’t know if any pages actually use all of those sections.

Where are they stored?

Per FHS 3.0, /usr/share/man is where they should be stored, but for what YOUR system uses, just run the manpath command. The manpath command “…is determined using information gained from the man-db configuration file.”

I imagine the manual on a system as a 3-ring locking binder that allows for one to easily add/remove pages as needed. My experience in the matter is that they are put there by whoever built your distribution, but can be added automatically when one uses their package manager to install something. Otherwise it would need to be done manually by just copying the files into the appropriate place.

More Info

Just check out man(1). Now you know how!