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

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

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

2 システムコール

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

3 ライブラリコール

libc の関数の大部分。

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

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

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

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

6 ゲーム

7 概要、約束事、その他

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

8 システム管理コマンド

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

マクロパッケージ

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

タイトル行

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

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

「伝統的に使われてきた見出しが使える場合には、それを使ってほしい。」この種の一貫性を保つことで、情報を理解しやすくなるからである。どうしても必要な場合には、理解しやすくなるように独自の見出しを作ってもよい (特にセクション 4 や 5 のページではこうした方がわかりやすくなる)。ただし、そうする前に、伝統的な見出しを使い、そのセクション内にサブセクション ( .SS) を設けることで対応できないか考えてほしい。

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

名前 (NAME)

The name of this manual page. See man(7) for important details of the line(s) that should follow the .SH NAME command. All words in this line (including the word immediately following the "\-") should be in lowercase, except where English or technical terminological convention dictates otherwise.

書式 (SYNOPSIS)

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

 

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

CONFIGURATION

デバイスの設定詳細。通常、このセクションは 4 章のマニュアルページでのみ登場する。

説明 (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 のバージョンについての簡潔な概要。一般に、全ての新しいインターフェイスは、マニュアルページに「バージョン」の節を設けるべきである。残念なことに、多くの既存のマニュアルページにこの情報は含まれていない (これらのページが書かれた時点ではそのようなポリシーはなかったからである)。これを改善するパッチは歓迎されるが、新しいコードを書くプログラマの観点からすれば、おそらくこの情報が重要になるのは、 Linux 2.4 以降で追加されたカーネルインターフェイス (カーネル 2.2 からの変更) と glibc バージョン 2.1 以降で追加されたライブラリ関数 (glibc 2.0 からの変更) についてのみであろう。

 

syscalls(2) マニュアルページにも、いろいろなシステムコールが初めて登場したカーネルバージョンについての情報が書かれている。

準拠 (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)

関連するマニュアルページを、コンマ区切りのリストで、セクション番号順に、セクション内ではアルファベット順で記載する。可能なら関連する他の文書も書く。慣習では、このセクションは最後に置く。リストの末尾にピリオドを置かないこと。

Where the SEE ALSO list contains many long manual page names, to improve the visual result of the output, it may be useful to employ the .ad l (don't right justify) and .nh (don't hyphenate) directives. Hyphenation of individual page names can be prevented by preceding words with the string "\%".

フォントの慣習

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

引き数名といった変数名はイタリック体を指定すべきである。

ファイル名 (パス名、または /usr/include ディレクトリ内のファイルへの参照) は常にイタリック体にする (例: <stdio.h>)。ただし、書式 (SYNOPSIS) セクションは例外で、インクルードファイルはボールドにする (例: #include <stdio.h>)。 /usr/include 以下の標準のインクルードファイルを参照する際は、通常の C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例： <stdio.h>)。

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

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

完全なコマンドは、長い場合には、例に示すように字下げした行にコマンドだけを記載すべきである。

man 7 man-pages

コマンドが短い場合は、 man 7 man-pages のようにイタリック体で文中に埋め込んで記載してもよい。この場合、コマンド内の適切な位置に、改行できないスペース ("\ ") を使うとよいかもしれない。コマンドオプションも -l のようにイタリック体で記載すべきである。

式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。繰り返しになるが、式を通常の文中に埋め込む場合にも、改行できないスペースを使うとよいだろう。

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

.BR fcntl ()

("\fB...\fP()"よりも、この形式を使うこと。これにより、マニュアルページのソースファイルを解釈するツールを書くのが簡単になる。)

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

.BR intro (2)

(相互参照にセクション番号を含めておくと、 man2html といったツールがページ間のハイパーリンクを適切に生成できる。)

綴り (spelling)

Capitalization

サンプルプログラムとシェルのセッション

*

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

*

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

*

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

*

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

*

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

*

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

*

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

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

プログラムの使い方や他のシステムの特徴を示すためにシェルのセッション例を含める場合、ユーザの入力文をボールドにして、システムが生成する出力と区別できるようにすること。

構造体の定義、シェルのセッションログなどの字下げ