Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > M

man(1)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

man — find manpage information by keywords; print out a manpage

SYNOPSIS

man [-M path] -k keyword...

man [-M path] -f file...

man [-] [-M path] [-T macro-package] [section[subsection]] entry_name...

DESCRIPTION

man accesses information from the HP-UX manpages. It can be used to:

  • List all manpages whose one-line description contains any of a specified set of keywords.

  • Display or print one-line descriptions of manpages specified by name.

  • Search on-line manpage directories by manpage name and display or print the specified manpages.

  • Search a specified on-line manpage section (directory) and display or print the specified manpages in that section.

Searching for Entry Names by Keyword (first form)

The first form above searches the one-line descriptions of individual manpages for specified keywords. Arguments are as follows:

-k keyword

-k followed by one or more keywords causes man to print the one-line description of each manpage whose one-line description contains text matching one or more of the specified keywords (similar to the behavior of grep(1)). Keywords are separated by blanks (space or tab).

Before this option can be used, file /usr/share/lib/whatis must exist. /usr/share/lib/whatis can be created by running catman(1M).

Obtaining One-Line Description of an Entry (second form)

The second form above finds and displays or prints the one-line descriptions of specified individual manpages. Arguments are as follows:

-f file

-f followed by one or more file names causes man to print the one-line description of each manpage found whose name matches file. When specifying two or more files, file arguments are separated by blanks (space or tab). If manpage names matching file exist in two or more sections, the one-line description of each matched file name is output.

Before this option can be used, file /usr/share/lib/whatis must exist. /usr/share/lib/whatis can be created by running catman(1M).

Viewing Individual Manpages (third form)

The third form shown above is used for viewing one or more individual manpages. man in this form recognizes the following arguments:

-

(optional) When the - argument is present, man sends the formatted manpage directly to standard output without processing it through the output filter specified by the PAGER environment variable.

-M path

Change the search path for manpages. path is a colon-separated list of directories that contain manpage directory subtrees. When used with the -k or -f options, the -M option must appear first.

-T macro-package

man uses macro-package rather than the standard -man macros defined in /usr/share/lib/tmac/tmac.an for formatting manpages.

When specifying the -T option to man , the full path must be given. For example:

man -T /usr/share/lib/tmac/tmac.s ls

section[subsection]

