- Display man page for a command:man [command]- Display man page for a command from section 7:man [command].- Display path searched for manpages:man --path- Display location of a manpage rather than the manpage itself:man -w [command]- Do a keyword search for manpages containing a search string:man -k [keyword]
man [-C file] [-d] [-D] [--warnings[=warnings]] [-R encoding] [-L locale] [-m system[,...]] [-M path] [-S list] [-e extension] [-i|-I] [--regex|--wildcard] [--names-only] [-a] [-u] [--no-subpages] [-P pager] [-r prompt] [-7] [-E encoding] [--no-hyphenation] [--no-justification] [-p string] [-t] [-T[device]] [-H[browser]] [-X[dpi]] [-Z] [[section] page[.section] ...] ... man -k [apropos options] regexp ... man -K [-w|-W] [-S list] [-i|-I] [--regex] [section] term ... man -f [whatis options] page ... man -l [-C file] [-d] [-D] [--warnings[=warnings]] [-R encoding] [-L locale] [-P pager] [-r prompt] [-7] [-E encoding] [-p string] [-t] [-T[device]] [-H[browser]] [-X[dpi]] [-Z] file ... man -w|-W [-C file] [-d] [-D] page ... man -c [-C file] [-d] [-D] page ... man [-?V]
man is the system's manual pager. Each page argument given to man is normally the name of a program, utility or function. The manual page associated with each of these arguments is then found and displayed. A section, if provided, will direct man to look only in that section of the manual. The default action is to search in all of the available sections following a pre-defined order ("1 n l 8 3 2 3posix 3pm 3perl 3am 5 4 9 6 7" by default, unless overridden by the SECTION directive in /etc/manpath.config), and to show only the first page found, even if page exists in several sections.
The table below shows the section numbers of the manual followed by the types of pages they contain.
A manual page consists of several sections.
Conventional section names include NAME, SYNOPSIS, CONFIGURATION, DESCRIPTION, OPTIONS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, VERSIONS, CONFORMING TO, NOTES, BUGS, EXAMPLE, AUTHORS, and SEE ALSO.
The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections.
Exact rendering may vary depending on the output device. For instance, man will usually not be able to render italics when running in a terminal, and will typically use underlined or coloured text instead.
The command or function illustration is a pattern that should match all possible invocations. In some cases it is advisable to illustrate several exclusive invocations as is shown in the SYNOPSIS section of this manual page.
Many options are available to man in order to give as much flexibility as possible to the user. Changes can be made to the search path, section order, output processor, and other behaviours and operations detailed below.
If set, various environment variables are interrogated to determine the operation of man. It is possible to set the `catch all' variable $MANOPT to any string in command line format with the exception that any spaces used as part of an option's argument must be escaped (preceded by a backslash). man will parse $MANOPT prior to parsing its own command line. Those options requiring an argument will be overridden by the same options found on the command line. To reset all of the options set in $MANOPT, -D can be specified as the initial command line option. This will allow man to `forget' about the options specified in $MANOPT although they must still have been valid.
The manual pager utilities packaged as man-db make extensive use of index database caches. These caches contain information such as where each manual page can be found on the filesystem and what its whatis (short one line description of the man page) contains, and allow man to run faster than if it had to search the filesystem each time to find the appropriate manual page. If requested using the -u option, man will ensure that the caches remain consistent, which can obviate the need to manually run software to update traditional whatis text databases.
If man cannot find a mandb initiated index database for a particular manual page hierarchy, it will still search for the requested manual pages, although file globbing will be necessary to search within that hierarchy. If whatis or apropos fails to find an index it will try to extract information from a traditional whatis database instead.
These utilities support compressed source nroff files having, by default, the extensions of .Z, .z and .gz. It is possible to deal with any compression extension, but this information must be known at compile time. Also, by default, any cat pages produced are compressed using gzip. Each `global' manual page hierarchy such as /usr/share/man or /usr/X11R6/man may have any directory as its cat page hierarchy. Traditionally the cat pages are stored under the same hierarchy as the man pages, but for reasons such as those specified in the File Hierarchy Standard (FHS), it may be better to store them elsewhere. For details on how to do this, please read manpath(5). For details on why to do this, read the standard.
International support is available with this package. Native language manual pages are accessible (if available on your system) via use of locale functions. To activate such support, it is necessary to set either $LC_MESSAGES, $LANG or another system dependent environment variable to your language locale, usually specified in the POSIX 1003.1 based format:
If the desired page is available in your locale, it will be displayed in lieu of the standard (usually American English) page.
Support for international message catalogues is also featured in this package and can be activated in the same way, again if available. If you find that the manual pages and message catalogues supplied with this package are not available in your native language and you would like to supply them, please contact the maintainer who will be coordinating such activity.
For information regarding other features and extensions available with this manual pager, please read the documents supplied with the package.
man will search for the desired manual pages within the index database caches. If the -u option is given, a cache consistency check is performed to ensure the databases accurately reflect the filesystem. If this option is always given, it is not generally necessary to run mandb after the caches are initially created, unless a cache becomes corrupt. However, the cache consistency check can be slow on systems with many manual pages installed, so it is not performed by default, and system administrators may wish to run mandb every week or so to keep the database caches fresh. To forestall problems caused by outdated caches, man will fall back to file globbing if a cache lookup fails, just as it would if no cache was present.
Once a manual page has been located, a check is performed to find out if a relative preformatted `cat' file already exists and is newer than the nroff file. If it does and is, this preformatted file is (usually) decompressed and then displayed, via use of a pager. The pager can be specified in a number of ways, or else will fall back to a default is used (see option -P for details). If no cat is found or is older than the nroff file, the nroff is filtered through various programs and is shown immediately.
If a cat file can be produced (a relative cat directory exists and has appropriate permissions), man will compress and store the cat file in the background.
The filters are deciphered by a number of means. Firstly, the command line option -p or the environment variable $MANROFFSEQ is interrogated. If -p was not used and the environment variable was not set, the initial line of the nroff file is parsed for a preprocessor string. To contain a valid preprocessor string, the first line must resemble
where string can be any combination of letters described by option -p below.
If none of the above methods provide any filter information, a default set is used.
A formatting pipeline is formed from the filters and the primary formatter (nroff or [tg]roff with -t) and executed. Alternatively, if an executable program mandb_nfmt (or mandb_tfmt with -t) exists in the man tree root, it is executed instead. It gets passed the manual source file, the preprocessor string, and optionally the device specified with -T or -E as arguments.
Non argument options that are duplicated either on the command line, in $MANOPT, or both, are not harmful. For options that require an argument, each duplication will override the previous argument value.
-m system[,...], --systems=system[,...]
The system specified can be a combination of comma delimited operating system names. To include a search of the native operating system's manual pages, include the system name man in the argument string. This option will override the $SYSTEM environment variable.
A path specified as a manpath must be the root of a manual page hierarchy structured into sections as described in the man-db manual (under "The manual page system"). To view manual pages outside such hierarchies, see the -l option.
$ man -aw git diff /usr/share/man/man1/git-diff.1.gz
To disable this behaviour, use the --no-subpages option.
$ man -aw --no-subpages git diff /usr/share/man/man1/git.1.gz /usr/share/man/man3/Git.3pm.gz /usr/share/man/man1/diff.1.gz
The value may be a simple command name or a command with arguments, and may use shell quoting (backslashes, single quotes, or double quotes). It may not use pipes to connect multiple commands; if you need that, use a wrapper script, which may take the file to display either as an argument or on standard input.
Manual page name(sec) line x
where name denotes the manual page name, sec denotes the section it was found under and x the current line number. This is achieved by using the $LESS environment variable.
Supplying -r with a string will override this default. The string may contain the text $MAN_PN which will be expanded to the name of the current manual page and its section name surrounded by `(' and `)'. The string used to produce the default could be expressed as
\ Manual\ page\ \$MAN_PN\ ?ltline\ %lt?L/%L.: byte\ %bB?s/%s..?\ (END):?pB\ %pB\\%.. (press h for help or q to quit)
It is broken into three lines here for the sake of readability only. For its meaning see the less(1) manual page. The prompt string is first evaluated by the shell. All double quotes, back-quotes and backslashes in the prompt must be escaped by a preceding backslash. The prompt string may end in an escaped $ which may be followed by further options for less. By default man sets the -ix8 options.
The $MANLESS environment variable described below may be used to set a default prompt string if none is supplied on the command line.
If the latin1 column displays correctly, your terminal may be set up for latin1 characters and this option is not necessary. If the latin1 and ascii columns are identical, you are reading this page using this option or man did not format this page using the latin1 device description. If the latin1 column is missing or corrupt, you may need to view manual pages with this option.
This option is ignored when using options -t, -H, -T, or -Z and may be useless for nroff other than GNU's.
If you are writing a manual page and simply want to prevent nroff from hyphenating a word at an inappropriate point, do not use this option, but consult the nroff documentation instead; for instance, you can put "\%" inside a word to indicate that it may be hyphenated at that point, or put "\%" at the start of a word to prevent it from being hyphenated.
If you are writing a manual page and simply want to prevent nroff from justifying certain paragraphs, do not use this option, but consult the nroff documentation instead; for instance, you can use the ".na", ".nf", ".fi", and ".ad" requests to temporarily disable adjusting and filling.
apropos(1), groff(1), less(1), manpath(1), nroff(1), troff(1), whatis(1), zsoelim(1), setlocale(3), manpath(5), ascii(7), latin1(7), man(7), catman(8), mandb(8), the man-db package manual, FSSTND
1990, 1991 - Originally written by John W. Eaton (firstname.lastname@example.org).
Dec 23 1992: Rik Faith (email@example.com) applied bug fixes supplied by Willem Kasdorp (firstname.lastname@example.org).
30th April 1994 - 23rd February 2000: Wilf. (G.Wilford@ee.surrey.ac.uk) has been developing and maintaining this package with the help of a few dedicated people.
30th October 1996 - 30th March 2001: Fabrizio Polacco <email@example.com> maintained and enhanced this package for the Debian project, with the help of all the community.
31st March 2001 - present day: Colin Watson <firstname.lastname@example.org> is now developing and maintaining man-db.