diff options
Diffstat (limited to 'man2/fanotify_init.2')
| -rw-r--r-- | man2/fanotify_init.2 | 542 |
1 files changed, 0 insertions, 542 deletions
diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 deleted file mode 100644 index e5f9cbf29..000000000 --- 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 (date) "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) |