man 中文man页面-man中文

命令名

man - 格式化显示 man pages

总览

groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title

描述

本手册页对 groff tamc.an 宏命令包以及创建包含这些宏命令的手册页（man pages)的有关约定作一些说明。本手册用于帮助开发人员创建或发布 linux 手册页（linux man pages）。本手册与其他版本的兼容性良好，所以发布不会是个问题（除非包含 net-2 BSD 版本，它使用完全不同的宏命令包（叫做 mdoc），您可以察看 mdoc(7) 获取更详细的说明）。不过使用 man -mdoc xxxx 也可以察看 mdoc 格式的文件。而且我们推荐您使用该参数，因为他会自动检查文件所使用的宏命令的类别。

导言

手册页中的***个命令一般是：其中：

标题: 手册页的标题（通常与命令名相同）（比如： MAN)。
章节号: 手册页的章节号（比如： 7 ）
日期: ***更新日期 -- 要记得每次更新后都把日期改为***，这也是进行版本控制的好方法。
资源？？？: (MISSING SOME PARTS) 手册名手册名（比如： Linux Programmer's Manual（Linux 程序员手册））。注意 BSD mdoc 格式的页以 Dd 命令开始，而不是 .TH 命令。

手册的各章节内容通常如下规定：（一个手册可以有好几节，比如 man(1)、man(7)等，可分别用 man 1 man 、 man 7 man来察看。）

1 命令: 命令的使用方法，可以使用的参数等。
2 系统调用: 只有系统才能执行的函数
3 库调用: 大多是 libc 函数，如 qsort(3)
4 特殊文件: 文件在 /dev 中。
文件的格式，比如: /etc/passwd 及其他可读文件。
6 游戏
7 宏命令包和约定: 一些描述，关于标准文件系统设计、网络协议，ASCII 和其他字符编码、man page (手册页）和其他。
8 系统管理命令: 诸如 mount(8) 之类的命令，多数只有 root 可以执行。
9 内核程序: 这个章节几乎不用了。原来曾想把一些关于核心的文件放在这里，但是实际上只有极少数可以写成文件放在这里，而且它们也很快过时了。核心开发者可以找到其他更好的资源。

段

段以 .SH 开始，后跟标题。如果标题包含空格并且和 .SH 在同一行，则需在标题上加双引号。约定（推荐使用）的标题包括： NAME(命令名），SYNOPSIS（总览），DESCRIPTION（描述）， RETURN VALUE (or RETURN VALUES)（返回值）， EXIT STATUS（退出状态），ERROR HANDLING（错误处理）， ERRORS（错误），OPTIONS（选项）， USAGE（用法），FILES（文件），ENVIRONMENT（环境）， DIAGNOSTICS（诊断），SECURITY（安全）， CONFORMING TO（遵循），NOTES（注意事项），BUGS（已知漏洞）， AUTHOR（作者），和 SEE ALSO（参见）．在适合使用约定标题的地方，请使用他；这样做可以使文章更易读、易懂。不过，只要您的标题能够增加易懂性，请放心使用。唯一必须的标题是 NAME（命令名），他应是手册页的***段，后面应紧跟对该命令的简单描述。比如： .SH NAME 命令名 chess - the game of chess 请一定要按照这个格式来写，注意在短横线（-）前要有个斜杠（)。这种语法结构在 makewhatis(8)程序中为 whatis(1) 和 apropos(1) 建立简短命令描述时要用到。

其他约定段的内容应为：

总览: 简要描述命令或函数接口。对命令，显示他的命令和参数（包括各种选项）；黑体表示各种参数，下划线（或斜体字）表示可以替换的选项；方括号[]中的是可选项，竖线 | 用于把几个选项间隔开，小括号()中的部分可以自动重复。对函数，显示需要的数据声明或需包含的项目，后跟函数声明。
描述: 解释命令、函数或格式的用途。说明其如何与文件及标准输入交互，他们的标准输出及标准错误。必须要指明的细节。描述一般情况。选项和参数信息放在 OPTIONS（参数）段。如果有语法说明和一些复杂的设定，建议把它们放到 USAGE（用法）段（本段中可写一个概要）。
返回值: 列出程序或函数会返回的值，指出引发返回值的条件或原因。
退出状态: 列出可能的退出状态的值，指出引起返回的程序或原因（可以与“返回值”段合并）。
参数: 指出程序可用的参数，及其作用。
用法: 描述程序的较高级的使用方法。
文件: 列出程序或函数使用到的文件，比如配置文件、启动文件和程序直接操作的文件。给出文件的绝对路径，使用安装程序调整这些路径以使其与用户的实际情况相符。对大多数程序来说，缺省的安装路径是 /usr/local，所以你的文件要与此一致。
环境: 列出影响你的程序的所有环境变量，并说明影响的原因。
诊断: 写出常会出现的错误概述，并说明解决的办法。你无需解释系统错误信息或信号，除非它们会影响到您的程序。
安全: 讨论安全问题和相关话题。对应予避免的配置和环境，可能有安全隐患的命令等等给出警告，特别是当它们不是很明显时。单独用一段来讨论安全并不必要；如果比较好理解的话，把它放在其他段中（比如描述或用法段）。但是，不能不写。
约定: 描述该程序的标准和约定（或是习惯用法）。
已知漏洞: 列出局限、已知的缺点或不便之处，还有其他可能存在的问题。
作者: 列出程序或文件作者，联系办法等。
参见: 以字母顺序列出相关的手册页（man pages)。通常来讲，这是一个手册页的***一段。

