Debian Codegraph @

upstream/debian-unstable/man7/fanotify.7

raw
1 .\" Copyright 2014, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH fanotify 7 2026-02-14 "Linux man-pages 6.18"
7 .SH NAME
8 fanotify \- monitoring filesystem events
9 .SH DESCRIPTION
10 The fanotify API provides notification and interception of
11 filesystem events.
12 Use cases include virus scanning and hierarchical storage management.
13 In the original fanotify API, only a limited set of events was supported.
14 In particular, there was no support for create, delete, and move events.
15 The support for those events was added in Linux 5.1.
16 (See
17 .BR inotify (7)
18 for details of an API that did notify those events pre Linux 5.1.)
19 .P
20 Additional capabilities compared to the
21 .BR inotify (7)
22 API include the ability to monitor all of the objects
23 in a mounted filesystem,
24 the ability to make access permission decisions, and the
25 possibility to read or modify files before access by other applications.
26 .P
27 The following system calls are used with this API:
28 .BR fanotify_init (2),
29 .BR fanotify_mark (2),
30 .BR read (2),
31 .BR write (2),
32 and
33 .BR close (2).
34 .SS fanotify_init(), fanotify_mark(), and notification groups
35 The
36 .BR fanotify_init (2)
37 system call creates and initializes an fanotify notification group
38 and returns a file descriptor referring to it.
39 .P
40 An fanotify notification group is a kernel-internal object that holds
41 a list of files, directories, filesystems, and mounts for which
42 events shall be created.
43 .P
44 For each entry in an fanotify notification group, two bit masks exist: the
45 .I mark
46 mask and the
47 .I ignore
48 mask.
49 The mark mask defines file activities for which an event shall be created.
50 The ignore mask defines activities for which no event shall be generated.
51 Having these two types of masks permits a filesystem, mount, or
52 directory to be marked for receiving events, while at the same time
53 ignoring events for specific objects under a mount or directory.
54 .P
55 The
56 .BR fanotify_mark (2)
57 system call adds a file, directory, filesystem, or mount to a
58 notification group and specifies which events
59 shall be reported (or ignored), or removes or modifies such an entry.
60 .P
61 A possible usage of the ignore mask is for a file cache.
62 Events of interest for a file cache are modification of a file and closing
63 of the same.
64 Hence, the cached directory or mount is to be marked to receive these
65 events.
66 After receiving the first event informing that a file has been modified,
67 the corresponding cache entry will be invalidated.
68 No further modification events for this file are of interest until the file
69 is closed.
70 Hence, the modify event can be added to the ignore mask.
71 Upon receiving the close event, the modify event can be removed from the
72 ignore mask and the file cache entry can be updated.
73 .P
74 The entries in the fanotify notification groups refer to files and
75 directories via their inode number and to mounts via their mount ID.
76 If files or directories are renamed or moved within the same mount,
77 the respective entries survive.
78 If files or directories are deleted or moved to another mount or if
79 filesystems or mounts are unmounted, the corresponding entries are deleted.
80 .SS The event queue
81 As events occur on the filesystem objects monitored by a notification group,
82 the fanotify system generates events that are collected in a queue.
83 These events can then be read (using
84 .BR read (2)
85 or similar)
86 from the fanotify file descriptor
87 returned by
88 .BR fanotify_init (2).
89 .P
90 Two types of events are generated:
91 .I notification
92 events and
93 .I permission
94 events.
95 Notification events are merely informative and require no action to be taken
96 by the receiving application with one exception: if a valid file descriptor
97 is provided within a generic event, the file descriptor must be closed.
98 Permission events are requests to the receiving application to decide
99 whether permission for a file access shall be granted.
100 For these events, the recipient must write a response which decides whether
101 access is granted or not.
102 .P
103 An event is removed from the event queue of the fanotify group
104 when it has been read.
105 Permission events that have been read are kept in an internal list of the
106 fanotify group until either a permission decision has been taken by
107 writing to the fanotify file descriptor or the fanotify file descriptor
108 is closed.
109 .SS Reading fanotify events
110 Calling
111 .BR read (2)
112 for the file descriptor returned by
113 .BR fanotify_init (2)
114 blocks (if the flag
115 .B FAN_NONBLOCK
116 is not specified in the call to
117 .BR fanotify_init (2))
118 until either a file event occurs or the call is interrupted by a signal
119 (see
120 .BR signal (7)).
121 .P
122 After a successful
123 .BR read (2),
124 the read buffer contains one or more of the following structures:
125 .P
126 .in +4n
127 .EX
128 struct fanotify_event_metadata {
129 __u32 event_len;
130 __u8 vers;
131 __u8 reserved;
132 __u16 metadata_len;
133 __aligned_u64 mask;
134 __s32 fd;
135 __s32 pid;
136 };
137 .EE
138 .in
139 .P
140 Information records are
141 supplemental pieces of information that
142 may be provided alongside the generic
143 .I fanotify_event_metadata
144 structure.
145 The
146 .I flags
147 passed to
148 .BR fanotify_init (2)
149 have influence over the type of information records that
150 may be returned for an event.
151 For example,
152 if a notification group is initialized with
153 .B FAN_REPORT_FID
154 or
155 .BR FAN_REPORT_DIR_FID ,
156 then event listeners should also expect to receive a
157 .I fanotify_event_info_fid
158 structure alongside the
159 .I fanotify_event_metadata
160 structure,
161 whereby file handles are used to
162 identify filesystem objects
163 rather than file descriptors.
164 Information records may also be stacked,
165 meaning that using the various
166 .B FAN_REPORT_*
167 flags in conjunction with one another is supported.
168 In such cases,
169 multiple information records can be returned for an event
170 alongside the generic
171 .I fanotify_event_metadata
172 structure.
173 For example,
174 if a notification group is initialized with
175 .B FAN_REPORT_TARGET_FID
176 and
177 .BR FAN_REPORT_PIDFD ,
178 then an event listener should expect to receive up to two
179 .I fanotify_event_info_fid
180 information records and one
181 .I fanotify_event_info_pidfd
182 information record alongside the generic
183 .I fanotify_event_metadata
184 structure.
185 Importantly,
186 fanotify provides no guarantee around
187 the ordering of information records
188 when a notification group is initialized with a
189 stacked based configuration.
190 Each information record has a nested structure of type
191 .IR fanotify_event_info_header .
192 It is imperative for event listeners to inspect the
193 .I info_type
194 field of this structure in order to
195 determine the type of information record that
196 had been received for a given event.
197 .P
198 In cases where an fanotify group
199 identifies filesystem objects by file handles,
200 event listeners should also expect to
201 receive one or more of the below
202 information record objects alongside the generic
203 .I fanotify_event_metadata
204 structure within the read buffer:
205 .P
206 .in +4n
207 .EX
208 struct fanotify_event_info_fid {
209 struct fanotify_event_info_header hdr;
210 __kernel_fsid_t fsid;
211 unsigned char handle[];
212 };
213 .EE
214 .in
215 .P
216 In cases where an fanotify group is initialized with
217 .BR FAN_REPORT_PIDFD ,
218 event listeners should expect to receive the below
219 information record object alongside the generic
220 .I fanotify_event_metadata
221 structure within the read buffer:
222 .P
223 .in +4n
224 .EX
225 struct fanotify_event_info_pidfd {
226 struct fanotify_event_info_header hdr;
227 __s32 pidfd;
228 };
229 .EE
230 .in
231 .P
232 In cases where an fanotify group is initialized with
233 .BR FAN_REPORT_MNT ,
234 event listeners should expect to receive
235 the below information record object
236 alongside the generic
237 .I fanotify_event_metadata
238 structure within the read buffer.
239 This structure is defined as follows:
240 .P
241 .in +4n
242 .EX
243 struct fanotify_event_info_mnt {
244 struct fanotify_event_info_header hdr;
245 __u64 mnt_id;
246 };
247 .EE
248 .in
249 .P
250 In case of a
251 .B FAN_FS_ERROR
252 event,
253 an additional information record describing the error that occurred
254 is returned alongside the generic
255 .I fanotify_event_metadata
256 structure within the read buffer.
257 This structure is defined as follows:
258 .P
259 .in +4n
260 .EX
261 struct fanotify_event_info_error {
262 struct fanotify_event_info_header hdr;
263 __s32 error;
264 __u32 error_count;
265 };
266 .EE
267 .in
268 .P
269 In case of
270 .B FAN_PRE_ACCESS
271 events,
272 an additional information record describing the access range
273 is returned alongside the generic
274 .I fanotify_event_metadata
275 structure within the read buffer.
276 This structure is defined as follows:
277 .P
278 .in +4n
279 .EX
280 struct fanotify_event_info_range {
281 struct fanotify_event_info_header hdr;
282 __u32 pad;
283 __u64 offset;
284 __u64 count;
285 };
286 .EE
287 .in
288 .P
289 All information records contain a nested structure of type
290 .IR fanotify_event_info_header .
291 This structure holds meta-information about the information record
292 that may have been returned alongside the generic
293 .I fanotify_event_metadata
294 structure.
295 This structure is defined as follows:
296 .P
297 .in +4n
298 .EX
299 struct fanotify_event_info_header {
300 __u8 info_type;
301 __u8 pad;
302 __u16 len;
303 };
304 .EE
305 .in
306 .P
307 For performance reasons, it is recommended to use a large
308 buffer size (for example, 4096 bytes),
309 so that multiple events can be retrieved by a single
310 .BR read (2).
311 .P
312 The return value of
313 .BR read (2)
314 is the number of bytes placed in the buffer,
315 or \-1 in case of an error (but see BUGS).
316 .P
317 The fields of the
318 .I fanotify_event_metadata
319 structure are as follows:
320 .TP
321 .I event_len
322 This is the size of the data for the current event and the offset
323 to the next event in the buffer.
324 Unless the group identifies filesystem objects by file handles, the value of
325 .I event_len
326 is always
327 .BR FAN_EVENT_METADATA_LEN .
328 For a group that identifies filesystem objects by file handles,
329 .I event_len
330 also includes the variable size file identifier records.
331 .TP
332 .I vers
333 This field holds a version number for the structure.
334 It must be compared to
335 .B FANOTIFY_METADATA_VERSION
336 to verify that the structures returned at run time match
337 the structures defined at compile time.
338 In case of a mismatch, the application should abandon trying to use the
339 fanotify file descriptor.
340 .TP
341 .I reserved
342 This field is not used.
343 .TP
344 .I metadata_len
345 This is the size of the structure.
346 The field was introduced to facilitate the implementation of
347 optional headers per event type.
348 No such optional headers exist in the current implementation.
349 .TP
350 .I mask
351 This is a bit mask describing the event (see below).
352 .TP
353 .I fd
354 This is an open file descriptor for the object being accessed, or
355 .B FAN_NOFD
356 if a queue overflow occurred.
357 With an fanotify group that identifies filesystem objects by file handles,
358 applications should expect this value to be set to
359 .B FAN_NOFD
360 for each event that is received.
361 The file descriptor can be used to access the contents
362 of the monitored file or directory.
363 The reading application is responsible for closing this file descriptor.
364 .IP
365 When calling
366 .BR fanotify_init (2),
367 the caller may specify (via the
368 .I event_f_flags
369 argument) various file status flags that are to be set
370 on the open file description that corresponds to this file descriptor.
371 In addition, the (kernel-internal)
372 .B FMODE_NONOTIFY
373 file status flag is set on the open file description.
374 This flag suppresses fanotify event generation.
375 Hence, when the receiver of the fanotify event accesses the notified file or
376 directory using this file descriptor, no additional events will be created.
377 .IP
378 When an fanotify group is initialized using
379 .BR FAN_REPORT_FD_ERROR ,
380 this field will contain a negative error value in case a file descriptor
381 could not be opened and
382 in case of a queue overflow, the value will be
383 .BR \-EBADF .
384 .TP
385 .I pid
386 If flag
387 .B FAN_REPORT_TID
388 was set in
389 .BR fanotify_init (2),
390 this is the TID of the thread that caused the event.
391 Otherwise, this the PID of the process that caused the event.
392 .P
393 A program listening to fanotify events can compare this PID
394 to the PID returned by
395 .BR getpid (2),
396 to determine whether the event is caused by the listener itself,
397 or is due to a file access by another process.
398 .P
399 The bit mask in
400 .I mask
401 indicates which events have occurred for a single filesystem object.
402 Multiple bits may be set in this mask,
403 if more than one event occurred for the monitored filesystem object.
404 In particular,
405 consecutive events for the same filesystem object and originating from the
406 same process may be merged into a single event, with the exception that two
407 permission events are never merged into one queue entry.
408 .P
409 The bits that may appear in
410 .I mask
411 are as follows:
412 .TP
413 .B FAN_ACCESS
414 A file or a directory (but see BUGS) was accessed (read).
415 .TP
416 .B FAN_OPEN
417 A file or a directory was opened.
418 .TP
419 .B FAN_OPEN_EXEC
420 A file was opened with the intent to be executed.
421 See NOTES in
422 .BR fanotify_mark (2)
423 for additional details.
424 .TP
425 .B FAN_ATTRIB
426 A file or directory metadata was changed.
427 .TP
428 .B FAN_CREATE
429 A child file or directory was created in a watched parent.
430 .TP
431 .B FAN_DELETE
432 A child file or directory was deleted in a watched parent.
433 .TP
434 .B FAN_DELETE_SELF
435 A watched file or directory was deleted.
436 .TP
437 .B FAN_RENAME
438 A file or directory has been moved to or from a watched parent directory.
439 .TP
440 .B FAN_MOVED_FROM
441 A file or directory has been moved from a watched parent directory.
442 .TP
443 .B FAN_MOVED_TO
444 A file or directory has been moved to a watched parent directory.
445 .TP
446 .B FAN_MOVE_SELF
447 A watched file or directory was moved.
448 .TP
449 .B FAN_MODIFY
450 A file was modified.
451 .TP
452 .B FAN_CLOSE_WRITE
453 A file that was opened for writing
454 .RB ( O_WRONLY
455 or
456 .BR O_RDWR )
457 was closed.
458 .TP
459 .B FAN_CLOSE_NOWRITE
460 A file or directory that was opened read-only
461 .RB ( O_RDONLY )
462 was closed.
463 .TP
464 .B FAN_MNT_ATTACH
465 A mount was attached to mount namespace.
466 .TP
467 .B FAN_MNT_DETACH
468 A mount was detached from mount namespace.
469 .TP
470 .B FAN_FS_ERROR
471 A filesystem error was detected.
472 .TP
473 .B FAN_Q_OVERFLOW
474 The event queue exceeded the limit on number of events.
475 This limit can be overridden by specifying the
476 .B FAN_UNLIMITED_QUEUE
477 flag when calling
478 .BR fanotify_init (2).
479 .TP
480 .B FAN_ACCESS_PERM
481 An application wants to read a file or directory, for example using
482 .BR read (2)
483 or
484 .BR readdir (2).
485 The reader must write a response (as described below)
486 that determines whether the permission to
487 access the filesystem object shall be granted.
488 .TP
489 .B FAN_OPEN_PERM
490 An application wants to open a file or directory.
491 The reader must write a response that determines whether the permission to
492 open the filesystem object shall be granted.
493 .TP
494 .B FAN_OPEN_EXEC_PERM
495 An application wants to open a file for execution.
496 The reader must write a response that determines whether the permission to
497 open the filesystem object for execution shall be granted.
498 See NOTES in
499 .BR fanotify_mark (2)
500 for additional details.
501 .P
502 To check for any close event, the following bit mask may be used:
503 .TP
504 .B FAN_CLOSE
505 A file was closed.
506 This is a synonym for:
507 .IP
508 .in +4n
509 .EX
510 FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
511 .EE
512 .in
513 .P
514 To check for any move event, the following bit mask may be used:
515 .TP
516 .B FAN_MOVE
517 A file or directory was moved.
518 This is a synonym for:
519 .IP
520 .in +4n
521 .EX
522 FAN_MOVED_FROM | FAN_MOVED_TO
523 .EE
524 .in
525 .P
526 The following bits may appear in
527 .I mask
528 only in conjunction with other event type bits:
529 .TP
530 .B FAN_ONDIR
531 The events described in the
532 .I mask
533 have occurred on a directory object.
534 Reporting events on directories requires setting this flag in the mark mask.
535 See
536 .BR fanotify_mark (2)
537 for additional details.
538 The
539 .B FAN_ONDIR
540 flag is reported in an event mask only if the fanotify group identifies
541 filesystem objects by file handles.
542 .P
543 Information records that are supplied alongside the generic
544 .I fanotify_event_metadata
545 structure will always contain a nested structure of type
546 .IR fanotify_event_info_header .
547 The fields of the
548 .I fanotify_event_info_header
549 are as follows:
550 .TP
551 .I info_type
552 A unique integer value representing
553 the type of information record object received for an event.
554 The value of this field can be set to one of the following.
555 .RS
556 .TP
557 .B FAN_EVENT_INFO_TYPE_FID
558 .TQ
559 .B FAN_EVENT_INFO_TYPE_DFID
560 .TQ
561 .B FAN_EVENT_INFO_TYPE_DFID_NAME
562 .TQ
563 .B FAN_EVENT_INFO_TYPE_PIDFD
564 .TQ
565 .B FAN_EVENT_INFO_TYPE_ERROR
566 .TQ
567 .B FAN_EVENT_INFO_TYPE_RANGE
568 .TQ
569 .B FAN_EVENT_INFO_TYPE_MNT
570 .RE
571 .IP
572 The value set for this field
573 is dependent on the flags that have been supplied to
574 .BR fanotify_init (2).
575 Refer to the field details of each information record object type below
576 to understand the different cases in which the
577 .I info_type
578 values can be set.
579 .TP
580 .I pad
581 This field is currently not used by any information record object type
582 and therefore is set to zero.
583 .TP
584 .I len
585 The value of
586 .I len
587 is set to the size of the information record object,
588 including the
589 .IR fanotify_event_info_header .
590 The total size of all additional information records
591 is not expected to be larger than
592 .RI ( event_len
593 \-
594 .IR metadata_len ).
595 .P
596 The fields of the
597 .I fanotify_event_info_fid
598 structure are as follows:
599 .TP
600 .I hdr
601 This is a structure of type
602 .IR fanotify_event_info_header .
603 For example, when an fanotify file descriptor is created using
604 .BR FAN_REPORT_FID ,
605 a single information record is expected to be attached to the event with
606 .I info_type
607 field value of
608 .BR FAN_EVENT_INFO_TYPE_FID .
609 When an fanotify file descriptor is created using the combination of
610 .B FAN_REPORT_FID
611 and
612 .BR FAN_REPORT_DIR_FID ,
613 there may be two information records attached to the event:
614 one with
615 .I info_type
616 field value of
617 .BR FAN_EVENT_INFO_TYPE_DFID ,
618 identifying a parent directory object, and one with
619 .I info_type
620 field value of
621 .BR FAN_EVENT_INFO_TYPE_FID ,
622 identifying a child object.
623 Note that for the directory entry modification events
624 .BR FAN_CREATE ,
625 .BR FAN_DELETE ,
626 .BR FAN_MOVE ,
627 and
628 .BR FAN_RENAME ,
629 an information record identifying the created/deleted/moved child object
630 is reported only if an fanotify group was initialized with the flag
631 .BR FAN_REPORT_TARGET_FID .
632 .TP
633 .I fsid
634 This is a unique identifier of the filesystem containing the object
635 associated with the event.
636 It is a structure of type
637 .I __kernel_fsid_t
638 and contains the same value as
639 .I f_fsid
640 when calling
641 .BR statfs (2).
642 Note that some filesystems (e.g.,
643 .BR fuse (4))
644 report zero
645 .IR fsid .
646 In these cases,
647 it is not possible to use
648 .I fsid
649 to associate the event with a specific filesystem instance,
650 so monitoring different filesystem instances that report zero
651 .I fsid
652 with the same fanotify group is not supported.
653 .TP
654 .I handle
655 This field contains a variable-size structure of type
656 .IR "struct file_handle" .
657 It is an opaque handle that corresponds to a specified object on a
658 filesystem as returned by
659 .BR name_to_handle_at (2).
660 It can be used to uniquely identify a file on a filesystem and can be
661 passed as an argument to
662 .BR open_by_handle_at (2).
663 If the value of
664 .I info_type
665 field is
666 .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
667 the file handle is followed by a null terminated string that identifies the
668 created/deleted/moved directory entry name.
669 For other events such as
670 .BR FAN_OPEN ,
671 .BR FAN_ATTRIB ,
672 .BR FAN_DELETE_SELF ,
673 and
674 .BR FAN_MOVE_SELF ,
675 if the value of
676 .I info_type
677 field is
678 .BR FAN_EVENT_INFO_TYPE_FID ,
679 the
680 .I handle
681 identifies the object correlated to the event.
682 If the value of
683 .I info_type
684 field is
685 .BR FAN_EVENT_INFO_TYPE_DFID ,
686 the
687 .I handle
688 identifies the directory object correlated to the event or the parent directory
689 of a non-directory object correlated to the event.
690 If the value of
691 .I info_type
692 field is
693 .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
694 the
695 .I handle
696 identifies the same directory object that would be reported with
697 .B FAN_EVENT_INFO_TYPE_DFID
698 and the file handle is followed by a null terminated string that identifies the
699 name of a directory entry in that directory, or '.' to identify the directory
700 object itself.
701 .P
702 The fields of the
703 .I fanotify_event_info_pidfd
704 structure are as follows:
705 .TP
706 .I hdr
707 This is a structure of type
708 .IR fanotify_event_info_header .
709 When an fanotify group is initialized using
710 .BR FAN_REPORT_PIDFD ,
711 the
712 .I info_type
713 field value of the
714 .I fanotify_event_info_header
715 is set to
716 .BR FAN_EVENT_INFO_TYPE_PIDFD .
717 .TP
718 .I pidfd
719 This is a process file descriptor that refers to
720 the process responsible for generating the event.
721 The returned process file descriptor is no different from
722 one which could be obtained manually if
723 .BR pidfd_open (2)
724 were to be called on
725 .IR fanotify_event_metadata.pid .
726 In the instance that an error is encountered during pidfd creation,
727 one of two possible error types represented by
728 a negative integer value may be returned in this
729 .I pidfd
730 field.
731 In cases where
732 the process responsible for generating the event
733 has terminated prior to
734 the event listener being able to
735 read events from the notification queue,
736 .B FAN_NOPIDFD
737 is returned.
738 The pidfd creation for an event is only performed at the time the
739 events are read from the notification queue.
740 All other possible pidfd creation failures are represented by
741 .BR FAN_EPIDFD .
742 Once the event listener has dealt with an event
743 and the pidfd is no longer required,
744 the pidfd should be closed via
745 .BR close (2).
746 .IP
747 When an fanotify group is initialized using
748 .BR FAN_REPORT_FD_ERROR ,
749 this field will contain a negative error value
750 in case a pidfd creation failure and
751 in case of a terminated process, the value will be
752 .BR \-ESRCH .
753 .P
754 The fields of the
755 .I fanotify_event_info_mnt
756 structure are as follows:
757 .TP
758 .I .hdr
759 This is a structure of type
760 .IR fanotify_event_info_header .
761 The
762 .I .info_type
763 field is set to
764 .BR FAN_EVENT_INFO_TYPE_MNT .
765 .TP
766 .I .mnt_id
767 Identifies the mount associated with the event.
768 It is a 64-bit unique mount id as the one returned by
769 .BR statx (2)
770 with the
771 .B STATX_MNT_ID_UNIQUE
772 flag.
773 .P
774 The fields of the
775 .I fanotify_event_info_error
776 structure are as follows:
777 .TP
778 .I hdr
779 This is a structure of type
780 .IR fanotify_event_info_header .
781 The
782 .I info_type
783 field is set to
784 .BR FAN_EVENT_INFO_TYPE_ERROR .
785 .TP
786 .I error
787 Identifies the type of error that occurred.
788 .TP
789 .I error_count
790 This is a counter of the number of errors suppressed
791 since the last error was read.
792 .P
793 The fields of the
794 .I fanotify_event_info_range
795 structure are as follows:
796 .TP
797 .I hdr
798 This is a structure of type
799 .IR fanotify_event_info_header .
800 The
801 .I info_type
802 field is set to
803 .BR FAN_EVENT_INFO_TYPE_RANGE .
804 .TP
805 .I count
806 The number of bytes being read or written to the file.
807 .TP
808 .I offset
809 The offset from which bytes are read or written to the file.
810 .P
811 The following macros are provided to iterate over a buffer containing
812 fanotify event metadata returned by a
813 .BR read (2)
814 from an fanotify file descriptor:
815 .TP
816 .B FAN_EVENT_OK(meta, size)
817 This macro checks the remaining size
818 .I size
819 of the buffer
820 .I meta
821 against the size of the metadata structure and the
822 .I event_len
823 field of the first metadata structure in the buffer.
824 .TP
825 .B FAN_EVENT_NEXT(meta, size)
826 This macro uses the size indicated in the
827 .I event_len
828 field of the metadata structure pointed to by
829 .I meta
830 to calculate the address of the next metadata structure that follows
831 .IR meta .
832 .I size
833 is the number of bytes of metadata that currently remain in the buffer.
834 The macro returns a pointer to the next metadata structure that follows
835 .IR meta ,
836 and reduces
837 .I size
838 by the number of bytes in the metadata structure that
839 has been skipped over (i.e., it subtracts
840 .I meta\->event_len
841 from
842 .IR size ).
843 .P
844 In addition, there is:
845 .TP
846 .B FAN_EVENT_METADATA_LEN
847 This macro returns the size (in bytes) of the structure
848 .IR fanotify_event_metadata .
849 This is the minimum size (and currently the only size) of any event metadata.
850 .\"
851 .SS Monitoring an fanotify file descriptor for events
852 When an fanotify event occurs, the fanotify file descriptor indicates as
853 readable when passed to
854 .BR epoll (7),
855 .BR poll (2),
856 or
857 .BR select (2).
858 .SS Dealing with permission events
859 For permission events, the application must
860 .BR write (2)
861 a structure of the following form to the
862 fanotify file descriptor:
863 .P
864 .in +4n
865 .EX
866 struct fanotify_response {
867 __s32 fd;
868 __u32 response;
869 };
870 .EE
871 .in
872 .P
873 The fields of this structure are as follows:
874 .TP
875 .I fd
876 This is the file descriptor from the structure
877 .IR fanotify_event_metadata .
878 .TP
879 .I response
880 This field indicates whether or not the permission is to be granted.
881 Its value must contain either the flag
882 .B FAN_ALLOW
883 to allow the file operation or
884 .B FAN_DENY
885 to deny the file operation.
886 .P
887 If access is denied, the requesting application call will receive an
888 .B EPERM
889 error.
890 Since Linux 6.13,
891 .\" commit b4b2ff4f61ded819bfa22e50fdec7693f51cbbee
892 if a notification group is initialized with class
893 .BR FAN_CLASS_PRE_CONTENT ,
894 the file operation can be denied with errors other than
895 .BR EPERM .
896 For example, for the requesting application to get the
897 .B EIO
898 error, the event listener can write the response
899 .BR FAN_DENY_ERRNO ( EIO ).
900 At the time of writing,
901 only the following error values could be returned to the application with
902 .BR FAN_DENY_ERRNO (\f[I]e\f[])
903 macro:
904 .BR EPERM ,
905 .BR EIO ,
906 .BR EBUSY ,
907 .BR ETXTBSY ,
908 .BR EAGAIN ,
909 .BR ENOSPC ,
910 .BR EDQUOT .
911 .P
912 Additionally, if the notification group has been created with the
913 .B FAN_ENABLE_AUDIT
914 flag, then the
915 .B FAN_AUDIT
916 flag can be set in the
917 .I response
918 field.
919 In that case, the audit subsystem will log information about the access
920 decision to the audit logs.
921 .P
922 Since Linux 6.3,
923 .\" commit 70529a199574c15a40f46b14256633b02ba10ca2
924 the
925 .B FAN_INFO
926 flag can be set in the
927 .I .response
928 field.
929 It indicates that an extra variable-length response record follows the
930 .I fanotify_response
931 structure.
932 Extra response records start with a common header:
933 .P
934 .in +4n
935 .EX
936 struct fanotify_response_info_header {
937 __u8 type;
938 __u8 pad;
939 __u16 len;
940 };
941 .EE
942 .in
943 .P
944 The value of
945 .I .type
946 determines the format of the extra response record.
947 .TP
948 .B FAN_RESPONSE_INFO_AUDIT_RULE
949 The following response record is expected
950 with extra details for the audit log:
951 .IP
952 .in +4n
953 .EX
954 struct fanotify_response_info_audit_rule {
955 struct fanotify_response_info_header hdr;
956 __u32 rule_number;
957 __u32 subj_trust;
958 __u32 obj_trust;
959 };
960 .EE
961 .in
962 .\"
963 .SS Monitoring filesystems for errors
964 A single
965 .B FAN_FS_ERROR
966 event is stored per filesystem at once.
967 Extra error messages are suppressed and accounted for in the
968 .I error_count
969 field of the existing
970 .B FAN_FS_ERROR
971 event record,
972 but details about the errors are lost.
973 .P
974 Errors reported by
975 .B FAN_FS_ERROR
976 are generic
977 .I errno
978 values,
979 but not all kinds of error types are reported by all filesystems.
980 .P
981 Errors not directly related to a file
982 (i.e., super block corruption)
983 are reported with an invalid
984 .IR handle .
985 For these errors, the
986 .I handle
987 will have the field
988 .I handle_type
989 set to
990 .BR FILEID_INVALID ,
991 and the handle buffer size set to
992 .BR 0 .
993 .\"
994 .SS Closing the fanotify file descriptor
995 When all file descriptors
996 referring to the fanotify notification group
997 are closed,
998 the fanotify group is released
999 and its resources are freed for reuse by the kernel.
1000 Upon
1001 .BR close (2),
1002 outstanding permission events will be set to allowed.
1003 .SS /proc interfaces
1004 The file
1005 .IR /proc/ pid /fdinfo/ fd
1006 contains information about fanotify marks for file descriptor
1007 .I fd
1008 of process
1009 .IR pid .
1010 See
1011 .BR proc (5)
1012 for details.
1013 .P
1014 Since Linux 5.13 (and 5.10.220),
1015 .\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
1016 the following interfaces can be used to control the amount of
1017 kernel resources consumed by fanotify:
1018 .TP
1019 .I /proc/sys/fs/fanotify/max_queued_events
1020 The value in this file is used when an application calls
1021 .BR fanotify_init (2)
1022 to set an upper limit on the number of events that can be
1023 queued to the corresponding fanotify group.
1024 Events in excess of this limit are dropped, but an
1025 .B FAN_Q_OVERFLOW
1026 event is always generated.
1027 Prior to Linux kernel 5.13,
1028 .\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
1029 the hardcoded limit was 16384 events.
1030 .TP
1031 .I /proc/sys/fs/fanotify/max_user_group
1032 This specifies an upper limit on the number of fanotify groups
1033 that can be created per real user ID.
1034 Prior to Linux kernel 5.13,
1035 .\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
1036 the hardcoded limit was 128 groups per user.
1037 .TP
1038 .I /proc/sys/fs/fanotify/max_user_marks
1039 This specifies an upper limit on the number of fanotify marks
1040 that can be created per real user ID.
1041 Prior to Linux kernel 5.13,
1042 .\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
1043 the hardcoded limit was 8192 marks per group (not per user).
1044 .SH ERRORS
1045 In addition to the usual errors for
1046 .BR read (2),
1047 the following errors can occur when reading from the
1048 fanotify file descriptor:
1049 .TP
1050 .B EINVAL
1051 The buffer is too small to hold the event.
1052 .TP
1053 .B EMFILE
1054 The per-process limit on the number of open files has been reached.
1055 See the description of
1056 .B RLIMIT_NOFILE
1057 in
1058 .BR getrlimit (2).
1059 .TP
1060 .B ENFILE
1061 The system-wide limit on the total number of open files has been reached.
1062 See
1063 .I /proc/sys/fs/file\-max
1064 in
1065 .BR proc (5).
1066 .TP
1067 .B ETXTBSY
1068 This error is returned by
1069 .BR read (2)
1070 if
1071 .B O_RDWR
1072 or
1073 .B O_WRONLY
1074 was specified in the
1075 .I event_f_flags
1076 argument when calling
1077 .BR fanotify_init (2)
1078 and an event occurred for a monitored file that is currently being executed.
1079 .P
1080 In addition to the usual errors for
1081 .BR write (2),
1082 the following errors can occur when writing to the fanotify file descriptor:
1083 .TP
1084 .B EINVAL
1085 Fanotify access permissions are not enabled in the kernel configuration
1086 or the value of
1087 .I response
1088 in the response structure is not valid.
1089 .TP
1090 .B ENOENT
1091 The file descriptor
1092 .I fd
1093 in the response structure is not valid.
1094 This may occur when a response for the permission event has already been
1095 written.
1096 .SH STANDARDS
1097 Linux.
1098 .SH HISTORY
1099 The fanotify API was introduced in Linux 2.6.36 and
1100 enabled in Linux 2.6.37.
1101 fdinfo support was added in Linux 3.8.
1102 .SH NOTES
1103 The fanotify API is available only if the kernel was built with the
1104 .B CONFIG_FANOTIFY
1105 configuration option enabled.
1106 In addition, fanotify permission handling is available only if the
1107 .B CONFIG_FANOTIFY_ACCESS_PERMISSIONS
1108 configuration option is enabled.
1109 .SS Limitations and caveats
1110 Fanotify reports only events that a user-space program triggers through the
1111 filesystem API.
1112 As a result,
1113 it does not catch remote events that occur on network filesystems.
1114 .P
1115 The fanotify API does not report file accesses and modifications that
1116 may occur because of
1117 .BR mmap (2),
1118 .BR msync (2),
1119 and
1120 .BR munmap (2).
1121 .P
1122 Events for directories are created only if the directory itself is opened,
1123 read, and closed.
1124 Adding, removing, or changing children of a marked directory does not create
1125 events for the monitored directory itself.
1126 .P
1127 Fanotify monitoring of directories is not recursive:
1128 to monitor subdirectories under a directory,
1129 additional marks must be created.
1130 The
1131 .B FAN_CREATE
1132 event can be used for detecting when a subdirectory has been created under
1133 a marked directory.
1134 An additional mark must then be set on the newly created subdirectory.
1135 This approach is racy, because it can lose events that occurred inside the
1136 newly created subdirectory, before a mark is added on that subdirectory.
1137 Monitoring mounts offers the capability to monitor a whole directory tree
1138 in a race-free manner.
1139 Monitoring filesystems offers the capability to monitor changes made from
1140 any mount of a filesystem instance in a race-free manner.
1141 .P
1142 The event queue can overflow.
1143 In this case, events are lost.
1144 .SH BUGS
1145 Before Linux 3.19,
1146 .BR fallocate (2)
1147 did not generate fanotify events.
1148 Since Linux 3.19,
1149 .\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35
1150 calls to
1151 .BR fallocate (2)
1152 generate
1153 .B FAN_MODIFY
1154 events.
1155 .P
1156 As of Linux 3.17,
1157 the following bugs exist:
1158 .IP \[bu] 3
1159 On Linux, a filesystem object may be accessible through multiple paths,
1160 for example, a part of a filesystem may be remounted using the
1161 .I \-\-bind
1162 option of
1163 .BR mount (8).
1164 A listener that marked a mount will be notified only of events that were
1165 triggered for a filesystem object using the same mount.
1166 Any other event will pass unnoticed.
1167 .IP \[bu]
1168 .\" FIXME . A patch was proposed.
1169 When an event is generated,
1170 no check is made to see whether the user ID of the
1171 receiving process has authorization to read or write the file
1172 before passing a file descriptor for that file.
1173 This poses a security risk, when the
1174 .B CAP_SYS_ADMIN
1175 capability is set for programs executed by unprivileged users.
1176 .IP \[bu]
1177 If a call to
1178 .BR read (2)
1179 processes multiple events from the fanotify queue and an error occurs,
1180 the return value will be the total size of the events successfully
1181 copied to the user-space buffer before the error occurred.
1182 The return value will not be \-1, and
1183 .I errno
1184 will not be set.
1185 Thus, the reading application has no way to detect the error.
1186 .SH EXAMPLES
1187 The two example programs below demonstrate the usage of the fanotify API.
1188 .SS Example program: fanotify_example.c
1189 The first program is an example of fanotify being
1190 used with its event object information passed in the form of a file
1191 descriptor.
1192 The program marks the mount passed as a command-line argument and
1193 waits for events of type
1194 .B FAN_OPEN_PERM
1195 and
1196 .BR FAN_CLOSE_WRITE .
1197 When a permission event occurs, a
1198 .B FAN_ALLOW
1199 response is given.
1200 .P
1201 The following shell session shows an example of
1202 running this program.
1203 This session involved editing the file
1204 .IR /home/user/temp/notes .
1205 Before the file was opened, a
1206 .B FAN_OPEN_PERM
1207 event occurred.
1208 After the file was closed, a
1209 .B FAN_CLOSE_WRITE
1210 event occurred.
1211 Execution of the program ends when the user presses the ENTER key.
1212 .P
1213 .in +4n
1214 .EX
1215 .RB # " ./fanotify_example /home" ;
1216 Press enter key to terminate.
1217 Listening for events.
1218 FAN_OPEN_PERM: File /home/user/temp/notes
1219 FAN_CLOSE_WRITE: File /home/user/temp/notes
1220 \&
1221 Listening for events stopped.
1222 .EE
1223 .in
1224 .SS Program source: fanotify_example.c
1225 \&
1226 .EX
1227 #define _GNU_SOURCE /* Needed to get O_LARGEFILE definition */
1228 #include <errno.h>
1229 #include <fcntl.h>
1230 #include <limits.h>
1231 #include <poll.h>
1232 #include <stdio.h>
1233 #include <stdlib.h>
1234 #include <sys/fanotify.h>
1235 #include <unistd.h>
1236 \&
1237 /* Read all available fanotify events from the file descriptor \[aq]fd\[aq]. */
1238 \&
1239 static void
1240 handle_events(int fd)
1241 {
1242 const struct fanotify_event_metadata *metadata;
1243 struct fanotify_event_metadata buf[200];
1244 ssize_t size;
1245 char path[PATH_MAX];
1246 ssize_t path_len;
1247 char procfd_path[PATH_MAX];
1248 struct fanotify_response response;
1249 \&
1250 /* Loop while events can be read from fanotify file descriptor. */
1251 \&
1252 for (;;) {
1253 \&
1254 /* Read some events. */
1255 \&
1256 size = read(fd, buf, sizeof(buf));
1257 if (size == \-1 && errno != EAGAIN) {
1258 perror("read");
1259 exit(EXIT_FAILURE);
1260 }
1261 \&
1262 /* Check if end of available data reached. */
1263 \&
1264 if (size <= 0)
1265 break;
1266 \&
1267 /* Point to the first event in the buffer. */
1268 \&
1269 metadata = buf;
1270 \&
1271 /* Loop over all events in the buffer. */
1272 \&
1273 while (FAN_EVENT_OK(metadata, size)) {
1274 \&
1275 /* Check that run\-time and compile\-time structures match. */
1276 \&
1277 if (metadata\->vers != FANOTIFY_METADATA_VERSION) {
1278 fprintf(stderr,
1279 "Mismatch of fanotify metadata version.\[rs]n");
1280 exit(EXIT_FAILURE);
1281 }
1282 \&
1283 /* metadata\->fd contains either FAN_NOFD, indicating a
1284 queue overflow, or a file descriptor (a nonnegative
1285 integer). Here, we simply ignore queue overflow. */
1286 \&
1287 if (metadata\->fd >= 0) {
1288 \&
1289 /* Handle open permission event. */
1290 \&
1291 if (metadata\->mask & FAN_OPEN_PERM) {
1292 printf("FAN_OPEN_PERM: ");
1293 \&
1294 /* Allow file to be opened. */
1295 \&
1296 response.fd = metadata\->fd;
1297 response.response = FAN_ALLOW;
1298 write(fd, &response, sizeof(response));
1299 }
1300 \&
1301 /* Handle closing of writable file event. */
1302 \&
1303 if (metadata\->mask & FAN_CLOSE_WRITE)
1304 printf("FAN_CLOSE_WRITE: ");
1305 \&
1306 /* Retrieve and print pathname of the accessed file. */
1307 \&
1308 snprintf(procfd_path, sizeof(procfd_path),
1309 "/proc/self/fd/%d", metadata\->fd);
1310 path_len = readlink(procfd_path, path,
1311 sizeof(path) \- 1);
1312 if (path_len == \-1) {
1313 perror("readlink");
1314 exit(EXIT_FAILURE);
1315 }
1316 \&
1317 path[path_len] = \[aq]\[rs]0\[aq];
1318 printf("File %s\[rs]n", path);
1319 \&
1320 /* Close the file descriptor of the event. */
1321 \&
1322 close(metadata\->fd);
1323 }
1324 \&
1325 /* Advance to next event. */
1326 \&
1327 metadata = FAN_EVENT_NEXT(metadata, size);
1328 }
1329 }
1330 }
1331 \&
1332 int
1333 main(int argc, char *argv[])
1334 {
1335 char buf;
1336 int fd, poll_num;
1337 nfds_t nfds;
1338 struct pollfd fds[2];
1339 \&
1340 /* Check mount point is supplied. */
1341 \&
1342 if (argc != 2) {
1343 fprintf(stderr, "Usage: %s MOUNT\[rs]n", argv[0]);
1344 exit(EXIT_FAILURE);
1345 }
1346 \&
1347 printf("Press enter key to terminate.\[rs]n");
1348 \&
1349 /* Create the file descriptor for accessing the fanotify API. */
1350 \&
1351 fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK,
1352 O_RDONLY | O_LARGEFILE);
1353 if (fd == \-1) {
1354 perror("fanotify_init");
1355 exit(EXIT_FAILURE);
1356 }
1357 \&
1358 /* Mark the mount for:
1359 \- permission events before opening files
1360 \- notification events after closing a write\-enabled
1361 file descriptor. */
1362 \&
1363 if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT,
1364 FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD,
1365 argv[1]) == \-1) {
1366 perror("fanotify_mark");
1367 exit(EXIT_FAILURE);
1368 }
1369 \&
1370 /* Prepare for polling. */
1371 \&
1372 nfds = 2;
1373 \&
1374 fds[0].fd = STDIN_FILENO; /* Console input */
1375 fds[0].events = POLLIN;
1376 \&
1377 fds[1].fd = fd; /* Fanotify input */
1378 fds[1].events = POLLIN;
1379 \&
1380 /* This is the loop to wait for incoming events. */
1381 \&
1382 printf("Listening for events.\[rs]n");
1383 \&
1384 for (;;) {
1385 poll_num = poll(fds, nfds, \-1);
1386 if (poll_num == \-1) {
1387 if (errno == EINTR) /* Interrupted by a signal */
1388 continue; /* Restart poll() */
1389 \&
1390 perror("poll"); /* Unexpected error */
1391 exit(EXIT_FAILURE);
1392 }
1393 \&
1394 if (poll_num > 0) {
1395 if (fds[0].revents & POLLIN) {
1396 \&
1397 /* Console input is available: empty stdin and quit. */
1398 \&
1399 while (read(STDIN_FILENO, &buf, 1) > 0 && buf != \[aq]\[rs]n\[aq])
1400 continue;
1401 break;
1402 }
1403 \&
1404 if (fds[1].revents & POLLIN) {
1405 \&
1406 /* Fanotify events are available. */
1407 \&
1408 handle_events(fd);
1409 }
1410 }
1411 }
1412 \&
1413 printf("Listening for events stopped.\[rs]n");
1414 exit(EXIT_SUCCESS);
1415 }
1416 .EE
1417 .\"
1418 .SS Example program: fanotify_fid.c
1419 The second program is an example of fanotify being used with a group that
1420 identifies objects by file handles.
1421 The program marks the filesystem object that is passed as
1422 a command-line argument
1423 and waits until an event of type
1424 .B FAN_CREATE
1425 has occurred.
1426 The event mask indicates which type of filesystem object\[em]either
1427 a file or a directory\[em]was created.
1428 Once all events have been read from the buffer and processed accordingly,
1429 the program simply terminates.
1430 .P
1431 The following shell sessions show two different invocations of
1432 this program, with different actions performed on a watched object.
1433 .P
1434 The first session shows a mark being placed on
1435 .IR /home/user .
1436 This is followed by the creation of a regular file,
1437 .IR /home/user/testfile.txt .
1438 This results in a
1439 .B FAN_CREATE
1440 event being generated and reported against the file's parent watched
1441 directory object and with the created file name.
1442 Program execution ends once all events captured within the buffer have
1443 been processed.
1444 .P
1445 .in +4n
1446 .EX
1447 .RB # " ./fanotify_fid /home/user" ;
1448 Listening for events.
1449 FAN_CREATE (file created):
1450 Directory /home/user has been modified.
1451 Entry \[aq]testfile.txt\[aq] is not a subdirectory.
1452 All events processed successfully. Program exiting.
1453 \&
1454 .RB $ " touch /home/user/testfile.txt" "; # In another terminal"
1455 .EE
1456 .in
1457 .P
1458 The second session shows a mark being placed on
1459 .IR /home/user .
1460 This is followed by the creation of a directory,
1461 .IR /home/user/testdir .
1462 This specific action results in a
1463 .B FAN_CREATE
1464 event being generated and is reported with the
1465 .B FAN_ONDIR
1466 flag set and with the created directory name.
1467 .P
1468 .in +4n
1469 .EX
1470 .RB # " ./fanotify_fid /home/user" ;
1471 Listening for events.
1472 FAN_CREATE | FAN_ONDIR (subdirectory created):
1473 Directory /home/user has been modified.
1474 Entry \[aq]testdir\[aq] is a subdirectory.
1475 All events processed successfully. Program exiting.
1476 \&
1477 .RB $ " mkdir \-p /home/user/testdir" "; # In another terminal"
1478 .EE
1479 .in
1480 .SS Program source: fanotify_fid.c
1481 \&
1482 .EX
1483 #define _GNU_SOURCE
1484 #include <errno.h>
1485 #include <fcntl.h>
1486 #include <limits.h>
1487 #include <stdio.h>
1488 #include <stdlib.h>
1489 #include <sys/types.h>
1490 #include <sys/stat.h>
1491 #include <sys/fanotify.h>
1492 #include <unistd.h>
1493 \&
1494 #define BUF_SIZE 256
1495 \&
1496 int
1497 main(int argc, char *argv[])
1498 {
1499 int fd, ret, event_fd, mount_fd;
1500 ssize_t size, path_len;
1501 char path[PATH_MAX];
1502 char procfd_path[PATH_MAX];
1503 char events_buf[BUF_SIZE];
1504 struct file_handle *file_handle;
1505 struct fanotify_event_metadata *metadata;
1506 struct fanotify_event_info_fid *fid;
1507 const char *file_name;
1508 struct stat sb;
1509 \&
1510 if (argc != 2) {
1511 fprintf(stderr, "Invalid number of command line arguments.\[rs]n");
1512 exit(EXIT_FAILURE);
1513 }
1514 \&
1515 mount_fd = open(argv[1], O_DIRECTORY | O_RDONLY);
1516 if (mount_fd == \-1) {
1517 perror(argv[1]);
1518 exit(EXIT_FAILURE);
1519 }
1520 \&
1521 /* Create an fanotify file descriptor with FAN_REPORT_DFID_NAME as
1522 a flag so that program can receive fid events with directory
1523 entry name. */
1524 \&
1525 fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME, 0);
1526 if (fd == \-1) {
1527 perror("fanotify_init");
1528 exit(EXIT_FAILURE);
1529 }
1530 \&
1531 /* Place a mark on the filesystem object supplied in argv[1]. */
1532 \&
1533 ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
1534 FAN_CREATE | FAN_ONDIR,
1535 AT_FDCWD, argv[1]);
1536 if (ret == \-1) {
1537 perror("fanotify_mark");
1538 exit(EXIT_FAILURE);
1539 }
1540 \&
1541 printf("Listening for events.\[rs]n");
1542 \&
1543 /* Read events from the event queue into a buffer. */
1544 \&
1545 size = read(fd, events_buf, sizeof(events_buf));
1546 if (size == \-1 && errno != EAGAIN) {
1547 perror("read");
1548 exit(EXIT_FAILURE);
1549 }
1550 \&
1551 /* Process all events within the buffer. */
1552 \&
1553 for (metadata = (struct fanotify_event_metadata *) events_buf;
1554 FAN_EVENT_OK(metadata, size);
1555 metadata = FAN_EVENT_NEXT(metadata, size)) {
1556 fid = (struct fanotify_event_info_fid *) (metadata + 1);
1557 file_handle = (struct file_handle *) fid\->handle;
1558 \&
1559 /* Ensure that the event info is of the correct type. */
1560 \&
1561 if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_FID ||
1562 fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID) {
1563 file_name = NULL;
1564 } else if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
1565 file_name = file_handle\->f_handle +
1566 file_handle\->handle_bytes;
1567 } else {
1568 fprintf(stderr, "Received unexpected event info type.\[rs]n");
1569 exit(EXIT_FAILURE);
1570 }
1571 \&
1572 if (metadata\->mask == FAN_CREATE)
1573 printf("FAN_CREATE (file created):\[rs]n");
1574 \&
1575 if (metadata\->mask == (FAN_CREATE | FAN_ONDIR))
1576 printf("FAN_CREATE | FAN_ONDIR (subdirectory created):\[rs]n");
1577 \&
1578 /* metadata\->fd is set to FAN_NOFD when the group identifies
1579 objects by file handles. To obtain a file descriptor for
1580 the file object corresponding to an event you can use the
1581 struct file_handle that\[aq]s provided within the
1582 fanotify_event_info_fid in conjunction with the
1583 open_by_handle_at(2) system call. A check for ESTALE is
1584 done to accommodate for the situation where the file handle
1585 for the object was deleted prior to this system call. */
1586 \&
1587 event_fd = open_by_handle_at(mount_fd, file_handle, O_RDONLY);
1588 if (event_fd == \-1) {
1589 if (errno == ESTALE) {
1590 printf("File handle is no longer valid. "
1591 "File has been deleted\[rs]n");
1592 continue;
1593 } else {
1594 perror("open_by_handle_at");
1595 exit(EXIT_FAILURE);
1596 }
1597 }
1598 \&
1599 snprintf(procfd_path, sizeof(procfd_path), "/proc/self/fd/%d",
1600 event_fd);
1601 \&
1602 /* Retrieve and print the path of the modified dentry. */
1603 \&
1604 path_len = readlink(procfd_path, path, sizeof(path) \- 1);
1605 if (path_len == \-1) {
1606 perror("readlink");
1607 exit(EXIT_FAILURE);
1608 }
1609 \&
1610 path[path_len] = \[aq]\[rs]0\[aq];
1611 printf("\[rs]tDirectory \[aq]%s\[aq] has been modified.\[rs]n", path);
1612 \&
1613 if (file_name) {
1614 ret = fstatat(event_fd, file_name, &sb, 0);
1615 if (ret == \-1) {
1616 if (errno != ENOENT) {
1617 perror("fstatat");
1618 exit(EXIT_FAILURE);
1619 }
1620 printf("\[rs]tEntry \[aq]%s\[aq] does not exist.\[rs]n", file_name);
1621 } else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
1622 printf("\[rs]tEntry \[aq]%s\[aq] is a subdirectory.\[rs]n", file_name);
1623 } else {
1624 printf("\[rs]tEntry \[aq]%s\[aq] is not a subdirectory.\[rs]n",
1625 file_name);
1626 }
1627 }
1628 \&
1629 /* Close associated file descriptor for this event. */
1630 \&
1631 close(event_fd);
1632 }
1633 \&
1634 printf("All events processed successfully. Program exiting.\[rs]n");
1635 exit(EXIT_SUCCESS);
1636 }
1637 .EE
1638 .SH SEE ALSO
1639 .ad l
1640 .BR fanotify_init (2),
1641 .BR fanotify_mark (2),
1642 .BR inotify (7)