#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 mountIf 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" mountMan 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 mountIt'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 mountThis 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