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/
に書かれている。