kazmax - Linux で自宅サーバー

inotify - 約束事その他の説明 - Linux コマンド集 一覧表

  1. 名前
  2. 説明
  3. 注意
  4. バージョン
  5. 準拠
  6. 関連項目

名前

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

説明

inotify API はファイルシステムイベントを監視するための機構を提供する。 inotify は個々のファイルやディレクトリを監視するのに使える。 ディレクトリを監視する場合、inotify はディレクトリ自身と ディレクトリ内のファイルのイベントを返す。
以下のシステムコールがこの API と共に使用される。 inotify_init (), inotify_add_watch (), read (), inotify_rm_watch (), close ().
inotify_init (2)は inotify インスタンスを作成し、inotify オブジェクトを参照する ファイルディスクリプタを返す。
inotify_add_watch (2)は inotify に関連づけられた「監視対象 (watch) リスト」を操作する。 監視対象リストの各アイテム ("watch") は、 ファイルまたはディレクトリのパス名と、 そのパス名で参照されるファイルに対して カーネルが監視する複数のイベントの集合を指定する。 inotify_add_watch ()は新しい監視アイテムの作成や既存の監視対象の変更ができる。 各監視対象は一意の「監視対象ディスクリプタ」を持つ。 これは監視対象を作成したときに inotify_add_watch ()から返される整数である。
inotify_rm_watch (2)は inotify の監視対象リストからアイテムを削除する。
inotify オブジェクトを指している 全てのファイルディスクリプタがクローズされた場合、 その下層にあるオブジェクトとそのリソースは、 カーネルで再利用するために解放される。 関連が切られた監視対象は自動的に解放される。
どのようなイベントが起こっていたかを知るには、 アプリケーションで inotify ファイルディスクリプタを   read (2) すればよい。 これまでに何もイベントが起こっていない場合、 停止 (blocking) モードのファイルディスクリプタであれば、 少なくとも 1 つのイベントが起こるまで read ()は停止する。
read ()が成功すると、以下の構造体を 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 ()呼び出しで返された監視対象ディスクリプタのうちの 1 つである。
mask には発生したイベント (下記参照) を記述するためのビットが含まれる。
cookie は関連するイベントを関連づけるための一意な整数である。 現在のところ、この値は rename イベントに対してのみ使われており、 結果のペアである IN_MOVE_FROMIN_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 ()を呼ぶときの mask に指定可能であり、 read ()で返される 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 ()を呼び出すときの mask 引き数として使える。
さらに 2 つの便利なマクロがある。 IN_MOVE は IN_MOVED_FROM|IN_MOVED_TO と等しく、 IN_CLOSE は IN_CLOSE_WRITE|IN_CLOSE_NOWRITE と等しい。

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

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

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

IN_IGNORED 監視対象が (inotify_rm_watch() により) 明示的に削除された。もしくは (ファイルの削除、またはファイルシステムのアンマウントにより) 自動的に削除された。
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 ファイルディスクリプタは   select (2),   poll (2),   epoll (4) を使って監視できる。
inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 ( wd , mask , cookie , name が等しい場合)、連続するイベントが 1 つのイベントにまとめられる。
inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で イベントが生成されることが保証される。
FIONREAD ioctl ()は inotify ファイルディスクリプタから何バイト読み込めるかを返す。
inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ以下のサブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。

バージョン

inotify は 2.6.13 の Linux カーネルに組込まれた。 これに必要なライブラリのインターフェースは、 glibc のバージョン 2.4 に追加された。

準拠

inotify API は Linux 独自のものである。 他のシステムでも同様な機構を提供しているものがある。 たとえば、FreeBSD には kqueue があり、Solaris には /dev/poll がある。

関連項目

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