Arch manual pages

MAN(1) 手册分页显示工具 MAN(1)

man - an interface to the system reference manuals

man [man options] [[section] page ...] ...
man -k [apropos options] regexp ...
man -K [man options] [section] term ...
man -f [whatis 选项] ...
man -l [man options] file ...
man -w|-W [man options] page ...

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 (see DEFAULTS), and to show only the first page found, even if page exists in several sections.

下表显示了手册的 章节 号及其包含的手册页类型。

1 可执行程序或 shell 命令
2 系统调用(内核提供的函数)
3 库调用(程序库中的函数)
4 特殊文件(通常位于 /dev)
5 File formats and conventions, e.g. /etc/passwd
6 游戏
7 杂项(包括宏包和规范,如 man(7)groff(7))
8 系统管理命令(通常只针对 root 用户)
9 内核例程 [非标准

一个手册 页面 包含若干个小节。

小节名称通常包括 NAME, 概述(SYNOPSIS), 配置(CONFIGURATION), 描述(DESCRIPTION), 选项(OPTIONS), 退出状态(EXIT STATUS), 返回值(RETURN VALUE), 错误(ERRORS), 环境(ENVIRONMENT), 文件(FILES), 版本(VERSIONS), 符合标准(CONFORMING TO), 注(NOTES), 缺陷(BUGS), 示例(EXAMPLE), 作者(AUTHORS), 和 亦见(SEE ALSO).

以下规范适用于 概述(SYNOPSIS) 小节,也可作为其他小节的指南。

加粗文本 按原样显示。
倾斜文本 用相应的参数进行替换。
[-abc] “[ ]” 内的任意/全部参数都是可选的。
-a|-b 以“|”分隔的选项可以一起使用。
参数 ... 参数 可以重复。
[表达式] ... “[ ]”内的整个 表达式 可以重复。

实际渲染的效果可能因输出设备而异。例如,在终端中 man 程序通常无法渲染出斜体,这时一般会以下划线或彩色文字代替。

程序和函数说明应该是一个可以匹配所有可能用法的模式(pattern)。有些情况下,建议按此手册页 概述(SYNOPSIS) 小节所显示的分别陈述几种互斥的用法。

man ls
显示 项目 (程序) ls 对应的手册页
man man.7
Display the manual page for macro package man from section 7. (This is an alternative spelling of "man 7 man".)
man 'man(7)'
Display the manual page for macro package man from section 7. (This is another alternative spelling of "man 7 man". It may be more convenient when copying and pasting cross-references to manual pages. Note that the parentheses must normally be quoted to protect them from the shell.)
man -a intro
正确执行时显示手册中包含的所有可用的 intro 手册页。可以在连续显示过程中退出或跳过任一页。
man -t bash | lpr -Pps
Format the manual page for bash into the default troff or groff format and pipe it to the printer named ps. The default output for groff is usually PostScript. man --help should advise as to which processor is bound to the -t option.
man -l -Tdvi ./foo.1x.gz > ./foo.1x.dvi
This command will decompress and format the nroff source manual page ./foo.1x.gz into a device independent (dvi) file. The redirection is necessary as the -T flag causes output to be directed to stdout with no pager. The output could be viewed with a program such as xdvi or further processed into PostScript using a program such as dvips.
man -k printf
将关键词 printf 作为正则表达式来搜索对应的手册页概述和手册页名称,并打印所有匹配结果。等效于 apropos printf.
man -f smail
查找 smail 引用的手册页并输出找到的所有概述。等效于 whatis smail.

man 有许多选项供用户灵活使用。搜索路径、章节顺序、输出处理器和其他行为和操作均可更改,具体如下。

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.

Manual pages are normally stored in nroff(1) format under a directory such as /usr/share/man. In some installations, there may also be preformatted cat pages to improve performance. See manpath(5) for details of where these files are stored.

This package supports manual pages in multiple languages, controlled by your locale. If your system did not set this up for you automatically, then you may need to set $LC_MESSAGES, $LANG, or another system-dependent environment variable to indicate your preferred locale, usually specified in the POSIX format:

<语言>[_<地区>[.<字符集>[,<版本>]]]

如果所需的页面有您的 区域 对应的版本,它会替代标准的(通常为美国英语)手册页显示。

If you find that the translations 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.

Individual manual pages are normally written and maintained by the maintainers of the program, function, or other topic that they document, and are not included with this package. If you find that a manual page is missing or inadequate, please report that to the maintainers of the package in question.

有关此手册分页程序其他可用功能和扩展的信息,请阅读此包提供的文档。

The order of sections to search may be overridden by the environment variable $MANSECT or by the SECTION directive in /etc/man_db.conf. By default it is as follows:

1 n l 8 3 0 2 5 4 9 6 7

The formatted manual page is displayed using a pager. This can be specified in a number of ways, or else will fall back to a default (see option -P for details).

可以通过几种方式指定过滤程序。首先,会查询命令行选项 -p 或环境变量 $MANROFFSEQ。如果没有指定 -p,环境变量也未设置,将解析 nroff 的第一行来查找预处理器字符串。要包含有效的预处理器字符串,第一行必须这样写:

'\" <字符串>

其中 字符串 可以是下面 -p 选项所描述的任何字符的组合。

如果以上方法都没有提供过滤程序信息,将使用默认程序集。

过滤程序和主格式化程序(nroff 或 [tg]roff -t) 将组成格式化流水线并执行。或者,如果 man 树根节点有可执行的 mandb_nfmt (或 mandb_tfmt -t) 程序,将转而执行它。手册源文件、预处理字符串,以及可选的以 -T-E 指定的设备将作为参数传递给它。

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.

-C 文件--config-file=文件
使用此用户配置文件代替默认的 ~/.manpath
-d, --debug
打印调试信息。
-D, --default
此选项通常作为第一个选项,它将 man 的行为恢复为默认值。它的作用是重置任何在 $MANOPT 中设置的选项。-D 之后的任何选项保留其原有效果。
--warnings[=警告]
启用来自 groff 的警告。这可以用于检查手册页源文件完整性。警告 是以英文逗号分隔的警告名列表;如果不提供,默认为“mac”。请查阅 info groff 中的 “警告” 节点了解可用的警告名列表。

-f, --whatis
等同于 whatis。显示来自手册页的加简短说明(若有)。详见 whatis(1)
-k, --apropos
等同于 apropos。搜索关键词对应的手册概述并显示所有匹配结果。详见 apropos
-K, --global-apropos
在所有手册中搜索文本。这是蛮力搜索,需要花费一定时间;如果可以,您应该指定手册章节以减少需要搜索的手册页数量。搜索条目可以是简单的字符串(默认),或正则表达式(若使用了 --regex 选项)。
注意,这种做法应用于搜索手册页的 资源,而非渲染后的文本,所以可能会包含一些不相干的内容(如源文件中的注释)。若要搜索渲染后的文本,速度会比较慢。
-l, --local-file
Activate "local" mode. Format and display local manual files instead of searching through the system's manual collection. Each manual page argument will be interpreted as an nroff source file in the correct format. No cat file is produced. If '-' is listed as one of the arguments, input will be taken from stdin. When this option is not used, and man fails to find the page required, before displaying the error message, it attempts to act as if this option was supplied, using the name as a filename and looking for an exact match.
-w, --where, --path, --location
Don't actually display the manual page, but do print the location of the source nroff file that would be formatted. If the -a option is also used, then print the locations of all source files that match the search criteria.
-W, --where-cat, --location-cat
Don't actually display the manual page, but do print the location of the preformatted cat file that would be displayed. If the -a option is also used, then print the locations of all preformatted cat files that match the search criteria.
If -w and -W are both used, then print both source file and cat file separated by a space. If all of -w, -W, and -a are used, then do this for each possible match.
-c, --catman
此选项一般不使用,并且只应由 catman 程序使用。
-R 编码--recode=编码
与正常的格式化手册页不同,将输入源转换成指定的 编码 输出。如果您已经知道源文件的编码,也可以直接使用 manconv(1)。不过,此选项可以将几个手册页转换为单一编码,而不用明确声明各自的编码,前提是它们已经安装在与手册页层次结构类似的目录结构中。
Consider using man-recode(1) instead for converting multiple manual pages, since it has an interface designed for bulk conversion and so can be much faster.

-L 区域--locale=区域
man 通常会通过调用 C 语言函数 setlocale(3) 来确定您的当前区域设置。该函数会查询多个环境变量,可能包括 $LC_MESSAGES 和 $LANG。要临时覆盖检测到的值,请使用该选项直接向 man 提供一个 区域 字符串。注意,在搜索页面实际开始前它不会生效。帮助消息等输出将始终以检测到的区域语言显示。
-m 系统[,...], --systems=系统[,...]
如果此系统可以访问其他操作系统的手册页,可以使用此选项访问它们。如要在 NewOS 的手册页集中搜索某个手册页,使用 -m NewOS 选项。

指定的 系统 选项可以是逗号分隔的操作系统名称组合。要在搜索中包括本地操作系统的手册页,可以在参数字符串中包含系统名 man。此选项会覆盖 $SYSTEM 环境变量。

-M 路径--manpath=路径
指定要使用的另一 manpath 路径。默认情况下 man 使用 manpath 得到的代码来确定搜索路径。此选项会覆盖 $SYSTEM 环境变量。

指定为 manpath 的路径必须是划分为若干章节的手册页层次结构的根目录。章节描述见 man-db 手册(位于“手册页系统”)。要查看层次结构之外的手册页,请参阅 -l 选项。

-S list, -s list, --sections=list
The given list is a colon- or comma-separated list of sections, used to determine which manual sections to search and in what order. This option overrides the $MANSECT environment variable. (The -s spelling is for compatibility with System V.)
-e sub-extension--extension=sub-extension
Some systems incorporate large packages of manual pages, such as those that accompany the Tcl package, into the main manual page hierarchy. To get around the problem of having two manual pages with the same name such as exit(3), the Tcl pages were usually all assigned to section l. As this is unfortunate, it is now possible to put the pages in the correct section, and to assign a specific "extension" to them, in this case, exit(3tcl). Under normal operation, man will display exit(3) in preference to exit(3tcl). To negotiate this situation and to avoid having to know which section the page you require resides in, it is now possible to give man a sub-extension string indicating which package the page must belong to. Using the above example, supplying the option -e tcl to man will restrict the search to pages having an extension of *tcl.
-i, --ignore-case
搜索手册页时忽略大小写。此为默认值。
-I, --match-case
搜索手册页时匹配大小写。
--regex
显示名字或描述的任何部分与所提供的正则表达式 参数匹配的所有页面,像使用 apropos(1) 一样。由于搜索正则表达式时通常没办法选出“最佳”手册页,此选项隐含了 -a 选项。
--wildcard
显示名字或描述的任何部分与所提供的 shell 格式通配符 参数匹配的所有页面,像使用 apropos(1) --wildcard 一样。 参数必须匹配整个名字或描述,或匹配描述中单词的边界。由于搜索通配符时通常没办法选出“最佳”手册页,此选项隐含了 -a 选项。
--names-only
如果使用了 --regex--wildcard 选项,则只匹配手册页名而不匹配描述,就像使用 whatis(1) 一样。否则不起作用。
-a, --all
默认情况下,man 在显示它找到的最符合的手册页后会退出。此选项强制 man 显示名字匹配搜索条件的所有的手册页。
-u, --update
This option causes man to update its database caches of installed manual pages. This is only needed in rare situations, and it is normally better to run mandb(8) instead.
--no-subpages
默认情况下,man 会试图将命令行上提供的一对手册页名视同包含连字符或下划线的单个手册页名来解释。这会支持那些实现了多个子命令的程序的常见模式,允许程序为每个子命令提供手册页,并用和调用各子命令的语法类似的方式访问它们。例如:

  $ man -aw git diff
  /usr/share/man/man1/git-diff.1.gz
    

要禁用此行为,请使用 --no-subpages 选项。

  $ 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
    

-P 分页程序--pager=分页程序
指定使用哪个输出分页程序。man 默认使用 less,在无法找到 less 或它不是可执行文件时则会回退到使用 cat。此选项会覆盖 $MANPAGER 环境变量,进一步覆盖 $PAGER 环境变量。它不和 -f-k 合用。

值可以是简单的命令名或带参数的命令,并可以使用 shell 引用(反斜杠、单引号或双引号)。不能使用管道连接多个命令;如果您需要,请使用封装器脚本,它能够以参数形式或从标准输入获得要显示的文件。

-r 提示--prompt=提示
如果使用较新的 less 作为分页程序,man 将尝试设置它的提示消息和一些敏感选项。默认的提示消息类似于

 Manual page name(sec) line x

其中 name 表示手册页名,sec 表示找到的手册页所属的章节,x 是当前行号。这是通过使用 $LESS 环境变量实现的。

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)

