Learn How to Learn Linux: Part 2

This article is part of a series on learning how to learn Linux. In this article we're going to cover the nuts and bolts of the man page system and accessing and using it to your advantage. Additionally, we're going to cover other places you might find documentation on your Linux system and how make best use of it.

The man sections

Understanding the man pages lies in grasping the purpose and utilization of the various sections of the man page corpus (which is just a fancy word for collection).

There are 8 standard man page sections that originate from the original Unix developers Dennis Ritchie and Brian Kernighan (see Part I of the series for more).

These sections are briefly described if you type the following command:

man 7 man-pages

If you do you'll see something like the following:

1 User commands (Programs)
       Commands that can be executed by the user from within a shell.

2 System calls
       Functions which wrap operations performed by the kernel.

3 Library calls
       All library functions excluding the system call wrappers
       (Most of the libc functions).

4 Special files (devices)
       Files found in /dev which allow to access to devices through
       the kernel.

5 File formats and configuration files
       Describes various human-readable file formats and
       configuration files.

6 Games
       Games and funny little programs available on the system.

7 Overview, conventions, and miscellaneous
       Overviews or descriptions of various topics, conventions and
       protocols, character set standards, the standard filesystem
       layout, and miscellaneous other things.

8 System management commands
       Commands like mount(8), many of which only root can execute.

Now you may have commented that the command you typed to view this was a little peculiar. Instead of the typical man command, e.g. man vi, we added a number in between between the word man and what we want a man page for. If you were adventerous and tried to run man-pages in your shell you will have noticed that man-pages is not even a command.

What's going on here is that we've queried section 7 of the man pages with this command and section 7 is labelled "Overview, conventions, and miscellaneous." Thus, this command just returned a man page that was just generally giving information on the "man pages."

Hopefully you're having an "ah-ha" moment right now and realizing that there is a lot more to the man pages that finding out what arguments a command takes. Indeed, if you look at the sections you'll find there are all kinds of goodies tucked away in various sections of the man pages.

One of the core concepts discussed in Part I of this article series is that Unix-based operating systems attempt, traditionally, to come with all the documentation for each component that ship with it. That being said, to locate all the man pages available for a given section, just browse the folders your man pages are in! If you type:

$ ls -1d /usr/share/man/man*
/usr/share/man/man1
/usr/share/man/man4
/usr/share/man/man5
/usr/share/man/man6
/usr/share/man/man7
/usr/share/man/man8
/usr/share/man/man9

If you wish to view the man pages available for section 7 just type

ls /usr/share/man/man7

There are other places, however, that man pages may be stored. Check the shell variable $MANPATH for a comprehensive list for your system (and user). For a more thorough explanation of how $MANPATH is generated see:

man 5 manpath

You'll notice that this is in section 5 of the man pages. This is because it is a reference to the configuration file /etc/manpath.config. This is an extremely useful section. Linux relies heavily on configuration files for proper operation and you are sure to spend a lot of time getting to know them as you use Linux or become acquainted with new tools.

I would highly recommend running the following command to check out what man pages there are for existing configuration files on your system if you haven't ever done this:

ls /usr/share/man/man5

If you don't see any man pages listed in following the above instructions, then don't worry. This mystery will be solved in the next section.

The man-db & man-pages Packages

Now I’ll go out on a limb and assume none of you are running Unix proper at home (or anywhere) but instead one of it’s direct descendants like a distribution of the much loved GNU/Linux.

While the details of how GNU/Linux emerged from the world of Unix is beyond the scope of this article, all you need to know for the sake of this article is that the package man-db makes this mostly possible, and is more or less a port of the original Unix manual pager utilities package for GNU/Linux.

If the man-db package is the paging utilities that let you scroll up and down and search in a man page, then man-pages is the packages that contains the actual man pages that get fed into the pager: the raw, un-rendered man pages.

To install these packages on your Linux distribution should they be missing, use the following:

sudo apt install man-db man-pages

sudo dnf install man-db man-pages 

The man command

