1fanotify(7) Miscellaneous Information Manual fanotify(7)
2
6 fanotify - monitoring filesystem events
7
9 The fanotify API provides notification and interception of filesystem
10 events. Use cases include virus scanning and hierarchical storage man‐
11 agement. In the original fanotify API, only a limited set of events
12 was supported. In particular, there was no support for create, delete,
13 and move events. The support for those events was added in Linux 5.1.
14 (See inotify(7) for details of an API that did notify those events pre
15 Linux 5.1.)
16 Additional capabilities compared to the inotify(7) API include the
18 ability to monitor all of the objects in a mounted filesystem, the
19 ability to make access permission decisions, and the possibility to
20 read or modify files before access by other applications.
21 The following system calls are used with this API: fanotify_init(2),
23 fanotify_mark(2), read(2), write(2), and close(2).
24 fanotify_init(), fanotify_mark(), and notification groups
26 The fanotify_init(2) system call creates and initializes an fanotify
27 notification group and returns a file descriptor referring to it.
28 An fanotify notification group is a kernel-internal object that holds a
30 list of files, directories, filesystems, and mounts for which events
31 shall be created.
32 For each entry in an fanotify notification group, two bit masks exist:
34 the mark mask and the ignore mask. The mark mask defines file activi‐
35 ties for which an event shall be created. The ignore mask defines ac‐
36 tivities for which no event shall be generated. Having these two types
37 of masks permits a filesystem, mount, or directory to be marked for re‐
38 ceiving events, while at the same time ignoring events for specific ob‐
39 jects under a mount or directory.
40 The fanotify_mark(2) system call adds a file, directory, filesystem, or
42 mount to a notification group and specifies which events shall be re‐
43 ported (or ignored), or removes or modifies such an entry.
44 A possible usage of the ignore mask is for a file cache. Events of in‐
46 terest for a file cache are modification of a file and closing of the
47 same. Hence, the cached directory or mount is to be marked to receive
48 these events. After receiving the first event informing that a file
49 has been modified, the corresponding cache entry will be invalidated.
50 No further modification events for this file are of interest until the
51 file is closed. Hence, the modify event can be added to the ignore
52 mask. Upon receiving the close event, the modify event can be removed
53 from the ignore mask and the file cache entry can be updated.
54 The entries in the fanotify notification groups refer to files and di‐
56 rectories via their inode number and to mounts via their mount ID. If
57 files or directories are renamed or moved within the same mount, the
58 respective entries survive. If files or directories are deleted or
59 moved to another mount or if filesystems or mounts are unmounted, the
60 corresponding entries are deleted.
61 The event queue
63 As events occur on the filesystem objects monitored by a notification
64 group, the fanotify system generates events that are collected in a
65 queue. These events can then be read (using read(2) or similar) from
66 the fanotify file descriptor returned by fanotify_init(2).
67 Two types of events are generated: notification events and permission
69 events. Notification events are merely informative and require no ac‐
70 tion to be taken by the receiving application with one exception: if a
71 valid file descriptor is provided within a generic event, the file de‐
72 scriptor must be closed. Permission events are requests to the receiv‐
73 ing application to decide whether permission for a file access shall be
74 granted. For these events, the recipient must write a response which
75 decides whether access is granted or not.
76 An event is removed from the event queue of the fanotify group when it
78 has been read. Permission events that have been read are kept in an
79 internal list of the fanotify group until either a permission decision
80 has been taken by writing to the fanotify file descriptor or the fan‐
81 otify file descriptor is closed.
82 Reading fanotify events
84 Calling read(2) for the file descriptor returned by fanotify_init(2)
85 blocks (if the flag FAN_NONBLOCK is not specified in the call to fan‐
86 otify_init(2)) until either a file event occurs or the call is inter‐
87 rupted by a signal (see signal(7)).
88 After a successful read(2), the read buffer contains one or more of the
90 following structures:
91 struct fanotify_event_metadata {
93 __u32 event_len;
94 __u8 vers;
95 __u8 reserved;
96 __u16 metadata_len;
97 __aligned_u64 mask;
98 __s32 fd;
99 __s32 pid;
100 };
101 Information records are supplemental pieces of information that may be
103 provided alongside the generic fanotify_event_metadata structure. The
104 flags passed to fanotify_init(2) have influence over the type of infor‐
105 mation records that may be returned for an event. For example, if a
106 notification group is initialized with FAN_REPORT_FID or FAN_RE‐
107 PORT_DIR_FID, then event listeners should also expect to receive a fan‐
108 otify_event_info_fid structure alongside the fanotify_event_metadata
109 structure, whereby file handles are used to identify filesystem objects
110 rather than file descriptors. Information records may also be stacked,
111 meaning that using the various FAN_REPORT_* flags in conjunction with
112 one another is supported. In such cases, multiple information records
113 can be returned for an event alongside the generic fanotify_event_meta‐
114 data structure. For example, if a notification group is initialized
115 with FAN_REPORT_TARGET_FID and FAN_REPORT_PIDFD, then an event listener
116 should expect to receive up to two fanotify_event_info_fid information
117 records and one fanotify_event_info_pidfd information record alongside
118 the generic fanotify_event_metadata structure. Importantly, fanotify
119 provides no guarantee around the ordering of information records when a
120 notification group is initialized with a stacked based configuration.
121 Each information record has a nested structure of type fan‐
122 otify_event_info_header. It is imperative for event listeners to in‐
123 spect the info_type field of this structure in order to determine the
124 type of information record that had been received for a given event.
125 In cases where an fanotify group identifies filesystem objects by file
127 handles, event listeners should also expect to receive one or more of
128 the below information record objects alongside the generic fan‐
129 otify_event_metadata structure within the read buffer:
130 struct fanotify_event_info_fid {
132 struct fanotify_event_info_header hdr;
133 __kernel_fsid_t fsid;
134 unsigned char file_handle[0];
135 };
136 In cases where an fanotify group is initialized with FAN_REPORT_PIDFD,
138 event listeners should expect to receive the below information record
139 object alongside the generic fanotify_event_metadata structure within
140 the read buffer:
141 struct fanotify_event_info_pidfd {
143 struct fanotify_event_info_header hdr;
144 __s32 pidfd;
145 };
146 In case of a FAN_FS_ERROR event, an additional information record de‐
148 scribing the error that occurred is returned alongside the generic fan‐
149 otify_event_metadata structure within the read buffer. This structure
150 is defined as follows:
151 struct fanotify_event_info_error {
153 struct fanotify_event_info_header hdr;
154 __s32 error;
155 __u32 error_count;
156 };
157 All information records contain a nested structure of type fan‐
159 otify_event_info_header. This structure holds meta-information about
160 the information record that may have been returned alongside the
161 generic fanotify_event_metadata structure. This structure is defined
162 as follows:
163 struct fanotify_event_info_header {
165 __u8 info_type;
166 __u8 pad;
167 __u16 len;
168 };
169 For performance reasons, it is recommended to use a large buffer size
171 (for example, 4096 bytes), so that multiple events can be retrieved by
172 a single read(2).
173 The return value of read(2) is the number of bytes placed in the buf‐
175 fer, or -1 in case of an error (but see BUGS).
176 The fields of the fanotify_event_metadata structure are as follows:
178 event_len
180 This is the length of the data for the current event and the
181 offset to the next event in the buffer. Unless the group iden‐
182 tifies filesystem objects by file handles, the value of
183 event_len is always FAN_EVENT_METADATA_LEN. For a group that
184 identifies filesystem objects by file handles, event_len also
185 includes the variable length file identifier records.
186 vers This field holds a version number for the structure. It must be
188 compared to FANOTIFY_METADATA_VERSION to verify that the struc‐
189 tures returned at run time match the structures defined at com‐
190 pile time. In case of a mismatch, the application should aban‐
191 don trying to use the fanotify file descriptor.
192 reserved
194 This field is not used.
195 metadata_len
197 This is the length of the structure. The field was introduced
198 to facilitate the implementation of optional headers per event
199 type. No such optional headers exist in the current implementa‐
200 tion.
201 mask This is a bit mask describing the event (see below).
203 fd This is an open file descriptor for the object being accessed,
205 or FAN_NOFD if a queue overflow occurred. With an fanotify
206 group that identifies filesystem objects by file handles, appli‐
207 cations should expect this value to be set to FAN_NOFD for each
208 event that is received. The file descriptor can be used to ac‐
209 cess the contents of the monitored file or directory. The read‐
210 ing application is responsible for closing this file descriptor.
211 When calling fanotify_init(2), the caller may specify (via the
213 event_f_flags argument) various file status flags that are to be
214 set on the open file description that corresponds to this file
215 descriptor. In addition, the (kernel-internal) FMODE_NONOTIFY
216 file status flag is set on the open file description. This flag
217 suppresses fanotify event generation. Hence, when the receiver
218 of the fanotify event accesses the notified file or directory
219 using this file descriptor, no additional events will be cre‐
220 ated.
221 pid If flag FAN_REPORT_TID was set in fanotify_init(2), this is the
223 TID of the thread that caused the event. Otherwise, this the
224 PID of the process that caused the event.
225 A program listening to fanotify events can compare this PID to the PID
227 returned by getpid(2), to determine whether the event is caused by the
228 listener itself, or is due to a file access by another process.
229 The bit mask in mask indicates which events have occurred for a single
231 filesystem object. Multiple bits may be set in this mask, if more than
232 one event occurred for the monitored filesystem object. In particular,
233 consecutive events for the same filesystem object and originating from
234 the same process may be merged into a single event, with the exception
235 that two permission events are never merged into one queue entry.
236 The bits that may appear in mask are as follows:
238 FAN_ACCESS
240 A file or a directory (but see BUGS) was accessed (read).
241 FAN_OPEN
243 A file or a directory was opened.
244 FAN_OPEN_EXEC
246 A file was opened with the intent to be executed. See NOTES in
247 fanotify_mark(2) for additional details.
248 FAN_ATTRIB
250 A file or directory metadata was changed.
251 FAN_CREATE
253 A child file or directory was created in a watched parent.
254 FAN_DELETE
256 A child file or directory was deleted in a watched parent.
257 FAN_DELETE_SELF
259 A watched file or directory was deleted.
260 FAN_FS_ERROR
262 A filesystem error was detected.
263 FAN_RENAME
265 A file or directory has been moved to or from a watched parent
266 directory.
267 FAN_MOVED_FROM
269 A file or directory has been moved from a watched parent direc‐
270 tory.
271 FAN_MOVED_TO
273 A file or directory has been moved to a watched parent direc‐
274 tory.
275 FAN_MOVE_SELF
277 A watched file or directory was moved.
278 FAN_MODIFY
280 A file was modified.
281 FAN_CLOSE_WRITE
283 A file that was opened for writing (O_WRONLY or O_RDWR) was
284 closed.
285 FAN_CLOSE_NOWRITE
287 A file or directory that was opened read-only (O_RDONLY) was
288 closed.
289 FAN_Q_OVERFLOW
291 The event queue exceeded the limit on number of events. This
292 limit can be overridden by specifying the FAN_UNLIMITED_QUEUE
293 flag when calling fanotify_init(2).
294 FAN_ACCESS_PERM
296 An application wants to read a file or directory, for example
297 using read(2) or readdir(2). The reader must write a response
298 (as described below) that determines whether the permission to
299 access the filesystem object shall be granted.
300 FAN_OPEN_PERM
302 An application wants to open a file or directory. The reader
303 must write a response that determines whether the permission to
304 open the filesystem object shall be granted.
305 FAN_OPEN_EXEC_PERM
307 An application wants to open a file for execution. The reader
308 must write a response that determines whether the permission to
309 open the filesystem object for execution shall be granted. See
310 NOTES in fanotify_mark(2) for additional details.
311 To check for any close event, the following bit mask may be used:
313 FAN_CLOSE
315 A file was closed. This is a synonym for:
316 FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
318 To check for any move event, the following bit mask may be used:
320 FAN_MOVE
322 A file or directory was moved. This is a synonym for:
323 FAN_MOVED_FROM | FAN_MOVED_TO
325 The following bits may appear in mask only in conjunction with other
327 event type bits:
328 FAN_ONDIR
330 The events described in the mask have occurred on a directory
331 object. Reporting events on directories requires setting this
332 flag in the mark mask. See fanotify_mark(2) for additional de‐
333 tails. The FAN_ONDIR flag is reported in an event mask only if
334 the fanotify group identifies filesystem objects by file han‐
335 dles.
336 Information records that are supplied alongside the generic fan‐
338 otify_event_metadata structure will always contain a nested structure
339 of type fanotify_event_info_header. The fields of the fan‐
340 otify_event_info_header are as follows:
341 info_type
343 A unique integer value representing the type of information
344 record object received for an event. The value of this field
345 can be set to one of the following: FAN_EVENT_INFO_TYPE_FID,
346 FAN_EVENT_INFO_TYPE_DFID, FAN_EVENT_INFO_TYPE_DFID_NAME, or
347 FAN_EVENT_INFO_TYPE_PIDFD. The value set for this field is de‐
348 pendent on the flags that have been supplied to fan‐
349 otify_init(2). Refer to the field details of each information
350 record object type below to understand the different cases in
351 which the info_type values can be set.
352 pad This field is currently not used by any information record ob‐
354 ject type and therefore is set to zero.
355 len The value of len is set to the size of the information record
357 object, including the fanotify_event_info_header. The total
358 size of all additional information records is not expected to be
359 larger than (event_len - metadata_len).
360 The fields of the fanotify_event_info_fid structure are as follows:
362 hdr This is a structure of type fanotify_event_info_header. For ex‐
364 ample, when an fanotify file descriptor is created using FAN_RE‐
365 PORT_FID, a single information record is expected to be attached
366 to the event with info_type field value of
367 FAN_EVENT_INFO_TYPE_FID. When an fanotify file descriptor is
368 created using the combination of FAN_REPORT_FID and FAN_RE‐
369 PORT_DIR_FID, there may be two information records attached to
370 the event: one with info_type field value of
371 FAN_EVENT_INFO_TYPE_DFID, identifying a parent directory object,
372 and one with info_type field value of FAN_EVENT_INFO_TYPE_FID,
373 identifying a child object. Note that for the directory entry
374 modification events FAN_CREATE, FAN_DELETE, FAN_MOVE, and
375 FAN_RENAME, an information record identifying the cre‐
376 ated/deleted/moved child object is reported only if an fanotify
377 group was initialized with the flag FAN_REPORT_TARGET_FID.
378 fsid This is a unique identifier of the filesystem containing the ob‐
380 ject associated with the event. It is a structure of type
381 __kernel_fsid_t and contains the same value as f_fsid when call‐
382 ing statfs(2).
383 file_handle
385 This is a variable length structure of type struct file_handle.
386 It is an opaque handle that corresponds to a specified object on
387 a filesystem as returned by name_to_handle_at(2). It can be
388 used to uniquely identify a file on a filesystem and can be
389 passed as an argument to open_by_handle_at(2). If the value of
390 info_type field is FAN_EVENT_INFO_TYPE_DFID_NAME, the file han‐
391 dle is followed by a null terminated string that identifies the
392 created/deleted/moved directory entry name. For other events
393 such as FAN_OPEN, FAN_ATTRIB, FAN_DELETE_SELF, and
394 FAN_MOVE_SELF, if the value of info_type field is
395 FAN_EVENT_INFO_TYPE_FID, the file_handle identifies the object
396 correlated to the event. If the value of info_type field is
397 FAN_EVENT_INFO_TYPE_DFID, the file_handle identifies the direc‐
398 tory object correlated to the event or the parent directory of a
399 non-directory object correlated to the event. If the value of
400 info_type field is FAN_EVENT_INFO_TYPE_DFID_NAME, the file_han‐
401 dle identifies the same directory object that would be reported
402 with FAN_EVENT_INFO_TYPE_DFID and the file handle is followed by
403 a null terminated string that identifies the name of a directory
404 entry in that directory, or '.' to identify the directory object
405 itself.
406 The fields of the fanotify_event_info_pidfd structure are as follows:
408 hdr This is a structure of type fanotify_event_info_header. When an
410 fanotify group is initialized using FAN_REPORT_PIDFD, the
411 info_type field value of the fanotify_event_info_header is set
412 to FAN_EVENT_INFO_TYPE_PIDFD.
413 pidfd This is a process file descriptor that refers to the process re‐
415 sponsible for generating the event. The returned process file
416 descriptor is no different from one which could be obtained man‐
417 ually if pidfd_open(2) were to be called on fanotify_event_meta‐
418 data.pid. In the instance that an error is encountered during
419 pidfd creation, one of two possible error types represented by a
420 negative integer value may be returned in this pidfd field. In
421 cases where the process responsible for generating the event has
422 terminated prior to the event listener being able to read events
423 from the notification queue, FAN_NOPIDFD is returned. The pidfd
424 creation for an event is only performed at the time the events
425 are read from the notification queue. All other possible pidfd
426 creation failures are represented by FAN_EPIDFD. Once the event
427 listener has dealt with an event and the pidfd is no longer re‐
428 quired, the pidfd should be closed via close(2).
429 The fields of the fanotify_event_info_error structure are as follows:
431 hdr This is a structure of type fanotify_event_info_header. The
433 info_type field is set to FAN_EVENT_INFO_TYPE_ERROR.
434 error Identifies the type of error that occurred.
436 error_count
438 This is a counter of the number of errors suppressed since the
439 last error was read.
440 The following macros are provided to iterate over a buffer containing
442 fanotify event metadata returned by a read(2) from an fanotify file de‐
443 scriptor:
444 FAN_EVENT_OK(meta, len)
446 This macro checks the remaining length len of the buffer meta
447 against the length of the metadata structure and the event_len
448 field of the first metadata structure in the buffer.
449 FAN_EVENT_NEXT(meta, len)
451 This macro uses the length indicated in the event_len field of
452 the metadata structure pointed to by meta to calculate the ad‐
453 dress of the next metadata structure that follows meta. len is
454 the number of bytes of metadata that currently remain in the
455 buffer. The macro returns a pointer to the next metadata struc‐
456 ture that follows meta, and reduces len by the number of bytes
457 in the metadata structure that has been skipped over (i.e., it
458 subtracts meta->event_len from len).
459 In addition, there is:
461 FAN_EVENT_METADATA_LEN
463 This macro returns the size (in bytes) of the structure fan‐
464 otify_event_metadata. This is the minimum size (and currently
465 the only size) of any event metadata.
466 Monitoring an fanotify file descriptor for events
468 When an fanotify event occurs, the fanotify file descriptor indicates
469 as readable when passed to epoll(7), poll(2), or select(2).
470 Dealing with permission events
472 For permission events, the application must write(2) a structure of the
473 following form to the fanotify file descriptor:
474 struct fanotify_response {
476 __s32 fd;
477 __u32 response;
478 };
479 The fields of this structure are as follows:
481 fd This is the file descriptor from the structure fan‐
483 otify_event_metadata.
484 response
486 This field indicates whether or not the permission is to be
487 granted. Its value must be either FAN_ALLOW to allow the file
488 operation or FAN_DENY to deny the file operation.
489 If access is denied, the requesting application call will receive an
491 EPERM error. Additionally, if the notification group has been created
492 with the FAN_ENABLE_AUDIT flag, then the FAN_AUDIT flag can be set in
493 the response field. In that case, the audit subsystem will log infor‐
494 mation about the access decision to the audit logs.
495 Monitoring filesystems for errors
497 A single FAN_FS_ERROR event is stored per filesystem at once. Extra
498 error messages are suppressed and accounted for in the error_count
499 field of the existing FAN_FS_ERROR event record, but details about the
500 errors are lost.
501 Errors reported by FAN_FS_ERROR are generic errno values, but not all
503 kinds of error types are reported by all filesystems.
504 Errors not directly related to a file (i.e. super block corruption) are
506 reported with an invalid file_handle. For these errors, the file_han‐
507 dle will have the field handle_type set to FILEID_INVALID, and the han‐
508 dle buffer size set to 0.
509 Closing the fanotify file descriptor
511 When all file descriptors referring to the fanotify notification group
512 are closed, the fanotify group is released and its resources are freed
513 for reuse by the kernel. Upon close(2), outstanding permission events
514 will be set to allowed.
515 /proc interfaces
517 The file /proc/pid/fdinfo/fd contains information about fanotify marks
518 for file descriptor fd of process pid. See proc(5) for details.
519 Since Linux 5.13, the following interfaces can be used to control the
521 amount of kernel resources consumed by fanotify:
522 /proc/sys/fs/fanotify/max_queued_events
524 The value in this file is used when an application calls fan‐
525 otify_init(2) to set an upper limit on the number of events that
526 can be queued to the corresponding fanotify group. Events in
527 excess of this limit are dropped, but an FAN_Q_OVERFLOW event is
528 always generated. Prior to Linux kernel 5.13, the hardcoded
529 limit was 16384 events.
530 /proc/sys/fs/fanotify/max_user_group
532 This specifies an upper limit on the number of fanotify groups
533 that can be created per real user ID. Prior to Linux kernel
534 5.13, the hardcoded limit was 128 groups per user.
535 /proc/sys/fs/fanotify/max_user_marks
537 This specifies an upper limit on the number of fanotify marks
538 that can be created per real user ID. Prior to Linux kernel
539 5.13, the hardcoded limit was 8192 marks per group (not per
540 user).
541
543 In addition to the usual errors for read(2), the following errors can
544 occur when reading from the fanotify file descriptor:
545 EINVAL The buffer is too small to hold the event.
547 EMFILE The per-process limit on the number of open files has been
549 reached. See the description of RLIMIT_NOFILE in getrlimit(2).
550 ENFILE The system-wide limit on the total number of open files has been
552 reached. See /proc/sys/fs/file-max in proc(5).
553 ETXTBSY
555 This error is returned by read(2) if O_RDWR or O_WRONLY was
556 specified in the event_f_flags argument when calling fan‐
557 otify_init(2) and an event occurred for a monitored file that is
558 currently being executed.
559 In addition to the usual errors for write(2), the following errors can
561 occur when writing to the fanotify file descriptor:
562 EINVAL Fanotify access permissions are not enabled in the kernel con‐
564 figuration or the value of response in the response structure is
565 not valid.
566 ENOENT The file descriptor fd in the response structure is not valid.
568 This may occur when a response for the permission event has al‐
569 ready been written.
570
572 Linux.
573
575 The fanotify API was introduced in Linux 2.6.36 and enabled in Linux
576 2.6.37. fdinfo support was added in Linux 3.8.
577
579 The fanotify API is available only if the kernel was built with the
580 CONFIG_FANOTIFY configuration option enabled. In addition, fanotify
581 permission handling is available only if the CONFIG_FANOTIFY_AC‐
582 CESS_PERMISSIONS configuration option is enabled.
583 Limitations and caveats
585 Fanotify reports only events that a user-space program triggers through
586 the filesystem API. As a result, it does not catch remote events that
587 occur on network filesystems.
588 The fanotify API does not report file accesses and modifications that
590 may occur because of mmap(2), msync(2), and munmap(2).
591 Events for directories are created only if the directory itself is
593 opened, read, and closed. Adding, removing, or changing children of a
594 marked directory does not create events for the monitored directory it‐
595 self.
596 Fanotify monitoring of directories is not recursive: to monitor subdi‐
598 rectories under a directory, additional marks must be created. The
599 FAN_CREATE event can be used for detecting when a subdirectory has been
600 created under a marked directory. An additional mark must then be set
601 on the newly created subdirectory. This approach is racy, because it
602 can lose events that occurred inside the newly created subdirectory,
603 before a mark is added on that subdirectory. Monitoring mounts offers
604 the capability to monitor a whole directory tree in a race-free manner.
605 Monitoring filesystems offers the capability to monitor changes made
606 from any mount of a filesystem instance in a race-free manner.
607 The event queue can overflow. In this case, events are lost.
609
611 Before Linux 3.19, fallocate(2) did not generate fanotify events.
612 Since Linux 3.19, calls to fallocate(2) generate FAN_MODIFY events.
613 As of Linux 3.17, the following bugs exist:
615 • On Linux, a filesystem object may be accessible through multiple
617 paths, for example, a part of a filesystem may be remounted using
618 the --bind option of mount(8). A listener that marked a mount will
619 be notified only of events that were triggered for a filesystem ob‐
620 ject using the same mount. Any other event will pass unnoticed.
621 • When an event is generated, no check is made to see whether the user
623 ID of the receiving process has authorization to read or write the
624 file before passing a file descriptor for that file. This poses a
625 security risk, when the CAP_SYS_ADMIN capability is set for programs
626 executed by unprivileged users.
627 • If a call to read(2) processes multiple events from the fanotify
629 queue and an error occurs, the return value will be the total length
630 of the events successfully copied to the user-space buffer before
631 the error occurred. The return value will not be -1, and errno will
632 not be set. Thus, the reading application has no way to detect the
633 error.
634
636 The two example programs below demonstrate the usage of the fanotify
637 API.
638 Example program: fanotify_example.c
640 The first program is an example of fanotify being used with its event
641 object information passed in the form of a file descriptor. The pro‐
642 gram marks the mount passed as a command-line argument and waits for
643 events of type FAN_OPEN_PERM and FAN_CLOSE_WRITE. When a permission
644 event occurs, a FAN_ALLOW response is given.
645 The following shell session shows an example of running this program.
647 This session involved editing the file /home/user/temp/notes. Before
648 the file was opened, a FAN_OPEN_PERM event occurred. After the file
649 was closed, a FAN_CLOSE_WRITE event occurred. Execution of the program
650 ends when the user presses the ENTER key.
651 # ./fanotify_example /home
653 Press enter key to terminate.
654 Listening for events.
655 FAN_OPEN_PERM: File /home/user/temp/notes
656 FAN_CLOSE_WRITE: File /home/user/temp/notes
657 Listening for events stopped.
659 Program source: fanotify_example.c
661 #define _GNU_SOURCE /* Needed to get O_LARGEFILE definition */
663 #include <errno.h>
664 #include <fcntl.h>
665 #include <limits.h>
666 #include <poll.h>
667 #include <stdio.h>
668 #include <stdlib.h>
669 #include <sys/fanotify.h>
670 #include <unistd.h>
671 /* Read all available fanotify events from the file descriptor 'fd'. */
673 static void
675 handle_events(int fd)
676 {
677 const struct fanotify_event_metadata *metadata;
678 struct fanotify_event_metadata buf[200];
679 ssize_t len;
680 char path[PATH_MAX];
681 ssize_t path_len;
682 char procfd_path[PATH_MAX];
683 struct fanotify_response response;
684 /* Loop while events can be read from fanotify file descriptor. */
686 for (;;) {
688 /* Read some events. */
690 len = read(fd, buf, sizeof(buf));
692 if (len == -1 && errno != EAGAIN) {
693 perror("read");
694 exit(EXIT_FAILURE);
695 }
696 /* Check if end of available data reached. */
698 if (len <= 0)
700 break;
701 /* Point to the first event in the buffer. */
703 metadata = buf;
705 /* Loop over all events in the buffer. */
707 while (FAN_EVENT_OK(metadata, len)) {
709 /* Check that run-time and compile-time structures match. */
711 if (metadata->vers != FANOTIFY_METADATA_VERSION) {
713 fprintf(stderr,
714 "Mismatch of fanotify metadata version.\n");
715 exit(EXIT_FAILURE);
716 }
717 /* metadata->fd contains either FAN_NOFD, indicating a
719 queue overflow, or a file descriptor (a nonnegative
720 integer). Here, we simply ignore queue overflow. */
721 if (metadata->fd >= 0) {
723 /* Handle open permission event. */
725 if (metadata->mask & FAN_OPEN_PERM) {
727 printf("FAN_OPEN_PERM: ");
728 /* Allow file to be opened. */
730 response.fd = metadata->fd;
732 response.response = FAN_ALLOW;
733 write(fd, &response, sizeof(response));
734 }
735 /* Handle closing of writable file event. */
737 if (metadata->mask & FAN_CLOSE_WRITE)
739 printf("FAN_CLOSE_WRITE: ");
740 /* Retrieve and print pathname of the accessed file. */
742 snprintf(procfd_path, sizeof(procfd_path),
744 "/proc/self/fd/%d", metadata->fd);
745 path_len = readlink(procfd_path, path,
746 sizeof(path) - 1);
747 if (path_len == -1) {
748 perror("readlink");
749 exit(EXIT_FAILURE);
750 }
751 path[path_len] = '\0';
753 printf("File %s\n", path);
754 /* Close the file descriptor of the event. */
756 close(metadata->fd);
758 }
759 /* Advance to next event. */
761 metadata = FAN_EVENT_NEXT(metadata, len);
763 }
764 }
765 }
766 int
768 main(int argc, char *argv[])
769 {
770 char buf;
771 int fd, poll_num;
772 nfds_t nfds;
773 struct pollfd fds[2];
774 /* Check mount point is supplied. */
776 if (argc != 2) {
778 fprintf(stderr, "Usage: %s MOUNT\n", argv[0]);
779 exit(EXIT_FAILURE);
780 }
781 printf("Press enter key to terminate.\n");
783 /* Create the file descriptor for accessing the fanotify API. */
785 fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK,
787 O_RDONLY | O_LARGEFILE);
788 if (fd == -1) {
789 perror("fanotify_init");
790 exit(EXIT_FAILURE);
791 }
792 /* Mark the mount for:
794 - permission events before opening files
795 - notification events after closing a write-enabled
796 file descriptor. */
797 if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT,
799 FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD,
800 argv[1]) == -1) {
801 perror("fanotify_mark");
802 exit(EXIT_FAILURE);
803 }
804 /* Prepare for polling. */
806 nfds = 2;
808 fds[0].fd = STDIN_FILENO; /* Console input */
810 fds[0].events = POLLIN;
811 fds[1].fd = fd; /* Fanotify input */
813 fds[1].events = POLLIN;
814 /* This is the loop to wait for incoming events. */
816 printf("Listening for events.\n");
818 while (1) {
820 poll_num = poll(fds, nfds, -1);
821 if (poll_num == -1) {
822 if (errno == EINTR) /* Interrupted by a signal */
823 continue; /* Restart poll() */
824 perror("poll"); /* Unexpected error */
826 exit(EXIT_FAILURE);
827 }
828 if (poll_num > 0) {
830 if (fds[0].revents & POLLIN) {
831 /* Console input is available: empty stdin and quit. */
833 while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\n')
835 continue;
836 break;
837 }
838 if (fds[1].revents & POLLIN) {
840 /* Fanotify events are available. */
842 handle_events(fd);
844 }
845 }
846 }
847 printf("Listening for events stopped.\n");
849 exit(EXIT_SUCCESS);
850 }
851 Example program: fanotify_fid.c
853 The second program is an example of fanotify being used with a group
854 that identifies objects by file handles. The program marks the
855 filesystem object that is passed as a command-line argument and waits
856 until an event of type FAN_CREATE has occurred. The event mask indi‐
857 cates which type of filesystem object—either a file or a directory—was
858 created. Once all events have been read from the buffer and processed
859 accordingly, the program simply terminates.
860 The following shell sessions show two different invocations of this
862 program, with different actions performed on a watched object.
863 The first session shows a mark being placed on /home/user. This is
865 followed by the creation of a regular file, /home/user/testfile.txt.
866 This results in a FAN_CREATE event being generated and reported against
867 the file's parent watched directory object and with the created file
868 name. Program execution ends once all events captured within the buf‐
869 fer have been processed.
870 # ./fanotify_fid /home/user
872 Listening for events.
873 FAN_CREATE (file created):
874 Directory /home/user has been modified.
875 Entry 'testfile.txt' is not a subdirectory.
876 All events processed successfully. Program exiting.
877 $ touch /home/user/testfile.txt # In another terminal
879 The second session shows a mark being placed on /home/user. This is
881 followed by the creation of a directory, /home/user/testdir. This spe‐
882 cific action results in a FAN_CREATE event being generated and is re‐
883 ported with the FAN_ONDIR flag set and with the created directory name.
884 # ./fanotify_fid /home/user
886 Listening for events.
887 FAN_CREATE | FAN_ONDIR (subdirectory created):
888 Directory /home/user has been modified.
889 Entry 'testdir' is a subdirectory.
890 All events processed successfully. Program exiting.
891 $ mkdir -p /home/user/testdir # In another terminal
893 Program source: fanotify_fid.c
895 #define _GNU_SOURCE
897 #include <errno.h>
898 #include <fcntl.h>
899 #include <limits.h>
900 #include <stdio.h>
901 #include <stdlib.h>
902 #include <sys/types.h>
903 #include <sys/stat.h>
904 #include <sys/fanotify.h>
905 #include <unistd.h>
906 #define BUF_SIZE 256
908 int
910 main(int argc, char *argv[])
911 {
912 int fd, ret, event_fd, mount_fd;
913 ssize_t len, path_len;
914 char path[PATH_MAX];
915 char procfd_path[PATH_MAX];
916 char events_buf[BUF_SIZE];
917 struct file_handle *file_handle;
918 struct fanotify_event_metadata *metadata;
919 struct fanotify_event_info_fid *fid;
920 const char *file_name;
921 struct stat sb;
922 if (argc != 2) {
924 fprintf(stderr, "Invalid number of command line arguments.\n");
925 exit(EXIT_FAILURE);
926 }
927 mount_fd = open(argv[1], O_DIRECTORY | O_RDONLY);
929 if (mount_fd == -1) {
930 perror(argv[1]);
931 exit(EXIT_FAILURE);
932 }
933 /* Create an fanotify file descriptor with FAN_REPORT_DFID_NAME as
935 a flag so that program can receive fid events with directory
936 entry name. */
937 fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME, 0);
939 if (fd == -1) {
940 perror("fanotify_init");
941 exit(EXIT_FAILURE);
942 }
943 /* Place a mark on the filesystem object supplied in argv[1]. */
945 ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
947 FAN_CREATE | FAN_ONDIR,
948 AT_FDCWD, argv[1]);
949 if (ret == -1) {
950 perror("fanotify_mark");
951 exit(EXIT_FAILURE);
952 }
953 printf("Listening for events.\n");
955 /* Read events from the event queue into a buffer. */
957 len = read(fd, events_buf, sizeof(events_buf));
959 if (len == -1 && errno != EAGAIN) {
960 perror("read");
961 exit(EXIT_FAILURE);
962 }
963 /* Process all events within the buffer. */
965 for (metadata = (struct fanotify_event_metadata *) events_buf;
967 FAN_EVENT_OK(metadata, len);
968 metadata = FAN_EVENT_NEXT(metadata, len)) {
969 fid = (struct fanotify_event_info_fid *) (metadata + 1);
970 file_handle = (struct file_handle *) fid->handle;
971 /* Ensure that the event info is of the correct type. */
973 if (fid->hdr.info_type == FAN_EVENT_INFO_TYPE_FID ||
975 fid->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID) {
976 file_name = NULL;
977 } else if (fid->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
978 file_name = file_handle->f_handle +
979 file_handle->handle_bytes;
980 } else {
981 fprintf(stderr, "Received unexpected event info type.\n");
982 exit(EXIT_FAILURE);
983 }
984 if (metadata->mask == FAN_CREATE)
986 printf("FAN_CREATE (file created):\n");
987 if (metadata->mask == (FAN_CREATE | FAN_ONDIR))
989 printf("FAN_CREATE | FAN_ONDIR (subdirectory created):\n");
990 /* metadata->fd is set to FAN_NOFD when the group identifies
992 objects by file handles. To obtain a file descriptor for
993 the file object corresponding to an event you can use the
994 struct file_handle that's provided within the
995 fanotify_event_info_fid in conjunction with the
996 open_by_handle_at(2) system call. A check for ESTALE is
997 done to accommodate for the situation where the file handle
998 for the object was deleted prior to this system call. */
999 event_fd = open_by_handle_at(mount_fd, file_handle, O_RDONLY);
1001 if (event_fd == -1) {
1002 if (errno == ESTALE) {
1003 printf("File handle is no longer valid. "
1004 "File has been deleted\n");
1005 continue;
1006 } else {
1007 perror("open_by_handle_at");
1008 exit(EXIT_FAILURE);
1009 }
1010 }
1011 snprintf(procfd_path, sizeof(procfd_path), "/proc/self/fd/%d",
1013 event_fd);
1014 /* Retrieve and print the path of the modified dentry. */
1016 path_len = readlink(procfd_path, path, sizeof(path) - 1);
1018 if (path_len == -1) {
1019 perror("readlink");
1020 exit(EXIT_FAILURE);
1021 }
1022 path[path_len] = '\0';
1024 printf("\tDirectory '%s' has been modified.\n", path);
1025 if (file_name) {
1027 ret = fstatat(event_fd, file_name, &sb, 0);
1028 if (ret == -1) {
1029 if (errno != ENOENT) {
1030 perror("fstatat");
1031 exit(EXIT_FAILURE);
1032 }
1033 printf("\tEntry '%s' does not exist.\n", file_name);
1034 } else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
1035 printf("\tEntry '%s' is a subdirectory.\n", file_name);
1036 } else {
1037 printf("\tEntry '%s' is not a subdirectory.\n",
1038 file_name);
1039 }
1040 }
1041 /* Close associated file descriptor for this event. */
1043 close(event_fd);
1045 }
1046 printf("All events processed successfully. Program exiting.\n");
1048 exit(EXIT_SUCCESS);
1049 }
1050
1052 fanotify_init(2), fanotify_mark(2), inotify(7)
1053Linux man-pages 6.05 2023-05-03 fanotify(7)