Linux Cookbook

Introduction

Documentation for Linux programs is abundant. Finding it can be a bit challenging, though. You’re not going to find lots of sleek, glossy printed manuals, because most Linux software is distributed online, rather than in shiny boxed sets.

There’s another difficulty, too: Linux follows the grand Unix tradition of small, specialized programs working cooperatively, so any Linux distribution contains a large number of individual programs. For example, Tom’s Root Boot, “The most GNU/Linux on one floppy disk,” contains over 230 separate, individual programs on a single 3.5” diskette. A general-purpose distribution such as Mandrake or SuSE contains several thousand programs and there are over 12,000 packages in the Debian repositories. While organizing and maintaining a printed library presents some difficulties, the good news is that all of these things are documented. Whatever you want to know, there is a way to find it.

man and info: The Universal Linux Manuals

Almost every program written for Linux has a man page. They’re usually not the best teaching tool for newbies. Their purpose is to document the command syntax and every command option, and to be universally available. No matter what kind of strange desert-island scenario you may find yourself in, there will always be man pages. And because man pages are incorporated into the programs to which they belong, you’ll find that only installed programs have man pages and that the versions of those pages are pertinent to your system.

info pages tend to be more verbose than man pages and are hyperlinked. The hyperlinks navigate to the various nodes, or chapters, inside the document and to cross-references in other info pages. Many info pages are simply reformatted man pages. But in some instances—primarily the GNU project programs—the info pages are more detailed, containing tutorials and extensive examples.

Graphical Viewers

There are several good graphical man and info page viewers:

Konqueror: The web and file browser in KDE also contains an excellent man and info page viewer. Simply type man:foo or info:/foo in the address bar. It is easy to print from Konqueror, and easy to select individual man or info pages for printing.
Yelp: The Gnome viewer. Displays man and info pages, and Gnome’s help documents. It is indexed and searchable.
Pinfo: A nice ncurses-based info and man viewer for the console. Users can add new documents to it, and it supports regexp searches.

1.2. Understanding man Pages

Problem

You’re trying to use some programs (for example, everyone’s favorite, grep; the name tells you so much) and you can’t make them do what you want. So, heeding the standard “RTFM” (read the fine man page) advice, you dig up the relevant man pages. But they don’t make a lot of sense—now what?

Solution

Learn how man pages are organized, and familiarize yourself with their conventions for teaching command syntax and options, and you’ll find that man pages really are helpful.

Discussion

Linux sees all the man pages on a system as part of a single manual. This manual is divided into sections:

1 Executable programs or shell commands

2 System calls

3 Library calls

4 Special files (usually found in /dev)

5 File formats and conventions

6 Games

7 Miscellaneous

8 System administration commands

9 Nonstandard kernel routines

n New documentation, which may be moved later

l Local documentation, specific to your system

Each individual program, utility, or function has its own page in this manual, like a page in a book. Finding the man page for a program or command is usually as easy as typing man foo, where foo is the name of the program.

You’ve probably seen references to numbered man pages, like grep(1). This is referring to man grep in section 1. Call it up this way:

               $ man 1 grep

Some man pages are in more than one section. man foo will only display the first one. You can list all of them with the -f switch:

               $ man -f man
man (1)   an interface to the online reference manuals
man (7)   macros to format man pages

Each man page is divided into sections. The section names vary, but you’ll usually see these: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, EXAMPLES, SEE ALSO, BUGS, and AUTHOR.

Here’s the notation used to show command syntax, found in the Synopsis of the man pages:

command-name [optional flags] any-other-required-elements

Command flags are shown this way:

bold text: Type this exactly as it is shown.
italic text: Italic text indicates an argument, which means you replace it with your desired value. Depending on the viewer you are using, you may not see italics, but rather underlines or bold text.
[-abc]: Everything inside square brackets is optional and can be combined.
[-a|-b|-c]: Options separated by the pipe | (Shift-backslash) cannot be combined.
argument...: The ellipsis indicates that several arguments can be listed. Watch out for delimiters—usually they are spaces, but sometimes commas are used.
[expression] ...: The ellipsis indicates that several expressions can be listed.

Short options can be typed two ways:

-abc

or:

-a -b -c

Long options must be individually hyphenated, and they use double hyphens:

--option1 --option2 --option3