I'm sure you are all fairly familiar with the man command if you're reading an article about learning Linux so I won't spend long here.

I would like to point out an extremely useful switch available on the command for those of you that are unfamiliar: -k. This switch provides the same functionality as the antiquated apropos command, which is basically a "search" feature of the man pages.

The -k switch is going to be your go-to tool for situations where you know, or expect, there to be man pages on a topic but you're just not sure what they are.

For example, if you're setting up NFS for the first time on a server or on a client and you just want to see what's available to you as far as man pages on the topic, you would type man -k nfs.  You might do this because you don't know what the configuration files are, or you don't know what commands you need to run on the client, or on the server, etc.

When I run man -k nfs on my system I get the following results:

blkmapd (8)          - pNFS block layout mapping daemon
confstr (3)          - get configuration dependent string variables
filesystems (5)      - Linux filesystem types: ext, ext2, ext3, ext4, hpfs, iso9660, J...
fs (5)               - Linux filesystem types: ext, ext2, ext3, ext4, hpfs, iso9660, J...
idmapd (8)           - NFSv4 ID <-> Name Mapper
idmapd.conf (5)      - configuration file for libnfsidmap
ipa-client-automount (1) - Configure automount and NFS for IPA
mount.nfs (8)        - mount a Network File System
mountstats (8)       - Displays various NFS client per-mount statistics
nfs (5)              - fstab format and options for the nfs file systems
nfs.conf (5)         - general configuration for NFS daemons and tools
nfs.systemd (7)      - managing NFS services through systemd.
nfs4_uid_to_name (3) - ID mapping routines used for NFSv4
nfsconf (8)          - Query various NFS configuration settings
nfsidmap (5)         - The NFS idmapper upcall program
nfsiostat (8)        - Emulate iostat for NFS mount points using /proc/self/mountstats
nfsmount.conf (5)    - Configuration file for NFS mounts
nfsservctl (2)       - syscall interface to kernel nfs daemon
nfsstat (8)          - list NFS statistics
rpc.idmapd (8)       - NFSv4 ID <-> Name Mapper
rpc.sm-notify (8)    - send reboot notifications to NFS peers
rpcdebug (8)         - set and clear NFS and RPC kernel debug flags
showmount (8)        - show mount information for an NFS server
sm-notify (8)        - send reboot notifications to NFS peers
umount.nfs (8)       - unmount a Network File System

You'll notice there is a wealth of information available to you on the topic. You're made aware of everything from filetypes to use with the mount command, to configuration files, to the general man 5 filesystems page.

I cannot overemphasize how much you will learn about Linux by exploring the man pages with man -k.

The Wild West of Documentation: /usr/share

There is often overflow documentation available in /usr/share or /usr/share/doc for complicated programs and frameworks you may have installed on your system. I say "or" because technically /usr/share/doc, which sounds like it would be where the documentation goes, is mentioned briefly in section 4.11.3 of the Filesystem Hierarchy Standard, there's rarely anything too juicy in there. Instead, you'll often find the real documentation – should it exist – in a folder named after the program in question within /usr/share.

For example, gnupg usually comes extremely well-documented, including information in /usr/share/gnupg.  What you'll find in this folder usually comes in two varieties:

1. Example configuration files
2. Manuals and how-to guides in the form of .txt, .html, or sometimes .pdf documents.

While there is no real convention here as how this folder should be structured or what should be contained in here, it's anyone's guess as to what you'll find there for any given program. However conventionless the content may be, the notion of applications that ship with full documentation is something we have the original Unix creators for. That in mind, usually what you'll find here is documentation too extensive for man pages and for that reason you'll usually find it for programs that are quite complex or multi-faceted.

Please note that /share/ directories exist all over the place. Don't forget to check /usr/local/share, $HOME/.local/share and /opt/*/share. All of these are potential locations for documentation and sample configuration files.

To be continued...

In the next article in this series we'll talk about how our use of the command line and the man pages can (and may already have) reveal much deeper information about the inner workings of Linux.