ch01.fm Page 1 Friday, October 22, 1999 12:14 PM

CHAPTER 1 Documentation

Introduction

There are a wide variety of sources for documentation on Linux. The quality of the information provided ranges from nearly poetic in its eloquence and usefulness all the way down to misleading or even blatantly wrong. Caveat emptor.

Most commercial packages provide a variety of FAQ’s and HOWTO’s in addition to the standard online documentation (man, info, ...). These are generally centered around some non- trivial task (e.g., running X-Windows, communicating with the lesser operating systems).

Usenet has dozens, if not hundreds, of newsgroups devoted to the various facets of Linux. Be advised that they are usually segre- gated according to level of expertise and the locals can be grumpy about inappropriate newbie questions—you should (as always) read the FAQ (frequently asked questions) before posting.

Similarly diverse information can be found on the Web. Proba- bly the best site is http://metalab.unc.edu/LDP, the official Linux Documentation Project Web site.

Because Linux is a variation of the Unix operating system, the published Unix references will, for the most part, apply to Linux as well. Also, as Linux gains popularity, more Linux-specific periodi- cals are available at bookstores.

1

ch01.fm Page 2 Friday, October 22, 1999 12:14 PM

2 Chapter 1 • Documentation

Of course, your first source of information should be your own machine. Most questions can be answered by a careful reading of the docu- mentation. The commands covered in this section tell you how to use the resources on your machine to answer questions. They include: apropos Search the whatis database. info Provide hypertext documentation. locate Search for a file in the locate database. man Access on-line manual pages. makewhatis Create the whatis database. manpath Specify the search path for the man command. updatedb Update the locate database. whatis Search the whatis database for information. whereis Locate source files and documentation.

Related Files /etc/man.config Default man.conf file. /usr/sbin/makewhatis Create the whatis database.

Commands

apropos keyword Search the whatis database for keyword. Provides terse but thorough docu- mentation. Good place to start looking if you’re clueless. You must run makewhatis before using. Example: To retrieve information on the various files and executables dealing with passwords: apropos passwd

info options keyword Info is a hypertext reader which searches and displays online documenta- tion about the specified keyword.

ch01.fm Page 3 Friday, October 22, 1999 12:14 PM

Commands 3

Example: To look up information on the cd command: info cd Example: To look up information on the grep command and store it in output file grep.doc: info -o grep.doc grep

--directory Look for info files in the specified directories. DIRECTORY-PATH, -d DIRECTORY-PATH

--file FILENAME, Search the specified filename for information about -f FILENAME keyword.

--node NODENAME, Force display of the specified info node. -n NODENAME

--output FILENAME, Direct all output to FILENAME rather than standard -o FILENAME output.

--subnodes Recursively output the nodes appearing in the menu of each node being output.

--help, -h Output a description of the available options for info.

--version Display the version information.

locate [-d path] [--database=path][--version][--help] pattern Search the locate database for pattern. This command serves some of the same purposes as find, but it is quicker and not as thorough. Note that in order for this command to work, the updatedb command must first be run. If you get in the habit of using locate, you probably ought to put a line in your crontab to run updatedb every night; other- wise, your information will get out of date quickly. Example: To get locate to search its database for HOWTO files pertaining to XFree86: locate HOWTO | grep XFree86

ch01.fm Page 4 Friday, October 22, 1999 12:14 PM

4 Chapter 1 • Documentation

If the file you’re after was created since the last time updatedb was run, locate won’t find it. Use the find command instead.

-d path, -- Search the specified path instead of the default path. database=path

--version Display the version number.

--help Display help info.

makewhatis options Create the whatis database, an on-line database of commands used by the whatis command. Generally, makewhatis needs to be run only once. Example: To update the whatis database after you’ve installed a new batch of man pages: makewhatis -w

-u Update database with new man pages.

-v Operate verbosely.

-w Use manpath obtained from man --path.

