.\" 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 2020\-11\-01 Linux "Linux Programmer's Manual"
.SH 名前
fanotify_mark \- ファイルシステムオブジェクトへの fanotify マークの追加、削除、変更
.SH 書式
.nf
\fB#include <sys/fanotify.h>\fP
.PP
\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() はファイルシステムオブジェクトに対する 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
Remove either all marks for filesystems, all marks for mounts, or all marks
for directories and files from the fanotify group.  If \fIflags\fP contains
\fBFAN_MARK_MOUNT\fP, all marks for mounts are removed from the group.  If
\fIflags\fP contains \fBFAN_MARK_FILESYSTEM\fP, all marks for filesystems are
removed from the group.  Otherwise, all marks for directories and files are
removed.  No flag other than and at most one of the flags \fBFAN_MARK_MOUNT\fP
or \fBFAN_MARK_FILESYSTEM\fP can be used in conjunction with
\fBFAN_MARK_FLUSH\fP.  \fImask\fP is ignored.
.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
Mark the mount point specified by \fIpathname\fP.  If \fIpathname\fP is not itself
a mount point, the mount point containing \fIpathname\fP will be marked.  All
directories, subdirectories, and the contained files of the mount point will
be monitored.  The events which require that filesystem objects are
identified by file handles, such as \fBFAN_CREATE\fP, \fBFAN_ATTRIB\fP,
\fBFAN_MOVE\fP, and \fBFAN_DELETE_SELF\fP, cannot be provided as a \fImask\fP when
\fIflags\fP contains \fBFAN_MARK_MOUNT\fP.  Attempting to do so will result in the
error \fBEINVAL\fP being returned.
.TP 
\fBFAN_MARK_FILESYSTEM\fP (Linux 4.20 以降)
.\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
Mark the filesystem specified by \fIpathname\fP.  The filesystem containing
\fIpathname\fP will be marked.  All the contained files and directories of the
filesystem from any mount point will be monitored.
.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_EXEC\fP (Linux 5.0 以降)
.\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa
Create an event when a file is opened with the intent to be executed.  See
NOTES for additional details.
.TP 
\fBFAN_ATTRIB\fP (Linux 5.1 以降)
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when the metadata for a file or directory has changed.  An
fanotify group that identifies filesystem objects by file handles is
required.
.TP 
\fBFAN_CREATE\fP (Linux 5.1 以降)
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a file or directory has been created in a marked parent
directory.  An fanotify group that identifies filesystem objects by file
handles is required.
.TP 
\fBFAN_DELETE\fP (Linux 5.1 以降)
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a file or directory has been deleted in a marked parent
directory.  An fanotify group that identifies filesystem objects by file
handles is required.
.TP 
\fBFAN_DELETE_SELF\fP (Linux 5.1 以降)
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a marked file or directory itself is deleted.  An
fanotify group that identifies filesystem objects by file handles is
required.
.TP 
\fBFAN_MOVED_FROM\fP (Linux 5.1 以降)
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a file or directory has been moved from a marked parent
directory.  An fanotify group that identifies filesystem objects by file
handles is required.
.TP 
\fBFAN_MOVED_TO\fP (Linux 5.1 以降)
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a file or directory has been moved to a marked parent
directory.  An fanotify group that identifies filesystem objects by file
handles is required.
.TP 
\fBFAN_MOVE_SELF\fP (Linux 5.1 以降)
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a marked file or directory itself has been moved.  An
fanotify group that identifies filesystem objects by file handles is
required.
.TP 
\fBFAN_OPEN_PERM\fP
ファイルやディレクトリをオープンするアクセス許可が要求された際にイベントを作成する。 fanotify ファイルディスクリプターが
\fBFAN_CLASS_PRE_CONTENT\fP か \fBFAN_CLASS_CONTENT\fP を指定されて作成されている必要がある。
.TP 
\fBFAN_OPEN_EXEC_PERM\fP (since Linux 5.0)
.\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9
Create an event when a permission to open a file for execution is
requested.  An fanotify file descriptor created with
\fBFAN_CLASS_PRE_CONTENT\fP or \fBFAN_CLASS_CONTENT\fP is required.  See NOTES for
additional details.
.TP 
\fBFAN_ACCESS_PERM\fP
ファイルやディレクトリを読み出すアクセス許可が要求された際にイベントを作成する。 fanotify ファイルディスクリプターが
\fBFAN_CLASS_PRE_CONTENT\fP か \fBFAN_CLASS_CONTENT\fP を指定されて作成されている必要がある。
.TP 
\fBFAN_ONDIR\fP
Create events for directories\(emfor example, when \fBopendir\fP(3),
\fBreaddir\fP(3)  (but see BUGS), and \fBclosedir\fP(3)  are called.  Without this
flag, events are created only for files.  In the context of directory entry
events, such as \fBFAN_CREATE\fP, \fBFAN_DELETE\fP, \fBFAN_MOVED_FROM\fP, and
\fBFAN_MOVED_TO\fP, specifying the flag \fBFAN_ONDIR\fP is required in order to
create events when subdirectory entries are modified (i.e., \fBmkdir\fP(2)/
\fBrmdir\fP(2)).
.TP 
\fBFAN_EVENT_ON_CHILD\fP
Events for the immediate children of marked directories shall be created.
The flag has no effect when marking mounts and filesystems.  Note that
events are not generated for children of the subdirectories of marked
directories.  More specifically, the directory entry modification events
\fBFAN_CREATE\fP, \fBFAN_DELETE\fP, \fBFAN_MOVED_FROM\fP, and \fBFAN_MOVED_TO\fP are not
generated for any entry modifications performed inside subdirectories of
marked directories.  Note that the events \fBFAN_DELETE_SELF\fP and
\fBFAN_MOVE_SELF\fP are not generated for children of marked directories.  To
monitor complete directory trees it is necessary to mark the relevant mount
or filesystem.
.PP
The following composed values are defined:
.TP 
\fBFAN_CLOSE\fP
ファイルがクローズされた (\fBFAN_CLOSE_WRITE\fP|\fBFAN_CLOSE_NOWRITE\fP)。
.TP 
\fBFAN_MOVE\fP
A file or directory has been moved (\fBFAN_MOVED_FROM\fP|\fBFAN_MOVED_TO\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
The fanotify file descriptor was opened with \fBFAN_CLASS_NOTIF\fP or the
fanotify group identifies filesystem objects by file handles and mask
contains a flag for permission events (\fBFAN_OPEN_PERM\fP or
\fBFAN_ACCESS_PERM\fP).
.TP 
\fBENODEV\fP
The filesystem object indicated by \fIpathname\fP is not associated with a
filesystem that supports \fIfsid\fP (e.g., \fBtmpfs\fP(5)).  This error can be
returned only with an fanotify group that identifies filesystem objects by
file handles.
.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
がディレクトリを指定していない。
.TP 
\fBEOPNOTSUPP\fP
The object indicated by \fIpathname\fP is associated with a filesystem that
does not support the encoding of file handles.  This error can be returned
only with an fanotify group that identifies filesystem objects by file
handles.
.TP 
\fBEXDEV\fP
The filesystem object indicated by \fIpathname\fP resides within a filesystem
subvolume (e.g., \fBbtrfs\fP(5))  which uses a different \fIfsid\fP than its root
superblock.  This error can be returned only with an fanotify group that
identifies filesystem objects by file handles.
.SH バージョン
\fBfanotify_mark\fP() は Linux カーネルのバージョン 2.6.36 で導入され、 バージョン 2.6.37 で有効になった。
.SH 準拠
このシステムコールは Linux 独自である。
.SH 注意
.SS "FAN_OPEN_EXEC と FAN_OPEN_EXEC_PERM"
When using either \fBFAN_OPEN_EXEC\fP or \fBFAN_OPEN_EXEC_PERM\fP within the
\fImask\fP, events of these types will be returned only when the direct
execution of a program occurs.  More specifically, this means that events of
these types will be generated for files that are opened using \fBexecve\fP(2),
\fBexecveat\fP(2), or \fBuselib\fP(2).  Events of these types will not be raised
in the situation where an interpreter is passed (or reads) a file for
interpretation.
.PP
Additionally, if a mark has also been placed on the Linux dynamic linker, a
user should also expect to receive an event for it when an ELF object has
been successfully opened using \fBexecve\fP(2)  or \fBexecveat\fP(2).
.PP
For example, if the following ELF binary were to be invoked and a
\fBFAN_OPEN_EXEC\fP mark has been placed on /:
.PP
.in +4n
.EX
$ /bin/echo foo
.EE
.in
.PP
The listening application in this case would receive \fBFAN_OPEN_EXEC\fP events
for both the ELF binary and interpreter, respectively:
.PP
.in +4n
.EX
/bin/echo
/lib64/ld\-linux\-x86\-64.so.2
.EE
.in
.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() が \fBFAN_MARK_FLUSH\fP 付きで呼び出された場合、 \fIflags\fP
の値が無効かはチェックされない。
.SH 関連項目
\fBfanotify_init\fP(2), \fBfanotify\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
\%https://www.kernel.org/doc/man\-pages/ に書かれている。