1FANOTIFY_MARK(2)           Linux Programmer's Manual          FANOTIFY_MARK(2)
2
3
4

NAME

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

SYNOPSIS

10       #include <sys/fanotify.h>
11
12       int fanotify_mark(int fanotify_fd, unsigned int flags,
13                         uint64_t mask, int dirfd, const char *pathname);
14

DESCRIPTION

16       For an overview of the fanotify API, see fanotify(7).
17
18       fanotify_mark() adds, removes,  or  modifies  an  fanotify  mark  on  a
19       filesystem  object.   The  caller  must  have  read  permission  on the
20       filesystem object that is to be marked.
21
22       The  fanotify_fd  argument  is  a  file  descriptor  returned  by  fan‐
23       otify_init(2).
24
25       flags  is  a  bit mask describing the modification to perform.  It must
26       include exactly one of the following values:
27
28       FAN_MARK_ADD
29              The events in mask will be added to the mark mask (or to the ig‐
30              nore  mask).  mask must be nonempty or the error EINVAL will oc‐
31              cur.
32
33       FAN_MARK_REMOVE
34              The events in argument mask will be removed from the  mark  mask
35              (or  from  the ignore mask).  mask must be nonempty or the error
36              EINVAL will occur.
37
38       FAN_MARK_FLUSH
39              Remove either all marks for filesystems, all marks  for  mounts,
40              or  all marks for directories and files from the fanotify group.
41              If flags contains FAN_MARK_MOUNT, all marks for mounts  are  re‐
42              moved  from  the  group.  If flags contains FAN_MARK_FILESYSTEM,
43              all marks for filesystems are removed from  the  group.   Other‐
44              wise,  all marks for directories and files are removed.  No flag
45              other than, and at most one  of,  the  flags  FAN_MARK_MOUNT  or
46              FAN_MARK_FILESYSTEM    can   be   used   in   conjunction   with
47              FAN_MARK_FLUSH.  mask is ignored.
48
49       If none of the values above is specified, or more than  one  is  speci‐
50       fied, the call fails with the error EINVAL.
51
52       In  addition,  zero  or  more  of the following values may be ORed into
53       flags:
54
55       FAN_MARK_DONT_FOLLOW
56              If pathname is a symbolic link, mark  the  link  itself,  rather
57              than  the file to which it refers.  (By default, fanotify_mark()
58              dereferences pathname if it is a symbolic link.)
59
60       FAN_MARK_ONLYDIR
61              If the filesystem object to be marked is not  a  directory,  the
62              error ENOTDIR shall be raised.
63
64       FAN_MARK_MOUNT
65              Mark the mount specified by pathname.  If pathname is not itself
66              a mount point, the mount containing  pathname  will  be  marked.
67              All  directories, subdirectories, and the contained files of the
68              mount will be monitored.  The events which require that filesys‐
69              tem  objects are identified by file handles, such as FAN_CREATE,
70              FAN_ATTRIB, FAN_MOVE, and FAN_DELETE_SELF, cannot be provided as
71              a  mask when flags contains FAN_MARK_MOUNT.  Attempting to do so
72              will result in the error EINVAL being returned.
73
74       FAN_MARK_FILESYSTEM (since Linux 4.20)
75              Mark the filesystem specified by pathname.  The filesystem  con‐
76              taining  pathname  will  be marked.  All the contained files and
77              directories of the filesystem from any mount point will be moni‐
78              tored.
79
80       FAN_MARK_IGNORED_MASK
81              The  events in mask shall be added to or removed from the ignore
82              mask.
83
84       FAN_MARK_IGNORED_SURV_MODIFY
85              The ignore mask shall survive modify events.  If  this  flag  is
86              not  set,  the ignore mask is cleared when a modify event occurs
87              for the ignored file or directory.
88
89       mask defines which events shall be listened for (or which shall be  ig‐
90       nored).  It is a bit mask composed of the following values:
91
92       FAN_ACCESS
93              Create  an  event when a file or directory (but see BUGS) is ac‐
94              cessed (read).
95
96       FAN_MODIFY
97              Create an event when a file is modified (write).
98
99       FAN_CLOSE_WRITE
100              Create an event when a writable file is closed.
101
102       FAN_CLOSE_NOWRITE
103              Create an event when a read-only file or directory is closed.
104
105       FAN_OPEN
106              Create an event when a file or directory is opened.
107
108       FAN_OPEN_EXEC (since Linux 5.0)
109              Create an event when a file is opened with the intent to be exe‐
110              cuted.  See NOTES for additional details.
111
112       FAN_ATTRIB (since Linux 5.1)
113              Create  an  event  when the metadata for a file or directory has
114              changed.  An fanotify group that identifies  filesystem  objects
115              by file handles is required.
116
117       FAN_CREATE (since Linux 5.1)
118              Create  an  event when a file or directory has been created in a
119              marked parent directory.   An  fanotify  group  that  identifies
120              filesystem objects by file handles is required.
121
122       FAN_DELETE (since Linux 5.1)
123              Create  an  event when a file or directory has been deleted in a
124              marked parent directory.   An  fanotify  group  that  identifies
125              filesystem objects by file handles is required.
126
127       FAN_DELETE_SELF (since Linux 5.1)
128              Create  an  event  when  a  marked  file  or directory itself is
129              deleted.  An fanotify group that identifies  filesystem  objects
130              by file handles is required.
131
132       FAN_MOVED_FROM (since Linux 5.1)
133              Create  an  event when a file or directory has been moved from a
134              marked parent directory.   An  fanotify  group  that  identifies
135              filesystem objects by file handles is required.
136
137       FAN_MOVED_TO (since Linux 5.1)
138              Create  an  event  when  a file or directory has been moved to a
139              marked parent directory.   An  fanotify  group  that  identifies
140              filesystem objects by file handles is required.
141
142       FAN_MOVE_SELF (since Linux 5.1)
143              Create  an event when a marked file or directory itself has been
144              moved.  An fanotify group that identifies filesystem objects  by
145              file handles is required.
146
147       FAN_OPEN_PERM
148              Create an event when a permission to open a file or directory is
149              requested.    An   fanotify   file   descriptor   created   with
150              FAN_CLASS_PRE_CONTENT or FAN_CLASS_CONTENT is required.
151
152       FAN_OPEN_EXEC_PERM (since Linux 5.0)
153              Create  an  event when a permission to open a file for execution
154              is  requested.   An  fanotify  file  descriptor   created   with
155              FAN_CLASS_PRE_CONTENT  or  FAN_CLASS_CONTENT  is  required.  See
156              NOTES for additional details.
157
158       FAN_ACCESS_PERM
159              Create an event when a permission to read a file or directory is
160              requested.    An   fanotify   file   descriptor   created   with
161              FAN_CLASS_PRE_CONTENT or FAN_CLASS_CONTENT is required.
162
163       FAN_ONDIR
164              Create events  for  directories—for  example,  when  opendir(3),
165              readdir(3)  (but see BUGS), and closedir(3) are called.  Without
166              this flag, events are created only for files.  In the context of
167              directory   entry   events,   such  as  FAN_CREATE,  FAN_DELETE,
168              FAN_MOVED_FROM, and FAN_MOVED_TO, specifying the flag  FAN_ONDIR
169              is  required in order to create events when subdirectory entries
170              are modified (i.e., mkdir(2)/ rmdir(2)).
171
172       FAN_EVENT_ON_CHILD
173              Events for the immediate children of marked directories shall be
174              created.   The  flag  has  no  effect  when  marking  mounts and
175              filesystems.  Note that events are not generated for children of
176              the  subdirectories  of  marked directories.  More specifically,
177              the directory entry modification events FAN_CREATE,  FAN_DELETE,
178              FAN_MOVED_FROM, and FAN_MOVED_TO are not generated for any entry
179              modifications performed inside subdirectories of marked directo‐
180              ries.   Note  that  the events FAN_DELETE_SELF and FAN_MOVE_SELF
181              are not generated for children of marked directories.  To  moni‐
182              tor  complete  directory trees it is necessary to mark the rele‐
183              vant mount or filesystem.
184
185       The following composed values are defined:
186
187       FAN_CLOSE
188              A file is closed (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE).
189
190       FAN_MOVE
191              A      file      or      directory      has      been      moved
192              (FAN_MOVED_FROM|FAN_MOVED_TO).
193
194       The filesystem object to be marked is determined by the file descriptor
195       dirfd and the pathname specified in pathname:
196
197       *  If pathname is NULL, dirfd  defines  the  filesystem  object  to  be
198          marked.
199
200       *  If pathname is NULL, and dirfd takes the special value AT_FDCWD, the
201          current working directory is to be marked.
202
203       *  If pathname is absolute, it defines  the  filesystem  object  to  be
204          marked, and dirfd is ignored.
205
206       *  If pathname is relative, and dirfd does not have the value AT_FDCWD,
207          then the filesystem object to be marked is determined by  interpret‐
208          ing pathname relative the directory referred to by dirfd.
209
210       *  If  pathname is relative, and dirfd has the value AT_FDCWD, then the
211          filesystem object to be marked is determined by  interpreting  path‐
212          name  relative to the current working directory.  (See openat(2) for
213          an explanation of why the dirfd argument is useful.)
214

