Winter 2014 - January to April 2014 - Updated 2018-10-04 17:44 EDT
Unix-like operating systems – including Linux, BSD, and OSX – have command-line help files called “man pages” (manual pages). The usual way to access to man pages is via the man
command.
You may be told to RTFM
which means Read the F*** Manual
. That’s what this page is about.
First, we need to know how manual pages are displayed on your screen.
less
IndexWhen you type man something
at a Linux shell prompt, the pages of the manual are displayed one-at-a-time using a standard “pagination” program named less
. For example, try:
$ man date
You will see one screen of the manual followed by a Manual page
prompt at the bottom of your terminal screen. You can type the characters h
or ?
to get a list of possible commands that the less
pagination program can do. Typing q
will return you from the help screen back to the manual page itself. Typing q
again will quit the man
program and return you to your shell prompt.
Common commands you use in the less
program are q
(quit) and SPACE BAR to go to the next page. A b
goes back one page. If you forget how to use less
, ask for the help screen by typing ?
or h
at the Manual page
prompt. Try these now.
If
less
is not available to paginate the output, theman
command usesmore
in place ofless
. Themore
andless
commands are more-or-less the same, withless
having more features.
You can also look at Linux man pages online, though this is a generic set of manual pages that may or may not apply to the commands on the version of Linux that you are running.
Because manual pages are usually paginated using a standard pagination program such as less
, you can use all the features of the pagination program to search inside the manual page, including the text search feature that is usually bound to the slash key /
.
For example, bring up the man page for the ls
command (man ls
) and then at the Manual page
prompt at the bottom of your screen search for the three words long listing format
by typing a slash followed by the words you want to search for, followed by the ENTER
kay:
/long listing format
You will instantly skip forward to the -l
option description that makes the ls
command give a long listing output format:
-l use a long listing format
You can use the n
key to repeat a search if the first thing you find isn’t what you are looking for. Try searching for the word file
and use the n
key repeatedly to find each line containing the word.
If you forget how to use these features, simply follow the help directions in the prompt at the bottom of your screen as you read the manual page, or try man less
at the shell prompt for more information on the less
pagination program itself.
man
command – man man
and man intro
IndexYou may find the short web resource Using Man Pages useful for understanding the format of manual pages.
The arguments to the man
command must be single command names or topics, e.g.
$ man date
$ man ls
$ man intro
$ man man
A useful start page and command introduction is: man intro
The introduction summarizes these important topics:
If you want to know what the -p
option to the mkdir
command does, look in the man page for the mkdir
command, i.e. you must type:
$ man mkdir
You cannot say man mkdir -p
nor can you type man -p
. You must open man mkdir
and do a text search for the -p
option in the mkdir
man page. You can use the slash (/
) character to text search for the option name inside the man page and n
to search again.
Some basic GNU/Linux “coreutils” manual pages are incomplete summaries of the master GNU TexInfo documentation pages; these pages have a SEE ALSO section at the bottom saying The full documentation for [this command] is maintained as a Texinfo manual. This means these man pages are very terse and don’t have all the information about commands that you might need. You can find a list of these basic “coreutils” commands here: http://www.gnu.org/software/coreutils/manual/coreutils.html#Top
The full TexInfo documentation is readable online using the old info
or pinfo
commands, but these commands pre-date HTML and are hard to learn and use. You can try to learn to use the info
or pinfo
commands, or you can read the documentation online in easy-to-read HTML form.
You can find the full documentation for most of the basic (“core”) Linux commands online at http://www.gnu.org/software/coreutils/ in the online manual http://www.gnu.org/software/coreutils/manual/
The Unix manual has “sections”. The man command searches sections in a particular order and finds the first matching man page (which may not be in the section you want). Specify the section number first to see a page in a particular section, e.g.: man 5 passwd
Useful sections (for details, try man 1 intro
, man 2 intro
, etc.):
date, who, ls
useradd, ifconfig
read(), write()
fread(), fwrite()
null, fifo, zero, hd
passwd, group, resolv.conf
See how the section number changes what information you get:
$ man passwd # gives passwd command syntax from section 1
$ man 5 passwd # gives /etc/passwd file format from section 5
man -k
and apropos
IndexSometimes you don’t know what manual page you want. You can search all the title lines (and only the title lines) using the ‘-k
’ (keyword) option to the man
command, followed by a single keyword:
$ man -k keyword
The output of this search is not paginated, so often, if there are many results, you want to pipe the output of man -k
into a pagination program such as less
:
$ man -k keyword | less
The |
character is the Unix “pipe” special character (often SHIFT-\
).
The man -k
command works the same way as the apropos
command:
$ man -k keyword | less
$ apropos keyword | less
They are the same command.
Often, you get pages you don’t want in the output of man -k
. You can pipe the output of man -k
into the grep
or fgrep
programs to select output that is more useful. To see only pages in section (1)
of the manual (only the commands):
$ man -k name | fgrep '(1)' | less
Note the use of single quotes to protect the special characters (in this case, parentheses) from the Unix shell. Until you know what characters are safe, always single-quote the first argument to the fgrep
command.
The
fgrep
command is the same as thegrep -F
command and option; it runsgrep
using fixed strings (not patterns) as the search strings. Until you know how to usegrep
patterns, always usefgrep
.
To find only pages that are not in section (1) of the manual:
$ man -k name | fgrep -v '(1)' | less
Note the use of the -v
option to the fgrep
command (RTFM).
Finding pages containing “name” in the title, that are in section (1), that do not contain the string “directory” in the title:
$ man -k name | fgrep '(1)' | fgrep -v 'directory' | less
The man -k
command works the same way as the apropos
command:
$ apropos name | fgrep '(1)' | fgrep -v 'directory' | less
Make sure you protect the characters used in the fgrep
pattern (the first argument to fgrep
) from expansion or processing by the shell by surrounding the fgrep
pattern (the first argument) by single quotes.
On the old Microsoft DOS command line, commands print internal help by using the /?
command line switch. Under Unix, you can try giving an argument of --help
or -help
, or -h
. Not all commands have internal help.
Be careful not to try unknown options such as -h
on commands that might have serious side-effects – the -h
might do things you don’t want it to do. Check the man page for what -h
means before trying it with a command.
SYNOPSIS
Line(s)IndexTo understand how to read the syntax of the SYNOPSIS section of a manual page, see the following conventions lines in the DESCRIPTION section of the man page for the man
command. Using man man
you can learn what conventions apply to the SYNOPSIS section. (You can search for following conventions
in the man page.)
Answer these questions about the SYNOPSIS section of a man page:
[]
around something mean?|
(SHIFT-\
) mean?...
mean?Use the above answers to do this exercise:
Given this small excerpt from the SYNOPSIS section of man man
:
SYNOPSIS
man -K [-w|-W] [-S list] [-i|-I] [--
regex] [section] term …
Which of these command lines has valid syntax, based on the above SYNOPSIS?
man foo
man 3 foo
man -K foo
man -K -w -W foo
man -K -w foo
man -K -W foo
man -K -S foo
man -K -S 1,2,3 foo
man -K -i -I foo
man -K -W -i foo
man -K --regex foo
man -K --regex 3 foo
man -K -w -I --regex 3 foo
man -K -w -S 1,2,3 -W -i -I --regex 3 foo
Correct answers (valid syntax): 3, 5, 6, 8, 10, 11, 12, 13
All the other command lines are not a valid syntax, given the above SYNOPSIS.