Debian Codegraph @

upstream/debian-unstable/man2/fanotify_init.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH fanotify_init 2 2025-05-17 "Linux man-pages 6.18"
6 .SH NAME
7 fanotify_init \- create and initialize fanotify group
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
14 .B #include <sys/fanotify.h>
15 .P
16 .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
17 .fi
18 .SH DESCRIPTION
19 For an overview of the fanotify API, see
20 .BR fanotify (7).
21 .P
22 .BR fanotify_init ()
23 initializes a new fanotify group and returns a file descriptor for the event
24 queue associated with the group.
25 .P
26 The file descriptor is used in calls to
27 .BR fanotify_mark (2)
28 to specify the files, directories, mounts, or filesystems for which fanotify
29 events shall be created.
30 These events are received by reading from the file descriptor.
31 Some events are only informative, indicating that a file has been accessed.
32 Other events can be used to determine whether
33 another application is permitted to access a file or directory.
34 Permission to access filesystem objects is granted by writing to the file
35 descriptor.
36 .P
37 Multiple programs may be using the fanotify interface at the same time to
38 monitor the same files.
39 .P
40 The number of fanotify groups per user is limited.
41 See
42 .BR fanotify (7)
43 for details about this limit.
44 .P
45 The
46 .I flags
47 argument contains a multi-bit field defining the notification class of the
48 listening application and further single bit fields specifying the behavior
49 of the file descriptor.
50 .P
51 If multiple listeners for permission events exist,
52 the notification class is used to establish the sequence
53 in which the listeners receive the events.
54 .P
55 Only one of the following notification classes may be specified in
56 .IR flags :
57 .TP
58 .B FAN_CLASS_PRE_CONTENT
59 This value allows the receipt of events notifying that a file has been
60 accessed and events for permission decisions if a file may be accessed.
61 It is intended for event listeners
62 that may need to write data to files
63 before their final data can be accessed.
64 This notification class might be used by hierarchical storage managers,
65 for example.
66 Use of this flag requires the
67 .B CAP_SYS_ADMIN
68 capability.
69 .TP
70 .B FAN_CLASS_CONTENT
71 This value allows the receipt of events notifying that a file has been
72 accessed and events for permission decisions if a file may be accessed.
73 It is intended for event listeners that need to access files when they
74 already contain their final content.
75 This notification class might be used by malware detection programs, for
76 example.
77 Use of this flag requires the
78 .B CAP_SYS_ADMIN
79 capability.
80 .TP
81 .B FAN_CLASS_NOTIF
82 This is the default value.
83 It does not need to be specified.
84 This value only allows the receipt of events notifying that a file has been
85 accessed.
86 Permission decisions before the file is accessed are not possible.
87 .P
88 Listeners with different notification classes will receive events in the
89 order
90 .BR FAN_CLASS_PRE_CONTENT ,
91 .BR FAN_CLASS_CONTENT ,
92 .BR FAN_CLASS_NOTIF .
93 The order of notification for listeners in the same notification class
94 is undefined.
95 .P
96 The following bits can additionally be set in
97 .IR flags :
98 .TP
99 .B FAN_CLOEXEC
100 Set the close-on-exec flag
101 .RB ( FD_CLOEXEC )
102 on the new file descriptor.
103 See the description of the
104 .B O_CLOEXEC
105 flag in
106 .BR open (2).
107 .TP
108 .B FAN_NONBLOCK
109 Enable the nonblocking flag
110 .RB ( O_NONBLOCK )
111 for the file descriptor.
112 Reading from the file descriptor will not block.
113 Instead, if no data is available,
114 .BR read (2)
115 fails with the error
116 .BR EAGAIN .
117 .TP
118 .B FAN_UNLIMITED_QUEUE
119 Remove the limit on the number of events in the event queue.
120 See
121 .BR fanotify (7)
122 for details about this limit.
123 Use of this flag requires the
124 .B CAP_SYS_ADMIN
125 capability.
126 .TP
127 .B FAN_UNLIMITED_MARKS
128 Remove the limit on the number of fanotify marks per user.
129 See
130 .BR fanotify (7)
131 for details about this limit.
132 Use of this flag requires the
133 .B CAP_SYS_ADMIN
134 capability.
135 .TP
136 .BR FAN_REPORT_TID " (since Linux 4.20)"
137 .\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29
138 Report thread ID (TID) instead of process ID (PID)
139 in the
140 .I pid
141 field of the
142 .I "struct fanotify_event_metadata"
143 supplied to
144 .BR read (2)
145 (see
146 .BR fanotify (7)).
147 Use of this flag requires the
148 .B CAP_SYS_ADMIN
149 capability.
150 .TP
151 .BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
152 .\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
153 Enable generation of audit log records about access mediation performed by
154 permission events.
155 The permission event response has to be marked with the
156 .B FAN_AUDIT
157 flag for an audit log record to be generated.
158 Use of this flag requires the
159 .B CAP_AUDIT_WRITE
160 capability.
161 .TP
162 .BR FAN_REPORT_FID " (since Linux 5.1)"
163 .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
164 This value allows the receipt of events which contain additional information
165 about the underlying filesystem object correlated to an event.
166 An additional record of type
167 .B FAN_EVENT_INFO_TYPE_FID
168 encapsulates the information about the object and is included alongside the
169 generic event metadata structure.
170 The file descriptor that is used to represent the object correlated to an
171 event is instead substituted with a file handle.
172 It is intended for applications that may find the use of a file handle to
173 identify an object more suitable than a file descriptor.
174 Additionally, it may be used for applications monitoring a directory or a
175 filesystem that are interested in the directory entry modification events
176 .BR FAN_CREATE ,
177 .BR FAN_DELETE ,
178 .BR FAN_MOVE ,
179 and
180 .BR FAN_RENAME ,
181 or in events such as
182 .BR FAN_ATTRIB ,
183 .BR FAN_DELETE_SELF ,
184 and
185 .BR FAN_MOVE_SELF .
186 All the events above require an fanotify group that identifies filesystem
187 objects by file handles.
188 Note that without the flag
189 .BR FAN_REPORT_TARGET_FID ,
190 for the directory entry modification events,
191 there is an information record that identifies the modified directory
192 and not the created/deleted/moved child object.
193 The use of
194 .B FAN_CLASS_CONTENT
195 or
196 .B FAN_CLASS_PRE_CONTENT
197 is not permitted with this flag and will result in the error
198 .BR EINVAL .
199 See
200 .BR fanotify (7)
201 for additional details.
202 .TP
203 .BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
204 .\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f
205 Events for fanotify groups initialized with this flag will contain
206 (see exceptions below) additional information about a directory object
207 correlated to an event.
208 An additional record of type
209 .B FAN_EVENT_INFO_TYPE_DFID
210 encapsulates the information about the directory object and is included
211 alongside the generic event metadata structure.
212 For events that occur on a non-directory object, the additional structure
213 includes a file handle that identifies the parent directory filesystem object.
214 Note that there is no guarantee that the directory filesystem object will be
215 found at the location described by the file handle information at the time
216 the event is received.
217 When combined with the flag
218 .BR FAN_REPORT_FID ,
219 two records may be reported with events that occur on a non-directory object,
220 one to identify the non-directory object itself and one to identify the parent
221 directory object.
222 Note that in some cases, a filesystem object does not have a parent,
223 for example, when an event occurs on an unlinked but open file.
224 In that case, with the
225 .B FAN_REPORT_FID
226 flag, the event will be reported with only one record to identify the
227 non-directory object itself, because there is no directory associated with
228 the event.
229 Without the
230 .B FAN_REPORT_FID
231 flag, no event will be reported.
232 See
233 .BR fanotify (7)
234 for additional details.
235 .TP
236 .BR FAN_REPORT_NAME " (since Linux 5.9)"
237 .\" commit 929943b38daf817f2e6d303ea04401651fc3bc05
238 Events for fanotify groups initialized with this flag will contain additional
239 information about the name of the directory entry correlated to an event.
240 This flag must be provided in conjunction with the flag
241 .BR FAN_REPORT_DIR_FID .
242 Providing this flag value without
243 .B FAN_REPORT_DIR_FID
244 will result in the error
245 .BR EINVAL .
246 This flag may be combined with the flag
247 .BR FAN_REPORT_FID .
248 An additional record of type
249 .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
250 which encapsulates the information about the directory entry, is included
251 alongside the generic event metadata structure and substitutes the additional
252 information record of type
253 .BR FAN_EVENT_INFO_TYPE_DFID .
254 The additional record includes a file handle that identifies a directory
255 filesystem object followed by a name that identifies an entry in that
256 directory.
257 For the directory entry modification events
258 .BR FAN_CREATE ,
259 .BR FAN_DELETE ,
260 and
261 .BR FAN_MOVE ,
262 the reported name is that of the created/deleted/moved directory entry.
263 The event
264 .B FAN_RENAME
265 may contain two information records.
266 One of type
267 .B FAN_EVENT_INFO_TYPE_OLD_DFID_NAME
268 identifying the old directory entry,
269 and another of type
270 .B FAN_EVENT_INFO_TYPE_NEW_DFID_NAME
271 identifying the new directory entry.
272 For other events that occur on a directory object, the reported file handle
273 is that of the directory object itself and the reported name is '.'.
274 For other events that occur on a non-directory object, the reported file handle
275 is that of the parent directory object and the reported name is the name of a
276 directory entry where the object was located at the time of the event.
277 The rationale behind this logic is that the reported directory file handle can
278 be passed to
279 .BR open_by_handle_at (2)
280 to get an open directory file descriptor and that file descriptor along with
281 the reported name can be used to call
282 .BR fstatat (2).
283 The same rule that applies to record type
284 .B FAN_EVENT_INFO_TYPE_DFID
285 also applies to record type
286 .BR FAN_EVENT_INFO_TYPE_DFID_NAME :
287 if a non-directory object has no parent, either the event will not be reported
288 or it will be reported without the directory entry information.
289 Note that there is no guarantee that the filesystem object will be found at the
290 location described by the directory entry information at the time the event is
291 received.
292 See
293 .BR fanotify (7)
294 for additional details.
295 .TP
296 .B FAN_REPORT_DFID_NAME
297 This is a synonym for
298 .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
299 .TP
300 .BR FAN_REPORT_TARGET_FID " (since Linux 5.17, 5.15.154, and 5.10.220)"
301 .\" commit d61fd650e9d206a71fda789f02a1ced4b19944c4
302 Events for fanotify groups initialized with this flag
303 will contain additional information about the child
304 correlated with directory entry modification events.
305 This flag must be provided in conjunction with the flags
306 .BR FAN_REPORT_FID ,
307 .B FAN_REPORT_DIR_FID
308 and
309 .BR FAN_REPORT_NAME .
310 or else the error
311 .B EINVAL
312 will be returned.
313 For the directory entry modification events
314 .BR FAN_CREATE ,
315 .BR FAN_DELETE ,
316 .BR FAN_MOVE ,
317 and
318 .BR FAN_RENAME ,
319 an additional record of type
320 .BR FAN_EVENT_INFO_TYPE_FID ,
321 is reported in addition to the information records of type
322 .BR FAN_EVENT_INFO_TYPE_DFID ,
323 .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
324 .BR FAN_EVENT_INFO_TYPE_OLD_DFID_NAME ,
325 and
326 .BR FAN_EVENT_INFO_TYPE_NEW_DFID_NAME .
327 The additional record includes a file handle
328 that identifies the filesystem child object
329 that the directory entry is referring to.
330 .TP
331 .B FAN_REPORT_DFID_NAME_TARGET
332 This is a synonym for
333 .RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
334 .TP
335 .BR FAN_REPORT_MNT " (since Linux 6.14)"
336 .\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
337 This value allows the receipt of events which contain additional information
338 about the underlying mount correlated to an event.
339 An additional record of type
340 .B FAN_EVENT_INFO_TYPE_MNT
341 encapsulates the information about the mount
342 and is included alongside the generic event metadata structure.
343 The use of
344 .BR FAN_CLASS_CONTENT ,
345 .BR FAN_CLASS_PRE_CONTENT ,
346 or any of the
347 .B FAN_REPORT_DFID_NAME_TARGET
348 flags along with this flag is not permitted
349 and will result in the error
350 .BR EINVAL .
351 See
352 .BR fanotify (7)
353 for additional details.
354 .TP
355 .BR FAN_REPORT_PIDFD " (since Linux 5.15 and 5.10.220)"
356 .\" commit af579beb666aefb17e9a335c12c788c92932baf1
357 Events for fanotify groups initialized with this flag will contain
358 an additional information record alongside the generic
359 .I fanotify_event_metadata
360 structure.
361 This information record will be of type
362 .B FAN_EVENT_INFO_TYPE_PIDFD
363 and will contain a pidfd for the process that
364 was responsible for generating an event.
365 A pidfd returned in this information record object is
366 no different to the pidfd that is returned when calling
367 .BR pidfd_open (2).
368 Usage of this information record are for applications that
369 may be interested in reliably determining whether
370 the process responsible for generating an event
371 has been recycled or terminated.
372 The use of the
373 .B FAN_REPORT_TID
374 flag along with
375 .B FAN_REPORT_PIDFD
376 is currently not supported and
377 attempting to do so will result in the error
378 .B EINVAL
379 being returned.
380 This limitation is currently imposed by the pidfd API
381 as it currently only supports
382 the creation of pidfds for thread-group leaders.
383 Creating pidfds for non-thread-group leaders
384 may be supported at some point in the future,
385 so this restriction may eventually be lifted.
386 For more details on information records,
387 see
388 .BR fanotify (7).
389 .TP
390 .BR FAN_REPORT_FD_ERROR " (since Linux 6.13 and 6.12.4 and 6.6.66)"
391 .\" commit 522249f05c5551aec9ec0ba9b6438f1ec19c138d
392 Events for fanotify groups initialized with this flag may contain
393 an error code that explains the reason for failure to open a file descriptor.
394 The
395 .I .fd
396 member of the
397 .I fanotify_event_metadata
398 structure normally contains
399 an open file descriptor associated with the object of the event
400 or FAN_NOFD in case a file descriptor could not be opened.
401 For a group initialized with this flag, instead of FAN_NOFD,
402 the
403 .I .fd
404 member of the
405 .I fanotify_event_metadata
406 structure will contain a negative error value.
407 When the group is also initialized with flag
408 .BR FAN_REPORT_PIDFD ,
409 in case a process file descriptor could not be opened,
410 the
411 .I .pidfd
412 member of the
413 .I fanotify_event_info_pidfd
414 structure will also contain a negative error value.
415 For more details, see
416 .BR fanotify (7).
417 .P
418 The
419 .I event_f_flags
420 argument
421 defines the file status flags that will be set on the open file descriptions
422 that are created for fanotify events.
423 For details of these flags, see the description of the
424 .I flags
425 values in
426 .BR open (2).
427 .I event_f_flags
428 includes a multi-bit field for the access mode.
429 This field can take the following values:
430 .TP
431 .B O_RDONLY
432 This value allows only read access.
433 .TP
434 .B O_WRONLY
435 This value allows only write access.
436 .TP
437 .B O_RDWR
438 This value allows read and write access.
439 .P
440 Additional bits can be set in
441 .IR event_f_flags .
442 The most useful values are:
443 .TP
444 .B O_LARGEFILE
445 Enable support for files exceeding 2\ GB.
446 Failing to set this flag will result in an
447 .B EOVERFLOW
448 error when trying to open a large file which is monitored by
449 an fanotify group on a 32-bit system.
450 .TP
451 .BR O_CLOEXEC " (since Linux 3.18)"
452 .\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
453 Enable the close-on-exec flag for the file descriptor.
454 See the description of the
455 .B O_CLOEXEC
456 flag in
457 .BR open (2)
458 for reasons why this may be useful.
459 .P
460 The following are also allowable:
461 .BR O_APPEND ,
462 .BR O_DSYNC ,
463 .BR O_NOATIME ,
464 .BR O_NONBLOCK ,
465 and
466 .BR O_SYNC .
467 Specifying any other flag in
468 .I event_f_flags
469 yields the error
470 .B EINVAL
471 (but see BUGS).
472 .SH RETURN VALUE
473 On success,
474 .BR fanotify_init ()
475 returns a new file descriptor.
476 On error, \-1 is returned, and
477 .I errno
478 is set to indicate the error.
479 .SH ERRORS
480 .TP
481 .B EINVAL
482 An invalid value was passed in
483 .I flags
484 or
485 .IR event_f_flags .
486 .B FAN_ALL_INIT_FLAGS
487 (deprecated since Linux 4.20)
488 .\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4
489 defines all allowable bits for
490 .IR flags .
491 .TP
492 .B EMFILE
493 The number of fanotify groups for this user exceeds the limit.
494 See
495 .BR fanotify (7)
496 for details about this limit.
497 .TP
498 .B EMFILE
499 The per-process limit on the number of open file descriptors has been reached.
500 .TP
501 .B ENOMEM
502 The allocation of memory for the notification group failed.
503 .TP
504 .B ENOSYS
505 This kernel does not implement
506 .BR fanotify_init ().
507 The fanotify API is available only if the kernel was configured with
508 .BR CONFIG_FANOTIFY .
509 .TP
510 .B EPERM
511 The operation is not permitted because the caller lacks a required capability.
512 .SH VERSIONS
513 Prior to Linux 5.13 (and 5.10.220),
514 .\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7
515 calling
516 .BR fanotify_init ()
517 required the
518 .B CAP_SYS_ADMIN
519 capability.
520 Since Linux 5.13 (and 5.10.220),
521 .\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7
522 users may call
523 .BR fanotify_init ()
524 without the
525 .B CAP_SYS_ADMIN
526 capability to create and initialize
527 an fanotify group with limited functionality.
528 .TP
529 The limitations imposed on an event listener created by a user without the
530 .B CAP_SYS_ADMIN
531 capability are as follows:
532 .RS
533 .IP \[bu] 3
534 The user cannot request for an unlimited event queue by using
535 .BR FAN_UNLIMITED_QUEUE .
536 .IP \[bu]
537 The user cannot request for an unlimited number of marks by using
538 .BR FAN_UNLIMITED_MARKS .
539 .IP \[bu]
540 The user cannot request to use either notification classes
541 .B FAN_CLASS_CONTENT
542 or
543 .BR FAN_CLASS_PRE_CONTENT .
544 This means that user cannot request permission events.
545 .IP \[bu]
546 The user is required to create a group that identifies filesystem objects by
547 file handles, for example, by providing the
548 .B FAN_REPORT_FID
549 flag.
550 .IP \[bu]
551 The user is limited to only mark inodes.
552 The ability to mark a mount or filesystem via
553 .BR fanotify_mark ()
554 through the use of
555 .B FAN_MARK_MOUNT
556 or
557 .B FAN_MARK_FILESYSTEM
558 is not permitted.
559 .IP \[bu]
560 The event object in the event queue is limited in terms of the information
561 that is made available to the unprivileged user.
562 A user will also not receive the pid that generated the event, unless the
563 listening process itself generated the event.
564 .RE
565 .SH STANDARDS
566 Linux.
567 .SH HISTORY
568 Linux 2.6.37.
569 .\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37.
570 .SH BUGS
571 The following bug was present before Linux 3.18:
572 .IP \[bu] 3
573 .\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
574 The
575 .B O_CLOEXEC
576 is ignored when passed in
577 .IR event_f_flags .
578 .P
579 The following bug was present before Linux 3.14:
580 .IP \[bu] 3
581 .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580
582 The
583 .I event_f_flags
584 argument is not checked for invalid flags.
585 Flags that are intended only for internal use,
586 such as
587 .BR FMODE_EXEC ,
588 can be set, and will consequently be set for the file descriptors
589 returned when reading from the fanotify file descriptor.
590 .SH SEE ALSO
591 .BR fanotify_mark (2),
592 .BR fanotify (7)