man [-acdfhkKtwW] [-m system] [-p string] [-C config_file] [-M path] [-P pager] [-S section_list] [section] name ... Format and display on-line manual pages. Manual pages are prepared doc- uments associated with a particular command. They describe the command syntax, the usage, the associated files, and occasionally provide usage exam- ples. The following environment variables apply: MANPATH Specify the path to be searched for man pages. MANROFFSEQ Determine the set of preprocessors run before nroff or troff. MANSECT Specify which sections of the manual to search (if set at all). MANWIDTH Specify the width at which man pages are dis- played.

ch01.fm Page 5 Friday, October 22, 1999 12:14 PM

Commands 5

MANPAGER Specify the paging program used to output man pages. LANG Specify the subdirectory where man first looks for entries. Example: To search for the manual page for the ls command: man ls Example: To search for all manual pages (not just the first one) on the mke2fs command and display using the less pager: man -a -P less mke2fs

-C config_file Specify the configuration file used by man. Default is /etc/ man.conf.

-M path Specify the list of directories to search for man pages.

-P pager Specify which program is used to present the output to the user. Default is /usr/bin/less-is.

-S section_list Specify a list of man sections to search (list delimited by colons).

-a Force man to display all man pages matching the name argu- ment, not just the first.

-c Force man to reformat the source page, regardless of whether an up-to-date cat page exists.

-d Print debugging information instead of actual man pages.

-D Display and print debugging information.

-f Force man to behave as if it were the whatis program.

-h Print a succinct help message.

-k Force man to behave as if it were the apropos program.

-K Force man to search for the specified string in all man pages. Painfully slow.

-m system Specify an alternate set of man pages to search based on the system name given.

ch01.fm Page 6 Friday, October 22, 1999 12:14 PM

6 Chapter 1 • Documentation

-p string String is a sequence of preprocessors to be run before nroff or troff.

-t Use /usr/bin/groff -Tps-mandoc to format the man page.

-w or --path Instead of the man page, print the path of the man page that would be displayed.

-W Like -w (above) but only prints file names one per line.

updatedb [options] Update the file database used by locate. Example: To update the database used by locate: updatedb If you use locate, you should run this command nightly via cron.

--localpaths='path1 path2...' Non-network directories to put in the data- base.

--netpaths='path1 path2...' Network (NFS, AFS, RFS, etc.) directories to put in the database. Default is none.

--prunepaths='path1 path2...' Directories to not put in the database, which would otherwise be. Default is /tmp / usr/tmp /var/tmp /afs.

--output=dbfile The database file to build. Default is sys- tem-dependent, but typically /usr/local/var/ locatedb.

--netuser=user The user to search network directories as, using su(1). Default is daemon.

--old-format Create the database in the old format instead of the new one.

--version Print the version number of updatedb and exit.

--help Print a summary of the options to updatedb and exit. ch01.fm Page 7 Friday, October 22, 1999 12:14 PM

Commands 7

whatis keyword ... Search the whatis database for keyword. The whatis database contains short descriptions of system commands. Note that in order to be usable, you must first run the /usr/sbin/makewhatis command. Example: To get a brief description of the cron command: whatis cron

whereis [ -bmsu ] [ -BMS directory... -f ] filename ... Locate source files and applicable manual sections for the specified files. Example: To search for source files and manual selections for the /etc/hosts file: whereis /etc/hosts

-b Search for binary files only.

-m Search the manual pages only.

-s Search for source files only.

-u Search for unusual entries. An unusual entry is a file in the current directory which has neither a binary, a man page, nor a source file associated with it.

-B Specify where to look for binaries.

-M Specify where to look for man pages.

-S Specify where to look for source files.

-f Used as a delimiter on the command line. Indicates that the directory list has ended and the file list is about to begin. ch01.fm Page 8 Friday, October 22, 1999 12:14 PM

8 Chapter 1 • Documentation