man is a program for interacting with your system’s reference manuals and is an absolute necessity when working on the command line. It can display useful information about the purpose and usage of things like executables, system calls, special files and much, much more.
man to examine what
ls does. To do this, run
man ls – a window should open with the documentation of the command
This is the default way to use
man – it tries to look for a manual page(s), whose name matches the provided argument(s). However, there are other it can also do different things, depending on if the following flags are specified:
||Gives short descriptions of the matching manual pages.|
||Searches for text in the man pages themselves.|
||Only print the location of the page, don’t display it.|
||Attempt to show all matched pages (not just the first one.|
Although the default usage is arguably the most useful, it is still good to know of others.
As mentioned above,
man covers a variety of topics, divided in to various sections. The division is necessary, because (for example)
exit could mean any of the following:
- a shell command
- a system call
- a C library function
Some common sections include:
||Library functions, mostly the C standard library|
||Special files (usually devices from /dev) and drivers|
||File formats and conventions|
||Games and screensavers|
||System administration commands and daemons|
To specify, which section the page should be displayed from, either of the following works:
Changing the way the page is displayed
man contains a few flags for modifying how the text is rendered:
||Set the encoding of the displayed page.|
||Prevent line breaks on words that don’t contain hyphens.|
||Don’t justify to both margins.|
Also, if you set the
MANWIDTH environment variable, the width of the page will automatically adjusted to its value. If not, it will default to taking up the whole terminal window width.
Exporting to other formats
One can use the
-T option to convert a manpage to a different format. For example,
man -Tpdf ls > ls_man_page.pdf will generate a neat-looking PDF. Other formats like PS and HTML are also supported – to see the full list, see
groff’s documentation (namely the
In my opinion,
man pages are, by default, rather dull-looking. They use
less by default to do the displaying and while it does offer some forms of highlighting (bold, italics,…), it is quite limited and not nearly as nice as it could be.
One way to change this is to use
most comes in – it’s also a pager, similar to
less, but offers nice coloring out-of-the-box. To use it, first install it using your package manager and then use the
man -Pmost ls. A good idea to make this change persistent would either be to create an alias, or to change the
MANPAGER variable in your shell to
Changing the language
The language that
man uses is determined by the
LC_MESSAGES environment variables. If you prefer to display the manual pages in other languages1, use the
man -Lcs gpasswd –
man will try to open the page in the language of your choice and will default to English if it isn’t successful.
man internally uses
/etc/man_db.conf for configuration. Examining the file can tell you where
man looks for the reference pages that it can display, and also the order in which sections are searcher for your manpage.
The manual files are (normally) stored in the
nroff format (compressed in the
.gz format) and are then processed using various pre-processors, followed by the
groff formatting system and then either ran through additional post-processors, or presented to the user via a pager (
less by default).
A sample page’s source file (
ls, for example, found in
/usr/share/man/man1/ls.1.gz on my machine) looks something like this:
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.3. .TH LS "1" "March 2020" "GNU coreutils 8.32" "User Commands" .SH NAME ls \- list directory contents .SH SYNOPSIS .B ls [\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... .SH DESCRIPTION .\" Add any additional description here .PP List information about the FILEs (the current directory by default). Sort entries alphabetically if none of \fB\-cftuvSUX\fR nor \fB\-\-sort\fR is specified. .PP Mandatory arguments to long options are mandatory for short options too. .TP \fB\-a\fR, \fB\-\-all\fR do not ignore entries starting with . .TP \fB\-A\fR, \fB\-\-almost\-all\fR do not list implied . and ..
Interestingly enough, this particular man page is actually auto-generated from
--version flags using the
help2man. I found that some other commands (
date) also do it, but a lot of them don’t.
The above results in the following output:
LS(1) User Commands LS(1) NAME ls - list directory contents SYNOPSIS ls [OPTION]... [FILE]... DESCRIPTION List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuvSUX nor --sort is speci‐ fied. 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 ..
- Man page Wikipedia page
Sadly, the language support for most of the languages is rather limited. Browsing through a few of them, a lot of translations are in a WIP state and they only cover the most essential commands. Let’s hope that this will change in the future 🙂. ↩