RETURN VALUE

216       On success, fanotify_mark() returns 0.  On error, -1 is  returned,  and
217       errno is set to indicate the error.
218

ERRORS

220       EBADF  An invalid file descriptor was passed in fanotify_fd.
221
222       EBADF  pathname  is  relative but dirfd is neither AT_FDCWD nor a valid
223              file descriptor.
224
225       EINVAL An invalid value was passed in flags or mask, or fanotify_fd was
226              not an fanotify file descriptor.
227
228       EINVAL The  fanotify file descriptor was opened with FAN_CLASS_NOTIF or
229              the fanotify group identifies filesystem objects by file handles
230              and mask contains a flag for permission events (FAN_OPEN_PERM or
231              FAN_ACCESS_PERM).
232
233       ENODEV The filesystem object indicated by pathname  is  not  associated
234              with a filesystem that supports fsid (e.g., tmpfs(5)).  This er‐
235              ror can be returned only with an fanotify group that  identifies
236              filesystem objects by file handles.
237
238       ENOENT The  filesystem  object indicated by dirfd and pathname does not
239              exist.  This error also occurs when trying to remove a mark from
240              an object which is not marked.
241
242       ENOMEM The necessary memory could not be allocated.
243
244       ENOSPC The number of marks exceeds the limit of 8192 and the FAN_UNLIM‐
245              ITED_MARKS flag was not specified when  the  fanotify  file  de‐
246              scriptor was created with fanotify_init(2).
247
248       ENOSYS This  kernel  does  not implement fanotify_mark().  The fanotify
249              API is available only if the kernel  was  configured  with  CON‐
250              FIG_FANOTIFY.
251
252       ENOTDIR
253              flags  contains  FAN_MARK_ONLYDIR, and dirfd and pathname do not
254              specify a directory.
255
256       EOPNOTSUPP
257              The object indicated by pathname is associated with a filesystem
258              that  does not support the encoding of file handles.  This error
259              can be returned only with  an  fanotify  group  that  identifies
260              filesystem objects by file handles.
261
262       EXDEV  The  filesystem  object  indicated  by pathname resides within a
263              filesystem subvolume (e.g., btrfs(5))  which  uses  a  different
264              fsid  than its root superblock.  This error can be returned only
265              with an fanotify group that  identifies  filesystem  objects  by
266              file handles.
267

