#11: Understanding Linux man pages
man
is probably one of the most used Linux commands at all. Less known, however, is that man
is more than just man
. Manual pages on Linux are divided into eight categories:
- User commands that everyone can execute
- System calls (syscalls) provided by the kernel
- C library functions
- Devices and special files (e.g. device files in
/dev
) - File formats and conventions (e.g. syntax of
/etc/fstab
) - Games and other fun stuff
- Miscellaneous (e.g. macro packages)
- System administration tools and daemons that only root can execute
This is the basic structure of man pages; some distributions may extend this scheme. Because of this structure, there may be several man pages of the same name in different sections. E.g., mount
appears in section 8 with a man page describing the usage of the command itself and in section 2 describing the syscall mount()
. To specify which section you want to see, you have to pass its number to man
, i.e., to see section 2 for mount
(the syscall) run
man 2 mount
If you don't pass the section number, man
will search all sections in that order set with MANSECT
. This might be either configured in your /etc/man.conf
or as an environment variable. It contains a colon separated list of sections. man
traverses this list until it finds a category containing a proper man page. On my system I've got the following priority order, but your's might look completely different as it differs from system to system:
MANSECT 1:1p:8:2:3:3p:4:5:6:7:9:0p:tcl:n:l:p:o:1x:2x:3x:4x:5x:6x:7x:8x
With this order being set, man
looks in section 1 and 1p at first, then in 8, 2, 3, etc. Thus, when I run man mount
I get mount(8)
since section 2 has a lower priority than 8. You also see that I have some more proprietary sections than just 1-8. Instead of sticking to the default order, you may also set the order manually with the parameter -S
. The following call of man
would prefer section 2 over 8:
man -S "2:8" mount
Man pages are saved as compressed files in /usr/share/man
. They are stored in directories named man1
, man2
, man3
etc. /usr/share/man
might also contain directories for different languages than English. If you set your system to a language other than English, man
tries to find man pages in the corresponding language folder first and uses the default English man pages as fallback.
I've shown you the parameter -S
, but another interesting one is -a
. This shows all man pages from all sections for the given command. So when you exit the first man page by hitting q
on your keyboard, the next one is displayed (if there is one) until no more man pages are found. I find this option very interesting, but to be honest: I've never used it because it's quite inefficient to skip through all available man pages. In my humble opinion, man -f
and whatis
, respectively, are a much better way. Both commands do exactly the same: they display a short list of available man pages. This list is extracted from the whatis database located at /usr/share/man/whatis
by default. It is created with makewhatis
. If you know what's in which section, you can now directly open the appropriate man page without having to read all of them. Here's some example output for whatis mount
:
mount (2) - mount file system mount (8) - mount a filesystem mount [] (2) - mount file system mount.cifs [] (8) - mount using the Common Internet File System (CIFS) mount.cifs [mount] (8) - mount using the Common Internet File System (CIFS) mount.nfs [mount] (8) - mount a Network File System mount.nfs4 [mount] (8) - mount a Network File System
There are two man pages for mount
(sections 2 and 8 ) and some other for related commands such as mount.cifs
or mount.nfs
. You also see a short description. If you need more verbose output you can use apropos
(which is the same as man -k
). That searches all entries in the whatis database for the given keyword. Most of the time the output of apropos
is too verbose but sometimes it's very helpful if you need help for something but don't find an appropriate man page for it.
Normally your man pages are located at /usr/share/man
, but you can move them wherever you want. You only have to set the MANPATH
directive in /etc/man.conf
or the MANPATH
environment variable to the new location. It's also possible to use a different location to read the man pages from with the -M
parameter. The following command would read the man pages for mount
from /usr/share/othermanpages
:
man -M /usr/share/othermanpages mount
It's also possible to set the pager application used for displaying the man page on the console by passing -P
to man
:
man -P /bin/more mount
This would use more
as the pager instead of less
. I've also written an article about console pagers here on Refining Linux. To read more about this topic see Configuring your console pager. For more information about the command man
run man man
. That sounds like Chinese, but it is just the man page for man
.
An alternative to man
is info
. This man page system uses hypertext and has some advantages such as nodes you can jump between (press n
or enter for next node, p
for previous), hyperlinks and more – just what hypertext can do. Particularly GNU tools do not only have a conventional man page but also an info page, which often contains more precise information. The man pages for those tools not very seldom contain something like “See the info entry for more information on this command”. Some people really prefer info
over man
and yes, it has some advantages, but I still prefer the good old-fashioned man pages since many of them provide a better reading experience due to nicer formatting and more consistent structure. Therefore, I use info pages rarely and even not at all if I don't have to. But it's your decision which tool you use.
Read more about man and info pages:
RT @reflinux: #Advent series "24 Short #Linux #Hints", day 11: Understanding Linux #man pages http://bit.ly/hl1tKt