diff options
Diffstat (limited to '')
| -rw-r--r-- | man2/fanotify_mark.2 | 843 |
1 files changed, 843 insertions, 0 deletions
diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 new file mode 100644 index 0000000..d1f7eec --- /dev/null +++ b/man2/fanotify_mark.2 @@ -0,0 +1,843 @@ +.\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH fanotify_mark 2 2023-03-30 "Linux man-pages 6.05.01" +.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) |