1fanotify_mark(2) System Calls Manual fanotify_mark(2)
2
6 fanotify_mark - add, remove, or modify an fanotify mark on a filesystem
7 object
8
10 Standard C library (libc, -lc)
11
13 #include <sys/fanotify.h>
14 int fanotify_mark(int fanotify_fd, unsigned int flags,
16 uint64_t mask, int dirfd,
17 const char *_Nullable pathname);
18
20 For an overview of the fanotify API, see fanotify(7).
21 fanotify_mark() adds, removes, or modifies an fanotify mark on a
23 filesystem object. The caller must have read permission on the
24 filesystem object that is to be marked.
25 The fanotify_fd argument is a file descriptor returned by fan‐
27 otify_init(2).
28 flags is a bit mask describing the modification to perform. It must
30 include exactly one of the following values:
31 FAN_MARK_ADD
33 The events in mask will be added to the mark mask (or to the ig‐
34 nore mask). mask must be nonempty or the error EINVAL will oc‐
35 cur.
36 FAN_MARK_REMOVE
38 The events in argument mask will be removed from the mark mask
39 (or from the ignore mask). mask must be nonempty or the error
40 EINVAL will occur.
41 FAN_MARK_FLUSH
43 Remove either all marks for filesystems, all marks for mounts,
44 or all marks for directories and files from the fanotify group.
45 If flags contains FAN_MARK_MOUNT, all marks for mounts are re‐
46 moved from the group. If flags contains FAN_MARK_FILESYSTEM,
47 all marks for filesystems are removed from the group. Other‐
48 wise, all marks for directories and files are removed. No flag
49 other than, and at most one of, the flags FAN_MARK_MOUNT or
50 FAN_MARK_FILESYSTEM can be used in conjunction with
51 FAN_MARK_FLUSH. mask is ignored.
52 If none of the values above is specified, or more than one is speci‐
54 fied, the call fails with the error EINVAL.
55 In addition, zero or more of the following values may be ORed into
57 flags:
58 FAN_MARK_DONT_FOLLOW
60 If pathname is a symbolic link, mark the link itself, rather
61 than the file to which it refers. (By default, fanotify_mark()
62 dereferences pathname if it is a symbolic link.)
63 FAN_MARK_ONLYDIR
65 If the filesystem object to be marked is not a directory, the
66 error ENOTDIR shall be raised.
67 FAN_MARK_MOUNT
69 Mark the mount specified by pathname. If pathname is not itself
70 a mount point, the mount containing pathname will be marked.
71 All directories, subdirectories, and the contained files of the
72 mount will be monitored. The events which require that filesys‐
73 tem objects are identified by file handles, such as FAN_CREATE,
74 FAN_ATTRIB, FAN_MOVE, and FAN_DELETE_SELF, cannot be provided as
75 a mask when flags contains FAN_MARK_MOUNT. Attempting to do so
76 will result in the error EINVAL being returned. Use of this
77 flag requires the CAP_SYS_ADMIN capability.
78 FAN_MARK_FILESYSTEM (since Linux 4.20)
80 Mark the filesystem specified by pathname. The filesystem con‐
81 taining pathname will be marked. All the contained files and
82 directories of the filesystem from any mount point will be moni‐
83 tored. Use of this flag requires the CAP_SYS_ADMIN capability.
84 FAN_MARK_IGNORED_MASK
86 The events in mask shall be added to or removed from the ignore
87 mask. Note that the flags FAN_ONDIR, and FAN_EVENT_ON_CHILD
88 have no effect when provided with this flag. The effect of set‐
89 ting the flags FAN_ONDIR, and FAN_EVENT_ON_CHILD in the mark
90 mask on the events that are set in the ignore mask is undefined
91 and depends on the Linux kernel version. Specifically, prior to
92 Linux 5.9, setting a mark mask on a file and a mark with ignore
93 mask on its parent directory would not result in ignoring events
94 on the file, regardless of the FAN_EVENT_ON_CHILD flag in the
95 parent directory's mark mask. When the ignore mask is updated
96 with the FAN_MARK_IGNORED_MASK flag on a mark that was previ‐
97 ously updated with the FAN_MARK_IGNORE flag, the update fails
98 with EEXIST error.
99 FAN_MARK_IGNORE (since Linux 6.0)
101 This flag has a similar effect as setting the FAN_MARK_IG‐
102 NORED_MASK flag. The events in mask shall be added to or re‐
103 moved from the ignore mask. Unlike the FAN_MARK_IGNORED_MASK
104 flag, this flag also has the effect that the FAN_ONDIR, and
105 FAN_EVENT_ON_CHILD flags take effect on the ignore mask.
106 Specifically, unless the FAN_ONDIR flag is set with FAN_MARK_IG‐
107 NORE, events on directories will not be ignored. If the flag
108 FAN_EVENT_ON_CHILD is set with FAN_MARK_IGNORE, events on chil‐
109 dren will be ignored. For example, a mark on a directory with
110 combination of a mask with FAN_CREATE event and FAN_ONDIR flag
111 and an ignore mask with FAN_CREATE event and without FAN_ONDIR
112 flag, will result in getting only the events for creation of
113 sub-directories. When using the FAN_MARK_IGNORE flag to add to
114 an ignore mask of a mount, filesystem, or directory inode mark,
115 the FAN_MARK_IGNORED_SURV_MODIFY flag must be specified. Fail‐
116 ure to do so will results with EINVAL or EISDIR error.
117 FAN_MARK_IGNORED_SURV_MODIFY
119 The ignore mask shall survive modify events. If this flag is
120 not set, the ignore mask is cleared when a modify event occurs
121 on the marked object. Omitting this flag is typically used to
122 suppress events (e.g., FAN_OPEN) for a specific file, until that
123 specific file's content has been modified. It is far less use‐
124 ful to suppress events on an entire filesystem, or mount, or on
125 all files inside a directory, until some file's content has been
126 modified. For this reason, the FAN_MARK_IGNORE flag requires
127 the FAN_MARK_IGNORED_SURV_MODIFY flag on a mount, filesystem, or
128 directory inode mark. This flag cannot be removed from a mark
129 once set. When the ignore mask is updated without this flag on
130 a mark that was previously updated with the FAN_MARK_IGNORE and
131 FAN_MARK_IGNORED_SURV_MODIFY flags, the update fails with EEXIST
132 error.
133 FAN_MARK_IGNORE_SURV
135 This is a synonym for (FAN_MARK_IGNORE|FAN_MARK_IG‐
136 NORED_SURV_MODIFY).
137 FAN_MARK_EVICTABLE (since Linux 5.19)
139 When an inode mark is created with this flag, the inode object
140 will not be pinned to the inode cache, therefore, allowing the
141 inode object to be evicted from the inode cache when the memory
142 pressure on the system is high. The eviction of the inode ob‐
143 ject results in the evictable mark also being lost. When the
144 mask of an evictable inode mark is updated without using the
145 FAN_MARK_EVICATBLE flag, the marked inode is pinned to inode
146 cache and the mark is no longer evictable. When the mask of a
147 non-evictable inode mark is updated with the FAN_MARK_EVICTABLE
148 flag, the inode mark remains non-evictable and the update fails
149 with EEXIST error. Mounts and filesystems are not evictable ob‐
150 jects, therefore, an attempt to create a mount mark or a
151 filesystem mark with the FAN_MARK_EVICTABLE flag, will result in
152 the error EINVAL. For example, inode marks can be used in com‐
153 bination with mount marks to reduce the amount of events from
154 noninteresting paths. The event listener reads events, checks
155 if the path reported in the event is of interest, and if it is
156 not, the listener sets a mark with an ignore mask on the direc‐
157 tory. Evictable inode marks allow using this method for a large
158 number of directories without the concern of pinning all inodes
159 and exhausting the system's memory.
160 mask defines which events shall be listened for (or which shall be ig‐
162 nored). It is a bit mask composed of the following values:
163 FAN_ACCESS
165 Create an event when a file or directory (but see BUGS) is ac‐
166 cessed (read).
167 FAN_MODIFY
169 Create an event when a file is modified (write).
170 FAN_CLOSE_WRITE
172 Create an event when a writable file is closed.
173 FAN_CLOSE_NOWRITE
175 Create an event when a read-only file or directory is closed.
176 FAN_OPEN
178 Create an event when a file or directory is opened.
179 FAN_OPEN_EXEC (since Linux 5.0)
181 Create an event when a file is opened with the intent to be exe‐
182 cuted. See NOTES for additional details.
183 FAN_ATTRIB (since Linux 5.1)
185 Create an event when the metadata for a file or directory has
186 changed. An fanotify group that identifies filesystem objects
187 by file handles is required.
188 FAN_CREATE (since Linux 5.1)
190 Create an event when a file or directory has been created in a
191 marked parent directory. An fanotify group that identifies
192 filesystem objects by file handles is required.
193 FAN_DELETE (since Linux 5.1)
195 Create an event when a file or directory has been deleted in a
196 marked parent directory. An fanotify group that identifies
197 filesystem objects by file handles is required.
198 FAN_DELETE_SELF (since Linux 5.1)
200 Create an event when a marked file or directory itself is
201 deleted. An fanotify group that identifies filesystem objects
202 by file handles is required.
203 FAN_FS_ERROR (since Linux 5.16)
205 Create an event when a filesystem error leading to inconsistent
206 filesystem metadata is detected. An additional information
207 record of type FAN_EVENT_INFO_TYPE_ERROR is returned for each
208 event in the read buffer. An fanotify group that identifies
209 filesystem objects by file handles is required.
210 Events of such type are dependent on support from the underlying
212 filesystem. At the time of writing, only the ext4 filesystem
213 reports FAN_FS_ERROR events.
214 See fanotify(7) for additional details.
216 FAN_MOVED_FROM (since Linux 5.1)
218 Create an event when a file or directory has been moved from a
219 marked parent directory. An fanotify group that identifies
220 filesystem objects by file handles is required.
221 FAN_MOVED_TO (since Linux 5.1)
223 Create an event when a file or directory has been moved to a
224 marked parent directory. An fanotify group that identifies
225 filesystem objects by file handles is required.
226 FAN_RENAME (since Linux 5.17)
228 This event contains the same information provided by events
229 FAN_MOVED_FROM and FAN_MOVED_TO, however is represented by a
230 single event with up to two information records. An fanotify
231 group that identifies filesystem objects by file handles is re‐
232 quired. If the filesystem object to be marked is not a direc‐
233 tory, the error ENOTDIR shall be raised.
234 FAN_MOVE_SELF (since Linux 5.1)
236 Create an event when a marked file or directory itself has been
237 moved. An fanotify group that identifies filesystem objects by
238 file handles is required.
239 FAN_OPEN_PERM
241 Create an event when a permission to open a file or directory is
242 requested. An fanotify file descriptor created with
243 FAN_CLASS_PRE_CONTENT or FAN_CLASS_CONTENT is required.
244 FAN_OPEN_EXEC_PERM (since Linux 5.0)
246 Create an event when a permission to open a file for execution
247 is requested. An fanotify file descriptor created with
248 FAN_CLASS_PRE_CONTENT or FAN_CLASS_CONTENT is required. See
249 NOTES for additional details.
250 FAN_ACCESS_PERM
252 Create an event when a permission to read a file or directory is
253 requested. An fanotify file descriptor created with
254 FAN_CLASS_PRE_CONTENT or FAN_CLASS_CONTENT is required.
255 FAN_ONDIR
257 Create events for directories—for example, when opendir(3),
258 readdir(3) (but see BUGS), and closedir(3) are called. Without
259 this flag, events are created only for files. In the context of
260 directory entry events, such as FAN_CREATE, FAN_DELETE,
261 FAN_MOVED_FROM, and FAN_MOVED_TO, specifying the flag FAN_ONDIR
262 is required in order to create events when subdirectory entries
263 are modified (i.e., mkdir(2)/ rmdir(2)).
264 FAN_EVENT_ON_CHILD
266 Events for the immediate children of marked directories shall be
267 created. The flag has no effect when marking mounts and
268 filesystems. Note that events are not generated for children of
269 the subdirectories of marked directories. More specifically,
270 the directory entry modification events FAN_CREATE, FAN_DELETE,
271 FAN_MOVED_FROM, and FAN_MOVED_TO are not generated for any entry
272 modifications performed inside subdirectories of marked directo‐
273 ries. Note that the events FAN_DELETE_SELF and FAN_MOVE_SELF
274 are not generated for children of marked directories. To moni‐
275 tor complete directory trees it is necessary to mark the rele‐
276 vant mount or filesystem.
277 The following composed values are defined:
279 FAN_CLOSE
281 A file is closed (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE).
282 FAN_MOVE
284 A file or directory has been moved
285 (FAN_MOVED_FROM|FAN_MOVED_TO).
286 The filesystem object to be marked is determined by the file descriptor
288 dirfd and the pathname specified in pathname:
289 • If pathname is NULL, dirfd defines the filesystem object to be
291 marked.
292 • If pathname is NULL, and dirfd takes the special value AT_FDCWD, the
294 current working directory is to be marked.
295 • If pathname is absolute, it defines the filesystem object to be
297 marked, and dirfd is ignored.
298 • If pathname is relative, and dirfd does not have the value AT_FDCWD,
300 then the filesystem object to be marked is determined by interpret‐
301 ing pathname relative the directory referred to by dirfd.
302 • If pathname is relative, and dirfd has the value AT_FDCWD, then the
304 filesystem object to be marked is determined by interpreting path‐
305 name relative to the current working directory. (See openat(2) for
306 an explanation of why the dirfd argument is useful.)
307
309 On success, fanotify_mark() returns 0. On error, -1 is returned, and
310 errno is set to indicate the error.
311
313 EBADF An invalid file descriptor was passed in fanotify_fd.
314 EBADF pathname is relative but dirfd is neither AT_FDCWD nor a valid
316 file descriptor.
317 EEXIST The filesystem object indicated by dirfd and pathname has a mark
319 that was updated without the FAN_MARK_EVICTABLE flag, and the
320 user attempted to update the mark with FAN_MARK_EVICTABLE flag.
321 EEXIST The filesystem object indicated by dirfd and pathname has a mark
323 that was updated with the FAN_MARK_IGNORE flag, and the user at‐
324 tempted to update the mark with FAN_MARK_IGNORED_MASK flag.
325 EEXIST The filesystem object indicated by dirfd and pathname has a mark
327 that was updated with the FAN_MARK_IGNORE and FAN_MARK_IG‐
328 NORED_SURV_MODIFY flags, and the user attempted to update the
329 mark only with FAN_MARK_IGNORE flag.
330 EINVAL An invalid value was passed in flags or mask, or fanotify_fd was
332 not an fanotify file descriptor.
333 EINVAL The fanotify file descriptor was opened with FAN_CLASS_NOTIF or
335 the fanotify group identifies filesystem objects by file handles
336 and mask contains a flag for permission events (FAN_OPEN_PERM or
337 FAN_ACCESS_PERM).
338 EINVAL The group was initialized without FAN_REPORT_FID but one or more
340 event types specified in the mask require it.
341 EINVAL flags contains FAN_MARK_IGNORE, and either FAN_MARK_MOUNT or
343 FAN_MARK_FILESYSTEM, but does not contain FAN_MARK_IG‐
344 NORED_SURV_MODIFY.
345 EISDIR flags contains FAN_MARK_IGNORE, but does not contain
347 FAN_MARK_IGNORED_SURV_MODIFY, and dirfd and pathname specify a
348 directory.
349 ENODEV The filesystem object indicated by dirfd and pathname is not as‐
351 sociated with a filesystem that supports fsid (e.g., fuse(4)).
352 tmpfs(5) did not support fsid prior to Linux 5.13. This error
353 can be returned only with an fanotify group that identifies
354 filesystem objects by file handles.
355 ENOENT The filesystem object indicated by dirfd and pathname does not
357 exist. This error also occurs when trying to remove a mark from
358 an object which is not marked.
359 ENOMEM The necessary memory could not be allocated.
361 ENOSPC The number of marks for this user exceeds the limit and the
363 FAN_UNLIMITED_MARKS flag was not specified when the fanotify
364 file descriptor was created with fanotify_init(2). See fan‐
365 otify(7) for details about this limit.
366 ENOSYS This kernel does not implement fanotify_mark(). The fanotify
368 API is available only if the kernel was configured with CON‐
369 FIG_FANOTIFY.
370 ENOTDIR
372 flags contains FAN_MARK_ONLYDIR, and dirfd and pathname do not
373 specify a directory.
374 ENOTDIR
376 mask contains FAN_RENAME, and dirfd and pathname do not specify
377 a directory.
378 ENOTDIR
380 flags contains FAN_MARK_IGNORE, or the fanotify group was ini‐
381 tialized with flag FAN_REPORT_TARGET_FID, and mask contains di‐
382 rectory entry modification events (e.g., FAN_CREATE,
383 FAN_DELETE), or directory event flags (e.g., FAN_ONDIR,
384 FAN_EVENT_ON_CHILD), and dirfd and pathname do not specify a di‐
385 rectory.
386 EOPNOTSUPP
388 The object indicated by pathname is associated with a filesystem
389 that does not support the encoding of file handles. This error
390 can be returned only with an fanotify group that identifies
391 filesystem objects by file handles.
392 EPERM The operation is not permitted because the caller lacks a re‐
394 quired capability.
395 EXDEV The filesystem object indicated by pathname resides within a
397 filesystem subvolume (e.g., btrfs(5)) which uses a different
398 fsid than its root superblock. This error can be returned only
399 with an fanotify group that identifies filesystem objects by
400 file handles.
401
403 Linux.
404
406 Linux 2.6.37.
407
409 FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
410 When using either FAN_OPEN_EXEC or FAN_OPEN_EXEC_PERM within the mask,
411 events of these types will be returned only when the direct execution
412 of a program occurs. More specifically, this means that events of
413 these types will be generated for files that are opened using ex‐
414 ecve(2), execveat(2), or uselib(2). Events of these types will not be
415 raised in the situation where an interpreter is passed (or reads) a
416 file for interpretation.
417 Additionally, if a mark has also been placed on the Linux dynamic
419 linker, a user should also expect to receive an event for it when an
420 ELF object has been successfully opened using execve(2) or execveat(2).
421 For example, if the following ELF binary were to be invoked and a
423 FAN_OPEN_EXEC mark has been placed on /:
424 $ /bin/echo foo
426 The listening application in this case would receive FAN_OPEN_EXEC
428 events for both the ELF binary and interpreter, respectively:
429 /bin/echo
431 /lib64/ld-linux-x86-64.so.2
432
434 The following bugs were present in before Linux 3.16:
435 • If flags contains FAN_MARK_FLUSH, dirfd, and pathname must specify a
437 valid filesystem object, even though this object is not used.
438 • readdir(2) does not generate a FAN_ACCESS event.
440 • If fanotify_mark() is called with FAN_MARK_FLUSH, flags is not
442 checked for invalid values.
443
445 fanotify_init(2), fanotify(7)
446Linux man-pages 6.04 2023-03-30 fanotify_mark(2)