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
148 .BR fanotify_init (2)
149 influences what data structures are returned to the event listener for each
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 .SS Example program: fanotify_example.c
684 The first program is an example of fanotify being
685 used with its event object information passed in the form of a file
687 The program marks the mount point passed as a command-line argument and
688 waits for events of type
691 .BR FAN_CLOSE_WRITE .
692 When a permission event occurs, a
696 The following shell session shows an example of
697 running this program.
698 This session involved editing the file
699 .IR /home/user/temp/notes .
700 Before the file was opened, a
703 After the file was closed, a
706 Execution of the program ends when the user presses the ENTER key.
710 # \fB./fanotify_example /home\fP
711 Press enter key to terminate.
712 Listening for events.
713 FAN_OPEN_PERM: File /home/user/temp/notes
714 FAN_CLOSE_WRITE: File /home/user/temp/notes
716 Listening for events stopped.
721 .SS Program source: fanotify_example.c
724 #define _GNU_SOURCE /* Needed to get O_LARGEFILE definition */
731 #include <sys/fanotify.h>
734 /* Read all available fanotify events from the file descriptor \(aqfd\(aq */
737 handle_events(int fd)
739 const struct fanotify_event_metadata *metadata;
740 struct fanotify_event_metadata buf[200];
744 char procfd_path[PATH_MAX];
745 struct fanotify_response response;
747 /* Loop while events can be read from fanotify file descriptor */
751 /* Read some events */
753 len = read(fd, (void *) &buf, sizeof(buf));
754 if (len == \-1 && errno != EAGAIN) {
759 /* Check if end of available data reached */
764 /* Point to the first event in the buffer */
768 /* Loop over all events in the buffer */
770 while (FAN_EVENT_OK(metadata, len)) {
772 /* Check that run\-time and compile\-time structures match */
774 if (metadata\->vers != FANOTIFY_METADATA_VERSION) {
776 "Mismatch of fanotify metadata version.\en");
780 /* metadata\->fd contains either FAN_NOFD, indicating a
781 queue overflow, or a file descriptor (a nonnegative
782 integer). Here, we simply ignore queue overflow. */
784 if (metadata\->fd >= 0) {
786 /* Handle open permission event */
788 if (metadata\->mask & FAN_OPEN_PERM) {
789 printf("FAN_OPEN_PERM: ");
791 /* Allow file to be opened */
793 response.fd = metadata\->fd;
794 response.response = FAN_ALLOW;
796 sizeof(struct fanotify_response));
799 /* Handle closing of writable file event */
801 if (metadata\->mask & FAN_CLOSE_WRITE)
802 printf("FAN_CLOSE_WRITE: ");
804 /* Retrieve and print pathname of the accessed file */
806 snprintf(procfd_path, sizeof(procfd_path),
807 "/proc/self/fd/%d", metadata\->fd);
808 path_len = readlink(procfd_path, path,
810 if (path_len == \-1) {
815 path[path_len] = \(aq\e0\(aq;
816 printf("File %s\en", path);
818 /* Close the file descriptor of the event */
820 close(metadata\->fd);
823 /* Advance to next event */
825 metadata = FAN_EVENT_NEXT(metadata, len);
831 main(int argc, char *argv[])
836 struct pollfd fds[2];
838 /* Check mount point is supplied */
841 fprintf(stderr, "Usage: %s MOUNT\en", argv[0]);
845 printf("Press enter key to terminate.\en");
847 /* Create the file descriptor for accessing the fanotify API */
849 fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK,
850 O_RDONLY | O_LARGEFILE);
852 perror("fanotify_init");
856 /* Mark the mount for:
857 \- permission events before opening files
858 \- notification events after closing a write\-enabled
861 if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT,
862 FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD,
864 perror("fanotify_mark");
868 /* Prepare for polling */
874 fds[0].fd = STDIN_FILENO;
875 fds[0].events = POLLIN;
880 fds[1].events = POLLIN;
882 /* This is the loop to wait for incoming events */
884 printf("Listening for events.\en");
887 poll_num = poll(fds, nfds, \-1);
888 if (poll_num == \-1) {
889 if (errno == EINTR) /* Interrupted by a signal */
890 continue; /* Restart poll() */
892 perror("poll"); /* Unexpected error */
897 if (fds[0].revents & POLLIN) {
899 /* Console input is available: empty stdin and quit */
901 while (read(STDIN_FILENO, &buf, 1) > 0 && buf != \(aq\en\(aq)
906 if (fds[1].revents & POLLIN) {
908 /* Fanotify events are available */
915 printf("Listening for events stopped.\en");
920 .SS Example program: fanotify_fid.c
921 The second program is an example of fanotify being used with
924 The program marks the filesystem object that is passed as
925 a command-line argument
926 and waits until an event of type
929 The event mask indicates which type of filesystem object\(emeither
930 a file or a directory\(emwas created".
931 Once all events have been read from the buffer and processed accordingly,
932 the program simply terminates.
934 The following shell sessions show two different invocations of
935 this program, with different actions performed on a watched object.
937 The first session shows a mark being placed on
939 This is followed by the creation of a regular file,
940 .IR /home/user/testfile.txt .
943 event being created and reported against the file's parent watched
945 Program execution ends once all events captured within the buffer have
947 Program execution ends once all events captured within the buffer are
952 # \fB./fanotify_fid /home/user\fP
953 Listening for events.
954 FAN_CREATE (file created): Directory /home/user has been modified.
955 All events processed successfully. Program exiting.
957 $ \fBtouch /home/user/testing\fP # In another terminal
961 The second session shows a mark being placed on
963 This is followed by the creation of a directory,
964 .IR /home/user/testdir .
965 This specific action results in the program producing a
973 # \fB./fanotify_fid /home/user\fP
974 Listening for events.
975 FAN_CREATE | FAN_ONDIR (subdirectory created):
976 Directory /home/user has been modified.
977 All events processed successfully. Program exiting.
979 $ \fBmkdir \-p /home/user/testing\fP # In another terminal
982 .SS Program source: fanotify_fid.c
991 #include <sys/types.h>
992 #include <sys/stat.h>
993 #include <sys/fanotify.h>
999 main(int argc, char **argv)
1001 int fd, ret, event_fd;
1002 ssize_t len, path_len;
1003 char path[PATH_MAX];
1004 char procfd_path[PATH_MAX];
1005 char events_buf[BUF_SIZE];
1006 struct file_handle *file_handle;
1007 struct fanotify_event_metadata *metadata;
1008 struct fanotify_event_info_fid *fid;
1011 fprintf(stderr, "Invalid number of command line arguments.\e\n");
1015 /* Create an fanotify file descriptor with FAN_REPORT_FID as a flag
1016 so that program can receive fid events. */
1018 fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_FID, 0);
1020 perror("fanotify_init");
1024 /* Place a mark on the filesystem object supplied in argv[1]. */
1026 ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
1027 FAN_CREATE | FAN_ONDIR,
1030 perror("fanotify_mark");
1034 printf("Listening for events.\e\n");
1036 /* Read events from the event queue into a buffer */
1038 len = read(fd, (void *) &events_buf, sizeof(events_buf));
1039 if (len == \-1 && errno != EAGAIN) {
1044 /* Process all events within the buffer */
1046 for (metadata = (struct fanotify_event_metadata *) events_buf;
1047 FAN_EVENT_OK(metadata, len);
1048 metadata = FAN_EVENT_NEXT(metadata, len)) {
1049 fid = (struct fanotify_event_info_fid *) (metadata + 1);
1050 file_handle = (struct file_handle *) fid->handle;
1052 /* Ensure that the event info is of the correct type */
1054 if (fid->hdr.info_type != FAN_EVENT_INFO_TYPE_FID) {
1055 fprintf(stderr, "Received unexpected event info type.\e\n");
1059 if (metadata->mask == FAN_CREATE)
1060 printf("FAN_CREATE (file created):");
1062 if (metadata->mask == FAN_CREATE | FAN_ONDIR)
1063 printf("FAN_CREATE | FAN_ONDIR (subdirectory created):");
1065 /* metadata->fd is set to FAN_NOFD when FAN_REPORT_FID is enabled.
1066 To obtain a file descriptor for the file object corresponding to
1067 an event you can use the struct file_handle that\(aqs provided
1068 within the fanotify_event_info_fid in conjunction with the
1069 open_by_handle_at(2) system call. A check for ESTALE is done
1070 to accommodate for the situation where the file handle for the
1071 object was deleted prior to this system call. */
1073 event_fd = open_by_handle_at(AT_FDCWD, file_handle, O_RDONLY);
1075 if (errno == ESTALE) {
1076 printf("File handle is no longer valid. "
1077 "File has been deleted\e\n");
1080 perror("open_by_handle_at");
1085 snprintf(procfd_path, sizeof(procfd_path), "/proc/self/fd/%d",
1088 /* Retrieve and print the path of the modified dentry */
1090 path_len = readlink(procfd_path, path, sizeof(path) \- 1);
1091 if (path_len == \-1) {
1096 path[path_len] = \(aq\e\0\(aq;
1097 printf("\etDirectory \(aq%s\(aq has been modified.\e\n", path);
1099 /* Close associated file descriptor for this event */
1104 printf("All events processed successfully. Program exiting.\e\n");
1110 .BR fanotify_init (2),
1111 .BR fanotify_mark (2),