draft/man7/inotify.7

   1 .\" t
   2 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" Japanese Version Copyright (c) 2006 Yuichi SATO
  33 .\"     and Copyright (c) 2007-2008 Akihiro MOTOKI
  34 .\" Translated 2006-07-05 by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v2.29
  35 .\" Updated 2006-07-20 by Yuichi SATO, LDP v2.36
  36 .\" Updated 2007-06-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.55
  37 .\" Updated 2008-08-10, Akihiro MOTOKI, LDP v3.05
  38 .\" Updated 2008-09-19, Akihiro MOTOKI, LDP v3.08
  39 .\" Updated 2012-04-30, Akihiro MOTOKI <amotoki@gmail.com>
  40 .\" Updated 2012-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  41 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  42 .\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
  43 .\"
  44 .TH INOTIFY 7 2013\-07\-21 Linux "Linux Programmer's Manual"
  45 .SH 名前
  46 inotify \- ファイルシステムイベントを監視する
  47 .SH 説明
  48 \fIinotify\fP API はファイルシステムイベントを監視するための機構を提供する。 inotify
  49 は個々のファイルやディレクトリを監視するのに使える。 ディレクトリを監視する場合、inotify はディレクトリ自身と
  50 ディレクトリ内のファイルのイベントを返す。
  51
  52 以下のシステムコールがこの API と共に使用される: \fBinotify_init\fP(2)  (や \fBinotify_init1\fP(2)),
  53 \fBinotify_add_watch\fP(2), \fBinotify_rm_watch\fP(2), \fBread\fP(2), \fBclose\fP(2).
  54
  55 \fBinotify_init\fP(2)  は inotify インスタンスを作成し、inotify インスタンスを参照する ファイルディスクリプタを返す。
  56 もっと新しい \fBinotify_init1\fP(2)  も \fBinotify_init\fP(2)  と同様だが、いくつかの追加の機能が提供されている。
  57
  58 \fBinotify_add_watch\fP(2)  は inotify インスタンスに関連づけられた「監視対象 (watch) リスト」を操作する。
  59 監視対象リストの各アイテム ("watch") は、 ファイルまたはディレクトリのパス名と、 そのパス名で参照されるファイルに対して
  60 カーネルが監視する複数のイベントの集合を指定する。 \fBinotify_add_watch\fP(2)
  61 は新しい監視アイテムの作成や既存の監視対象の変更ができる。 各監視対象は一意の「監視対象ディスクリプタ」を持つ。 これは監視対象を作成したときに
  62 \fBinotify_add_watch\fP(2)  から返される整数である。
  63
  64 \fBinotify_rm_watch\fP(2)  は inotify の監視対象リストからアイテムを削除する。
  65
  66 inotify インスタンスを指している 全てのファイルディスクリプタがクローズされた場合、 その下層にあるオブジェクトとそのリソースは、
  67 カーネルで再利用するために解放される。 関連が切られた監視対象は自動的に解放される。
  68
  69 どのようなイベントが起こっていたかを知るには、 アプリケーションで inotify ファイルディスクリプタを \fBread\fP(2)  すればよい。
  70 これまでに何もイベントが起こっていない場合、 停止 (blocking) モードのファイルディスクリプタであれば、 少なくとも 1
  71 つのイベントが起こるまで \fBread\fP(2)  は停止する (シグナルにより割り込まれなかった場合。
  72 シグナルによる割り込みがあった場合、呼び出しはエラー \fBEINTR\fP で失敗する。 \fBsignal\fP(7)  参照)。
  73
  74 \fBread\fP(2)  が成功すると、以下の構造体を 1 つ以上含むバッファが返される:
  75 .in +4n
  76 .nf
  77
  78 .\" FIXME . The type of the 'wd' field should probably be "int32_t".
  79 .\" I submitted a patch to fix this.  See the LKML thread
  80 .\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008
  81 .\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040
  82 struct inotify_event {
  83     int      wd;       /* 監視対象ディスクリプタ */
  84     uint32_t mask;     /* イベントのマスク */
  85     uint32_t cookie;   /* 関連するイベント群を関連づける
  86                           一意なクッキー (rename(2) 用) */
  87     uint32_t len;      /* \(aqname\(aq フィールドのサイズ */
  88     char     name[];   /* NULL で終端された任意の名前 */
  89 };
  90 .fi
  91 .in
  92
  93 \fIwd\fP はイベント発生の監視対象を指定する。 これは、前もって行われた \fBinotify_add_watch\fP(2)
  94 呼び出しで返された監視対象ディスクリプタのうちの 1 つである。
  95
  96 \fImask\fP には発生したイベント (下記参照) を記述するためのビットが含まれる。
  97
  98 \fIcookie\fP は関連するイベントを関連づけるための一意な整数である。
  99 現在のところ、この値は rename イベントに対してのみ使われており、
 100 結果のペアである \fBIN_MOVED_FROM\fP と \fBIN_MOVED_TO\fP イベントを
 101 アプリケーションで関連づけることができる。
 102 他のイベント種別の場合には、 \fIcookie\fP は 0 に設定する。
 103
 104 \fIname\fP フィールドは監視しているディレクトリ内のファイルに対して イベントが返される場合のためにだけ存在する。
 105 監視するディレクトリからのファイルの相対パス名を表す。 このパス名は NULL で終端され、 その後の読み込みで適切なアドレス境界に調整するために、
 106 さらに NULL バイト (\(aq\e0\(aq) が含まれる場合もある。
 107
 108 \fIlen\fP フィールドは NULL バイトを含む \fIname\fP の全てのバイト数を表す。
 109 よって、 \fIinotify_event\fP 構造体のサイズは
 110 \fIsizeof(struct inotify_event)+len\fP である。
 111
 112 \fBread\fP(2) に渡されたバッファが小さすぎて次のイベントに関する情報を返せ
 113 ない場合の動作はカーネルのバージョンにより異なる。 2.6.21 より前のカー
 114 ネルでは、 \fBread\fP(2) は 0 を返す。 2.6.21 以降のカーネルでは、
 115 \fBread\fP(2) はエラー \fBEINVAL\fP で失敗する。
 116 バッファサイズとして
 117
 118     sizeof(struct inotify_event) + NAME_MAX + 1
 119
 120 を指定すれば、少なくとも 1 イベントで読み出しを行うには十分である。
 121 .SS "inotify イベント"
 122 \fBinotify_add_watch\fP(2)  の \fImask\fP 引き数と、inotify ファイル構造体を \fBread\fP(2)
 123 したときに返される \fIinotify_event\fP 構造体の \fImask\fP フィールドは、ともに inotify イベントを識別するための
 124 ビットマスクである。 以下のビットが \fBinotify_add_watch\fP(2)  を呼ぶときの \fImask\fP に指定可能であり、
 125 \fBread\fP(2)  で返される \fImask\fP フィールドで返される:
 126 .RS 4
 127 .sp
 128 .PD 0
 129 .TP  18
 130 \fBIN_ACCESS\fP
 131 ファイルがアクセス (read) された。(*)
 132 .TP
 133 \fBIN_ATTRIB\fP
 134 メタデータが変更された。 メタデータとは、例えば、許可 (permission)、タイムスタンプ、拡張属性、 リンクカウント (Linux 2.6.25
 135 以降)、UID、GID などである。(*)
 136 .TP
 137 \fBIN_CLOSE_WRITE\fP
 138 書き込みのためにオープンされたファイルがクローズされた。(*)
 139 .TP
 140 \fBIN_CLOSE_NOWRITE\fP
 141 書き込み以外のためにオープンされたファイルがクローズされた。(*)
 142 .TP
 143 \fBIN_CREATE\fP
 144 監視対象ディレクトリ内でファイルやディレクトリが作成された。(*)
 145 .TP
 146 \fBIN_DELETE\fP
 147 監視対象ディレクトリ内でファイルやディレクトリが削除された。(*)
 148 .TP
 149 \fBIN_DELETE_SELF\fP
 150 監視対象のディレクトリまたはファイル自身が削除された。
 151 .TP
 152 \fBIN_MODIFY\fP
 153 ファイルが修正された。(*)
 154 .TP
 155 \fBIN_MOVE_SELF\fP
 156 監視対象のディレクトリまたはファイル自身が移動された。
 157 .TP
 158 \fBIN_MOVED_FROM\fP
 159 Generated for the directory containing the old filename when a file is
 160 renamed (*).
 161 .TP
 162 \fBIN_MOVED_TO\fP
 163 Generated for the directory containing the new filename when a file is
 164 renamed (*).
 165 .TP
 166 \fBIN_OPEN\fP
 167 ファイルがオープンされた。(*)
 168 .PD
 169 .RE
 170 .PP
 171 ディレクトリを監視する場合、 上記でアスタリスク (*) を付けたイベントは、 そのディレクトリ内のファイルに対して発生する。 このとき
 172 \fIinotify_event\fP 構造体で返される \fIname\fP フィールドは、ディレクトリ内のファイル名を表す。
 173 .PP
 174 \fBIN_ALL_EVENTS\fP マクロは上記のイベント全てのマスクとして定義される。 このマクロは \fBinotify_add_watch\fP(2)
 175 を呼び出すときの \fImask\fP 引き数として使える。
 176
 177 さらに 2 つの便利なマクロがある。
 178 \fBIN_MOVE\fP は IN_MOVED_FROM|IN_MOVED_TO と同じで、
 179 \fBIN_CLOSE\fP は IN_CLOSE_WRITE|IN_CLOSE_NOWRITE と同じである。
 180 .PP
 181 その他にも以下のビットを \fBinotify_add_watch\fP(2)  を呼ぶときの \fImask\fP に指定できる:
 182 .RS 4
 183 .sp
 184 .PD 0
 185 .TP  18
 186 \fBIN_DONT_FOLLOW\fP
 187 \fIpathname\fP がシンボリックリンクである場合に辿らない。 (Linux 2.6.15 以降)
 188 .TP
 189 \fBIN_EXCL_UNLINK\fP (Linux 2.6.36 以降)
 190 .\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6
 191 デフォルトでは、あるディレクトリの子ファイルに関するイベントを監視 (watch) した際、ディレクトリからその子ファイルが削除 (unlink)
 192 された場合であってもその子ファイルに対してイベントが生成される。このことは、アプリケーションによってはあまり興味のないイベントが大量に発生することにつながる
 193 (例えば、\fI/tmp\fP を監視している場合、たくさんのアプリケーションが、すぐにその名前が削除される一時ファイルをそのディレクトリに作成する)。
 194 \fBIN_EXCL_UNLINK\fP
 195 を指定するとこのデフォルトの動作を変更でき、監視対象のディレクトリから子ファイルが削除された後に子ファイルに関するイベントが生成されなくなる。
 196 .TP
 197 \fBIN_MASK_ADD\fP
 198 \fIpathname\fP に対する監視マスクが既に存在する場合、 (マスクの置き換えではなく) イベントを追加 (OR) する。
 199 .TP
 200 \fBIN_ONESHOT\fP
 201 1 つのイベントについて \fIpathname\fP を監視し、 イベントが発生したら監視対象リストから削除する。
 202 .TP
 203 \fBIN_ONLYDIR\fP (Linux 2.6.15 以降)
 204 \fIpathname\fP がディレクトリの場合にのみ監視する。
 205 .PD
 206 .RE
 207 .PP
 208 以下のビットが \fBread\fP(2)  で返される \fImask\fP フィールドに設定される:
 209 .RS 4
 210 .sp
 211 .PD 0
 212 .TP  18
 213 \fBIN_IGNORED\fP
 214 監視対象が (\fBinotify_rm_watch\fP(2) により) 明示的に 削除された。もしくは (ファイルの削除、またはファイル
 215 システムのアンマウントにより) 自動的に削除された。
 216 .TP
 217 \fBIN_ISDIR\fP
 218 このイベントの対象がディレクトリである。
 219 .TP
 220 \fBIN_Q_OVERFLOW\fP
 221 イベントキューが溢れた (このイベントの場合、\fIwd\fP は \-1 である)。
 222 .TP
 223 \fBIN_UNMOUNT\fP
 224 監視対象オブジェクトを含むファイルシステムがアンマウントされた。
 225 .PD
 226 .RE
 227 .SS "/proc インターフェース"
 228 以下のインターフェースは、inotify で消費される カーネルメモリの総量を制限するのに使用できる:
 229 .TP
 230 \fI/proc/sys/fs/inotify/max_queued_events\fP
 231 このファイルの値は、アプリケーションが \fBinotify_init\fP(2)  を呼び出すときに使用され、対応する inotify インスタンスについて
 232 キューに入れられるイベントの数の上限を設定する。 この制限を超えたイベントは破棄されるが、 \fBIN_Q_OVERFLOW\fP イベントが常に生成される。
 233 .TP
 234 \fI/proc/sys/fs/inotify/max_user_instances\fP
 235 1 つの実ユーザ ID に対して生成できる inotify インスタンスの数の上限を指定する。
 236 .TP
 237 \fI/proc/sys/fs/inotify/max_user_watches\fP
 238 作成可能な監視対象の数の実 UID 単位の上限を指定する。
 239 .SH バージョン
 240 inotify は 2.6.13 の Linux カーネルに組込まれた。 これに必要なライブラリのインターフェースは、 glibc のバージョン 2.4
 241 に追加された (\fBIN_DONT_FOLLOW\fP, \fBIN_MASK_ADD\fP, \fBIN_ONLYDIR\fP はバージョン 2.5 で追加された)。
 242 .SH 準拠
 243 inotify API は Linux 独自のものである。
 244 .SH 注意
 245 inotify ファイルディスクリプタは \fBselect\fP(2), \fBpoll\fP(2), \fBepoll\fP(7)  を使って監視できる。
 246 イベントがある場合、ファイルディスクリプタは読み込み可能と通知する。
 247
 248 Linux 2.6.25 以降では、シグナル駆動 (signal\-driven) I/O の通知が inotify
 249 ファイルディスクリプタについて利用可能である。 \fBfcntl\fP(2)  に書かれている (\fBO_ASYNC\fP フラグを設定するための)
 250 \fBF_SETFL\fP, \fBF_SETOWN\fP, \fBF_SETSIG\fP の議論を参照のこと。 シグナルハンドラに渡される \fIsiginfo_t\fP
 251 構造体は、以下のフィールドが設定される (\fIsiginfo_t\fP は \fBsigaction\fP(2)  で説明されている)。 \fIsi_fd\fP には
 252 inotify ファイルディスクリプタ番号が、 \fIsi_signo\fP にはシグナル番号が、 \fIsi_code\fP には \fBPOLL_IN\fP が、
 253 \fIsi_band\fP には \fBPOLLIN\fP が設定される。
 254
 255 inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 (\fIwd\fP, \fImask\fP,
 256 \fIcookie\fP, \fIname\fP が等しい場合)、 前のイベントがまだ読み込まれていなければ、 連続するイベントが 1 つのイベントにまとめられる
 257 (ただし「バグ」の節も参照のこと)。
 258
 259 inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。
 260 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で
 261 イベントが生成されることが保証される。
 262
 263 \fBFIONREAD\fP \fBioctl\fP(2)  は inotify ファイルディスクリプタから何バイト読み込めるかを返す。
 264 .SS 制限と警告
 265 inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ以下の
 266 サブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。
 267 大きなディレクトリツリーの場合には、この作業にかなり時間がかかることがある。
 268
 269 inotify API では、inotify イベントが発生するきっかけとなったユーザやプロセスに関する情報は提供されない。とりわけ、inotify
 270 経由でイベントを監視しているプロセスが、自分自身がきっかけとなったイベントと他のプロセスがきっかけとなったイベントを区別する簡単な手段はない。
 271
 272 イベントキューは溢れる場合があることに注意すること。この場合にはイベントは
 273 失われてしまう。堅牢性が必要なアプリケーションでは、イベントが失われる可能性
 274 を適切に扱う必要がある。
 275
 276 inotify API では影響が受けるファイルをファイル名で特定する。
 277 しかしながら、アプリケーションが inotify イベントを処理する時点では、
 278 そのファイル名がすでに削除されたり変更されたりしている可能性がある。
 279
 280 ディレクトリツリー全体を監視していて、そのツリー内に新しいサブディレクトリが
 281 作成される場合、新しいサブディレクトリに対する watch を作成するまでに、
 282 新しいファイルがそのサブディレクトリ内にすでに作成されている場合がある点に
 283 注意すること。したがって、watch を追加した直後にサブディレクトリの内容を
 284 スキャンしたいと思う場合もあるだろう。
 285 .SH バグ
 286 2.6.16 以前のカーネルでは \fBIN_ONESHOT\fP \fImask\fP フラグが働かない。
 287
 288 カーネル 2.6.25 より前では、 連続する同一のイベントを一つにまとめることを意図したコード (古い方のイベントがまだ読み込まれていない場合に、
 289 最新の 2 つのイベントを一つにまとめられる可能性がある) が、 最新のイベントが「最も古い」読み込まれていないイベントとまとめられるか
 290 をチェックするようになっていた。
 291 .SH 関連項目
 292 \fBinotify_add_watch\fP(2), \fBinotify_init\fP(2), \fBinotify_init1\fP(2),
 293 \fBinotify_rm_watch\fP(2), \fBread\fP(2), \fBstat\fP(2)
 294
 295 Linux カーネルソース内の \fIDocumentation/filesystems/inotify.txt\fP
 296 .SH この文書について
 297 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 298 である。プロジェクトの説明とバグ報告に関する情報は
 299 http://www.kernel.org/doc/man\-pages/ に書かれている。