(optional) Search in the specified section for the given entry_name. section specifies a single section number or one of the words local, new, old, or public to search for one or more of the entries indicated. section corresponds to the section number where the manpage appears in the HP-UX Reference. It can be followed by an optional uppercase/lowercase subsection identifier such as 3C which would indicate a library routine in Section 3. 3, 3c, and 3C are interpreted as equivalent, since all Section 3 manpages are stored in the same or in related directories (such as /usr/share/man/man3.Z and /usr/share/man/man3. However, if a manpage is in Section 1M, section must be specified as 1m or 1M.

entry_name

Search for a specific manpage where entry_name is the name of the manpage without its section-number suffix. Except for names exceeding 11 characters, entry_name is identical to the name of the manpage as listed at the top of each page, or is the same as one of the keywords in the left-hand part of the one-line description in the corresponding manpage.

If entry_name is longer than 11 characters, man first searches for the full-length entry_name. If not found, entry_name is truncated to 11 characters to ensure that there is room for the section suffix in 14-character source file names. Files in the /usr/share/man/* directories are normally installed with the filename truncated to 11 characters where necessary so that the name plus a three-character section suffix does not exceed the maximum filename length on short filename systems.

If section is not specified (see previous argument description), man searches all manpage sections in order: man1, man2, man1M, man3, man4, man5, man6, man7, man8, man9, manlocal, mannew, manold, then manpublic; it prints the first matching manpage it encounters.

If there is more than one manpage among the sections, the first manpage is displayed. For example, man intro will display only intro(1). man 4 intro will display intro(4).

If the standard output is a teletype, and if the - flag is not given, man pipes its output through more (see more(1)), with the -s option, to eliminate multiple blank lines and stop after each screenful. This default behavior can be changed by setting the PAGER variable in the user's environment. The value of PAGER must be a string that names an output filter (such as pg(1)), along with the desired options.

File Search Conventions

man searches in several directories, as appropriate, for the specified manpage. The search continues until either the manpage is found or all candidate directories are searched. The first three directories searched, in order, are: /usr/share/man, /usr/contrib/man, and /usr/local/man.

The MANPATH environment variable can be used to specify directories to be searched, and, if set, overrides the default paths given above. Upon logging in, /etc/profile ( or /etc/csh.login ) sets the MANPATH environment variable to default settings. If the file /etc/MANPATH exists, the default settings are taken from this file. The MANPATH variable follows the same form as the PATH variable (see environ(5)).

Within each of these directories, man searches in the cat*.Z subdirectories, the man*.Z subdirectories, the cat* subdirectories, and the man* subdirectories. man*.Z and man* directories contain nroff(1)-compatible source text for the manpages. cat*.Z and cat* directories contain the formatted versions of the manpages. man*.Z and cat.Z directories contain manpages in compressed form. Files in these directories are uncompressed by uncompress (see compress(1)) before being processed for printing or display.

If the LANG environment variable is set to any valid language name defined by lang(5), and the MANPATH variable is not set, or is set to the default directories, man searches in three additional directories for the manpage before searching in /usr/share/man. First, man searches in /usr/share/man/$LANG, then in /usr/contrib/man/$LANG, then in /usr/local/man/$LANG. Thus, native-language manpages are displayed if they are present and installed properly in the system.

If the MANPATH environment variable is set to anything other than the default, the above directories with $LANG as part of the path are not automatically searched. All directories must be explicitly given in MANPATH. The %L, %l, %t, and %c specifiers can be used as path components to cause locale-specific directories to be searched. See environ(5) for a complete description of MANPATH.

man uses the most recent version that it finds in the subdirectories searched. If the most recent version is in:

man*.Z

The manpage is uncompressed, formatted, and displayed. If the cat*.Z directory exists, the formatted manpage is compressed and installed in cat*.Z. If the cat* directory exists, the formatted manpage is installed in cat*.

cat*.Z

The manpage is uncompressed and displayed.

man*

The manpage is formatted, and displayed. If the cat*.Z directory exists, it is compressed, and installed in cat*.Z. If the cat* directory exists, the formatted manpage is installed in cat*.

cat*

The manpage is displayed.

If only the cat* or cat*.Z subdirectory is present and/or nroff(1) is not installed, only manpages that are already formatted can be displayed.

To improve man performance, you can run the catman(1M) command to create the formatted manpages in the cat* directories. Running catman with the default creates the cat*.Z directories (after removing any cat* directories that exist on your system) and also creates the file /usr/share/lib/whatis used by the man -k option. If you choose to have the cat* directories, it would be space-saving to remove any cat*.Z directories that may exist on your system. Beware that man updates both directories (cat* and cat*.Z) if they both exist.

Special Manpages

Some situations may require creation of manpages for local use or distribution by third-party software suppliers. The manpage formatting macros have been structured to redefine page footers so that manpages not originating from Hewlett-Packard Company do not show the HP name in the footer. For more information about this change and a description of the manpage formatting macros used with nroff or troff, see man(5).

EXTERNAL INFLUENCES

Environment Variables

LANG determines the language in which messages are displayed. LANG is also used to determine the search path (as described above).

If LANG is not specified or is set to the empty string, a default of "C" (see lang(5)) is used instead of LANG for messages, but not for the search path.

If any internationalization variable contains an invalid setting, man behaves as if all internationalization variables are set to "C". See environ(5).

MANPATH, if set, gives a list of directories to be searched for the given manpage, replacing the default paths.

PAGER, if set, defines an output filter to be used instead of more(1) to paginate output.

International Code Set Support

Single- and multibyte character code sets are supported.

EXAMPLES

List the manpages that contain the word grep in their respective one-line description (NAME) lines:

man -k grep

The output is:

grep, egrep, fgrep (1) - search a file for a pattern zgrep(1) - search possibly compressed files for a regular expression

Print the one-line description of the grep(1) manpage:

man -f grep

Print the entire grep(1) manpage:

man grep

Set a search path that includes a path directly below the current directory. The manpage, mypage is assumed to exist in the directory ./man1 (or ./man1.Z, cat1, or cat1.Z).

MANPATH=.:/usr/share/man:/usr/contrib/man:/usr/local/man export MANPATH man mypage

Display the manpage for id(1), with the output piped through pg -c:

PAGER="pg -c" export PAGER man id

Display intro(4) and intro(7):

man 4 intro man 7 intro

WARNINGS

Manpages are structured such that they can be printed on a phototypesetter, conventional line printer, and screen display devices. However, due to line printer and display device limitations, some information may be lost in certain situations.

FILES

/usr/share/lib/whatis

keyword database

/usr/share/man/cat*[.Z]/*

formatted manpages [compressed]

/usr/share/man/man*[.Z]/*

raw ( nroff(1)) source) manpages [compressed]

/usr/contrib/man/cat*[.Z]/*

/usr/contrib/man/man*[.Z]/*

/usr/local/man/cat*[.Z]/*

/usr/local/man/man*[.Z]/*

/usr/share/man/$LANG/cat*[.Z]/*

formatted native-language manpages [compressed]

/usr/share/man/$LANG/man*[.Z]/*

raw ( nroff(1)) source) native-language manpages [compressed]

/usr/contrib/man/$LANG/cat*[.Z]/*

/usr/contrib/man/$LANG/man*[.Z]/*

/usr/local/man/$LANG/cat*[.Z]/*

/usr/local/man/$LANG/man*[.Z]/*

STANDARDS CONFORMANCE

man: XPG4

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.