名前

       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  ケーパビリ
              ティーが必要である。

       FAN_REPORT_TID (Linux 4.20 以降)
              Report  thread ID (TID) instead of process ID (PID)  in the pid field of the struct
              fanotify_event_metadata supplied to read(2)  (see fanotify(7)).

       FAN_REPORT_FID (Linux 5.1 以降)
              This value allows the receipt of events which contain additional information  about
              the  underlying  filesystem object correlated to an event.  An additional record of
              type FAN_EVENT_INFO_TYPE_FID encapsulates the information about the object  and  is
              included  alongside the generic event metadata structure.  The file descriptor that
              is used to represent the object correlated to an event is instead substituted  with
              a  file  handle.   It  is intended for applications that may find the use of a file
              handle to identify an object more suitable than a file  descriptor.   Additionally,
              it  may  be  used  for applications monitoring a directory or a filesystem that are
              interested in the directory entry modification events FAN_CREATE,  FAN_DELETE,  and
              FAN_MOVE, or in events such as FAN_ATTRIB, FAN_DELETE_SELF, and FAN_MOVE_SELF.  All
              the events above require an fanotify group that identifies  filesystem  objects  by
              file  handles.   Note that for the directory entry modification events the reported
              file handle identifies the modified directory  and  not  the  created/deleted/moved
              child  object.   The  use  of  FAN_CLASS_CONTENT  or  FAN_CLASS_PRE_CONTENT  is not
              permitted with this flag and will result in the error EINVAL.  See fanotify(7)  for
              additional details.

       FAN_REPORT_DIR_FID (Linux 5.9 以降)
              Events  for fanotify groups initialized with this flag will contain (see exceptions
              below) additional information about a directory object correlated to an event.   An
              additional  record  of  type  FAN_EVENT_INFO_TYPE_DFID encapsulates the information
              about the directory object and is included alongside  the  generic  event  metadata
              structure.   For  events  that  occur  on  a  non-directory  object, the additional
              structure includes a file handle that identifies the  parent  directory  filesystem
              object.   Note that there is no guarantee that the directory filesystem object will
              be found at the location described by the file handle information at the  time  the
              event  is received.  When combined with the flag FAN_REPORT_FID, two records may be
              reported with events that occur on a non-directory  object,  one  to  identify  the
              non-directory  object itself and one to identify the parent directory object.  Note
              that in some cases, a filesystem object does not have a parent, for  example,  when
              an   event  occurs  on  an  unlinked  but  open  file.   In  that  case,  with  the
              FAN_REPORT_FID flag, the event will be reported with only one  record  to  identify
              the  non-directory object itself, because there is no directory associated with the
              event.   Without  the  FAN_REPORT_FID  flag,  no  event  will  be  reported.    See
              fanotify(7)  for additional details.

       FAN_REPORT_NAME (Linux 5.9 以降)
              Events  for  fanotify  groups  initialized  with  this flag will contain additional
              information about the name of the directory entry correlated  to  an  event.   This
              flag  must  be provided in conjunction with the flag FAN_REPORT_DIR_FID.  Providing
              this flag value without FAN_REPORT_DIR_FID will result in the error  EINVAL.   This
              flag  may  be  combined with the flag FAN_REPORT_FID.  An additional record of type
              FAN_EVENT_INFO_TYPE_DFID_NAME,  which  encapsulates  the  information   about   the
              directory  entry,  is  included  alongside the generic event metadata structure and
              substitutes the additional information  record  of  type  FAN_EVENT_INFO_TYPE_DFID.
              The additional record includes a file handle that identifies a directory filesystem
              object followed by a name that identifies an entry  in  that  directory.   For  the
              directory  entry  modification  events  FAN_CREATE,  FAN_DELETE,  and FAN_MOVE, the
              reported name is that of the  created/deleted/moved  directory  entry.   For  other
              events  that  occur  on a directory object, the reported file handle is that of the
              directory object itself and the reported name is '.'.  For other events that  occur
              on a non-directory object, the reported file handle is that of the parent directory
              object and the reported name is the name of a directory entry where the object  was
              located  at  the  time  of  the event.  The rationale behind this logic is that the
              reported directory file handle can be passed to  open_by_handle_at(2)   to  get  an
              open  directory  file  descriptor  and that file descriptor along with the reported
              name can be used to call fstatat(2).  The same rule that  applies  to  record  type
              FAN_EVENT_INFO_TYPE_DFID also applies to record type FAN_EVENT_INFO_TYPE_DFID_NAME:
              if a non-directory object has no parent, either the event will not be  reported  or
              it will be reported without the directory entry information.  Note that there is no
              guarantee that the filesystem object will be found at the location described by the
              directory entry information at the time the event is received.  See fanotify(7) for
              additional details.

       FAN_REPORT_DFID_NAME
              This is a synonym for (FAN_REPORT_DIR_FID|FAN_REPORT_NAME).

       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 (Linux 3.18 以降)
              このファイルディスクリプターで  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 An  invalid  value  was  passed  in  flags  or  event_f_flags.   FAN_ALL_INIT_FLAGS
              (deprecated since Linux kernel version 4.20)  defines all allowable bits for flags.

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

       EMFILE The per-process limit on the number of open file descriptors has been reached.

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

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

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

バージョン

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

準拠

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

バグ

       The following bug was present in Linux kernels before version 3.18:

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

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

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

関連項目

       fanotify_mark(2), fanotify(7)

この文書について

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