Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1456 insertions, 0 deletions

diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
new file mode 100644
index 0000000..c08ce33
--- /dev/null
+++ b/man/man7/fanotify.7
@@ -0,0 +1,1456 @@
+.\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
+.\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.TH fanotify 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+fanotify \- monitoring filesystem events
+.SH DESCRIPTION
+The fanotify API provides notification and interception of
+filesystem events.
+Use cases include virus scanning and hierarchical storage management.
+In the original fanotify API, only a limited set of events was supported.
+In particular, there was no support for create, delete, and move events.
+The support for those events was added in Linux 5.1.
+(See
+.BR inotify (7)
+for details of an API that did notify those events pre Linux 5.1.)
+.P
+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.
+.P
+The following system calls are used with this API:
+.BR fanotify_init (2),
+.BR fanotify_mark (2),
+.BR read (2),
+.BR write (2),
+and
+.BR close (2).
+.SS fanotify_init(), fanotify_mark(), and notification groups
+The
+.BR fanotify_init (2)
+system call creates and initializes an fanotify notification group
+and returns a file descriptor referring to it.
+.P
+An fanotify notification group is a kernel-internal object that holds
+a list of files, directories, filesystems, and mounts for which
+events shall be created.
+.P
+For each entry in an fanotify notification group, two bit masks exist: the
+.I mark
+mask and the
+.I ignore
+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 filesystem, mount, or
+directory to be marked for receiving events, while at the same time
+ignoring events for specific objects under a mount or directory.
+.P
+The
+.BR fanotify_mark (2)
+system call adds a file, directory, filesystem, or mount to a
+notification group and specifies which events
+shall be reported (or ignored), or removes or modifies such an entry.
+.P
+A possible usage of the ignore mask is for a file cache.
+Events of interest for a file cache are modification of a file and closing
+of the same.
+Hence, the cached directory or mount is to be marked to receive these
+events.
+After receiving the first event informing that a file has been modified,
+the corresponding cache entry will be invalidated.
+No further modification events for this file are of interest until the file
+is closed.
+Hence, the modify event can be added to the ignore mask.
+Upon receiving the close event, the modify event can be removed from the
+ignore mask and the file cache entry can be updated.
+.P
+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 within the same mount,
+the respective entries survive.
+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.
+These events can then be read (using
+.BR read (2)
+or similar)
+from the fanotify file descriptor
+returned by
+.BR fanotify_init (2).
+.P
+Two types of events are generated:
+.I notification
+events and
+.I permission
+events.
+Notification events are merely informative and require no action to be taken
+by the receiving application with one exception: if a valid file descriptor
+is provided within a generic event, the file descriptor must be closed.
+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.
+.P
+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
+fanotify group until either a permission decision has been taken by
+writing to the fanotify file descriptor or the fanotify file descriptor
+is closed.
+.SS Reading fanotify events
+Calling
+.BR read (2)
+for the file descriptor returned by
+.BR fanotify_init (2)
+blocks (if the flag
+.B FAN_NONBLOCK
+is not specified in the call to
+.BR fanotify_init (2))
+until either a file event occurs or the call is interrupted by a signal
+(see
+.BR signal (7)).
+.P
+After a successful
+.BR read (2),
+the read buffer contains one or more of the following structures:
+.P
+.in +4n
+.EX
+struct fanotify_event_metadata {
+    __u32 event_len;
+    __u8 vers;
+    __u8 reserved;
+    __u16 metadata_len;
+    __aligned_u64 mask;
+    __s32 fd;
+    __s32 pid;
+};
+.EE
+.in
+.P
+Information records are
+supplemental pieces of information that
+may be provided alongside the generic
+.I fanotify_event_metadata
+structure.
+The
+.I flags
+passed to
+.BR fanotify_init (2)
+have influence over the type of information records that
+may be returned for an event.
+For example,
+if a notification group is initialized with
+.B FAN_REPORT_FID
+or
+.BR FAN_REPORT_DIR_FID ,
+then event listeners should also expect to receive a
+.I fanotify_event_info_fid
+structure alongside the
+.I fanotify_event_metadata
+structure,
+whereby file handles are used to
+identify filesystem objects
+rather than file descriptors.
+Information records may also be stacked,
+meaning that using the various
+.B FAN_REPORT_*
+flags in conjunction with one another is supported.
+In such cases,
+multiple information records can be returned for an event
+alongside the generic
+.I fanotify_event_metadata
+structure.
+For example,
+if a notification group is initialized with
+.B FAN_REPORT_TARGET_FID
+and
+.BR FAN_REPORT_PIDFD ,
+then an event listener should expect to receive up to two
+.I fanotify_event_info_fid
+information records and one
+.I fanotify_event_info_pidfd
+information record alongside the generic
+.I fanotify_event_metadata
+structure.
+Importantly,
+fanotify provides no guarantee around
+the ordering of information records
+when a notification group is initialized with a
+stacked based configuration.
+Each information record has a nested structure of type
+.IR fanotify_event_info_header .
+It is imperative for event listeners to inspect the
+.I info_type
+field of this structure in order to
+determine the type of information record that
+had been received for a given event.
+.P
+In cases where an fanotify group
+identifies filesystem objects by file handles,
+event listeners should also expect to
+receive one or more of the below
+information record objects alongside the generic
+.I fanotify_event_metadata
+structure within the read buffer:
+.P
+.in +4n
+.EX
+struct fanotify_event_info_fid {
+    struct fanotify_event_info_header hdr;
+    __kernel_fsid_t fsid;
+    unsigned char handle[];
+};
+.EE
+.in
+.P
+In cases where an fanotify group is initialized with
+.BR FAN_REPORT_PIDFD ,
+event listeners should expect to receive the below
+information record object alongside the generic
+.I fanotify_event_metadata
+structure within the read buffer:
+.P
+.in +4n
+.EX
+struct fanotify_event_info_pidfd {
+        struct fanotify_event_info_header hdr;
+        __s32 pidfd;
+};
+.EE
+.in
+.P
+In case of a
+.B FAN_FS_ERROR
+event,
+an additional information record describing the error that occurred
+is returned alongside the generic
+.I fanotify_event_metadata
+structure within the read buffer.
+This structure is defined as follows:
+.P
+.in +4n
+.EX
+struct fanotify_event_info_error {
+    struct fanotify_event_info_header hdr;
+    __s32 error;
+    __u32 error_count;
+};
+.EE
+.in
+.P
+All information records contain a nested structure of type
+.IR fanotify_event_info_header .
+This structure holds meta-information about the information record
+that may have been returned alongside the generic
+.I fanotify_event_metadata
+structure.
+This structure is defined as follows:
+.P
+.in +4n
+.EX
+struct fanotify_event_info_header {
+	__u8 info_type;
+	__u8 pad;
+	__u16 len;
+};
+.EE
+.in
+.P
+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).
+.P
+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).
+.P
+The fields of the
+.I fanotify_event_metadata
+structure are as follows:
+.TP
+.I event_len
+This is the length of the data for the current event and the offset
+to the next event in the buffer.
+Unless the group identifies filesystem objects by file handles, the value of
+.I event_len
+is always
+.BR FAN_EVENT_METADATA_LEN .
+For a group that identifies filesystem objects by file handles,
+.I event_len
+also includes the variable length file identifier records.
+.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 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.
+.TP
+.I reserved
+This field is not used.
+.TP
+.I metadata_len
+This is the length of the structure.
+The field was introduced to facilitate the implementation of
+optional headers per event type.
+No such optional headers exist in the current implementation.
+.TP
+.I mask
+This is a bit mask describing the event (see below).
+.TP
+.I fd
+This is an open file descriptor for the object being accessed, or
+.B FAN_NOFD
+if a queue overflow occurred.
+With an fanotify group that identifies filesystem objects by file handles,
+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.
+.IP
+When calling
+.BR fanotify_init (2),
+the caller may specify (via the
+.I event_f_flags
+argument) various file status flags that are to be set
+on the open file description that corresponds to this file descriptor.
+In addition, the (kernel-internal)
+.B FMODE_NONOTIFY
+file status flag is set on the open file description.
+This flag suppresses fanotify event generation.
+Hence, when the receiver of the fanotify event accesses the notified file or
+directory using this file descriptor, no additional events will be created.
+.TP
+.I pid
+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.
+.P
+A program listening to fanotify events can compare this PID
+to the PID returned by
+.BR getpid (2),
+to determine whether the event is caused by the listener itself,
+or is due to a file access by another process.
+.P
+The bit mask in
+.I mask
+indicates which events have occurred for a single filesystem object.
+Multiple bits may be set in this mask,
+if more than one event occurred for the monitored filesystem object.
+In particular,
+consecutive events for the same filesystem object and originating from the
+same process may be merged into a single event, with the exception that two
+permission events are never merged into one queue entry.
+.P
+The bits that may appear in
+.I mask
+are as follows:
+.TP
+.B FAN_ACCESS
+A file or a directory (but see BUGS) was accessed (read).
+.TP
+.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_FS_ERROR
+A filesystem error was detected.
+.TP
+.B FAN_RENAME
+A file or directory has been moved to or from a watched parent directory.
+.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
+.B FAN_CLOSE_WRITE
+A file that was opened for writing
+.RB ( O_WRONLY
+or
+.BR O_RDWR )
+was closed.
+.TP
+.B FAN_CLOSE_NOWRITE
+A file or directory that was opened read-only
+.RB ( O_RDONLY )
+was closed.
+.TP
+.B FAN_Q_OVERFLOW
+The event queue exceeded the limit on number of events.
+This limit can be overridden by specifying the
+.B FAN_UNLIMITED_QUEUE
+flag when calling
+.BR fanotify_init (2).
+.TP
+.B FAN_ACCESS_PERM
+An application wants to read a file or directory, for example using
+.BR read (2)
+or
+.BR readdir (2).
+The reader must write a response (as described below)
+that determines whether the permission to
+access the filesystem object shall be granted.
+.TP
+.B FAN_OPEN_PERM
+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.
+.P
+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
+.in +4n
+.EX
+FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
+.EE
+.in
+.P
+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
+.in +4n
+.EX
+FAN_MOVED_FROM | FAN_MOVED_TO
+.EE
+.in
+.P
+The following bits may appear in
+.I mask
+only in conjunction with other event type bits:
+.TP
+.B FAN_ONDIR
+The events described in the
+.I mask
+have occurred on a directory object.
+Reporting events on directories requires setting this flag in the mark mask.
+See
+.BR fanotify_mark (2)
+for additional details.
+The
+.B FAN_ONDIR
+flag is reported in an event mask only if the fanotify group identifies
+filesystem objects by file handles.
+.P
+Information records that are supplied alongside the generic
+.I fanotify_event_metadata
+structure will always contain a nested structure of type
+.IR fanotify_event_info_header .
+The fields of the
+.I fanotify_event_info_header
+are as follows:
+.TP
+.I info_type
+A unique integer value representing
+the type of information record object received for an event.
+The value of this field can be set to one of the following:
+.BR FAN_EVENT_INFO_TYPE_FID ,
+.BR FAN_EVENT_INFO_TYPE_DFID ,
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+or
+.BR FAN_EVENT_INFO_TYPE_PIDFD .
+The value set for this field
+is dependent on the flags that have been supplied to
+.BR fanotify_init (2).
+Refer to the field details of each information record object type below
+to understand the different cases in which the
+.I info_type
+values can be set.
+.TP
+.I pad
+This field is currently not used by any information record object type
+and therefore is set to zero.
+.TP
+.I len
+The value of
+.I len
+is set to the size of the information record object,
+including the
+.IR fanotify_event_info_header .
+The total size of all additional information records
+is not expected to be larger than
+.RI ( event_len
+\-
+.IR metadata_len ).
+.P
+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 .
+For example, when an fanotify file descriptor is created using
+.BR FAN_REPORT_FID ,
+a single information record is expected to be attached to the event with
+.I info_type
+field value of
+.BR FAN_EVENT_INFO_TYPE_FID .
+When an fanotify file descriptor is created using the combination of
+.B FAN_REPORT_FID
+and
+.BR FAN_REPORT_DIR_FID ,
+there may be two information records attached to the event:
+one with
+.I info_type
+field value of
+.BR FAN_EVENT_INFO_TYPE_DFID ,
+identifying a parent directory object, and one with
+.I info_type
+field value of
+.BR FAN_EVENT_INFO_TYPE_FID ,
+identifying a child object.
+Note that for the directory entry modification events
+.BR FAN_CREATE ,
+.BR FAN_DELETE ,
+.BR FAN_MOVE ,
+and
+.BR FAN_RENAME ,
+an information record identifying the created/deleted/moved child object
+is reported only if an fanotify group was initialized with the flag
+.BR FAN_REPORT_TARGET_FID .
+.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 handle
+This field contains a variable-length structure of type
+.IR "struct 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).
+If the value of
+.I info_type
+field is
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+the file handle is followed by a null terminated string that identifies the
+created/deleted/moved directory entry name.
+For other events such as
+.BR FAN_OPEN ,
+.BR FAN_ATTRIB ,
+.BR FAN_DELETE_SELF ,
+and
+.BR FAN_MOVE_SELF ,
+if the value of
+.I info_type
+field is
+.BR FAN_EVENT_INFO_TYPE_FID ,
+the
+.I handle
+identifies the object correlated to the event.
+If the value of
+.I info_type
+field is
+.BR FAN_EVENT_INFO_TYPE_DFID ,
+the
+.I handle
+identifies the directory object correlated to the event or the parent directory
+of a non-directory object correlated to the event.
+If the value of
+.I info_type
+field is
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+the
+.I handle
+identifies the same directory object that would be reported with
+.B FAN_EVENT_INFO_TYPE_DFID
+and the file handle is followed by a null terminated string that identifies the
+name of a directory entry in that directory, or '.' to identify the directory
+object itself.
+.P
+The fields of the
+.I fanotify_event_info_pidfd
+structure are as follows:
+.TP
+.I hdr
+This is a structure of type
+.IR fanotify_event_info_header .
+When an fanotify group is initialized using
+.BR FAN_REPORT_PIDFD ,
+the
+.I info_type
+field value of the
+.I fanotify_event_info_header
+is set to
+.BR FAN_EVENT_INFO_TYPE_PIDFD .
+.TP
+.I pidfd
+This is a process file descriptor that refers to
+the process responsible for generating the event.
+The returned process file descriptor is no different from
+one which could be obtained manually if
+.BR pidfd_open (2)
+were to be called on
+.IR fanotify_event_metadata.pid .
+In the instance that an error is encountered during pidfd creation,
+one of two possible error types represented by
+a negative integer value may be returned in this
+.I pidfd
+field.
+In cases where
+the process responsible for generating the event
+has terminated prior to
+the event listener being able to
+read events from the notification queue,
+.B FAN_NOPIDFD
+is returned.
+The pidfd creation for an event is only performed at the time the
+events are read from the notification queue.
+All other possible pidfd creation failures are represented by
+.BR FAN_EPIDFD .
+Once the event listener has dealt with an event
+and the pidfd is no longer required,
+the pidfd should be closed via
+.BR close (2).
+.P
+The fields of the
+.I fanotify_event_info_error
+structure are as follows:
+.TP
+.I hdr
+This is a structure of type
+.IR fanotify_event_info_header .
+The
+.I info_type
+field is set to
+.BR FAN_EVENT_INFO_TYPE_ERROR .
+.TP
+.I error
+Identifies the type of error that occurred.
+.TP
+.I error_count
+This is a counter of the number of errors suppressed
+since the last error was read.
+.P
+The following macros are provided to iterate over a buffer containing
+fanotify event metadata returned by a
+.BR read (2)
+from an fanotify file descriptor:
+.TP
+.B FAN_EVENT_OK(meta, len)
+This macro checks the remaining length
+.I len
+of the buffer
+.I meta
+against the length of the metadata structure and the
+.I event_len
+field of the first metadata structure in the buffer.
+.TP
+.B FAN_EVENT_NEXT(meta, len)
+This macro uses the length indicated in the
+.I event_len
+field of the metadata structure pointed to by
+.I meta
+to calculate the address of the next metadata structure that follows
+.IR meta .
+.I len
+is the number of bytes of metadata that currently remain in the buffer.
+The macro returns a pointer to the next metadata structure that follows
+.IR meta ,
+and reduces
+.I len
+by the number of bytes in the metadata structure that
+has been skipped over (i.e., it subtracts
+.I meta\->event_len
+from
+.IR len ).
+.P
+In addition, there is:
+.TP
+.B FAN_EVENT_METADATA_LEN
+This macro returns the size (in bytes) of the structure
+.IR fanotify_event_metadata .
+This is the minimum size (and currently the only size) of any event metadata.
+.\"
+.SS Monitoring an fanotify file descriptor for events
+When an fanotify event occurs, the fanotify file descriptor indicates as
+readable when passed to
+.BR epoll (7),
+.BR poll (2),
+or
+.BR select (2).
+.SS Dealing with permission events
+For permission events, the application must
+.BR write (2)
+a structure of the following form to the
+fanotify file descriptor:
+.P
+.in +4n
+.EX
+struct fanotify_response {
+    __s32 fd;
+    __u32 response;
+};
+.EE
+.in
+.P
+The fields of this structure are as follows:
+.TP
+.I fd
+This is the file descriptor from the structure
+.IR fanotify_event_metadata .
+.TP
+.I response
+This field indicates whether or not the permission is to be granted.
+Its value must be either
+.B FAN_ALLOW
+to allow the file operation or
+.B FAN_DENY
+to deny the file operation.
+.P
+If access is denied, the requesting application call will receive an
+.B EPERM
+error.
+Additionally, if the notification group has been created with the
+.B FAN_ENABLE_AUDIT
+flag, then the
+.B FAN_AUDIT
+flag can be set in the
+.I response
+field.
+In that case, the audit subsystem will log information about the access
+decision to the audit logs.
+.\"
+.SS Monitoring filesystems for errors
+A single
+.B FAN_FS_ERROR
+event is stored per filesystem at once.
+Extra error messages are suppressed and accounted for in the
+.I error_count
+field of the existing
+.B FAN_FS_ERROR
+event record,
+but details about the errors are lost.
+.P
+Errors reported by
+.B FAN_FS_ERROR
+are generic
+.I errno
+values,
+but not all kinds of error types are reported by all filesystems.
+.P
+Errors not directly related to a file (i.e. super block corruption)
+are reported with an invalid
+.IR handle .
+For these errors, the
+.I handle
+will have the field
+.I handle_type
+set to
+.BR FILEID_INVALID ,
+and the handle buffer size set to
+.BR 0 .
+.\"
+.SS Closing the fanotify file descriptor
+When all file descriptors referring to the fanotify notification group are
+closed, the fanotify group is released and its resources
+are freed for reuse by the kernel.
+Upon
+.BR close (2),
+outstanding permission events will be set to allowed.
+.SS /proc interfaces
+The file
+.IR /proc/ pid /fdinfo/ fd
+contains information about fanotify marks for file descriptor
+.I fd
+of process
+.IR pid .
+See
+.BR proc (5)
+for details.
+.P
+Since Linux 5.13,
+.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
+the following interfaces can be used to control the amount of
+kernel resources consumed by fanotify:
+.TP
+.I /proc/sys/fs/fanotify/max_queued_events
+The value in this file is used when an application calls
+.BR fanotify_init (2)
+to set an upper limit on the number of events that can be
+queued to the corresponding fanotify group.
+Events in excess of this limit are dropped, but an
+.B FAN_Q_OVERFLOW
+event is always generated.
+Prior to Linux kernel 5.13,
+.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
+the hardcoded limit was 16384 events.
+.TP
+.I /proc/sys/fs/fanotify/max_user_group
+This specifies an upper limit on the number of fanotify groups
+that can be created per real user ID.
+Prior to Linux kernel 5.13,
+.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
+the hardcoded limit was 128 groups per user.
+.TP
+.I /proc/sys/fs/fanotify/max_user_marks
+This specifies an upper limit on the number of fanotify marks
+that can be created per real user ID.
+Prior to Linux kernel 5.13,
+.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
+the hardcoded limit was 8192 marks per group (not per user).
+.SH ERRORS
+In addition to the usual errors for
+.BR read (2),
+the following errors can occur when reading from the
+fanotify file descriptor:
+.TP
+.B EINVAL
+The buffer is too small to hold the event.
+.TP
+.B EMFILE
+The per-process limit on the number of open files has been reached.
+See the description of
+.B RLIMIT_NOFILE
+in
+.BR getrlimit (2).
+.TP
+.B ENFILE
+The system-wide limit on the total number of open files has been reached.
+See
+.I /proc/sys/fs/file\-max
+in
+.BR proc (5).
+.TP
+.B ETXTBSY
+This error is returned by
+.BR read (2)
+if
+.B O_RDWR
+or
+.B O_WRONLY
+was specified in the
+.I event_f_flags
+argument when calling
+.BR fanotify_init (2)
+and an event occurred for a monitored file that is currently being executed.
+.P
+In addition to the usual errors for
+.BR write (2),
+the following errors can occur when writing to the fanotify file descriptor:
+.TP
+.B EINVAL
+Fanotify access permissions are not enabled in the kernel configuration
+or the value of
+.I response
+in the response structure is not valid.
+.TP
+.B ENOENT
+The file descriptor
+.I fd
+in the response structure is not valid.
+This may occur when a response for the permission event has already been
+written.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+The fanotify API was introduced in Linux 2.6.36 and
+enabled in Linux 2.6.37.
+fdinfo support was added in Linux 3.8.
+.SH NOTES
+The fanotify API is available only if the kernel was built with the
+.B CONFIG_FANOTIFY
+configuration option enabled.
+In addition, fanotify permission handling is available only if the
+.B CONFIG_FANOTIFY_ACCESS_PERMISSIONS
+configuration option is enabled.
+.SS Limitations and caveats
+Fanotify reports only events that a user-space program triggers through the
+filesystem API.
+As a result,
+it does not catch remote events that occur on network filesystems.
+.P
+The fanotify API does not report file accesses and modifications that
+may occur because of
+.BR mmap (2),
+.BR msync (2),
+and
+.BR munmap (2).
+.P
+Events for directories are created only if the directory itself is opened,
+read, and closed.
+Adding, removing, or changing children of a marked directory does not create
+events for the monitored directory itself.
+.P
+Fanotify monitoring of directories is not recursive:
+to monitor subdirectories under a directory,
+additional marks must be created.
+The
+.B FAN_CREATE
+event can be used for detecting when a subdirectory has been created under
+a marked directory.
+An additional mark must then be set on the newly created subdirectory.
+This approach is racy, because it can lose events that occurred inside the
+newly created subdirectory, before a mark is added on that subdirectory.
+Monitoring mounts offers the capability to monitor a whole directory tree
+in a race-free manner.
+Monitoring filesystems offers the capability to monitor changes made from
+any mount of a filesystem instance in a race-free manner.
+.P
+The event queue can overflow.
+In this case, events are lost.
+.SH BUGS
+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.
+.P
+As of Linux 3.17,
+the following bugs exist:
+.IP \[bu] 3
+On Linux, a filesystem object may be accessible through multiple paths,
+for example, a part of a filesystem may be remounted using the
+.I \-\-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 \[bu]
+.\" 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
+before passing a file descriptor for that file.
+This poses a security risk, when the
+.B CAP_SYS_ADMIN
+capability is set for programs executed by unprivileged users.
+.IP \[bu]
+If a call to
+.BR read (2)
+processes multiple events from the fanotify queue and an error occurs,
+the return value will be the total length of the events successfully
+copied to the user-space buffer before the error occurred.
+The return value will not be \-1, and
+.I errno
+will not be set.
+Thus, the reading application has no way to detect the error.
+.SH EXAMPLES
+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 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.
+.P
+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
+event occurred.
+After the file was closed, a
+.B FAN_CLOSE_WRITE
+event occurred.
+Execution of the program ends when the user presses the ENTER key.
+.P
+.in +4n
+.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.
+.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 <limits.h>
+#include <poll.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/fanotify.h>
+#include <unistd.h>
+\&
+/* Read all available fanotify events from the file descriptor \[aq]fd\[aq]. */
+\&
+static void
+handle_events(int fd)
+{
+    const struct fanotify_event_metadata *metadata;
+    struct fanotify_event_metadata buf[200];
+    ssize_t len;
+    char path[PATH_MAX];
+    ssize_t path_len;
+    char procfd_path[PATH_MAX];
+    struct fanotify_response response;
+\&
+    /* Loop while events can be read from fanotify file descriptor. */
+\&
+    for (;;) {
+\&
+        /* Read some events. */
+\&
+        len = read(fd, buf, sizeof(buf));
+        if (len == \-1 && errno != EAGAIN) {
+            perror("read");
+            exit(EXIT_FAILURE);
+        }
+\&
+        /* Check if end of available data reached. */
+\&
+        if (len <= 0)
+            break;
+\&
+        /* Point to the first event in the buffer. */
+\&
+        metadata = buf;
+\&
+        /* Loop over all events in the buffer. */
+\&
+        while (FAN_EVENT_OK(metadata, len)) {
+\&
+            /* Check that run\-time and compile\-time structures match. */
+\&
+            if (metadata\->vers != FANOTIFY_METADATA_VERSION) {
+                fprintf(stderr,
+                        "Mismatch of fanotify metadata version.\en");
+                exit(EXIT_FAILURE);
+            }
+\&
+            /* metadata\->fd contains either FAN_NOFD, indicating a
+               queue overflow, or a file descriptor (a nonnegative
+               integer). Here, we simply ignore queue overflow. */
+\&
+            if (metadata\->fd >= 0) {
+\&
+                /* Handle open permission event. */
+\&
+                if (metadata\->mask & FAN_OPEN_PERM) {
+                    printf("FAN_OPEN_PERM: ");
+\&
+                    /* Allow file to be opened. */
+\&
+                    response.fd = metadata\->fd;
+                    response.response = FAN_ALLOW;
+                    write(fd, &response, sizeof(response));
+                }
+\&
+                /* Handle closing of writable file event. */
+\&
+                if (metadata\->mask & FAN_CLOSE_WRITE)
+                    printf("FAN_CLOSE_WRITE: ");
+\&
+                /* Retrieve and print pathname of the accessed file. */
+\&
+                snprintf(procfd_path, sizeof(procfd_path),
+                         "/proc/self/fd/%d", metadata\->fd);
+                path_len = readlink(procfd_path, path,
+                                    sizeof(path) \- 1);
+                if (path_len == \-1) {
+                    perror("readlink");
+                    exit(EXIT_FAILURE);
+                }
+\&
+                path[path_len] = \[aq]\e0\[aq];
+                printf("File %s\en", path);
+\&
+                /* Close the file descriptor of the event. */
+\&
+                close(metadata\->fd);
+            }
+\&
+            /* Advance to next event. */
+\&
+            metadata = FAN_EVENT_NEXT(metadata, len);
+        }
+    }
+}
+\&
+int
+main(int argc, char *argv[])
+{
+    char buf;
+    int fd, poll_num;
+    nfds_t nfds;
+    struct pollfd fds[2];
+\&
+    /* Check mount point is supplied. */
+\&
+    if (argc != 2) {
+        fprintf(stderr, "Usage: %s MOUNT\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    printf("Press enter key to terminate.\en");
+\&
+    /* Create the file descriptor for accessing the fanotify API. */
+\&
+    fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK,
+                       O_RDONLY | O_LARGEFILE);
+    if (fd == \-1) {
+        perror("fanotify_init");
+        exit(EXIT_FAILURE);
+    }
+\&
+    /* Mark the mount for:
+       \- permission events before opening files
+       \- notification events after closing a write\-enabled
+         file descriptor. */
+\&
+    if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT,
+                      FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD,
+                      argv[1]) == \-1) {
+        perror("fanotify_mark");
+        exit(EXIT_FAILURE);
+    }
+\&
+    /* Prepare for polling. */
+\&
+    nfds = 2;
+\&
+    fds[0].fd = STDIN_FILENO;       /* Console input */
+    fds[0].events = POLLIN;
+\&
+    fds[1].fd = fd;                 /* Fanotify input */
+    fds[1].events = POLLIN;
+\&
+    /* This is the loop to wait for incoming events. */
+\&
+    printf("Listening for events.\en");
+\&
+    while (1) {
+        poll_num = poll(fds, nfds, \-1);
+        if (poll_num == \-1) {
+            if (errno == EINTR)     /* Interrupted by a signal */
+                continue;           /* Restart poll() */
+\&
+            perror("poll");         /* Unexpected error */
+            exit(EXIT_FAILURE);
+        }
+\&
+        if (poll_num > 0) {
+            if (fds[0].revents & POLLIN) {
+\&
+                /* Console input is available: empty stdin and quit. */
+\&
+                while (read(STDIN_FILENO, &buf, 1) > 0 && buf != \[aq]\en\[aq])
+                    continue;
+                break;
+            }
+\&
+            if (fds[1].revents & POLLIN) {
+\&
+                /* Fanotify events are available. */
+\&
+                handle_events(fd);
+            }
+        }
+    }
+\&
+    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 a group that
+identifies objects by file handles.
+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\[em]either
+a file or a directory\[em]was created.
+Once all events have been read from the buffer and processed accordingly,
+the program simply terminates.
+.P
+The following shell sessions show two different invocations of
+this program, with different actions performed on a watched object.
+.P
+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 generated and reported against the file's parent watched
+directory object and with the created file name.
+Program execution ends once all events captured within the buffer have
+been processed.
+.P
+.in +4n
+.EX
+# \fB./fanotify_fid /home/user\fP
+Listening for events.
+FAN_CREATE (file created):
+        Directory /home/user has been modified.
+        Entry \[aq]testfile.txt\[aq] is not a subdirectory.
+All events processed successfully. Program exiting.
+\&
+$ \fBtouch /home/user/testfile.txt\fP              # In another terminal
+.EE
+.in
+.P
+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 a
+.B FAN_CREATE
+event being generated and is reported with the
+.B FAN_ONDIR
+flag set and with the created directory name.
+.P
+.in +4n
+.EX
+# \fB./fanotify_fid /home/user\fP
+Listening for events.
+FAN_CREATE | FAN_ONDIR (subdirectory created):
+        Directory /home/user has been modified.
+        Entry \[aq]testdir\[aq] is a subdirectory.
+All events processed successfully. Program exiting.
+\&
+$ \fBmkdir \-p /home/user/testdir\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, mount_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;
+    const char *file_name;
+    struct stat sb;
+\&
+    if (argc != 2) {
+        fprintf(stderr, "Invalid number of command line arguments.\en");
+        exit(EXIT_FAILURE);
+    }
+\&
+    mount_fd = open(argv[1], O_DIRECTORY | O_RDONLY);
+    if (mount_fd == \-1) {
+        perror(argv[1]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    /* Create an fanotify file descriptor with FAN_REPORT_DFID_NAME as
+       a flag so that program can receive fid events with directory
+       entry name. */
+\&
+    fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME, 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.\en");
+\&
+    /* Read events from the event queue into a buffer. */
+\&
+    len = read(fd, 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 ||
+            fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID) {
+            file_name = NULL;
+        } else if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
+            file_name = file_handle\->f_handle +
+                        file_handle\->handle_bytes;
+        } else {
+            fprintf(stderr, "Received unexpected event info type.\en");
+            exit(EXIT_FAILURE);
+        }
+\&
+        if (metadata\->mask == FAN_CREATE)
+            printf("FAN_CREATE (file created):\en");
+\&
+        if (metadata\->mask == (FAN_CREATE | FAN_ONDIR))
+            printf("FAN_CREATE | FAN_ONDIR (subdirectory created):\en");
+\&
+	/* metadata\->fd is set to FAN_NOFD when the group identifies
+	   objects by file handles.  To obtain a file descriptor for
+	   the file object corresponding to an event you can use the
+	   struct file_handle that\[aq]s 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(mount_fd, file_handle, O_RDONLY);
+        if (event_fd == \-1) {
+            if (errno == ESTALE) {
+                printf("File handle is no longer valid. "
+                        "File has been deleted\en");
+                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]\e0\[aq];
+        printf("\etDirectory \[aq]%s\[aq] has been modified.\en", path);
+\&
+        if (file_name) {
+            ret = fstatat(event_fd, file_name, &sb, 0);
+            if (ret == \-1) {
+                if (errno != ENOENT) {
+                    perror("fstatat");
+                    exit(EXIT_FAILURE);
+                }
+                printf("\etEntry \[aq]%s\[aq] does not exist.\en", file_name);
+            } else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
+                printf("\etEntry \[aq]%s\[aq] is a subdirectory.\en", file_name);
+            } else {
+                printf("\etEntry \[aq]%s\[aq] is not a subdirectory.\en",
+                        file_name);
+            }
+        }
+\&
+        /* Close associated file descriptor for this event. */
+\&
+        close(event_fd);
+    }
+\&
+    printf("All events processed successfully. Program exiting.\en");
+    exit(EXIT_SUCCESS);
+}
+.EE
+.SH SEE ALSO
+.ad l
+.BR fanotify_init (2),
+.BR fanotify_mark (2),
+.BR inotify (7)