FANOTIFY_MARK - Linux手册页

时间:2019-08-20 17:58:40  来源:igfitidea点击:

Linux程序员手册 第2部分
更新日期: 2020-06-09

名称

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()添加,删除或修改文件系统对象上的fanotify标记。调用方必须对要标记的文件系统对象具有读取权限。

fanotify_fd参数是fanotify_init(2)返回的文件描述符。

标志是描述要执行的修改的位掩码。它必须完全包含以下值之一:

FAN_MARK_ADD
掩码中的事件将添加到标记掩码(或忽略掩码)中。 mask必须为非空,否则将发生错误EINVAL。
FAN_MARK_REMOVE
参数掩码中的事件将从标记掩码(或忽略掩码)中删除。 mask必须为非空,否则将发生错误EINVAL。
FAN_MARK_FLUSH
从fanotify组中删除文件系统的所有标记,挂载的所有标记或目录和文件的所有标记。如果标志包含FAN_MARK_MOUNT,则会从组中删除所有安装标记。如果标志包含FAN_MARK_FILESYSTEM,则将从该组中删除文件系统的所有标志。否则,将删除目录和文件的所有标记。除了FAN_MARK_MOUNT或FAN_MARK_FILESYSTEM标志之外,没有其他标志可以与FAN_MARK_FLUSH一起使用。掩码被忽略。

如果未指定上述任何一个值,或者指定多个,则调用将失败,并显示错误EINVAL。

此外,可以将以下零个或多个值与标志进行或运算:

FAN_MARK_DONT_FOLLOW
如果路径名是符号链接,请标记链接本身,而不是它所引用的文件。 (默认情况下,如果fanotify_mark()是符号链接,则会取消引用路径名。)
FAN_MARK_ONLYDIR
如果要标记的文件系统对象不是目录,则将引发错误ENOTDIR。
FAN_MARK_MOUNT
标记由路径名指定的安装点。如果路径名本身不是安装点,则将标记包含路径名的安装点。将监视安装点的所有目录,子目录和包含的文件。当标志包含FAN_MARK_MOUNT时,不能将要求fanotify_fd文件描述符已用标志FAN_REPORT_FID初始化的事件(例如FAN_CREATEFAN_ATTRIB,FAN_MOVE和FAN_DELETE_SELF)作为掩码提供。尝试这样做将导致返回错误EINVAL。
FAN_MARK_FILESYSTEM(since Linux 4.20)
标记由路径名指定的文件系统。包含路径名的文件系统将被标记。任何安装点上文件系统中所有包含的文件和目录都将受到监视。
FAN_MARK_IGNORED_MASK
掩码中的事件应添加到忽略掩码中或从中删除。
FAN_MARK_IGNORED_SURV_MODIFY
忽略掩码应保留修改事件。如果未设置此标志,则在忽略文件或目录发生修改事件时,将清除忽略掩码。

掩码定义应监听(或应忽略)的事件。它是由以下值组成的位掩码:

FAN_ACCESS
访问(读取)文件或目录(但请参阅BUGS)时创建事件。
FAN_MODIFY
修改(写入)文件时创建事件。
FAN_CLOSE_WRITE
关闭可写文件时创建一个事件。
FAN_CLOSE_NOWRITE
关闭只读文件或目录时,创建一个事件。
FAN_OPEN
打开文件或目录时创建事件。
FAN_OPEN_EXEC(since Linux 5.0)
打开要执行的文件时创建事件。有关其他详细信息,请参见注释。
FAN_ATTRIB(since Linux 5.1)
当文件或目录的元数据已更改时,创建一个事件。需要使用FAN_REPORT_FID创建的fanotify文件描述符。
FAN_CREATE(since Linux 5.1)
在标记的父目录中创建文件或目录后,创建事件。需要使用FAN_REPORT_FID创建的fanotify文件描述符。
FAN_DELETE(since Linux 5.1)
在标记的父目录中删除文件或目录后,创建事件。需要使用FAN_REPORT_FID创建的fanotify文件描述符。
FAN_DELETE_SELF(since Linux 5.1)
删除标记的文件或目录本身时,创建一个事件。需要使用FAN_REPORT_FID创建的fanotify文件描述符。
FAN_MOVED_FROM(since Linux 5.1)
从标记的父目录中移出文件或目录后,创建事件。需要使用FAN_REPORT_FID创建的fanotify文件描述符。
FAN_MOVED_TO(since Linux 5.1)
将文件或目录移动到标记的父目录后,创建事件。需要使用FAN_REPORT_FID创建的fanotify文件描述符。
FAN_MOVE_SELF(since Linux 5.1)
当标记的文件或目录本身已移动时,创建一个事件。需要使用FAN_REPORT_FID创建的fanotify文件描述符。
FAN_OPEN_PERM
当请求打开文件或目录的权限时创建事件。需要使用FAN_CLASS_PRE_CONTENT或FAN_CLASS_CONTENT创建的fanotify文件描述符。
FAN_OPEN_EXEC_PERM(since Linux 5.0)
当请求打开文件执行权限时创建事件。需要使用FAN_CLASS_PRE_CONTENT或FAN_CLASS_CONTENT创建的fanotify文件描述符。有关其他详细信息,请参见注释。
FAN_ACCESS_PERM
当请求读取文件或目录的权限时创建事件。需要使用FAN_CLASS_PRE_CONTENT或FAN_CLASS_CONTENT创建的fanotify文件描述符。
FAN_ONDIR
为目录创建事件-例如,当调用opendir(3),readdir(3)(但请参阅BUGS)和closedir(3)时。如果没有此标志,则仅为文件创建事件。在目录条目事件(例如FAN_CREATEFAN_DELETE,FAN_MOVED_FROM和FAN_MOVED_TO)的上下文中,需要指定标志FAN_ONDIR才能在修改子目录条目时创建事件(即mkdir(2)/ rmdir(2))。
FAN_EVENT_ON_CHILD
应创建标记目录的直接子项的事件。当标记挂载和文件系统时,该标志无效。请注意,不会为标记目录的子目录的子级生成事件。更具体地说,对于在标记目录的子目录内执行的任何条目修改,不会生成目录条目修改事件FAN_CREATEFAN_DELETE,FAN_MOVED_FROM和FAN_MOVED_TO。请注意,不会为标记目录的子级生成事件FAN_DELETE_SELF和FAN_MOVE_SELF。要监视完整的目录树,必须标记相关的安装或文件系统。

