Merging upstream version 6.8.

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

1 files changed, 542 insertions, 0 deletions

diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
new file mode 100644
index 0000000..19b3fe3
--- /dev/null
+++ b/man/man2/fanotify_init.2
@@ -0,0 +1,542 @@
+.\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.TH fanotify_init 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+fanotify_init \- create and initialize fanotify group
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
+.B #include <sys/fanotify.h>
+.P
+.BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
+.fi
+.SH DESCRIPTION
+For an overview of the fanotify API, see
+.BR fanotify (7).
+.P
+.BR fanotify_init ()
+initializes a new fanotify group and returns a file descriptor for the event
+queue associated with the group.
+.P
+The file descriptor is used in calls to
+.BR fanotify_mark (2)
+to specify the files, directories, mounts, or filesystems for which fanotify
+events shall be created.
+These events are received by reading from the file descriptor.
+Some events are only informative, indicating that a file has been accessed.
+Other events can be used to determine whether
+another application is permitted to access a file or directory.
+Permission to access filesystem objects is granted by writing to the file
+descriptor.
+.P
+Multiple programs may be using the fanotify interface at the same time to
+monitor the same files.
+.P
+The number of fanotify groups per user is limited.
+See
+.BR fanotify (7)
+for details about this limit.
+.P
+The
+.I flags
+argument contains a multi-bit field defining the notification class of the
+listening application and further single bit fields specifying the behavior
+of the file descriptor.
+.P
+If multiple listeners for permission events exist,
+the notification class is used to establish the sequence
+in which the listeners receive the events.
+.P
+Only one of the following notification classes may be specified in
+.IR flags :
+.TP
+.B FAN_CLASS_PRE_CONTENT
+This value allows the receipt of events notifying that a file has been
+accessed and events for permission decisions if a file may be accessed.
+It is intended for event listeners that need to access files before they
+contain their final data.
+This notification class might be used by hierarchical storage managers,
+for example.
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
+.TP
+.B FAN_CLASS_CONTENT
+This value allows the receipt of events notifying that a file has been
+accessed and events for permission decisions if a file may be accessed.
+It is intended for event listeners that need to access files when they
+already contain their final content.
+This notification class might be used by malware detection programs, for
+example.
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
+.TP
+.B FAN_CLASS_NOTIF
+This is the default value.
+It does not need to be specified.
+This value only allows the receipt of events notifying that a file has been
+accessed.
+Permission decisions before the file is accessed are not possible.
+.P
+Listeners with different notification classes will receive events in the
+order
+.BR FAN_CLASS_PRE_CONTENT ,
+.BR FAN_CLASS_CONTENT ,
+.BR FAN_CLASS_NOTIF .
+The order of notification for listeners in the same notification class
+is undefined.
+.P
+The following bits can additionally be set in
+.IR flags :
+.TP
+.B FAN_CLOEXEC
+Set the close-on-exec flag
+.RB ( FD_CLOEXEC )
+on the new file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2).
+.TP
+.B FAN_NONBLOCK
+Enable the nonblocking flag
+.RB ( O_NONBLOCK )
+for the file descriptor.
+Reading from the file descriptor will not block.
+Instead, if no data is available,
+.BR read (2)
+fails with the error
+.BR EAGAIN .
+.TP
+.B FAN_UNLIMITED_QUEUE
+Remove the limit on the number of events in the event queue.
+See
+.BR fanotify (7)
+for details about this limit.
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
+.TP
+.B FAN_UNLIMITED_MARKS
+Remove the limit on the number of fanotify marks per user.
+See
+.BR fanotify (7)
+for details about this limit.
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
+.TP
+.BR FAN_REPORT_TID " (since Linux 4.20)"
+.\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29
+Report thread ID (TID) instead of process ID (PID)
+in the
+.I pid
+field of the
+.I "struct fanotify_event_metadata"
+supplied to
+.BR read (2)
+(see
+.BR fanotify (7)).
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
+.TP
+.BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
+.\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
+Enable generation of audit log records about access mediation performed by
+permission events.
+The permission event response has to be marked with the
+.B FAN_AUDIT
+flag for an audit log record to be generated.
+Use of this flag requires the
+.B CAP_AUDIT_WRITE
+capability.
+.TP
+.BR FAN_REPORT_FID " (since Linux 5.1)"
+.\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
+This value allows the receipt of events which contain additional information
+about the underlying filesystem object correlated to an event.
+An additional record of type
+.B FAN_EVENT_INFO_TYPE_FID
+encapsulates the information about the object and is included alongside the
+generic event metadata structure.
+The file descriptor that is used to represent the object correlated to an
+event is instead substituted with a file handle.
+It is intended for applications that may find the use of a file handle to
+identify an object more suitable than a file descriptor.
+Additionally, it may be used for applications monitoring a directory or a
+filesystem that are interested in the directory entry modification events
+.BR FAN_CREATE ,
+.BR FAN_DELETE ,
+.BR FAN_MOVE ,
+and
+.BR FAN_RENAME ,
+or in events such as
+.BR FAN_ATTRIB ,
+.BR FAN_DELETE_SELF ,
+and
+.BR FAN_MOVE_SELF .
+All the events above require an fanotify group that identifies filesystem
+objects by file handles.
+Note that without the flag
+.BR FAN_REPORT_TARGET_FID ,
+for the directory entry modification events,
+there is an information record that identifies the modified directory
+and not the created/deleted/moved child object.
+The use of
+.B FAN_CLASS_CONTENT
+or
+.B FAN_CLASS_PRE_CONTENT
+is not permitted with this flag and will result in the error
+.BR EINVAL .
+See
+.BR fanotify (7)
+for additional details.
+.TP
+.BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
+.\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f
+Events for fanotify groups initialized with this flag will contain
+(see exceptions below) additional information about a directory object
+correlated to an event.
+An additional record of type
+.B FAN_EVENT_INFO_TYPE_DFID
+encapsulates the information about the directory object and is included
+alongside the generic event metadata structure.
+For events that occur on a non-directory object, the additional structure
+includes a file handle that identifies the parent directory filesystem object.
+Note that there is no guarantee that the directory filesystem object will be
+found at the location described by the file handle information at the time
+the event is received.
+When combined with the flag
+.BR FAN_REPORT_FID ,
+two records may be reported with events that occur on a non-directory object,
+one to identify the non-directory object itself and one to identify the parent
+directory object.
+Note that in some cases, a filesystem object does not have a parent,
+for example, when an event occurs on an unlinked but open file.
+In that case, with the
+.B FAN_REPORT_FID
+flag, the event will be reported with only one record to identify the
+non-directory object itself, because there is no directory associated with
+the event.
+Without the
+.B FAN_REPORT_FID
+flag, no event will be reported.
+See
+.BR fanotify (7)
+for additional details.
+.TP
+.BR FAN_REPORT_NAME " (since Linux 5.9)"
+.\" commit 929943b38daf817f2e6d303ea04401651fc3bc05
+Events for fanotify groups initialized with this flag will contain additional
+information about the name of the directory entry correlated to an event.
+This flag must be provided in conjunction with the flag
+.BR FAN_REPORT_DIR_FID .
+Providing this flag value without
+.B FAN_REPORT_DIR_FID
+will result in the error
+.BR EINVAL .
+This flag may be combined with the flag
+.BR FAN_REPORT_FID .
+An additional record of type
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+which encapsulates the information about the directory entry, is included
+alongside the generic event metadata structure and substitutes the additional
+information record of type
+.BR FAN_EVENT_INFO_TYPE_DFID .
+The additional record includes a file handle that identifies a directory
+filesystem object followed by a name that identifies an entry in that
+directory.
+For the directory entry modification events
+.BR FAN_CREATE ,
+.BR FAN_DELETE ,
+and
+.BR FAN_MOVE ,
+the reported name is that of the created/deleted/moved directory entry.
+The event
+.B FAN_RENAME
+may contain two information records.
+One of type
+.B FAN_EVENT_INFO_TYPE_OLD_DFID_NAME
+identifying the old directory entry,
+and another of type
+.B FAN_EVENT_INFO_TYPE_NEW_DFID_NAME
+identifying the new directory entry.
+For other events that occur on a directory object, the reported file handle
+is that of the directory object itself and the reported name is '.'.
+For other events that occur on a non-directory object, the reported file handle
+is that of the parent directory object and the reported name is the name of a
+directory entry where the object was located at the time of the event.
+The rationale behind this logic is that the reported directory file handle can
+be passed to
+.BR open_by_handle_at (2)
+to get an open directory file descriptor and that file descriptor along with
+the reported name can be used to call
+.BR fstatat (2).
+The same rule that applies to record type
+.B FAN_EVENT_INFO_TYPE_DFID
+also applies to record type
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME :
+if a non-directory object has no parent, either the event will not be reported
+or it will be reported without the directory entry information.
+Note that there is no guarantee that the filesystem object will be found at the
+location described by the directory entry information at the time the event is
+received.
+See
+.BR fanotify (7)
+for additional details.
+.TP
+.B FAN_REPORT_DFID_NAME
+This is a synonym for
+.RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
+.TP
+.BR FAN_REPORT_TARGET_FID " (since Linux 5.17)"
+.\" commit d61fd650e9d206a71fda789f02a1ced4b19944c4
+Events for fanotify groups initialized with this flag
+will contain additional information about the child
+correlated with directory entry modification events.
+This flag must be provided in conjunction with the flags
+.BR FAN_REPORT_FID ,
+.B FAN_REPORT_DIR_FID
+and
+.BR FAN_REPORT_NAME .
+or else the error
+.B EINVAL
+will be returned.
+For the directory entry modification events
+.BR FAN_CREATE ,
+.BR FAN_DELETE ,
+.BR FAN_MOVE ,
+and
+.BR FAN_RENAME ,
+an additional record of type
+.BR FAN_EVENT_INFO_TYPE_FID ,
+is reported in addition to the information records of type
+.BR FAN_EVENT_INFO_TYPE_DFID ,
+.BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+.BR FAN_EVENT_INFO_TYPE_OLD_DFID_NAME ,
+and
+.BR FAN_EVENT_INFO_TYPE_NEW_DFID_NAME .
+The additional record includes a file handle
+that identifies the filesystem child object
+that the directory entry is referring to.
+.TP
+.B FAN_REPORT_DFID_NAME_TARGET
+This is a synonym for
+.RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
+.TP
+.BR FAN_REPORT_PIDFD " (since Linux 5.15)"
+.\" commit af579beb666aefb17e9a335c12c788c92932baf1
+Events for fanotify groups initialized with this flag will contain
+an additional information record alongside the generic
+.I fanotify_event_metadata
+structure.
+This information record will be of type
+.B FAN_EVENT_INFO_TYPE_PIDFD
+and will contain a pidfd for the process that
+was responsible for generating an event.
+A pidfd returned in this information record object is
+no different to the pidfd that is returned when calling
+.BR pidfd_open (2).
+Usage of this information record are for applications that
+may be interested in reliably determining whether
+the process responsible for generating an event
+has been recycled or terminated.
+The use of the
+.B FAN_REPORT_TID
+flag along with
+.B FAN_REPORT_PIDFD
+is currently not supported and
+attempting to do so will result in the error
+.B EINVAL
+being returned.
+This limitation is currently imposed by the pidfd API
+as it currently only supports
+the creation of pidfds for thread-group leaders.
+Creating pidfds for non-thread-group leaders
+may be supported at some point in the future,
+so this restriction may eventually be lifted.
+For more details on information records,
+see
+.BR fanotify (7).
+.P
+The
+.I event_f_flags
+argument
+defines the file status flags that will be set on the open file descriptions
+that are created for fanotify events.
+For details of these flags, see the description of the
+.I flags
+values in
+.BR open (2).
+.I event_f_flags
+includes a multi-bit field for the access mode.
+This field can take the following values:
+.TP
+.B O_RDONLY
+This value allows only read access.
+.TP
+.B O_WRONLY
+This value allows only write access.
+.TP
+.B O_RDWR
+This value allows read and write access.
+.P
+Additional bits can be set in
+.IR event_f_flags .
+The most useful values are:
+.TP
+.B O_LARGEFILE
+Enable support for files exceeding 2\ GB.
+Failing to set this flag will result in an
+.B EOVERFLOW
+error when trying to open a large file which is monitored by
+an fanotify group on a 32-bit system.
+.TP
+.BR O_CLOEXEC " (since Linux 3.18)"
+.\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
+Enable the close-on-exec flag for the file descriptor.
+See the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2)
+for reasons why this may be useful.
+.P
+The following are also allowable:
+.BR O_APPEND ,
+.BR O_DSYNC ,
+.BR O_NOATIME ,
+.BR O_NONBLOCK ,
+and
+.BR O_SYNC .
+Specifying any other flag in
+.I event_f_flags
+yields the error
+.B EINVAL
+(but see BUGS).
+.SH RETURN VALUE
+On success,
+.BR fanotify_init ()
+returns a new file descriptor.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+An invalid value was passed in
+.I flags
+or
+.IR event_f_flags .
+.B FAN_ALL_INIT_FLAGS
+(deprecated since Linux 4.20)
+.\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4
+defines all allowable bits for
+.IR flags .
+.TP
+.B EMFILE
+The number of fanotify groups for this user exceeds the limit.
+See
+.BR fanotify (7)
+for details about this limit.
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B ENOMEM
+The allocation of memory for the notification group failed.
+.TP
+.B ENOSYS
+This kernel does not implement
+.BR fanotify_init ().
+The fanotify API is available only if the kernel was configured with
+.BR CONFIG_FANOTIFY .
+.TP
+.B EPERM
+The operation is not permitted because the caller lacks a required capability.
+.SH VERSIONS
+Prior to Linux 5.13,
+.\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7
+calling
+.BR fanotify_init ()
+required the
+.B CAP_SYS_ADMIN
+capability.
+Since Linux 5.13,
+.\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7
+users may call
+.BR fanotify_init ()
+without the
+.B CAP_SYS_ADMIN
+capability to create and initialize
+an fanotify group with limited functionality.
+.TP
+The limitations imposed on an event listener created by a user without the
+.B CAP_SYS_ADMIN
+capability are as follows:
+.RS
+.IP \[bu] 3
+The user cannot request for an unlimited event queue by using
+.BR FAN_UNLIMITED_QUEUE .
+.IP \[bu]
+The user cannot request for an unlimited number of marks by using
+.BR FAN_UNLIMITED_MARKS .
+.IP \[bu]
+The user cannot request to use either notification classes
+.B FAN_CLASS_CONTENT
+or
+.BR FAN_CLASS_PRE_CONTENT .
+This means that user cannot request permission events.
+.IP \[bu]
+The user is required to create a group that identifies filesystem objects by
+file handles, for example, by providing the
+.B FAN_REPORT_FID
+flag.
+.IP \[bu]
+The user is limited to only mark inodes.
+The ability to mark a mount or filesystem via
+.BR fanotify_mark ()
+through the use of
+.B FAN_MARK_MOUNT
+or
+.B FAN_MARK_FILESYSTEM
+is not permitted.
+.IP \[bu]
+The event object in the event queue is limited in terms of the information
+that is made available to the unprivileged user.
+A user will also not receive the pid that generated the event, unless the
+listening process itself generated the event.
+.RE
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.37.
+.\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37.
+.SH BUGS
+The following bug was present before Linux 3.18:
+.IP \[bu] 3
+.\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
+The
+.B O_CLOEXEC
+is ignored when passed in
+.IR event_f_flags .
+.P
+The following bug was present before Linux 3.14:
+.IP \[bu] 3
+.\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580
+The
+.I event_f_flags
+argument is not checked for invalid flags.
+Flags that are intended only for internal use,
+such as
+.BR FMODE_EXEC ,
+can be set, and will consequently be set for the file descriptors
+returned when reading from the fanotify file descriptor.
+.SH SEE ALSO
+.BR fanotify_mark (2),
+.BR fanotify (7)