Locating Information in Man Pages

You can search for information about Oracle Solaris commands in man pages by using the man command. The new -K (uppercase) keywords option enables you search all sections of all of the man pages for the specified keywords. The -k option (lowercase) is limited to searching just the NAME subsection of all of the man page sections.

Creating Index Files to Enable the Searching of Man Pages for Specific Keywords

To search for information in man pages by specifying keywords, start by creating index files that can be queried by the man command. You can use the catman utility to create preformatted versions of the online reference manual. When used without any options, the catman utility generates index files of the man pages that are in the /usr/share/man and usr/gnu/share/man directories. Note that you must be the root user to use the catman utility.

The catman utility also includes a -w option. This option enables you to create an index file of man pages in the directories that are specified by the MANPATH variable or when the -M option is used. You can use the -M option of the catman utility to specify an alternate directory to create an index file of third-party man pages. By default, when used without any options, the catman utility creates an index file of the man pages that are located in the /usr/share/man and /usr/gnu/share/man directories.

To specify an alternate directory, type the following command:

# catman -M directory -w

For example, to create an index file for man pages that are located in the /usr/local/share/man directory, you would type the following command:

# catman -M /usr/local/share/man -w

-M directory

Updates the man pages that are located in the specified directory, which is /usr/share/man by default. If the -M option is specified, the directory argument must not contain a comma (,) because a comma is used to delineate section numbers in man pages.

-w

Creates an index file in the directories that are specified by the MANPATH variable or with the -M option. If the MANPATH variable or the -M option is not specified, index files are created for the both the /usr/share/man/ and /usr/gnu/share/man directories.

For a complete description of the catman utility, including all of the command-line options that you can specify, see the catman(1M) man page.

Searching for Information in Man Pages by Specifying Keywords

To search for information in man pages by specifying keywords, create an index file, or files, by using the catman utility. For instructions, see Creating Index Files to Enable the Searching of Man Pages for Specific Keywords.

To conduct a full-text search for information in all of the man page sections by specifying keywords, type the man command with the new -K keywords option, as follows:

$ man -K keywords

-K

Conducts a full-text search of the specified keywords throughout all of the man page sections.

keywords

Is a user-defined string that is specified. To specify multiple keywords in single search, use double quotation marks. For example:

$ man -K "create zfs pool"

To search for information in just the NAME subsection of all of the man pages, type the man command with the -k keywords option, as follows:

$ man -k keywords

To search for information in a specific subsection of all of the man pages, include the SECTNAME in the man -K keywords command syntax, as follows:

$ man -K SECTNAME:keywords

where SECTNAME can be any of the following subsections in all of the man page sections:

• ATTRIBUTES

• DESCRIPTION

• ENVIRONMENT VARIABLES

• EXAMPLES

• EXIT STATUS

• FILES

• LIST OF COMMANDS

• NAME

• NOTES

• NULL

• OPTIONS

• OPERANDS

• OUTPUT

• SECURITY

• SEE ALSO

• SYNOPSIS

• USAGE

To search a specific man page section, use the -s option with the man command and the -k or -K option.

$ man -s manpage-section -K "keywords"

For example, to search for the keywords “cpu usage” in the 1M man page section, you would type the following command:

$ man -s 1m -K "cpu usage"

Note the following additional key information about the man command:

• The command syntax that is used for searching man pages by using the man command with either the -k or -K option is not case-sensitive.

• The man command normalizes keywords before conducting a search, which means a query for a specified keyword also generates results for all words that include part of that word. For example, if you query the word “searching,” the words “search,” “searches,” and “searched,” are also included in the search results.

Example 1-1 Searching for Commands in the NAME Subsection of All Man Pages by Specifying Keywords

In the following example, the man -k command is used to search for instances of the init command in the NAME section of all man pages only:

$ man -k init
Searching in: /usr/man
Searching in: /usr/dt/man
Searching in: /usr/openwin/share/man
Searching in: /usr/sfw/man

1. init(1m)     "NAME"  /usr/share/man/man1m/init.1m
init, telinit - process control initialization


2. inittab(4)   "NAME"  /usr/share/man/man4/inittab.4
inittab - script for init


3. init.d(4)    "NAME"  /usr/share/man/man4/init.d.4
init.d - initialization and termination scripts for changing init states

In this example, the output of the man -k command displays the search results for the init command in the NAME subsection of all man page sections only. Note that any man page that contains init in its name is also included in the search results.

Example 1-2 Searching for Commands in All Man Page Sections by Specifying Keywords

In the following example, the man -K keywords command is used to search for instances of the dumpadm command in all of the sections of the man pages.

$ man -K dumpadm
Searching in: /usr/man
Searching in: /usr/dt/man
Searching in: /usr/openwin/share/man
Searching in: /usr/sfw/man

1. dumpadm(1m)  NAME    /usr/share/man/man1m/dumpadm.1m
dumpadm - configure operating system crash dump


2. savecore(1m) DESCRIPTION     /usr/share/man/man1m/savecore.1m
The savecore utility saves a crash dump of the kernel (assuming that one
was made) and writes a reboot message in the shutdown log. It is invoked
by the dumpadm service each time the system boots.


3. svccfg(1m)   EXAMPLES        /usr/sh

In this example, the search returns three instances of the dumpadm command in the man pages:

• The first instance was found in the NAME subsection of the dumpadm(1M) man page.

• The second instance was found in the DESCRIPTION subsection of the savecore(1M) man page.

• The third instance was found in the EXAMPLES subsection of the svccfg(1M) man page.

Based on the results of this query, the user knows where additional information about the dumpadm command can be found in all of the man pages.

Example 1-3 Searching for Commands in Specific Man Page Subsections by Specifying Keywords

In the following example, the man -K command is used with the SECTNAME:keywords argument to search for instances of the bootadm command in the DESCRIPTION subsection of all of the man page sections.

$ man -K description:bootadm
Searching in: /usr/man
Searching in: /usr/dt/man
Searching in: /usr/openwin/share/man
Searching in: /usr/sfw/man

1. bootadm(1m)  DESCRIPTION     /usr/share/man/man1m/bootadm.1m
The bootadm command manages the boot archive and, with x86 boot environments,
the GRUB (GRand Unified Bootloader) menu. The update-archive option
provides a way for user to update the boot archive as a preventative
measure or as part of a


2. boot(1m)     DESCRIPTION     /usr/share/man/man1m/boot.1m
# bootadm update-archive

In this example, the search returns two instances of the bootadm command in the DESCRIPTION subsection of the following man page sections:

• The first instance was found in the bootadm(1M) man page.

• The second instance was found in the boot(1M) man page.

For more information about using the man command, see the man(1) man page.