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

名称

man - 系统参考手册的接口

概述

man [man 选项] [[章节] 页 ...] ...
man -k [apropos 选项] 正则表达式 ...
man -K [man 选项] [章节] 关键词 ...
man -f [whatis 选项] 页 ...
man -l [man 选项] 文件 ...
man -w|-W [man 选项] page ...

描述

man 是系统的手册分页程序。指定给 man 的 页 选项通常是程序、工具或函数名。程序将显示每一个找到的相关 手册页。如果指定了 章节，man 将只在手册的指定 章节 搜索。默认将按预定的顺序查找所有可用的 章节（参见 默认值 一节），并只显示找到的第一个 页，即使多个 章节 中都有这个 页面。

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

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

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

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

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

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

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

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

示例

显示 项目 (程序) ls 对应的手册页。
显示章节 7 中宏包 man 对应的手册页。（这是“man 7 man”的另一种拼写方法。）
显示章节 7 中宏包 man 对应的手册页。（这是“man 7 man”的另一种拼写方法。该方法在复制和粘贴手册页的交叉引用时可能更方便。请注意，括号在通常情况下必须被引号括起以避免 shell 转义。）
正确执行时显示手册中包含的所有可用的 intro 手册页。可以在连续显示过程中退出或跳过任一页。
将 bash 的手册页格式化为默认的 troff 或 groff 格式，并将其通过管道送至名为 ps 的打印机。groff 的默认输出通常是 PostScript。man --help 应该会提示哪个处理器程序与 -t 选项绑定。
此命令会将 nroff 源手册页 ./foo.1x.gz 解压并格式化为 设备无关(dvi) 文件。重定向是必须的，因为 -T 标志会导致输出不经分页程序直接传送到 stdout。 应该使用 xdvi 这样的程序查看输出结果，或使用 dvips 这样的程序进一步处理为 PostScript。
将关键词 printf 作为正则表达式来搜索对应的手册页概述和手册页名称，并打印所有匹配结果。等效于 apropos printf.
查找 smail 引用的手册页并输出找到的所有概述。等效于 whatis smail.

概述

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

如果被设置，程序将检查各种环境变量来确定 man 如何操作。可以对命令行中的任何字符串设置“catch all”变量 $MANOPT，除非是选项参数中需要转义的空格。man 将会先解析 $MANOPT，再解析它自己的命令行。这些需要参数的选项将会被命令行中其他的相同选项所覆盖。若要重置 $MANOPT 中的所有选项，可以在命令行开头指定 -D 选项。这会让 man “忘掉”$MANOPT 中给定的选项，但即便如此曾经给定的选项必须仍然合法。

手册页通常以 nroff(1) 格式存放在诸如 /usr/share/man 路径下的目录中。在某些安装场景中，也可能存在用于提高性能的预格式化 cat pages。请参见 manpath(5) 以了解这些文件存放位置的具体信息。

本软件包支持多语言的手册页，其行为由您的 locale（语区）所控制。如果您的系统未帮您自动设置，那么您可能需要手动设置 $LC_MESSAGES、$LANG 或其它系统相关的环境变量以指示您偏好的区域语言设置，通常以 POSIX 格式给出：

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

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

如果您发现此包提供的翻译对您的本地语言不可用并且您想提供支持的话，请联系协调这类活动的（手册本地化）维护者。

独立的各个手册页通常由各个程序、函数或相关主题的维护者所编写提供，它们并不包含于本软件包中。如果您发现了缺失或内容不完整的手册页，请向对应软件包的维护者报告这个问题。

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

默认值

要搜索的章节顺序可以使用 $MANSECT 或 /etc/man_db.conf 配置文件的 SECTION 指令进行覆盖。其默认行为如下所示：

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

经过格式化的手册页将使用一个分页器（pager）进行显示。有数种指定分页显示的方法，若无指定则将使用默认方式（参见 -P 选项了解详细信息）。

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

'\" <字符串>

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

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

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

选项

非参数的选项如果在命令行和/或 $MANOPT 重复指定，不会产生问题。对于需要参数的选项，每次重复将覆盖上个参数值。

常规选项

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

主要操作方式

