1FANOTIFY_INIT(2) Linux Programmer's Manual FANOTIFY_INIT(2)
3
7 fanotify_init - create and initialize fanotify group
8
10 #include <fcntl.h>
11 #include <sys/fanotify.h>
12 int fanotify_init(unsigned int flags, unsigned int event_f_flags);
14
16 For an overview of the fanotify API, see fanotify(7).
17 fanotify_init() initializes a new fanotify group and returns a file
19 descriptor for the event queue associated with the group.
20 The file descriptor is used in calls to fanotify_mark(2) to specify the
22 files, directories, mounts or filesystems for which fanotify events
23 shall be created. These events are received by reading from the file
24 descriptor. Some events are only informative, indicating that a file
25 has been accessed. Other events can be used to determine whether
26 another application is permitted to access a file or directory. Per‐
27 mission to access filesystem objects is granted by writing to the file
28 descriptor.
29 Multiple programs may be using the fanotify interface at the same time
31 to monitor the same files.
32 In the current implementation, the number of fanotify groups per user
34 is limited to 128. This limit cannot be overridden.
35 Calling fanotify_init() requires the CAP_SYS_ADMIN capability. This
37 constraint might be relaxed in future versions of the API. Therefore,
38 certain additional capability checks have been implemented as indicated
39 below.
40 The flags argument contains a multi-bit field defining the notification
42 class of the listening application and further single bit fields speci‐
43 fying the behavior of the file descriptor.
44 If multiple listeners for permission events exist, the notification
46 class is used to establish the sequence in which the listeners receive
47 the events.
48 Only one of the following notification classes may be specified in
50 flags:
51 FAN_CLASS_PRE_CONTENT
53 This value allows the receipt of events notifying that a file
54 has been accessed and events for permission decisions if a file
55 may be accessed. It is intended for event listeners that need
56 to access files before they contain their final data. This
57 notification class might be used by hierarchical storage man‐
58 agers, for example.
59 FAN_CLASS_CONTENT
61 This value allows the receipt of events notifying that a file
62 has been accessed and events for permission decisions if a file
63 may be accessed. It is intended for event listeners that need
64 to access files when they already contain their final content.
65 This notification class might be used by malware detection pro‐
66 grams, for example.
67 FAN_REPORT_FID (since Linux 5.1)
69 This value allows the receipt of events which contain additional
70 information about the underlying filesystem object correlated to
71 an event. An additional structure encapsulates the information
72 about the object and is included alongside the generic event
73 metadata structure. The file descriptor that is used to repre‐
74 sent the object correlated to an event is instead substituted
75 with a file handle. It is intended for applications that may
76 find the use of a file handle to identify an object more suit‐
77 able than a file descriptor. Additionally, it may be used for
78 applications that are interested in directory entry events, such
79 as FAN_CREATE, FAN_ATTRIB, FAN_MOVE, and FAN_DELETE for example.
80 Note that the use of directory modification events are not sup‐
81 ported when monitoring a mount point. The use of FAN_CLASS_CON‐
82 TENT or FAN_CLASS_PRE_CONTENT is not permitted with this flag
83 and will result in the error EINVAL. See fanotify(7) for addi‐
84 tional information.
85 FAN_CLASS_NOTIF
87 This is the default value. It does not need to be specified.
88 This value only allows the receipt of events notifying that a
89 file has been accessed. Permission decisions before the file is
90 accessed are not possible.
91 Listeners with different notification classes will receive events in
93 the order FAN_CLASS_PRE_CONTENT, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF.
94 The order of notification for listeners in the same notification class
95 is undefined.
96 The following bits can additionally be set in flags:
98 FAN_CLOEXEC
100 Set the close-on-exec flag (FD_CLOEXEC) on the new file descrip‐
101 tor. See the description of the O_CLOEXEC flag in open(2).
102 FAN_NONBLOCK
104 Enable the nonblocking flag (O_NONBLOCK) for the file descrip‐
105 tor. Reading from the file descriptor will not block. Instead,
106 if no data is available, read(2) fails with the error EAGAIN.
107 FAN_UNLIMITED_QUEUE
109 Remove the limit of 16384 events for the event queue. Use of
110 this flag requires the CAP_SYS_ADMIN capability.
111 FAN_UNLIMITED_MARKS
113 Remove the limit of 8192 marks. Use of this flag requires the
114 CAP_SYS_ADMIN capability.
115 FAN_REPORT_TID (since Linux 4.20)
117 Report thread ID (TID) instead of process ID (PID) in the pid
118 field of the struct fanotify_event_metadata supplied to read(2)
119 (see fanotify(7)).
120 The event_f_flags argument defines the file status flags that will be
122 set on the open file descriptions that are created for fanotify events.
123 For details of these flags, see the description of the flags values in
124 open(2). event_f_flags includes a multi-bit field for the access mode.
125 This field can take the following values:
126 O_RDONLY
128 This value allows only read access.
129 O_WRONLY
131 This value allows only write access.
132 O_RDWR This value allows read and write access.
134 Additional bits can be set in event_f_flags. The most useful values
136 are:
137 O_LARGEFILE
139 Enable support for files exceeding 2 GB. Failing to set this
140 flag will result in an EOVERFLOW error when trying to open a
141 large file which is monitored by an fanotify group on a 32-bit
142 system.
143 O_CLOEXEC (since Linux 3.18)
145 Enable the close-on-exec flag for the file descriptor. See the
146 description of the O_CLOEXEC flag in open(2) for reasons why
147 this may be useful.
148 The following are also allowable: O_APPEND, O_DSYNC, O_NOATIME, O_NON‐
150 BLOCK, and O_SYNC. Specifying any other flag in event_f_flags yields
151 the error EINVAL (but see BUGS).
152
154 On success, fanotify_init() returns a new file descriptor. On error,
155 -1 is returned, and errno is set to indicate the error.
156
158 EINVAL An invalid value was passed in flags or event_f_flags.
159 FAN_ALL_INIT_FLAGS (deprecated since Linux kernel version 4.20)
160 defines all allowable bits for flags.
161 EMFILE The number of fanotify groups for this user exceeds 128.
163 EMFILE The per-process limit on the number of open file descriptors has
165 been reached.
166 ENOMEM The allocation of memory for the notification group failed.
168 ENOSYS This kernel does not implement fanotify_init(). The fanotify
170 API is available only if the kernel was configured with CON‐
171 FIG_FANOTIFY.
172 EPERM The operation is not permitted because the caller lacks the
174 CAP_SYS_ADMIN capability.
175
177 fanotify_init() was introduced in version 2.6.36 of the Linux kernel
178 and enabled in version 2.6.37.
179
181 This system call is Linux-specific.
182
184 The following bug was present in Linux kernels before version 3.18:
185 * The O_CLOEXEC is ignored when passed in event_f_flags.
187 The following bug was present in Linux kernels before version 3.14:
189 * The event_f_flags argument is not checked for invalid flags. Flags
191 that are intended only for internal use, such as FMODE_EXEC, can be
192 set, and will consequently be set for the file descriptors returned
193 when reading from the fanotify file descriptor.
194
196 fanotify_mark(2), fanotify(7)
197
199 This page is part of release 5.04 of the Linux man-pages project. A
200 description of the project, information about reporting bugs, and the
201 latest version of this page, can be found at
202 https://www.kernel.org/doc/man-pages/.
203Linux 2019-08-02 FANOTIFY_INIT(2)