man page分類與說明

轉載自http://itzone.hk/article/article.php?aid=200407152225014657

(如有侵權,請留言或來信告知)

前言

Man page是每位程式設計員及Unix/Linux系統管理員日常必備的參考，它必須是可靠以及準確(reliable & accurate)的，當然man page的擺放位置亦是關鍵，起碼你的man page是能夠被其他人存取的。

你需要知道man page的整個運作原理、存放規定以及編寫man page時要注意的表意問題，以達到更高的可靠度及準確度。

Man Page種類

Man page可分為九類：

1. 使用者命令(User command)
2. 系統程式(System call)
3. 程式庫程序(Library function)
4. 設備檔案(Device file)
5. 檔案用途描述
6. 遊戲說明
7. 雜項(Miscellaneous)
8. 系統管理工具(只有root才能使用)
9. Linux核心程序

Linux根據以上的分類，製作了九類man page，Linux程式開發者也根據以上的分類，編寫描述軟件的man page，以上每一個分類我們叫做一個section，例如「man」這個指令屬第一類，即section 1，以man(1)表示；「malloc」為程式庫程序，因此它屬於第三類，以malloc(3)表示。

Man page命名及存放目錄

而man page的source file也有其命名方法，它的名稱必須為「cmd_name.section_no」，例如「malloc」指令，它的檔案名必須為「malloc.3」。另外，有些man page檔案名稱的最尾會加上「C」、「tk」或「X」之類，那代表該指令/程序/檔案分別是屬於C語言、tk語言及X程式專屬的參考。這樣命名的目的，始終在於避免發生同名指令的衝突，當您命名您的指令/程序時，最好先確保沒有和系統文件以及現有指令的名稱有所衝突。

所有man page的預設存放位址為/usr/man，而為了分類需要，在/usr/man裡都會有/usr/man/man1、/usr/man/man2等等，作為軟件開發者，您必須跟從man1、man2至man8的分類方法，但您仍可保留是否在/usr/man裡擺放man page的權利，大部分軟件都讓使用者輸入MANDIR，作為安裝man page的目錄，當然MANDIR之下是依照man1至man8的分類方法。詳情請參看http://www.pathname.com/fhs/。

Man page內容分類

以下引述了http://www.tldp.org/HOWTO/Man-Page/q3.html的例子：

FOO(1)                     User Manuals                    FOO(1)

NAME
    foo - frobnicate the bar library

SYNOPSIS
    foo [-bar] [-c config-file ] file ...

DESCRIPTION
     foo  frobnicates the bar library by tweaking internal symbol
     tables. By default it parses all baz segments and rearranges
     them  in  reverse  order  by time for the xyzzy(1) linker to
     find them. The symdef entry is then compressed using the WBG
     (Whiz-Bang-Gizmo) algorithm.  All files are processed in the
     order specified.

OPTIONS
     -b   Do not write `busy' to stdout while processing.

-c config-file
          Use the alternate system wide  config-file  instead  of
          /etc/foo.conf.   This overrides any FOOCONF environment
          variable.

-a   In addition to the baz segments, also parse the  blurfl
          headers.

-r   Recursive  mode.  Operates  as fast as lightning at the
          expense of a megabyte of virtual memory.

FILES
     /etc/foo.conf
          The system wide configuration file. See foo(5) for fur-
          ther details.
     ~/.foorc
          Per  user  configuration  file.  See foo(5) for further
          details.

ENVIRONMENT
     FOOCONF
          If non-null the full pathname for an  alternate  system
          wide foo.conf.  Overridden by the -c option.

DIAGNOSTICS
     The following diagnostics may be issued on stderr:

Bad magic number.
          The input file does not look like an archive file.
     Old style baz segments.
          foo  can  only  handle  new  style  baz segments. COBOL
          object libraries are not supported in this version.

BUGS
     The command name should have been chosen more  carefully  to
     reflect its purpose.

AUTHOR
     Jens Schweikhardt <howto at schweikhardt dot net>

SEE ALSO
     bar(1), foo(5), xyzzy(1)

Linux                Last change: MARCH 1995                    2

• NAME

  這是man page必須包含的部分，你必須以該指令/程序名稱作開頭，若您的man page如fscanf一般是一系列的指令，您可以使用「,」號分開，然後加入「-」(dash)號，最後填上指令/程序的簡短描述。

• SYNOPSIS

  您可以在這部分裡填上指令所需要的header file、函數原型(prototype)及傳回類型。

• DESCRIPTION

  你需要在這部分寫上你的程式是做甚麼，講解各個參數的用途，以及運作原理及算法等等。

• OPTIONS

  顯示如何加入不同的選項能如何更改你程式的執行效果。

• FILES

  列出執行時所需的檔案及程式。

• ENVIRONMENT

  顯示不同的環境變數值能如何影響著您的程式。

• DIAGNOSTICS

  講解程式在執行時會遇上的錯誤。

• BUGS

  列出您的程式有甚麼問題……

• AUTHOR

  作者的名稱及電郵地址。

• SEE ALSO

  列出相關的man page。