1fanotify_init(2) System Calls Manual fanotify_init(2)
2
6 fanotify_init - create and initialize fanotify group
7
9 Standard C library (libc, -lc)
10
12 #include <fcntl.h> /* Definition of O_* constants */
13 #include <sys/fanotify.h>
14 int fanotify_init(unsigned int flags, unsigned int event_f_flags);
16
18 For an overview of the fanotify API, see fanotify(7).
19 fanotify_init() initializes a new fanotify group and returns a file de‐
21 scriptor for the event queue associated with the group.
22 The file descriptor is used in calls to fanotify_mark(2) to specify the
24 files, directories, mounts, or filesystems for which fanotify events
25 shall be created. These events are received by reading from the file
26 descriptor. Some events are only informative, indicating that a file
27 has been accessed. Other events can be used to determine whether an‐
28 other application is permitted to access a file or directory. Permis‐
29 sion to access filesystem objects is granted by writing to the file de‐
30 scriptor.
31 Multiple programs may be using the fanotify interface at the same time
33 to monitor the same files.
34 The number of fanotify groups per user is limited. See fanotify(7) for
36 details about this limit.
37 The flags argument contains a multi-bit field defining the notification
39 class of the listening application and further single bit fields speci‐
40 fying the behavior of the file descriptor.
41 If multiple listeners for permission events exist, the notification
43 class is used to establish the sequence in which the listeners receive
44 the events.
45 Only one of the following notification classes may be specified in
47 flags:
48 FAN_CLASS_PRE_CONTENT
50 This value allows the receipt of events notifying that a file
51 has been accessed and events for permission decisions if a file
52 may be accessed. It is intended for event listeners that need
53 to access files before they contain their final data. This no‐
54 tification class might be used by hierarchical storage managers,
55 for example. Use of this flag requires the CAP_SYS_ADMIN capa‐
56 bility.
57 FAN_CLASS_CONTENT
59 This value allows the receipt of events notifying that a file
60 has been accessed and events for permission decisions if a file
61 may be accessed. It is intended for event listeners that need
62 to access files when they already contain their final content.
63 This notification class might be used by malware detection pro‐
64 grams, for example. Use of this flag requires the CAP_SYS_ADMIN
65 capability.
66 FAN_CLASS_NOTIF
68 This is the default value. It does not need to be specified.
69 This value only allows the receipt of events notifying that a
70 file has been accessed. Permission decisions before the file is
71 accessed are not possible.
72 Listeners with different notification classes will receive events in
74 the order FAN_CLASS_PRE_CONTENT, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF.
75 The order of notification for listeners in the same notification class
76 is undefined.
77 The following bits can additionally be set in flags:
79 FAN_CLOEXEC
81 Set the close-on-exec flag (FD_CLOEXEC) on the new file descrip‐
82 tor. See the description of the O_CLOEXEC flag in open(2).
83 FAN_NONBLOCK
85 Enable the nonblocking flag (O_NONBLOCK) for the file descrip‐
86 tor. Reading from the file descriptor will not block. Instead,
87 if no data is available, read(2) fails with the error EAGAIN.
88 FAN_UNLIMITED_QUEUE
90 Remove the limit on the number of events in the event queue.
91 See fanotify(7) for details about this limit. Use of this flag
92 requires the CAP_SYS_ADMIN capability.
93 FAN_UNLIMITED_MARKS
95 Remove the limit on the number of fanotify marks per user. See
96 fanotify(7) for details about this limit. Use of this flag re‐
97 quires the CAP_SYS_ADMIN capability.
98 FAN_REPORT_TID (since Linux 4.20)
100 Report thread ID (TID) instead of process ID (PID) in the pid
101 field of the struct fanotify_event_metadata supplied to read(2)
102 (see fanotify(7)). Use of this flag requires the CAP_SYS_ADMIN
103 capability.
104 FAN_ENABLE_AUDIT (since Linux 4.15)
106 Enable generation of audit log records about access mediation
107 performed by permission events. The permission event response
108 has to be marked with the FAN_AUDIT flag for an audit log record
109 to be generated. Use of this flag requires the CAP_AUDIT_WRITE
110 capability.
111 FAN_REPORT_FID (since Linux 5.1)
113 This value allows the receipt of events which contain additional
114 information about the underlying filesystem object correlated to
115 an event. An additional record of type FAN_EVENT_INFO_TYPE_FID
116 encapsulates the information about the object and is included
117 alongside the generic event metadata structure. The file de‐
118 scriptor that is used to represent the object correlated to an
119 event is instead substituted with a file handle. It is intended
120 for applications that may find the use of a file handle to iden‐
121 tify an object more suitable than a file descriptor. Addition‐
122 ally, it may be used for applications monitoring a directory or
123 a filesystem that are interested in the directory entry modifi‐
124 cation events FAN_CREATE, FAN_DELETE, FAN_MOVE, and FAN_RENAME,
125 or in events such as FAN_ATTRIB, FAN_DELETE_SELF, and
126 FAN_MOVE_SELF. All the events above require an fanotify group
127 that identifies filesystem objects by file handles. Note that
128 without the flag FAN_REPORT_TARGET_FID, for the directory entry
129 modification events, there is an information record that identi‐
130 fies the modified directory and not the created/deleted/moved
131 child object. The use of FAN_CLASS_CONTENT or
132 FAN_CLASS_PRE_CONTENT is not permitted with this flag and will
133 result in the error EINVAL. See fanotify(7) for additional de‐
134 tails.
135 FAN_REPORT_DIR_FID (since Linux 5.9)
137 Events for fanotify groups initialized with this flag will con‐
138 tain (see exceptions below) additional information about a di‐
139 rectory object correlated to an event. An additional record of
140 type FAN_EVENT_INFO_TYPE_DFID encapsulates the information about
141 the directory object and is included alongside the generic event
142 metadata structure. For events that occur on a non-directory
143 object, the additional structure includes a file handle that
144 identifies the parent directory filesystem object. Note that
145 there is no guarantee that the directory filesystem object will
146 be found at the location described by the file handle informa‐
147 tion at the time the event is received. When combined with the
148 flag FAN_REPORT_FID, two records may be reported with events
149 that occur on a non-directory object, one to identify the non-
150 directory object itself and one to identify the parent directory
151 object. Note that in some cases, a filesystem object does not
152 have a parent, for example, when an event occurs on an unlinked
153 but open file. In that case, with the FAN_REPORT_FID flag, the
154 event will be reported with only one record to identify the non-
155 directory object itself, because there is no directory associ‐
156 ated with the event. Without the FAN_REPORT_FID flag, no event
157 will be reported. See fanotify(7) for additional details.
158 FAN_REPORT_NAME (since Linux 5.9)
160 Events for fanotify groups initialized with this flag will con‐
161 tain additional information about the name of the directory en‐
162 try correlated to an event. This flag must be provided in con‐
163 junction with the flag FAN_REPORT_DIR_FID. Providing this flag
164 value without FAN_REPORT_DIR_FID will result in the error EIN‐
165 VAL. This flag may be combined with the flag FAN_REPORT_FID.
166 An additional record of type FAN_EVENT_INFO_TYPE_DFID_NAME,
167 which encapsulates the information about the directory entry, is
168 included alongside the generic event metadata structure and sub‐
169 stitutes the additional information record of type
170 FAN_EVENT_INFO_TYPE_DFID. The additional record includes a file
171 handle that identifies a directory filesystem object followed by
172 a name that identifies an entry in that directory. For the di‐
173 rectory entry modification events FAN_CREATE, FAN_DELETE, and
174 FAN_MOVE, the reported name is that of the created/deleted/moved
175 directory entry. The event FAN_RENAME may contain two informa‐
176 tion records. One of type FAN_EVENT_INFO_TYPE_OLD_DFID_NAME
177 identifying the old directory entry, and another of type
178 FAN_EVENT_INFO_TYPE_NEW_DFID_NAME identifying the new directory
179 entry. For other events that occur on a directory object, the
180 reported file handle is that of the directory object itself and
181 the reported name is '.'. For other events that occur on a non-
182 directory object, the reported file handle is that of the parent
183 directory object and the reported name is the name of a direc‐
184 tory entry where the object was located at the time of the
185 event. The rationale behind this logic is that the reported di‐
186 rectory file handle can be passed to open_by_handle_at(2) to get
187 an open directory file descriptor and that file descriptor along
188 with the reported name can be used to call fstatat(2). The same
189 rule that applies to record type FAN_EVENT_INFO_TYPE_DFID also
190 applies to record type FAN_EVENT_INFO_TYPE_DFID_NAME: if a non-
191 directory object has no parent, either the event will not be re‐
192 ported or it will be reported without the directory entry infor‐
193 mation. Note that there is no guarantee that the filesystem ob‐
194 ject will be found at the location described by the directory
195 entry information at the time the event is received. See fan‐
196 otify(7) for additional details.
197 FAN_REPORT_DFID_NAME
199 This is a synonym for (FAN_REPORT_DIR_FID|FAN_REPORT_NAME).
200 FAN_REPORT_TARGET_FID (since Linux 5.17)
202 Events for fanotify groups initialized with this flag will con‐
203 tain additional information about the child correlated with di‐
204 rectory entry modification events. This flag must be provided
205 in conjunction with the flags FAN_REPORT_FID, FAN_REPORT_DIR_FID
206 and FAN_REPORT_NAME. or else the error EINVAL will be returned.
207 For the directory entry modification events FAN_CREATE,
208 FAN_DELETE, FAN_MOVE, and FAN_RENAME, an additional record of
209 type FAN_EVENT_INFO_TYPE_FID, is reported in addition to the in‐
210 formation records of type FAN_EVENT_INFO_TYPE_DFID,
211 FAN_EVENT_INFO_TYPE_DFID_NAME,
212 FAN_EVENT_INFO_TYPE_OLD_DFID_NAME, and
213 FAN_EVENT_INFO_TYPE_NEW_DFID_NAME. The additional record in‐
214 cludes a file handle that identifies the filesystem child object
215 that the directory entry is referring to.
216 FAN_REPORT_DFID_NAME_TARGET
218 This is a synonym for (FAN_REPORT_DFID_NAME|FAN_RE‐
219 PORT_FID|FAN_REPORT_TARGET_FID).
220 FAN_REPORT_PIDFD (since Linux 5.15)
222 Events for fanotify groups initialized with this flag will con‐
223 tain an additional information record alongside the generic fan‐
224 otify_event_metadata structure. This information record will be
225 of type FAN_EVENT_INFO_TYPE_PIDFD and will contain a pidfd for
226 the process that was responsible for generating an event. A
227 pidfd returned in this information record object is no different
228 to the pidfd that is returned when calling pidfd_open(2). Usage
229 of this information record are for applications that may be in‐
230 terested in reliably determining whether the process responsible
231 for generating an event has been recycled or terminated. The
232 use of the FAN_REPORT_TID flag along with FAN_REPORT_PIDFD is
233 currently not supported and attempting to do so will result in
234 the error EINVAL being returned. This limitation is currently
235 imposed by the pidfd API as it currently only supports the cre‐
236 ation of pidfds for thread-group leaders. Creating pidfds for
237 non-thread-group leaders may be supported at some point in the
238 future, so this restriction may eventually be lifted. For more
239 details on information records, see fanotify(7).
240 The event_f_flags argument defines the file status flags that will be
242 set on the open file descriptions that are created for fanotify events.
243 For details of these flags, see the description of the flags values in
244 open(2). event_f_flags includes a multi-bit field for the access mode.
245 This field can take the following values:
246 O_RDONLY
248 This value allows only read access.
249 O_WRONLY
251 This value allows only write access.
252 O_RDWR This value allows read and write access.
254 Additional bits can be set in event_f_flags. The most useful values
256 are:
257 O_LARGEFILE
259 Enable support for files exceeding 2 GB. Failing to set this
260 flag will result in an EOVERFLOW error when trying to open a
261 large file which is monitored by an fanotify group on a 32-bit
262 system.
263 O_CLOEXEC (since Linux 3.18)
265 Enable the close-on-exec flag for the file descriptor. See the
266 description of the O_CLOEXEC flag in open(2) for reasons why
267 this may be useful.
268 The following are also allowable: O_APPEND, O_DSYNC, O_NOATIME, O_NON‐
270 BLOCK, and O_SYNC. Specifying any other flag in event_f_flags yields
271 the error EINVAL (but see BUGS).
272
274 On success, fanotify_init() returns a new file descriptor. On error,
275 -1 is returned, and errno is set to indicate the error.
276
278 EINVAL An invalid value was passed in flags or event_f_flags.
279 FAN_ALL_INIT_FLAGS (deprecated since Linux 4.20) defines all al‐
280 lowable bits for flags.
281 EMFILE The number of fanotify groups for this user exceeds the limit.
283 See fanotify(7) for details about this limit.
284 EMFILE The per-process limit on the number of open file descriptors has
286 been reached.
287 ENOMEM The allocation of memory for the notification group failed.
289 ENOSYS This kernel does not implement fanotify_init(). The fanotify
291 API is available only if the kernel was configured with CON‐
292 FIG_FANOTIFY.
293 EPERM The operation is not permitted because the caller lacks a re‐
295 quired capability.
296
298 Prior to Linux 5.13, calling fanotify_init() required the CAP_SYS_ADMIN
299 capability. Since Linux 5.13, users may call fanotify_init() without
300 the CAP_SYS_ADMIN capability to create and initialize an fanotify group
301 with limited functionality.
302 The limitations imposed on an event listener created by a user without
304 the
305 CAP_SYS_ADMIN capability are as follows:
306 • The user cannot request for an unlimited event queue by using
308 FAN_UNLIMITED_QUEUE.
309 • The user cannot request for an unlimited number of marks by
311 using FAN_UNLIMITED_MARKS.
312 • The user cannot request to use either notification classes
314 FAN_CLASS_CONTENT or FAN_CLASS_PRE_CONTENT. This means that
315 user cannot request permission events.
316 • The user is required to create a group that identifies
318 filesystem objects by file handles, for example, by providing
319 the FAN_REPORT_FID flag.
320 • The user is limited to only mark inodes. The ability to mark
322 a mount or filesystem via fanotify_mark() through the use of
323 FAN_MARK_MOUNT or FAN_MARK_FILESYSTEM is not permitted.
324 • The event object in the event queue is limited in terms of
326 the information that is made available to the unprivileged
327 user. A user will also not receive the pid that generated
328 the event, unless the listening process itself generated the
329 event.
330
332 Linux.
333
335 Linux 2.6.37.
336
338 The following bug was present before Linux 3.18:
339 • The O_CLOEXEC is ignored when passed in event_f_flags.
341 The following bug was present before Linux 3.14:
343 • The event_f_flags argument is not checked for invalid flags. Flags
345 that are intended only for internal use, such as FMODE_EXEC, can be
346 set, and will consequently be set for the file descriptors returned
347 when reading from the fanotify file descriptor.
348
350 fanotify_mark(2), fanotify(7)
351Linux man-pages 6.05 2023-07-08 fanotify_init(2)