release/man7/inotify.7

   1 .\" t
   2 .\" Copyright (C) 2006, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" Copyright (C) 2014 Heinrich Schuchardt <xypron.glpk@gmx.de>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\"*******************************************************************
  28 .\"
  29 .\" This file was generated with po4a. Translate the source file.
  30 .\"
  31 .\"*******************************************************************
  32 .\"
  33 .\" Japanese Version Copyright (c) 2006 Yuichi SATO
  34 .\"     and Copyright (c) 2007-2008 Akihiro MOTOKI
  35 .\" Translated 2006-07-05 by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v2.29
  36 .\" Updated 2006-07-20 by Yuichi SATO, LDP v2.36
  37 .\" Updated 2007-06-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.55
  38 .\" Updated 2008-08-10, Akihiro MOTOKI, LDP v3.05
  39 .\" Updated 2008-09-19, Akihiro MOTOKI, LDP v3.08
  40 .\" Updated 2012-04-30, Akihiro MOTOKI <amotoki@gmail.com>
  41 .\" Updated 2012-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  42 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  43 .\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
  44 .\" Updated 2013-08-21, Akihiro MOTOKI <amotoki@gmail.com>, LDP v3.53
  45 .\"
  46 .TH INOTIFY 7 2014\-12\-31 Linux "Linux Programmer's Manual"
  47 .SH 名前
  48 inotify \- ファイルシステムイベントを監視する
  49 .SH 説明
  50 \fIinotify\fP API はファイルシステムイベントを監視するための機構を提供する。 inotify
  51 は個々のファイルやディレクトリを監視するのに使える。 ディレクトリを監視する場合、inotify はディレクトリ自身と
  52 ディレクトリ内のファイルのイベントを返す。
  53
  54 この API では以下のシステムコールが使用される。
  55 .IP * 3
  56 \fBinotify_init\fP(2)  は inotify インスタンスを作成し、inotify インスタンスを参照する ファイルディスクリプタを返す。
  57 より新しい \fBinotify_init1\fP(2)  も \fBinotify_init\fP(2)  と同様だが、
  58 こちらにはいくつかの追加の機能を利用するための \fIflags\fP 引き数がある。
  59 .IP *
  60 \fBinotify_add_watch\fP(2)  は inotify インスタンスに関連づけられた「監視対象 (watch) リスト」を操作する。
  61 監視対象リストの各アイテム ("watch") は、 ファイルまたはディレクトリのパス名と、 そのパス名で参照されるファイルに対して
  62 カーネルが監視する複数のイベントの集合を指定する。 \fBinotify_add_watch\fP(2)
  63 は新しい監視アイテムの作成や既存の監視対象の変更ができる。 各監視対象は一意の「監視対象ディスクリプタ」を持つ。 これは監視対象を作成したときに
  64 \fBinotify_add_watch\fP(2)  から返される整数である。
  65 .IP *
  66 監視しているファイルやディレクトリでイベントが起こると、 それらのイベントはアプリケーションから inotify ファイルディスクリプタから
  67 \fBread\fP(2) を使って構造化データとして読み出すことができる (下記参照)。
  68 .IP *
  69 \fBinotify_rm_watch\fP(2)  は inotify の監視対象リストからアイテムを削除する。
  70 .IP *
  71 inotify インスタンスを指している 全てのファイルディスクリプタが (\fBclose\fP(2) を使って) クローズされた場合、
  72 その下層にあるオブジェクトとそのリソースは、 カーネルで再利用するために解放される。 関連が切られた監視対象は自動的に解放される。
  73 .PP
  74 注意深くプログラミングすることで、 アプリケーションは inotify
  75 を使ってファイルシステムオブジェクトの集合の状態を効率的に監視しキャッシュしておくことができる。
  76 しかしながら、ロバストなアプリケーションでは、監視ロジックのバグや以下に説明があるような種類の競合条件によりファイルシステムの状態とキャッシュが一致しない状態になることがあるという事実も考慮に入れておくべきである。
  77 おそらく何らかの一貫性のチェックを行い、不一致が検出された場合にはキャッシュを再構築するのが懸命だろう。
  78 .SS "inotify ファイルディスクリプタからのイベントの読み出し"
  79 どのようなイベントが起こっていたかを知るには、 アプリケーションで inotify ファイルディスクリプタを \fBread\fP(2)  すればよい。
  80 これまでに何もイベントが起こっていない場合、 停止 (blocking) モードのファイルディスクリプタであれば、 少なくとも 1
  81 つのイベントが起こるまで \fBread\fP(2)  は停止する (シグナルにより割り込まれなかった場合。
  82 シグナルによる割り込みがあった場合、呼び出しはエラー \fBEINTR\fP で失敗する。 \fBsignal\fP(7)  参照)。
  83
  84 \fBread\fP(2)  が成功すると、以下の構造体を 1 つ以上含むバッファが返される:
  85 .in +4n
  86 .nf
  87
  88 .\" FIXME . The type of the 'wd' field should probably be "int32_t".
  89 .\" I submitted a patch to fix this.  See the LKML thread
  90 .\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008
  91 .\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040
  92 struct inotify_event {
  93     int      wd;       /* 監視対象ディスクリプタ */
  94     uint32_t mask;     /* イベントを示すマスク */
  95     uint32_t cookie;   /* 関連するイベント群を関連づける
  96                           一意なクッキー (rename(2) 用) */
  97     uint32_t len;      /* \(aqname\(aq フィールドのサイズ */
  98     char     name[];   /* ヌルで終端された任意の名前 */
  99 };
 100 .fi
 101 .in
 102
 103 \fIwd\fP はイベント発生の監視対象を指定する。 これは、前もって行われた \fBinotify_add_watch\fP(2)
 104 呼び出しで返された監視対象ディスクリプタのうちの 1 つである。
 105
 106 \fImask\fP には発生したイベント (下記参照) を記述するためのビットが含まれる。
 107
 108 \fIcookie\fP は関連するイベントを関連づけるための一意な整数である。
 109 現在のところ、この値は rename イベントに対してのみ使われており、
 110 結果のペアである \fBIN_MOVED_FROM\fP と \fBIN_MOVED_TO\fP イベントを
 111 アプリケーションで関連づけることができる。
 112 他のイベント種別の場合には、 \fIcookie\fP は 0 に設定する。
 113
 114 \fIname\fP フィールドは監視しているディレクトリ内のファイルに対して イベントが返される場合のためにだけ存在する。
 115 監視するディレクトリからのファイルの相対パス名を表す。 このパス名はヌルで終端され、 その後の読み込みで適切なアドレス境界に調整するために、
 116 さらにヌルバイト (\(aq\e0\(aq) が含まれる場合もある。
 117
 118 \fIlen\fP フィールドはヌルバイトを含む \fIname\fP の全てのバイト数を表す。
 119 よって、 \fIinotify_event\fP 構造体のサイズは
 120 \fIsizeof(struct inotify_event)+len\fP である。
 121
 122 \fBread\fP(2) に渡されたバッファが小さすぎて次のイベントに関する情報を返せ
 123 ない場合の動作はカーネルのバージョンにより異なる。 2.6.21 より前のカー
 124 ネルでは、 \fBread\fP(2) は 0 を返す。 2.6.21 以降のカーネルでは、
 125 \fBread\fP(2) はエラー \fBEINVAL\fP で失敗する。
 126 バッファサイズとして
 127
 128     sizeof(struct inotify_event) + NAME_MAX + 1
 129
 130 を指定すれば、少なくとも 1 イベントで読み出しを行うには十分である。
 131 .SS "inotify イベント"
 132 \fBinotify_add_watch\fP(2)  の \fImask\fP 引き数と、inotify ファイル構造体を \fBread\fP(2)
 133 したときに返される \fIinotify_event\fP 構造体の \fImask\fP フィールドは、ともに inotify イベントを識別するための
 134 ビットマスクである。 以下のビットが \fBinotify_add_watch\fP(2)  を呼ぶときの \fImask\fP に指定可能であり、
 135 \fBread\fP(2)  で返される \fImask\fP フィールドで返される:
 136 .RS 4
 137 .TP
 138 \fBIN_ACCESS\fP (+)
 139 (\fBread\fP(2), \fBexecve\fP(2) などで) ファイルがアクセスされた。
 140 .TP
 141 \fBIN_ATTRIB\fP (*)
 142 メタデータが変更された。 メタデータとは、例えば、アクセス許可 (\fBchmod\fP(2))、タイムスタンプ (\fButimensat\fP(2)
 143 など)、拡張属性 (\fBsetxattr\fP(2))、 リンクカウント (Linux 2.6.25 以降; \fBlink\fP(2) のリンク先や
 144 \fBunlink\fP(2) など)、ユーザー/グループ ID (\fBchown\fP(2) など) などである。
 145 .TP
 146 \fBIN_CLOSE_WRITE\fP (+)
 147 書き込みのためにオープンされたファイルがクローズされた。
 148 .TP
 149 \fBIN_CLOSE_NOWRITE\fP (*)
 150 書き込み用としてはオープンされていないファイルやディレクトリがクローズされた。
 151 .TP
 152 \fBIN_CREATE\fP (+)
 153 監視対象ディレクトリ内でファイルやディレクトリが作成された (\fBopen\fP(2)  \fBO_CREAT\fP, \fBmkdir\fP(2),
 154 \fBlink\fP(2), \fBsymlink\fP(2), UNIX ドメインソケットに対する \fBbind\fP(2) など)。
 155 .TP
 156 \fBIN_DELETE\fP (+)
 157 監視対象ディレクトリ内でファイルやディレクトリが削除された。
 158 .TP
 159 \fBIN_DELETE_SELF\fP
 160 監視対象のファイルやディレクトリ自身が削除あれた。 (このイベントはオブジェクトが別のファイルシステムに移動された場合にも発生する。 \fBmv\fP(1)
 161 は実際には別のファイルシステムにファイルをコピーした後、元のファイルシステムからそのファイルを削除するからである。) また、
 162 結果的に監視ディスクリプタに対して \fBIN_IGNORED\fP イベントも生成される。
 163 .TP
 164 \fBIN_MODIFY\fP (+)
 165 ファイルが変更された (\fBwrite\fP(2), \fBtruncate\fP(2) など)。
 166 .TP
 167 \fBIN_MOVE_SELF\fP
 168 監視対象のディレクトリまたはファイル自身が移動された。
 169 .TP
 170 \fBIN_MOVED_FROM\fP (+)
 171 ファイル名の変更を行った際に変更前のファイル名が含まれるディレクトリに対して生成される。
 172 .TP
 173 \fBIN_MOVED_TO\fP (+)
 174 ファイル名の変更を行った際に新しいファイル名が含まれるディレクトリに対して生成される。
 175 .TP
 176 \fBIN_OPEN\fP (*)
 177 ファイルやディレクトリがオープンされた。
 178 .RE
 179 .PP
 180 When monitoring a directory:
 181 .IP * 3
 182 the events marked above with an asterisk (*) can occur both for the
 183 directory itself and for objects inside the directory; and
 184 .IP *
 185 the events marked with a plus sign (+) occur only for objects inside the
 186 directory (not for the directory itself).
 187 .PP
 188 When events are generated for objects inside a watched directory, the
 189 \fIname\fP field in the returned \fIinotify_event\fP structure identifies the name
 190 of the file within the directory.
 191 .PP
 192 \fBIN_ALL_EVENTS\fP マクロは上記のイベント全てのマスクとして定義される。 このマクロは \fBinotify_add_watch\fP(2)
 193 を呼び出すときの \fImask\fP 引き数として使える。
 194
 195 以下の 2 つの便利なマクロが定義されている。
 196 .RS 4
 197 .TP
 198 \fBIN_MOVE\fP
 199 \fBIN_MOVED_FROM | IN_MOVED_TO\fP と等価。
 200 .TP
 201 \fBIN_CLOSE\fP
 202 \fBIN_CLOSE_WRITE | IN_CLOSE_NOWRITE\fP と等価。
 203 .RE
 204 .PP
 205 その他にも以下のビットを \fBinotify_add_watch\fP(2)  を呼ぶときの \fImask\fP に指定できる:
 206 .RS 4
 207 .TP
 208 \fBIN_DONT_FOLLOW\fP (Linux 2.6.15 以降)
 209 \fIpathname\fP がシンボリックリンクである場合に辿らない。 (Linux 2.6.15 以降)
 210 .TP
 211 \fBIN_EXCL_UNLINK\fP (Linux 2.6.36 以降)
 212 .\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6
 213 デフォルトでは、あるディレクトリの子ファイルに関するイベントを監視 (watch) した際、ディレクトリからその子ファイルが削除 (unlink)
 214 された場合であってもその子ファイルに対してイベントが生成される。このことは、アプリケーションによってはあまり興味のないイベントが大量に発生することにつながる
 215 (例えば、\fI/tmp\fP を監視している場合、たくさんのアプリケーションが、すぐにその名前が削除される一時ファイルをそのディレクトリに作成する)。
 216 \fBIN_EXCL_UNLINK\fP
 217 を指定するとこのデフォルトの動作を変更でき、監視対象のディレクトリから子ファイルが削除された後に子ファイルに関するイベントが生成されなくなる。
 218 .TP
 219 \fBIN_MASK_ADD\fP
 220 If a watch instance already exists for the filesystem object corresponding
 221 to \fIpathname\fP, add (OR) the events in \fImask\fP to the watch mask (instead of
 222 replacing the mask).
 223 .TP
 224 \fBIN_ONESHOT\fP
 225 Monitor the filesystem object corresponding to \fIpathname\fP for one event,
 226 then remove from watch list.
 227 .TP
 228 \fBIN_ONLYDIR\fP (Linux 2.6.15 以降)
 229 Only watch \fIpathname\fP if it is a directory.  Using this flag provides an
 230 application with a race\-free way of ensuring that the monitored object is a
 231 directory.
 232 .RE
 233 .PP
 234 以下のビットが \fBread\fP(2)  で返される \fImask\fP フィールドに設定される:
 235 .RS 4
 236 .TP
 237 \fBIN_IGNORED\fP
 238 監視対象が (\fBinotify_rm_watch\fP(2) により) 明示的に 削除された。もしくは (ファイルの削除、またはファイル
 239 システムのアンマウントにより) 自動的に削除された。「バグ」も参照のこと。
 240 .TP
 241 \fBIN_ISDIR\fP
 242 このイベントの対象がディレクトリである。
 243 .TP
 244 \fBIN_Q_OVERFLOW\fP
 245 イベントキューが溢れた (このイベントの場合、\fIwd\fP は \-1 である)。
 246 .TP
 247 \fBIN_UNMOUNT\fP
 248 監視対象オブジェクトを含むファイルシステムがアンマウントされた。さらに、この監視対象ディスクリプタに対して \fBIN_IGNORED\fP
 249 イベントが生成される。
 250 .RE
 251 .SS 例
 252 アプリケーションがディレクトリ \fIdir\fP とファイル \fIdir/myfile\fP のすべてのイベントを監視しているとする。 以下に、これらの 2
 253 つのオブジェクトに対して生成されるイベントの例を示す。
 254 .RS 4
 255 .TP
 256 fd = open("dir/myfile", O_RDWR);
 257 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_OPEN\fP イベントが生成される。
 258 .TP
 259 read(fd, buf, count);
 260 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_ACCESS\fP イベントが生成される
 261 .TP
 262 write(fd, buf, count);
 263 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_MODIFY\fP イベントが生成される
 264 .TP
 265 fchmod(fd, mode);
 266 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_ATTRIB\fP イベントが生成される
 267 .TP
 268 close(fd);
 269 \fIdir\fP と \fIdir/myfile\fP の両方に対して \fBIN_CLOSE_WRITE\fP イベントが生成される
 270 .RE
 271 .PP
 272 アプリケーションがディレクトリ \fIdir1\fP と \fIdir2\fP、およびファイル \fIdir1/myfile\fP を監視しているとする。
 273 以下に生成されるイベントの例を示す。
 274 .RS 4
 275 .TP
 276 link("dir1/myfile", "dir2/new");
 277 \fImyfile\fP に対して \fBIN_ATTRIB\fP イベントが生成され、 \fIdir2\fP に対して \fBIN_CREATE\fP イベントが生成される。
 278 .TP
 279 rename("dir1/myfile", "dir2/myfile");
 280 \fIdir1\fP に対してイベント \fBIN_MOVED_FROM\fP が、 \fIdir2\fP に対してイベント \fBIN_MOVED_TO\fP が、
 281 \fImyfile\fP に対してイベント \fBIN_MOVE_SELF\fP が生成される。この際 イベント \fBIN_MOVED_FROM\fP と
 282 \fBIN_MOVED_TO\fP は同じ \fIcookie\fP 値を持つ。
 283 .RE
 284 .PP
 285 \fIdir1/xx\fP と \fIdir2/yy\fP は同じファイルを参照するリンクで (他のリンクはないものとする)、 アプリケーションは \fIdir1\fP,
 286 \fIdir2\fP, \fIdir1/xx\fP, \fIdir2/yy\fP を監視しているものとする。
 287 以下に示す順序で下記の呼び出しを実行すると、以下のイベントが生成される。
 288 .RS 4
 289 .TP
 290 unlink("dir2/yy");
 291 \fIxx\fP に対して \fBIN_ATTRIB\fP イベントが生成され (リンク数が変化したため)、 \fIdir2\fP に対して \fBIN_DELETE\fP
 292 イベントが生成される。
 293 .TP
 294 unlink("dir1/xx");
 295 \fIxx\fP に対してイベント \fBIN_ATTRIB\fP, \fBIN_DELETE_SELF\fP, \fBIN_IGNORED\fP が生成され、 \fIdir1\fP
 296 に対して \fBIN_DELETE\fP イベントが生成される。
 297 .RE
 298 .PP
 299 アプリケーションがディレクトリ \fIdir\fP と (空の) ディレクトリ \fIdir/subdir\fP を監視しているものとする。
 300 以下に生成されるイベントの例を示す。
 301 .RS 4
 302 .TP
 303 mkdir("dir/new", mode);
 304 \fIdir\fP に対して \fBIN_CREATE | IN_ISDIR\fP イベントが生成される。
 305 .TP
 306 rmdir("dir/subdir");
 307 \fIsubdir\fP に対してイベント \fBIN_DELETE_SELF\fP と \fBIN_IGNORED\fP が生成され、 \fIdir\fP に対して
 308 \fBIN_DELETE | IN_ISDIR\fP イベントが生成される。
 309 .RE
 310 .SS "/proc インターフェース"
 311 以下のインターフェースは、inotify で消費される カーネルメモリの総量を制限するのに使用できる:
 312 .TP
 313 \fI/proc/sys/fs/inotify/max_queued_events\fP
 314 このファイルの値は、アプリケーションが \fBinotify_init\fP(2)  を呼び出すときに使用され、対応する inotify インスタンスについて
 315 キューに入れられるイベントの数の上限を設定する。 この制限を超えたイベントは破棄されるが、 \fBIN_Q_OVERFLOW\fP イベントが常に生成される。
 316 .TP
 317 \fI/proc/sys/fs/inotify/max_user_instances\fP
 318 1 つの実ユーザ ID に対して生成できる inotify インスタンスの数の上限を指定する。
 319 .TP
 320 \fI/proc/sys/fs/inotify/max_user_watches\fP
 321 作成可能な監視対象の数の実 UID 単位の上限を指定する。
 322 .SH バージョン
 323 inotify は 2.6.13 の Linux カーネルに組込まれた。 これに必要なライブラリのインターフェースは、 glibc のバージョン 2.4
 324 に追加された (\fBIN_DONT_FOLLOW\fP, \fBIN_MASK_ADD\fP, \fBIN_ONLYDIR\fP は glibc バージョン 2.5
 325 で追加された)。
 326 .SH 準拠
 327 inotify API は Linux 独自のものである。
 328 .SH 注意
 329 inotify ファイルディスクリプタは \fBselect\fP(2), \fBpoll\fP(2), \fBepoll\fP(7)  を使って監視できる。
 330 イベントがある場合、ファイルディスクリプタは読み込み可能と通知する。
 331
 332 Linux 2.6.25 以降では、シグナル駆動 (signal\-driven) I/O の通知が inotify
 333 ファイルディスクリプタについて利用可能である。 \fBfcntl\fP(2)  に書かれている (\fBO_ASYNC\fP フラグを設定するための)
 334 \fBF_SETFL\fP, \fBF_SETOWN\fP, \fBF_SETSIG\fP の議論を参照のこと。 シグナルハンドラに渡される \fIsiginfo_t\fP
 335 構造体は、以下のフィールドが設定される (\fIsiginfo_t\fP は \fBsigaction\fP(2)  で説明されている)。 \fIsi_fd\fP には
 336 inotify ファイルディスクリプタ番号が、 \fIsi_signo\fP にはシグナル番号が、 \fIsi_code\fP には \fBPOLL_IN\fP が、
 337 \fIsi_band\fP には \fBPOLLIN\fP が設定される。
 338
 339 inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 (\fIwd\fP, \fImask\fP,
 340 \fIcookie\fP, \fIname\fP が等しい場合)、 前のイベントがまだ読み込まれていなければ、 連続するイベントが 1 つのイベントにまとめられる
 341 (ただし「バグ」の節も参照のこと)。 これによりイベントキューに必要なカーネルメモリ量が減るが、
 342 これはまたアプリケーションがファイルイベント数を信頼性を持って数えるのに inotify を使用できないということでもある。
 343
 344 inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。
 345 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で
 346 イベントが生成されることが保証される。
 347
 348 \fBFIONREAD\fP \fBioctl\fP(2)  は inotify ファイルディスクリプタから何バイト読み込めるかを返す。
 349 .SS 制限と警告
 350 inotify API では、inotify イベントが発生するきっかけとなったユーザやプロセスに関する情報は提供されない。とりわけ、inotify
 351 経由でイベントを監視しているプロセスが、自分自身がきっかけとなったイベントと他のプロセスがきっかけとなったイベントを区別する簡単な手段はない。
 352
 353 inotify は、ファイルシステム API 経由でユーザー空間プログラムがきっかけとなったイベントだけを報告する。 結果として、 inotify
 354 はネットワークファイルシステムで発生したリモートのイベントを捉えることはできない
 355 (このようなイベントを捉えるにはアプリケーションはファイルシステムをポーリングする必要がある)。 さらに、 \fI/proc\fP, \fI/sys\fP,
 356 \fI/dev/pts\fP といったいくつかの疑似ファイルシステムは inotify で監視することができない。
 357
 358 inotify API は \fBmmap\fP(2), \fBmsync\fP(2), \fBmunmap\fP(2)
 359 により起こったファイルのアクセスと変更を報告しない。
 360
 361 inotify API では影響が受けるファイルをファイル名で特定する。
 362 しかしながら、アプリケーションが inotify イベントを処理する時点では、
 363 そのファイル名がすでに削除されたり変更されたりしている可能性がある。
 364
 365 inotify API では監視対象ディスクリプタを通してイベントが区別される。 (必要であれば)
 366 監視対象ディスクリプタとパス名のマッピングをキャッシュしておくのはアプリケーションの役目である。
 367 ディレクトリの名前変更の場合、キャッシュしている複数のパス名に影響がある点に注意すること。
 368
 369 inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ以下の
 370 サブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。
 371 大きなディレクトリツリーの場合には、この作業にかなり時間がかかることがある。
 372
 373 ディレクトリツリー全体を監視していて、 そのツリー内に新しいサブディレクトリが作成されるか、
 374 既存のディレクトリが名前が変更されそのツリー内に移動した場合、 新しいサブディレクトリに対する watch を作成するまでに、 新しいファイル
 375 (やサブディレクトリ) がそのサブディレクトリ内にすでに作成されている場合がある点に注意すること。 したがって、watch
 376 を追加した直後にサブディレクトリの内容をスキャンしたいと思う場合もあるだろう (必要ならそのサブディレクトリ内のサブディレクトリに対する watch
 377 も再帰的に追加することもあるだろう)。
 378
 379 イベントキューはオーバーフローする場合があることに注意すること。 この場合、イベントは失なわれる。 ロバスト性が求められるアプリケーションでは、
 380 イベントが失なわれる可能性も含めて適切に処理を行うべきである。
 381 例えば、アプリケーション内のキャッシュの一部分または全てを再構築する必要があるかもしれない。 (単純だが、おそらくコストがかかる方法は、 inotify
 382 ファイルディスクリプタをクローズし、 キャッシュを空にし、 新しい inotify ファイルディスクリプタを作成し、
 383 監視しているオブジェクトの監視対象ディスクリプタとキャッシュエントリーの再作成を行う方法である。)
 384 .SS "rename() イベントの取り扱い"
 385 上述の通り、 \fBrename\fP(2) により生成される \fBIN_MOVED_FROM\fP と \fBIN_MOVED_TO\fP イベントの組は、共有される
 386 cookie 値によって対応を取ることができる。 しかし、対応を取る場合にはいくつか難しい点がある。
 387
 388 These two events are usually consecutive in the event stream available when
 389 reading from the inotify file descriptor.  However, this is not guaranteed.
 390 If multiple processes are triggering events for monitored objects, then (on
 391 rare occasions) an arbitrary number of other events may appear between the
 392 \fBIN_MOVED_FROM\fP and \fBIN_MOVED_TO\fP events.  Furthermore, it is not
 393 guaranteed that the event pair is atomically inserted into the queue: there
 394 may be a brief interval where the \fBIN_MOVED_FROM\fP has appeared, but the
 395 \fBIN_MOVED_TO\fP has not.
 396
 397 したがって、 \fBrename\fP(2) により生成された \fBIN_MOVED_FROM\fP と \fBIN_MOVED_TO\fP
 398 のイベントの組の対応を取るのは本質的に難しいことである (監視対象のディレクトリの外へオブジェクトの rename が行われた場合には
 399 \fBIN_MOVED_TO\fP イベントは存在しさえしないことを忘れてはならない)。 (イベントは常に連続しているとの仮定を置くといった)
 400 発見的な方法を使うと、ほとんどの場合でイベントの組をうまく見つけることができるが、 いくつかの場合に見逃すことが避けられず、 アプリケーションが
 401 \fBIN_MOVED_FROM\fP と \fBIN_MOVED_TO\fP イベントが無関係だとみなしてしまう可能性がある。
 402 結果的に、監視対象ディスクリプタが破棄され再作成された場合、これらの監視対象ディスクリプタは、処理待ちイベントの監視対象ディスクリプタと一貫性のないものになってしまう
 403 (inotify ファイルディスクリプタの再作成とキャッシュの再構成はこの状況に対処するのに有用な方法なのだが)。
 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), which should be done with a (small)
 409 timeout to allow for the fact that insertion of the
 410 \fBIN_MOVED_FROM\fP\-\fBIN_MOVED_TO\fP event pair is not atomic, and also the
 411 possibility that there may not be any \fBIN_MOVED_TO\fP event.
 412 .SH バグ
 413 As of kernel 3.17, calling \fBfallocate\fP(2)  does not create any inotify
 414 events.
 415
 416 .\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321
 417 .\" implies that unmount events were buggy 2.6.11 to 2.6.36
 418 .\"
 419 2.6.16 以前のカーネルでは \fBIN_ONESHOT\fP \fImask\fP フラグが働かない。
 420
 421 元々は設計/実装時の意図通り、 イベントが一つ発生し watch が削除された際に \fBIN_ONESHOT\fP フラグでは \fBIN_IGNORED\fP
 422 イベントが発生しなかった。 しかし、 別の変更での意図していなかった影響により、 Linux 2.6.36 以降では、 この場合に
 423 \fBIN_IGNORED\fP イベントが生成される。
 424
 425 .\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2
 426 カーネル 2.6.25 より前では、 連続する同一のイベントを一つにまとめることを意図したコード (古い方のイベントがまだ読み込まれていない場合に、
 427 最新の 2 つのイベントを一つにまとめられる可能性がある) が、 最新のイベントが「最も古い」読み込まれていないイベントとまとめられるか
 428 をチェックするようになっていた。
 429
 430 .\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=77111
 431 When a watch descriptor is removed by calling \fBinotify_rm_watch\fP(2)  (or
 432 because a watch file is deleted or the filesystem that contains it is
 433 unmounted), any pending unread events for that watch descriptor remain
 434 available to read.  As watch descriptors are subsequently allocated with
 435 \fBinotify_add_watch\fP(2), the kernel cycles through the range of possible
 436 watch descriptors (0 to \fBINT_MAX\fP)  incrementally.  When allocating a free
 437 watch descriptor, no check is made to see whether that watch descriptor
 438 number has any pending unread events in the inotify queue.  Thus, it can
 439 happen that a watch descriptor is reallocated even when pending unread
 440 events exist for a previous incarnation of that watch descriptor number,
 441 with the result that the application might then read those events and
 442 interpret them as belonging to the file associated with the newly recycled
 443 watch descriptor.  In practice, the likelihood of hitting this bug may be
 444 extremely low, since it requires that an application cycle through
 445 \fBINT_MAX\fP watch descriptors, release a watch descriptor while leaving
 446 unread events for that watch descriptor in the queue, and then recycle that
 447 watch descriptor.  For this reason, and because there have been no reports
 448 of the bug occurring in real\-world applications, as of Linux 3.15, no kernel
 449 changes have yet been made to eliminate this possible bug.
 450 .SH 例
 451 以下のプログラムは inotify API の使用例を示したものである。 コマンドライン引き数で渡されたディレクトリに印を付け、 タイプが
 452 \fBIN_OPEN\fP, \fBIN_CLOSE_NOWRITE\fP \fBIN_CLOSE_WRITE\fP のイベントを待つ。
 453 .PP
 454 以下は、 ファイル \fI/home/user/temp/foo\fP を編集し、 ディレクトリ \fI/tmp\fP の一覧表示を行った場合の出力である。
 455 対象のファイルとディレクトリがオープンされる前に、イベント \fBIN_OPEN\fP が発生している。 対象ファイルがクローズされた後にイベント
 456 \fBIN_CLOSE_WRITE\fP が発生している。 対象ディレクトリがクローズされた後にイベント \fBIN_CLOSE_NOWRITE\fP
 457 が発生している。 ユーザーが ENTER キーを押すると、プログラムの実行は終了する。
 458 .SS 出力例
 459 .in +4n
 460 .nf
 461 $ \fB./a.out /tmp /home/user/temp\fP
 462 Press enter key to terminate.
 463 Listening for events.
 464 IN_OPEN: /home/user/temp/foo [file]
 465 IN_CLOSE_WRITE: /home/user/temp/foo [file]
 466 IN_OPEN: /tmp/ [directory]
 467 IN_CLOSE_NOWRITE: /tmp/ [directory]
 468
 469 Listening for events stopped.
 470 .fi
 471 .in
 472 .SS プログラムソース
 473 .nf
 474 #include <errno.h>
 475 #include <poll.h>
 476 #include <stdio.h>
 477 #include <stdlib.h>
 478 #include <sys/inotify.h>
 479 #include <unistd.h>
 480
 481 /* Read all available inotify events from the file descriptor 'fd'.
 482    wd is the table of watch descriptors for the directories in argv.
 483    argc is the length of wd and argv.
 484    argv is the list of watched directories.
 485    Entry 0 of wd and argv is unused. */
 486
 487 static void
 488 handle_events(int fd, int *wd, int argc, char* argv[])
 489 {
 490     /* Some systems cannot read integer variables if they are not
 491        properly aligned. On other systems, incorrect alignment may
 492        decrease performance. Hence, the buffer used for reading from
 493        the inotify file descriptor should have the same alignment as
 494        struct inotify_event. */
 495
 496     char buf[4096]
 497         __attribute__ ((aligned(__alignof__(struct inotify_event))));
 498     const struct inotify_event *event;
 499     int i;
 500     ssize_t len;
 501     char *ptr;
 502
 503     /* Loop while events can be read from inotify file descriptor. */
 504
 505     for (;;) {
 506
 507         /* Read some events. */
 508
 509         len = read(fd, buf, sizeof buf);
 510         if (len == \-1 && errno != EAGAIN) {
 511             perror("read");
 512             exit(EXIT_FAILURE);
 513         }
 514
 515         /* If the nonblocking read() found no events to read, then
 516            it returns \-1 with errno set to EAGAIN. In that case,
 517            we exit the loop. */
 518
 519         if (len <= 0)
 520             break;
 521
 522         /* Loop over all events in the buffer */
 523
 524         for (ptr = buf; ptr < buf + len;
 525                 ptr += sizeof(struct inotify_event) + event\->len) {
 526
 527             event = (const struct inotify_event *) ptr;
 528
 529             /* Print event type */
 530
 531             if (event\->mask & IN_OPEN)
 532                 printf("IN_OPEN: ");
 533             if (event\->mask & IN_CLOSE_NOWRITE)
 534                 printf("IN_CLOSE_NOWRITE: ");
 535             if (event\->mask & IN_CLOSE_WRITE)
 536                 printf("IN_CLOSE_WRITE: ");
 537
 538             /* Print the name of the watched directory */
 539
 540             for (i = 1; i < argc; ++i) {
 541                 if (wd[i] == event\->wd) {
 542                     printf("%s/", argv[i]);
 543                     break;
 544                 }
 545             }
 546
 547             /* Print the name of the file */
 548
 549             if (event\->len)
 550                 printf("%s", event\->name);
 551
 552             /* Print type of filesystem object */
 553
 554             if (event\->mask & IN_ISDIR)
 555                 printf(" [directory]\en");
 556             else
 557                 printf(" [file]\en");
 558         }
 559     }
 560 }
 561
 562 int
 563 main(int argc, char* argv[])
 564 {
 565     char buf;
 566     int fd, i, poll_num;
 567     int *wd;
 568     nfds_t nfds;
 569     struct pollfd fds[2];
 570
 571     if (argc < 2) {
 572         printf("Usage: %s PATH [PATH ...]\en", argv[0]);
 573         exit(EXIT_FAILURE);
 574     }
 575
 576     printf("Press ENTER key to terminate.\en");
 577
 578     /* Create the file descriptor for accessing the inotify API */
 579
 580     fd = inotify_init1(IN_NONBLOCK);
 581     if (fd == \-1) {
 582         perror("inotify_init1");
 583         exit(EXIT_FAILURE);
 584     }
 585
 586     /* Allocate memory for watch descriptors */
 587
 588     wd = calloc(argc, sizeof(int));
 589     if (wd == NULL) {
 590         perror("calloc");
 591         exit(EXIT_FAILURE);
 592     }
 593
 594     /* Mark directories for events
 595        \- file was opened
 596        \- file was closed */
 597
 598     for (i = 1; i < argc; i++) {
 599         wd[i] = inotify_add_watch(fd, argv[i],
 600                                   IN_OPEN | IN_CLOSE);
 601         if (wd[i] == \-1) {
 602             fprintf(stderr, "Cannot watch '%s'\en", argv[i]);
 603             perror("inotify_add_watch");
 604             exit(EXIT_FAILURE);
 605         }
 606     }
 607
 608     /* Prepare for polling */
 609
 610     nfds = 2;
 611
 612     /* Console input */
 613
 614     fds[0].fd = STDIN_FILENO;
 615     fds[0].events = POLLIN;
 616
 617     /* Inotify input */
 618
 619     fds[1].fd = fd;
 620     fds[1].events = POLLIN;
 621
 622     /* Wait for events and/or terminal input */
 623
 624     printf("Listening for events.\en");
 625     while (1) {
 626         poll_num = poll(fds, nfds, \-1);
 627         if (poll_num == \-1) {
 628             if (errno == EINTR)
 629                 continue;
 630             perror("poll");
 631             exit(EXIT_FAILURE);
 632         }
 633
 634         if (poll_num > 0) {
 635
 636             if (fds[0].revents & POLLIN) {
 637
 638                 /* Console input is available. Empty stdin and quit */
 639
 640                 while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\en')
 641                     continue;
 642                 break;
 643             }
 644
 645             if (fds[1].revents & POLLIN) {
 646
 647                 /* Inotify events are available */
 648
 649                 handle_events(fd, wd, argc, argv);
 650             }
 651         }
 652     }
 653
 654     printf("Listening for events stopped.\en");
 655
 656     /* Close inotify file descriptor */
 657
 658     close(fd);
 659
 660     free(wd);
 661     exit(EXIT_SUCCESS);
 662 }
 663 .fi
 664 .SH 関連項目
 665 \fBinotifywait\fP(1), \fBinotifywatch\fP(1), \fBinotify_add_watch\fP(2),
 666 \fBinotify_init\fP(2), \fBinotify_init1\fP(2), \fBinotify_rm_watch\fP(2), \fBread\fP(2),
 667 \fBstat\fP(2), \fBfanotify\fP(7)
 668
 669 Linux カーネルソース内の \fIDocumentation/filesystems/inotify.txt\fP
 670 .SH この文書について
 671 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.76 の一部
 672 である。プロジェクトの説明とバグ報告に関する情報は
 673 http://www.kernel.org/doc/man\-pages/ に書かれている。