summaryrefslogtreecommitdiffstats
path: root/man2/fanotify_init.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/fanotify_init.2')
-rw-r--r--man2/fanotify_init.2542
1 files changed, 0 insertions, 542 deletions
diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
deleted file mode 100644
index 8a9667b..0000000
--- a/man2/fanotify_init.2
+++ /dev/null
@@ -1,542 +0,0 @@
-.\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.TH fanotify_init 2 2023-10-31 "Linux man-pages 6.7"
-.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)