Linux Certif

Toute la documentation sur la certification Linux LPI

inotify

名前

inotify - ファイルシステムイベントを監視する

説明

inotify API はファイルシステムイベントを監視するための機構を提供する。 inotify は個々のファイルやディレクトリを監視するのに使える。 ディレクトリを監視する場合、inotify はディレクトリ自身と ディレクトリ内のファイルのイベントを返す。

以下のシステムコールがこの API と共に使用される。 inotify_init(2), inotify_add_watch(2), inotify_rm_watch(2), read(2), close(2).

inotify_init(2) は inotify インスタンスを作成し、inotify インスタンスを参照する ファイルディスクリプタを返す。

inotify_add_watch(2) は inotify インスタンスに関連づけられた「監視対象 (watch) リスト」を操作する。 監視対象リストの各アイテム ("watch") は、 ファイルまたはディレクトリのパス名と、 そのパス名で参照されるファイルに対して カーネルが監視する複数のイベントの集合を指定する。 inotify_add_watch(2) は新しい監視アイテムの作成や既存の監視対象の変更ができる。 各監視対象は一意の「監視対象ディスクリプタ」を持つ。 これは監視対象を作成したときに inotify_add_watch(2) から返される整数である。

inotify_rm_watch(2) は inotify の監視対象リストからアイテムを削除する。

inotify インスタンスを指している 全てのファイルディスクリプタがクローズされた場合、 その下層にあるオブジェクトとそのリソースは、 カーネルで再利用するために解放される。 関連が切られた監視対象は自動的に解放される。

どのようなイベントが起こっていたかを知るには、 アプリケーションで inotify ファイルディスクリプタを read(2) すればよい。 これまでに何もイベントが起こっていない場合、 停止 (blocking) モードのファイルディスクリプタであれば、 少なくとも 1 つのイベントが起こるまで read(2) は停止する。

read(2) が成功すると、以下の構造体を 1 つ以上含むバッファが返される:

 
 struct inotify_event {
     int      wd;       /* 監視対象ディスクリプタ */
     uint32_t mask;     /* イベントのマスク */
     uint32_t cookie;   /* 関連するイベント群を関連づける
                           一意なクッキー (rename(2) 用) */
     uint32_t len;      /* 'name' フィールドのサイズ */
     char     name[];   /* NULL で終端された任意の名前 */
 };
 

wd はイベント発生の監視対象を指定する。 これは、前もって行われた inotify_add_watch(2) 呼び出しで返された監視対象ディスクリプタのうちの 1 つである。

mask には発生したイベント (下記参照) を記述するためのビットが含まれる。

cookie は関連するイベントを関連づけるための一意な整数である。 現在のところ、この値は rename イベントに対してのみ使われており、 結果のペアである IN_MOVE_FROM と IN_MOVE_TO イベントをアプリケーションで関連づけることができる。

name フィールドは監視しているディレクトリ内のファイルに対して イベントが返される場合のためにだけ存在する。 監視するディレクトリからのファイルの相対パス名を表す。 このパス名は NULL で終端され、 その後の読み込みで適切なアドレス境界に調整するために、 さらに NULL バイトが含まれる場合もある。

len フィールドは NULL バイトを含む name の全てのバイト数を表す。 よって、 inotify_event 構造体のサイズは sizeof(inotify_event)+len である。

inotify イベント

inotify_add_watch(2) の mask 引き数と、inotify ファイル構造体を read(2) したときに返される inotify_event 構造体の mask フィールドは、ともに inotify イベントを識別するための ビットマスクである。 以下のビットが inotify_add_watch(2) を呼ぶときの mask に指定可能であり、 read(2) で返される mask フィールドで返される:

ビット	説明
IN_ACCESS	ファイルがアクセス (read) された。(*)
IN_ATTRIB	メタデータが変更された (許可、タイムスタンプ、
	拡張属性など)。(*)
IN_CLOSE_WRITE	書き込みのためにオープンされたファイルが
	クローズされた。(*)
IN_CLOSE_NOWRITE	書き込み以外のためにオープンされたファイルが
	クローズされた。(*)
IN_CREATE	監視対象ディレクトリ内でファイルや
	ディレクトリが作成された。(*)