定义了以下组成值:

FAN_CLOSE
文件已关闭(FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE)。
FAN_MOVE
文件或目录已移动(FAN_MOVED_FROM | FAN_MOVED_TO)。

要标记的文件系统对象由文件描述符dirfd和在路径名中指定的路径名​​确定:

*
如果pathname为NULL,则dirfd定义要标记的文件系统对象。
*
如果路径名为NULL,并且dirfd采用特殊值AT_FDCWD,则将标记当前工作目录。
*
如果路径名是绝对的,它将定义要标记的文件系统对象,而dirfd将被忽略。
*
如果路径名是相对的,并且dirfd不具有值AT_FDCWD,则通过解释相对于dirfd引用的目录的路径名来确定要标记的文件系统对象。
*
如果路径名是相对的,并且dirfd的值为AT_FDCWD,则通过解释相对于当前工作目录的路径名来确定要标记的文件系统对象。

返回值

成功时,fanotify_mark()返回0。错误时,返回-1,并将errno设置为指示错误。

错误说明

EBADF
在fanotify_fd中传递了无效的文件描述符。
EINVAL
在标志或掩码中传递了无效的值,或者fanotify_fd不是幻想文件描述符。
EINVAL
fanotify文件描述符使用FAN_CLASS_NOTIF或FAN_REPORT_FID打开,并且掩码包含权限事件的标记(FAN_OPEN_PERM或FAN_ACCESS_PERM)。
ENODEV
路径名指示的文件系统对象与支持fsid的文件系统不关联(例如tmpfs(5))。仅当已使用FAN_REPORT_FID创建了fanotify_init(2)返回的fanotify文件描述符时,才可以返回此错误。
ENOENT
dirfd和路径名指示的文件系统对象不存在。尝试从未标记的对象中删除标记时,也会发生此错误。
ENOMEM
无法分配必要的内存。
ENOSPC
使用fanotify_init(2)创建fanotify文件描述符时,标记数超过了8192的限制,并且未指定FAN_UNLIMITED_MARKS标志。
ENOSYS
该内核未实现fanotify_mark()。仅当内核配置有CONFIG_FANOTIFY时,fanotify API才可用。
ENOTDIR
标志包含FAN_MARK_ONLYDIR,并且dirfd和路径名未指定目录。
EOPNOTSUPP
路径名指示的对象与不支持文件句柄编码的文件系统关联。仅当已使用FAN_REPORT_FID创建了fanotify_init(2)返回的fanotify文件描述符时,才可以返回此错误。
EXDEV
路径名指示的文件系统对象驻留在文件系统子卷(例如btrfs(5))中,该子卷使用与其根超级块不同的fsid。仅当已使用FAN_REPORT_FID创建了fanotify_init(2)返回的fanotify文件描述符时,才可以返回此错误。

版本

fanotify_mark()在Linux内核的2.6.36版中引入,并在2.6.37版中启用。

遵循规范

此系统调用是特定于Linux的。

备注

FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM

在掩码中使用FAN_OPEN_EXEC或FAN_OPEN_EXEC_PERM时,仅在直接执行程序时才返回这些类型的事件。更具体地说,这意味着将为使用execve(2),execveat(2)或uselib(2)打开的文件生成这些类型的事件。在传递解释器(或读取)文件以进行解释的情况下,不会引发此类事件。

此外,如果在Linux动态链接器上也放置了标记,则当使用execve(2)或execveat(2)成功打开ELF对象时,用户也应该期望收到一个事件。

例如,如果要调用以下ELF二进制文件,并且在/上放置了FAN_OPEN_EXEC标记:

$ /bin/echo foo

在这种情况下,侦听应用程序将分别为ELF二进制文件和解释器接收FAN_OPEN_EXEC事件:

/bin/echo
/lib64/ld-linux-x86-64.so.2

BUGS

在3.16版之前的Linux内核中存在以下错误:

*
如果标志包含FAN_MARK_FLUSH,即使未使用该对象,dirfd和路径名也必须指定一个有效的文件系统对象。
*
readdir(2)不会生成FAN_ACCESS事件。
*
如果使用FAN_MARK_FLUSH调用fanotify_mark(),则不会检查标志中的无效值。

另外参见

fanotify_init(2),fanotify(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本,请访问https://www.kernel.org/doc/man-pages/