大约等同于 whatis。显示来自手册页的加简短说明(若有)。详见 whatis(1)。
大约等同于 apropos。搜索关键词对应的手册概述并显示所有匹配结果。详见 apropos。
在所有手册中搜索文本。这是蛮力搜索，需要花费一定时间；如果可以，您应该指定手册章节以减少需要搜索的手册页数量。搜索条目可以是简单的字符串(默认)，或正则表达式(若使用了 --regex 选项)。
注意，这种做法应用于搜索手册页的 资源，而非渲染后的文本，所以可能会包含一些假结果（如源文件中的注释），或遗漏某些结果（如源文件中写为“\-”的连字符）。若要搜索渲染后的文本，速度会比较慢。
启用“本地”方式。格式化并显示本地手册文件，而非搜索系统手册集。每个手册页参数将解释为格式正确的 nroff 源文件。不产生 cat 文件。如果参数中有“-”，将从标准输入读取。
如果未指定该选项，则 man 也会在参数中包含“/”字符的情况下回退到将手册页参数解释为本地文件名的行为。这是因为该特征说明参数对应了文件系统中的一个文件路径。
不实际显示手册页，但打印将被格式化的源 nroff 文件的位置。如果同时指定了 -a 选项，则打印所有匹配搜索条件的源文件的位置。
不实际显示手册页，但打印将显示的预格式化 cat 文件的位置。如果同时使用了 -a 选项，则打印所有匹配搜索条件的预格式化 cat 文件的位置。
如果同时使用了 -w 和 -W 选项，则同时打印源文件和 cat 文件，并使用空格分隔。如果使用了全部 -w、-W 和 -a 三个选项，则为每个可能的匹配进行相同的操作。
此选项一般不使用，并且只应由 catman 程序使用。
与正常的格式化手册页不同，将输入源转换成指定的 编码 输出。如果您已经知道源文件的编码，也可以直接使用 manconv(1)。不过，此选项可以将几个手册页转换为单一编码，而不用明确声明各自的编码，前提是它们已经安装在与手册页层次结构类似的目录结构中。
如需转换多个手册页，请考虑使用 man-recode(1) 工具；它提供了批量转换的接口，能够大大加快处理速度。

查找手册页

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

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

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

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

给定的 list 是一个用英文冒号或逗号分隔的手册章节列表，用于确定要搜索的手册章节的搜索顺序。此选项会覆盖 $MANSECT 环境变量。(使用 -s 表示是为了与 System V 兼容。)
某些系统包含大量的手册页包，例如某些系统将 Tcl (手册)包并入主手册页层次目录。为避免两个手册页重名，如 exit(3)，Tcl 手册页通常都归于 l 章节。为解决这一不便，现在可以将页面放在正确的节，分配给它们一个特定的“扩展（extension）”即可；这个例子中则是 exit(3tcl)。正常操作时，man 会优先显示 exit(3) 而不是 exit(3tcl)。为协调这一状况并避免要记住所需手册页属于哪个章节，现在可以给 man 指定一个 sub-extension字符串，指示该手册页必须属于哪个包。对于上面的例子，给 man 加上 -e tcl 选项，就能限制只搜索带有 *tcl 扩展的页面。
搜索手册页时忽略大小写。此为默认值。
搜索手册页时匹配大小写。
显示名字或描述的任何部分与所提供的正则表达式 页 参数匹配的所有页面，像使用 apropos(1) 一样。由于搜索正则表达式时通常没办法选出“最佳”手册页，此选项隐含了 -a 选项。
显示名字或描述的任何部分与所提供的 shell 格式通配符 页 参数匹配的所有页面，像使用 apropos(1) --wildcard 一样。页 参数必须匹配整个名字或描述，或匹配描述中单词的边界。由于搜索通配符时通常没办法选出“最佳”手册页，此选项隐含了 -a 选项。
如果使用了 --regex 或 --wildcard 选项，则只匹配手册页名而不匹配描述，就像使用 whatis(1) 一样。否则不起作用。
默认情况下，man 在显示它找到的最符合的手册页后会退出。此选项强制 man 显示名字匹配搜索条件的所有的手册页。
该选项将使得 man 更新已安装手册页的缓存数据库。该操作只在极少数情况下才需要进行，一般情况下只运行 mandb(8) 更好。
默认情况下，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

控制格式化输出

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

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

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

Manual page name(sec) line x

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

提供一个带字符串的 -r 选项会覆盖这个默认值。字符串可以包含文本 $MAN_PN，它会展开为用“(”和“)”括起来的当前手册页的章节名。显示默认提示的字符串可以表示为

\ 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 nroff 的 latin1(7) 设备时才正确显示。
描述 八进制 latin1 ascii
连字符 255 ‐ -
点（中间点） 267 • o
重音符号 264 ´ '
乘号 327 × x

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

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

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

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

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

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

