MAN-PAGES

名前

書式

説明

マニュアルページのセクション

マニュアルのセクションは、習慣的に以下のような定義が用いられている:

1 コマンド (プログラム)

シェルの中からユーザが実行できるコマンド。

2 システムコール

カーネルが処理しなければならない関数。

3 ライブラリコール

libc の関数の大部分。

4 スペシャルファイル (デバイス)

/dev 以下にあるファイル。

5 ファイルのフォーマットと規約

/etc/passwd などの人が読めるファイルのフォーマット。

6 ゲーム

7 約束事その他

様々な事柄の概要、慣習、プロトコル、文字集合の規格、その他雑多なこと。

8 システム管理コマンド

mount(8) のような root のみが実行可能なコマンド。

マクロパッケージ

ソースファイルの配置に関する決まり事

新しい文は行頭から開始する。 これにより、パッチの内容を確認しやすくなる。 パッチは文単位であることが多いからである。  

タイトル行

.TH title section date source manual

title

man ページのタイトル。全部大文字で記載する (例: MAN-PAGES)。

section

man ページが属するセクション番号 (例: 7)。

date

最新のリビジョンの日付 --- man ページに変更を加えたときには 必ずこれを変更すること。 これが最も一般的なバージョン管理方法である。 日付は YYYY-MM-DD の形式で記載すべきである。

source

コマンド、関数、システムコールの出自。

数少ないセクション 1 と 8 のページの場合、おそらく単に GNU とだけ書くことが多いだろう。

システムコールの場合、単に Linux とだけ書く。 (以前の慣習では、マニュアルページを記載した/内容を確認したカーネルの バージョン番号を記載していた。しかし、バージョン番号が実際の内容と 一致していることはなく、そのためバージョン番号がないよりも おそらく悪い形になっていた。 今後は、バージョン番号を含めるのは避けること。)

glibc のライブラリコールや その他の一般的な GNU ライブラリのライブラリコールの場合、 単に GNU C Library, GNU と書くか、空の文字列を使う。

セクション 4 のページでは Linux を使う。

よくわからない場合は、 Linux とか GNU と書いておく。

manual

マニュアルのタイトル (例: man-pages パッケージのセクション 2 および 3 のページの場合には、 Linux Programmer's Manual を使うこと)。

マニュアルページのセクション

名前
書式
説明
オプション         [通常はセクション 1, 8 のみ]
終了ステータス     [通常はセクション 1, 8 のみ]
返り値             [通常はセクション 2, 3 のみ]
エラー             [たいていはセクション 2, 3 のみ]
環境変数
ファイル
バージョン         [通常はセクション 2, 3 のみ]
準拠
注意/備考
バグ
例
関連項目

以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。

名前 (NAME)

そのマニュアルページの名前。 .SH NAME コマンドの行が従うべき大事な点については man(7) を参照してほしい。

書式 (SYNOPSIS)

コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。 そのまま書くテキストにはボールド体を用い、置き換える引き数には イタリックを用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒 (|) で区切り、繰り返しには省略符号 (...) を書く。 関数に対しては、必要なデータ宣言や #include 指定を書き、関数宣言を続ける。

ヘッダファイルから関数 (や変数) の定義を得るために 機能検査マクロ (feature test macro) を定義しなければならない場合、 書式 (SYNOPSIS) に必要な機能検査マクロを記載すべきである。 機能検査マクロについては feature_test_macros(7) で説明されている。

説明 (DESCRIPTION)

プログラム・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。 通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 オプション のセクションを用いる。

オプション (OPTIONS)

プログラムが受け付けるコマンドライン・オプションと、 その場合プログラムの振舞いがどう変わるかを説明する。 このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。

終了ステータス (EXIT STATUS)

プログラムの終了ステータスの値と、それらの値に対応する状況を列挙する。 このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。

返り値 (RETURN VALUE)

セクション 2 と 3 のページの場合、このセクションに ライブラリルーチンが呼び出し元に返す値のリストを記載する。 それらの値が返された場合の状態に対する説明も書く。

エラー (ERRORS)

セクション 2 と 3 のマニュアルページでは、 エラーが発生した場合に errno に設定される可能性がある値のリストを記載する。 リストには、エラーの値とエラーの原因についての情報を書く。 「エラーリストはアルファベット順にすべきである。」

環境変数 (ENVIRONMENT)

プログラムや関数に影響する環境変数をリストし、それらの効果を書く。

ファイル (FILES)

プログラムや関数が用いるファイルを列記する。 例えば、設定ファイル、起動ファイル、プログラムが直接操作するファイルなどである。 これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インストール処理で変更できるようにする。 多くのプログラムではデフォルトのインストール先は /usr/local である。したがってベースとなるマニュアルページでも /usr/local が使われていることが多いだろう。

バージョン (VERSIONS)

システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カーネルや glibc のバージョンについての簡潔な概要。

準拠 (CONFORMING TO)

そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習について記載する。 セクション 2 や 3 のページでは、このセクションで システムコールや関数が準拠する POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG などの他の標準規格や、SVr4 や 4.xBSD の実装標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1 の現行バージョンで規定されていない場合以外は、 あまり深く気にする必要はない。) (standards(7) 参照。)

そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨を記載すること。 そのコールが Linux 固有の場合は、その旨を記載すること。

注意 (NOTES)

その他の注意点を書く。 セクション 2 と 3 のマニュアルページでは、 Linux での注意 (Linux Notes) や glibc での注意 (Glibc Notes) という名前のサブセクション (SS) を設けると便利なこともある。

バグ (BUGS)

制限・知られている欠陥や不便な点、その他不思議な動作などを書く。

例 (EXAMPLE)

この関数・ファイル・コマンドをどのように使うかを示した ひとつまたは複数の例を記述する。 サンプルプログラムを書く際の詳細は 以下の「サンプルプログラム」の節を参照のこと。

著者 (AUTHORS)

文書またはプログラムの著者を列記する。 著者セクションは極力使用しないこと。 一般的には、著者のリストを各ページに撒き散らさない方がよい (時間がたつと、作者のリストは膨大になる可能性がある)。 マニュアルページを新規に書いたり、大幅に修正を行った場合には、 ソースファイルにコメントとして著作権表示を追加すること。 あなたがデバイスドライバの作者で、バグを報告するためのアドレスを 載せたい場合は、「バグ」セクションの後ろにこのセクションを配置すること。

関連項目 (SEE ALSO)

関連する man ページをセクション番号順に、セクション内では アルファベット順に列挙する。 可能なら関連する他の文書も書く。 慣習では、このセクションは最後に置く。

フォントの慣習

関数に対しては、引き数には常にイタリックを用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」 関数の他の部分はボールドを指定する:

int myfunction(int argc, char **argv);

ファイル名は常にイタリックにする (例: /usr/include/stdio.h), ただし書式 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: #include <stdio.h>)。

通常、大文字で表現する特殊マクロはボールドで表す (例えば MAXINT)。 例外として NULL はボールドにしない。

エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 .TP マクロを用いる)。

そのマニュアルページの説明対象への参照は、ボールドで名前を記載する。 対象が関数 (つまり、セクション 2 や 3 のページ) の場合、 名前の後ろにローマンフォント (通常のフォント) で丸括弧の対を続ける。 例えば、 fcntl(2) のマニュアルページでは、説明対象への参照は fcntl() のように記載する。 マニュアルページのソースファイルには次のように記載するのが望ましい:

    .BR fcntl ()

別のマニュアルページへの参照は、ボールドで名前を記載し、 それに続けてセクション番号を「必ず」書く。セクション番号は ローマンフォント (通常のフォント) で書き、スペースは入れない (例: intro(2))。 マニュアルページのソースファイルには次のように記載するのが望ましい:

    .BR intro (2)

綴り (spelling)

サンプルプログラム

*

サンプルプログラムは C で記載すること。

*

サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合にだけ 必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。

*

サンプルプログラムはかなり短めにすること (100行以下が望ましく、50行以下が理想的である)。

*

サンプルプログラムでは、システムコールやライブラリ関数を呼び出した後で エラーチェックを行うこと。

*

サンプルプログラムは完結していて、 cc -Wall でコンパイルした際に警告なしでコンパイルできること。

*

可能かつ適切な場合には、サンプルプログラムで 入力により動作を変化させるなどの実験を行うとよい (理想的には、コマンドライン引き数や、プログラムが読み込む入力データ 経由で、動作を変化させるのがよい)。

*

サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文字で行う。 (ソースコードで TAB 文字を使うのは避けること。)

サンプルプログラムがどんな風になっていればよいかの例については、 wait(2) と pipe(2) を参照すること。  

例

関連項目

Index

名前

書式

説明

マニュアルページのセクション

マクロパッケージ

ソースファイルの配置に関する決まり事

タイトル行

マニュアルページのセクション

フォントの慣習

綴り (spelling)

サンプルプログラム

例

関連項目