Long options are especially useful in scripts, so you can remember what the script does.

The bulk of most man pages is a list of the options available.

1.3. Finding Appropriate man Pages

Problem

You need a program or utility to perform a specific function—for example, counting the words in a file—but you don’t know what to look for. If you knew what you were looking for, you wouldn’t need to look for it, right? How do you get out of this dilemma?

Solution

Do keyword searches with apropos or man -k. For example, if you want a command to count the words in a file, use:

               $ apropos count words

or:

               $ man -k count words
american-english (5) - a list of english words
grpconv (8)          - convert to and from shadow passwords and groups.
grpunconv (8)        - convert to and from shadow passwords and groups.
kmessedwords (1)     - a letter order game for KDE
lppasswd (1)         - add, change, or delete digest passwords.
pwconv (8)           - convert to and from shadow passwords and groups.
pwunconv (8)         - convert to and from shadow passwords and groups.
shadowconfig (8)     - toggle shadow passwords on and off
wc (1)               - print the number of newlines, words, and bytes in files

It doesn’t matter which you use; apropos and man -k are the same. There are a lot of options, but wc looks like the program you want.

Remember the -f switch, to find all versions of a man page:

               $ man -f manpath
manpath (1)      - determine search path for manual pages
manpath (5)      - format of the /etc/manpath.config file

Discussion

These commands perform keyword searches in the NAME sections of the man pages. You can use any number of search terms, but the more you use, the more results you’ll get, because they search each keyword in sequence.

Because these are literal keyword searches, broad concepts like “bandwidth shaping” or “user management” do not carry the same meaning for apropos and man -k; they see “bandwidth shaping” as two unrelated search terms, so single-word searches usually work best.

1.4. Finding Lost man Pages

Problem

You can’t find a man page for an installed program, and you’re certain it should be on the system.

Solution

Sometimes the man database gets corrupted, users make strange modifications, or programs install man pages incorrectly. First try searching with whereis -m :

               $ whereis -m cat
               cat:/usr/man/man1/cat.1.gz /usr/share/man/man1/cat.1.gz

Now you’ve found the page. Read it with man:

               $ man /usr/man/man1/cat.1.gz

If that doesn’t work, try rebuilding the man database with mandb:

               # mandb

If that doesn’t work, try a system-wide search with locate and egrep:

               $ locate / cat. | egrep -w 'cat\.[1-9][a-zA-Z]*[.gz]?'

This works for any man page—simply replace cat with whatever you’re looking for.

If none of these approaches turn up the man page you are looking for, try the finddoc script in Recipe 1.11. If this doesn’t find it, it’s not on your system.

Discussion

There are all kinds of man page repositories on the Web, so you can always try a Google search. However, some programs simply don’t have man pages, so don’t ruin your health searching for one that may not exist.

1.5. Reading man Pages Without a man Viewer

Problem

You’re working on a system that is seriously messed up, and you can’t read man pages because the man viewer doesn’t work.

Solution

Try reading the raw man page with zcat and nroff:

               $ zcat /usr/man/man1/cat.1.gz | nroff -man | less

As a last resort, read the raw page code with zless :

               $ zless /usr/man/man1/cat.1.gz
.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.32.
.TH CAT "1" "July 2003" "cat (coreutils) 5.0" "User Commands"
.SH NAME
cat \- concatenate files and print on the standard output
.SH SYNOPSIS
.B cat
[\fIOPTION\fR] [\fIFILE\fR]...

It’s not pretty, but it works.

Discussion

nroff is a wrapper for groff , for formatting man pages. groff is a document-formatting, or typesetting, program. It enables you to create many differently formatted documents from a single source file: HTML, .pdf, printed hard copies, info pages, and many more. See Chapter 9 of Running Linux for a good introduction.

1.6. Configuring Your manpath

Problem

You’re repeatedly having trouble finding man pages; using tools from Recipe 1.4, you find that most of the missing pages are in a directory that man doesn’t seem to know about. Perhaps a newly-installed program put its man pages in a strange place, like /opt/man. Or perhaps you want to put some man pages in a nonstandard location. How do you configure man to find them?

Solution

Edit /etc/manpath.config.

Suppose the directory you want to add is /opt/man. Add /opt/man to /etc/manpath.config:

# every automatically generated MANPATH includes
# these fields
   