为了方便阅读,这里分成了三行。字符串的含义请参阅 less(1) 手册页。提示字符串将首先由 shell 解释。提示中的所有的双引号、反斜杠都必须在前面加一个反斜杠转义。提示字符串可以转义的 $ 结束,后面还可以跟其他的 less 选项。man 默认设置 -ix8 选项。

下面描述的 $MANLESS 环境变量可以用来在命令行未指定时设置默认的提示字符串。

-7, --ascii
当在7位编码的终端或终端模拟器中查看纯 ascii(7) 手册页时,若使用 GNU nroff latin1(7) 设备描述,一些字符可能显示不正确。此选项允许纯 ascii 手册页使用 latin11 设备以 ascii 显示。它不会转换任何 latin1 文本。以下表格显示了进行的转换:其中一部分可能只有在使用 GNU nrofflatin1(7) 设备时才正确显示。

描述 八进制 latin1 ascii
连字符 255 -
点(中间点) 267 o
重音符号 264 ´ '
乘号 327 × x

如果 latin1 列显示正确,您的终端可能作了 latin1 字符设置,此选项将不需要。如果 latin1ascii 列一样,那么您正在使用此选项阅读本手册页,或 man 未使用 latin1 设备描述来格式化此页。如果 latin1 列缺损,您可能要使用此选项来查看手册页。

