Searching for items in the Unix manual pages (RTFM)

Ian! D. Allen – www.idallen.com

Fall 2012 - September to December 2012 - Updated 2018-10-04 17:44 EDT

1 The Unix manual pages (RTFM)Indexup to 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 lessIndexup to index

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 pageIndexup to index

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 introIndexup to index

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:

4.1 Looking up options to commandsIndexup to index

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.

5 Some basic “coreutils” man pages are incompleteIndexup to index

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 sectionsIndexup to index

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

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 aproposIndexup to index

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.

7.1 Using fgrep to filter search resultsIndexup to index

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 the grep -F command and option; it runs grep using fixed strings (not patterns) as the search strings. Until you know how to use grep patterns, always use fgrep.

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.

8 Some commands have internal help as well as man pagesIndexup to index

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)Indexup to 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:

9.1 Exercise: reading the SYNOPSIS sectionIndexup to index

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?

  1. man foo
  2. man 3 foo
  3. man -K foo
  4. man -K -w -W foo
  5. man -K -w foo
  6. man -K -W foo
  7. man -K -S foo
  8. man -K -S 1,2,3 foo
  9. man -K -i -I foo
  10. man -K -W -i foo
  11. man -K --regex foo
  12. man -K --regex 3 foo
  13. man -K -w -I --regex 3 foo
  14. 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.

10 Comic: XKCD on “man pages”Indexup to index

XKCD man page
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/

Plain Text - plain text version of this page in Pandoc Markdown format

Campaign for non-browser-specific HTML   Valid XHTML 1.0 Transitional   Valid CSS!   Creative Commons by nc sa 3.0   Hacker Ideals Emblem   Author Ian! D. Allen