.\" 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 2015-05-07 "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
.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
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.
generate
.B FAN_MODIFY
events.
-
+.PP
As of Linux 3.17,
the following bugs exist:
.IP * 3
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>
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] = '\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 */
/* 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
+.EE
.SH SEE ALSO
.ad l
.BR fanotify_init (2),
projects / thirdparty / man-pages.git / blobdiff