MAN(1) | 手册分页显示工具 | MAN(1) |
man - 在线参考手册的接口
man [-C 文件] [-d]
[-D] [--warnings[=警告]] [-R
编码] [-L 区域] [-m
系统[,...]] [-M 路径]
[-S 列表] [-e 扩展]
[-i|-I] [--regex|--wildcard]
[--names-only] [-a] [-u] [--no-subpages]
[-P 分页程序] [-r
提示] [-7] [-E 编码]
[--no-hyphenation] [--no-justification] [-p
字符串] [-t]
[-T[设备]]
[-H[浏览器]] [-X[dpi]]
[-Z] [[章节]
页[.章节] ...] ...
man -k [apropos 选项]
正则表达式 ...
man -K [-w|-W] [-S list]
[-i|-I] [--regex] [章节]
词语 ...
man -f [whatis 选项] 页
...
man -l [-C 文件] [-d]
[-D] [--warnings[=警告]] [-R
编码] [-L 区域] [-P
分页程序] [-r 提示]
[-7] [-E 编码] [-p
字符串] [-t]
[-T[设备]]
[-H[浏览器]] [-X[dpi]]
[-Z] 文件 ...
man -w|-W [-C 文件] [-d]
[-D] 页 ...
man -c [-C 文件] [-d]
[-D] 页 ...
man [-?V]
man 是系统的手册分页程序。指定给 man 的 页 选项通常是程序、工具或函数名。程序将显示每一个找到的相关 手册页。如果指定了 章节,man 将只在手册的指定 章节 搜索。默认将按预定的顺序查找所有可用的 章节 (默认是“1 n l 8 3 2 3posix 3pm 3perl 3am 5 4 9 6 7”,除非被 /etc/manpath.config 中的 SECTION 指令覆盖),并只显示找到的第一个 页,即使多个 章节 中都有这个 页面。
下表显示了手册的 章节 号及其包含的手册页类型。
1 | 可执行程序或 shell 命令 |
2 | 系统调用(内核提供的函数) |
3 | 库调用(程序库中的函数) |
4 | 特殊文件(通常位于 /dev) |
5 | 文件格式和规范,如 /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 有许多选项供用户灵活使用。搜索路径、章节顺序、输出处理器和其他行为和操作均可更改,具体如下。
如果被设置,程序将检查各种环境变量来确定 man 如何操作。可以对命令行中的任何字符串设置“catch all”变量 $MANOPT,除非是选项参数中需要转义的空格。man 将会先解析 $MANOPT,再解析它自己的命令行。这些需要参数的选项将会被命令行中其他的相同选项所覆盖。若要重置 $MANOPT 中的所有选项,可以在命令行开头指定 -D 选项。这会让 man “忘掉”$MANOPT 中指定的选项,即便它们可能仍然是有效的。
手册分页程序工具封装在 man-db 程序包里,它们充分利用 索引 数据库缓存。这些缓存包含了诸如每个手册页存储在文件系统的什么位置,它的 whatis (对手册页的一句概述) 包含什么,而且能让 man 运行更快些,因为不用每次搜索文件系统查找相应的手册页。如果调用时使用了 -u 选项,man 会保证缓存的一致性;这避免了手动运行软件来更新传统的 whatis 文本数据库。
如果 man 从 mandb 初始化的 索引 数据库中找不到某个手册页层次结构,它仍然会搜索请求的手册页,尽管搜索该层次结构时需要展开文件。如果 whatis 或 apropos 找不到 索引,它会尝试从传统的 whatis 数据库中提取信息。
这些工具默认支持以 .Z, .z 和 .gz 为扩展名的 nroff 压缩源文件。可以支持其他压缩扩展名,但相应信息需要在编译时提供。同样,任何 cat 页面将使用 gzip 压缩。每个“全局”手册页层次结构如 /usr/share/man 或 /usr/X11R6/man 可以包含任何与其 cat 页层次结构相同的目录。传统上 cat 页面保存在与 man 页面相同的层次结构下,但由于某些原因,例如 File Hierarchy Standard (文件系统层次结构标准, FHS) 所指出的,可能将它们保存在其他位置更好。有关如何操作的详细信息,请参阅 manpath(5)。想了解这样做的详细原因,请阅读标准文档。
此包提供了国际化支持。本地语言的手册页(如果系统上有)可以通过使用 locale 功能来访问。要启用本地语言支持,需要将 $LC_MESSAGES 或 $LANG 或其他系统相关的环境变量设置为您的语言区域代码;该代码通常以基于 POSIX 1003.1 的格式指定:
<语言>[_<地区>[.<字符集>[,<版本>]]]
如果所需的页面有您的 区域 对应的版本,它会替代标准的(通常为美国英语)手册页显示。
国际化的消息分类功能也包含在此包中,可以用同样的方式启用(如果可用的话)。如果您发现此包提供的手册页和消息分类对您的本地语言不可用并且想提供支持,请联系协调这类活动的(手册本地化)维护者。
有关此手册分页程序其他可用功能和扩展的信息,请阅读此包提供的文档。
man 将在 索引 数据库缓存中搜索需要的手册页。如果指定了 -u 选项,将执行缓存一致性检查来保证数据库与文件系统精确对应。如果总是指定该选项,则不必在缓存初次创建后运行 mandb,除非缓存被破坏。不过,缓存一致性检查在安装了很多手册页的系统上可能很慢,因此默认不检查;系统管理员可以隔段时间(如每周)运行一次 mandb 来保证数据库缓存及时更新。为预防过期缓存导致的问题,man 会在查找缓存失败后退回到文件展开查找,就像没有缓存时一样。
一旦定位到手册页,程序将检查是否已存在一个相关的“cat”文件并且比 nroff 文件新。如果是,这个预格式化的文件(通常)会使用分页程序解压和显示。分页程序可以通过几种方式指定,或者退回到使用一个默认的(详见 -P 选项)。如果找不到 cat 文件或它比 nroff 文件旧,nroff 将通过各种程序过滤并立即显示。
如果可以生成 cat 文件(相应的 cat 目录存在并有正确的权限),man 会在后台压缩并保存 cat 文件。
可以通过几种方式指定过滤程序。首先,会查询命令行选项 -p 或环境变量 $MANROFFSEQ。如果没有指定 -p,环境变量也未设置,将解析 nroff 的第一行来查找预处理器字符串。要包含有效的预处理器字符串,第一行必须这样写:
'\" <字符串>
其中 字符串 可以是下面 -p 选项所描述的任何字符的组合。
如果以上方法都没有提供过滤程序信息,将使用默认程序集。
过滤程序和主格式化程序(nroff 或 [tg]roff -t) 将组成格式化流水线并执行。或者,如果 man 树根节点有可执行的 mandb_nfmt (或 mandb_tfmt -t) 程序,将转而执行它。手册源文件、预处理字符串,以及可选的以 -T 或 -E 指定的设备将作为参数传递给它。
非参数的选项如果在命令行和/或 $MANOPT 重复指定,不会产生问题。对于需要参数的选项,每次重复将覆盖上个参数值。
-m 系统[,...], --systems=系统[,...]
指定的 系统 选项可以是逗号分隔的操作系统名称组合。要在搜索中包括本地操作系统的手册页,可以在参数字符串中包含系统名 man。此选项会覆盖 $SYSTEM 环境变量。
指定为 manpath 的路径必须是划分为若干章节的手册页层次结构的根目录。章节描述见 man-db 手册(位于“手册页系统”)。要查看层次结构之外的手册页,请参阅 -l 选项。
$ 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
值可以是简单的命令名或带参数的命令,并可以使用 shell 引用(反斜杠、单引号或双引号)。不能使用管道连接多个命令;如果您需要,请使用封装器脚本,它能够以参数形式或从标准输入获得要显示的文件。
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 环境变量可以用来在命令行未指定时设置默认的提示字符串。
描述 | 八进制 | latin1 | ascii |
连字符 | 255 | ‐ | - |
点(中间点) | 267 | • | o |
重音符号 | 264 | ´ | ' |
乘号 | 327 | × | x |
如果 latin1 列显示正确,您的终端可能作了 latin1 字符设置,此选项将不需要。如果 latin1 和 ascii 列一样,那么您正在使用此选项阅读本手册页,或 man 未使用 latin1 设备描述来格式化此页。如果 latin1 列缺损,您可能要使用此选项来查看手册页。
在使用 -t, -H, -T, 或 -Z 选项时此选项可能对 GNU 版 之外的 nroff 程序无用。
如果您编写手册页时只是不希望 nroff 在某个位置不恰当地断字,不要使用此选项,而应查阅 nroff 文档中的相关方法;例如,您可以在单词中插入“\%”来指示该位置可以断字,或在单词开头插入“\%”来阻止对它断字。
如果您编写手册页时只是不希望 nroff 对齐某些段落,不要使用此选项,而应查阅 nroff 文档中的相关方法;例如,您可以使用“.na”、“.nf”、“.fi”和“.ad”请求来临时禁止对齐和填充。
值可以是简单的命令名或带参数的命令,并可以使用 shell 引用(反斜杠、单引号或双引号)。不能使用管道连接多个命令;如果您需要,请使用封装器脚本,它能够以参数形式或从标准输入获得要显示的文件。
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), man-db 包的手册,FSSTND
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。
2019-01-05 | 2.8.5 |