MANDATORY_MANPATH                   /usr/man
MANDATORY_MANPATH                   /usr/share/man
MANDATORY_MANPATH                   /usr/X11R6/man
MANDATORY_MANPATH                   /usr/local/man
MANDATORY_MANPATH                   /opt/man

And you’re done. Now man will find the man pages in the new directory.

When you create a custom man page directory, be sure to include the section directories:

               $ ls /opt/man/local
man1  man2  man3  man4  man5  man6  man7  man8  man9

It’s not necessary to include all the numbered sections, just the ones pertinent to the man pages you’ll be storing there.

If you’re going to have subdirectories—for example, /opt/man and /opt/man/local—be sure to list them in this order:

MANDATORY_MANPATH                   /opt/man/local
MANDATORY_MANPATH                   /opt/man

Subdirectories must be listed before parent directories, or they will be overlooked by the man viewer.

Discussion

You can run manpath with no options to see your current manpaths:

               $ manpath
/usr/local/man:/usr/share/man:/usr/X11R6/man:/usr/man

1.7. Using info Pages

Problem

You decide to give info pages a try, so you call up info tar (or any other info page of your choice). But you find that navigating info tar is confusing and difficult. What is the best way to learn your way around?

Solution

Use info’s built-in tutorial. Type info at any command line, hit the letter h, then do what it says. It should take 15-30 minutes, and it is time well-spent.

Discussion

Even though some folks think that info pages are unnecessarily complicated to navigate, it is worth getting acquainted with them. Even though they are more difficult to navigate than man pages, they are (usually) easier to understand. Once you get the hang of moving around in them, you can go very fast and find information quickly. Info pages often contain more information than man pages, and they sometimes include tutorials and extensive examples.

There are also a number of nice info viewers, such as pinfo, Konqueror, and Yelp. Pinfo runs in the console, and Konqueror and Yelp need X. Konqueror is especially easy to navigate and to use for printing selected pages.

1.8. Printing man Pages

Problem

You want to print a man page, nicely formatted and readable. You have tried man foo | lpr, but it doesn’t look very good. The margins are too small, and all the formatting is lost.

Solution

One way to print a nicely formatted man page is to use the -t flag, which formats it especially for printing. man finger is good for practice, because it’s only two pages long:

               $ man -t finger | lpr

To use a networked printer:

               $ man -t finger | lpr -P printername

To see your available printers:

               $ lpstat -p -d

Another option is to use the following command, which formats the page in HTML and sends it to the web browser of your choice:

               $ man -Hmozilla finger

Then use the browser’s print command. Be sure there is no space between -H and the browser name.

Discussion

All of the major Linux distributions ship with CUPS, the Common Unix Printing System. CUPS supports both the System V (lp) and Berkeley (lpr) commands. This recipe uses the Berkeley commands. Here is the System V equivalent.

               $ man -t finger | lp

To use a networked printer:

               $ man -t finger | lp -d printername

1.9. Printing info Pages

Problem

You want to print some info pages, but there doesn’t seem to be a built-in print command for info.

Solution

You can use lpr :

               $ info finger | lpr

However, this may result in too-small margins and odd line breaks, depending on your printer defaults. Use lpr options to format it:

               $ info finger | lpr -o cpi=12 -o page-left=54 -o page-right=54 -o page-top=54 \
               -o page-bottom=54

The numbered values are points, or 1/72”. This example creates 3/4” margins all the way around. cpi=12 sets the number of characters to 12 per inch. All of these options are documented in the CUPS Software Users Manual, at http://localhost:631/documentation.html.

Discussion

All of the major Linux distributions ship with CUPS, the Common Unix Printing System. CUPS supports both the System V (lp) and Berkeley (lpr) commands. This recipe uses the Berkeley commands. Here are the System V equivalents.

To print an info page use:

               $ info finger | lp

To print the info page using lp's formatting options use:

               $ info finger | lp -o cpi=12 -o page-left=54 -o page-right=54 -o page-top=54 \
               -o page-bottom=54

1.10. Printing Selected man or info Pages

Problem

You would like to print selected man and info pages, because most man and info documents are quite long. For example, man bash consumes 33 printed pages. How can you print pages selectively?

Solution

Export the man or info page to a plain text file, using the col command. Then you can easily select the pages to print. To do this with man bash or info bash use:

               $ man bash | col -b > bash.txt
               $ info bash | col -b > bash.txt

