1fanotify_mark(2)              System Calls Manual             fanotify_mark(2)
2
3
4

NAME

6       fanotify_mark - add, remove, or modify an fanotify mark on a filesystem
7       object
8

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

13       #include <sys/fanotify.h>
14
15       int fanotify_mark(int fanotify_fd, unsigned int flags,
16                         uint64_t mask, int dirfd,
17                         const char *_Nullable pathname);
18

DESCRIPTION

20       For an overview of the fanotify API, see fanotify(7).
21
22       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
26       The  fanotify_fd  argument  is  a  file  descriptor  returned  by  fan‐
27       otify_init(2).
28
29       flags  is  a  bit mask describing the modification to perform.  It must
30       include exactly one of the following values:
31
32       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
37       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
42       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
53       If none of the values above is specified, or more than  one  is  speci‐
54       fied, the call fails with the error EINVAL.
55
56       In  addition,  zero  or  more  of the following values may be ORed into
57       flags:
58
59       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
64       FAN_MARK_ONLYDIR
65              If the filesystem object to be marked is not  a  directory,  the
66              error ENOTDIR shall be raised.
67
68       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
79       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
85       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
100       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
118       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
134       FAN_MARK_IGNORE_SURV
135              This   is   a    synonym    for    (FAN_MARK_IGNORE|FAN_MARK_IG‐
136              NORED_SURV_MODIFY).
137
138       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
161       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
164       FAN_ACCESS
165              Create an event when a file or directory (but see BUGS)  is  ac‐
166              cessed (read).
167
168       FAN_MODIFY
169              Create an event when a file is modified (write).
170
171       FAN_CLOSE_WRITE
172              Create an event when a writable file is closed.
173
174       FAN_CLOSE_NOWRITE
175              Create an event when a read-only file or directory is closed.
176
177       FAN_OPEN
178              Create an event when a file or directory is opened.
179
180       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
184       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
189       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
194       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
199       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
204       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
211              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
215              See fanotify(7) for additional details.
216
217       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
222       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
227       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
235       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
240       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
245       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
251       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
256       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
265       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
278       The following composed values are defined:
279
280       FAN_CLOSE
281              A file is closed (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE).
282
283       FAN_MOVE
284              A      file      or      directory      has      been      moved
285              (FAN_MOVED_FROM|FAN_MOVED_TO).
286
287       The filesystem object to be marked is determined by the file descriptor
288       dirfd and the pathname specified in pathname:
289
290       •  If pathname is NULL, dirfd  defines  the  filesystem  object  to  be
291          marked.
292
293       •  If pathname is NULL, and dirfd takes the special value AT_FDCWD, the
294          current working directory is to be marked.
295
296       •  If pathname is absolute, it defines  the  filesystem  object  to  be
297          marked, and dirfd is ignored.
298
299       •  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
303       •  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

RETURN VALUE

309       On success, fanotify_mark() returns 0.  On error, -1 is  returned,  and
310       errno is set to indicate the error.
311

ERRORS

313       EBADF  An invalid file descriptor was passed in fanotify_fd.
314
315       EBADF  pathname  is  relative but dirfd is neither AT_FDCWD nor a valid
316              file descriptor.
317
318       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
322       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
326       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
331       EINVAL An invalid value was passed in flags or mask, or fanotify_fd was
332              not an fanotify file descriptor.
333
334       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
339       EINVAL The group was initialized without FAN_REPORT_FID but one or more
340              event types specified in the mask require it.
341
342       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
346       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
350       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
356       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
360       ENOMEM The necessary memory could not be allocated.
361
362       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
367       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
371       ENOTDIR
372              flags  contains  FAN_MARK_ONLYDIR, and dirfd and pathname do not
373              specify a directory.
374
375       ENOTDIR
376              mask contains FAN_RENAME, and dirfd and pathname do not  specify
377              a directory.
378
379       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
387       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
393       EPERM  The  operation  is  not permitted because the caller lacks a re‐
394              quired capability.
395
396       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

STANDARDS

403       Linux.
404

HISTORY

406       Linux 2.6.37.
407

NOTES

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
418       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
422       For example, if the following ELF binary  were  to  be  invoked  and  a
423       FAN_OPEN_EXEC mark has been placed on /:
424
425           $ /bin/echo foo
426
427       The  listening  application  in  this  case would receive FAN_OPEN_EXEC
428       events for both the ELF binary and interpreter, respectively:
429
430           /bin/echo
431           /lib64/ld-linux-x86-64.so.2
432

BUGS

434       The following bugs were present in before Linux 3.16:
435
436       •  If flags contains FAN_MARK_FLUSH, dirfd, and pathname must specify a
437          valid filesystem object, even though this object is not used.
438
439readdir(2) does not generate a FAN_ACCESS event.
440
441       •  If  fanotify_mark()  is  called  with  FAN_MARK_FLUSH,  flags is not
442          checked for invalid values.
443

SEE ALSO

445       fanotify_init(2), fanotify(7)
446
447
448
449Linux man-pages 6.04              2023-03-30                  fanotify_mark(2)
Impressum