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

名称

fanotify_init-创建和初始化fanotify组

语法

＃包括
＃包括

int fanotify_init(unsigned int标志，unsigned int event_f_flags);

说明

有关fanotify API的概述，请参见fanotify(7)。

fanotify_init()初始化一个新的fanotify组，并为与该组关联的事件队列返回文件描述符。

在对fanotify_mark(2)的调用中使用文件描述符来指定要为其创建fanotify事件的文件，目录，安装或文件系统。通过从文件描述符读取来接收这些事件。某些事件仅提供信息，表明已访问文件。其他事件可用于确定是否允许另一个应用程序访问文件或目录。通过写入文件描述符来授予访问文件系统对象的权限。

多个程序可能同时使用fanotify界面来监视相同的文件。

在当前的实现中，每个用户的Fanotify组的数量限制为128个。不能超过此限制。

调用fanotify_init()需要CAP_SYS_ADMIN功能。在将来的API版本中可能会放宽此约束。因此，某些附加功能检查已实现，如下所示。

flags参数包含一个用于定义侦听应用程序的通知类的多位字段，以及用于指定文件描述符行为的其他单个位字段。

如果存在用于权限事件的多个侦听器，则使用通知类来建立侦听器接收事件的顺序。

标志中只能指定以下通知类别之一：

FAN_CLASS_PRE_CONTENT

此值允许接收通知已访问文件的事件，以及是否可以访问文件的权限决定事件。它用于需要在包含最终数据之前访问文件的事件侦听器。例如，分层存储管理器可能会使用此通知类。

FAN_CLASS_CONTENT

此值允许接收通知已访问文件的事件，以及是否可以访问文件的权限决定事件。它适用于需要在文件已经包含其最终内容时访问文件的事件侦听器。例如，恶意软件检测程序可能会使用此通知类。

FAN_CLASS_NOTIF

这是默认值。不需要指定。该值仅允许接收通知已访问文件的事件。无法在访问文件之前做出权限决定。

具有不同通知类别的侦听器将按FAN_CLASS_PRE_CONTENT，FAN_CLASS_CONTENT，FAN_CLASS_NOTIF的顺序接收事件。未定义同一通知类中侦听器的通知顺序。

可以在标志中另外设置以下位：

FAN_CLOEXEC

在新文件描述符上设置执行时关闭标志(FD_CLOEXEC)。请参见open(2)中O_CLOEXEC标志的描述。

FAN_NONBLOCK

启用文件描述符的非阻塞标志(O_NONBLOCK)。从文件描述符读取不会阻塞。相反，如果没有可用数据，则read(2)失败，并显示错误EAGAIN。

FAN_UNLIMITED_QUEUE

删除事件队列的16384个事件的限制。使用此标志需要CAP_SYS_ADMIN功能。

FAN_UNLIMITED_MARKS

删除8192标记的限制。使用此标志需要CAP_SYS_ADMIN功能。

FAN_REPORT_TID(since Linux 4.20)

在提供给read(2)的结构fanotify_event_metadata的pid字段中，报告线程ID(TID)而不是进程ID(PID)(请参阅fanotify(7))。

FAN_REPORT_FID(since Linux 5.1)

该值允许接收事件，该事件包含有关与事件相关的基础文件系统对象的附加信息。附加结构封装了有关对象的信息，并与通用事件元数据结构一起被包含在内。相反，用于表示与事件相关的对象的文件描述符替换为文件句柄。它适用于可能发现使用文件句柄来标识比文件描述符更合适的对象的应用程序。此外，它还可用于对目录条目事件感兴趣的应用程序，例如FAN_CREATE，FAN_ATTRIB，FAN_MOVE和FAN_DELETE。请注意，监视挂载点时不支持使用目录修改事件。该标志不允许使用FAN_CLASS_CONTENT或FAN_CLASS_PRE_CONTENT，这将导致错误EINVAL。有关更多信息，请参见fanotify(7)。

event_f_flags参数定义将在为fanotify事件创建的打开文件描述上设置的文件状态标志。有关这些标志的详细信息，请参见open(2)中的标志值说明。 event_f_flags包含用于访问模式的多位字段。该字段可以采用以下值：

O_RDONLY

该值仅允许读取访问。

O_WRONLY

该值仅允许写访问。

O_RDWR

该值允许读写访问。

可以在event_f_flags中设置其他位。最有用的值是：

O_LARGEFILE

启用对超过2 GB的文件的支持。尝试打开一个由32位系统上的fanotify组监视的大文件时，未能设置此标志将导致EOVERFLOW错误。

O_CLOEXEC(since Linux 3.18)

启用文件描述符的close-on-exec标志。有关为什么可能有用的原因，请参见open(2)中O_CLOEXEC标志的描述。

以下也是允许的：O_APPEND，O_DSYNC，O_NOATIME，O_NONBLOCK和O_SYNC。在event_f_flags中指定任何其他标志会产生错误EINVAL(但请参阅BUGS)。

返回值

成功时，fanotify_init()返回一个新的文件描述符。如果出错，则返回-1，并且将errno设置为指示错误。

错误说明

EINVAL

在标志或event_f_flags中传递了无效的值。 FAN_ALL_INIT_FLAGS(从Linux内核版本4.20开始不推荐使用)定义了标志的所有允许位。

EMFILE

该用户的Fanotify组数超过128。

EMFILE

已达到打开文件描述符数量的每个进程限制。

ENOMEM

通知组的内存分配失败。

ENOSYS

该内核未实现fanotify_init()。仅当内核配置有CONFIG_FANOTIFY时，fanotify API才可用。

EPERM

不允许该操作，因为调用者缺少CAP_SYS_ADMIN功能。

版本

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

遵循规范

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

BUGS

版本3.18之前的Linux内核中存在以下错误：

*

当传入event_f_flags时，将忽略O_CLOEXEC。

版本3.14之前的Linux内核中存在以下错误：

*

不会检查event_f_flags参数是否包含无效标志。可以设置仅供内部使用的标志，例如FMODE_EXEC，因此将为从fanotify文件描述符中读取时返回的文件描述符设置标志。

另外参见

fanotify_mark(2)，fanotify(7)

出版信息

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