名前

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

説明

inotify API はファイルシステムイベントを監視するための機構を提供する。 inotify は個々のファイルやディレクトリを監視するのに使える。ディレクトリを監視する場合、inotify はディレクトリ自身とディレクトリ内のファイルのイベントを返す。 以下のシステムコールがこの API と共に使用される: inotify_init(2) (や inotify_init1(2)), inotify_add_watch(2), inotify_rm_watch(2), read(2), close(2). inotify_init(2) は inotify インスタンスを作成し、inotify インスタンスを参照するファイルディスクリプタを返す。もっと新しい inotify_init1(2) も inotify_init(2) と同様だが、いくつかの追加の機能が提供されている。 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) は停止する (シグナルにより割り込まれなかった場合。シグナルによる割り込みがあった場合、呼び出しはエラー EINTR で失敗する。 signal(7) 参照)。 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_MOVED_FROM と IN_MOVED_TO イベントをアプリケーションで関連づけることができる。他のイベント種別の場合には、 cookie は 0 に設定する。

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

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

read(2) に渡されたバッファが小さすぎて次のイベントに関する情報を返せない場合の動作はカーネルのバージョンにより異なる。 2.6.21 より前のカーネルでは、 read(2) は 0 を返す。 2.6.21 以降のカーネルでは、 read(2) はエラー EINVAL で失敗する。バッファサイズとして

sizeof(struct inotify_event) + NAME_MAX + 1

を指定すれば、少なくとも 1 イベントで読み出しを行うには十分である。

バージョン

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) を使って監視できる。イベントがある場合、ファイルディスクリプタは読み込み可能と通知する。 Linux 2.6.25 以降では、シグナル駆動 (signal-driven) I/O の通知が inotify ファイルディスクリプタについて利用可能である。 fcntl(2) に書かれている ( O_ASYNC フラグを設定するための) F_SETFL, F_SETOWN, F_SETSIG の議論を参照のこと。シグナルハンドラに渡される siginfo_t 構造体は、以下のフィールドが設定される ( siginfo_t は sigaction(2) で説明されている)。 si_fd には inotify ファイルディスクリプタ番号が、 si_signo にはシグナル番号が、 si_code には POLL_IN が、 si_band には POLLIN が設定される。 inotify ファイルディスクリプタに対して連続して生成される出力 inotify イベントが同一の場合 ( wd, mask, cookie, name が等しい場合)、前のイベントがまだ読み込まれていなければ、連続するイベントが 1 つのイベントにまとめられる (ただし「バグ」の節も参照のこと)。 inotify ファイルディスクリプタの読み込みで返されるイベントは、順序付けられたキューになる。従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番でイベントが生成されることが保証される。 FIONREAD ioctl(2) は inotify ファイルディスクリプタから何バイト読み込めるかを返す。

バグ

2.6.16 以前のカーネルでは IN_ONESHOT mask フラグが働かない。 カーネル 2.6.25 より前では、連続する同一のイベントを一つにまとめることを意図したコード (古い方のイベントがまだ読み込まれていない場合に、最新の 2 つのイベントを一つにまとめられる可能性がある) が、最新のイベントが「最も古い」読み込まれていないイベントとまとめられるかをチェックするようになっていた。

関連項目

inotify_add_watch(2), inotify_init(2), inotify_init1(2), inotify_rm_watch(2), read(2), stat(2) Linux カーネルソース内の Documentation/filesystems/inotify.txt

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.51 の一部である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。