字体

虽然在 UNIX 世界中有各种对手册页（man pages)的不同约定，但在 linux 系统下存在一个字体的标准：对函数，其参数通常用下划线（或斜体），在总览（SYNOPSIS)中也是这样，其他部分用黑体。文件名用下划线（或斜体），但在总览（SYNOPSIS)中不是，包含的文件用黑体（如： #include )。专用宏，一般大写表示，用黑体（如： MAXINT)。列举错误代号时，代号用黑体（这种列举通常使用 .TP 宏命令）。对其他手册页的引用（或本页中某主体的引用）用黑体。手册章节号用普通体（如： man(7)）．设置字体的宏命令如下：

.B: 黑体 .BI 黑体和下划线（或斜体）交替（描述函数时非常有用） .BR 黑体和普通体交替（描述引用时非常有用） .I 下划线（或斜体） .IB 下划线（或斜体）和黑体交替 .IR 下划线（或斜体）和普通体交替 .RI 普通体和下划线（或斜体）交替 .SB 小号字和黑体交替 .SM 小号字（用于缩写）

按照惯例，每个命令最多可以有六个小节的参数，但是 GNU 去除了这个限制。小节之间以空格隔开。如果某小节含有空格，则需要给其加上双引号。各小节在显示时无间隔，所以 .BR 命令可以指定一个黑体的词，后跟一个普通体的标点。如果命令后无参数，则命令作用于下一行。

其他宏命令和字符串

下面是其他一些相关的宏和预定义的字符串。除非指明，否则所有的宏在本行文本结束时终止。多数宏使用“流行缩进”（prevailing indent)方式。 “流行缩进”的值由紧跟着宏命令的 i 值指定，如果不指定，那就会使用当前的“流行缩进”值。这样，连续的缩进段就可使用相同的缩进值而不需要重新指定。普通段（不缩进）将“流行缩进”值重值为缺省值（0.5 英寸）。缺省时，缩进是有规则的 en(s)：用 en(s) 或者 em(s) 作为缩进的单位，因为它们会自动地调整字体的大小。 (注：度量距离有不同的单位，当请求需要用到不同的距离时，可以使用默认类型来修饰数字，度量单位是英寸，厘米，pica,en,em,点，unit和垂直行距。 1pica等于1/6英寸，1em等于字母m的宽度，默认宽度取决于troff中使用的字体。En是em的一半。) 其他宏命令定义如下：

普通段（无缩进）

.LP: 与 .PP 相同（开始一个新段） .P 同上 .PP 开始一个新段，重置“流行缩进”值。

相对缩进

