man
intro to Linux , released 9. 8. 2020, updated 19. 7. 2023
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.
Usage
Let’s use man
to examine what ls
does. To do this, run man ls
– a window should open with the documentation of the command ls
.
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:
Flag | Description |
---|---|
-f , --whatis |
Gives short descriptions of the matching manual pages. |
-K , --global-apropos |
Searches for text in the man pages themselves. |
-w , --where |
Only print the location of the page, don’t display it. |
-a , --all |
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.
Specifying sections
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:
Section | Description |
---|---|
1 |
General commands |
2 |
System calls |
3 |
Library functions, mostly the C standard library |
4 |
Special files (usually devices from /dev) and drivers |
5 |
File formats and conventions |
6 |
Games and screensavers |
7 |
Miscellanea |
8 |
System administration commands and daemons |
9 |
Kernel routines |
l |
Local documentation |
n |
Tcl/Tk keywords |
To specify, which section the page should be displayed from, either of the following works:
man <page>.<section>
man <page>(<section>)
Changing the way the page is displayed
man
contains a few flags for modifying how the text is rendered:
Flag | Description |
---|---|
-E , |
Set the encoding of the displayed page. |
--nh , |
Prevent line breaks on words that don’t contain hyphens. |
--nj , |
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 -T
flag).
Adding color
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 -P
flag: man -Pmost ls
. A good idea to make this change persistent would either be to create an alias, or to change the PAGER
/MANPAGER
variable in your shell to most
.
Changing the language
The language that man
uses is determined by the LANG
and LC_MESSAGES
environment variables. If you prefer to display the manual pages in other languages1, use the -L
flag: 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.
Internals
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 ls
’s --help
and --version
flags using the help2man
. I found that some other commands (uname
, printf
, chroot
, 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 ..
Sources
man man
- 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 🙂. ↩