diff options
Diffstat (limited to 'man2/fanotify_init.2')
| -rw-r--r-- | man2/fanotify_init.2 | 542 |
1 files changed, 542 insertions, 0 deletions
diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 new file mode 100644 index 0000000..f48e43a --- /dev/null +++ b/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 2023-07-08 "Linux man-pages 6.05.01" +.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> +.PP +.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). +.PP +.BR fanotify_init () +initializes a new fanotify group and returns a file descriptor for the event +queue associated with the group. +.PP +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. +.PP +Multiple programs may be using the fanotify interface at the same time to +monitor the same files. +.PP +The number of fanotify groups per user is limited. +See +.BR fanotify (7) +for details about this limit. +.PP +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. +.PP +If multiple listeners for permission events exist, +the notification class is used to establish the sequence +in which the listeners receive the events. +.PP +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. +.PP +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. +.PP +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). +.PP +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. +.PP +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. +.PP +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 . +.PP +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) |