Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all bug

名前

       fanotify_init - fanotify グループを作成し、初期化する

書式

       #include <fcntl.h>
       #include <sys/fanotify.h>

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

説明

       fanotify API の概要については fanotify(7) を参照。

       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 が起こる (ただし、バグを参照)。

返り値

       成功すると fanotify_init() は新しいファイルディスクリプターを返す。 エラーの場合、 -1 を返
       し、 errno にエラーを示す値を設定する。

エラー

       EINVAL flagsevent_f_flags に無効な値が渡された。 FAN_ALL_INIT_FLAGSflags に指定で
              きる全ビットが定義されている。

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

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

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

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

バージョン

       fanotify_init() は Linux カーネルのバージョン 2.6.36 で導入され、 バージョン 2.6.37 で有効
       になった。

準拠

       このシステムコールは Linux 独自である。

バグ

       Linux 3.17 時点では、 以下のバグが存在する。

       *  O_CLOEXECevent_f_flags に指定された場合、 無視される。

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

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

関連項目

       fanotify_mark(2), fanotify(7)

この文書について

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