From: Akihiro MOTOKI Date: Mon, 21 Apr 2014 14:47:13 +0000 (+0900) Subject: (split) LDP: Update draft and release (from the previous commit) X-Git-Tag: LDP-3.64-final X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=refs%2Ftags%2FLDP-3.64-final;p=linuxjm%2FLDP_man-pages.git (split) LDP: Update draft and release (from the previous commit) --- diff --git a/draft/man3/termios.3 b/draft/man3/termios.3 index 5e16c5a7..4a7b539b 100644 --- a/draft/man3/termios.3 +++ b/draft/man3/termios.3 @@ -484,37 +484,30 @@ LNEXT も効果を持つ)。 \fBread\fP(2) は最大でも 1行の入力しか が完了する条件が決定される。4種類の場合がある: .TP MIN == 0, TIME == 0 (polling read) -If data is available, \fBread\fP(2) returns immediately, with the lesser of -the number of bytes available, or the number of bytes requested. If no data -is available, \fBread\fP(2) returns 0. +データが利用可能であれば、 \fBread\fP(2) はすぐに返る。このときの返り値は、そのとき利用可能なバイト数か \fBread\fP(2) +の要求バイト数のうち小さい方となる。 利用可能なデータがない場合 \fBread\fP(2) は 0 を返す。 .TP MIN > 0, TIME == 0 (blocking read) -\fBread\fP(2) blocks until MIN bytes are available, and returns up to the -number of bytes requested. +\fBread\fP(2) は、利用可能なデータが MIN バイトに達するまで停止する。返り値は最大でも要求バイト数である。 .TP MIN == 0, TIME > 0 (read with timeout) -TIME specifies the limit for a timer in tenths of a second. The timer is -started when \fBread\fP(2) is called. \fBread\fP(2) returns either when at -least one byte of data is available, or when the timer expires. If the -timer expires without any input becoming available, \fBread\fP(2) returns 0. -If data is already available at the time of the call to \fBread\fP(), the call -behaves as though the data was received immediately after the call. +TIME はタイマの上限を規定し、単位は 1/10 秒である。 タイマは \fBread\fP(2) が呼ばれた時点で開始される。 \fBread\fP(2) +が返るのは、少なくとも 1バイトのデータが利用可能となった時点、 またはタイマが時間切れとなった時点である。 +入力が全くなくタイマが時間切れとなった場合、 \fBread\fP(2) は 0 を返す。 \fBread\fP() +の呼び出し時にすでに利用可能なデータがある場合、 その呼び出しは呼び出し直後にそのデータが到着したかのように振る舞う。 .TP MIN > 0, TIME > 0 (read with interbyte timeout) -TIME specifies the limit for a timer in tenths of a second. Once an initial -byte of input becomes available, the timer is restarted after each further -byte is received. \fBread\fP(2) returns when any of the following conditions -is met: +TIME はタイマの上限を規定し、単位は 1/10 秒である。 入力の最初のバイトが利用可能になった後は、 新たに +1バイト受信する度にタイマがリセットされる。 \fBread\fP(2) は以下の条件のいずれかを満たした場合に返る。 .RS .IP * 3 -MIN bytes have been received. +MIN バイトのデータを受信した。 .IP * -The interbyte timer expires. +バイト間タイマーが時間切れになった。 .IP * .\" e.g., Solaris -The number of bytes requested by \fBread\fP(2) has been received. (POSIX does -not specify this termination condition, and on some other implementations -\fBread\fP() does not return in this case.) +\fBread\fP(2) で要求されたバイト数のデータを受信した (POSIX ではこの終了条件は規定されておらず、 他のいくつかの実装では +\fBread\fP() はこの条件では返らない)。 .RE .IP Because the timer is started only after the initial byte becomes available, diff --git a/draft/man5/proc.5 b/draft/man5/proc.5 index 27baef70..edf4919b 100644 --- a/draft/man5/proc.5 +++ b/draft/man5/proc.5 @@ -720,10 +720,9 @@ Writing to \fI/proc/[pid]/oom_score_adj\fP or \fI/proc/[pid]/oom_adj\fP will change the other with its scaled value. .TP \fI/proc/[pid]/root\fP -UNIX and Linux support the idea of a per\-process root of the filesystem, set -by the \fBchroot\fP(2) system call. This file is a symbolic link that points -to the process's root directory, and behaves in the same way as \fIexe\fP, and -\fIfd/*\fP. +UNIX と Linux では、 ファイルシステムのルート (/) をプロセスごとに別々にできる。 これはシステムコール \fBchroot\fP(2) +によって設定する。 このファイルはプロセスのルートディレクトリを指すシンボリックリンクで、 \fIexe\fP や \fIfd/*\fP +などと同じような動作をする。 .\" The following was still true as at kernel 2.6.13 .\" FIXME Describe /proc/[pid]/seccomp @@ -2545,7 +2544,7 @@ kill されるだけかもしれない。 この場合には、カーネルパ \fBifconfig\fP(8), \fBinit\fP(8), \fBlsmod\fP(8), \fBlspci\fP(8), \fBmount\fP(8), \fBnetstat\fP(8), \fBprocinfo\fP(8), \fBroute\fP(8), \fBsysctl\fP(8) -The Linux kernel source files: \fIDocumentation/filesystems/proc.txt\fP +Linux カーネルのソースファイル: \fIDocumentation/filesystems/proc.txt\fP \fIDocumentation/sysctl/fs.txt\fP, \fIDocumentation/sysctl/kernel.txt\fP, \fIDocumentation/sysctl/net.txt\fP, and \fIDocumentation/sysctl/vm.txt\fP. .SH この文書について diff --git a/draft/man7/feature_test_macros.7 b/draft/man7/feature_test_macros.7 index 7b17303d..ac1cab13 100644 --- a/draft/man7/feature_test_macros.7 +++ b/draft/man7/feature_test_macros.7 @@ -133,10 +133,8 @@ ISO 標準の C。 \fBgcc\fP(1) を \fI\-std=c99\fP や \fI\-ansi\fP などの .IP \(bu 値が 199506 以上の場合、 POSIX.1c (スレッド) 関連の定義が追加で公開される。 .IP \(bu -(Since glibc 2.3.3) The value 200112L or greater additionally exposes -definitions corresponding to the POSIX.1\-2001 base specification (excluding -the XSI extension) and also causes C95 (since glibc 2.12) and C99 (since -glibc 2.10) features to be exposed. +(glibc 2.3.3 以降) 値が 200112L 以上の場合、 (XSI 拡張を除く) POSIX.1\-2001 +基本仕様に対応する定義も追加で公開され、また C95 (glibc 2.12 以降) と C99 (glibc 2.10 以降) の機能も公開される。 .IP \(bu (glibc 2.10 以降) 値が 200809L 以上の場合、 (XSI 拡張を除く) POSIX.1\-2008 基本仕様に対応する定義が追加で公開される。 @@ -201,8 +199,8 @@ definitions. (The primary change in C95 was support for international character sets.) .TP \fB_ISOC11_SOURCE\fP (glibc 2.16 以降) -Exposes declarations consistent with the ISO C11 standard. Defining this -macro also enables C99 and C95 features (like \fB_ISOC99_SOURCE\fP). +ISO C11 標準に準拠した宣言を公開する。 このマクロを定義すると (\fB_ISOC99_SOURCE\fP 同様) C99 と C95 +の機能も有効になる。 .TP \fB_LARGEFILE64_SOURCE\fP LFS (Large File Summit) により "暫定拡張 (transitional extension)" Single UNIX diff --git a/draft/man7/inotify.7 b/draft/man7/inotify.7 index c15071b5..14a6e777 100644 --- a/draft/man7/inotify.7 +++ b/draft/man7/inotify.7 @@ -330,12 +330,10 @@ Linux 2.6.25 以降では、シグナル駆動 (signal\-driven) I/O の通知が inotify ファイルディスクリプタ番号が、 \fIsi_signo\fP にはシグナル番号が、 \fIsi_code\fP には \fBPOLL_IN\fP が、 \fIsi_band\fP には \fBPOLLIN\fP が設定される。 -If successive output inotify events produced on the inotify file descriptor -are identical (same \fIwd\fP, \fImask\fP, \fIcookie\fP, and \fIname\fP), then they are -coalesced into a single event if the older event has not yet been read (but -see BUGS). This reduces the amount of kernel memory required for the event -queue, but also means that an application can't use inotify to reliably -count file events. +inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 (\fIwd\fP, \fImask\fP, +\fIcookie\fP, \fIname\fP が等しい場合)、 前のイベントがまだ読み込まれていなければ、 連続するイベントが 1 つのイベントにまとめられる +(ただし「バグ」の節も参照のこと)。 これによりイベントキューに必要なカーネルメモリ量が減るが、 +これはまたアプリケーションがファイルイベント数を信頼性を持って数えるのに inotify を使用できないということでもある。 inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で @@ -368,13 +366,11 @@ inotify によるディレクトリの監視は再帰的に行われない: あ サブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。 大きなディレクトリツリーの場合には、この作業にかなり時間がかかることがある。 -If monitoring an entire directory subtree, and a new subdirectory is created -in that tree or an existing directory is renamed into that tree, be aware -that by the time you create a watch for the new subdirectory, new files (and -subdirectories) may already exist inside the subdirectory. Therefore, you -may want to scan the contents of the subdirectory immediately after adding -the watch (and, if desired, recursively add watches for any subdirectories -that it contains). +ディレクトリツリー全体を監視していて、 そのツリー内に新しいサブディレクトリが作成されるか、 +既存のディレクトリが名前が変更されそのツリー内に移動した場合、 新しいサブディレクトリに対する watch を作成するまでに、 新しいファイル +(やサブディレクトリ) がそのサブディレクトリ内にすでに作成されている場合がある点に注意すること。 したがって、watch +を追加した直後にサブディレクトリの内容をスキャンしたいと思う場合もあるだろう (必要ならそのサブディレクトリ内のサブディレクトリに対する watch +も再帰的に追加することもあるだろう)。 Note that the event queue can overflow. In this case, events are lost. Robust applications should handle the possibility of lost events diff --git a/draft/man7/man-pages.7 b/draft/man7/man-pages.7 new file mode 100644 index 00000000..f93cb45b --- /dev/null +++ b/draft/man7/man-pages.7 @@ -0,0 +1,677 @@ +.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler +.\" (faith@cs.unc.edu and dwheeler@ida.org) +.\" and (C) Copyright 2007 Michael Kerrisk +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" 2007-05-30 created by mtk, using text from old man.7 plus +.\" rewrites and additional text. +.\" +.\"******************************************************************* +.\" +.\" This file was generated with po4a. Translate the source file. +.\" +.\"******************************************************************* +.\" +.\" Japanese Version Copyright (c) 2007 Akihiro MOTOKI +.\" all rights reserved. +.\" Translated 2007-06-13, Akihiro MOTOKI , LDP v2.54 +.\" Updated 2007-07-04, Akihiro MOTOKI , LDP v2.59 +.\" Updated 2007-09-03, Akihiro MOTOKI , LDP v2.64 +.\" Updated 2008-08-09, Akihiro MOTOKI , LDP v3.05 +.\" Updated 2013-05-04, Akihiro MOTOKI +.\" Updated 2013-07-24, Akihiro MOTOKI +.\" Updated 2013-08-21, Akihiro MOTOKI , LDP v3.53 +.\" +.TH MAN\-PAGES 7 2014\-03\-16 Linux "Linux Programmer's Manual" +.SH 名前 +man\-pages \- Linux の man ページを書く際の決まり事 +.SH 書式 +\fBman\fP [\fIsection\fP] \fItitle\fP +.SH 説明 +このページでは、 Linux \fIman\-pages\fP プロジェクトのマニュアルページを書く際に 従うべき決まり事について説明する。 Linux +\fIman\-pages\fP プロジェクトは Linux カーネルおよび GNU C ライブラリが提供するユーザ空間 API +のドキュメント作成を行っている。Linux システムのマニュアルページのセクション 2 のページのほとんどと、セクション 3, 4, 5, 7 +の多くのページが、このプロジェクトにより提供されている。このページで説明されている決まり事は、他のプロジェクトの +マニュアルページを書く作者にも役立つことだろう。 +.SS マニュアルページのセクション +.PP +マニュアルのセクションは、習慣的に以下のような定義が用いられている: +.TP 10 +\fB1 コマンド (プログラム)\fP +シェルの中からユーザが実行できるコマンド。 +.TP +\fB2 システムコール\fP +カーネルが処理しなければならない関数。 +.TP +\fB3 ライブラリコール\fP +\fIlibc\fP の関数の大部分。 +.TP +\fB4 スペシャルファイル (デバイス)\fP +\fI/dev\fP 以下にあるファイル。 +.TP +\fB5 ファイルのフォーマットと規約\fP +\fI/etc/passwd\fP などの人が読めるファイルのフォーマット。 +.TP +\fB6 ゲーム\fP +.TP +\fB7 概要、約束事、その他\fP +様々な事柄の概要、慣習、プロトコル、文字集合の規格、その他雑多なこと。 +.TP +\fB8 システム管理コマンド\fP +.\" .TP +.\" .B 9 Kernel routines +.\" This is an obsolete manual section. +.\" Once it was thought a good idea to document the Linux kernel here, +.\" but in fact very little has been documented, and the documentation +.\" that exists is outdated already. +.\" There are better sources of +.\" information for kernel developers. +\fBmount\fP(8) のような root のみが実行可能なコマンド。 +.SS マクロパッケージ +新しいマニュアルページは \fBman\fP(7) で説明されている \fBgroff an.tmac\fP パッケージを使って記述すべきである。 +この方針は一貫性の確保が主な理由である。既存の Linux のマニュアルページ の圧倒的多数がこれらのマクロを使って記述されている。 +.SS ソースファイルの配置に関する決まり事 +マニュアルページのソースコードの 1行の長さは 可能な限り 75文字を越えないようにしてほしい。 こうすることで、パッチをメール本文に載せて送る場合に、 +メールクライアントによる行折り返しを回避することができる。 + +新しい文は行頭から開始する。 これにより、パッチの内容を確認しやすくなる。 パッチは文単位であることが多いからである。 +.SS タイトル行 +man ページの最初の行は \fBTH\fP コマンドにすべきである。 +.RS +.sp +\fB\&.TH\fP \fItitle section date source manual\fP +.sp +.RE +個々の説明: +.RS +.TP 10 +\fItitle\fP +man ページのタイトル。全部大文字で記載する (例: \fIMAN\-PAGES\fP)。 +.TP +\fIsection\fP +man ページが属するセクション番号 (例: \fI7\fP)。 +.TP +\fIdate\fP +最新のリビジョンの日付\(emman ページに些細でない変更を加えたときには必ずこれを変更すること。 日付は YYYY\-MM\-DD +の形式で記載すべきである。 +.TP +\fIsource\fP +コマンド、関数、システムコールの出自。 + +数少ないセクション 1 と 8 のページの場合、おそらく単に \fIGNU\fP とだけ書くことが多いだろう。 + +システムコールの場合、単に \fILinux\fP とだけ書く。 (以前の慣習では、マニュアルページを記載した/内容を確認したカーネルの +バージョン番号を記載していた。しかし、バージョン番号が実際の内容と 一致していることはなく、そのためバージョン番号がないよりも +おそらく悪い形になっていた。 今後は、バージョン番号を含めるのは避けること。) + +glibc のライブラリコールや その他の一般的な GNU ライブラリのライブラリコールの場合、 単に \fIGNU C Library\fP, \fIGNU\fP +と書くか、空の文字列を使う。 + +セクション 4 のページでは \fILinux\fP を使う。 + +よくわからない場合は、 \fILinux\fP とか \fIGNU\fP と書いておく。 +.TP +\fImanual\fP +マニュアルのタイトル (例: \fIman\-pages\fP パッケージのセクション 2 および 3 のページの場合には、 \fILinux +Programmer's Manual\fP を使うこと)。 +.RE +.SS マニュアルページのセクション +昔から使われてきたセクション名を以下のリストに示す。 これらを使うと良いだろう。 一般的に、マニュアルページは、少なくとも \fB色つき\fP +のセクションを持つのが望ましい。 新しくマニュアルページを作成する際には、だいたい以下のリストに示した 順序でセクションを配置するようにしてもらいたい。 +.in +0.5i +.nf + +.\" May 07: Few current man pages have an ERROR HANDLING section,,, +.\" ERROR HANDLING, +.\" May 07: Almost no current man pages have a USAGE section,,, +.\" USAGE, +.\" DIAGNOSTICS, +.\" May 07: Almost no current man pages have a SECURITY section,,, +.\" SECURITY, +.\" AUTHORS sections are discouraged +.\" AUTHORS [Discouraged] +\fB名前\fP +\fB書式\fP +設定 [通常はセクション 4 のみ] +\fB説明\fP +オプション [通常はセクション 1, 8 のみ] +終了ステータス [通常はセクション 1, 8 のみ] +返り値 [通常はセクション 2, 3 のみ] +エラー [たいていはセクション 2, 3 のみ] +環境変数 +ファイル +バージョン [通常はセクション 2, 3 のみ] +属性 [通常はセクション 2, 3 のみ] +準拠 +注意/備考 +バグ +例 +\fB関連項目\fP + +.fi +.in +「伝統的に使われてきた見出しが使える場合には、それを使ってほしい。」 この種の一貫性を保つことで、情報を理解しやすくなるからである。 +どうしても必要な場合には、理解しやすくなるように独自の見出しを 作ってもよい (特にセクション 4 や 5 のページではこうした方が +わかりやすくなる)。ただし、そうする前に、伝統的な見出しを使い、 そのセクション内にサブセクション (\fI.SS\fP) を設けることで +対応できないか考えてほしい。 + +以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。 +.TP 14 +\fB名前 (NAME)\fP +マニュアルページの名前。 \fB.SH NAME\fP コマンドの後に続ける行の重要な情報については \fBman\fP(7) を参照。この行のすべての単語は +("\e\-" の直後の単語も含め) 小文字にすべきである。但し、英語や技術用語の慣例として別の記載をする場合はこの限りではない。 +.TP +\fB書式 (SYNOPSIS)\fP +コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。 +そのまま書くテキストにはボールド体を用い、置き換える引き数には イタリック体を用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒 +(|) で区切り、繰り返しには省略符号 (...) を書く。 関数に対しては、必要なデータ宣言や \fB#include\fP 指定を書き、関数宣言を続ける。 + +.\" FIXME . Say something here about compiler options +ヘッダファイルから関数 (や変数) の定義を得るために 機能検査マクロ (feature test macro) を定義しなければならない場合、 書式 +(SYNOPSIS) に必要な機能検査マクロを記載すべきである。 機能検査マクロについては \fBfeature_test_macros\fP(7) +で説明されている。 +.TP +\fBCONFIGURATION\fP +デバイスの設定詳細。 通常、このセクションは 4 章のマニュアルページでのみ登場する。 +.TP +\fB説明 (DESCRIPTION)\fP +.\" If there is some kind of input grammar or complex set of subcommands, +.\" consider describing them in a separate +.\" .B USAGE +.\" section (and just place an overview in the +.\" .B DESCRIPTION +.\" section). +プログラム・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を +どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。 +通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 \fBオプション\fP のセクションを用いる。 + +システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際は、 変更が取り込まれたカーネルや C +ライブラリのバージョンを注記に入れるように気を付けること。 フラグにこの情報の注記を入れる方法としては、推奨される方法は、 以下のように \fB.TP\fP +リストの一部にすることである (この例はシステムコールの新しいフラグの場合)。 +.RS 22 +.TP + \fBXYZ_FLAG\fP (Linux 3.7 以降) +フラグの説明... +.RE +.IP +バージョン情報を入れておくのは、 古いバージョンのカーネルや C ライブラリを使わざるを得ないユーザにとって、 特に有用である +(例えば、組み込みシステムではよくあることである)。 +.TP +\fBオプション (OPTIONS)\fP +.\" .TP +.\" .B USAGE +.\" describes the grammar of any sublanguage this implements. +プログラムが受け付けるコマンドライン・オプションと、 その場合プログラムの振舞いがどう変わるかを説明する。 このセクションはセクション 1 と 8 +のマニュアルページにだけ登場すべきである。 +.TP +\fB終了ステータス (EXIT STATUS)\fP +プログラムの終了ステータスの値と、それらの値に対応する状況を列挙する。 このセクションはセクション 1 と 8 +のマニュアルページにだけ登場すべきである。 +.TP +\fB返り値 (RETURN VALUE)\fP +セクション 2 と 3 のページの場合、このセクションに ライブラリルーチンが呼び出し元に返す値のリストを記載する。 +それらの値が返された場合の状態に対する説明も書く。 +.TP +\fBエラー (ERRORS)\fP +セクション 2 と 3 のマニュアルページでは、 エラーが発生した場合に \fIerrno\fP に設定される可能性がある値のリストを記載する。 +リストには、エラーの値とエラーの原因についての情報を書く。 「エラーリストはアルファベット順にすべきである。」 +.TP +\fB環境変数 (ENVIRONMENT)\fP +プログラムや関数に影響する環境変数をリストし、それらの効果を書く。 +.TP +\fBファイル (FILES)\fP +.\" May 07: Almost no current man pages have a DIAGNOSTICS section; +.\" "RETURN VALUE" or "EXIT STATUS" is preferred. +.\" .TP +.\" .B DIAGNOSTICS +.\" gives an overview of the most common error messages and how to +.\" cope with them. +.\" You don't need to explain system error messages +.\" or fatal signals that can appear during execution of any program +.\" unless they're special in some way to the program. +.\" +.\" May 07: Almost no current man pages have a SECURITY section. +.\".TP +.\".B SECURITY +.\"discusses security issues and implications. +.\"Warn about configurations or environments that should be avoided, +.\"commands that may have security implications, and so on, especially +.\"if they aren't obvious. +.\"Discussing security in a separate section isn't necessary; +.\"if it's easier to understand, place security information in the +.\"other sections (such as the +.\" .B DESCRIPTION +.\" or +.\" .B USAGE +.\" section). +.\" However, please include security information somewhere! +プログラムや関数が用いるファイルを列記する。 例えば、設定ファイル、起動ファイル、プログラムが直接操作するファイルなどである。 +これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インストール処理で変更できるようにする。 +多くのプログラムではデフォルトのインストール先は \fI/usr/local\fP である。したがってベースとなるマニュアルページでも +\fI/usr/local\fP が使われていることが多いだろう。 +.TP +\fB属性 (ATTRIBUTES)\fP +そのページで説明している関数の種々の属性の概要を、サブセクションに分けて説明する。以下のサブセクションが定義されている。 +.sp +.RS +.TP +\fBマルチスレッディング (pthreads(7) 参照)\fP +このサブセクションでは、マルチスレッドアプリケーションに関連する属性について説明する。 +.RS +.IP * 3 +その関数がスレッドセーフかどうか。 +.IP * +その関数が取り消しポイント (cancellation point) かどうか。 +.IP * +その関数が非同期で安全にキャンセルできるか (async\-cancel\-safe かどうか)。 +.RE +.IP +これらの属性の詳細は \fBpthreads\fP(7) で説明されている。 +.RE +.TP +\fBバージョン (VERSIONS)\fP +システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カーネルや glibc のバージョンについての簡潔な概要。 +一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきである。 +残念なことに、多くの既存のマニュアルページにこの情報は含まれていない (これらのページが書かれた時点ではそのようなポリシーはなかったからである)。 +これを改善するパッチは歓迎されるが、 新しいコードを書くプログラマの観点からすれば、 おそらくこの情報が重要になるのは、 Linux 2.4 +以降で追加されたカーネルインターフェイス (カーネル 2.2 からの変更) と glibc バージョン 2.1 以降で追加されたライブラリ関数 +(glibc 2.0 からの変更) についてのみであろう。 + +\fBsyscalls\fP(2) マニュアルページにも、いろいろなシステムコールが初めて登場した カーネルバージョンについての情報が書かれている。 +.TP +\fB準拠 (CONFORMING TO)\fP +そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習について記載する。 様々な標準を示すのに適した用語は +\fBstandards\fP(7) に見出しでリストになっている。 セクション 2 や 3 のページでは、このセクションで システムコールや関数が準拠する +POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG などの他の標準規格や、SVr4 や +4.xBSD の実装標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1 の現行バージョンで規定されていない場合以外は、 +あまり深く気にする必要はない。) (\fBstandards\fP(7) 参照。) + +そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨を記載すること。 そのコールが Linux +固有の場合は、その旨を記載すること。 + +(そうなっているページが多いが) このセクションの内容が標準のリスト だけの場合、リストの最後にピリオド (\(aq.\(aq) を置くこと。 +.TP +\fB注意 (NOTES)\fP +その他の注意点を書く。 セクション 2 と 3 のマニュアルページでは、 \fILinux での注意 (Linux Notes)\fP や \fIglibc +での注意 (Glibc Notes)\fP という名前のサブセクション (\fBSS\fP) を設けると便利なこともある。 +.TP +\fBバグ (BUGS)\fP +制限・知られている欠陥や不便な点、その他不思議な動作などを書く。 +.TP +\fB例 (EXAMPLE)\fP +この関数・ファイル・コマンドをどのように使うかを示した ひとつまたは複数の例を記述する。 サンプルプログラムを書く際の詳細は +以下の「サンプルプログラム」の節を参照のこと。 +.TP +\fB著者 (AUTHORS)\fP +文書またはプログラムの著者を列記する。 \fB著者セクションは極力使用しないこと。\fP 一般的には、著者のリストを各ページに撒き散らさない方がよい +(時間がたつと、作者のリストは膨大になる可能性がある)。 マニュアルページを新規に書いたり、大幅に修正を行った場合には、 +ソースファイルにコメントとして著作権表示を追加すること。 あなたがデバイスドライバの作者で、バグを報告するためのアドレスを +載せたい場合は、「バグ」セクションの後ろにこのセクションを配置すること。 +.TP +\fB関連項目 (SEE ALSO)\fP +関連するマニュアルページを、コンマ区切りのリストで、 セクション番号順に、セクション内ではアルファベット順で記載する。 可能なら関連する他の文書も書く。 +慣習では、このセクションは最後に置く。 リストの末尾にピリオドを置かないこと。 +.IP +関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP +(ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。 +.SH "STYLE GUIDE" +The following subsections describe the preferred style for the \fIman\-pages\fP +project. For details not covered below, the Chicago Manual of Style is +usually a good source; try also grepping for preexisting usage in the +project source tree. +.SS "Use of gender\-neutral language" +As far as possible, use gender\-neutral language in the text of man pages. +Use of "they" ("them", "themself", "their") as a gender\-neutral singular +pronoun is acceptable. +.SS フォントの慣習 +.PP +関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」 +関数の他の部分はボールドを指定する: +.PP +\fB int myfunction(int \fP\fIargc\fP\fB, char **\fP\fIargv\fP\fB);\fP +.PP +引き数名といった変数名はイタリック体を指定すべきである。 +.PP +ファイル名 (パス名、またはヘッダーファイルへの参照) は常にイタリック体にする (例: \fI\fP)。 ただし、書式 +(SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: \fB#include \fP)。 +標準のインクルードヘッダファイルを参照する際は、 通常の C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例： +\fI\fP)。 +.PP +通常、大文字で表現する特殊マクロはボールドで表す (例えば \fBMAXINT\fP)。 例外として NULL はボールドにしない。 +.PP +エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 \fB\&.TP\fP マクロを用いる)。 +.PP +完全なコマンドは、長い場合には、例に示すように 字下げした行にコマンドだけを記載し、コマンドの前後には空行を置くべきである。 +.in +4n +.nf + +man 7 man\-pages + +.fi +.in +コマンドが短い場合は、 \fIman 7 man\-pages\fP のようにイタリック体で文中に埋め込んで記載してもよい。 +この場合、コマンド内の適切な位置に、改行できないスペース ("\e\ ") を使うとよいかもしれない。 コマンドオプションも (\fI\-l\fP のように) +イタリック体で記載すべきである。 +.PP +式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。 繰り返しになるが、式を通常の文中に埋め込む場合にも、 +改行できないスペースを使うとよいだろう。 +.PP +そのマニュアルページの説明対象への参照は、ボールドで名前を記載する。 対象が関数 (つまり、セクション 2 や 3 のページ) の場合、 +名前の後ろにローマンフォント (通常のフォント) で丸括弧の対を続ける。 例えば、 \fBfcntl\fP(2) のマニュアルページでは、説明対象への参照は +\fBfcntl\fP() のように記載する。 マニュアルページのソースファイルには次のように記載するのが望ましい: +.nf + + .BR fcntl () + +.fi +("\efB...\efP()" よりも、この形式を使うこと。 これにより、マニュアルページのソースファイルを解釈するツールを 書くのが簡単になる。) +.PP +別のマニュアルページへの参照は、ボールドで名前を記載し、 それに続けてセクション番号を「必ず」書く。セクション番号は ローマンフォント +(通常のフォント) で書き、スペースは入れない (例: \fBintro\fP(2))。 マニュアルページのソースファイルには次のように記載するのが望ましい: +.nf + + .BR intro (2) + +.fi +(相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。) + +Control characters should be written in bold face, with no quotes; for +example, \fB^X\fP. +.SS "綴り (spelling)" +リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている +(以前はイギリス英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に従って下さい。 + +Aside from the well\-known spelling differences, there are a few other +subtleties to watch for: +.IP * 3 +American English tends to use the forms "backward", "upward", "toward", and +so on rather than the British forms "backwards", "upwards", "towards", and +so on. +.SS "BSD version numbers" +The classical scheme for writing BSD version numbers is \fIx.yBSD\fP, where +\fIx.y\fP is the version number (e.g., 4.2BSD). Avoid forms such as \fIBSD +4.3\fP. +.SS 大文字表記 +サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞) +やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。 + +\&.SS Unicode under Linux + +.SS 構造体の定義、シェルのセッションログなどの字下げ、など +構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と +\&\fI.in\fP で囲む)。 +.SS "Preferred terms" +The following table lists some preferred terms to use in man pages, mainly +to ensure consistency across pages. +.TS +l l l +--- +l l l. +用語 使用を避ける単語 備考 + +bit mask bitmask +built\-in builtin +Epoch epoch T{ +For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) +T} +filename file name +filesystem file system +hostname host name +inode i\-node +lowercase lower case, lower\-case +pathname path name +pseudoterminal pseudo\-terminal +privileged port T{ +reserved port, +system port +T} +real\-time T{ +realtime, +real time +T} +run time runtime +saved set\-group\-ID T{ +saved group ID, +saved set\-GID +T} +saved set\-user\-ID T{ +saved user ID, +saved set\-UID +T} +set\-group\-ID set\-GID, setgid +set\-user\-ID set\-UID, setuid +superuser T{ +super user, +super\-user +T} +superblock T{ +super block, +super\-block +T} +timestamp time stamp +timezone time zone +uppercase upper case, upper\-case +usable useable +user space userspace +username user name +zeros zeroes +.TE +.PP +See also the discussion \fIHyphenation of attributive compounds\fP below. +.SS "Terms to avoid" +The following table lists some terms to avoid using in man pages, along with +some suggested alternatives, mainly to ensure consistency across pages. +.TS +l l l +--- +l l l. +Avoid Use instead Notes + +32bit 32\-bit T{ +same for 8\-bit, 16\-bit, etc. +T} +current process calling process T{ +A common mistake made by kernel programmers when writing man pages +T} +manpage T{ +man page, manual page +T} +minus infinity negative infinity +non\-root unprivileged user +non\-superuser unprivileged user +nonprivileged unprivileged +OS operating system +plus infinity positive infinity +pty pseudoterminal +tty terminal +Unices UNIX systems +Unixes UNIX systems +.TE +.SS 商標 +Use the correct spelling and case for trademarks. The following is a list +of the correct spellings of various relevant trademarks that are sometimes +misspelled: + + DG/UX + HP\-UX + UNIX + UnixWare +.SS "NULL, NUL, null pointer, and null character" +A \fInull pointer\fP is a pointer that points to nothing, and is normally +indicated by the constant \fINULL\fP. On the other hand, \fINUL\fP is the \fInull +byte\fP, a byte with the value 0, represented in C via the character constant +\fI\(aq\e0\(aq\fP. + +The preferred term for the pointer is "null pointer" or simply "NULL"; avoid +writing "NULL pointer". + +The preferred term for the byte is "null byte". Avoid writing "NUL", since +it is too easily confused with "NULL". Avoid also the terms "zero byte" and +"null character". The byte that terminates a C string should be described +as "the terminating null byte"; strings may be described as +"null\-terminated", but avoid the use of "NUL\-terminated". +.SS ハイパーリンク +For hyperlinks, use the \fI.UR\fP/\fI.UE\fP macro pair (see \fBgroff_man\fP(7)). +This produces proper hyperlinks that can be used in a web browser, when +rendering a page with, say: + + BROWSER=firefox man \-H pagename +.SS "Use of e.g., i.e., etc., a.k.a., and similar" +In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", +"a.k.a." should be avoided, in favor of suitable full wordings ("for +example", "that is", "and so on", "also known as"). + +The only place where such abbreviations may be acceptable is in \fIshort\fP +parenthetical asides (e.g., like this one). + +Always include periods in such abbreviations, as shown here. In addition, +"e.g." and "i.e." should always be followed by a comma. +.SS Em\-dashes +The way to write an em\-dash\(emthe glyph that appears at either end of this +subphrase\(emin *roff is with the macro "\e(em". (On an ASCII terminal, an +em\-dash typically renders as two hyphens, but in other typographical +contexts it renders as a long dash.) Em\-dashes should be written \fIwithout\fP +surrounding spaces. +.SS "Hyphenation of attributive compounds" +Compound terms should be hyphenated when used attributively (i.e., to +qualify a following noun). Some examples: + + 32\-bit value + command\-line argument + floating\-point number + run\-time check + user\-space function + wide\-character string +.SS "Hyphenation with multi, non, pre, re, sub, and so on" +The general tendency in modern English is not to hyphenate after prefixes +such as "multi", "non", "pre", "re", "sub", and so on. Manual pages should +generally follow this rule when these prefixes are used in natural English +constructions with simple suffixes. The following list gives some examples +of the preferred forms: + + interprocess + multithreaded + multiprocess + nonblocking + nondefault + nonempty + noninteractive + nonnegative + nonportable + nonzero + preallocated + precreate + prerecorded + reestablished + reinitialize + rearm + reread + subcomponent + subdirectory + subsystem + +Hyphens should be retained when the prefixes are used in nonstandard English +words, with trademarks, proper nouns, acronyms, or compound terms. Some +examples: + + non\-ASCII + non\-English + non\-NULL + non\-real\-time + +Finally, note that "re\-create" and "recreate" are two different verbs, and +the former is probably what you want. +.SS "Real minus character" +Where a real minus character is required (e.g., for numbers such as \-1, or +when writing options that have a leading dash, such as in \fIls\ \-l\fP), use +the following form in the man page source: + + \e\- + +This guideline applies also to code examples. +.SS "Character constants" +To produce single quotes that render well in both ASCII and UTF\-8, use the +following form for character constants in the man page source: + + \e(aqC\e(aq + +where \fIC\fP is the quoted character. This guideline applies also to +character constants used in code examples. +.SS サンプルプログラムとシェルのセッション +マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。 +.IP * 3 +サンプルプログラムは C で記載すること。 +.IP * +サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合にだけ +必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。 +.IP * +サンプルプログラムはかなり短めにすること (100行未満が望ましく、50行未満が理想的である)。 +.IP * +サンプルプログラムでは、システムコールやライブラリ関数を呼び出した後で エラーチェックを行うこと。 +.IP * +サンプルプログラムは完結していて、 \fIcc\ \-Wall\fP でコンパイルした際に警告なしでコンパイルできること。 +.IP * +可能かつ適切な場合には、サンプルプログラムで 入力により動作を変化させるなどの実験を行うとよい +(理想的には、コマンドライン引き数や、プログラムが読み込む入力データ 経由で、動作を変化させるのがよい)。 +.IP * +サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文字で行う。 (ソースコードで +TAB 文字を使うのは避けること。) +.IP * +For consistency, all example programs should terminate using either of: + + exit(EXIT_SUCCESS); + exit(EXIT_FAILURE); + +Avoid using the following forms to terminate a program: + + exit(0); + exit(1); + return n; +.IP * +If there is extensive explanatory text before the program source code, mark +off the source code with a susbsection heading \fIProgram source\fP, as in: + +\&.SS プログラムのソース + +Always do this if the explanatory text includes a shell session log. +.PP +プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、 +.IP * 3 +セッションログをソースコードの前に置くこと +.IP * +セッションログをスペース 4 つで字下げすること +.IP * +ユーザの入力文をボールドにして、システムが生成する出力と区別できるようにすること +.PP +サンプルプログラムがどんな風になっていればよいかの例については、 \fBwait\fP(2) と \fBpipe\fP(2) を参照すること。 +.SH 例 +\fIman\-pages\fP パッケージに含まれるマニュアルページの体裁の標準的な例については、 \fBpipe\fP(2) と \fBfcntl\fP(2) +を参照すること。 +.SH 関連項目 +\fBman\fP(1), \fBman2html\fP(1), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7), +\fBmdoc\fP(7) +.SH この文書について +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.64 の一部 +である。プロジェクトの説明とバグ報告に関する情報は +http://www.kernel.org/doc/man\-pages/ に書かれている。 diff --git a/release/man3/termios.3 b/release/man3/termios.3 index 5e16c5a7..4a7b539b 100644 --- a/release/man3/termios.3 +++ b/release/man3/termios.3 @@ -484,37 +484,30 @@ LNEXT も効果を持つ)。 \fBread\fP(2) は最大でも 1行の入力しか が完了する条件が決定される。4種類の場合がある: .TP MIN == 0, TIME == 0 (polling read) -If data is available, \fBread\fP(2) returns immediately, with the lesser of -the number of bytes available, or the number of bytes requested. If no data -is available, \fBread\fP(2) returns 0. +データが利用可能であれば、 \fBread\fP(2) はすぐに返る。このときの返り値は、そのとき利用可能なバイト数か \fBread\fP(2) +の要求バイト数のうち小さい方となる。 利用可能なデータがない場合 \fBread\fP(2) は 0 を返す。 .TP MIN > 0, TIME == 0 (blocking read) -\fBread\fP(2) blocks until MIN bytes are available, and returns up to the -number of bytes requested. +\fBread\fP(2) は、利用可能なデータが MIN バイトに達するまで停止する。返り値は最大でも要求バイト数である。 .TP MIN == 0, TIME > 0 (read with timeout) -TIME specifies the limit for a timer in tenths of a second. The timer is -started when \fBread\fP(2) is called. \fBread\fP(2) returns either when at -least one byte of data is available, or when the timer expires. If the -timer expires without any input becoming available, \fBread\fP(2) returns 0. -If data is already available at the time of the call to \fBread\fP(), the call -behaves as though the data was received immediately after the call. +TIME はタイマの上限を規定し、単位は 1/10 秒である。 タイマは \fBread\fP(2) が呼ばれた時点で開始される。 \fBread\fP(2) +が返るのは、少なくとも 1バイトのデータが利用可能となった時点、 またはタイマが時間切れとなった時点である。 +入力が全くなくタイマが時間切れとなった場合、 \fBread\fP(2) は 0 を返す。 \fBread\fP() +の呼び出し時にすでに利用可能なデータがある場合、 その呼び出しは呼び出し直後にそのデータが到着したかのように振る舞う。 .TP MIN > 0, TIME > 0 (read with interbyte timeout) -TIME specifies the limit for a timer in tenths of a second. Once an initial -byte of input becomes available, the timer is restarted after each further -byte is received. \fBread\fP(2) returns when any of the following conditions -is met: +TIME はタイマの上限を規定し、単位は 1/10 秒である。 入力の最初のバイトが利用可能になった後は、 新たに +1バイト受信する度にタイマがリセットされる。 \fBread\fP(2) は以下の条件のいずれかを満たした場合に返る。 .RS .IP * 3 -MIN bytes have been received. +MIN バイトのデータを受信した。 .IP * -The interbyte timer expires. +バイト間タイマーが時間切れになった。 .IP * .\" e.g., Solaris -The number of bytes requested by \fBread\fP(2) has been received. (POSIX does -not specify this termination condition, and on some other implementations -\fBread\fP() does not return in this case.) +\fBread\fP(2) で要求されたバイト数のデータを受信した (POSIX ではこの終了条件は規定されておらず、 他のいくつかの実装では +\fBread\fP() はこの条件では返らない)。 .RE .IP Because the timer is started only after the initial byte becomes available, diff --git a/release/man5/proc.5 b/release/man5/proc.5 index 27baef70..edf4919b 100644 --- a/release/man5/proc.5 +++ b/release/man5/proc.5 @@ -720,10 +720,9 @@ Writing to \fI/proc/[pid]/oom_score_adj\fP or \fI/proc/[pid]/oom_adj\fP will change the other with its scaled value. .TP \fI/proc/[pid]/root\fP -UNIX and Linux support the idea of a per\-process root of the filesystem, set -by the \fBchroot\fP(2) system call. This file is a symbolic link that points -to the process's root directory, and behaves in the same way as \fIexe\fP, and -\fIfd/*\fP. +UNIX と Linux では、 ファイルシステムのルート (/) をプロセスごとに別々にできる。 これはシステムコール \fBchroot\fP(2) +によって設定する。 このファイルはプロセスのルートディレクトリを指すシンボリックリンクで、 \fIexe\fP や \fIfd/*\fP +などと同じような動作をする。 .\" The following was still true as at kernel 2.6.13 .\" FIXME Describe /proc/[pid]/seccomp @@ -2545,7 +2544,7 @@ kill されるだけかもしれない。 この場合には、カーネルパ \fBifconfig\fP(8), \fBinit\fP(8), \fBlsmod\fP(8), \fBlspci\fP(8), \fBmount\fP(8), \fBnetstat\fP(8), \fBprocinfo\fP(8), \fBroute\fP(8), \fBsysctl\fP(8) -The Linux kernel source files: \fIDocumentation/filesystems/proc.txt\fP +Linux カーネルのソースファイル: \fIDocumentation/filesystems/proc.txt\fP \fIDocumentation/sysctl/fs.txt\fP, \fIDocumentation/sysctl/kernel.txt\fP, \fIDocumentation/sysctl/net.txt\fP, and \fIDocumentation/sysctl/vm.txt\fP. .SH この文書について diff --git a/release/man7/feature_test_macros.7 b/release/man7/feature_test_macros.7 index 7b17303d..ac1cab13 100644 --- a/release/man7/feature_test_macros.7 +++ b/release/man7/feature_test_macros.7 @@ -133,10 +133,8 @@ ISO 標準の C。 \fBgcc\fP(1) を \fI\-std=c99\fP や \fI\-ansi\fP などの .IP \(bu 値が 199506 以上の場合、 POSIX.1c (スレッド) 関連の定義が追加で公開される。 .IP \(bu -(Since glibc 2.3.3) The value 200112L or greater additionally exposes -definitions corresponding to the POSIX.1\-2001 base specification (excluding -the XSI extension) and also causes C95 (since glibc 2.12) and C99 (since -glibc 2.10) features to be exposed. +(glibc 2.3.3 以降) 値が 200112L 以上の場合、 (XSI 拡張を除く) POSIX.1\-2001 +基本仕様に対応する定義も追加で公開され、また C95 (glibc 2.12 以降) と C99 (glibc 2.10 以降) の機能も公開される。 .IP \(bu (glibc 2.10 以降) 値が 200809L 以上の場合、 (XSI 拡張を除く) POSIX.1\-2008 基本仕様に対応する定義が追加で公開される。 @@ -201,8 +199,8 @@ definitions. (The primary change in C95 was support for international character sets.) .TP \fB_ISOC11_SOURCE\fP (glibc 2.16 以降) -Exposes declarations consistent with the ISO C11 standard. Defining this -macro also enables C99 and C95 features (like \fB_ISOC99_SOURCE\fP). +ISO C11 標準に準拠した宣言を公開する。 このマクロを定義すると (\fB_ISOC99_SOURCE\fP 同様) C99 と C95 +の機能も有効になる。 .TP \fB_LARGEFILE64_SOURCE\fP LFS (Large File Summit) により "暫定拡張 (transitional extension)" Single UNIX diff --git a/release/man7/inotify.7 b/release/man7/inotify.7 index c15071b5..14a6e777 100644 --- a/release/man7/inotify.7 +++ b/release/man7/inotify.7 @@ -330,12 +330,10 @@ Linux 2.6.25 以降では、シグナル駆動 (signal\-driven) I/O の通知が inotify ファイルディスクリプタ番号が、 \fIsi_signo\fP にはシグナル番号が、 \fIsi_code\fP には \fBPOLL_IN\fP が、 \fIsi_band\fP には \fBPOLLIN\fP が設定される。 -If successive output inotify events produced on the inotify file descriptor -are identical (same \fIwd\fP, \fImask\fP, \fIcookie\fP, and \fIname\fP), then they are -coalesced into a single event if the older event has not yet been read (but -see BUGS). This reduces the amount of kernel memory required for the event -queue, but also means that an application can't use inotify to reliably -count file events. +inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 (\fIwd\fP, \fImask\fP, +\fIcookie\fP, \fIname\fP が等しい場合)、 前のイベントがまだ読み込まれていなければ、 連続するイベントが 1 つのイベントにまとめられる +(ただし「バグ」の節も参照のこと)。 これによりイベントキューに必要なカーネルメモリ量が減るが、 +これはまたアプリケーションがファイルイベント数を信頼性を持って数えるのに inotify を使用できないということでもある。 inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で @@ -368,13 +366,11 @@ inotify によるディレクトリの監視は再帰的に行われない: あ サブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。 大きなディレクトリツリーの場合には、この作業にかなり時間がかかることがある。 -If monitoring an entire directory subtree, and a new subdirectory is created -in that tree or an existing directory is renamed into that tree, be aware -that by the time you create a watch for the new subdirectory, new files (and -subdirectories) may already exist inside the subdirectory. Therefore, you -may want to scan the contents of the subdirectory immediately after adding -the watch (and, if desired, recursively add watches for any subdirectories -that it contains). +ディレクトリツリー全体を監視していて、 そのツリー内に新しいサブディレクトリが作成されるか、 +既存のディレクトリが名前が変更されそのツリー内に移動した場合、 新しいサブディレクトリに対する watch を作成するまでに、 新しいファイル +(やサブディレクトリ) がそのサブディレクトリ内にすでに作成されている場合がある点に注意すること。 したがって、watch +を追加した直後にサブディレクトリの内容をスキャンしたいと思う場合もあるだろう (必要ならそのサブディレクトリ内のサブディレクトリに対する watch +も再帰的に追加することもあるだろう)。 Note that the event queue can overflow. In this case, events are lost. Robust applications should handle the possibility of lost events diff --git a/release/man7/man-pages.7 b/release/man7/man-pages.7 index 8146be66..f93cb45b 100644 --- a/release/man7/man-pages.7 +++ b/release/man7/man-pages.7 @@ -43,7 +43,7 @@ .\" Updated 2013-07-24, Akihiro MOTOKI .\" Updated 2013-08-21, Akihiro MOTOKI , LDP v3.53 .\" -.TH MAN\-PAGES 7 2013\-07\-24 Linux "Linux Programmer's Manual" +.TH MAN\-PAGES 7 2014\-03\-16 Linux "Linux Programmer's Manual" .SH 名前 man\-pages \- Linux の man ページを書く際の決まり事 .SH 書式 @@ -113,8 +113,8 @@ man ページのタイトル。全部大文字で記載する (例: \fIMAN\-PAGE man ページが属するセクション番号 (例: \fI7\fP)。 .TP \fIdate\fP -最新のリビジョンの日付\(emman ページに変更を加えたときには 必ずこれを変更すること。 これが最も一般的なバージョン管理方法である。 日付は -YYYY\-MM\-DD の形式で記載すべきである。 +最新のリビジョンの日付\(emman ページに些細でない変更を加えたときには必ずこれを変更すること。 日付は YYYY\-MM\-DD +の形式で記載すべきである。 .TP \fIsource\fP コマンド、関数、システムコールの出自。 @@ -161,8 +161,8 @@ Programmer's Manual\fP を使うこと)。 エラー [たいていはセクション 2, 3 のみ] 環境変数 ファイル -属性 [通常はセクション 2, 3 のみ] バージョン [通常はセクション 2, 3 のみ] +属性 [通常はセクション 2, 3 のみ] 準拠 注意/備考 バグ @@ -301,10 +301,11 @@ Programmer's Manual\fP を使うこと)。 \fBsyscalls\fP(2) マニュアルページにも、いろいろなシステムコールが初めて登場した カーネルバージョンについての情報が書かれている。 .TP \fB準拠 (CONFORMING TO)\fP -そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習について記載する。 セクション 2 や 3 のページでは、このセクションで -システムコールや関数が準拠する POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG -などの他の標準規格や、SVr4 や 4.xBSD の実装標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1 -の現行バージョンで規定されていない場合以外は、 あまり深く気にする必要はない。) (\fBstandards\fP(7) 参照。) +そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習について記載する。 様々な標準を示すのに適した用語は +\fBstandards\fP(7) に見出しでリストになっている。 セクション 2 や 3 のページでは、このセクションで システムコールや関数が準拠する +POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG などの他の標準規格や、SVr4 や +4.xBSD の実装標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1 の現行バージョンで規定されていない場合以外は、 +あまり深く気にする必要はない。) (\fBstandards\fP(7) 参照。) そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨を記載すること。 そのコールが Linux 固有の場合は、その旨を記載すること。 @@ -334,6 +335,15 @@ Programmer's Manual\fP を使うこと)。 .IP 関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP (ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。 +.SH "STYLE GUIDE" +The following subsections describe the preferred style for the \fIman\-pages\fP +project. For details not covered below, the Chicago Manual of Style is +usually a good source; try also grepping for preexisting usage in the +project source tree. +.SS "Use of gender\-neutral language" +As far as possible, use gender\-neutral language in the text of man pages. +Use of "they" ("them", "themself", "their") as a gender\-neutral singular +pronoun is acceptable. .SS フォントの慣習 .PP 関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」 @@ -343,16 +353,16 @@ Programmer's Manual\fP を使うこと)。 .PP 引き数名といった変数名はイタリック体を指定すべきである。 .PP -ファイル名 (パス名、または \fI/usr/include\fP ディレクトリ内のファイルへの参照) は常にイタリック体にする (例: -\fI\fP)。 ただし、書式 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: -\fB#include \fP)。 \fI/usr/include\fP 以下の標準のインクルードファイルを参照する際は、 通常の -C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例： \fI\fP)。 +ファイル名 (パス名、またはヘッダーファイルへの参照) は常にイタリック体にする (例: \fI\fP)。 ただし、書式 +(SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: \fB#include \fP)。 +標準のインクルードヘッダファイルを参照する際は、 通常の C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例： +\fI\fP)。 .PP 通常、大文字で表現する特殊マクロはボールドで表す (例えば \fBMAXINT\fP)。 例外として NULL はボールドにしない。 .PP エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 \fB\&.TP\fP マクロを用いる)。 .PP -完全なコマンドは、長い場合には、例に示すように 字下げした行にコマンドだけを記載すべきである。 +完全なコマンドは、長い場合には、例に示すように 字下げした行にコマンドだけを記載し、コマンドの前後には空行を置くべきである。 .in +4n .nf @@ -361,8 +371,8 @@ man 7 man\-pages .fi .in コマンドが短い場合は、 \fIman 7 man\-pages\fP のようにイタリック体で文中に埋め込んで記載してもよい。 -この場合、コマンド内の適切な位置に、改行できないスペース ("\e\ ") を使うとよいかもしれない。 コマンドオプションも \fI\-l\fP -のようにイタリック体で記載すべきである。 +この場合、コマンド内の適切な位置に、改行できないスペース ("\e\ ") を使うとよいかもしれない。 コマンドオプションも (\fI\-l\fP のように) +イタリック体で記載すべきである。 .PP 式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。 繰り返しになるが、式を通常の文中に埋め込む場合にも、 改行できないスペースを使うとよいだろう。 @@ -385,45 +395,276 @@ man 7 man\-pages .fi (相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。) + +Control characters should be written in bold face, with no quotes; for +example, \fB^X\fP. .SS "綴り (spelling)" -リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている。 新しいページやパッチは全てこの慣習に従って下さい。 +リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている +(以前はイギリス英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に従って下さい。 + +Aside from the well\-known spelling differences, there are a few other +subtleties to watch for: +.IP * 3 +American English tends to use the forms "backward", "upward", "toward", and +so on rather than the British forms "backwards", "upwards", "towards", and +so on. +.SS "BSD version numbers" +The classical scheme for writing BSD version numbers is \fIx.yBSD\fP, where +\fIx.y\fP is the version number (e.g., 4.2BSD). Avoid forms such as \fIBSD +4.3\fP. .SS 大文字表記 サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞) やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。 + +\&.SS Unicode under Linux + +.SS 構造体の定義、シェルのセッションログなどの字下げ、など +構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と +\&\fI.in\fP で囲む)。 +.SS "Preferred terms" +The following table lists some preferred terms to use in man pages, mainly +to ensure consistency across pages. +.TS +l l l +--- +l l l. +用語 使用を避ける単語 備考 + +bit mask bitmask +built\-in builtin +Epoch epoch T{ +For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) +T} +filename file name +filesystem file system +hostname host name +inode i\-node +lowercase lower case, lower\-case +pathname path name +pseudoterminal pseudo\-terminal +privileged port T{ +reserved port, +system port +T} +real\-time T{ +realtime, +real time +T} +run time runtime +saved set\-group\-ID T{ +saved group ID, +saved set\-GID +T} +saved set\-user\-ID T{ +saved user ID, +saved set\-UID +T} +set\-group\-ID set\-GID, setgid +set\-user\-ID set\-UID, setuid +superuser T{ +super user, +super\-user +T} +superblock T{ +super block, +super\-block +T} +timestamp time stamp +timezone time zone +uppercase upper case, upper\-case +usable useable +user space userspace +username user name +zeros zeroes +.TE +.PP +See also the discussion \fIHyphenation of attributive compounds\fP below. +.SS "Terms to avoid" +The following table lists some terms to avoid using in man pages, along with +some suggested alternatives, mainly to ensure consistency across pages. +.TS +l l l +--- +l l l. +Avoid Use instead Notes + +32bit 32\-bit T{ +same for 8\-bit, 16\-bit, etc. +T} +current process calling process T{ +A common mistake made by kernel programmers when writing man pages +T} +manpage T{ +man page, manual page +T} +minus infinity negative infinity +non\-root unprivileged user +non\-superuser unprivileged user +nonprivileged unprivileged +OS operating system +plus infinity positive infinity +pty pseudoterminal +tty terminal +Unices UNIX systems +Unixes UNIX systems +.TE +.SS 商標 +Use the correct spelling and case for trademarks. The following is a list +of the correct spellings of various relevant trademarks that are sometimes +misspelled: + + DG/UX + HP\-UX + UNIX + UnixWare +.SS "NULL, NUL, null pointer, and null character" +A \fInull pointer\fP is a pointer that points to nothing, and is normally +indicated by the constant \fINULL\fP. On the other hand, \fINUL\fP is the \fInull +byte\fP, a byte with the value 0, represented in C via the character constant +\fI\(aq\e0\(aq\fP. + +The preferred term for the pointer is "null pointer" or simply "NULL"; avoid +writing "NULL pointer". + +The preferred term for the byte is "null byte". Avoid writing "NUL", since +it is too easily confused with "NULL". Avoid also the terms "zero byte" and +"null character". The byte that terminates a C string should be described +as "the terminating null byte"; strings may be described as +"null\-terminated", but avoid the use of "NUL\-terminated". +.SS ハイパーリンク +For hyperlinks, use the \fI.UR\fP/\fI.UE\fP macro pair (see \fBgroff_man\fP(7)). +This produces proper hyperlinks that can be used in a web browser, when +rendering a page with, say: + + BROWSER=firefox man \-H pagename +.SS "Use of e.g., i.e., etc., a.k.a., and similar" +In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", +"a.k.a." should be avoided, in favor of suitable full wordings ("for +example", "that is", "and so on", "also known as"). + +The only place where such abbreviations may be acceptable is in \fIshort\fP +parenthetical asides (e.g., like this one). + +Always include periods in such abbreviations, as shown here. In addition, +"e.g." and "i.e." should always be followed by a comma. +.SS Em\-dashes +The way to write an em\-dash\(emthe glyph that appears at either end of this +subphrase\(emin *roff is with the macro "\e(em". (On an ASCII terminal, an +em\-dash typically renders as two hyphens, but in other typographical +contexts it renders as a long dash.) Em\-dashes should be written \fIwithout\fP +surrounding spaces. +.SS "Hyphenation of attributive compounds" +Compound terms should be hyphenated when used attributively (i.e., to +qualify a following noun). Some examples: + + 32\-bit value + command\-line argument + floating\-point number + run\-time check + user\-space function + wide\-character string +.SS "Hyphenation with multi, non, pre, re, sub, and so on" +The general tendency in modern English is not to hyphenate after prefixes +such as "multi", "non", "pre", "re", "sub", and so on. Manual pages should +generally follow this rule when these prefixes are used in natural English +constructions with simple suffixes. The following list gives some examples +of the preferred forms: + + interprocess + multithreaded + multiprocess + nonblocking + nondefault + nonempty + noninteractive + nonnegative + nonportable + nonzero + preallocated + precreate + prerecorded + reestablished + reinitialize + rearm + reread + subcomponent + subdirectory + subsystem + +Hyphens should be retained when the prefixes are used in nonstandard English +words, with trademarks, proper nouns, acronyms, or compound terms. Some +examples: + + non\-ASCII + non\-English + non\-NULL + non\-real\-time + +Finally, note that "re\-create" and "recreate" are two different verbs, and +the former is probably what you want. +.SS "Real minus character" +Where a real minus character is required (e.g., for numbers such as \-1, or +when writing options that have a leading dash, such as in \fIls\ \-l\fP), use +the following form in the man page source: + + \e\- + +This guideline applies also to code examples. +.SS "Character constants" +To produce single quotes that render well in both ASCII and UTF\-8, use the +following form for character constants in the man page source: + + \e(aqC\e(aq + +where \fIC\fP is the quoted character. This guideline applies also to +character constants used in code examples. .SS サンプルプログラムとシェルのセッション マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。 -.TP 3 -* +.IP * 3 サンプルプログラムは C で記載すること。 -.TP -* +.IP * サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合にだけ 必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。 -.TP -* +.IP * サンプルプログラムはかなり短めにすること (100行未満が望ましく、50行未満が理想的である)。 -.TP -* +.IP * サンプルプログラムでは、システムコールやライブラリ関数を呼び出した後で エラーチェックを行うこと。 -.TP -* +.IP * サンプルプログラムは完結していて、 \fIcc\ \-Wall\fP でコンパイルした際に警告なしでコンパイルできること。 -.TP -* +.IP * 可能かつ適切な場合には、サンプルプログラムで 入力により動作を変化させるなどの実験を行うとよい (理想的には、コマンドライン引き数や、プログラムが読み込む入力データ 経由で、動作を変化させるのがよい)。 -.TP -* +.IP * サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文字で行う。 (ソースコードで TAB 文字を使うのは避けること。) +.IP * +For consistency, all example programs should terminate using either of: + + exit(EXIT_SUCCESS); + exit(EXIT_FAILURE); + +Avoid using the following forms to terminate a program: + + exit(0); + exit(1); + return n; +.IP * +If there is extensive explanatory text before the program source code, mark +off the source code with a susbsection heading \fIProgram source\fP, as in: + +\&.SS プログラムのソース + +Always do this if the explanatory text includes a shell session log. +.PP +プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、 +.IP * 3 +セッションログをソースコードの前に置くこと +.IP * +セッションログをスペース 4 つで字下げすること +.IP * +ユーザの入力文をボールドにして、システムが生成する出力と区別できるようにすること .PP サンプルプログラムがどんな風になっていればよいかの例については、 \fBwait\fP(2) と \fBpipe\fP(2) を参照すること。 - -プログラムの使い方や他のシステムの特徴を示すためにシェルのセッション例 を含める場合、ユーザの入力文をボールドにして、システムが生成する -出力と区別できるようにすること。 -.SS 構造体の定義、シェルのセッションログなどの字下げ -構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と -\&\fI.in\fP で囲む)。 .SH 例 \fIman\-pages\fP パッケージに含まれるマニュアルページの体裁の標準的な例については、 \fBpipe\fP(2) と \fBfcntl\fP(2) を参照すること。 @@ -431,6 +672,6 @@ TAB 文字を使うのは避けること。) \fBman\fP(1), \fBman2html\fP(1), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7), \fBmdoc\fP(7) .SH この文書について -この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.54 の一部 +この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.64 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man\-pages/ に書かれている。