1 .\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of
9 .\" this manual under the conditions for verbatim copying, provided that
10 .\" the entire resulting derived work is distributed under the terms of
11 .\" a permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume.
15 .\" no responsibility for errors or omissions, or for damages resulting.
16 .\" from the use of the information contained herein. The author(s) may.
17 .\" not have taken the same level of care in the production of this.
18 .\" manual, which is licensed free of charge, as they might when working.
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
24 .TH FANOTIFY_MARK 2 2021-03-22 "Linux" "Linux Programmer's Manual"
26 fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem
30 .B #include <sys/fanotify.h>
32 .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags ,
33 .BI " uint64_t " mask ", int " dirfd \
34 ", const char *" pathname );
37 For an overview of the fanotify API, see
41 adds, removes, or modifies an fanotify mark on a filesystem object.
42 The caller must have read permission on the filesystem object that
47 argument is a file descriptor returned by
48 .BR fanotify_init (2).
51 is a bit mask describing the modification to perform.
52 It must include exactly one of the following values:
57 will be added to the mark mask (or to the ignore mask).
59 must be nonempty or the error
64 The events in argument
66 will be removed from the mark mask (or from the ignore mask).
68 must be nonempty or the error
73 Remove either all marks for filesystems, all marks for mounts, or all
74 marks for directories and files from the fanotify group.
79 all marks for mounts are removed from the group.
83 .BR FAN_MARK_FILESYSTEM ,
84 all marks for filesystems are removed from the group.
85 Otherwise, all marks for directories and files are removed.
86 No flag other than and at most one of the flags
89 .B FAN_MARK_FILESYSTEM
90 can be used in conjunction with
95 If none of the values above is specified, or more than one is specified,
96 the call fails with the error
100 zero or more of the following values may be ORed into
103 .B FAN_MARK_DONT_FOLLOW
106 is a symbolic link, mark the link itself, rather than the file to which it
112 if it is a symbolic link.)
115 If the filesystem object to be marked is not a directory, the error
120 Mark the mount point specified by
124 is not itself a mount point, the mount point containing
127 All directories, subdirectories, and the contained files of the mount point
129 The events which require that filesystem objects are identified by file handles,
135 .BR FAN_DELETE_SELF ,
136 cannot be provided as a
142 Attempting to do so will result in the error
146 .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
147 .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
148 Mark the filesystem specified by
150 The filesystem containing
153 All the contained files and directories of the filesystem from any mount
154 point will be monitored.
156 .B FAN_MARK_IGNORED_MASK
159 shall be added to or removed from the ignore mask.
161 .B FAN_MARK_IGNORED_SURV_MODIFY
162 The ignore mask shall survive modify events.
163 If this flag is not set,
164 the ignore mask is cleared when a modify event occurs
165 for the ignored file or directory.
168 defines which events shall be listened for (or which shall be ignored).
169 It is a bit mask composed of the following values:
172 Create an event when a file or directory (but see BUGS) is accessed (read).
175 Create an event when a file is modified (write).
178 Create an event when a writable file is closed.
181 Create an event when a read-only file or directory is closed.
184 Create an event when a file or directory is opened.
186 .BR FAN_OPEN_EXEC " (since Linux 5.0)"
187 .\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa
188 Create an event when a file is opened with the intent to be executed.
189 See NOTES for additional details.
191 .BR FAN_ATTRIB " (since Linux 5.1)"
192 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
193 Create an event when the metadata for a file or directory has changed.
194 An fanotify group that identifies filesystem objects by file handles
197 .BR FAN_CREATE " (since Linux 5.1)"
198 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
199 Create an event when a file or directory has been created in a marked
201 An fanotify group that identifies filesystem objects by file handles
204 .BR FAN_DELETE " (since Linux 5.1)"
205 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
206 Create an event when a file or directory has been deleted in a marked
208 An fanotify group that identifies filesystem objects by file handles
211 .BR FAN_DELETE_SELF " (since Linux 5.1)"
212 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
213 Create an event when a marked file or directory itself is deleted.
214 An fanotify group that identifies filesystem objects by file handles
217 .BR FAN_MOVED_FROM " (since Linux 5.1)"
218 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
219 Create an event when a file or directory has been moved from a marked
221 An fanotify group that identifies filesystem objects by file handles
224 .BR FAN_MOVED_TO " (since Linux 5.1)"
225 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
226 Create an event when a file or directory has been moved to a marked parent
228 An fanotify group that identifies filesystem objects by file handles
231 .BR FAN_MOVE_SELF " (since Linux 5.1)"
232 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
233 Create an event when a marked file or directory itself has been moved.
234 An fanotify group that identifies filesystem objects by file handles
238 Create an event when a permission to open a file or directory is requested.
239 An fanotify file descriptor created with
240 .B FAN_CLASS_PRE_CONTENT
245 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
246 .\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9
247 Create an event when a permission to open a file for execution is
249 An fanotify file descriptor created with
250 .B FAN_CLASS_PRE_CONTENT
254 See NOTES for additional details.
257 Create an event when a permission to read a file or directory is requested.
258 An fanotify file descriptor created with
259 .B FAN_CLASS_PRE_CONTENT
265 Create events for directories\(emfor example, when
271 Without this flag, events are created only for files.
272 In the context of directory entry events, such as
280 is required in order to create events when subdirectory entries are
285 .B FAN_EVENT_ON_CHILD
286 Events for the immediate children of marked directories shall be created.
287 The flag has no effect when marking mounts and filesystems.
288 Note that events are not generated for children of the subdirectories
289 of marked directories.
290 More specifically, the directory entry modification events
296 are not generated for any entry modifications performed inside subdirectories
297 of marked directories.
302 are not generated for children of marked directories.
303 To monitor complete directory trees it is necessary to mark the relevant
306 The following composed values are defined:
310 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
313 A file or directory has been moved
314 .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ).
316 The filesystem object to be marked is determined by the file descriptor
318 and the pathname specified in
325 defines the filesystem object to be marked.
331 takes the special value
333 the current working directory is to be marked.
337 is absolute, it defines the filesystem object to be marked, and
345 does not have the value
347 then the filesystem object to be marked is determined by interpreting
349 relative the directory referred to by
358 then the filesystem object to be marked is determined by interpreting
360 relative the current working directory.
365 On error, \-1 is returned, and
367 is set to indicate the error.
371 An invalid file descriptor was passed in
375 An invalid value was passed in
381 was not an fanotify file descriptor.
384 The fanotify file descriptor was opened with
386 or the fanotify group identifies filesystem objects by file handles
387 and mask contains a flag for permission events
390 .BR FAN_ACCESS_PERM ).
393 The filesystem object indicated by
395 is not associated with a filesystem that supports
399 This error can be returned only with an fanotify group that identifies
400 filesystem objects by file handles.
403 The filesystem object indicated by
408 This error also occurs when trying to remove a mark from an object
412 The necessary memory could not be allocated.
415 The number of marks exceeds the limit of 8192 and the
416 .B FAN_UNLIMITED_MARKS
417 flag was not specified when the fanotify file descriptor was created with
418 .BR fanotify_init (2).
421 This kernel does not implement
422 .BR fanotify_mark ().
423 The fanotify API is available only if the kernel was configured with
424 .BR CONFIG_FANOTIFY .
429 .BR FAN_MARK_ONLYDIR ,
434 do not specify a directory.
437 The object indicated by
439 is associated with a filesystem that does not support the encoding of file
441 This error can be returned only with an fanotify group that identifies
442 filesystem objects by file handles.
445 The filesystem object indicated by
447 resides within a filesystem subvolume (e.g.,
449 which uses a different
451 than its root superblock.
452 This error can be returned only with an fanotify group that identifies
453 filesystem objects by file handles.
456 was introduced in version 2.6.36 of the Linux kernel and enabled in version
459 This system call is Linux-specific.
461 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
465 .B FAN_OPEN_EXEC_PERM
468 events of these types will be returned only when the direct execution of a
470 More specifically, this means that events of these types will be generated
471 for files that are opened using
476 Events of these types will not be raised in the situation where an
477 interpreter is passed (or reads) a file for interpretation.
479 Additionally, if a mark has also been placed on the Linux dynamic
480 linker, a user should also expect to receive an event for it when
481 an ELF object has been successfully opened using
486 For example, if the following ELF binary were to be invoked and a
488 mark has been placed on /:
496 The listening application in this case would receive
498 events for both the ELF binary and interpreter, respectively:
503 /lib64/ld\-linux\-x86\-64.so.2
507 The following bugs were present in Linux kernels before version 3.16:
509 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
517 must specify a valid filesystem object, even though this object is not used.
519 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
525 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
531 is not checked for invalid values.
533 .BR fanotify_init (2),