命令名

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">&nbsp;</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).

SEE ALSO

apropos(1), whatis(1), less(1), groff(1), man.conf(5).