以下のシステムコールがこの 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 である。
read(2) に渡されたバッファが小さすぎて次のイベントに関する情報を返せない 場合の動作はカーネルのバージョンにより異なる。 2.6.21 より前のカーネルでは、 read(2) は 0 を返す。 2.6.21 以降のカーネルでは、 read(2) はエラー EINVAL で失敗する。
| ビット | 説明 |
| 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 がシンボリックリンクである場合に辿らない。 |
| (Linux 2.6.15 以降) | |
| IN_MASK_ADD | pathname に対する監視マスクが既に存在する場合、 |
| (マスクの置き換えではなく) イベントを追加 (OR) する。 | |
| IN_ONESHOT | 1 つのイベントについて pathname を監視し、 |
| イベントが発生したら監視対象リストから削除する。 | |
| IN_ONLYDIR | pathname がディレクトリの場合にのみ監視する。 |
| (Linux 2.6.15 以降) |
以下のビットが read(2) で返される mask フィールドに設定される:
| ビット | 説明 |
| IN_IGNORED | 監視対象が (inotify_rm_watch(2) により) 明示的に |
| 削除された。もしくは (ファイルの削除、またはファイル | |
| システムのアンマウントにより) 自動的に削除された。 | |
| IN_ISDIR | このイベントの対象がディレクトリである。 |
| IN_Q_OVERFLOW | イベントキューが溢れた (このイベントの場合、 |
| wd は -1 である)。 | |
| IN_UNMOUNT | 監視対象オブジェクトを含むファイルシステムが |
| アンマウントされた。 |
inotify ファイルディスクリプタに対して 連続して生成される出力 inotify イベントが同一の場合 (wd, mask, cookie, name が等しい場合)、連続するイベントが 1 つのイベントにまとめられる。
inotify ファイルディスクリプタの読み込みで返されるイベントは、 順序付けられたキューになる。 従って、たとえば、あるディレクトリの名前を別の名前に変更した場合、 inotify ファイルディスクリプタについての正しい順番で イベントが生成されることが保証される。
FIONREAD ioctl(2) は inotify ファイルディスクリプタから何バイト読み込めるかを返す。
inotify によるディレクトリの監視は再帰的に行われない: あるディレクトリ以下のサブディレクトリを監視する場合、 監視対象を追加で作成しなければならない。