release/man7/inotify.7

   1 .\" t
   2 .\" Copyright (C) 2006, 2014 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 .\" Updated 2013-08-21, Akihiro MOTOKI <amotoki@gmail.com>, LDP v3.53
  44 .\"
  45 .TH INOTIFY 7 2014\-04\-01 Linux "Linux Programmer's Manual"
  46 .SH 名前
  47 inotify \- ファイルシステムイベントを監視する
  48 .SH 説明
  49 \fIinotify\fP API はファイルシステムイベントを監視するための機構を提供する。 inotify
  50 は個々のファイルやディレクトリを監視するのに使える。 ディレクトリを監視する場合、inotify はディレクトリ自身と
  51 ディレクトリ内のファイルのイベントを返す。
  52
  53 この API では以下のシステムコールが使用される。
  54 .IP * 3
  55 \fBinotify_init\fP(2)  は inotify インスタンスを作成し、inotify インスタンスを参照する ファイルディスクリプタを返す。
  56 もっと新しい \fBinotify_init1\fP(2)  も \fBinotify_init\fP(2)  と同様だが、いくつかの追加の機能を利用するための
  57 \fIflags\fP 引き数を持っている。
  58 .IP *
  59 \fBinotify_add_watch\fP(2)  は inotify インスタンスに関連づけられた「監視対象 (watch) リスト」を操作する。
  60 監視対象リストの各アイテム ("watch") は、 ファイルまたはディレクトリのパス名と、 そのパス名で参照されるファイルに対して
  61 カーネルが監視する複数のイベントの集合を指定する。 \fBinotify_add_watch\fP(2)
  62 は新しい監視アイテムの作成や既存の監視対象の変更ができる。 各監視対象は一意の「監視対象ディスクリプタ」を持つ。 これは監視対象を作成したときに
  63 \fBinotify_add_watch\fP(2)  から返される整数である。
  64 .IP *
  65 When events occur for monitored files and directories, those events are made
  66 available to the application as structured data that can be read from the
  67 inotify file descriptor using \fBread\fP(2)  (see below).
  68 .IP *
  69 \fBinotify_rm_watch\fP(2)  は inotify の監視対象リストからアイテムを削除する。
  70 .IP *
  71 inotify インスタンスを指している 全てのファイルディスクリプタが (\fBclose\fP(2) を使って) クローズされた場合、
  72 その下層にあるオブジェクトとそのリソースは、 カーネルで再利用するために解放される。 関連が切られた監視対象は自動的に解放される。
  73
  74 With careful programming, an application can use inotify to efficiently
  75 monitor and cache the state of a set of filesystem objects.  However, robust
  76 applications should allow for the fact that bugs in the monitoring logic or
  77 races of the kind described below may leave the cache inconsistent with the
  78 filesystem state.  It is probably wise to to do some consistency checking,
  79 and rebuild the cache when inconsistencies are detected.
  80 .SS "inotify ファイルディスクリプタからのイベントの読み出し"
  81 どのようなイベントが起こっていたかを知るには、 アプリケーションで inotify ファイルディスクリプタを \fBread\fP(2)  すればよい。
  82 これまでに何もイベントが起こっていない場合、 停止 (blocking) モードのファイルディスクリプタであれば、 少なくとも 1
  83 つのイベントが起こるまで \fBread\fP(2)  は停止する (シグナルにより割り込まれなかった場合。
  84 シグナルによる割り込みがあった場合、呼び出しはエラー \fBEINTR\fP で失敗する。 \fBsignal\fP(7)  参照)。
  85
  86 \fBread\fP(2)  が成功すると、以下の構造体を 1 つ以上含むバッファが返される:
  87 .in +4n
  88 .nf
  89
  90 .\" FIXME . The type of the 'wd' field should probably be "int32_t".
  91 .\" I submitted a patch to fix this.  See the LKML thread
  92 .\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008
  93 .\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040
  94 struct inotify_event {
  95     int      wd;       /* 監視対象ディスクリプタ */
  96     uint32_t mask;     /* イベントのマスク */
  97     uint32_t cookie;   /* 関連するイベント群を関連づける
  98                           一意なクッキー (rename(2) 用) */
  99     uint32_t len;      /* \(aqname\(aq フィールドのサイズ */
 100     char     name[];   /* ヌルで終端された任意の名前 */
 101 };
 102 .fi
 103 .in
 104
 105 \fIwd\fP はイベント発生の監視対象を指定する。 これは、前もって行われた \fBinotify_add_watch\fP(2)
 106 呼び出しで返された監視対象ディスクリプタのうちの 1 つである。
 107
 108 \fImask\fP には発生したイベント (下記参照) を記述するためのビットが含まれる。
 109
 110 \fIcookie\fP は関連するイベントを関連づけるための一意な整数である。
 111 現在のところ、この値は rename イベントに対してのみ使われており、
 112 結果のペアである \fBIN_MOVED_FROM\fP と \fBIN_MOVED_TO\fP イベントを
 113 アプリケーションで関連づけることができる。
 114 他のイベント種別の場合には、 \fIcookie\fP は 0 に設定する。
 115
 116 \fIname\fP フィールドは監視しているディレクトリ内のファイルに対して イベントが返される場合のためにだけ存在する。
 117 監視するディレクトリからのファイルの相対パス名を表す。 このパス名はヌルで終端され、 その後の読み込みで適切なアドレス境界に調整するために、
 118 さらにヌルバイト (\(aq\e0\(aq) が含まれる場合もある。
 119
 120 \fIlen\fP フィールドはヌルバイトを含む \fIname\fP の全てのバイト数を表す。
 121 よって、 \fIinotify_event\fP 構造体のサイズは
 122 \fIsizeof(struct inotify_event)+len\fP である。
 123
 124 \fBread\fP(2) に渡されたバッファが小さすぎて次のイベントに関する情報を返せ
 125 ない場合の動作はカーネルのバージョンにより異なる。 2.6.21 より前のカー
 126 ネルでは、 \fBread\fP(2) は 0 を返す。 2.6.21 以降のカーネルでは、
 127 \fBread\fP(2) はエラー \fBEINVAL\fP で失敗する。
 128 バッファサイズとして
 129
 130     sizeof(struct inotify_event) + NAME_MAX + 1
 131
 132 を指定すれば、少なくとも 1 イベントで読み出しを行うには十分である。
 133 .SS "inotify イベント"
 134 \fBinotify_add_watch\fP(2)  の \fImask\fP 引き数と、inotify ファイル構造体を \fBread\fP(2)
 135 したときに返される \fIinotify_event\fP 構造体の \fImask\fP フィールドは、ともに inotify イベントを識別するための
 136 ビットマスクである。 以下のビットが \fBinotify_add_watch\fP(2)  を呼ぶときの \fImask\fP に指定可能であり、
 137 \fBread\fP(2)  で返される \fImask\fP フィールドで返される:
 138 .RS 4
 139 .TP
 140 \fBIN_ACCESS\fP (*)
 141 (\fBread\fP(2), \fBexecve\fP(2) などで) ファイルがアクセスされた。
 142 .TP
 143 \fBIN_ATTRIB\fP (*)
 144 メタデータが変更された。 メタデータとは、例えば、アクセス許可 (\fBchmod\fP(2))、タイムスタンプ (\fButimensat\fP(2)
 145 など)、拡張属性 (\fBsetxattr\fP(2))、 リンクカウント (Linux 2.6.25 以降; \fBlink\fP(2) のリンク先や
 146 \fBunlink\fP(2) など)、ユーザー/グループ ID (\fBchown\fP(2) など) などである。
 147 .TP
 148 \fBIN_CLOSE_WRITE\fP (*)
 149 書き込みのためにオープンされたファイルがクローズされた。
 150 .TP
 151 \fBIN_CLOSE_NOWRITE\fP (*)
 152 書き込み以外のためにオープンされたファイルがクローズされた。
 153 .TP
 154 \fBIN_CREATE\fP (*)
 155 監視対象ディレクトリ内でファイルやディレクトリが作成された (\fBopen\fP(2)  \fBO_CREAT\fP, \fBmkdir\fP(2),
 156 \fBlink\fP(2), \fBsymlink\fP(2), UNIX ドメインソケットに対する \fBbind\fP(2) など)。
 157 .TP
 158 \fBIN_DELETE\fP (*)
 159 監視対象ディレクトリ内でファイルやディレクトリが削除された。
 160 .TP
 161 \fBIN_DELETE_SELF\fP
 162 Watched file/directory was itself deleted.  (This event also occurs if an
 163 object is moved to another filesystem, since \fBmv\fP(1)  in effect copies the
 164 file to the other filesystem and then deletes it from the original
 165 filesystem.)  In addition, an \fBIN_IGNORED\fP event will subsequently be
 166 generated for the watch descriptor.
 167 .TP
 168 \fBIN_MODIFY\fP (*)
 169 ファイルが変更された (\fBwrite\fP(2), \fBtruncate\fP(2) など)。
 170 .TP
 171 \fBIN_MOVE_SELF\fP
 172 監視対象のディレクトリまたはファイル自身が移動された。
 173 .TP
 174 \fBIN_MOVED_FROM\fP (*)
 175 ファイル名の変更を行った際に変更前のファイル名が含まれるディレクトリに対して生成される。
 176 .TP
 177 \fBIN_MOVED_TO\fP (*)
 178 ファイル名の変更を行った際に新しいファイル名が含まれるディレクトリに対して生成される。
 179 .TP
 180 \fBIN_OPEN\fP (*)
 181 ファイルがオープンされた。
 182 .RE
 183 .PP
 184 ディレクトリを監視する場合、 上記でアスタリスク (*) を付けたイベントは、 そのディレクトリ内のファイルに対して発生する。 このとき
 185 \fIinotify_event\fP 構造体で返される \fIname\fP フィールドは、ディレクトリ内のファイル名を表す。
 186 .PP
 187 \fBIN_ALL_EVENTS\fP マクロは上記のイベント全てのマスクとして定義される。 このマクロは \fBinotify_add_watch\fP(2)
 188 を呼び出すときの \fImask\fP 引き数として使える。
 189
 190 以下の 2 つの便利なマクロが定義されている。
 191 .RS 4
 192 .TP
 193 \fBIN_MOVE\fP
 194 \fBIN_MOVED_FROM | IN_MOVED_TO\fP と等価。
 195 .TP
 196 \fBIN_CLOSE\fP
 197 \fBIN_CLOSE_WRITE | IN_CLOSE_NOWRITE\fP と等価。
 198 .RE
 199 .PP
 200 その他にも以下のビットを \fBinotify_add_watch\fP(2)  を呼ぶときの \fImask\fP に指定できる:
 201 .RS 4
 202 .TP
 203 \fBIN_DONT_FOLLOW\fP (Linux 2.6.15 以降)
 204 \fIpathname\fP がシンボリックリンクである場合に辿らない。 (Linux 2.6.15 以降)
 205 .TP
 206 \fBIN_EXCL_UNLINK\fP (Linux 2.6.36 以降)
 207 .\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6
 208 デフォルトでは、あるディレクトリの子ファイルに関するイベントを監視 (watch) した際、ディレクトリからその子ファイルが削除 (unlink)
 209 された場合であってもその子ファイルに対してイベントが生成される。このことは、アプリケーションによってはあまり興味のないイベントが大量に発生することにつながる
 210 (例えば、\fI/tmp\fP を監視している場合、たくさんのアプリケーションが、すぐにその名前が削除される一時ファイルをそのディレクトリに作成する)。
 211 \fBIN_EXCL_UNLINK\fP
 212 を指定するとこのデフォルトの動作を変更でき、監視対象のディレクトリから子ファイルが削除された後に子ファイルに関するイベントが生成されなくなる。
 213 .TP
 214 \fBIN_MASK_ADD\fP
 215 \fIpathname\fP に対する監視マスクが既に存在する場合、 (マスクの置き換えではなく) イベントを追加 (OR) する。
 216 .TP
 217 \fBIN_ONESHOT\fP
 218 1 つのイベントについて \fIpathname\fP を監視し、 イベントが発生したら監視対象リストから削除する。
 219 .TP
 220 \fBIN_ONLYDIR\fP (Linux 2.6.15 以降)
 221 \fIpathname\fP がディレクトリの場合にのみ監視する。
 222 .RE
 223 .PP
 224 以下のビットが \fBread\fP(2)  で返される \fImask\fP フィールドに設定される:
 225 .RS 4
 226 .TP
 227 \fBIN_IGNORED\fP
 228 監視対象が (\fBinotify_rm_watch\fP(2) により) 明示的に 削除された。もしくは (ファイルの削除、またはファイル
 229 システムのアンマウントにより) 自動的に削除された。「バグ」も参照のこと。
 230 .TP
 231 \fBIN_ISDIR\fP
 232 このイベントの対象がディレクトリである。
 233 .TP
 234 \fBIN_Q_OVERFLOW\fP
 235 イベントキューが溢れた (このイベントの場合、\fIwd\fP は \-1 である)。
 236 .TP
 237 \fBIN_UNMOUNT\fP
 238 監視対象オブジェクトを含むファイルシステムがアンマウントされた。さらに、この監視対象ディスクリプタに対して \fBIN_IGNORED\fP
 239 イベントが生成される。
 240 .RE
 241 .SS 例
 242 Suppose an application is watching the directory \fIdir\fP and the file
 243 \fIdir/myfile\fP for all events.  The examples below show some events that will
 244 be generated for these two objects.
 245 .RS 4
 246 .TP
 247 fd = open("dir/myfile", O_RDWR);
 248 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_OPEN\fP イベントが生成される。
 249 .TP
 250 read(fd, buf, count);
 251 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_ACCESS\fP イベントが生成される
 252 .TP
 253 write(fd, buf, count);
 254 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_MODIFY\fP イベントが生成される
 255 .TP
 256 fchmod(fd, mode);
 257 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_ATTRIB\fP イベントが生成される
 258 .TP
 259 close(fd);
 260 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_CLOSE_WRITE\fP イベントが生成される
 261 .RE
 262 .PP
 263 Suppose an application is watching the directories \fIdir1\fP and \fIdir2\fP, and
 264 the file \fIdir1/myfile\fP.  The following examples show some events that may
 265 be generated.
 266 .RS 4
 267 .TP
 268 link("dir1/myfile", "dir2/new");
 269 \fImyfile\fP に対して \fBIN_ATTRIB\fP イベントが生成され、 \fIdir2\fP に対して \fBIN_CREATE\fP イベントが生成される。
 270 .TP
 271 rename("dir1/myfile", "dir2/myfile");
 272 \fIdir1\fP に対してイベント \fBIN_MOVED_FROM\fP が、 \fIdir2\fP に対してイベント \fBIN_MOVED_TO\fP が、
 273 \fImyfile\fP に対してイベント \fBIN_MOVE_SELF\fP が生成される。この際 イベント \fBIN_MOVED_FROM\fP と
 274 \fBIN_MOVED_TO\fP は同じ \fIcookie\fP 値を持つ。
 275 .RE
 276 .PP
 277 Suppose that \fIdir1/xx\fP and \fIdir2/yy\fP are (the only) links to the same
 278 file, and an application is watching \fIdir1\fP, \fIdir2\fP, \fIdir1/xx\fP, and
 279 \fIdir2/yy\fP.  Executing the following calls in the order given below will
 280 generate the following events:
 281 .RS 4
 282 .TP
 283 unlink("dir2/yy");
 284 Generates an \fBIN_ATTRIB\fP event for \fIxx\fP (because its link count changes)
 285 and an \fBIN_DELETE\fP event for \fIdir2\fP.
 286 .TP
 287 unlink("dir1/xx");
 288 Generates \fBIN_ATTRIB\fP, \fBIN_DELETE_SELF\fP, and \fBIN_IGNORED\fP events for
 289 \fIxx\fP, and an \fBIN_DELETE\fP event for \fIdir1\fP.
 290 .RE
 291 .PP
 292 Suppose an application is watching the directory \fIdir\fP and (the empty)
 293 directory \fIdir/subdir\fP.  The following examples show some events that may
 294 be generated.
 295 .RS 4
 296 .TP
 297 mkdir("dir/new", mode);
 298 Generates an \fBIN_CREATE | IN_ISDIR\fP event for \fIdir\fP.
 299 .TP
 300 rmdir("dir/subdir");
 301 Generates \fBIN_DELETE_SELF\fP and \fBIN_IGNORED\fP events for \fIsubdir\fP, and an
 302 \fBIN_DELETE | IN_ISDIR\fP event for \fIdir\fP.
 303 .RE
 304 .SS "/proc インターフェース"
 305 以下のインターフェースは、inotify で消費される カーネルメモリの総量を制限するのに使用できる:
 306 .TP
 307 \fI/proc/sys/fs/inotify/max_queued_events\fP
 308 このファイルの値は、アプリケーションが \fBinotify_init\fP(2)  を呼び出すときに使用され、対応する inotify インスタンスについて
 309 キューに入れられるイベントの数の上限を設定する。 この制限を超えたイベントは破棄されるが、 \fBIN_Q_OVERFLOW\fP イベントが常に生成される。
 310 .TP
 311 \fI/proc/sys/fs/inotify/max_user_instances\fP
 312 1 つの実ユーザ ID に対して生成できる inotify インスタンスの数の上限を指定する。
 313 .TP
 314 \fI/proc/sys/fs/inotify/max_user_watches\fP
 315 作成可能な監視対象の数の実 UID 単位の上限を指定する。
 316 .SH バージョン
 317 inotify は 2.6.13 の Linux カーネルに組込まれた。 これに必要なライブラリのインターフェースは、 glibc のバージョン 2.4
 318 に追加された (\fBIN_DONT_FOLLOW\fP, \fBIN_MASK_ADD\fP, \fBIN_ONLYDIR\fP は glibc バージョン 2.5
 319 で追加された)。
 320 .SH 準拠
 321 inotify API は Linux 独自のものである。
 322 .SH 注意
 323 inotify ファイルディスクリプタは \fBselect\fP(2), \fBpoll\fP(2), \fBepoll\fP(7)  を使って監視できる。
 324 イベントがある場合、ファイルディスクリプタは読み込み可能と通知する。
 325
 326 Linux 2.6.25 以降では、シグナル駆動 (signal\-driven) I/O の通知が inotify
 327 ファイルディスクリプタについて利用可能である。 \fBfcntl\fP(2)  に書かれている (\fBO_ASYNC\fP フラグを設定するための)
 328 \fBF_SETFL\fP, \fBF_SETOWN\fP, \fBF_SETSIG\fP の議論を参照のこと。 シグナルハンドラに渡される \fIsiginfo_t\fP
 329 構造体は、以下のフィールドが設定される (\fIsiginfo_t\fP は \fBsigaction\fP(2)  で説明されている)。 \fIsi_fd\fP には
 330 inotify ファイルディスクリプタ番号が、 \fIsi_signo\fP にはシグナル番号が、 \fIsi_code\fP には \fBPOLL_IN\fP が、
 331 \fIsi_band\fP には \fBPOLLIN\fP が設定される。
 332
 333 inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 (\fIwd\fP, \fImask\fP,
 334 \fIcookie\fP, \fIname\fP が等しい場合)、 前のイベントがまだ読み込まれていなければ、 連続するイベントが 1 つのイベントにまとめられる
 335 (ただし「バグ」の節も参照のこと)。 これによりイベントキューに必要なカーネルメモリ量が減るが、
 336 これはまたアプリケーションがファイルイベント数を信頼性を持って数えるのに inotify を使用できないということでもある。
 337
 338 inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。
 339 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で
 340 イベントが生成されることが保証される。
 341
 342 \fBFIONREAD\fP \fBioctl\fP(2)  は inotify ファイルディスクリプタから何バイト読み込めるかを返す。
 343 .SS 制限と警告
 344 inotify API では、inotify イベントが発生するきっかけとなったユーザやプロセスに関する情報は提供されない。とりわけ、inotify
 345 経由でイベントを監視しているプロセスが、自分自身がきっかけとなったイベントと他のプロセスがきっかけとなったイベントを区別する簡単な手段はない。
 346
 347 Inotify reports only events that a user\-space program triggers through the
 348 filesystem API.  As a result, it does not catch remote events that occur on
 349 network filesystems.  (Applications must fall back to polling the filesystem
 350 to catch such events.)  Furthermore, various pseudo\-filesystems such as
 351 \fI/proc\fP, \fI/sys\fP, and \fI/dev/pts\fP are not monitorable with inotify.
 352
 353 The inotify API does not report file accesses and modifications that may
 354 occur because of \fBmmap\fP(2)  and \fBmsync\fP(2).
 355
 356 inotify API では影響が受けるファイルをファイル名で特定する。
 357 しかしながら、アプリケーションが inotify イベントを処理する時点では、
 358 そのファイル名がすでに削除されたり変更されたりしている可能性がある。
 359
 360 The inotify API identifies events via watch descriptors.  It is the
 361 application's responsibility to cache a mapping (if one is needed) between
 362 watch descriptors and pathnames.  Be aware that directory renamings may
 363 affect multiple cached pathnames.
 364
 365 inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ以下の
 366 サブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。
 367 大きなディレクトリツリーの場合には、この作業にかなり時間がかかることがある。
 368
 369 ディレクトリツリー全体を監視していて、 そのツリー内に新しいサブディレクトリが作成されるか、
 370 既存のディレクトリが名前が変更されそのツリー内に移動した場合、 新しいサブディレクトリに対する watch を作成するまでに、 新しいファイル
 371 (やサブディレクトリ) がそのサブディレクトリ内にすでに作成されている場合がある点に注意すること。 したがって、watch
 372 を追加した直後にサブディレクトリの内容をスキャンしたいと思う場合もあるだろう (必要ならそのサブディレクトリ内のサブディレクトリに対する watch
 373 も再帰的に追加することもあるだろう)。
 374
 375 Note that the event queue can overflow.  In this case, events are lost.
 376 Robust applications should handle the possibility of lost events
 377 gracefully.  For example, it may be necessary to rebuild part or all of the
 378 application cache.  (One simple, but possibly expensive, approach is to
 379 close the inotify file descriptor, empty the cache, create a new inotify
 380 file descriptor, and then re\-create watches and cache entries for the
 381 objects to be monitored.)
 382 .SS "rename() イベントの取り扱い"
 383 As noted above, the \fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP event pair that is
 384 generated by \fBrename\fP(2)  can be matched up via their shared cookie value.
 385 However, the task of matching has some challenges.
 386
 387 These two events are usually consecutive in the event stream available when
 388 reading from the inotify file descriptor.  However, this is not guaranteed.
 389 If multiple processes are triggering events for monitored objects, then (on
 390 rare occasions) an arbitrary number of other events may appear between the
 391 \fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP events.
 392
 393 Matching up the \fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP event pair generated by
 394 \fBrename\fP(2)  is thus inherently racy.  (Don't forget that if an object is
 395 renamed outside of a monitored directory, there may not even be an
 396 \fBIN_MOVED_TO\fP event.)  Heuristic approaches (e.g., assume the events are
 397 always consecutive)  can be used to ensure a match in most cases, but will
 398 inevitably miss some cases, causing the application to perceive the
 399 \fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP events as being unrelated.  If watch
 400 descriptors are destroyed and re\-created as a result, then those watch
 401 descriptors will be inconsistent with the watch descriptors in any pending
 402 events.  (Re\-creating the inotify file descriptor and rebuilding the cache
 403 may be useful to deal with this scenario.)
 404
 405 Applications should also allow for the possibility that the \fBIN_MOVED_FROM\fP
 406 event was the last event that could fit in the buffer returned by the
 407 current call to \fBread\fP(2), and the accompanying \fBIN_MOVED_TO\fP event might
 408 be fetched only on the next \fBread\fP(2).
 409 .SH バグ
 410 .\" FIXME kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321
 411 .\" implies that unmount events were buggy 2.6.11 to 2.6.36
 412 .\"
 413 2.6.16 以前のカーネルでは \fBIN_ONESHOT\fP \fImask\fP フラグが働かない。
 414
 415 As originally designed and implemented, the \fBIN_ONESHOT\fP flag did not cause
 416 an \fBIN_IGNORED\fP event to be generated when the watch was dropped after one
 417 event.  However, as an unintended effect of other changes, since Linux
 418 2.6.36, an \fBIN_IGNORED\fP event is generated in this case.
 419
 420 .\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2
 421 カーネル 2.6.25 より前では、 連続する同一のイベントを一つにまとめることを意図したコード (古い方のイベントがまだ読み込まれていない場合に、
 422 最新の 2 つのイベントを一つにまとめられる可能性がある) が、 最新のイベントが「最も古い」読み込まれていないイベントとまとめられるか
 423 をチェックするようになっていた。
 424 .SH 関連項目
 425 \fBinotifywait\fP(1), \fBinotifywatch\fP(1), \fBinotify_add_watch\fP(2),
 426 \fBinotify_init\fP(2), \fBinotify_init1\fP(2), \fBinotify_rm_watch\fP(2), \fBread\fP(2),
 427 \fBstat\fP(2)
 428
 429 Linux カーネルソース内の \fIDocumentation/filesystems/inotify.txt\fP
 430 .SH この文書について
 431 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
 432 である。プロジェクトの説明とバグ報告に関する情報は
 433 http://www.kernel.org/doc/man\-pages/ に書かれている。