release/man7/inotify.7

   1 '\" t
   2 .\" Hey Emacs! This file is -*- nroff -*- source.
   3 .\"
   4 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   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 .\"
  26 .\" Japanese Version Copyright (c) 2006 Yuichi SATO
  27 .\"     and Copyright (c) 2007-2008 Akihiro MOTOKI
  28 .\" Translated 2006-07-05 by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v2.29
  29 .\" Updated 2006-07-20 by Yuichi SATO, LDP v2.36
  30 .\" Updated 2007-06-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.55
  31 .\" Updated 2008-08-10, Akihiro MOTOKI, LDP v3.05
  32 .\" Updated 2008-09-19, Akihiro MOTOKI, LDP v3.08
  33 .\"
  34 .TH INOTIFY 7 2008-11-18 "Linux" "Linux Programmer's Manual"
  35 .SH 名前
  36 inotify \- ファイルシステムイベントを監視する
  37 .SH 説明
  38 .I inotify
  39 API はファイルシステムイベントを監視するための機構を提供する。
  40 inotify は個々のファイルやディレクトリを監視するのに使える。
  41 ディレクトリを監視する場合、inotify はディレクトリ自身と
  42 ディレクトリ内のファイルのイベントを返す。
  43
  44 以下のシステムコールがこの API と共に使用される:
  45 .BR inotify_init (2)
  46 (や
  47 .BR inotify_init1 (2)),
  48 .BR inotify_add_watch (2),
  49 .BR inotify_rm_watch (2),
  50 .BR read (2),
  51 .BR close (2).
  52
  53 .BR inotify_init (2)
  54 は inotify インスタンスを作成し、inotify インスタンスを参照する
  55 ファイルディスクリプタを返す。
  56 もっと新しい
  57 .BR inotify_init1 (2)
  58 も
  59 .BR inotify_init (2)
  60 と同様だが、いくつかの追加の機能が提供されている。
  61
  62 .BR inotify_add_watch (2)
  63 は inotify インスタンスに関連づけられた「監視対象 (watch) リスト」を操作する。
  64 監視対象リストの各アイテム ("watch") は、
  65 ファイルまたはディレクトリのパス名と、
  66 そのパス名で参照されるファイルに対して
  67 カーネルが監視する複数のイベントの集合を指定する。
  68 .BR inotify_add_watch (2)
  69 は新しい監視アイテムの作成や既存の監視対象の変更ができる。
  70 各監視対象は一意の「監視対象ディスクリプタ」を持つ。
  71 これは監視対象を作成したときに
  72 .BR inotify_add_watch (2)
  73 から返される整数である。
  74
  75 .BR inotify_rm_watch (2)
  76 は inotify の監視対象リストからアイテムを削除する。
  77
  78 inotify インスタンスを指している
  79 全てのファイルディスクリプタがクローズされた場合、
  80 その下層にあるオブジェクトとそのリソースは、
  81 カーネルで再利用するために解放される。
  82 関連が切られた監視対象は自動的に解放される。
  83
  84 どのようなイベントが起こっていたかを知るには、
  85 アプリケーションで inotify ファイルディスクリプタを
  86 .BR read (2)
  87 すればよい。
  88 これまでに何もイベントが起こっていない場合、
  89 停止 (blocking) モードのファイルディスクリプタであれば、
  90 少なくとも 1 つのイベントが起こるまで
  91 .BR read (2)
  92 は停止する (シグナルにより割り込まれなかった場合。
  93 シグナルによる割り込みがあった場合、呼び出しはエラー
  94 .BR EINTR
  95 で失敗する。
  96 .BR signal (7)
  97 参照)。
  98
  99 .BR read (2)
 100 が成功すると、以下の構造体を 1 つ以上含むバッファが返される:
 101 .in +4n
 102 .nf
 103
 104 struct inotify_event {
 105     int      wd;       /* 監視対象ディスクリプタ */
 106 .\" FIXME . The type of the 'wd' field should probably be "int32_t".
 107 .\" I submitted a patch to fix this.  See the LKML thread
 108 .\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008
 109 .\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040
 110     uint32_t mask;     /* イベントのマスク */
 111     uint32_t cookie;   /* 関連するイベント群を関連づける
 112                           一意なクッキー (rename(2) 用) */
 113     uint32_t len;      /* \(aqname\(aq フィールドのサイズ */
 114     char     name[];   /* NULL で終端された任意の名前 */
 115 };
 116 .fi
 117 .in
 118
 119 .I wd
 120 はイベント発生の監視対象を指定する。
 121 これは、前もって行われた
 122 .BR inotify_add_watch (2)
 123 呼び出しで返された監視対象ディスクリプタのうちの 1 つである。
 124
 125 .I mask
 126 には発生したイベント (下記参照) を記述するためのビットが含まれる。
 127
 128 .I cookie
 129 は関連するイベントを関連づけるための一意な整数である。
 130 現在のところ、この値は rename イベントに対してのみ使われており、
 131 結果のペアである
 132 .B IN_MOVE_FROM
 133 と
 134 .B IN_MOVE_TO
 135 イベントをアプリケーションで関連づけることができる。
 136
 137 .I name
 138 フィールドは監視しているディレクトリ内のファイルに対して
 139 イベントが返される場合のためにだけ存在する。
 140 監視するディレクトリからのファイルの相対パス名を表す。
 141 このパス名は NULL で終端され、
 142 その後の読み込みで適切なアドレス境界に調整するために、
 143 さらに NULL バイトが含まれる場合もある。
 144
 145 .I len
 146 フィールドは NULL バイトを含む
 147 .I name
 148 の全てのバイト数を表す。
 149 よって、
 150 .I inotify_event
 151 構造体のサイズは
 152 .I "sizeof(inotify_event)+len"
 153 である。
 154
 155 .BR read (2)
 156 に渡されたバッファが小さすぎて次のイベントに関する情報を返せない
 157 場合の動作はカーネルのバージョンにより異なる。
 158 2.6.21 より前のカーネルでは、
 159 .BR read (2)
 160 は 0 を返す。
 161 2.6.21 以降のカーネルでは、
 162 .BR read (2)
 163 はエラー
 164 .B EINVAL
 165 で失敗する。
 166 .SS inotify イベント
 167 .BR inotify_add_watch (2)
 168 の
 169 .I mask
 170 引き数と、inotify ファイル構造体を
 171 .BR read (2)
 172 したときに返される
 173 .I inotify_event
 174 構造体の
 175 .I mask
 176 フィールドは、ともに inotify イベントを識別するための
 177 ビットマスクである。
 178 以下のビットが
 179 .BR inotify_add_watch (2)
 180 を呼ぶときの
 181 .I mask
 182 に指定可能であり、
 183 .BR read (2)
 184 で返される
 185 .I mask
 186 フィールドで返される:
 187 .RS 4
 188 .sp
 189 .PD 0
 190 .TP 18
 191 .B IN_ACCESS
 192 ファイルがアクセス (read) された。(*)
 193 .TP
 194 .B IN_ATTRIB
 195 メタデータが変更された。
 196 メタデータとは、例えば、許可 (permission)、タイムスタンプ、拡張属性、
 197 リンクカウント (Linux 2.6.25 以降)、UID、GID などである。(*)
 198 .TP
 199 .B IN_CLOSE_WRITE
 200 書き込みのためにオープンされたファイルがクローズされた。(*)
 201 .TP
 202 .B IN_CLOSE_NOWRITE
 203 書き込み以外のためにオープンされたファイルがクローズされた。(*)
 204 .TP
 205 .B IN_CREATE
 206 監視対象ディレクトリ内でファイルやディレクトリが作成された。(*)
 207 .TP
 208 .B IN_DELETE
 209 監視対象ディレクトリ内でファイルやディレクトリが削除された。(*)
 210 .TP
 211 .B IN_DELETE_SELF
 212 監視対象のディレクトリまたはファイル自身が削除された。
 213 .TP
 214 .B IN_MODIFY
 215 ファイルが修正された。(*)
 216 .TP
 217 .B IN_MOVE_SELF
 218 監視対象のディレクトリまたはファイル自身が移動された。
 219 .TP
 220 .B IN_MOVED_FROM
 221 ファイルが監視対象ディレクトリ外へ移動された。(*)
 222 .TP
 223 .B IN_MOVED_TO
 224 ファイルが監視対象ディレクトリ内へ移動された。(*)
 225 .TP
 226 .B IN_OPEN
 227 ファイルがオープンされた。(*)
 228 .PD
 229 .RE
 230 .PP
 231 ディレクトリを監視する場合、
 232 上記でアスタリスク (*) を付けたイベントは、
 233 そのディレクトリ内のファイルに対して発生する。
 234 このとき
 235 .I inotify_event
 236 構造体で返される
 237 .I name
 238 フィールドは、ディレクトリ内のファイル名を表す。
 239 .PP
 240 .B IN_ALL_EVENTS
 241 マクロは上記のイベント全てのマスクとして定義される。
 242 このマクロは
 243 .BR inotify_add_watch (2)
 244 を呼び出すときの
 245 .I mask
 246 引き数として使える。
 247
 248 さらに 2 つの便利なマクロがある。
 249 .B IN_MOVE
 250 は
 251 IN_MOVED_FROM|IN_MOVED_TO
 252 と等しく、
 253 .B IN_CLOSE
 254 は
 255 IN_CLOSE_WRITE|IN_CLOSE_NOWRITE
 256 と等しい。
 257 .PP
 258 その他にも以下のビットを
 259 .BR inotify_add_watch (2)
 260 を呼ぶときの
 261 .I mask
 262 に指定できる:
 263 .RS 4
 264 .sp
 265 .PD 0
 266 .TP 18
 267 .B IN_DONT_FOLLOW
 268 \fIpathname\fP がシンボリックリンクである場合に辿らない。
 269 (Linux 2.6.15 以降)
 270 .TP
 271 .B IN_MASK_ADD
 272 \fIpathname\fP に対する監視マスクが既に存在する場合、
 273 (マスクの置き換えではなく) イベントを追加 (OR) する。
 274 .TP
 275 .B IN_ONESHOT
 276 1 つのイベントについて \fIpathname\fP を監視し、
 277 イベントが発生したら監視対象リストから削除する。
 278 .TP
 279 .BR IN_ONLYDIR " (Linux 2.6.15 以降)"
 280 \fIpathname\fP がディレクトリの場合にのみ監視する。
 281 .PD
 282 .RE
 283 .PP
 284 以下のビットが
 285 .BR read (2)
 286 で返される
 287 .I mask
 288 フィールドに設定される:
 289 .RS 4
 290 .sp
 291 .PD 0
 292 .TP 18
 293 .B IN_IGNORED
 294 監視対象が (\fBinotify_rm_watch\fP(2) により) 明示的に
 295 削除された。もしくは (ファイルの削除、またはファイル
 296 システムのアンマウントにより) 自動的に削除された。
 297 .TP
 298 .B IN_ISDIR
 299 このイベントの対象がディレクトリである。
 300 .TP
 301 .B IN_Q_OVERFLOW
 302 イベントキューが溢れた (このイベントの場合、\fIwd\fP は \-1 である)。
 303 .TP
 304 .B IN_UNMOUNT
 305 監視対象オブジェクトを含むファイルシステムがアンマウントされた。
 306 .PD
 307 .RE
 308 .SS /proc インターフェース
 309 以下のインターフェースは、inotify で消費される
 310 カーネルメモリの総量を制限するのに使用できる:
 311 .TP
 312 .I /proc/sys/fs/inotify/max_queued_events
 313 このファイルの値は、アプリケーションが
 314 .BR inotify_init (2)
 315 を呼び出すときに使用され、対応する inotify インスタンスについて
 316 キューに入れられるイベントの数の上限を設定する。
 317 この制限を超えたイベントは破棄されるが、
 318 .B IN_Q_OVERFLOW
 319 イベントが常に生成される。
 320 .TP
 321 .I /proc/sys/fs/inotify/max_user_instances
 322 1 つの実ユーザ ID に対して生成できる
 323 inotify インスタンスの数の上限を指定する。
 324 .TP
 325 .I /proc/sys/fs/inotify/max_user_watches
 326 作成可能な監視対象の数の実 UID 単位の上限を指定する。
 327 .SH バージョン
 328 inotify は 2.6.13 の Linux カーネルに組込まれた。
 329 これに必要なライブラリのインターフェースは、
 330 glibc のバージョン 2.4 に追加された
 331 .RB ( IN_DONT_FOLLOW ,
 332 .BR IN_MASK_ADD ,
 333 .B IN_ONLYDIR
 334 だけはバージョン 2.5 で追加された)。
 335 .SH 準拠
 336 inotify API は Linux 独自のものである。
 337 .SH 注意
 338 inotify ファイルディスクリプタは
 339 .BR select (2),
 340 .BR poll (2),
 341 .BR epoll (7)
 342 を使って監視できる。
 343 イベントがある場合、ファイルディスクリプタは読み込み可能と通知する。
 344
 345 Linux 2.6.25 以降では、シグナル駆動 (signal-driven) I/O の通知が
 346 inotify ファイルディスクリプタについて利用可能である。
 347 .BR fcntl (2)
 348 に書かれている
 349 .RB ( O_ASYNC
 350 フラグを設定するための)
 351 .BR F_SETFL ,
 352 .BR F_SETOWN ,
 353 .B F_SETSIG
 354 の議論を参照のこと。
 355 シグナルハンドラに渡される
 356 .I siginfo_t
 357 構造体は、以下のフィールドが設定される
 358 .RI ( siginfo_t
 359 は
 360 .BR sigaction (2)
 361 で説明されている)。
 362 .I si_fd
 363 には inotify ファイルディスクリプタ番号が、
 364 .I si_signo
 365 にはシグナル番号が、
 366 .I si_code
 367 には
 368 .BR POLL_IN
 369 が、
 370 .I si_band
 371 には
 372 .B POLLIN
 373 が設定される。
 374
 375 inotify ファイルディスクリプタに対して
 376 連続して生成される出力 inotify イベントが同一の場合
 377 .RI ( wd ,
 378 .IR mask ,
 379 .IR cookie ,
 380 .I name
 381 が等しい場合)、
 382 前のイベントがまだ読み込まれていなければ、
 383 連続するイベントが 1 つのイベントにまとめられる
 384 (ただし「バグ」の節も参照のこと)。
 385
 386 inotify ファイルディスクリプタの読み込みで返されるイベントは、
 387 順序付けられたキューになる。
 388 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、
 389 inotify ファイルディスクリプタについての正しい順番で
 390 イベントが生成されることが保証される。
 391
 392 .B FIONREAD
 393 .BR ioctl (2)
 394 は inotify ファイルディスクリプタから何バイト読み込めるかを返す。
 395
 396 inotify によるディレクトリの監視は再帰的に行われない:
 397 あるディレクトリ以下のサブディレクトリを監視する場合、
 398 監視対象を追加で作成しなければならない。
 399 .SH バグ
 400 2.6.16 以前のカーネルでは
 401 .B IN_ONESHOT
 402 .I mask
 403 フラグが働かない。
 404
 405 カーネル 2.6.25 より前では、
 406 連続する同一のイベントを一つにまとめることを意図したコード
 407 (古い方のイベントがまだ読み込まれていない場合に、
 408 最新の 2 つのイベントを一つにまとめられる可能性がある) が、
 409 最新のイベントが「最も古い」読み込まれていないイベントとまとめられるか
 410 をチェックするようになっていた。
 411 .SH 関連項目
 412 .BR inotify_add_watch (2),
 413 .BR inotify_init (2),
 414 .BR inotify_init1 (2),
 415 .BR inotify_rm_watch (2),
 416 .BR read (2),
 417 .BR stat (2),
 418 .IR Documentation/filesystems/inotify.txt .