.\" Copyright (C) 2013,  Heinrich Schuchardt <xypron.glpk@gmx.de>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of
.\" this manual under the conditions for verbatim copying, provided that
.\" the entire resulting derived work is distributed under the terms of
.\" a permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume.
.\" no responsibility for errors or omissions, or for damages resulting.
.\" from the use of the information contained herein.  The author(s) may.
.\" not have taken the same level of care in the production of this.
.\" manual, which is licensed free of charge, as they might when working.
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH FANOTIFY_MARK 2 2014\-10\-02 Linux "Linux Programmer's Manual"
.SH 名前
fanotify_mark \- ファイルシステムオブジェクトへの fanotify マークの追加、削除、変更
.SH 書式
.nf
\fB#include <sys/fanotify.h>\fP
.sp
\fBint fanotify_mark(int \fP\fIfanotify_fd\fP\fB, unsigned int \fP\fIflags\fP\fB,\fP
\fB                  uint64_t \fP\fImask\fP\fB, int \fP\fIdirfd\fP\fB, const char *\fP\fIpathname\fP\fB);\fP
.fi
.SH 説明
fanotify API の概要については \fBfanotify\fP(7) を参照。
.PP
\fBfanotify_mark\fP(2) はファイルシステムオブジェクトに対する fanotify マークの追加、削除、変更を行う。
呼び出し元はマークを付けるファイルシステムオブジェクトに対する読み出し許可を持っていなければならない。
.PP
\fIfanotify_fd\fP 引き数は \fBfanotify_init\fP(2) で返されたファイルディスクリプターである。
.PP
\fIflags\fP は実行する操作内容を示すビットマスクである。 以下の値のいずれか一つだけを指定しなければならない。
.TP 
\fBFAN_MARK_ADD\fP
\fImask\fP のイベントを mark マスク (もしくは ignore マスク) に追加する。 \fImask\fP は空であってはいけない。
空の場合はエラー \fBEINVAL\fP が発生する。
.TP 
\fBFAN_MARK_REMOVE\fP
引き数 \fImask\fP のイベントを mark マスク (もしくは ignore マスク) から削除する。 \fImask\fP は空であってはいけない。
空の場合はエラー \fBEINVAL\fPが発生する。
.TP 
\fBFAN_MARK_FLUSH\fP
fanotify グループから全てのマウント mark か全てのマウント以外の mark を削除する。 \fIflag\fP に
\fBFAN_MARK_MOUNT\fP が含まれる場合、 マウントに対する全ての mark がそのグループから削除される。 含まれない場合は、
ディレクトリとファイルに対する全ての mark が削除される。 \fBFAN_MARK_MOUNT\fP 以外のフラグを \fBFAN_MARK_FLUSH\fP
と組み合わせて使うことはできない。 \fImask\fP は無視される。
.PP
上記のどの値も指定されなかった場合、 または 2 つ以上の値が指定された場合、 呼び出しはエラー \fBEINVAL\fP で失敗する。
.PP
これに加えて、 \fIflags\fP に以下の値を 0 個以上ビット単位の論理和 (OR) で指定できる。
.TP 
\fBFAN_MARK_DONT_FOLLOW\fP
\fIpathname\fP がシンボリックリンクの場合、 リンクが参照するファイルではなく、 リンク自身にマークを付ける (デフォルトでは
\fBfanotify_mark\fP() は \fIpathname\fP がシンボリックリンクの場合シンボリックリンクの展開を行う)。
.TP 
\fBFAN_MARK_ONLYDIR\fP
マークが付けられたファイルシステムオブジェクトがディレクトリでない場合、 エラー \fBENOTDIR\fP が発生する。
.TP 
\fBFAN_MARK_MOUNT\fP
\fIpathname\fP で指定されたマウントポイントにマークを付ける。 \fIpathname\fP がマウントポイント自身ではない場合、
\fIpathname\fP を含むマウントポイントがマークされる。 マウントポイントに含まれる全てのディレクトリ、 サブディレクトリ、
その中のファイルが監視される。
.TP 
\fBFAN_MARK_IGNORED_MASK\fP
\fImask\fP のイベントの ignore マスクへの追加、もしくは削除を行う。
.TP 
\fBFAN_MARK_IGNORED_SURV_MODIFY\fP
ignore マスクは変更イベントが発生しても残り続ける。 このフラグがセットされていない場合、
無視するファイルやディレクトリに対して変更イベントが発生した際に ignore マスクはクリアされる。
.PP
\fImask\fP はどのイベントに対して通知を受けるか (もしくはどのイベントを無視するか) を定義する。  以下の値から構成されるビットマスクである。
.TP 
\fBFAN_ACCESS\fP
ファイルやディレクトリへのアクセス (読み出し) があった際にイベントを作成する (「バグ」も参照)。
.TP 
\fBFAN_MODIFY\fP
ファイルが変更された (書き込み) 際にイベントを作成する。
.TP 
\fBFAN_CLOSE_WRITE\fP
書き込み可能ファイルがクローズされた際にイベントを作成する。
.TP 
\fBFAN_CLOSE_NOWRITE\fP
読み出し専用のファイルやディレクトリがクローズされた際にイベントを作成する。
.TP 
\fBFAN_OPEN\fP
ファイルやディレクトリがオープンされた際にイベントを作成する。
.TP 
\fBFAN_OPEN_PERM\fP
ファイルやディレクトリをオープンするアクセス許可が要求された際にイベントを作成する。 fanotify ファイルディスクリプターが
\fBFAN_CLASS_PRE_CONTENT\fP か \fBFAN_CLASS_CONTENT\fP を指定されて作成されている必要がある。
.TP 
\fBFAN_ACCESS_PERM\fP
ファイルやディレクトリを読み出すアクセス許可が要求された際にイベントを作成する。 fanotify ファイルディスクリプターが
\fBFAN_CLASS_PRE_CONTENT\fP か \fBFAN_CLASS_CONTENT\fP を指定されて作成されている必要がある。
.TP 
\fBFAN_ONDIR\fP
ディレクトリに対するイベントを作成する。 例えば \fBopendir\fP(3)、 \fBreaddir\fP(3) (ただし「バグ」も参照)、
\fBclosedir\fP(3) が呼び出された場合。 このフラグが指定されなかった場合、 ファイルに対するイベントだけが作成される。
.TP 
\fBFAN_EVENT_ON_CHILD\fP
マークされたディレクトリの直下のエントリーに対してイベントを作成する。 このフラグはマウントにマークを付ける際には効果はない。
マークされたディレクトリのサブディレクトリのエントリーに対してはイベントが作成されない点に注意すること。 ディレクトリツリー全体を監視するには、
関連するマウントにマークを付ける必要がある。
.PP
以下の組み合わせ値が定義されている。
.TP 
\fBFAN_CLOSE\fP
ファイルがクローズされた (\fBFAN_CLOSE_WRITE\fP|\fBFAN_CLOSE_NOWRITE\fP)。
.PP
マークを付けるファイルシステムオブジェクトは、 ファイルディスクリプター \fIdirfd\fP と \fIpathname\fP
で指定されたパス名から決定される。
.IP * 3
\fIpathname\fP が NULL の場合、 \fIdirfd\fP でマークを付けるファイルシステムオブジェクトが定義される。
.IP *
\fIpathname\fP が NULL で、 \fIdirfd\fP が特別な値 \fBAT_FDCWD\fP の場合、
カレントワーキングディレクトリがマークされる。
.IP *
\fIpathname\fP が絶対パスの場合、 そのパス名によりマークを付けるファイルシステムオブジェクトが定義され、 \fIdirfd\fP は無視される。
.IP *
\fIpathname\fP が相対パスで、 \fIdirfd\fP が \fBAT_FDCWD\fP でない場合、 マークを付けるファイルシステムオブジェクトは
\fIdirfd\fP が参照するディレクトリに対する相対パス \fIpathname\fP を解釈して決定される。
.IP *
\fIpathname\fP が相対パスで、 \fIdirfd\fP が \fBAT_FDCWD\fP の場合、
マークを付けるファイルシステムオブジェクトはカレントワーキングディレクトリに対する相対パス \fIpathname\fP を解釈して決定される。
.SH 返り値
成功すると \fBfanotify_mark\fP() は 0 を返す。 エラーの場合、 \-1 を返し、 \fIerrno\fP にエラーの原因を示す値を設定する。
.SH エラー
.TP 
\fBEBADF\fP
無効なファイルディスクリプターが \fIfanotify_fd\fP で渡された。
.TP 
\fBEINVAL\fP
無効な値が \fIflags\fP か \fImask\fP に指定されたか、 \fIfanotify_fd\fP が fanotify
ファイルディスクリプターでなかった。
.TP 
\fBEINVAL\fP
fanotify ファイルディスクリプターが \fBFAN_CLASS_NOTIF\fP でオープンされたが、 アクセス許可イベント
(\fBFAN_OPEN_PERM\fP か \fBFAN_ACCESS_PERM\fP) のフラグがマスクに含まれている。
.TP 
\fBENOENT\fP
\fIdirfd\fP と \fIpathname\fP で指定されたファイルシステムオブジェクトが存在しない。
このエラーはマークされていないオブジェクトからマークを削除しようとした場合にも発生する。
.TP 
\fBENOMEM\fP
必要なメモリーを割り当てできなかった。
.TP 
\fBENOSPC\fP
マークの数が 8192 の上限を超過し、 \fBfanotify_init\fP(2) で fanotify ファイルディスクリプターが作成された際に
\fBFAN_UNLIMITED_MARKS\fP フラグが指定されていなかった。
.TP 
\fBENOSYS\fP
このカーネルでは \fBfanotify_mark\fP() が実装されていない。 fanotify API が利用できるのは、 カーネルで
\fBCONFIG_FANOTIFY\fP が有効になっている場合だけである。
.TP 
\fBENOTDIR\fP
\fIflags\fP に \fBFAN_MARK_ONLYDIR\fP が含まれているが、 \fIdirfd\fP と \fIpathname\fP
がディレクトリを指定していない。
.SH バージョン
\fBfanotify_mark\fP() は Linux カーネルのバージョン 2.6.36 で導入され、 バージョン 2.6.37 で有効になった。
.SH 準拠
このシステムコールは Linux 独自である。
.SH バグ
バージョン 3.16 より前の Linux カーネルでは以下のバグが存在した。
.IP * 3
.\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
\fIflags\fP に \fBFAN_MARK_FLUSH\fP が指定されている場合、 たとえそのオブジェクトが使用されない場合であっても、
\fIdirfd\fP と \fIpathname\fP には有効なファイルシステムオブジェクトを指定しなければならない。
.IP *
.\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
\fBreaddir\fP(2) は \fBFAN_ACCESS\fP イベントを生成しない。
.IP *
.\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
\fBfanotify_mark\fP(2) が \fBFAN_MARK_FLUSH\fP 付きで呼び出された場合、 \fIflags\fP
の値が無効かはチェックされない。
.SH 関連項目
\fBfanotify_init\fP(2), \fBfanotify\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。