在使用 -t, -H, -T, 或 -Z 选项时此选项可能对 GNU 版 之外的 nroff 程序无用。

-E 编码--encoding=编码
生成对应字符编码的输出,而非默认编码。为向后兼容,编码 可以是 nroff 设备,如 asciilatin1utf8,也可以是实际的字符编码如 UTF-8
--no-hyphenation, --nh
通常,如果需要将单词排在一行而不添加过多的空格, nroff 会在换行处自动断字(给文本添加连字符,即使单词本来不包含)。此选项禁止自动断字,即单词包含连字符时才会被断开。

如果您编写手册页时只是不希望 nroff 在某个位置不恰当地断字,不要使用此选项,而应查阅 nroff 文档中的相关方法;例如,您可以在单词中插入“\%”来指示该位置可以断字,或在单词开头插入“\%”来阻止对它断字。

--no-justification, --nj
通常,nroff 会自动两端对齐文本。此选项禁止两端对齐,只对齐左边,形成所谓的“ragged-right”(右边不齐)的文本。

如果您编写手册页时只是不希望 nroff 对齐某些段落,不要使用此选项,而应查阅 nroff 文档中的相关方法;例如,您可以使用“.na”、“.nf”、“.fi”和“.ad”请求来临时禁止对齐和填充。

