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

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

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

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

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

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

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

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

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

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

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

返り値

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

エラー

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

バージョン

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

準拠

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

バグ

バージョン 3.16 より前の Linux カーネルでは以下のバグが存在した。
  • flagsFAN_MARK_FLUSH が指定されている場合、 たとえそのオブジェクトが使用されない場合であっても、 dirfdpathname には有効なファイルシステムオブジェクトを指定しなければならない。
  • 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