| .\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of |
| .\" this manual under the conditions for verbatim copying, provided that |
| .\" the entire resulting derived work is distributed under the terms of |
| .\" a permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume. |
| .\" no responsibility for errors or omissions, or for damages resulting. |
| .\" from the use of the information contained herein. The author(s) may. |
| .\" not have taken the same level of care in the production of this. |
| .\" manual, which is licensed free of charge, as they might when working. |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .TH FANOTIFY_MARK 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem |
| object |
| .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 \ |
| ", const char *" 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 point specified by |
| .IR pathname . |
| If |
| .I pathname |
| is not itself a mount point, the mount point containing |
| .I pathname |
| will be marked. |
| All directories, subdirectories, and the contained files of the mount point |
| 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 |
| .IR mask |
| when |
| .I flags |
| contains |
| .BR FAN_MARK_MOUNT . |
| Attempting to do so will result in the error |
| .B EINVAL |
| being returned. |
| .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. |
| .TP |
| .B FAN_MARK_IGNORED_MASK |
| The events in |
| .I mask |
| shall be added to or removed from the ignore mask. |
| .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 |
| for the ignored file or directory. |
| .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_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_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\(emfor 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 |
| .BR 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 |
| .BR FAN_MOVED_TO |
| are not generated for any entry modifications performed inside subdirectories |
| of marked directories. |
| Note that the events |
| .BR FAN_DELETE_SELF |
| and |
| .BR 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 * 3 |
| If |
| .I pathname |
| is NULL, |
| .I dirfd |
| defines the filesystem object to be marked. |
| .IP * |
| If |
| .I pathname |
| is NULL, and |
| .I dirfd |
| takes the special value |
| .BR AT_FDCWD , |
| the current working directory is to be marked. |
| .IP * |
| If |
| .I pathname |
| is absolute, it defines the filesystem object to be marked, and |
| .I dirfd |
| is ignored. |
| .IP * |
| 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 * |
| 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 the current working directory. |
| .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 EINVAL |
| An invalid value was passed in |
| .IR 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 ENODEV |
| The filesystem object indicated by |
| .I pathname |
| is not associated with a filesystem that supports |
| .I fsid |
| (e.g., |
| .BR tmpfs (5)). |
| 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 |
| .IR dirfd |
| and |
| .IR 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 exceeds the limit of 8192 and the |
| .B FAN_UNLIMITED_MARKS |
| flag was not specified when the fanotify file descriptor was created with |
| .BR fanotify_init (2). |
| .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 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 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 VERSIONS |
| .BR fanotify_mark () |
| was introduced in version 2.6.36 of the Linux kernel and enabled in version |
| 2.6.37. |
| .SH CONFORMING TO |
| This system call is Linux-specific. |
| .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 |
| .BR 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 |
| .BR 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 Linux kernels before version 3.16: |
| .IP * 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 * |
| .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b |
| .BR readdir (2) |
| does not generate a |
| .B FAN_ACCESS |
| event. |
| .IP * |
| .\" 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) |