INOTIFY(7) Linux Programmer’s Manual INOTIFY(7) 名前 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") は、フ ァイルまたはディレクトリのパス名と、そのパス名で参照されるファイルに 対 し て カ ー ネ ル が 監 視 す る 複 数のイベントの集合を指定する。 ino- tify_add_watch(2) は新しい監視アイテムの作成や既存の監視対象の変更が で き る。各監視対象は一意の「監視対象ディスクリプタ」を持つ。これは監視対 象を作成したときに inotify_add_watch(2) から返される整数である。 inotify_rm_watch(2) は inotify の監視対象リストからアイテムを削除する。 inotify インスタンスを指している全てのファイルディスクリプタがクローズ された場合、その下層にあるオブジェクトとそのリソースは、カーネルで再 利 用するために解放される。関連が切られた監視対象は自動的に解放される。 ど の ようなイベントが起こっていたかを知るには、アプリケーションで ino- tify ファイルディスクリプタを 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 はイベント発生の監視対象を指定する。これは、前もって行わ れ た ino- tify_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 である。 read(2) に渡されたバッファが小さすぎて次のイベントに関する情報を返せな い場合の動作はカーネルのバージョンにより異なる。 2.6.21 より前のカー ネ ルでは、 read(2) は 0 を返す。 2.6.21 以降のカーネルでは、 read(2) はエ ラー EINVAL で失敗する。 inotify イベント inotify_add_watch(2) の mask 引き数と、inotify ファイル構造体を read(2) し た と き に返される inotify_event 構造体の mask フィールドは、ともに inotify イベントを識別するためのビットマスクである。以下のビットが ino- tify_add_watch(2) を呼ぶときの mask に指定可能であり、 read(2) で返され る mask フィールドで返される: IN_ACCESS ファイルがアクセス (read) された。(*) IN_ATTRIB メタデータが変更された。メタデータとは、例えば 、 許可 (permission)、タイムスタンプ、拡張属性、リン クカウント (Linux 2.6.25 以降)、UID、GID などであ る。(*) 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 がシンボリックリンクである場合に辿らない 。 (Linux 2.6.15 以降) IN_MASK_ADD pathname に対する監視マスクが既に存在する場合、 ( マ スクの置き換えではなく) イベントを追加 (OR) す る。 IN_ONESHOT 1 つのイベントについて pathname を監視し、イベ ン トが発生したら監視対象リストから削除する。 IN_ONLYDIR (Linux 2.6.15 以降) 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 作成可能な監視対象の数の実 UID 単位の上限を指定する。 バージョン 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 の通知 が ino- tify ファイルディスクリプタについて利用可能である。 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 ファイルディスクリプタから何バイト読み込め るかを返す。 inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ 以下のサブディレクトリを監視する場合、監視対象を追加で作成しなければ な らない。 バグ 2.6.16 以前のカーネルでは IN_ONESHOT mask フラグが働かない。 カ ーネル 2.6.25 より前では、連続する同一のイベントを一つにまとめること を意図したコード (古い方のイベントがまだ読み込まれていない場合に、最 新 の 2 つのイベントを一つにまとめられる可能性がある) が、最新のイベントが 「最も古い」読み込まれていないイベントとまとめられるかをチェックする よ うになっていた。 関連項目 inotify_add_watch(2), inotify_init(2), inotify_init1(2), ino- tify_rm_watch(2), read(2), stat(2), Documentation/filesystems/ino- tify.txt. Linux 2008-11-18 INOTIFY(7)
INOTIFY(7) Linux Programmer’s Manual INOTIFY(7) NAME inotify - monitoring file system events DESCRIPTION The inotify API provides a mechanism for monitoring file system events. Inotify can be used to monitor individual files, or to monitor directo- ries. When a directory is monitored, inotify will return events for the directory itself, and for files inside the directory. The following system calls are used with this API: inotify_init(2) (or inotify_init1(2)), inotify_add_watch(2), inotify_rm_watch(2), read(2), and close(2). inotify_init(2) creates an inotify instance and returns a file descrip- tor referring to the inotify instance. The more recent ino- tify_init1(2) is like inotify_init(2), but provides some extra func- tionality. inotify_add_watch(2) manipulates the "watch list" associated with an inotify instance. Each item ("watch") in the watch list specifies the pathname of a file or directory, along with some set of events that the kernel should monitor for the file referred to by that pathname. ino- tify_add_watch(2) either creates a new watch item, or modifies an existing watch. Each watch has a unique "watch descriptor", an integer returned by inotify_add_watch(2) when the watch is created. inotify_rm_watch(2) removes an item from an inotify watch list. When all file descriptors referring to an inotify instance have been closed, the underlying object and its resources are freed for re-use by the kernel; all associated watches are automatically freed. To determine what events have occurred, an application read(2)s from the inotify file descriptor. If no events have so far occurred, then, assuming a blocking file descriptor, read(2) will block until at least one event occurs (unless interrupted by a signal, in which case the call fails with the error EINTR; see signal(7)). Each successful read(2) returns a buffer containing one or more of the following structures: struct inotify_event { int wd; /* Watch descriptor */ uint32_t mask; /* Mask of events */ uint32_t cookie; /* Unique cookie associating related events (for rename(2)) */ uint32_t len; /* Size of name field */ char name[]; /* Optional null-terminated name */ }; wd identifies the watch for which this event occurs. It is one of the watch descriptors returned by a previous call to inotify_add_watch(2). mask contains bits that describe the event that occurred (see below). cookie is a unique integer that connects related events. Currently this is only used for rename events, and allows the resulting pair of IN_MOVE_FROM and IN_MOVE_TO events to be connected by the application. The name field is only present when an event is returned for a file inside a watched directory; it identifies the file pathname relative to the watched directory. This pathname is null-terminated, and may include further null bytes to align subsequent reads to a suitable address boundary. The len field counts all of the bytes in name, including the null bytes; the length of each inotify_event structure is thus sizeof(ino- tify_event)+len. The behavior when the buffer given to read(2) is too small to return information about the next event depends on the kernel version: in ker- nels before 2.6.21, read(2) returns 0; since kernel 2.6.21, read(2) fails with the error EINVAL. inotify events The inotify_add_watch(2) mask argument and the mask field of the ino- tify_event structure returned when read(2)ing an inotify file descrip- tor are both bit masks identifying inotify events. The following bits can be specified in mask when calling inotify_add_watch(2) and may be returned in the mask field returned by read(2): IN_ACCESS File was accessed (read) (*). IN_ATTRIB Metadata changed, e.g., permissions, timestamps, extended attributes, link count (since Linux 2.6.25), UID, GID, etc. (*). IN_CLOSE_WRITE File opened for writing was closed (*). IN_CLOSE_NOWRITE File not opened for writing was closed (*). IN_CREATE File/directory created in watched directory (*). IN_DELETE File/directory deleted from watched directory (*). IN_DELETE_SELF Watched file/directory was itself deleted. IN_MODIFY File was modified (*). IN_MOVE_SELF Watched file/directory was itself moved. IN_MOVED_FROM File moved out of watched directory (*). IN_MOVED_TO File moved into watched directory (*). IN_OPEN File was opened (*). When monitoring a directory, the events marked with an asterisk (*) above can occur for files in the directory, in which case the name field in the returned inotify_event structure identifies the name of the file within the directory. The IN_ALL_EVENTS macro is defined as a bit mask of all of the above events. This macro can be used as the mask argument when calling ino- tify_add_watch(2). Two additional convenience macros are IN_MOVE, which equates to IN_MOVED_FROM|IN_MOVED_TO, and IN_CLOSE which equates to IN_CLOSE_WRITE|IN_CLOSE_NOWRITE. The following further bits can be specified in mask when calling ino- tify_add_watch(2): IN_DONT_FOLLOW (since Linux 2.6.15) Don’t dereference pathname if it is a symbolic link. IN_MASK_ADD Add (OR) events to watch mask for this pathname if it already exists (instead of replacing mask). IN_ONESHOT Monitor pathname for one event, then remove from watch list. IN_ONLYDIR (since Linux 2.6.15) Only watch pathname if it is a directory. The following bits may be set in the mask field returned by read(2): IN_IGNORED Watch was removed explicitly (ino- tify_rm_watch(2)) or automatically (file was deleted, or file system was unmounted). IN_ISDIR Subject of this event is a directory. IN_Q_OVERFLOW Event queue overflowed (wd is -1 for this event). IN_UNMOUNT File system containing watched object was unmounted. /proc interfaces The following interfaces can be used to limit the amount of kernel mem- ory consumed by inotify: /proc/sys/fs/inotify/max_queued_events The value in this file is used when an application calls ino- tify_init(2) to set an upper limit on the number of events that can be queued to the corresponding inotify instance. Events in excess of this limit are dropped, but an IN_Q_OVERFLOW event is always generated. /proc/sys/fs/inotify/max_user_instances This specifies an upper limit on the number of inotify instances that can be created per real user ID. /proc/sys/fs/inotify/max_user_watches This specifies an upper limit on the number of watches that can be created per real user ID. VERSIONS Inotify was merged into the 2.6.13 Linux kernel. The required library interfaces were added to glibc in version 2.4. (IN_DONT_FOLLOW, IN_MASK_ADD, and IN_ONLYDIR were only added in version 2.5.) CONFORMING TO The inotify API is Linux-specific. NOTES Inotify file descriptors can be monitored using select(2), poll(2), and epoll(7). When an event is available, the file descriptor indicates as readable. Since Linux 2.6.25, signal-driven I/O notification is available for inotify file descriptors; see the discussion of F_SETFL (for setting the O_ASYNC flag), F_SETOWN, and F_SETSIG in fcntl(2). The siginfo_t structure (described in sigaction(2)) that is passed to the signal han- dler has the following fields set: si_fd is set to the inotify file descriptor number; si_signo is set to the signal number; si_code is set to POLL_IN; and POLLIN is set in si_band. If successive output inotify events produced on the inotify file descriptor are identical (same wd, mask, cookie, and name) then they are coalesced into a single event if the older event has not yet been read (but see BUGS). The events returned by reading from an inotify file descriptor form an ordered queue. Thus, for example, it is guaranteed that when renaming from one directory to another, events will be produced in the correct order on the inotify file descriptor. The FIONREAD ioctl(2) returns the number of bytes available to read from an inotify file descriptor. Inotify monitoring of directories is not recursive: to monitor subdi- rectories under a directory, additional watches must be created. BUGS In kernels before 2.6.16, the IN_ONESHOT mask flag does not work. Before kernel 2.6.25, the kernel code that was intended to coalesce successive identical events (i.e., the two most recent events could potentially be coalesced if the older had not yet been read) instead checked if the most recent event could be coalesced with the oldest unread event. SEE ALSO inotify_add_watch(2), inotify_init(2), inotify_init1(2), ino- tify_rm_watch(2), read(2), stat(2), Documentation/filesystems/ino- tify.txt. COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. Linux 2008-11-18 INOTIFY(7)
Copyright(C) linux-cmd.com All Rights Reserved. Author Takayuki Yukawa