VERSIONS

269       fanotify_mark()  was  introduced  in version 2.6.36 of the Linux kernel
270       and enabled in version 2.6.37.
271

CONFORMING TO

273       This system call is Linux-specific.
274

NOTES

276   FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
277       When using either FAN_OPEN_EXEC or FAN_OPEN_EXEC_PERM within the  mask,
278       events  of  these types will be returned only when the direct execution
279       of a program occurs.  More specifically,  this  means  that  events  of
280       these  types  will  be  generated  for  files that are opened using ex‐
281       ecve(2), execveat(2), or uselib(2).  Events of these types will not  be
282       raised  in  the  situation  where an interpreter is passed (or reads) a
283       file for interpretation.
284
285       Additionally, if a mark has also  been  placed  on  the  Linux  dynamic
286       linker,  a  user  should also expect to receive an event for it when an
287       ELF object has been successfully opened using execve(2) or execveat(2).
288
289       For example, if the following ELF binary  were  to  be  invoked  and  a
290       FAN_OPEN_EXEC mark has been placed on /:
291
292           $ /bin/echo foo
293
294       The  listening  application  in  this  case would receive FAN_OPEN_EXEC
295       events for both the ELF binary and interpreter, respectively:
296
297           /bin/echo
298           /lib64/ld-linux-x86-64.so.2
299

BUGS

301       The following bugs were present in Linux kernels before version 3.16:
302
303       *  If flags contains FAN_MARK_FLUSH, dirfd, and pathname must specify a
304          valid filesystem object, even though this object is not used.
305
306       *  readdir(2) does not generate a FAN_ACCESS event.
307
308       *  If  fanotify_mark()  is  called  with  FAN_MARK_FLUSH,  flags is not
309          checked for invalid values.
310

SEE ALSO

312       fanotify_init(2), fanotify(7)
313

COLOPHON

315       This page is part of release 5.13 of the Linux  man-pages  project.   A
316       description  of  the project, information about reporting bugs, and the
317       latest    version    of    this    page,    can     be     found     at
318       https://www.kernel.org/doc/man-pages/.
319
320
321
322Linux                             2021-08-27                  FANOTIFY_MARK(2)
Impressum