Scroll to navigation

FANOTIFY_MARK(2) Linux Programmer's Manual FANOTIFY_MARK(2)

名前

fanotify_mark - ファイルシステムオブジェクトへの fanotify マークの追加、削除、変更

書式

#include <sys/fanotify.h>

int fanotify_mark(int fanotify_fd, unsigned int flags,
                  uint64_t mask, int dirfd, const char *pathname);

説明

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

fanotify_mark(2) はファイルシステムオブジェクトに対する fanotify マークの追加、削除、変更を行う。 呼び出し元はマークを付けるファイルシステムオブジェクトに対する読み出し許可を持っていなければならない。

fanotify_fd 引き数は fanotify_init(2) で返されたファイルディスクリプターである。

flags は実行する操作内容を示すビットマスクである。 以下の値のいずれか一つだけを指定しなければならない。

mask のイベントを mark マスク (もしくは ignore マスク) に追加する。 mask は空であってはいけない。 空の場合はエラー EINVAL が発生する。
引き数 mask のイベントを mark マスク (もしくは ignore マスク) から削除する。 mask は空であってはいけない。 空の場合はエラー EINVALが発生する。
fanotify グループから全てのマウント mark か全てのマウント以外の mark を削除する。 flag に FAN_MARK_MOUNT が含まれる場合、 マウントに対する全ての mark がそのグループから削除される。 含まれない場合は、 ディレクトリとファイルに対する全ての mark が削除される。 FAN_MARK_MOUNT 以外のフラグを FAN_MARK_FLUSH と組み合わせて使うことはできない。 mask は無視される。

上記のどの値も指定されなかった場合、 または 2 つ以上の値が指定された場合、 呼び出しはエラー EINVAL で失敗する。

これに加えて、 flags に以下の値を 0 個以上ビット単位の論理和 (OR) で指定できる。

pathname がシンボリックリンクの場合、 リンクが参照するファイルではなく、 リンク自身にマークを付ける (デフォルトでは fanotify_mark() は pathname がシンボリックリンクの場合シンボリックリンクの展開を行う)。
マークが付けられたファイルシステムオブジェクトがディレクトリでない場合、 エラー ENOTDIR が発生する。
pathname で指定されたマウントポイントにマークを付ける。 pathname がマウントポイント自身ではない場合、 pathname を含むマウントポイントがマークされる。 マウントポイントに含まれる全てのディレクトリ、 サブディレクトリ、 その中のファイルが監視される。
mask のイベントの ignore マスクへの追加、もしくは削除を行う。
ignore マスクは変更イベントが発生しても残り続ける。 このフラグがセットされていない場合、 無視するファイルやディレクトリに対して変更イベントが発生した際に ignore マスクはクリアされる。

mask はどのイベントに対して通知を受けるか (もしくはどのイベントを無視するか) を定義する。 以下の値から構成されるビットマスクである。

ファイルやディレクトリへのアクセス (読み出し) があった際にイベントを作成する (「バグ」も参照)。
ファイルが変更された (書き込み) 際にイベントを作成する。
書き込み可能ファイルがクローズされた際にイベントを作成する。
読み出し専用のファイルやディレクトリがクローズされた際にイベントを作成する。
ファイルやディレクトリがオープンされた際にイベントを作成する。
ファイルやディレクトリをオープンするアクセス許可が要求された際にイベントを作成する。 fanotify ファイルディスクリプターが FAN_CLASS_PRE_CONTENT か FAN_CLASS_CONTENT を指定されて作成されている必要がある。
ファイルやディレクトリを読み出すアクセス許可が要求された際にイベントを作成する。 fanotify ファイルディスクリプターが FAN_CLASS_PRE_CONTENT か FAN_CLASS_CONTENT を指定されて作成されている必要がある。
ディレクトリに対するイベントを作成する。 例えば opendir(3)、 readdir(3) (ただし「バグ」も参照)、 closedir(3) が呼び出された場合。 このフラグが指定されなかった場合、 ファイルに対するイベントだけが作成される。
マークされたディレクトリの直下のエントリーに対してイベントを作成する。 このフラグはマウントにマークを付ける際には効果はない。 マークされたディレクトリのサブディレクトリのエントリーに対してはイベントが作成されない点に注意すること。 ディレクトリツリー全体を監視するには、 関連するマウントにマークを付ける必要がある。

以下の組み合わせ値が定義されている。

ファイルがクローズされた (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE)。

マークを付けるファイルシステムオブジェクトは、 ファイルディスクリプター dirfd と pathname で指定されたパス名から決定される。

  • pathname が NULL の場合、 dirfd でマークを付けるファイルシステムオブジェクトが定義される。
  • pathname が NULL で、 dirfd が特別な値 AT_FDCWD の場合、 カレントワーキングディレクトリがマークされる。
  • pathname が絶対パスの場合、 そのパス名によりマークを付けるファイルシステムオブジェクトが定義され、 dirfd は無視される。
  • pathname が相対パスで、 dirfd が AT_FDCWD でない場合、 マークを付けるファイルシステムオブジェクトは dirfd が参照するディレクトリに対する相対パス pathname を解釈して決定される。
  • pathname が相対パスで、 dirfd が AT_FDCWD の場合、 マークを付けるファイルシステムオブジェクトはカレントワーキングディレクトリに対する相対パス pathname を解釈して決定される。

返り値

成功すると fanotify_mark() は 0 を返す。 エラーの場合、 -1 を返し、 errno にエラーの原因を示す値を設定する。

エラー

無効なファイルディスクリプターが fanotify_fd で渡された。
無効な値が flags か mask に指定されたか、 fanotify_fd が fanotify ファイルディスクリプターでなかった。
fanotify ファイルディスクリプターが FAN_CLASS_NOTIF でオープンされたが、 アクセス許可イベント (FAN_OPEN_PERM か FAN_ACCESS_PERM) のフラグがマスクに含まれている。
dirfd と pathname で指定されたファイルシステムオブジェクトが存在しない。 このエラーはマークされていないオブジェクトからマークを削除しようとした場合にも発生する。
必要なメモリーを割り当てできなかった。
マークの数が 8192 の上限を超過し、 fanotify_init(2) で fanotify ファイルディスクリプターが作成された際に FAN_UNLIMITED_MARKS フラグが指定されていなかった。
このカーネルでは fanotify_mark() が実装されていない。 fanotify API が利用できるのは、 カーネルで CONFIG_FANOTIFY が有効になっている場合だけである。
flags に FAN_MARK_ONLYDIR が含まれているが、 dirfd と pathname がディレクトリを指定していない。

バージョン

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

準拠

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

バグ

バージョン 3.16 より前の Linux カーネルでは以下のバグが存在した。

  • flags に FAN_MARK_FLUSH が指定されている場合、 たとえそのオブジェクトが使用されない場合であっても、 dirfd と pathname には有効なファイルシステムオブジェクトを指定しなければならない。
  • readdir(2) は FAN_ACCESS イベントを生成しない。
  • fanotify_mark(2) が FAN_MARK_FLUSH 付きで呼び出された場合、 flags の値が無効かはチェックされない。

関連項目

fanotify_init(2), fanotify(7)

この文書について

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

2014-10-02 Linux