-p 字符串--preprocessor=字符串
指定 nrofftroff/groff 之前运行的预处理器序列。系统中可能未安装所有的预处理器。一些预处理器及其代号如下:eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r)。此选项覆盖 $MANROFFSEQ 环境变量。zsoelim 总是作为第一个预处理器运行。
-t, --troff
使用 %troff 来格式化手册页到 stdout。此选项不要求和 -H-T-Z 一起使用。
-T[设备], --troff-device[=设备]
此选项用于更改 groff (也可能是 troff) 的输出以适合某个非默认设备。此选项隐含了 -t。(Groff-1.17 提供的)例子包括 dvilatin1psutf8X75X100
-H[浏览器], --html[=浏览器]
此选项使 groff 生成 HTML 输出并在浏览器中显示输出结果。浏览器选择取决于可选的 browser 参数(若提供)、$BROWSER 环境变量,或编译时指定的默认值(或环境变量未设置,默认值通常为 lynx)。此选项隐含了 -t,并只和 GNU troff 一起使用。
-X[dpi], --gxditview[=dpi]
此选项使用 gxditview 程序在一个图形窗口中显示 groff 的输出结果。dpi (点/英寸)可以是 75、75-12、100 或 100-12,默认为 75;-12 形式使用 12 点的基础字号。此选项隐含了带相应 X75、X75-12、X100 或 X100-12 参数的 -T 选项。
-Z, --ditroff
groff 会运行 troff 然后使用合适的后处理器产生适合所选设备的输出。如果 %troffgroff,此选项会传递给 groff 并禁止使用后处理器。此选项隐含了 -t 选项。

-?, --help
打印帮助消息并退出。
--usage
打印简短的帮助消息并退出。
-V, --version
显示版本信息。

0
程序成功执行。
1
用法、语法或配置文件出错。
2
操作出错。
3
子进程返回了非零的退出状态码。
16
至少有一个页面/文件/关键词不存在或不匹配。

