man page分類與說明

2022-08-14 12:02:17

轉載自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可分為九類：

使用者命令(User command)
系統程式(System call)
程式庫程序(Library function)
設備檔案(Device file)
檔案用途描述
遊戲說明
雜項(Miscellaneous)
系統管理工具(只有root才能使用)
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>

码农公寓

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

前言

Man Page種類

Man page命名及存放目錄

Man page內容分類

相关文章