diff options
Diffstat (limited to 'man2/fanotify_mark.2')
| -rw-r--r-- | man2/fanotify_mark.2 | 843 |
1 files changed, 0 insertions, 843 deletions
diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 deleted file mode 100644 index 3f85deb23..000000000 --- a/man2/fanotify_mark.2 +++ /dev/null @@ -1,843 +0,0 @@ -.\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH fanotify_mark 2 (date) "Linux man-pages (unreleased)" -.SH NAME -fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem -object -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <sys/fanotify.h> -.PP -.BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags , -.BI " uint64_t " mask ", int " dirfd , -.BI " const char *_Nullable " pathname ); -.fi -.SH DESCRIPTION -For an overview of the fanotify API, see -.BR fanotify (7). -.PP -.BR fanotify_mark () -adds, removes, or modifies an fanotify mark on a filesystem object. -The caller must have read permission on the filesystem object that -is to be marked. -.PP -The -.I fanotify_fd -argument is a file descriptor returned by -.BR fanotify_init (2). -.PP -.I flags -is a bit mask describing the modification to perform. -It must include exactly one of the following values: -.TP -.B FAN_MARK_ADD -The events in -.I mask -will be added to the mark mask (or to the ignore mask). -.I mask -must be nonempty or the error -.B EINVAL -will occur. -.TP -.B FAN_MARK_REMOVE -The events in argument -.I mask -will be removed from the mark mask (or from the ignore mask). -.I mask -must be nonempty or the error -.B EINVAL -will occur. -.TP -.B FAN_MARK_FLUSH -Remove either all marks for filesystems, all marks for mounts, or all -marks for directories and files from the fanotify group. -If -.I flags -contains -.BR FAN_MARK_MOUNT , -all marks for mounts are removed from the group. -If -.I flags -contains -.BR FAN_MARK_FILESYSTEM , -all marks for filesystems are removed from the group. -Otherwise, all marks for directories and files are removed. -No flag other than, and at most one of, the flags -.B FAN_MARK_MOUNT -or -.B FAN_MARK_FILESYSTEM -can be used in conjunction with -.BR FAN_MARK_FLUSH . -.I mask -is ignored. -.PP -If none of the values above is specified, or more than one is specified, -the call fails with the error -.BR EINVAL . -.PP -In addition, -zero or more of the following values may be ORed into -.IR flags : -.TP -.B FAN_MARK_DONT_FOLLOW -If -.I pathname -is a symbolic link, mark the link itself, rather than the file to which it -refers. -(By default, -.BR fanotify_mark () -dereferences -.I pathname -if it is a symbolic link.) -.TP -.B FAN_MARK_ONLYDIR -If the filesystem object to be marked is not a directory, the error -.B ENOTDIR -shall be raised. -.TP -.B FAN_MARK_MOUNT -Mark the mount specified by -.IR pathname . -If -.I pathname -is not itself a mount point, the mount containing -.I pathname -will be marked. -All directories, subdirectories, and the contained files of the mount -will be monitored. -The events which require that filesystem objects are identified by file handles, -such as -.BR FAN_CREATE , -.BR FAN_ATTRIB , -.BR FAN_MOVE , -and -.BR FAN_DELETE_SELF , -cannot be provided as a -.I mask -when -.I flags -contains -.BR FAN_MARK_MOUNT . -Attempting to do so will result in the error -.B EINVAL -being returned. -Use of this flag requires the -.B CAP_SYS_ADMIN -capability. -.TP -.BR FAN_MARK_FILESYSTEM " (since Linux 4.20)" -.\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2 -Mark the filesystem specified by -.IR pathname . -The filesystem containing -.I pathname -will be marked. -All the contained files and directories of the filesystem from any mount -point will be monitored. -Use of this flag requires the -.B CAP_SYS_ADMIN -capability. -.TP -.B FAN_MARK_IGNORED_MASK -The events in -.I mask -shall be added to or removed from the ignore mask. -Note that the flags -.BR FAN_ONDIR , -and -.B FAN_EVENT_ON_CHILD -have no effect when provided with this flag. -The effect of setting the flags -.BR FAN_ONDIR , -and -.B FAN_EVENT_ON_CHILD -in the mark mask -on the events that are set in the ignore mask -is undefined and depends on the Linux kernel version. -Specifically, prior to Linux 5.9, -.\" commit 497b0c5a7c0688c1b100a9c2e267337f677c198e -setting a mark mask on a file -and a mark with ignore mask on its parent directory -would not result in ignoring events on the file, -regardless of the -.B FAN_EVENT_ON_CHILD -flag in the parent directory's mark mask. -When the ignore mask is updated with the -.B FAN_MARK_IGNORED_MASK -flag -on a mark that was previously updated with the -.B FAN_MARK_IGNORE -flag, -the update fails with -.B EEXIST -error. -.TP -.BR FAN_MARK_IGNORE " (since Linux 6.0)" -.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0 -This flag has a similar effect as setting the -.B FAN_MARK_IGNORED_MASK -flag. -The events in -.I mask -shall be added to or removed from the ignore mask. -Unlike the -.B FAN_MARK_IGNORED_MASK -flag, -this flag also has the effect that the -.BR FAN_ONDIR , -and -.B FAN_EVENT_ON_CHILD -flags take effect on the ignore mask. -Specifically, unless the -.B FAN_ONDIR -flag is set with -.BR FAN_MARK_IGNORE , -events on directories will not be ignored. -If the flag -.B FAN_EVENT_ON_CHILD -is set with -.BR FAN_MARK_IGNORE , -events on children will be ignored. -For example, -a mark on a directory with combination of -a mask with -.B FAN_CREATE -event -and -.B FAN_ONDIR -flag -and an ignore mask with -.B FAN_CREATE -event -and without -.B FAN_ONDIR -flag, -will result in getting only -the events for creation of sub-directories. -When using the -.B FAN_MARK_IGNORE -flag to add to an ignore mask -of a mount, -filesystem, -or directory inode mark, -the -.B FAN_MARK_IGNORED_SURV_MODIFY -flag must be specified. -Failure to do so will results with -.B EINVAL -or -.B EISDIR -error. -.TP -.B FAN_MARK_IGNORED_SURV_MODIFY -The ignore mask shall survive modify events. -If this flag is not set, -the ignore mask is cleared when a modify event occurs -on the marked object. -Omitting this flag is typically used to suppress events -(e.g., -.BR FAN_OPEN ) -for a specific file, -until that specific file's content has been modified. -It is far less useful to suppress events -on an entire filesystem, -or mount, -or on all files inside a directory, -until some file's content has been modified. -For this reason, -the -.B FAN_MARK_IGNORE -flag requires the -.B FAN_MARK_IGNORED_SURV_MODIFY -flag on a mount, -filesystem, -or directory inode mark. -This flag cannot be removed from a mark once set. -When the ignore mask is updated without this flag -on a mark that was previously updated with the -.B FAN_MARK_IGNORE -and -.B FAN_MARK_IGNORED_SURV_MODIFY -flags, -the update fails with -.B EEXIST -error. -.TP -.B FAN_MARK_IGNORE_SURV -This is a synonym for -.RB ( FAN_MARK_IGNORE | FAN_MARK_IGNORED_SURV_MODIFY ). -.TP -.BR FAN_MARK_EVICTABLE " (since Linux 5.19)" -.\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c -When an inode mark is created with this flag, -the inode object will not be pinned to the inode cache, -therefore, -allowing the inode object to be evicted from the inode cache -when the memory pressure on the system is high. -The eviction of the inode object -results in the evictable mark also being lost. -When the mask of an evictable inode mark is updated -without using the -.B FAN_MARK_EVICATBLE -flag, -the marked inode is pinned to inode cache -and the mark is no longer evictable. -When the mask of a non-evictable inode mark is updated -with the -.B FAN_MARK_EVICTABLE -flag, -the inode mark remains non-evictable -and the update fails with -.B EEXIST -error. -Mounts and filesystems are not evictable objects, -therefore, -an attempt to create a mount mark or a filesystem mark -with the -.B FAN_MARK_EVICTABLE -flag, -will result in the error -.BR EINVAL . -For example, -inode marks can be used in combination with mount marks -to reduce the amount of events from noninteresting paths. -The event listener reads events, -checks if the path reported in the event is of interest, -and if it is not, -the listener sets a mark with an ignore mask on the directory. -Evictable inode marks allow using this method for a large number of directories -without the concern of pinning all inodes and exhausting the system's memory. -.PP -.I mask -defines which events shall be listened for (or which shall be ignored). -It is a bit mask composed of the following values: -.TP -.B FAN_ACCESS -Create an event when a file or directory (but see BUGS) is accessed (read). -.TP -.B FAN_MODIFY -Create an event when a file is modified (write). -.TP -.B FAN_CLOSE_WRITE -Create an event when a writable file is closed. -.TP -.B FAN_CLOSE_NOWRITE -Create an event when a read-only file or directory is closed. -.TP -.B FAN_OPEN -Create an event when a file or directory is opened. -.TP -.BR FAN_OPEN_EXEC " (since Linux 5.0)" -.\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa -Create an event when a file is opened with the intent to be executed. -See NOTES for additional details. -.TP -.BR FAN_ATTRIB " (since Linux 5.1)" -.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 -Create an event when the metadata for a file or directory has changed. -An fanotify group that identifies filesystem objects by file handles -is required. -.TP -.BR FAN_CREATE " (since Linux 5.1)" -.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 -Create an event when a file or directory has been created in a marked -parent directory. -An fanotify group that identifies filesystem objects by file handles -is required. -.TP -.BR FAN_DELETE " (since Linux 5.1)" -.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 -Create an event when a file or directory has been deleted in a marked -parent directory. -An fanotify group that identifies filesystem objects by file handles -is required. -.TP -.BR FAN_DELETE_SELF " (since Linux 5.1)" -.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 -Create an event when a marked file or directory itself is deleted. -An fanotify group that identifies filesystem objects by file handles -is required. -.TP -.BR FAN_FS_ERROR " (since Linux 5.16)" -.\" commit 9709bd548f11a092d124698118013f66e1740f9b -Create an event when a filesystem error -leading to inconsistent filesystem metadata is detected. -An additional information record of type -.B FAN_EVENT_INFO_TYPE_ERROR -is returned for each event in the read buffer. -An fanotify group that identifies filesystem objects by file handles -is required. -.IP -Events of such type are dependent on support -from the underlying filesystem. -At the time of writing, -only the -.B ext4 -filesystem reports -.B FAN_FS_ERROR -events. -.IP -See -.BR fanotify (7) -for additional details. -.TP -.BR FAN_MOVED_FROM " (since Linux 5.1)" -.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 -Create an event when a file or directory has been moved from a marked -parent directory. -An fanotify group that identifies filesystem objects by file handles -is required. -.TP -.BR FAN_MOVED_TO " (since Linux 5.1)" -.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 -Create an event when a file or directory has been moved to a marked parent -directory. -An fanotify group that identifies filesystem objects by file handles -is required. -.TP -.BR FAN_RENAME " (since Linux 5.17)" -.\" commit 8cc3b1ccd930fe6971e1527f0c4f1bdc8cb56026 -This event contains the same information provided by events -.B FAN_MOVED_FROM -and -.BR FAN_MOVED_TO , -however is represented by a single event with up to two information records. -An fanotify group that identifies filesystem objects by file handles -is required. -If the filesystem object to be marked is not a directory, the error -.B ENOTDIR -shall be raised. -.TP -.BR FAN_MOVE_SELF " (since Linux 5.1)" -.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 -Create an event when a marked file or directory itself has been moved. -An fanotify group that identifies filesystem objects by file handles -is required. -.TP -.B FAN_OPEN_PERM -Create an event when a permission to open a file or directory is requested. -An fanotify file descriptor created with -.B FAN_CLASS_PRE_CONTENT -or -.B FAN_CLASS_CONTENT -is required. -.TP -.BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)" -.\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9 -Create an event when a permission to open a file for execution is -requested. -An fanotify file descriptor created with -.B FAN_CLASS_PRE_CONTENT -or -.B FAN_CLASS_CONTENT -is required. -See NOTES for additional details. -.TP -.B FAN_ACCESS_PERM -Create an event when a permission to read a file or directory is requested. -An fanotify file descriptor created with -.B FAN_CLASS_PRE_CONTENT -or -.B FAN_CLASS_CONTENT -is required. -.TP -.B FAN_ONDIR -Create events for directories\[em]for example, when -.BR opendir (3), -.BR readdir (3) -(but see BUGS), and -.BR closedir (3) -are called. -Without this flag, events are created only for files. -In the context of directory entry events, such as -.BR FAN_CREATE , -.BR FAN_DELETE , -.BR FAN_MOVED_FROM , -and -.BR FAN_MOVED_TO , -specifying the flag -.B FAN_ONDIR -is required in order to create events when subdirectory entries are -modified (i.e., -.BR mkdir (2)/ -.BR rmdir (2)). -.TP -.B FAN_EVENT_ON_CHILD -Events for the immediate children of marked directories shall be created. -The flag has no effect when marking mounts and filesystems. -Note that events are not generated for children of the subdirectories -of marked directories. -More specifically, the directory entry modification events -.BR FAN_CREATE , -.BR FAN_DELETE , -.BR FAN_MOVED_FROM , -and -.B FAN_MOVED_TO -are not generated for any entry modifications performed inside subdirectories -of marked directories. -Note that the events -.B FAN_DELETE_SELF -and -.B FAN_MOVE_SELF -are not generated for children of marked directories. -To monitor complete directory trees it is necessary to mark the relevant -mount or filesystem. -.PP -The following composed values are defined: -.TP -.B FAN_CLOSE -A file is closed -.RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ). -.TP -.B FAN_MOVE -A file or directory has been moved -.RB ( FAN_MOVED_FROM | FAN_MOVED_TO ). -.PP -The filesystem object to be marked is determined by the file descriptor -.I dirfd -and the pathname specified in -.IR pathname : -.IP \[bu] 3 -If -.I pathname -is NULL, -.I dirfd -defines the filesystem object to be marked. -.IP \[bu] -If -.I pathname -is NULL, and -.I dirfd -takes the special value -.BR AT_FDCWD , -the current working directory is to be marked. -.IP \[bu] -If -.I pathname -is absolute, it defines the filesystem object to be marked, and -.I dirfd -is ignored. -.IP \[bu] -If -.I pathname -is relative, and -.I dirfd -does not have the value -.BR AT_FDCWD , -then the filesystem object to be marked is determined by interpreting -.I pathname -relative the directory referred to by -.IR dirfd . -.IP \[bu] -If -.I pathname -is relative, and -.I dirfd -has the value -.BR AT_FDCWD , -then the filesystem object to be marked is determined by interpreting -.I pathname -relative to the current working directory. -(See -.BR openat (2) -for an explanation of why the -.I dirfd -argument is useful.) -.SH RETURN VALUE -On success, -.BR fanotify_mark () -returns 0. -On error, \-1 is returned, and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.B EBADF -An invalid file descriptor was passed in -.IR fanotify_fd . -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP -.B EEXIST -The filesystem object indicated by -.I dirfd -and -.I pathname -has a mark that was updated without the -.B FAN_MARK_EVICTABLE -flag, -and the user attempted to update the mark with -.B FAN_MARK_EVICTABLE -flag. -.TP -.B EEXIST -The filesystem object indicated by -.I dirfd -and -.I pathname -has a mark that was updated with the -.B FAN_MARK_IGNORE -flag, -and the user attempted to update the mark with -.B FAN_MARK_IGNORED_MASK -flag. -.TP -.B EEXIST -The filesystem object indicated by -.I dirfd -and -.I pathname -has a mark that was updated with the -.B FAN_MARK_IGNORE -and -.B FAN_MARK_IGNORED_SURV_MODIFY -flags, -and the user attempted to update the mark only with -.B FAN_MARK_IGNORE -flag. -.TP -.B EINVAL -An invalid value was passed in -.I flags -or -.IR mask , -or -.I fanotify_fd -was not an fanotify file descriptor. -.TP -.B EINVAL -The fanotify file descriptor was opened with -.B FAN_CLASS_NOTIF -or the fanotify group identifies filesystem objects by file handles -and mask contains a flag for permission events -.RB ( FAN_OPEN_PERM -or -.BR FAN_ACCESS_PERM ). -.TP -.B EINVAL -The group was initialized without -.B FAN_REPORT_FID -but one or more event types specified in the -.I mask -require it. -.TP -.B EINVAL -.I flags -contains -.BR FAN_MARK_IGNORE , -and either -.B FAN_MARK_MOUNT -or -.BR FAN_MARK_FILESYSTEM , -but does not contain -.BR FAN_MARK_IGNORED_SURV_MODIFY . -.TP -.B EISDIR -.I flags -contains -.BR FAN_MARK_IGNORE , -but does not contain -.BR FAN_MARK_IGNORED_SURV_MODIFY , -and -.I dirfd -and -.I pathname -specify a directory. -.TP -.B ENODEV -The filesystem object indicated by -.I dirfd -and -.I pathname -is not associated with a filesystem that supports -.I fsid -(e.g., -.BR fuse (4)). -.BR tmpfs (5) -did not support -.I fsid -prior to Linux 5.13. -.\" commit 59cda49ecf6c9a32fae4942420701b6e087204f6 -This error can be returned only with an fanotify group that identifies -filesystem objects by file handles. -.TP -.B ENOENT -The filesystem object indicated by -.I dirfd -and -.I pathname -does not exist. -This error also occurs when trying to remove a mark from an object -which is not marked. -.TP -.B ENOMEM -The necessary memory could not be allocated. -.TP -.B ENOSPC -The number of marks for this user exceeds the limit and the -.B FAN_UNLIMITED_MARKS -flag was not specified when the fanotify file descriptor was created with -.BR fanotify_init (2). -See -.BR fanotify (7) -for details about this limit. -.TP -.B ENOSYS -This kernel does not implement -.BR fanotify_mark (). -The fanotify API is available only if the kernel was configured with -.BR CONFIG_FANOTIFY . -.TP -.B ENOTDIR -.I flags -contains -.BR FAN_MARK_ONLYDIR , -and -.I dirfd -and -.I pathname -do not specify a directory. -.TP -.B ENOTDIR -.I mask -contains -.BR FAN_RENAME , -and -.I dirfd -and -.I pathname -do not specify a directory. -.TP -.B ENOTDIR -.I flags -contains -.BR FAN_MARK_IGNORE , -or the fanotify group was initialized with flag -.BR FAN_REPORT_TARGET_FID , -and -.I mask -contains directory entry modification events -(e.g., -.BR FAN_CREATE , -.BR FAN_DELETE ), -or directory event flags -(e.g., -.BR FAN_ONDIR , -.BR FAN_EVENT_ON_CHILD ), -and -.I dirfd -and -.I pathname -do not specify a directory. -.TP -.B EOPNOTSUPP -The object indicated by -.I pathname -is associated with a filesystem that does not support the encoding of file -handles. -This error can be returned only with an fanotify group that identifies -filesystem objects by file handles. -.TP -.B EPERM -The operation is not permitted because the caller lacks a required capability. -.TP -.B EXDEV -The filesystem object indicated by -.I pathname -resides within a filesystem subvolume (e.g., -.BR btrfs (5)) -which uses a different -.I fsid -than its root superblock. -This error can be returned only with an fanotify group that identifies -filesystem objects by file handles. -.SH STANDARDS -Linux. -.SH HISTORY -Linux 2.6.37. -.\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37. -.SH NOTES -.SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM -When using either -.B FAN_OPEN_EXEC -or -.B FAN_OPEN_EXEC_PERM -within the -.IR mask , -events of these types will be returned only when the direct execution of a -program occurs. -More specifically, this means that events of these types will be generated -for files that are opened using -.BR execve (2), -.BR execveat (2), -or -.BR uselib (2). -Events of these types will not be raised in the situation where an -interpreter is passed (or reads) a file for interpretation. -.PP -Additionally, if a mark has also been placed on the Linux dynamic -linker, a user should also expect to receive an event for it when -an ELF object has been successfully opened using -.BR execve (2) -or -.BR execveat (2). -.PP -For example, if the following ELF binary were to be invoked and a -.B FAN_OPEN_EXEC -mark has been placed on /: -.PP -.in +4n -.EX -$ /bin/echo foo -.EE -.in -.PP -The listening application in this case would receive -.B FAN_OPEN_EXEC -events for both the ELF binary and interpreter, respectively: -.PP -.in +4n -.EX -/bin/echo -/lib64/ld\-linux\-x86\-64.so.2 -.EE -.in -.SH BUGS -The following bugs were present in before Linux 3.16: -.IP \[bu] 3 -.\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563 -If -.I flags -contains -.BR FAN_MARK_FLUSH , -.IR dirfd , -and -.I pathname -must specify a valid filesystem object, even though this object is not used. -.IP \[bu] -.\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b -.BR readdir (2) -does not generate a -.B FAN_ACCESS -event. -.IP \[bu] -.\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406 -If -.BR fanotify_mark () -is called with -.BR FAN_MARK_FLUSH , -.I flags -is not checked for invalid values. -.SH SEE ALSO -.BR fanotify_init (2), -.BR fanotify (7) |