.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
-.TH FANOTIFY 7 2014-05-21 "Linux" "Linux Programmer's Manual"
+.TH FANOTIFY 7 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
fanotify \- monitoring filesystem events
.SH DESCRIPTION
(See
.BR inotify (7)
for details of an API that does notify those events.)
-
+.PP
Additional capabilities compared to the
.BR inotify (7)
API include the ability to monitor all of the objects
in a mounted filesystem,
the ability to make access permission decisions, and the
possibility to read or modify files before access by other applications.
-
+.PP
The following system calls are used with this API:
.BR fanotify_init (2),
.BR fanotify_mark (2),
and returns a file descriptor referring to it.
.PP
An fanotify notification group is a kernel-internal object that holds
-a list of files, directories, and mount points for which events shall be
-created.
+a list of files, directories, filesystems, and mount points for which
+events shall be created.
.PP
For each entry in an fanotify notification group, two bit masks exist: the
.I mark
mask.
The mark mask defines file activities for which an event shall be created.
The ignore mask defines activities for which no event shall be generated.
-Having these two types of masks permits a mount point or directory to be
-marked for receiving events, while at the same time ignoring events for
-specific objects under that mount point or directory.
+Having these two types of masks permits a filesystem, mount point, or
+directory to be marked for receiving events, while at the same time
+ignoring events for specific objects under a mount point or directory.
.PP
The
.BR fanotify_mark (2)
-system call adds a file, directory, or mount to a notification group
-and specifies which events
+system call adds a file, directory, filesystem or mount point to a
+notification group and specifies which events
shall be reported (or ignored), or removes or modifies such an entry.
.PP
A possible usage of the ignore mask is for a file cache.
.PP
The entries in the fanotify notification groups refer to files and
directories via their inode number and to mounts via their mount ID.
-If files or directories are renamed or moved,
+If files or directories are renamed or moved within the same mount,
the respective entries survive.
-If files or directories are deleted or mounts are unmounted,
-the corresponding entries are deleted.
+If files or directories are deleted or moved to another mount or if
+filesystems or mounts are unmounted, the corresponding entries are deleted.
.SS The event queue
As events occur on the filesystem objects monitored by a notification group,
the fanotify system generates events that are collected in a queue.
from the fanotify file descriptor
returned by
.BR fanotify_init (2).
-
+.PP
Two types of events are generated:
.I notification
events and
whether permission for a file access shall be granted.
For these events, the recipient must write a response which decides whether
access is granted or not.
-
+.PP
An event is removed from the event queue of the fanotify group
when it has been read.
Permission events that have been read are kept in an internal list of the
until either a file event occurs or the call is interrupted by a signal
(see
.BR signal (7)).
-
+.PP
After a successful
.BR read (2),
the read buffer contains one or more of the following structures:
-
+.PP
.in +4n
-.nf
+.EX
struct fanotify_event_metadata {
__u32 event_len;
__u8 vers;
__s32 fd;
__s32 pid;
};
-.fi
+.EE
.in
.PP
For performance reasons, it is recommended to use a large
buffer size (for example, 4096 bytes),
so that multiple events can be retrieved by a single
.BR read (2).
-
+.PP
The return value of
.BR read (2)
is the number of bytes placed in the buffer,
or \-1 in case of an error (but see BUGS).
-
+.PP
The fields of the
.I fanotify_event_metadata
structure are as follows:
This field holds a version number for the structure.
It must be compared to
.B FANOTIFY_METADATA_VERSION
-to verify that the structures returned at runtime match
+to verify that the structures returned at run time match
the structures defined at compile time.
In case of a mismatch, the application should abandon trying to use the
fanotify file descriptor.
directory using this file descriptor, no additional events will be created.
.TP
.I pid
-This is the ID of the process that caused the event.
+If flag
+.B FAN_REPORT_TID
+was set in
+.BR fanotify_init (2),
+this is the TID of the thread that caused the event.
+Otherwise, this the PID of the process that caused the event.
+.PP
A program listening to fanotify events can compare this PID
to the PID returned by
.BR getpid (2),
.B FAN_OPEN
A file or a directory was opened.
.TP
+.B FAN_OPEN_EXEC
+A file was opened with the intent to be executed.
+See NOTES in
+.BR fanotify_mark (2)
+for additional details.
+.TP
.B FAN_MODIFY
A file was modified.
.TP
An application wants to open a file or directory.
The reader must write a response that determines whether the permission to
open the filesystem object shall be granted.
+.TP
+.B FAN_OPEN_EXEC_PERM
+An application wants to open a file for execution.
+The reader must write a response that determines whether the permission to
+open the filesystem object for execution shall be granted.
+See NOTES in
+.BR fanotify_mark (2)
+for additional details.
.PP
To check for any close event, the following bit mask may be used:
.TP
.B FAN_CLOSE
A file was closed.
This is a synonym for:
-
+.IP
FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
.PP
The following macros are provided to iterate over a buffer containing
.IR meta ,
and reduces
.I len
-by the number of bytes in the the metadata structure that
+by the number of bytes in the metadata structure that
has been skipped over (i.e., it subtracts
.IR meta\->event_len
from
.BR write (2)
a structure of the following form to the
fanotify file descriptor:
-
+.PP
.in +4n
-.nf
+.EX
struct fanotify_response {
__s32 fd;
__u32 response;
};
-.fi
+.EE
.in
.PP
The fields of this structure are as follows:
.I fd
of process
.IR pid .
-See the kernel source file
-.I Documentation/filesystems/proc.txt
+See
+.BR proc (5)
for details.
.SH ERRORS
In addition to the usual errors for
.BR getrlimit (2).
.TP
.B ENFILE
-The system-wide limit on the number of open files has been reached.
+The system-wide limit on the total number of open files has been reached.
See
.I /proc/sys/fs/file-max
in
The fanotify API was introduced in version 2.6.36 of the Linux kernel and
enabled in version 2.6.37.
Fdinfo support was added in version 3.8.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
The fanotify API is Linux-specific.
.SH NOTES
The fanotify API is available only if the kernel was built with the
subdirectory has been created under a marked directory,
which makes recursive monitoring difficult.)
Monitoring mounts offers the capability to monitor a whole directory tree.
+Monitoring filesystems offers the capability to monitor changes made from
+any mount of a filesystem instance.
.PP
The event queue can overflow.
In this case, events are lost.
.SH BUGS
-As of Linux 3.15,
-the following bugs exists:
+Before Linux 3.19,
+.BR fallocate (2)
+did not generate fanotify events.
+Since Linux 3.19,
+.\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35
+calls to
+.BR fallocate (2)
+generate
+.B FAN_MODIFY
+events.
+.PP
+As of Linux 3.17,
+the following bugs exist:
.IP * 3
-.\" FIXME: A patch was proposed.
+On Linux, a filesystem object may be accessible through multiple paths,
+for example, a part of a filesystem may be remounted using the
+.IR \-\-bind
+option of
+.BR mount (8).
+A listener that marked a mount will be notified only of events that were
+triggered for a filesystem object using the same mount.
+Any other event will pass unnoticed.
+.IP *
+.\" FIXME . A patch was proposed.
When an event is generated,
no check is made to see whether the user ID of the
receiving process has authorization to read or write the file
The following program demonstrates the usage of the fanotify API.
It marks the mount point passed as a command-line argument
and waits for events of type
-.B FAN_PERM_OPEN
+.B FAN_OPEN_PERM
and
.BR FAN_CLOSE_WRITE .
When a permission event occurs, a
Execution of the program ends when the user presses the ENTER key.
.SS Example output
.in +4n
-.nf
+.EX
# ./fanotify_example /home
Press enter key to terminate.
Listening for events.
FAN_CLOSE_WRITE: File /home/user/temp/notes
Listening for events stopped.
-.fi
+.EE
.in
.SS Program source
-.nf
+\&
+.EX
#define _GNU_SOURCE /* Needed to get O_LARGEFILE definition */
#include <errno.h>
#include <fcntl.h>
handle_events(int fd)
{
const struct fanotify_event_metadata *metadata;
- char buf[4096];
+ struct fanotify_event_metadata buf[200];
ssize_t len;
char path[PATH_MAX];
ssize_t path_len;
/* Point to the first event in the buffer */
- metadata = (struct fanotify_event_metadata *) buf;
+ metadata = buf;
/* Loop over all events in the buffer */
if (metadata\->vers != FANOTIFY_METADATA_VERSION) {
fprintf(stderr,
- "Mismatch of fanotify metadata version.\\n");
+ "Mismatch of fanotify metadata version.\en");
exit(EXIT_FAILURE);
}
response.fd = metadata\->fd;
response.response = FAN_ALLOW;
write(fd, &response,
- sizeof(struct fanotify_response));
+ sizeof(struct fanotify_response));
}
/* Handle closing of writable file event */
exit(EXIT_FAILURE);
}
- path[path_len] = '\\0';
- printf("File %s\\n", path);
+ path[path_len] = '\e0';
+ printf("File %s\en", path);
/* Close the file descriptor of the event */
/* Check mount point is supplied */
if (argc != 2) {
- fprintf(stderr, "Usage: %s MOUNT\\n", argv[0]);
+ fprintf(stderr, "Usage: %s MOUNT\en", argv[0]);
exit(EXIT_FAILURE);
}
- printf("Press enter key to terminate.\\n");
+ printf("Press enter key to terminate.\en");
/* Create the file descriptor for accessing the fanotify API */
file descriptor */
if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT,
- FAN_OPEN_PERM | FAN_CLOSE_WRITE, \-1,
+ FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD,
argv[1]) == \-1) {
perror("fanotify_mark");
exit(EXIT_FAILURE);
/* This is the loop to wait for incoming events */
- printf("Listening for events.\\n");
+ printf("Listening for events.\en");
while (1) {
poll_num = poll(fds, nfds, \-1);
/* Console input is available: empty stdin and quit */
- while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\\n')
+ while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\en')
continue;
break;
}
}
}
- printf("Listening for events stopped.\\n");
+ printf("Listening for events stopped.\en");
exit(EXIT_SUCCESS);
}
-.fi
-.SH "SEE ALSO"
+.EE
+.SH SEE ALSO
.ad l
.BR fanotify_init (2),
.BR fanotify_mark (2),