Debian Codegraph @

upstream/debian-unstable/man2/fanotify_mark.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_mark 2 2025-10-06 "Linux man-pages 6.18"
6 .SH NAME
7 fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem
8 object
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/fanotify.h>
15 .P
16 .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags ,
17 .BI " uint64_t " mask ", int " dirfd ,
18 .BI " const char *_Nullable " path );
19 .fi
20 .SH DESCRIPTION
21 For an overview of the fanotify API, see
22 .BR fanotify (7).
23 .P
24 .BR fanotify_mark ()
25 adds, removes, or modifies an fanotify mark on a filesystem object.
26 The caller must have read permission on the filesystem object that
27 is to be marked.
28 .P
29 The
30 .I fanotify_fd
31 argument is a file descriptor returned by
32 .BR fanotify_init (2).
33 .P
34 .I flags
35 is a bit mask describing the modification to perform.
36 It must include exactly one of the following values:
37 .TP
38 .B FAN_MARK_ADD
39 The events in
40 .I mask
41 will be added to the mark mask (or to the ignore mask).
42 .I mask
43 must be nonempty or the error
44 .B EINVAL
45 will occur.
46 .TP
47 .B FAN_MARK_REMOVE
48 The events in argument
49 .I mask
50 will be removed from the mark mask (or from the ignore mask).
51 .I mask
52 must be nonempty or the error
53 .B EINVAL
54 will occur.
55 .TP
56 .B FAN_MARK_FLUSH
57 Remove either all marks for filesystems, all marks for mounts, or all
58 marks for directories and files from the fanotify group.
59 If
60 .I flags
61 contains
62 .BR FAN_MARK_MOUNT ,
63 all marks for mounts are removed from the group.
64 If
65 .I flags
66 contains
67 .BR FAN_MARK_FILESYSTEM ,
68 all marks for filesystems are removed from the group.
69 Otherwise, all marks for directories and files are removed.
70 No flag other than, and at most one of, the flags
71 .BR FAN_MARK_MNTNS ,
72 .BR FAN_MARK_MOUNT ,
73 or
74 .B FAN_MARK_FILESYSTEM
75 can be used in conjunction with
76 .BR FAN_MARK_FLUSH .
77 .I mask
78 is ignored.
79 .P
80 If none of the values above is specified, or more than one is specified,
81 the call fails with the error
82 .BR EINVAL .
83 .P
84 In addition,
85 zero or more of the following values may be ORed into
86 .IR flags :
87 .TP
88 .B FAN_MARK_DONT_FOLLOW
89 If
90 .I path
91 is a symbolic link, mark the link itself, rather than the file to which it
92 refers.
93 (By default,
94 .BR fanotify_mark ()
95 dereferences
96 .I path
97 if it is a symbolic link.)
98 .TP
99 .B FAN_MARK_ONLYDIR
100 If the filesystem object to be marked is not a directory, the error
101 .B ENOTDIR
102 shall be raised.
103 .TP
104 .BR FAN_MARK_MNTNS " (since Linux 6.14)"
105 .\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
106 Mark the mount namespace specified by
107 .IR path .
108 If
109 .I path
110 does not represent a mount namespace (e.g.
111 .IR /proc/ pid /ns/mnt ),
112 the call fails with the error
113 .BR EINVAL .
114 An fanotify group that was initialized with flag
115 .B FAN_REPORT_MNT
116 is required.
117 .TP
118 .B FAN_MARK_MOUNT
119 Mark the mount specified by
120 .IR path .
121 If
122 .I path
123 is not itself a mount point, the mount containing
124 .I path
125 will be marked.
126 All directories, subdirectories, and the contained files of the mount
127 will be monitored.
128 The events which require that filesystem objects are identified by file handles,
129 such as
130 .BR FAN_CREATE ,
131 .BR FAN_ATTRIB ,
132 .BR FAN_MOVE ,
133 and
134 .BR FAN_DELETE_SELF ,
135 cannot be provided as a
136 .I mask
137 when
138 .I flags
139 contains
140 .BR FAN_MARK_MOUNT .
141 Attempting to do so will result in the error
142 .B EINVAL
143 being returned.
144 Use of this flag requires the
145 .B CAP_SYS_ADMIN
146 capability.
147 .TP
148 .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
149 .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
150 Mark the filesystem specified by
151 .IR path .
152 The filesystem containing
153 .I path
154 will be marked.
155 All the contained files and directories of the filesystem from any mount
156 point will be monitored.
157 Use of this flag requires the
158 .B CAP_SYS_ADMIN
159 capability.
160 .TP
161 .B FAN_MARK_IGNORED_MASK
162 The events in
163 .I mask
164 shall be added to or removed from the ignore mask.
165 Note that the flags
166 .BR FAN_ONDIR ,
167 and
168 .B FAN_EVENT_ON_CHILD
169 have no effect when provided with this flag.
170 The effect of setting the flags
171 .BR FAN_ONDIR ,
172 and
173 .B FAN_EVENT_ON_CHILD
174 in the mark mask
175 on the events that are set in the ignore mask
176 is undefined and depends on the Linux kernel version.
177 Specifically, prior to Linux 5.9,
178 .\" commit 497b0c5a7c0688c1b100a9c2e267337f677c198e
179 setting a mark mask on a file
180 and a mark with ignore mask on its parent directory
181 would not result in ignoring events on the file,
182 regardless of the
183 .B FAN_EVENT_ON_CHILD
184 flag in the parent directory's mark mask.
185 When the ignore mask is updated with the
186 .B FAN_MARK_IGNORED_MASK
187 flag
188 on a mark that was previously updated with the
189 .B FAN_MARK_IGNORE
190 flag,
191 the update fails with
192 .B EEXIST
193 error.
194 .TP
195 .BR FAN_MARK_IGNORE " (since Linux 6.0, 5.15.154, and 5.10.220)"
196 .\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0
197 This flag has a similar effect as setting the
198 .B FAN_MARK_IGNORED_MASK
199 flag.
200 The events in
201 .I mask
202 shall be added to or removed from the ignore mask.
203 Unlike the
204 .B FAN_MARK_IGNORED_MASK
205 flag,
206 this flag also has the effect that the
207 .BR FAN_ONDIR ,
208 and
209 .B FAN_EVENT_ON_CHILD
210 flags take effect on the ignore mask.
211 Specifically, unless the
212 .B FAN_ONDIR
213 flag is set with
214 .BR FAN_MARK_IGNORE ,
215 events on directories will not be ignored.
216 If the flag
217 .B FAN_EVENT_ON_CHILD
218 is set with
219 .BR FAN_MARK_IGNORE ,
220 events on children will be ignored.
221 For example,
222 a mark on a directory with combination of
223 a mask with
224 .B FAN_CREATE
225 event
226 and
227 .B FAN_ONDIR
228 flag
229 and an ignore mask with
230 .B FAN_CREATE
231 event
232 and without
233 .B FAN_ONDIR
234 flag,
235 will result in getting only
236 the events for creation of sub-directories.
237 When using the
238 .B FAN_MARK_IGNORE
239 flag to add to an ignore mask
240 of a mount,
241 filesystem,
242 or directory inode mark,
243 the
244 .B FAN_MARK_IGNORED_SURV_MODIFY
245 flag must be specified.
246 Failure to do so will results with
247 .B EINVAL
248 or
249 .B EISDIR
250 error.
251 .TP
252 .B FAN_MARK_IGNORED_SURV_MODIFY
253 The ignore mask shall survive modify events.
254 If this flag is not set,
255 the ignore mask is cleared when a modify event occurs
256 on the marked object.
257 Omitting this flag is typically used to suppress events
258 (e.g.,
259 .BR FAN_OPEN )
260 for a specific file,
261 until that specific file's content has been modified.
262 It is far less useful to suppress events
263 on an entire filesystem,
264 or mount,
265 or on all files inside a directory,
266 until some file's content has been modified.
267 For this reason,
268 the
269 .B FAN_MARK_IGNORE
270 flag requires the
271 .B FAN_MARK_IGNORED_SURV_MODIFY
272 flag on a mount,
273 filesystem,
274 or directory inode mark.
275 This flag cannot be removed from a mark once set.
276 When the ignore mask is updated without this flag
277 on a mark that was previously updated with the
278 .B FAN_MARK_IGNORE
279 and
280 .B FAN_MARK_IGNORED_SURV_MODIFY
281 flags,
282 the update fails with
283 .B EEXIST
284 error.
285 .TP
286 .B FAN_MARK_IGNORE_SURV
287 This is a synonym for
288 .RB ( FAN_MARK_IGNORE | FAN_MARK_IGNORED_SURV_MODIFY ).
289 .TP
290 .BR FAN_MARK_EVICTABLE " (since Linux 5.19, 5.15.154, and 5.10.220)"
291 .\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c
292 When an inode mark is created with this flag,
293 the inode object will not be pinned to the inode cache,
294 therefore,
295 allowing the inode object to be evicted from the inode cache
296 when the memory pressure on the system is high.
297 The eviction of the inode object
298 results in the evictable mark also being lost.
299 When the mask of an evictable inode mark is updated
300 without using the
301 .B FAN_MARK_EVICATBLE
302 flag,
303 the marked inode is pinned to inode cache
304 and the mark is no longer evictable.
305 When the mask of a non-evictable inode mark is updated
306 with the
307 .B FAN_MARK_EVICTABLE
308 flag,
309 the inode mark remains non-evictable
310 and the update fails with
311 .B EEXIST
312 error.
313 Mounts and filesystems are not evictable objects,
314 therefore,
315 an attempt to create a mount mark or a filesystem mark
316 with the
317 .B FAN_MARK_EVICTABLE
318 flag,
319 will result in the error
320 .BR EINVAL .
321 For example,
322 inode marks can be used in combination with mount marks
323 to reduce the amount of events from noninteresting paths.
324 The event listener reads events,
325 checks if the path reported in the event is of interest,
326 and if it is not,
327 the listener sets a mark with an ignore mask on the directory.
328 Evictable inode marks allow using this method for a large number of directories
329 without the concern of pinning all inodes and exhausting the system's memory.
330 .P
331 .I mask
332 defines which events shall be listened for (or which shall be ignored).
333 It is a bit mask composed of the following values:
334 .TP
335 .B FAN_ACCESS
336 Create an event when a file or directory (but see BUGS) is accessed (read).
337 .TP
338 .B FAN_MODIFY
339 Create an event when a file is modified (write).
340 .TP
341 .B FAN_CLOSE_WRITE
342 Create an event when a writable file is closed.
343 .TP
344 .B FAN_CLOSE_NOWRITE
345 Create an event when a read-only file or directory is closed.
346 .TP
347 .B FAN_OPEN
348 Create an event when a file or directory is opened.
349 .TP
350 .BR FAN_OPEN_EXEC " (since Linux 5.0)"
351 .\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa
352 Create an event when a file is opened with the intent to be executed.
353 See NOTES for additional details.
354 .TP
355 .BR FAN_ATTRIB " (since Linux 5.1)"
356 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
357 Create an event when the metadata for a file or directory has changed.
358 An fanotify group that identifies filesystem objects by file handles
359 is required.
360 .TP
361 .BR FAN_CREATE " (since Linux 5.1)"
362 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
363 Create an event when a file or directory has been created in a marked
364 parent directory.
365 An fanotify group that identifies filesystem objects by file handles
366 is required.
367 .TP
368 .BR FAN_DELETE " (since Linux 5.1)"
369 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
370 Create an event when a file or directory has been deleted in a marked
371 parent directory.
372 An fanotify group that identifies filesystem objects by file handles
373 is required.
374 .TP
375 .BR FAN_DELETE_SELF " (since Linux 5.1)"
376 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
377 Create an event when a marked file or directory itself is deleted.
378 An fanotify group that identifies filesystem objects by file handles
379 is required.
380 .TP
381 .BR FAN_MOVED_FROM " (since Linux 5.1)"
382 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
383 Create an event when a file or directory has been moved from a marked
384 parent directory.
385 An fanotify group that identifies filesystem objects by file handles
386 is required.
387 .TP
388 .BR FAN_MOVED_TO " (since Linux 5.1)"
389 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
390 Create an event when a file or directory has been moved to a marked parent
391 directory.
392 An fanotify group that identifies filesystem objects by file handles
393 is required.
394 .TP
395 .BR FAN_RENAME " (since Linux 5.17, 5.15.154, and 5.10.220)"
396 .\" commit 8cc3b1ccd930fe6971e1527f0c4f1bdc8cb56026
397 This event contains the same information provided by events
398 .B FAN_MOVED_FROM
399 and
400 .BR FAN_MOVED_TO ,
401 however is represented by a single event with up to two information records.
402 An fanotify group that identifies filesystem objects by file handles
403 is required.
404 If the filesystem object to be marked is not a directory, the error
405 .B ENOTDIR
406 shall be raised.
407 .TP
408 .BR FAN_MOVE_SELF " (since Linux 5.1)"
409 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
410 Create an event when a marked file or directory itself has been moved.
411 An fanotify group that identifies filesystem objects by file handles
412 is required.
413 .TP
414 .B FAN_MNT_ATTACH
415 .TQ
416 .BR FAN_MNT_DETACH " (both since Linux 6.14)"
417 .\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
418 Create an event when
419 a mount was attached to or detached from a marked mount namespace,
420 respectively.
421 An attempt to set this flag on an inode, mount, or filesystem mark
422 will result in the error
423 .BR EINVAL .
424 An fanotify group that was initialized with flag
425 .B FAN_REPORT_MNT
426 and the mark flag
427 .B FAN_MARK_MNTNS
428 are required.
429 An additional information record of type
430 .B FAN_EVENT_INFO_TYPE_MNT
431 is returned with the event.
432 See
433 .BR fanotify (7)
434 for additional details.
435 .TP
436 .BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
437 .\" commit 9709bd548f11a092d124698118013f66e1740f9b
438 Create an event when a filesystem error
439 leading to inconsistent filesystem metadata is detected.
440 An additional information record of type
441 .B FAN_EVENT_INFO_TYPE_ERROR
442 is returned for each event in the read buffer.
443 An fanotify group that identifies filesystem objects by file handles
444 is required.
445 Events of such type are dependent on support
446 from the underlying filesystem.
447 At the time of writing,
448 only the
449 .B ext4
450 filesystem reports
451 .B FAN_FS_ERROR
452 events.
453 See
454 .BR fanotify (7)
455 for additional details.
456 .TP
457 .B FAN_OPEN_PERM
458 Create an event when a permission to open a file or directory is requested.
459 An fanotify file descriptor created with
460 .B FAN_CLASS_PRE_CONTENT
461 or
462 .B FAN_CLASS_CONTENT
463 is required.
464 .TP
465 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
466 .\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9
467 Create an event when a permission to open a file for execution is
468 requested.
469 An fanotify file descriptor created with
470 .B FAN_CLASS_PRE_CONTENT
471 or
472 .B FAN_CLASS_CONTENT
473 is required.
474 See NOTES for additional details.
475 .TP
476 .B FAN_ACCESS_PERM
477 Create an event when a permission to read a file or directory is requested.
478 An fanotify file descriptor created with
479 .B FAN_CLASS_PRE_CONTENT
480 or
481 .B FAN_CLASS_CONTENT
482 is required.
483 .TP
484 .BR FAN_PRE_ACCESS " (since Linux 6.14)"
485 .\" commit 4f8afa33817a6420398d1c177c6e220a05081f51
486 Create an event before read or write access to a file range,
487 that provides an opportunity for the event listener
488 to modify the content of the file
489 before access to the content
490 in the specified range.
491 An additional information record of type
492 .B FAN_EVENT_INFO_TYPE_RANGE
493 is returned for each event in the read buffer.
494 An fanotify file descriptor created with
495 .B FAN_CLASS_PRE_CONTENT
496 is required.
497 .TP
498 .B FAN_ONDIR
499 Create events for directories\[em]for example, when
500 .BR opendir (3),
501 .BR readdir (3)
502 (but see BUGS), and
503 .BR closedir (3)
504 are called.
505 Without this flag, events are created only for files.
506 In the context of directory entry events, such as
507 .BR FAN_CREATE ,
508 .BR FAN_DELETE ,
509 .BR FAN_MOVED_FROM ,
510 and
511 .BR FAN_MOVED_TO ,
512 specifying the flag
513 .B FAN_ONDIR
514 is required in order to create events when subdirectory entries are
515 modified (i.e.,
516 .BR mkdir (2)/
517 .BR rmdir (2)).
518 .TP
519 .B FAN_EVENT_ON_CHILD
520 Events for the immediate children of marked directories shall be created.
521 The flag has no effect when marking mounts and filesystems.
522 Note that events are not generated for children of the subdirectories
523 of marked directories.
524 More specifically, the directory entry modification events
525 .BR FAN_CREATE ,
526 .BR FAN_DELETE ,
527 .BR FAN_MOVED_FROM ,
528 and
529 .B FAN_MOVED_TO
530 are not generated for any entry modifications performed inside subdirectories
531 of marked directories.
532 Note that the events
533 .B FAN_DELETE_SELF
534 and
535 .B FAN_MOVE_SELF
536 are not generated for children of marked directories.
537 To monitor complete directory trees it is necessary to mark the relevant
538 mount or filesystem.
539 .P
540 The following composed values are defined:
541 .TP
542 .B FAN_CLOSE
543 A file is closed
544 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
545 .TP
546 .B FAN_MOVE
547 A file or directory has been moved
548 .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ).
549 .P
550 The filesystem object to be marked is determined by the file descriptor
551 .I dirfd
552 and the pathname specified in
553 .IR path :
554 .IP \[bu] 3
555 If
556 .I path
557 is NULL,
558 .I dirfd
559 defines the filesystem object to be marked.
560 .IP \[bu]
561 If
562 .I path
563 is NULL, and
564 .I dirfd
565 takes the special value
566 .BR AT_FDCWD ,
567 the current working directory is to be marked.
568 .IP \[bu]
569 If
570 .I path
571 is absolute, it defines the filesystem object to be marked, and
572 .I dirfd
573 is ignored.
574 .IP \[bu]
575 If
576 .I path
577 is relative, and
578 .I dirfd
579 does not have the value
580 .BR AT_FDCWD ,
581 then the filesystem object to be marked is determined by interpreting
582 .I path
583 relative the directory referred to by
584 .IR dirfd .
585 .IP \[bu]
586 If
587 .I path
588 is relative, and
589 .I dirfd
590 has the value
591 .BR AT_FDCWD ,
592 then the filesystem object to be marked is determined by interpreting
593 .I path
594 relative to the current working directory.
595 (See
596 .BR openat (2)
597 for an explanation of why the
598 .I dirfd
599 argument is useful.)
600 .SH RETURN VALUE
601 On success,
602 .BR fanotify_mark ()
603 returns 0.
604 On error, \-1 is returned, and
605 .I errno
606 is set to indicate the error.
607 .SH ERRORS
608 .TP
609 .B EBADF
610 An invalid file descriptor was passed in
611 .IR fanotify_fd .
612 .TP
613 .B EBADF
614 .I path
615 is relative but
616 .I dirfd
617 is neither
618 .B AT_FDCWD
619 nor a valid file descriptor.
620 .TP
621 .B EEXIST
622 The filesystem object indicated by
623 .I dirfd
624 and
625 .I path
626 has a mark that was updated without the
627 .B FAN_MARK_EVICTABLE
628 flag,
629 and the user attempted to update the mark with
630 .B FAN_MARK_EVICTABLE
631 flag.
632 .TP
633 .B EEXIST
634 The filesystem object indicated by
635 .I dirfd
636 and
637 .I path
638 has a mark that was updated with the
639 .B FAN_MARK_IGNORE
640 flag,
641 and the user attempted to update the mark with
642 .B FAN_MARK_IGNORED_MASK
643 flag.
644 .TP
645 .B EEXIST
646 The filesystem object indicated by
647 .I dirfd
648 and
649 .I path
650 has a mark that was updated with the
651 .B FAN_MARK_IGNORE
652 and
653 .B FAN_MARK_IGNORED_SURV_MODIFY
654 flags,
655 and the user attempted to update the mark only with
656 .B FAN_MARK_IGNORE
657 flag.
658 .TP
659 .B EINVAL
660 An invalid value was passed in
661 .I flags
662 or
663 .IR mask ,
664 or
665 .I fanotify_fd
666 was not an fanotify file descriptor.
667 .TP
668 .B EINVAL
669 The fanotify file descriptor was opened with
670 .B FAN_CLASS_NOTIF
671 or the fanotify group identifies filesystem objects by file handles
672 and mask contains a flag for permission events
673 .RB ( FAN_OPEN_PERM
674 or
675 .BR FAN_ACCESS_PERM ).
676 .TP
677 .B EINVAL
678 The group was initialized without
679 .B FAN_REPORT_FID
680 but one or more event types specified in the
681 .I mask
682 require it.
683 .TP
684 .B EINVAL
685 .I flags
686 contains
687 .BR FAN_MARK_IGNORE ,
688 and either
689 .B FAN_MARK_MOUNT
690 or
691 .BR FAN_MARK_FILESYSTEM ,
692 but does not contain
693 .BR FAN_MARK_IGNORED_SURV_MODIFY .
694 .TP
695 .B EISDIR
696 .I flags
697 contains
698 .BR FAN_MARK_IGNORE ,
699 but does not contain
700 .BR FAN_MARK_IGNORED_SURV_MODIFY ,
701 and
702 .I dirfd
703 and
704 .I path
705 specify a directory.
706 .TP
707 .B ENODEV
708 The filesystem object indicated by
709 .I dirfd
710 and
711 .I path
712 is associated with a filesystem that reports zero
713 .I fsid
714 (e.g.,
715 .BR fuse (4)).
716 This error can be returned only with an fanotify group that identifies
717 filesystem objects by file handles.
718 Since Linux 6.8,
719 .\" commit 30ad1938326bf9303ca38090339d948975a626f5
720 this error can be returned
721 when trying to add a mount or filesystem mark.
722 .TP
723 .B ENOENT
724 The filesystem object indicated by
725 .I dirfd
726 and
727 .I path
728 does not exist.
729 This error also occurs when trying to remove a mark from an object
730 that is not marked.
731 .TP
732 .B ENOMEM
733 The necessary memory could not be allocated.
734 .TP
735 .B ENOSPC
736 The number of marks for this user exceeds the limit and the
737 .B FAN_UNLIMITED_MARKS
738 flag was not specified when the fanotify file descriptor was created with
739 .BR fanotify_init (2).
740 See
741 .BR fanotify (7)
742 for details about this limit.
743 .TP
744 .B ENOSYS
745 This kernel does not implement
746 .BR fanotify_mark ().
747 The fanotify API is available only if the kernel was configured with
748 .BR CONFIG_FANOTIFY .
749 .TP
750 .B ENOTDIR
751 .I flags
752 contains
753 .BR FAN_MARK_ONLYDIR ,
754 and
755 .I dirfd
756 and
757 .I path
758 do not specify a directory.
759 .TP
760 .B ENOTDIR
761 .I mask
762 contains
763 .BR FAN_RENAME ,
764 and
765 .I dirfd
766 and
767 .I path
768 do not specify a directory.
769 .TP
770 .B ENOTDIR
771 .I flags
772 contains
773 .BR FAN_MARK_IGNORE ,
774 or the fanotify group was initialized with flag
775 .BR FAN_REPORT_TARGET_FID ,
776 and
777 .I mask
778 contains directory entry modification events
779 (e.g.,
780 .BR FAN_CREATE ,
781 .BR FAN_DELETE ),
782 or directory event flags
783 (e.g.,
784 .BR FAN_ONDIR ,
785 .BR FAN_EVENT_ON_CHILD ),
786 and
787 .I dirfd
788 and
789 .I path
790 do not specify a directory.
791 .TP
792 .B EOPNOTSUPP
793 The object indicated by
794 .I path
795 is associated with a filesystem
796 that does not support the encoding of file handles.
797 This error can be returned only with an fanotify group that identifies
798 filesystem objects by file handles.
799 Calling
800 .BR name_to_handle_at (2)
801 with the flag
802 .BR AT_HANDLE_FID " (since Linux 6.5)"
803 .\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8
804 can be used as a test
805 to check if a filesystem supports reporting events with file handles.
806 .TP
807 .B EPERM
808 The operation is not permitted because the caller lacks a required capability.
809 .TP
810 .B EXDEV
811 The filesystem object indicated by
812 .I path
813 resides within a filesystem subvolume (e.g.,
814 .BR btrfs (5))
815 which uses a different
816 .I fsid
817 than its root superblock.
818 This error can be returned only with an fanotify group that identifies
819 filesystem objects by file handles.
820 Since Linux 6.8,
821 .\" commit 30ad1938326bf9303ca38090339d948975a626f5
822 this error will be returned
823 when trying to add a mount or filesystem mark on a subvolume,
824 when trying to add inode marks in different subvolumes,
825 or when trying to add inode marks in a
826 .BR btrfs (5)
827 subvolume and in another filesystem.
828 Since Linux 6.8,
829 .\" commit 30ad1938326bf9303ca38090339d948975a626f5
830 this error will also be returned
831 when trying to add marks in different filesystems,
832 where one of the filesystems reports zero
833 .I fsid
834 (e.g.,
835 .BR fuse (4)).
836 .SH STANDARDS
837 Linux.
838 .SH HISTORY
839 Linux 2.6.37.
840 .\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37.
841 .SH NOTES
842 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
843 When using either
844 .B FAN_OPEN_EXEC
845 or
846 .B FAN_OPEN_EXEC_PERM
847 within the
848 .IR mask ,
849 events of these types will be returned only when the direct execution of a
850 program occurs.
851 More specifically, this means that events of these types will be generated
852 for files that are opened using
853 .BR execve (2),
854 .BR execveat (2),
855 or
856 .BR uselib (2).
857 Events of these types will not be raised in the situation where an
858 interpreter is passed (or reads) a file for interpretation.
859 .P
860 Additionally, if a mark has also been placed on the Linux dynamic
861 linker, a user should also expect to receive an event for it when
862 an ELF object has been successfully opened using
863 .BR execve (2)
864 or
865 .BR execveat (2).
866 .P
867 For example, if the following ELF binary were to be invoked and a
868 .B FAN_OPEN_EXEC
869 mark has been placed on /:
870 .P
871 .in +4n
872 .EX
873 $ /bin/echo foo
874 .EE
875 .in
876 .P
877 The listening application in this case would receive
878 .B FAN_OPEN_EXEC
879 events for both the ELF binary and interpreter, respectively:
880 .P
881 .in +4n
882 .EX
883 /bin/echo
884 /lib64/ld\-linux\-x86\-64.so.2
885 .EE
886 .in
887 .SH BUGS
888 The following bugs were present in before Linux 3.16:
889 .IP \[bu] 3
890 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
891 If
892 .I flags
893 contains
894 .BR FAN_MARK_FLUSH ,
895 .IR dirfd ,
896 and
897 .I path
898 must specify a valid filesystem object, even though this object is not used.
899 .IP \[bu]
900 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
901 .BR readdir (2)
902 does not generate a
903 .B FAN_ACCESS
904 event.
905 .IP \[bu]
906 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
907 If
908 .BR fanotify_mark ()
909 is called with
910 .BR FAN_MARK_FLUSH ,
911 .I flags
912 is not checked for invalid values.
913 .SH SEE ALSO
914 .BR fanotify_init (2),
915 .BR fanotify (7)