1 The Unix manual pages (RTFM)Index

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.

2 Displaying manual pages using lessIndex

When 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, the man command uses more in place of less. The more and less commands are more-or-less the same, with less 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.

3 Searching for text within a manual pageIndex

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.

4 Using the man command – man man and man introIndex

You 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:

• The shell
• Pathnames and the current directory
• Directories
• Getting information

   $ man mkdir

5 Some basic “coreutils” man pages are incompleteIndex

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/

6 The Manual has sectionsIndex

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.):

• Section 1 – user commands e.g. date, who, ls
• Section 8 – super-user and admin commands e.g. useradd, ifconfig
• Section 2 – kernel system calls e.g. read(), write()
• Section 3 – library function calls e.g. fread(), fwrite()
• Section 4 – special and device files e.g. null, fifo, zero, hd
• Section 5 – file formats e.g. 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

7 Searching for manual pages: man -k and aproposIndex

Sometimes 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.

   $ man -k name | fgrep '(1)' | less

   $ man -k name | fgrep -v '(1)' | less

   $ man -k name | fgrep '(1)' | fgrep -v 'directory' | less

   $ apropos name | fgrep '(1)' | fgrep -v 'directory' | less

8 Some commands have internal help as well as man pagesIndex

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.

9 Reading manual pages SYNOPSIS Line(s)Index

To 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:

1. What does bold text mean?
2. What does italic (underlined, on terminals) text mean?
3. What do square brackets [] around something mean?
4. What does the pipe or OR-bar symbol | (SHIFT-\) mean?
5. What do three dots (ellipsis) ... mean?

Use the above answers to do this exercise:

10 Comic: XKCD on “man pages”Index

Author: 
| Ian! D. Allen, BA, MMath  -  idallen@idallen.ca  -  Ottawa, Ontario, Canada
| Home Page: http://idallen.com/   Contact Improv: http://contactimprov.ca/
| College professor (Free/Libre GNU+Linux) at: http://teaching.idallen.com/
| Defend digital freedom:  http://eff.org/  and have fun:  http://fools.ca/