指定 nroff 或 troff/groff 之前运行的预处理器序列。系统中可能未安装所有的预处理器。一些预处理器及其代号如下：eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r)。此选项覆盖 $MANROFFSEQ 环境变量。zsoelim 总是作为第一个预处理器运行。
使用 %troff 来格式化手册页到 stdout。此选项不要求和 -H、-T 或 -Z 一起使用。
This option is used to change groff (or possibly troff's) output to be suitable for a device other than the default. It implies -t. Examples (as of groff 1.23.0) include dvi, latin1, pdf, ps, utf8, X75 and X100.
此选项使 groff 生成 HTML 输出并在浏览器中显示输出结果。浏览器选择取决于可选的 browser 参数(若提供)、$BROWSER 环境变量，或编译时指定的默认值(或环境变量未设置，默认值通常为 lynx)。此选项隐含了 -t，并只和 GNU troff 一起使用。
此选项使用 gxditview 程序在一个图形窗口中显示 groff 的输出结果。dpi (点/英寸)可以是 75、75-12、100 或 100-12，默认为 75；-12 形式使用 12 点的基础字号。此选项隐含了带相应 X75、X75-12、X100 或 X100-12 参数的 -T 选项。
groff 会运行 troff 然后使用合适的后处理器产生适合所选设备的输出。如果 %troff 为 groff，此选项会传递给 groff 并禁止使用后处理器。此选项隐含了 -t 选项。

获取帮助

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

退出状态

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

环境

如果设置了 $MANPATH，它的值会用作搜索手册页的路径。

请参考 manpath(5) 中的搜索路径一节以了解默认行为以及处理该环境变量的细节。

每当 man 调用格式化工具时（nroff、troff 或 groff），它将把 $MANROFFOPT 的内容添加至格式化工具的命令行参数。

For example, MANROFFOPT=-P-i tells the formatter to use italic text (which is only supported by some terminals) rather than underlined text.

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

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

如果设置了 $MANLESS，它的值将用作 less 分页程序的默认提示字符串，如同作为 -r 选项的参数传递一样(因此出现的任何 $MAN_PN 会以同样的方式展开)。例如，如果您想将提示字符串无条件地设置为“my prompt string”，请将 $MANLESS 设置为 ‘-Psmy prompt string’。使用 -r 选项会覆盖此环境变量。
如果设置了 $BROWSER，它的值(冒号分隔的命令列表)中的每一个会轮流用于尝试为 man --html 启动一个网络浏览器。每个命令中，%s 会替换成包含 groff HTML 输出的文件名，%% 会替换成一个百分号(%)，%c 会替换成冒号(:)。
如果设置了 $SYSTEM 环境变量，其效果将与 -m 选项的参数相同。
如果设置了 $MANOPT，它会先于 man 的命令行并假设为类似的格式来解析。由于所有其他的 man 特定环境变量可以表达为命令行选项而可以包被含进 $MANOPT，因此 这些环境变量可能废弃。注意，所有应当解释为命令行选项参数一部分的空格必须被转义。
如果设置了 $MANWIDTH，它的值将用作手册页格式化时的每行长度。如果未设置，手册页将使用适合当前终端的行长度格式化(使用 $COLUMNS 的值或通过 ioctl(2) 调用获取，或在都不可用的情况下退回到 80 个字符)。Cat 页面只有在默认格式化可用时才会保存，即终端行长度介于 66 到 80 个字符时。
通常，当输出不定向到终端时(如定向到文件或管道)，格式化字符会被忽略，以便不使用特殊工具就能阅读结果。但如果 $MAN_KEEP_FORMATTING 设置成了任何非空的值，这些格式化字符将保存。这对于可以解释格式化字符的 man 封装程序有用。
通常，当输出定向到终端时(一般是分页程序)，产生手册格式化版本的命令造成的任何错误输出都会被忽略，以免干扰分页程序显示。groff 这样的程度经常产生较小的有关排版显示的错误消息(如未对齐)。这些消息很难看，并且一般与手册页一起显示时会产生干扰。不过，有些用户就是想看到它们，好吧，如果 $MAN_KEEP_STDERR 设成了非空的值，这些错误输出会照常显示。
在 Linux 系统中，man 通常将处理不受信任数据的子进程使用 seccomp(2) 沙盒进行限制。这能够使得运行复杂的手册页解析代码变得更加安全。如果这种限制使得一些与页面显示内容无关的原因影响了程序正常行为，您可以设置 $MAN_DISABLE_SECCOMP 为任意非空值来禁用该沙盒。
如果 $PIPELINE_DEBUG 环境变量置为“1”，则 man 会向标准错误打印描述每个所运行子进程的调试信息。
取决于系统和实现，程序会查询 $LANG 和/或 $LC_MESSAGES 获知当前的消息区域语言。man 会以该区域语言显示消息(若可用)。参阅 setlocale(3) 了解准确的详情。

文件

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

标准

POSIX.1-2001, POSIX.1-2008, POSIX.1-2017.

亦见

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

某些包的文档可能以其它格式提供，如 info(1) 或 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 补丁。

1994年4月30日 – 2000年2月23日: Wilf. (G.Wilford@ee.surrey.ac.uk) 在几位热心人的帮助下开发和维护这个包。

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

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

https://gitlab.com/man-db/man-db/-/issues
https://savannah.nongnu.org/bugs/?group=man-db

2024-08-29 2.13.0