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
30              ignore  mask).   mask  must be nonempty or the error EINVAL will
31              occur.
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 mount or all non-mount marks from the fanotify
40              group.   If  flags contains FAN_MARK_MOUNT, all marks for mounts
41              are removed from the group.  Otherwise, all marks  for  directo‐
42              ries  and  files are removed.  No flag other than FAN_MARK_MOUNT
43              can  be  used  in  conjunction  with  FAN_MARK_FLUSH.   mask  is
44              ignored.
45
46       If  none  of  the values above is specified, or more than one is speci‐
47       fied, the call fails with the error EINVAL.
48
49       In addition, zero or more of the following  values  may  be  ORed  into
50       flags:
51
52       FAN_MARK_DONT_FOLLOW
53              If  pathname  is  a  symbolic link, mark the link itself, rather
54              than the file to which it refers.  (By default,  fanotify_mark()
55              dereferences pathname if it is a symbolic link.)
56
57       FAN_MARK_ONLYDIR
58              If  the  filesystem  object to be marked is not a directory, the
59              error ENOTDIR shall be raised.
60
61       FAN_MARK_MOUNT
62              Mark the mount point specified by pathname.  If pathname is  not
63              itself  a  mount point, the mount point containing pathname will
64              be marked.  All directories, subdirectories, and  the  contained
65              files of the mount point will be monitored.
66
67       FAN_MARK_IGNORED_MASK
68              The  events in mask shall be added to or removed from the ignore
69              mask.
70
71       FAN_MARK_IGNORED_SURV_MODIFY
72              The ignore mask shall survive modify events.  If  this  flag  is
73              not  set,  the ignore mask is cleared when a modify event occurs
74              for the ignored file or directory.
75
76       mask defines which events shall be listened  for  (or  which  shall  be
77       ignored).  It is a bit mask composed of the following values:
78
79       FAN_ACCESS
80              Create  an  event  when  a  file  or directory (but see BUGS) is
81              accessed (read).
82
83       FAN_MODIFY
84              Create an event when a file is modified (write).
85
86       FAN_CLOSE_WRITE
87              Create an event when a writable file is closed.
88
89       FAN_CLOSE_NOWRITE
90              Create an event when a read-only file or directory is closed.
91
92       FAN_OPEN
93              Create an event when a file or directory is opened.
94
95       FAN_Q_OVERFLOW
96              Create an event when an overflow of the event queue occurs.  The
97              size  of  the  event  queue  is  limited  to  16384  entries  if
98              FAN_UNLIMITED_QUEUE is not set in fanotify_init(2).
99
100       FAN_OPEN_PERM
101              Create an event when a permission to open a file or directory is
102              requested.    An   fanotify   file   descriptor   created   with
103              FAN_CLASS_PRE_CONTENT or FAN_CLASS_CONTENT is required.
104
105       FAN_ACCESS_PERM
106              Create an event when a permission to read a file or directory is
107              requested.    An   fanotify   file   descriptor   created   with
108              FAN_CLASS_PRE_CONTENT or FAN_CLASS_CONTENT is required.
109
110       FAN_ONDIR
111              Create events  for  directories—for  example,  when  opendir(3),
112              readdir(3)  (but see BUGS), and closedir(3) are called.  Without
113              this flag, only events for files are created.
114
115       FAN_EVENT_ON_CHILD
116              Events for the immediate children of marked directories shall be
117              created.  The flag has no effect when marking mounts.  Note that
118              events are not generated for children of the  subdirectories  of
119              marked  directories.   To monitor complete directory trees it is
120              necessary to mark the relevant mount.
121
122       The following composed value is defined:
123
124       FAN_CLOSE
125              A file is closed (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE).
126
127       The filesystem object to be marked is determined by the file descriptor
128       dirfd and the pathname specified in pathname:
129
130       *  If  pathname  is  NULL,  dirfd  defines  the filesystem object to be
131          marked.
132
133       *  If pathname is NULL, and dirfd takes the special value AT_FDCWD, the
134          current working directory is to be marked.
135
136       *  If  pathname  is  absolute,  it  defines the filesystem object to be
137          marked, and dirfd is ignored.
138
139       *  If pathname is relative, and dirfd does not have the value AT_FDCWD,
140          then  the filesystem object to be marked is determined by interpret‐
141          ing pathname relative the directory referred to by dirfd.
142
143       *  If pathname is relative, and dirfd has the value AT_FDCWD, then  the
144          filesystem  object  to be marked is determined by interpreting path‐
145          name relative the current working directory.
146

RETURN VALUE

148       On success, fanotify_mark() returns 0.  On error, -1 is  returned,  and
149       errno is set to indicate the error.
150

ERRORS

152       EBADF  An invalid file descriptor was passed in fanotify_fd.
153
154       EINVAL An invalid value was passed in flags or mask, or fanotify_fd was
155              not an fanotify file descriptor.
156
157       EINVAL The fanotify file descriptor was opened with FAN_CLASS_NOTIF and
158              mask  contains  a  flag  for permission events (FAN_OPEN_PERM or
159              FAN_ACCESS_PERM).
160
161       ENOENT The filesystem object indicated by dirfd and pathname  does  not
162              exist.  This error also occurs when trying to remove a mark from
163              an object which is not marked.
164
165       ENOMEM The necessary memory could not be allocated.
166
167       ENOSPC The number of marks exceeds the limit of 8192 and the FAN_UNLIM‐
168              ITED_MARKS  flag  was  not  specified  when  the  fanotify  file
169              descriptor was created with fanotify_init(2).
170
171       ENOSYS This kernel does not implement  fanotify_mark().   The  fanotify
172              API  is  available  only  if the kernel was configured with CON‐
173              FIG_FANOTIFY.
174
175       ENOTDIR
176              flags contains FAN_MARK_ONLYDIR, and dirfd and pathname  do  not
177              specify a directory.
178

VERSIONS

180       fanotify_mark()  was  introduced  in version 2.6.36 of the Linux kernel
181       and enabled in version 2.6.37.
182

CONFORMING TO

184       This system call is Linux-specific.
185

BUGS

187       The following bugs were present in Linux kernels before version 3.16:
188
189       *  If flags contains FAN_MARK_FLUSH, dirfd and pathname must specify  a
190          valid filesystem object, even though this object is not used.
191
192       *  readdir(2) does not generate a FAN_ACCESS event.
193
194       *  If  fanotify_mark()  is  called  with  FAN_MARK_FLUSH,  flags is not
195          checked for invalid values.
196

SEE ALSO

198       fanotify_init(2), fanotify(7)
199

COLOPHON

201       This page is part of release 4.15 of the Linux  man-pages  project.   A
202       description  of  the project, information about reporting bugs, and the
203       latest    version    of    this    page,    can     be     found     at
204       https://www.kernel.org/doc/man-pages/.
205
206
207
208Linux                             2016-10-08                  FANOTIFY_MARK(2)
Impressum