.\" 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
events.
Notification events are merely informative
and require no action to be taken by
-the receiving application except for closing the file descriptor passed
-in the event (see below).
+the receiving application with the exception being that the file
+descriptor provided within a generic event must be closed.
+The closing of file descriptors for each event applies only to
+applications that have initialized fanotify without using
+.BR FAN_REPORT_FID
+(see below).
Permission events are requests to the receiving application to decide
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
+Depending on whether
+.BR FAN_REPORT_FID
+is supplied as one of the flags when calling
+.BR fanotify_init (2)
+determines what structure(s) are returned for an event within the read
+buffer.
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
+In the case where
+.BR FAN_REPORT_FID
+is supplied as one of the flags to
+.BR fanotify_init (2),
+you should also expect to receive the structure detailed below following
+the generic
+.I fanotify_event_metadata
+structure within the read buffer:
+.PP
+.in +4n
+.EX
+struct fanotify_event_info_fid {
+ struct fanotify_event_info_header hdr;
+ __kernel_fsid_t fsid;
+ unsigned char file_handle[0];
+};
+.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:
.I event_len
This is the length of the data for the current event and the offset
to the next event in the buffer.
-In the current implementation, the value of
+Without
+.BR FAN_REPORT_FID ,
+the value of
.I event_len
is always
.BR FAN_EVENT_METADATA_LEN .
-However, the API is designed to allow
-variable-length structures to be returned in the future.
+With
+.BR FAN_REPORT_FID ,
+.I event_len
+also includes the variable length file identifier.
.TP
.I vers
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.
This is an open file descriptor for the object being accessed, or
.B FAN_NOFD
if a queue overflow occurred.
+If the fanotify file descriptor has been initialized using
+.BR FAN_REPORT_FID ,
+applications should expect this value to be set to
+.B FAN_NOFD
+for each event that is received.
The file descriptor can be used to access the contents
of the monitored file or directory.
The reading application is responsible for closing this 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_ATTRIB
+A file or directory metadata was changed.
+.TP
+.B FAN_CREATE
+A child file or directory was created in a watched parent.
+.TP
+.B FAN_DELETE
+A child file or directory was deleted in a watched parent.
+.TP
+.B FAN_DELETE_SELF
+A watched file or directory was deleted.
+.TP
+.B FAN_MOVED_FROM
+A file or directory has been moved from a watched parent directory.
+.TP
+.B FAN_MOVED_TO
+A file or directory has been moved to a watched parent directory.
+.TP
+.B FAN_MOVE_SELF
+A watched file or directory was moved.
+.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
+To check for any move event, the following bit mask may be used:
+.TP
+.B FAN_MOVE
+A file or directory was moved.
+This is a synonym for:
+.IP
+ FAN_MOVED_FROM | FAN_MOVED_TO
+.PP
+The fields of the
+.I fanotify_event_info_fid
+structure are as follows:
+.TP
+.I hdr
+This is a structure of type
+.IR fanotify_event_info_header .
+It is a generic header that contains information used to describe
+additional information attached to the event.
+For example, when an fanotify file descriptor is created using
+.BR FAN_REPORT_FID ,
+the
+.I info_type
+field of this header is set to
+.BR FAN_EVENT_INFO_TYPE_FID .
+Event listeners can use this field to check that the additional
+information received for an event is of the correct type.
+Additionally, the
+.I fanotify_event_info_header
+also contains a
+.I len
+field.
+In the current implementation, the value of
+.I len
+is always (event_len \- FAN_EVENT_METADATA_LEN).
+.TP
+.I fsid
+This is a unique identifier of the filesystem containing the object
+associated with the event.
+It is a structure of type
+.I __kernel_fsid_t
+and contains the same value as
+.I f_fsid
+when calling
+.BR statfs (2).
+.TP
+.I file_handle
+This is a variable length structure of type
+.IR file_handle .
+It is an opaque handle that corresponds to a specified object on a
+filesystem as returned by
+.BR name_to_handle_at (2).
+It can be used to uniquely identify a file on a filesystem and can be
+passed as an argument to
+.BR open_by_handle_at (2).
+Note that for directory entry events, such as
+.BR FAN_CREATE ,
+.BR FAN_DELETE ,
+and
+.BR FAN_MOVE ,
+the
+.IR file_handle
+describes the modified directory and not the created/deleted/moved child
+object.
+The events
+.BR FAN_ATTRIB ,
+.BR FAN_DELETE_SELF ,
+and
+.BR FAN_MOVE_SELF
+will carry the
+.IR file_handle
+information for the child object if the child object is being watched.
+.PP
The following macros are provided to iterate over a buffer containing
fanotify event metadata returned by a
.BR read (2)
.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
+.I /proc/sys/fs/file\-max
in
.BR proc (5).
.TP
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,
+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
will not be set.
Thus, the reading application has no way to detect the error.
.SH EXAMPLE
-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
+The two example programs below demonstrate the usage of the fanotify API.
+.SS Example program: fanotify_example.c
+The first program is an example of fanotify being
+used with its event object information passed in the form of a file
+descriptor.
+The program marks the mount point passed as a command-line argument and
+waits for events of type
+.B FAN_OPEN_PERM
and
.BR FAN_CLOSE_WRITE .
When a permission event occurs, a
.B FAN_ALLOW
response is given.
.PP
-The following output was recorded while editing the file
+The following shell session shows an example of
+running this program.
+This session involved editing the file
.IR /home/user/temp/notes .
Before the file was opened, a
.B FAN_OPEN_PERM
.B FAN_CLOSE_WRITE
event occurred.
Execution of the program ends when the user presses the ENTER key.
-.SS Example output
+.PP
.in +4n
-.nf
-# ./fanotify_example /home
+.EX
+# \fB./fanotify_example /home\fP
Press enter key to terminate.
Listening for events.
FAN_OPEN_PERM: File /home/user/temp/notes
FAN_CLOSE_WRITE: File /home/user/temp/notes
Listening for events stopped.
-.fi
+.EE
.in
-.SS Program source
-.nf
+.EE
+.in
+.SS Program source: fanotify_example.c
+\&
+.EX
#define _GNU_SOURCE /* Needed to get O_LARGEFILE definition */
#include <errno.h>
#include <fcntl.h>
#include <sys/fanotify.h>
#include <unistd.h>
-/* Read all available fanotify events from the file descriptor 'fd' */
+/* Read all available fanotify events from the file descriptor \(aqfd\(aq */
static void
handle_events(int fd)
/* Loop while events can be read from fanotify file descriptor */
- for(;;) {
+ for (;;) {
/* Read some events */
if (metadata\->vers != FANOTIFY_METADATA_VERSION) {
fprintf(stderr,
- "Mismatch of fanotify metadata version.\\n");
+ "Mismatch of fanotify metadata version.\en");
exit(EXIT_FAILURE);
}
exit(EXIT_FAILURE);
}
- path[path_len] = '\\0';
- printf("File %s\\n", path);
+ path[path_len] = \(aq\e0\(aq;
+ 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 != \(aq\en\(aq)
continue;
break;
}
}
}
- printf("Listening for events stopped.\\n");
+ printf("Listening for events stopped.\en");
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\"
+.SS Example program: fanotify_fid.c
+The second program is an example of fanotify being used with
+.B FAN_REPORT_FID
+enabled.
+The program marks the filesystem object that is passed as
+a command-line argument
+and waits until an event of type
+.B FAN_CREATE
+has occurred.
+The event mask indicates which type of filesystem object\(emeither
+a file or a directory\(emwas created".
+Once all events have been read from the buffer and processed accordingly,
+the program simply terminates.
+.PP
+The following shell sessions show two different invocations of
+this program, with different actions performed on a watched object.
+.PP
+The first session shows a mark being placed on
+.IR /home/user .
+This is followed by the creation of a regular file,
+.IR /home/user/testfile.txt .
+This results in a
+.B FAN_CREATE
+event being created and reported against the file's parent watched
+directory object.
+Program execution ends once all events captured within the buffer have
+been processed.
+Program execution ends once all events captured within the buffer are
+processed.
+.PP
+.in +4n
+.EX
+# \fB./fanotify_fid /home/user\fP
+Listening for events.
+FAN_CREATE (file created): Directory /home/user has been modified.
+All events processed successfully. Program exiting.
+
+$ \fBtouch /home/user/testing\fP # In another terminal
+.EE
+.in
+.PP
+The second session shows a mark being placed on
+.IR /home/user .
+This is followed by the creation of a directory,
+.IR /home/user/testdir .
+This specific action results in the program producing a
+.B FAN_CREATE
+and
+.B FAN_ONDIR
+event.
+.PP
+.in +4n
+.EX
+# \fB./fanotify_fid /home/user\fP
+Listening for events.
+FAN_CREATE | FAN_ONDIR (subdirectory created):
+ Directory /home/user has been modified.
+All events processed successfully. Program exiting.
+
+$ \fBmkdir \-p /home/user/testing\fP # In another terminal
+.EE
+.in
+.SS Program source: fanotify_fid.c
+\&
+.EX
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <limits.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <sys/fanotify.h>
+#include <unistd.h>
+
+#define BUF_SIZE 256
+
+int
+main(int argc, char **argv)
+{
+ int fd, ret, event_fd;
+ ssize_t len, path_len;
+ char path[PATH_MAX];
+ char procfd_path[PATH_MAX];
+ char events_buf[BUF_SIZE];
+ struct file_handle *file_handle;
+ struct fanotify_event_metadata *metadata;
+ struct fanotify_event_info_fid *fid;
+
+ if (argc != 2) {
+ fprintf(stderr, "Invalid number of command line arguments.\e\n");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Create an fanotify file descriptor with FAN_REPORT_FID as a flag
+ so that program can receive fid events. */
+
+ fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_FID, 0);
+ if (fd == \-1) {
+ perror("fanotify_init");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Place a mark on the filesystem object supplied in argv[1]. */
+
+ ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
+ FAN_CREATE | FAN_ONDIR,
+ AT_FDCWD, argv[1]);
+ if (ret == \-1) {
+ perror("fanotify_mark");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Listening for events.\e\n");
+
+ /* Read events from the event queue into a buffer */
+
+ len = read(fd, (void *) &events_buf, sizeof(events_buf));
+ if (len == \-1 && errno != EAGAIN) {
+ perror("read");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Process all events within the buffer */
+
+ for (metadata = (struct fanotify_event_metadata *) events_buf;
+ FAN_EVENT_OK(metadata, len);
+ metadata = FAN_EVENT_NEXT(metadata, len)) {
+ fid = (struct fanotify_event_info_fid *) (metadata + 1);
+ file_handle = (struct file_handle *) fid->handle;
+
+ /* Ensure that the event info is of the correct type */
+
+ if (fid->hdr.info_type != FAN_EVENT_INFO_TYPE_FID) {
+ fprintf(stderr, "Received unexpected event info type.\e\n");
+ exit(EXIT_FAILURE);
+ }
+
+ if (metadata->mask == FAN_CREATE)
+ printf("FAN_CREATE (file created):");
+
+ if (metadata->mask == FAN_CREATE | FAN_ONDIR)
+ printf("FAN_CREATE | FAN_ONDIR (subdirectory created):");
+
+ /* metadata->fd is set to FAN_NOFD when FAN_REPORT_FID is enabled.
+ To obtain a file descriptor for the file object corresponding to
+ an event you can use the struct file_handle that\(aqs provided
+ within the fanotify_event_info_fid in conjunction with the
+ open_by_handle_at(2) system call. A check for ESTALE is done
+ to accommodate for the situation where the file handle for the
+ object was deleted prior to this system call. */
+
+ event_fd = open_by_handle_at(AT_FDCWD, file_handle, O_RDONLY);
+ if (ret == \-1) {
+ if (errno == ESTALE) {
+ printf("File handle is no longer valid. "
+ "File has been deleted\e\n");
+ continue;
+ } else {
+ perror("open_by_handle_at");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ snprintf(procfd_path, sizeof(procfd_path), "/proc/self/fd/%d",
+ event_fd);
+
+ /* Retrieve and print the path of the modified dentry */
+
+ path_len = readlink(procfd_path, path, sizeof(path) \- 1);
+ if (path_len == \-1) {
+ perror("readlink");
+ exit(EXIT_FAILURE);
+ }
+
+ path[path_len] = \(aq\e\0\(aq;
+ printf("\etDirectory \(aq%s\(aq has been modified.\e\n", path);
+
+ /* Close associated file descriptor for this event */
+
+ close(event_fd);
+ }
+
+ printf("All events processed successfully. Program exiting.\e\n");
exit(EXIT_SUCCESS);
}
-.fi
-.SH "SEE ALSO"
+.EE
+.SH SEE ALSO
.ad l
.BR fanotify_init (2),
.BR fanotify_mark (2),
projects / thirdparty / man-pages.git / blobdiff