IN_DELETE	監視対象ディレクトリ内でファイルや
	ディレクトリが削除された。(*)
IN_DELETE_SELF	監視対象のディレクトリまたはファイル自身が
	削除された。
IN_MODIFY	ファイルが修正された。(*)
IN_MOVE_SELF	監視対象のディレクトリまたはファイル自身が
	移動された。
IN_MOVED_FROM	ファイルが監視対象ディレクトリ外へ移動された。(*)
IN_MOVED_TO	ファイルが監視対象ディレクトリ内へ移動された。(*)
IN_OPEN	ファイルがオープンされた。(*)

ディレクトリを監視する場合、 上記でアスタリスク (*) を付けたイベントは、 そのディレクトリ内のファイルに対して発生する。 このとき inotify_event 構造体で返される name フィールドは、ディレクトリ内のファイル名を表す。

IN_ALL_EVENTS マクロは上記のイベント全てのマスクとして定義される。 このマクロは inotify_add_watch(2) を呼び出すときの mask 引き数として使える。

さらに 2 つの便利なマクロがある。 IN_MOVE は IN_MOVED_FROM|IN_MOVED_TO と等しく、 IN_CLOSE は IN_CLOSE_WRITE|IN_CLOSE_NOWRITE と等しい。

その他にも以下のビットを inotify_add_watch(2) を呼ぶときの mask に指定できる:

ビット	説明
IN_DONT_FOLLOW	pathname がシンボリックリンクである場合に辿らない。
IN_MASK_ADD	pathname に対する監視マスクが既に存在する場合、
	(マスクの置き換えではなく) イベントを追加 (OR) する。
IN_ONESHOT	1 つのイベントについて pathname を監視し、
	イベントが発生したら監視対象リストから削除する。
IN_ONLYDIR	pathname がディレクトリの場合にのみ監視する。

以下のビットが read(2) で返される mask フィールドに設定される:

ビット	説明
IN_IGNORED	監視対象が (inotify_rm_watch(2) により) 明示的に
	削除された。もしくは (ファイルの削除、またはファイル
	システムのアンマウントにより) 自動的に削除された。
IN_ISDIR	このイベントの対象がディレクトリである。
IN_Q_OVERFLOW	イベントキューが溢れた (このイベントの場合、
	wd は -1 である)。
IN_UNMOUNT	監視対象オブジェクトを含むファイルシステムが
	アンマウントされた。

/proc インターフェース

以下のインターフェースは、inotify で消費される カーネルメモリの総量を制限するのに使用できる:

/proc/sys/fs/inotify/max_queued_events

このファイルの値は、アプリケーションが inotify_init(2) を呼び出すときに使用され、対応する inotify インスタンスについて キューに入れられるイベントの数の上限を設定する。 この制限を超えたイベントは破棄されるが、 IN_Q_OVERFLOW イベントが常に生成される。

/proc/sys/fs/inotify/max_user_instances

1 つの実ユーザ ID に対して生成できる inotify インスタンスの数の上限を指定する。

/proc/sys/fs/inotify/max_user_watches

各 inotify インスタンスに関連づける監視対象の数の制限を指定する。

バージョン

inotify は 2.6.13 の Linux カーネルに組込まれた。 これに必要なライブラリのインターフェースは、 glibc のバージョン 2.4 に追加された (IN_DONT_FOLLOW, IN_MASK_ADD, IN_ONLYDIR だけはバージョン 2.5 で追加された)。

準拠

inotify API は Linux 独自のものである。

注意

inotify ファイルディスクリプタは select(2), poll(2), epoll(7) を使って監視できる。

inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 (wd, mask, cookie, name が等しい場合)、連続するイベントが 1 つのイベントにまとめられる。

inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で イベントが生成されることが保証される。

FIONREAD ioctl(2) は inotify ファイルディスクリプタから何バイト読み込めるかを返す。

inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ以下のサブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。

バグ

2.6.16 以前のカーネルでは IN_ONESHOT mask フラグが働かない。

関連項目

inotify_add_watch(2), inotify_init(2), inotify_rm_watch(2), read(2), stat(2), Documentation/filesystems/inotify.txt.