MANPATH
如果设置了 $MANPATH,它的值会用作搜索手册页的路径。
MANROFFOPT
Every time man invokes the formatter (nroff, troff, or groff), it adds the contents of $MANROFFOPT to the formatter's command line.
MANROFFSEQ
如果设置了 $MANROFFSEQ,它的值会用于确定每个手册页经过的预处理程序的集合。默认的预处理器列表因系统而异。
MANSECT
如果设置了 $MANSECT,它的值(以冒号分隔的章节列表)会用于确定搜索哪些章节及搜索顺序。默认值为“1 n l 8 3 0 2 5 4 9 6 7”,除非被 /etc/man_db.conf 中的 SECTION 指令覆盖。
MANPAGER, PAGER
如果设置了 $MANPAGER 或 $PAGER (优先使用 $MANPAGER),它的值会用作显示手册页的程序的名称。默认使用 less,如果无法找到 less 或它不是可执行文件的话则会回退到使用 cat

值可以是简单的命令名或带参数的命令,并可以使用 shell 引用(反斜杠、单引号或双引号)。不能使用管道连接多个命令;如果您需要,请使用封装器脚本,它能够以参数形式或从标准输入获得要显示的文件。

MANLESS
如果设置了 $MANLESS,它的值将用作 less 分页程序的默认提示字符串,如同作为 -r 选项的参数传递一样(因此出现的任何 $MAN_PN 会以同样的方式展开)。例如,如果您想将提示字符串无条件地设置为“my prompt string”,请将 $MANLESS 设置为 ‘-Psmy prompt string’。使用 -r 选项会覆盖此环境变量。
BROWSER
如果设置了 $BROWSER,它的值(冒号分隔的命令列表)中的每一个会轮流用于尝试为 man --html 启动一个网络浏览器。每个命令中,%s 会替换成包含 groff HTML 输出的文件名,%% 会替换成一个百分号(%),%c 会替换成冒号(:)。
SYSTEM
如果设置了 $SYSTEM 环境变量,其效果将与 -m 选项的参数相同。
MANOPT
如果设置了 $MANOPT,它会先于 man 的命令行并假设为类似的格式来解析。由于所有其他的 man 特定环境变量可以表达为命令行选项而可以包被含进 $MANOPT,因此 这些环境变量可能废弃。注意,所有应当解释为命令行选项参数一部分的空格必须被转义。
MANWIDTH
If $MANWIDTH is set, its value is used as the line length for which manual pages should be formatted. If it is not set, manual pages will be formatted with a line length appropriate to the current terminal (using the value of $COLUMNS, and ioctl(2) if available, or falling back to 80 characters if neither is available). Cat pages will only be saved when the default formatting can be used, that is when the terminal line length is between 66 and 80 characters.
MAN_KEEP_FORMATTING
通常,当输出不定向到终端时(如定向到文件或管道),格式化字符会被忽略,以便不使用特殊工具就能阅读结果。但如果 $MAN_KEEP_FORMATTING 设置成了任何非空的值,这些格式化字符将保存。这对于可以解释格式化字符的 man 封装程序有用。
MAN_KEEP_STDERR
通常,当输出定向到终端时(一般是分页程序),产生手册格式化版本的命令造成的任何错误输出都会被忽略,以免干扰分页程序显示。groff 这样的程度经常产生较小的有关排版显示的错误消息(如未对齐)。这些消息很难看,并且一般与手册页一起显示时会产生干扰。不过,有些用户就是想看到它们,好吧,如果 $MAN_KEEP_STDERR 设成了非空的值,这些错误输出会照常显示。
LANG, LC_MESSAGES
取决于系统和实现,程序会查询 $LANG 和/或 $LC_MESSAGES 获知当前的消息区域语言。man 会以该区域语言显示消息(若可用)。参阅 setlocale(3) 了解准确的详情。

/etc/man_db.conf
man-db 配置文件。
/usr/share/man
全局手册页层次结构。

apropos(1), groff(1), less(1), manpath(1), nroff(1), troff(1), whatis(1), zsoelim(1), manpath(5), man(7), catman(8), mandb(8)

Documentation for some packages may be available in other formats, such as info(1) or HTML.

1990, 1991 – 原作者 John W. Eaton (jwe@che.utexas.edu)。

1992年12月23日: Rik Faith (faith@cs.unc.edu) 应用了 Willem Kasdorp (wkasdo@nikhefk.nikef.nl) 提供的 bug 补丁。

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.

1996年10月30日 – 2001年3月30日: Fabrizio Polacco <fpolacco@debian.org> 为 Debian 项目维护并增强了这个包,过程中得到整个社区的帮助。

2001年3月31日 – 今天: Colin Watson <cjwatson@debian.org> 开发和维护着 man-db。

2019-10-23 2.9.0