1 .\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
2 .\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of
10 .\" this manual under the conditions for verbatim copying, provided that
11 .\" the entire resulting derived work is distributed under the terms of
12 .\" a permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume.
16 .\" no responsibility for errors or omissions, or for damages resulting.
17 .\" from the use of the information contained herein. The author(s) may.
18 .\" not have taken the same level of care in the production of this.
19 .\" manual, which is licensed free of charge, as they might when working.
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH FANOTIFY 7 2019-03-06 "Linux" "Linux Programmer's Manual"
27 fanotify \- monitoring filesystem events
29 The fanotify API provides notification and interception of
31 Use cases include virus scanning and hierarchical storage management.
32 Currently, only a limited set of events is supported.
33 In particular, there is no support for create, delete, and move events.
36 for details of an API that does notify those events.)
38 Additional capabilities compared to the
40 API include the ability to monitor all of the objects
41 in a mounted filesystem,
42 the ability to make access permission decisions, and the
43 possibility to read or modify files before access by other applications.
45 The following system calls are used with this API:
46 .BR fanotify_init (2),
47 .BR fanotify_mark (2),
52 .SS fanotify_init(), fanotify_mark(), and notification groups
55 system call creates and initializes an fanotify notification group
56 and returns a file descriptor referring to it.
58 An fanotify notification group is a kernel-internal object that holds
59 a list of files, directories, filesystems, and mount points for which
60 events shall be created.
62 For each entry in an fanotify notification group, two bit masks exist: the
67 The mark mask defines file activities for which an event shall be created.
68 The ignore mask defines activities for which no event shall be generated.
69 Having these two types of masks permits a filesystem, mount point, or
70 directory to be marked for receiving events, while at the same time
71 ignoring events for specific objects under a mount point or directory.
75 system call adds a file, directory, filesystem or mount point to a
76 notification group and specifies which events
77 shall be reported (or ignored), or removes or modifies such an entry.
79 A possible usage of the ignore mask is for a file cache.
80 Events of interest for a file cache are modification of a file and closing
82 Hence, the cached directory or mount point is to be marked to receive these
84 After receiving the first event informing that a file has been modified,
85 the corresponding cache entry will be invalidated.
86 No further modification events for this file are of interest until the file
88 Hence, the modify event can be added to the ignore mask.
89 Upon receiving the close event, the modify event can be removed from the
90 ignore mask and the file cache entry can be updated.
92 The entries in the fanotify notification groups refer to files and
93 directories via their inode number and to mounts via their mount ID.
94 If files or directories are renamed or moved within the same mount,
95 the respective entries survive.
96 If files or directories are deleted or moved to another mount or if
97 filesystems or mounts are unmounted, the corresponding entries are deleted.
99 As events occur on the filesystem objects monitored by a notification group,
100 the fanotify system generates events that are collected in a queue.
101 These events can then be read (using
104 from the fanotify file descriptor
106 .BR fanotify_init (2).
108 Two types of events are generated:
113 Notification events are merely informative
114 and require no action to be taken by
115 the receiving application with the exception being that the file
116 descriptor provided within a generic event must be closed.
117 The closing of file descriptors for each event applies only to
118 applications that have initialized fanotify without using
121 Permission events are requests to the receiving application to decide
122 whether permission for a file access shall be granted.
123 For these events, the recipient must write a response which decides whether
124 access is granted or not.
126 An event is removed from the event queue of the fanotify group
127 when it has been read.
128 Permission events that have been read are kept in an internal list of the
129 fanotify group until either a permission decision has been taken by
130 writing to the fanotify file descriptor or the fanotify file descriptor
132 .SS Reading fanotify events
135 for the file descriptor returned by
136 .BR fanotify_init (2)
139 is not specified in the call to
140 .BR fanotify_init (2))
141 until either a file event occurs or the call is interrupted by a signal
147 is supplied as one of the flags when calling
148 .BR fanotify_init (2)
149 determines what structure(s) are returned for an event within the read
153 the read buffer contains one or more of the following structures:
157 struct fanotify_event_metadata {
171 is supplied as one of the flags to
172 .BR fanotify_init (2),
173 you should also expect to receive the structure detailed below following
175 .I fanotify_event_metadata
176 structure within the read buffer:
180 struct fanotify_event_info_fid {
181 struct fanotify_event_info_header hdr;
182 __kernel_fsid_t fsid;
183 unsigned char file_handle[0];
188 For performance reasons, it is recommended to use a large
189 buffer size (for example, 4096 bytes),
190 so that multiple events can be retrieved by a single
195 is the number of bytes placed in the buffer,
196 or \-1 in case of an error (but see BUGS).
199 .I fanotify_event_metadata
200 structure are as follows:
203 This is the length of the data for the current event and the offset
204 to the next event in the buffer.
210 .BR FAN_EVENT_METADATA_LEN .
214 also includes the variable length file identifier.
217 This field holds a version number for the structure.
218 It must be compared to
219 .B FANOTIFY_METADATA_VERSION
220 to verify that the structures returned at run time match
221 the structures defined at compile time.
222 In case of a mismatch, the application should abandon trying to use the
223 fanotify file descriptor.
226 This field is not used.
229 This is the length of the structure.
230 The field was introduced to facilitate the implementation of
231 optional headers per event type.
232 No such optional headers exist in the current implementation.
235 This is a bit mask describing the event (see below).
238 This is an open file descriptor for the object being accessed, or
240 if a queue overflow occurred.
241 If the fanotify file descriptor has been initialized using
243 applications should expect this value to be set to
245 for each event that is received.
246 The file descriptor can be used to access the contents
247 of the monitored file or directory.
248 The reading application is responsible for closing this file descriptor.
251 .BR fanotify_init (2),
252 the caller may specify (via the
254 argument) various file status flags that are to be set
255 on the open file description that corresponds to this file descriptor.
256 In addition, the (kernel-internal)
258 file status flag is set on the open file description.
259 This flag suppresses fanotify event generation.
260 Hence, when the receiver of the fanotify event accesses the notified file or
261 directory using this file descriptor, no additional events will be created.
267 .BR fanotify_init (2),
268 this is the TID of the thread that caused the event.
269 Otherwise, this the PID of the process that caused the event.
271 A program listening to fanotify events can compare this PID
272 to the PID returned by
274 to determine whether the event is caused by the listener itself,
275 or is due to a file access by another process.
279 indicates which events have occurred for a single filesystem object.
280 Multiple bits may be set in this mask,
281 if more than one event occurred for the monitored filesystem object.
283 consecutive events for the same filesystem object and originating from the
284 same process may be merged into a single event, with the exception that two
285 permission events are never merged into one queue entry.
287 The bits that may appear in
292 A file or a directory (but see BUGS) was accessed (read).
295 A file or a directory was opened.
298 A file was opened with the intent to be executed.
300 .BR fanotify_mark (2)
301 for additional details.
304 A file or directory metadata was changed.
307 A child file or directory was created in a watched parent.
310 A child file or directory was deleted in a watched parent.
313 A watched file or directory was deleted.
316 A file or directory has been moved from a watched parent directory.
319 A file or directory has been moved to a watched parent directory.
322 A watched file or directory was moved.
328 A file that was opened for writing
335 A file or directory that was opened read-only
340 The event queue exceeded the limit of 16384 entries.
341 This limit can be overridden by specifying the
342 .BR FAN_UNLIMITED_QUEUE
344 .BR fanotify_init (2).
347 An application wants to read a file or directory, for example using
351 The reader must write a response (as described below)
352 that determines whether the permission to
353 access the filesystem object shall be granted.
356 An application wants to open a file or directory.
357 The reader must write a response that determines whether the permission to
358 open the filesystem object shall be granted.
360 .B FAN_OPEN_EXEC_PERM
361 An application wants to open a file for execution.
362 The reader must write a response that determines whether the permission to
363 open the filesystem object for execution shall be granted.
365 .BR fanotify_mark (2)
366 for additional details.
368 To check for any close event, the following bit mask may be used:
372 This is a synonym for:
374 FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
376 To check for any move event, the following bit mask may be used:
379 A file or directory was moved.
380 This is a synonym for:
382 FAN_MOVED_FROM | FAN_MOVED_TO
385 .I fanotify_event_info_fid
386 structure are as follows:
389 This is a structure of type
390 .IR fanotify_event_info_header .
391 It is a generic header that contains information used to describe
392 additional information attached to the event.
393 For example, when an fanotify file descriptor is created using
397 field of this header is set to
398 .BR FAN_EVENT_INFO_TYPE_FID .
399 Event listeners can use this field to check that the additional
400 information received for an event is of the correct type.
402 .I fanotify_event_info_header
406 In the current implementation, the value of
408 is always (event_len - FAN_EVENT_METADATA_LEN).
411 This is a unique identifier of the filesystem containing the object
412 associated with the event.
413 It is a structure of type
415 and contains the same value as
421 This is a variable length structure of type
423 It is an opaque handle that corresponds to a specified object on a
424 filesystem as returned by
425 .BR name_to_handle_at (2).
426 It can be used to uniquely identify a file on a filesystem and can be
427 passed as an argument to
428 .BR open_by_handle_at (2).
429 Note that for directory entry events, such as
436 describes the modified directory and not the created/deleted/moved child
440 .BR FAN_DELETE_SELF ,
445 information for the child object if the child object is being watched.
447 The following macros are provided to iterate over a buffer containing
448 fanotify event metadata returned by a
450 from an fanotify file descriptor:
452 .B FAN_EVENT_OK(meta, len)
453 This macro checks the remaining length
457 against the length of the metadata structure and the
459 field of the first metadata structure in the buffer.
461 .B FAN_EVENT_NEXT(meta, len)
462 This macro uses the length indicated in the
464 field of the metadata structure pointed to by
466 to calculate the address of the next metadata structure that follows
469 is the number of bytes of metadata that currently remain in the buffer.
470 The macro returns a pointer to the next metadata structure that follows
474 by the number of bytes in the metadata structure that
475 has been skipped over (i.e., it subtracts
480 In addition, there is:
482 .B FAN_EVENT_METADATA_LEN
483 This macro returns the size (in bytes) of the structure
484 .IR fanotify_event_metadata .
485 This is the minimum size (and currently the only size) of any event metadata.
487 .SS Monitoring an fanotify file descriptor for events
488 When an fanotify event occurs, the fanotify file descriptor indicates as
489 readable when passed to
494 .SS Dealing with permission events
495 For permission events, the application must
497 a structure of the following form to the
498 fanotify file descriptor:
502 struct fanotify_response {
509 The fields of this structure are as follows:
512 This is the file descriptor from the structure
513 .IR fanotify_event_metadata .
516 This field indicates whether or not the permission is to be granted.
517 Its value must be either
519 to allow the file operation or
521 to deny the file operation.
523 If access is denied, the requesting application call will receive an
526 .SS Closing the fanotify file descriptor
528 When all file descriptors referring to the fanotify notification group are
529 closed, the fanotify group is released and its resources
530 are freed for reuse by the kernel.
533 outstanding permission events will be set to allowed.
534 .SS /proc/[pid]/fdinfo
536 .I /proc/[pid]/fdinfo/[fd]
537 contains information about fanotify marks for file descriptor
545 In addition to the usual errors for
547 the following errors can occur when reading from the
548 fanotify file descriptor:
551 The buffer is too small to hold the event.
554 The per-process limit on the number of open files has been reached.
555 See the description of
561 The system-wide limit on the total number of open files has been reached.
563 .I /proc/sys/fs/file\-max
568 This error is returned by
576 argument when calling
577 .BR fanotify_init (2)
578 and an event occurred for a monitored file that is currently being executed.
580 In addition to the usual errors for
582 the following errors can occur when writing to the fanotify file descriptor:
585 Fanotify access permissions are not enabled in the kernel configuration
588 in the response structure is not valid.
593 in the response structure is not valid.
594 This may occur when a response for the permission event has already been
597 The fanotify API was introduced in version 2.6.36 of the Linux kernel and
598 enabled in version 2.6.37.
599 Fdinfo support was added in version 3.8.
601 The fanotify API is Linux-specific.
603 The fanotify API is available only if the kernel was built with the
605 configuration option enabled.
606 In addition, fanotify permission handling is available only if the
607 .B CONFIG_FANOTIFY_ACCESS_PERMISSIONS
608 configuration option is enabled.
609 .SS Limitations and caveats
610 Fanotify reports only events that a user-space program triggers through the
613 it does not catch remote events that occur on network filesystems.
615 The fanotify API does not report file accesses and modifications that
622 Events for directories are created only if the directory itself is opened,
624 Adding, removing, or changing children of a marked directory does not create
625 events for the monitored directory itself.
627 Fanotify monitoring of directories is not recursive:
628 to monitor subdirectories under a directory,
629 additional marks must be created.
630 (But note that the fanotify API provides no way of detecting when a
631 subdirectory has been created under a marked directory,
632 which makes recursive monitoring difficult.)
633 Monitoring mounts offers the capability to monitor a whole directory tree.
634 Monitoring filesystems offers the capability to monitor changes made from
635 any mount of a filesystem instance.
637 The event queue can overflow.
638 In this case, events are lost.
642 did not generate fanotify events.
644 .\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35
652 the following bugs exist:
654 On Linux, a filesystem object may be accessible through multiple paths,
655 for example, a part of a filesystem may be remounted using the
659 A listener that marked a mount will be notified only of events that were
660 triggered for a filesystem object using the same mount.
661 Any other event will pass unnoticed.
663 .\" FIXME . A patch was proposed.
664 When an event is generated,
665 no check is made to see whether the user ID of the
666 receiving process has authorization to read or write the file
667 before passing a file descriptor for that file.
668 This poses a security risk, when the
670 capability is set for programs executed by unprivileged users.
674 processes multiple events from the fanotify queue and an error occurs,
675 the return value will be the total length of the events successfully
676 copied to the user-space buffer before the error occurred.
677 The return value will not be \-1, and
680 Thus, the reading application has no way to detect the error.
682 The two example programs below demonstrate the usage of the fanotify API.
683 The first program (fanotify_example.c) is an example of fanotify being
684 used with its event object information passed in the form of a file
686 It marks the mount point passed as a command-line argument and waits for
690 .BR FAN_CLOSE_WRITE .
691 When a permission event occurs, a
695 The second program (fanotify_fid.c) is an example of fanotify being used
699 It attempts to mark the filesystem object that is passed as
700 a command-line argument
701 and waits until an event of type
704 Depending on whether a file or directory is created depends on what mask
705 is returned in the event mask.
706 Once all events have been read from the buffer and processed accordingly,
707 the program simply terminates.
709 The first example program output was captured from fanotify_example.
710 This session involved editing the file
711 .IR /home/user/temp/notes .
712 Before the file was opened, a
715 After the file was closed, a
718 Execution of the program ends when the user presses the ENTER key.
720 The second example program output was captured from fanotify_fid.
721 There are two discrete invocations of this program, with each invocation
722 accommodating a different action performed on a watched object.
723 This first session shows a mark being placed on
725 This is followed by a subsequent regular file
726 .IR /home/user/testfile.txt
730 event being created and reported against the file's parent watched
732 Program execution ends once all events captured within the buffer have
734 The second session shows a mark being placed on
736 This is followed by a directory
737 .IR /home/user/testdir
739 This specific action results in the program producing a
744 Program execution ends once all events captured within the buffer are
746 .SS Example output (fanotify_example.c)
749 # ./fanotify_example /home
750 Press enter key to terminate.
751 Listening for events.
752 FAN_OPEN_PERM: File /home/user/temp/notes
753 FAN_CLOSE_WRITE: File /home/user/temp/notes
755 Listening for events stopped.
757 .SS Example output (fanotify_fid.c)
760 # ./fanotify_fid /home/user
761 Listening for events.
762 FAN_CREATE (file created): Directory /home/user has been modified.
763 All events processed successfully. Program exiting.
765 $ touch /home/user/testing
769 # ./fanotify_fid /home/user
770 Listening for events.
771 FAN_CREATE | FAN_ONDIR (subdirectory created): Directory /home/user has been modified.
772 All events processed successfully. Program exiting.
774 $ mkdir -p /home/user/testing
777 .SS Program source: fanotify_example.c
780 #define _GNU_SOURCE /* Needed to get O_LARGEFILE definition */
787 #include <sys/fanotify.h>
790 /* Read all available fanotify events from the file descriptor 'fd' */
793 handle_events(int fd)
795 const struct fanotify_event_metadata *metadata;
796 struct fanotify_event_metadata buf[200];
800 char procfd_path[PATH_MAX];
801 struct fanotify_response response;
803 /* Loop while events can be read from fanotify file descriptor */
807 /* Read some events */
809 len = read(fd, (void *) &buf, sizeof(buf));
810 if (len == \-1 && errno != EAGAIN) {
815 /* Check if end of available data reached */
820 /* Point to the first event in the buffer */
824 /* Loop over all events in the buffer */
826 while (FAN_EVENT_OK(metadata, len)) {
828 /* Check that run\-time and compile\-time structures match */
830 if (metadata\->vers != FANOTIFY_METADATA_VERSION) {
832 "Mismatch of fanotify metadata version.\en");
836 /* metadata\->fd contains either FAN_NOFD, indicating a
837 queue overflow, or a file descriptor (a nonnegative
838 integer). Here, we simply ignore queue overflow. */
840 if (metadata\->fd >= 0) {
842 /* Handle open permission event */
844 if (metadata\->mask & FAN_OPEN_PERM) {
845 printf("FAN_OPEN_PERM: ");
847 /* Allow file to be opened */
849 response.fd = metadata\->fd;
850 response.response = FAN_ALLOW;
852 sizeof(struct fanotify_response));
855 /* Handle closing of writable file event */
857 if (metadata\->mask & FAN_CLOSE_WRITE)
858 printf("FAN_CLOSE_WRITE: ");
860 /* Retrieve and print pathname of the accessed file */
862 snprintf(procfd_path, sizeof(procfd_path),
863 "/proc/self/fd/%d", metadata\->fd);
864 path_len = readlink(procfd_path, path,
866 if (path_len == \-1) {
871 path[path_len] = '\e0';
872 printf("File %s\en", path);
874 /* Close the file descriptor of the event */
876 close(metadata\->fd);
879 /* Advance to next event */
881 metadata = FAN_EVENT_NEXT(metadata, len);
887 main(int argc, char *argv[])
892 struct pollfd fds[2];
894 /* Check mount point is supplied */
897 fprintf(stderr, "Usage: %s MOUNT\en", argv[0]);
901 printf("Press enter key to terminate.\en");
903 /* Create the file descriptor for accessing the fanotify API */
905 fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK,
906 O_RDONLY | O_LARGEFILE);
908 perror("fanotify_init");
912 /* Mark the mount for:
913 \- permission events before opening files
914 \- notification events after closing a write\-enabled
917 if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT,
918 FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD,
920 perror("fanotify_mark");
924 /* Prepare for polling */
930 fds[0].fd = STDIN_FILENO;
931 fds[0].events = POLLIN;
936 fds[1].events = POLLIN;
938 /* This is the loop to wait for incoming events */
940 printf("Listening for events.\en");
943 poll_num = poll(fds, nfds, \-1);
944 if (poll_num == \-1) {
945 if (errno == EINTR) /* Interrupted by a signal */
946 continue; /* Restart poll() */
948 perror("poll"); /* Unexpected error */
953 if (fds[0].revents & POLLIN) {
955 /* Console input is available: empty stdin and quit */
957 while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\en')
962 if (fds[1].revents & POLLIN) {
964 /* Fanotify events are available */
971 printf("Listening for events stopped.\en");
976 .SS Program source: fanotify_fid.c
985 #include <sys/types.h>
986 #include <sys/stat.h>
987 #include <sys/fanotify.h>
992 int main(int argc, char **argv)
994 int fd, ret, event_fd;
995 ssize_t len, path_len;
997 char procfd_path[PATH_MAX];
998 char events_buf[BUF_SIZE];
1000 struct file_handle *file_handle;
1001 struct fanotify_event_metadata *metadata;
1002 struct fanotify_event_info_fid *fid;
1005 fprintf(stderr, "Invalid number of command line arguments.\\n");
1009 /* Create an fanotify file descriptor with FAN_REPORT_FID as a flag
1010 so that program can receive fid events. */
1012 fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_FID, 0);
1014 perror("fanotify_init");
1018 /* Place a mark on the filesystem object supplied in argv[1]. */
1020 ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
1021 FAN_CREATE | FAN_ONDIR,
1024 perror("fanotify_mark");
1028 printf("Listening for events.\\n");
1030 /* Read events from the event queue into a buffer */
1032 len = read(fd, (void *) &events_buf, sizeof(events_buf));
1033 if (len == -1 && errno != EAGAIN) {
1038 /* Process all events within the buffer */
1040 for (metadata = (struct fanotify_event_metadata *) events_buf;
1041 FAN_EVENT_OK(metadata, len);
1042 metadata = FAN_EVENT_NEXT(metadata, len)) {
1043 fid = (struct fanotify_event_info_fid *) (metadata + 1);
1044 file_handle = (struct file_handle *) fid->handle;
1046 /* Ensure that the event info is of the correct type */
1048 if (fid->hdr.info_type != FAN_EVENT_INFO_TYPE_FID) {
1049 fprintf(stderr, "Received unexpected event info type.\\n");
1053 if (metadata->mask == FAN_CREATE)
1054 printf("FAN_CREATE (file created): ");
1056 if (metadata->mask == FAN_CREATE | FAN_ONDIR)
1057 printf("FAN_CREATE | FAN_ONDIR (subdirectory created): ");
1059 /* metadata->fd is set to FAN_NOFD when FAN_REPORT_FID is enabled.
1060 To obtain a file descriptor for the file object corresponding to
1061 an event you can use the struct file_handle that's provided
1062 within the fanotify_event_info_fid in conjunction with the
1063 open_by_handle_at(2) system call. A check for -ESTALE is done
1064 to accommodate for the situation where the file handle was
1065 deleted for the object prior to this system call. */
1067 event_fd = open_by_handle_at(AT_FDCWD, file_handle, O_RDONLY);
1068 if (ret == -1 && errno == ESTALE) {
1069 printf("File handle is no longer valid. File has been deleted\\n");
1071 } else if (ret == -1) {
1072 perror("open_by_handle_at");
1076 snprintf(procfd_path, sizeof(procfd_path), "/proc/self/fd/%d", event_fd);
1078 /* Retrieve and print the path of the modified dentry */
1080 path_len = readlink(procfd_path, path, sizeof(path) - 1);
1081 if (path_len == -1) {
1086 path[path_len] = '\\0';
1087 printf("Directory '%s' has been modified.\\n", path);
1089 /* Close associated file descriptor for this event */
1093 printf("All events processed successfully. Program exiting.\\n");
1099 .BR fanotify_init (2),
1100 .BR fanotify_mark (2),