名前¶

書式¶

int fanotify_init(unsigned int flags, unsigned int event_f_flags);

説明¶

fanotify_init() は新しい fanotify グループを初期化し、 このグループに関連付けられたイベントキューに対するファイルディスクリプターを返す。

このファイルディスクリプターは、 fanotify_mark(2) の呼び出しで fanotify イベントが作成されるファイル、 ディレクトリ、 マウントを指定するのに使用できる。 fanotify_mark(2) で指定したファイル、 これらのイベントは、 このファイルディスクリプターからの読み出しで受信する。 いくつかのイベントは、 ファイルがアクセスされたことを示す単なる情報である。 他のいくつかのイベントは、 別のアプリケーションがファイルやディレクトリにアクセスする許可を与えるかを判定するのに使用される。 ファイルシステムオブジェクトへのアクセス許可イベントについては、 承認結果をこのファイルディスクリプターに書き込む。

複数のプログラムが同時に fanotify インターフェースを使って同じファイルを同時に監視することができる。

現在の実装では、 ユーザーあたりの fanotify グループ数は 128 に制限されている。 この制限は上書きすることができない。

fanotify_init() を呼び出すには CAP_SYS_ADMIN ケーパビリティーが必要である。 この制約は将来のバージョンの API で緩和される可能性がある。 そのため、 以下に示すケーパビリティーチェックのいくつかが実装されている。

flags 引き数は、 イベントを待つアプリケーションの通知クラスを定義する複数ビットのフィールドである。 これに加えて、 このファイルディスクリプターの動作を示す 1 ビットのフィールドがある。

アクセス許可イベントを監視しているプログラムが複数いる場合、 通知クラスを使って監視するプログラムのイベント受信順序が管理される。

以下の通知クラスのいずれか一つだけを flags に指定できる。

FAN_CLASS_PRE_CONTENT

この値は、 ファイルがアクセスされたことを通知するイベントと、 ファイルへのアクセスするかの許可の判断を求めるイベントを受信することを示す。 これはイベント受信者がファイルが最終的なデータを格納する前にそのファイルにアクセスする必要がある場合に使用される。 この通知クラスは例えば階層型ストレージ管理などで使用される。

FAN_CLASS_CONTENT

この値は、 ファイルがアクセスされたことを通知するイベントと、 ファイルへのアクセスするかの許可の判断を求めるイベントを受信することを示す。 これはイベント受信者がファイルに最終的なデータが格納された際にそのファイルにアクセスする必要がある場合に使用される。 この通知クラスは例えばウイルス検知プログラムなどで使用される。

FAN_CLASS_NOTIF

これはデフォルト値である。 この値を指定する必要はない。 この値は、 ファイルがアクセスされたことを通知するイベントの受信だけを行うことを意味する。 ファイルがアクセスする前にアクセス許可の判定を行うことはできない。

異なる通知クラスの受信者は FAN_CLASS_PRE_CONTENT, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF の順序でイベントを受信する。 同じ通知クラスの受信者での通知順序は不定である。

flags には以下のビットを追加でセットすることができる。

FAN_CLOEXEC

close-on-exec フラグ (FD_CLOEXEC) を新しいファイルディスクリプターにセットする。 open(2) の O_CLOEXEC フラグの説明を参照。

FAN_NONBLOCK

ノンブロッキングフラグ (O_NONBLOCK) をそのファイルディスクリプターで有効にする。 このファイルディスクリプターからの読み出しは停止しない。 その代わり、 読みだし可能なデータが何もない場合、 read(2) はエラー EAGAIN で失敗する。

FAN_UNLIMITED_QUEUE

そのイベントキューの 16384 イベントの上限を削除する。 このフラグを使用するには CAP_SYS_ADMIN ケーパビリティーが必要である。

FAN_UNLIMITED_MARKS

8192 マークの上限を削除する。 このフラグを使用するには CAP_SYS_ADMIN ケーパビリティーが必要である。

event_f_flags 引き数は fanotify イベントが作成されるオープンファイル記述にセットされるファイル状態フラグを定義する。 これらのフラグの詳細については open(2) の flags 値の説明を参照のこと。 event_f_flags にはアクセスモードのビットを複数入れることができる。 このフィールドには以下の値も指定することができる。

O_RDONLY

読み出しアクセスのみを許可する。

O_WRONLY

書き込みアクセスのみを許可する。

O_RDWR

読み出しと書き込みの両方を許可する。

他のビットも event_f_flags もセットすることができる。 役立つであろう値は以下である。

O_LARGEFILE

2 GB を超えるファイルのサポートを有効にする。 このフラグのセットに失敗すると、 32 ビットシステムで fanotify グループが監視するラージファイルをオープンしようとした際に EOVERFLOW エラーとなる。

O_CLOEXEC

このファイルディスクリプターで close-on-exec フラグを有効にする。 このフラグが役立つ理由については open(2) の O_CLOEXEC フラグの説明を参照。

O_APPEND, O_DSYNC, O_NOATIME, O_NONBLOCK, O_SYNC も指定することができる。 event_f_flags にこれ以外のフラグを指定すると、 エラー EINVAL が起こる (ただし、バグを参照)。

返り値¶

エラー¶

EINVAL

flags か event_f_flags に無効な値が渡された。 FAN_ALL_INIT_FLAGS で flags に指定できる全ビットが定義されている。

EMFILE

このユーザーの fanotify グループ数が 128 を超過した。

ENOMEM

通知グループへのメモリー割り当てが失敗した。

ENOSYS

このカーネルは fanotify_init() を実装していない。 fanotify API が利用できるのは、 カーネルが CONFIG_FANOTIFY を有効にして作成されている場合だけである。

EPERM

呼び出し元が CAP_SYS_ADMIN ケーパビリティーを持っていないので、操作が許可されない。

バージョン¶

準拠¶

バグ¶

*

O_CLOEXEC が event_f_flags に指定された場合、 無視される。

バージョン 3.14 より前の Linux カーネルには以下のバグが存在する。

*

event_f_flags 引き数に無効なフラグがないかのチェックが行われない。 FMODE_EXEC などの内部での使用のみが意図されたフラグを指定することができ、 その場合 fanotify ファイルディスクリプターからの読み出し時に返されるファイルディスクリプターにそのフラグがセットされる。

関連項目¶

この文書について¶