Table of Contents
Introduction
Imagine you’re trying to complete a project that’s due soon. While scouring through posts on various forums, you finally find the miracle command that fixes all of your problems. You smile to yourself because with that specific command and all of its weird options, everything just somehow works. This mode of operation works for a while until your conscience catches up with you and you start to wonder why the -ravHP flags were necessary to make rsync behave the way you needed it to when all the other times failed. How is it that the dorky keyboard warrior with 17.5K reputation on Stack Overflow knew to include those options and you didn’t? Where do you go to find the Holy Grail of all of this nerdy knowledge? For that, you need to RTFM (what that stands for totally depends on you 😉).
History
The concept of manual pages for a program is a nifty feature that is as old as the great grandfather of an operating system itself: Unix. Inventors of the C programming language, Ken Thompson and Dennis Ritchie are the first set of programmers to standardize manuals for their programs on a *-nix system. These manuals contain much more explanation than the quick --help option on the desired program would do all by itself. These separate manual entries for each program available on the system are compiled into one place and made searchable by the program man.
Manual Sections
The Manual is split up into 9 different sections, each with a myriad of individual man pages for the commands that a part of that section. The organization as follows:
| Section 1 | User commands | Programs that the user for productivity (i.e terminal, web browser, etc) |
| Section 2 | System calls | List of system calls that control how the OS interfaces with the kernel |
| Section 3 | Library functions | Explanation of libraries used in Standard C lib |
| Section 4 | Special Files | Describes special files like devices |
| Section 5 | File Formats | Deals with file formats and protocols |
| Section 6 | Games | Fun programs that exist for entertainment |
| Section 7 | Conventions and miscellaneous | Hodge-podge of odds and ends programs |
| Section 8 | Administration and privileged commands | For commands only used as sudo or root |
| Section 9 | Kernel routines [Non standard] | Special functions to interface with the kernel |
Just by the looking at the variety and quantity of sections and pages within sections, it should be obvious that this manual is not a cover to cover book to read, but rather a reference. However, if you do want to become a little more familiar with the concepts surrounding these sections, their introductions are available by simply entering:
man <sect number> intro
Page Sections
The man pages that are sitting on your Linux box today have gone through a lot of evolution. With that evolution, it is inevitable to notice some artifacts from this process. For most programs, a certain Linux format has been followed and with that, required headings/sections standardized. Other programs (i.e. cd ) pre-date Linux and adhere to manual programs (i.e. the POSIX Programmer’s Manual). Regardless of where the man page for your desired query originated, there are still some overlapping sections that will contain the bulk of the information you need to know.
Name
This section will give you name of the program and maybe a little blip about what it does. Knowing the name of the program is particularly useful in helping you memorize commands because the command/name association. For example, the following man pages of ls and rm explain their name like so (emphasis added):
ls - it directory contents
rm - eove files or directories
Synopsis
This section provides “a brief summary of the command or function’s interface”. It is in this section you will see how the command is actually used and in what order certain arguments to the program are placed. The capitalized text enclosed in square braces indicates the placement of the arguments or options for the specific command.
ls [OPTION]... [FILE]...
rm [OPTION]... [FILE]...
Description
This section provides an explanation for what the program does and the purpose it tries to serve. Unfortunately, some authors of these pages abuse this section and also use it as a place to list the options that the command can support:
List information about the FILEs (the current directory by default). Sort entries alphabetically if none of
-cftuvSUX nor --sort is specified.
Mandatory arguments to long options are mandatory for short options too.
-a, --all
do not ignore entries starting with .
-A, --almost-all
do not list implied . and ..
--author
with -l, print the author of each file
-b, --escape
print C-style escapes for nongraphic characters
....
This manual page documents the GNU version of . removes each specified file. By default, it does not
remove directories.
If the -I or --interactive=once option is given, and there are more than three files or the -r, -R, or --re‐
cursive are given, then rm prompts the user for whether to proceed with the entire operation. If the re‐
sponse is not affirmative, the entire command is aborted.
Otherwise, if a file is unwritable, standard input is a terminal, and the -f or --force option is not given,
or the -i or --interactive=always option is given, rm prompts the user for whether to remove the file. If
the response is not affirmative, the file is skipped.
Options
This section is where you will likely spend most of your time. It provides a description of all of the options that can be added to the command to modify its behavior:
Remove (unlink) the FILE(s).
ignore nonexistent files and arguments, never prompt
prompt before every removal
prompt once before removing more than three files, or when removing recursively; less intrusive than
while still giving protection against most mistakes
[=WHEN]
prompt according to WHEN: never, once ), or always ); without WHEN, prompt always
The cd utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax
Guidelines.
The following options shall be supported by the implementation:
Handle the operand dot-dot logically; symbolic link components shall not be resolved before dot-dot
components are processed (see steps 8. and 9. in the DESCRIPTION).
Handle the operand dot-dot physically; symbolic link components shall be resolved before dot-dot
components are processed (see step 7. in the DESCRIPTION).
If both and options are specified, the last of these options shall be used and all others ignored. If
neither nor is specified, the operand shall be handled dot-dot logically; see the DESCRIPTION.
There are many more helpful sections included in man pages for specific use-case functions that I can’t touch on here. But if your interest is piqued enough, you can always read more about it by executing:
$ man man-pages
Usage
Now that you are excited to start reading about your favorite, obscure Linux command, how do you actually start? In most cases, it is as easy as typing in:
man <name of the program here>
Most times, this will work, but on the occasion that there is no man page for the program you are looking for, you can use the -k flag to search for a term throughout the entire manual
man -k <name of the topic here>
Since man is its own program, you can also learn more about its usage by looking for its own manual entry!
man man
This article from the Gentoo Wiki has a very straightforward explanation of navigating your way around the program.
Useful Resources
If you are working on your own computer, have access to a web browser, and don’t necessarily like reading all of your documents in the monospaced font your terminal probably provides, you can peruse the man pages using the following links:
Conclusion
Becoming self-sufficient with the tools that you use in the mark of a true professional. The man pages in Linux are the de facto source of knowledge when it comes to using any sort of command line tool. Being familiar with these can possibly save you from hours of head scratching and expose you to a deeper knowledge of your Linux system.