Discussion

If you just type man bash > bash.txt, the results will be unpleasant. col -b cleans things up considerably by removing reverse line feeds, or backspaces. This is especially suited for converting man pages to plain text, because man pages are full of reverse line feeds, which then appear in text files as either empty boxes or repeated characters.

1.11. Finding All of the Documentation for a Program

Problem

You want to find all the relevant readmes, changelogs, howtos, guides, examples, samples, and other documentation that accompanies your installed programs.

Solution

Use finddoc, that wonderful Python script that comes to you courtesy of the excellent Akkana Peck.

You can call it anything you like. Remember to make it executable:

               $ chmod +x finddoc

Using it requires only the script name and the name of the program for which you need the documentation. For example:

               $ ./finddoc grep
/usr/share/doc/grep
/usr/share/doc/grep-dctrl
/usr/share/doc/grep-dctrl/changelog.gz
...

The output can be filtered through other commands, or redirected to a file:

               $ ./finddoc | grep -i examples | lpr
               $ ./finddoc | grep -i faq
               $ ./finddoc | grep -i examples > python-examples.txt

Program: finddoc

#!/usr/bin/env python
   
# Finddoc: A Script For Finding Linux Program Documentation
# When making your own copy of this script, be sure to
# preserve the leading spaces exactly as they are written
# here, because Python needs them. 
   
# Search for documentation related to the given strings;
# case-insensitive, and whole-word only.
# Relies on "locate" and assumes that the locate
# database is current.
#
# Copyright 2003 by Akkana Peck.
# You may use, distribute or modify this program
# under the terms of the GPL.
   
import sys, os, string, re
   
# This is the list of document-related filenames
# to search for. You may edit this list as needed.
# Be sure to add only lowercase names.
docfilenames = [ 
 "changelog", 
 "readme", 
 "install", 
 "howto", 
 "authors", 
 "news", 
 "todo", 
 "config", 
 "sample", 
 "samples", 
 "example", 
 "examples",
 "ref",
 "guide",
 "manual",
 "quickstart",
 "thanks",
 "notes",
 "features",
 "faq",
 "acknowledgement",
 "bugs",
 "problems"
]
   
def system_out (cmdstr) :
 retlist = [  ]
 fp = os.popen(cmdstr)
 while 1:
  s = fp.readline( )
  if not s : break
  retlist.append(s)
 fp.close( )
 return retlist
   
# main( )
for arg in sys.argv :
 #print string.split(arg, " \t./")
   
 files = system_out("locate " + arg + " | grep -w " + arg);
   
 for path in files :
  #print path
   
  # Special case for anything with "man", "doc", or "info" in the path:
  if (string.find(path, "/man") >= 0) \
   or (string.find(path, "/doc") >= 0) \
   or (string.find(path, "/info") >= 0) :
   print path,
)
   continue
   
  # Now see if it matches any of the docfilenames:
  base = os.path.basename(path)
  for nam in docfilenames :
   if base =  = "" : continue
   
   # Non full word search would use this:
:
   
   # Full-word-search:
   # Make a regexp to search for nam as full-word only
   pat = "^" + nam + "$"
   if (re.compile(nam).search(base, 1)) :
    print path,
    base = ""
    continue

Chapter 1. Finding Documentation

Introduction

man and info: The Universal Linux Manuals

Other Documentation

Graphical Viewers

1.2. Understanding man Pages

Problem

Solution

Discussion

See Also

1.3. Finding Appropriate man Pages

Problem

Solution

Discussion

See Also

1.4. Finding Lost man Pages

Problem

Solution

Discussion

See Also

1.5. Reading man Pages Without a man Viewer

Problem

Solution

Discussion

See Also

1.6. Configuring Your manpath

Problem

Solution

Discussion

See Also

1.7. Using info Pages

Problem

Solution

Discussion

See Also

1.8. Printing man Pages

Problem

Solution

Discussion

See Also

1.9. Printing info Pages

Problem

Solution

Discussion

See Also

1.10. Printing Selected man or info Pages

Problem

Solution

Discussion

See Also

1.11. Finding All of the Documentation for a Program

Problem

Solution

Program: finddoc

See Also

Don’t leave empty-handed

It’s yours, free.

Check it out now on O’Reilly