: 开始相对缩进 -- 把左边界右移 i (如果不指定 i 值，则使用“流行缩进”值）。同时设定“流行缩进”值为 0.5 英寸。直到使用 .RE结束这些设定。
.RE: 结束相对缩进同时把“流行缩进”恢复原值。

缩进

.HP i: 开始悬挂式缩进（段的***行从左边揭开时，其余缩进显示）
.IP x i: 在段上标签 x 。如果不指定 x ，则整个段缩进 i。如果指定了 x ，则 x 之前的段不缩进，之后的段缩进（有些象 .TP，不过 x 是跟在命令后面而不是在下一行）。如果 x 太长，后面的文本会挪到下一行（文本不会丢失或割断）。做公告列表，可以用 .IP * (bullet) 或 .IP --- (em dash) 要用数字或字母列表时，可以用 .IP 1. 或 .IP A. ，他们会转换成其他格式。
.TP i: 在段上悬挂标签。标签在下一行指定，但是结果和 .IP 相像。

超文本链接宏

.UR u: 建立一个超文本链接到 URI(URL) u；并以 UE 结束。当转换为 HTML 格式时，他会转换为 <A HREF="u">。有个例外：如果 u 是“ ：”，则之后不能建立任何超级链接，直到以 UE 结束（这用来在不需要超级链接时禁止他）。这个宏比较新，很多程序可能并不对他进行处理。 <A NAME="u" id="u"> </A>

杂项宏

.DT: 重置 tab 值为缺省(每一个0.5英寸)。不引起中断。
.IX ...: 插入索引信息（方便搜索系统工作，或打印索引列表）。在页中索引信息不能正常显示。如果只有一个参数，参数作为独立的索引项指向手册页的内容。如果有两个参数，他可能是 Perl 手册页格式；***个参数指定类型名（命令名，标题，题头，子段货源素之一），第二个参数指明自己的索引名。另外，长索引形式：每个参数是一个索引项，次级索引项，再次级索引项，等等直到以空参数结束，然后是程序名参数，\m，还有一小段描述。还可能在跟上一个空参数，有可能是页控制信息（如： PAGE START)。举例如下： "programmingtools""make""""make--- build programs".
.PD d: 在段中间垂直距离空开 d (如果不指定，则缺省为 d=0.4v)，不引起中断。
.SS t: 子标题 t (象是 .SH, 但是作为段中的字标题使用）

预定义字符串

\*R: 注册符号
\*S: 改变成缺省字体大小
\*(Tm: 商标符号
\*(lq: 左双引号
\*(rg: 右双引号

安全子集

理论上 man 是一个 troff 宏命令包，实际上很多工具程序没有支持所有的 man 宏命令。因此，为了这些程序可以正常工作***忽略 troff 的一些比较另类的宏。避免使用各种不同的 troff 预处理程序（如果必须的话，用 tbl(1)吧但是在建立双列表时请使用 IP 和 TP 命令）。避免使用计算；大多数其他程序不能处理他。使用简单的命令比较容易转换为其他格式。下面的宏命令一般认为是安全的（虽然多数时候他们都被忽略了）： \", . , ad , bp , br , ce , de, ds, el , ie , if , fi , ft, hy, ig , in , na , ne , nf, nh, ps , so , sp , tr . 你还可能使用 troff 转义字符（这些转移符号以 \ 开始）。但你要在文本中显示反斜线时，用\。其他转义字符包括： \' ，\` ，\- ，\. ，\" ，\% ，\*x ，\*(xx ， \(xx ，\$N ，\nx， \n(xx ，\fx，\f(xx。其中 x、xx 是任意字符，N 是任意数字不要使用转义字符来画图。不要随意使用 bp（break page(中断页））。 sp（vertical space(垂直距离）只应使用正值。不要用（de（define（定义）））定义与现有的宏同名的宏（无论 man 或 mdoc)；这种重新定义可能会被忽略。每个正缩进应对应一个负缩进（即使在使用 RS 和 RE 是也不例外）。可以使用的只有可忽略的转换（tr）．改变字体命令（ft 和 \f)只能带如下参数： 1，2，3，4，R,I,B,P,CW (ft 命令也可以不带参数)。如果你是用更多的功能，用各种程序仔细察看一下结果。如果你肯定某功能是安全的，请告诉我们，以便把他增加到这个列表中。

注意事项

尽量在文本中包含完整的 URL（或URIs）；一些工具软件（如：man2html(1)）能够自动把它们转换为超级链接。您也可用 UR 命令指定链接到相关信息。输入完整的 URL(如： )。以(.)或（')开始一行，表明是基于 troff 的文件（如： man 或 mdoc)。如果是（<）表明基于 SGML/XML (如：HTML 或 Docbook)．其他可能是纯文本。有些 man 以'\"和空格再加字符列开始，表示他的预处理方法。为了 troff 翻译器程序处理起来简单一些，您仅应使用 tbl(1) 而不是其他什么东东，Linux 可以检测到这一点。不过，你或许想要包含这些信息以使其可以在其他系统得到处理。下面是预处理调用的定义： e eqn(1) g grap(1) p pic(1) r refer(1) t tbl(1) v vgrind(1)

文件

/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis

已知漏洞

大多数宏命令描述的是格式（比如：字体和空格）而不是内容描述（比如：这段文字指向另外一页），与 mdoc 和 DocBook 正好相反（HTML 也有比较多的内容描述）。这使得 man 难以转换为其他形式，不容易与其他文件组合或自动插入交叉引用。遵照以上的安全说明，就比较容易在将来把他转换为其他格式。 Sun 的 macro TX 下不能用。

作者

---: James Clark (jjc@jclark.com) wrote the implementation of the macro package.
---: Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of this manual page.
---: Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO (which influenced this manual page).
---: David A. Wheeler (dwheeler@ida.org) heavily modified this manual page, such as adding detailed information on sections and macros.

参见

apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1).

#p#

NAME

man - format and display the on-line manual pages
manpath - determine user's search path for man pages

SYNOPSIS

man [-acdfFhkKtwW] [--path] [-m system] [-p string] [-C config_file] [-M pathlist] [-P pager] [-S section_list] [section] name ...

DESCRIPTION

man formats and displays the on-line manual pages. If you specify section, man only looks in that section of the manual. name is normally the name of the manual page, which is typically the name of a command, function, or file. However, if name contains a slash (/) then man interprets it as a file specification, so that you can do man ./foo.5 or even man /cd/foo/bar.1.gz.

See below for a description of where man looks for the manual page files.

OPTIONS

-C config_file: Specify the configuration file to use; the default is /etc/man.config. (See man.config(5).)
-M path: Specify the list of directories to search for man pages. Separate the directories with colons. An empty list is the same as not specifying -M at all. See SEARCH PATH FOR MANUAL PAGES.
-P pager: Specify which pager to use. This option overrides the MANPAGER environment variable, which in turn overrides the PAGER variable. By default, man uses /usr/bin/less -is.
-S section_list: List is a colon separated list of manual sections to search. This option overrides the MANSECT environment variable.
-a: By default, man will exit after displaying the first manual page it finds. Using this option forces man to display all the manual pages that match name, not just the first.
-c: Reformat the source man page, even when an up-to-date cat page exists. This can be meaningful if the cat page was formatted for a screen with a different number of columns, or if the preformatted page is corrupted.
-d: Don't actually display the man pages, but do print gobs of debugging information.
-D: Both display and print debugging info.
-f: Equivalent to whatis.
-F or --preformat: Format only - do not display.
-h: Print a one-line help message and exit.
-k: Equivalent to apropos.
-K: Search for the specified string in *all* man pages. Warning: this is probably very slow! It helps to specify a section. (Just to give a rough idea, on my machine this takes about a minute per 500 man pages.)
-m system: Specify an alternate set of man pages to search based on the system name given.
-p string: Specify the sequence of preprocessors to run before nroff or troff. Not all installations will have a full set of preprocessors. Some of the preprocessors and the letters used to designate them are: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). This option overrides the MANROFFSEQ environment variable.
-t: Use /usr/bin/groff -Tps -mandoc to format the manual page, passing the output to stdout. The output from /usr/bin/groff -Tps -mandoc may need to be passed through some filter or another before being printed.
-w or --path: Don't actually display the man pages, but do print the location(s) of the files that would be formatted or displayed. If no argument is given: display (on stdout) the list of directories that is searched by man for man pages. If manpath is a link to man, then "manpath" is equivalent to "man --path".
-W: Like -w, but print file names one per line, without additional information. This is useful in shell commands like man -aW man | xargs ls -l

CAT PAGES

Man will try to save the formatted man pages, in order to save formatting time the next time these pages are needed. Traditionally, formatted versions of pages in DIR/manX are saved in DIR/catX, but other mappings from man dir to cat dir can be specified in /etc/man.config. No cat pages are saved when the required cat directory does not exist. No cat pages are saved when they are formatted for a line length different from 80. No cat pages are saved when man.conf contains the line NOCACHE.

It is possible to make man suid to a user man. Then, if a cat directory has owner man and mode 0755 (only writable by man), and the cat files have owner man and mode 0644 or 0444 (only writable by man, or not writable at all), no ordinary user can change the cat pages or put other files in the cat directory. If man is not made suid, then a cat directory should have mode 0777 if all users should be able to leave cat pages there.

The option -c forces reformatting a page, even if a recent cat page exists.

SEARCH PATH FOR MANUAL PAGES

man uses a sophisticated method of finding manual page files, based on the invocation options and environment variables, the /etc/man.config configuration file, and some built in conventions and heuristics.

First of all, when the name argument to man contains a slash (/), man assumes it is a file specification itself, and there is no searching involved.

But in the normal case where name doesn't contain a slash, man searches a variety of directories for a file that could be a manual page for the topic named.

If you specify the -M pathlist option, pathlist is a colon-separated list of the directories that man searches.

If you don't specify -M but set the MANPATH environment variable, the value of that variable is the list of the directories that man searches.

If you don't specify an explicit path list with -M or MANPATH, man develops its own path list based on the contents of the configuration file /etc/man.config. The MANPATH statements in the configuration file identify particular directories to include in the search path.

Furthermore, the MANPATH_MAP statements add to the search path depending on your command search path (i.e. your PATH environment variable). For each directory that may be in the command search path, a MANPATH_MAP statement specifies a directory that should be added to the search path for manual page files. man looks at the PATH variable and adds the corresponding directories to the manual page file search path. Thus, with the proper use of MANPATH_MAP, when you issue the command man xyz, you get a manual page for the program that would run if you issued the command xyz.

In addition, for each directory in the command search path (we'll call it a "command directory") for which you do not have a MANPATH_MAP statement, man automatically looks for a manual page directory "nearby" namely as a subdirectory in the command directory itself or in the parent directory of the command directory.

You can disable the automatic "nearby" searches by including a NOAUTOPATH statement in /etc/man.config.

In each directory in the search path as described above, man searches for a file named topic.section, with an optional suffix on the section number and possibly a compression suffix. If it doesn't find such a file, it then looks in any subdirectories named manN or catN where N is the manual section number. If the file is in a catN subdirectory, man assumes it is a formatted manual page file (cat page). Otherwise, man assumes it is unformatted. In either case, if the filename has a known compression suffix (like .gz), man assumes it is gzipped.

If you want to see where (or if) man would find the manual page for a particular topic, use the --path (-w) option.

ENVIRONMENT

MANPATH: If MANPATH is set, man uses it as the path to search for manual page files. It overrides the configuration file and the automatic search path, but is overridden by the -M invocation option. See SEARCH PATH FOR MANUAL PAGES.
MANPL: If MANPL is set, its value is used as the display page length. Otherwise, the entire man page will occupy one (long) page.
MANROFFSEQ: If MANROFFSEQ is set, its value is used to determine the set of preprocessors run before running nroff or troff. By default, pages are passed through the tbl preprocessor before nroff.
MANSECT: If MANSECT is set, its value is used to determine which manual sections to search.
MANWIDTH: If MANWIDTH is set, its value is used as the width manpages should be displayed. Otherwise the pages may be displayed over the whole width of your screen.
MANPAGER: If MANPAGER is set, its value is used as the name of the program to use to display the man page. If not, then PAGER is used. If that has no value either, /usr/bin/less -is is used.
LANG: If LANG is set, its value defines the name of the subdirectory where man first looks for man pages. Thus, the command `LANG=dk man 1 foo' will cause man to look for the foo man page in .../dk/man1/foo.1, and if it cannot find such a file, then in .../man1/foo.1, where ... is a directory on the search path.
NLSPATH, LC_MESSAGES, LANG: The environment variables NLSPATH and LC_MESSAGES (or LANG when the latter does not exist) play a role in locating the message catalog. (But the English messages are compiled in, and for English no catalog is required.) Note that programs like col(1) called by man also use e.g. LC_CTYPE.
PATH: PATH helps determine the search path for manual page files. See SEARCH PATH FOR MANUAL PAGES.
SYSTEM: SYSTEM is used to get the default alternate system name (for use with the -m option).