man2/fanotify_mark.2

   1 .\" Copyright (C) 2013,  Heinrich Schuchardt <xypron.glpk@gmx.de>
   2 .\"
   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.
   7 .\"
   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.
  12 .\"
  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.
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .TH FANOTIFY_MARK 2 2014-04-24 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem
  27 object
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <sys/fanotify.h>
  31 .sp
  32 .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags ,
  33 .BI "                  uint64_t " mask ", int " dirfd \
  34 ", const char *" pathname );
  35 .fi
  36 .SH DESCRIPTION
  37 For an overview of the fanotify API, see
  38 .BR fanotify (7).
  39 .PP
  40 .BR fanotify_mark (2)
  41 adds, removes, or modifies an fanotify mark on a filesystem object.
  42 The caller must have read permission on the filesystem object that is to be
  43 marked.
  44 .PP
  45 The
  46 .I fanotify_fd
  47 argument is a file descriptor returned by
  48 .BR fanotify_init (2).
  49 .PP
  50 .I flags
  51 is a bit mask describing the modification to perform.
  52 It must include exactly one of the following values:
  53 .TP
  54 .B FAN_MARK_ADD
  55 The events in
  56 .I mask
  57 will be added to the mark mask (or to the ignore mask).
  58 .I mask
  59 must be nonempty or the error
  60 .B EINVAL
  61 will occur.
  62 .TP
  63 .B FAN_MARK_REMOVE
  64 The events in argument
  65 .I mask
  66 will be removed from the mark mask (or from the ignore mask).
  67 .I mask
  68 must be nonempty or the error
  69 .B EINVAL
  70 will occur.
  71 .TP
  72 .B FAN_MARK_FLUSH
  73 Remove either all mount or non-mount marks from the fanotify group.
  74 If
  75 .I flag
  76 contains
  77 .BR FAN_MARK_MOUNT ,
  78 all marks for mounts are removed from the group.
  79 Otherwise, all marks for directories and files are removed.
  80 No flag other than
  81 .B FAN_MARK_MOUNT
  82 can be used in conjunction with
  83 .BR FAN_MARK_FLUSH .
  84 .I mask
  85 is ignored.
  86 .PP
  87 If none of the values above is specified, or more than one is specified, the
  88 call fails with the error
  89 .BR EINVAL .
  90 .PP
  91 In addition,
  92 .I flags
  93 may contain zero or more of the following:
  94 .TP
  95 .B FAN_MARK_DONT_FOLLOW
  96 If
  97 .I pathname
  98 is a symbolic link, mark the link itself, rather than the file to which it
  99 refers.
 100 (By default,
 101 .BR fanotify_mark ()
 102 dereferences
 103 .I pathname
 104 if it is a symbolic link.)
 105 .TP
 106 .B FAN_MARK_ONLYDIR
 107 If the filesystem object to be marked is not a directory, the error
 108 .B ENOTDIR
 109 shall be raised.
 110 .TP
 111 .B FAN_MARK_MOUNT
 112 Mark the mount point specified by
 113 .IR pathname .
 114 If
 115 .I pathname
 116 is not itself a mount point, the mount point containing
 117 .I pathname
 118 will be marked.
 119 All directories, subdirectories, and the contained files of the mount point
 120 will be monitored.
 121 .TP
 122 .B FAN_MARK_IGNORED_MASK
 123 The events in
 124 .I mask
 125 shall be added to or removed from the ignore mask.
 126 .TP
 127 .B FAN_MARK_IGNORED_SURV_MODIFY
 128 The ignore mask shall survive modify events.
 129 If this flag is not set, the ignore mask is cleared when a modify event occurs
 130 for the ignored file or directory.
 131 .PP
 132 .I mask
 133 defines which events shall be listened to (or which shall be ignored).
 134 It is a bit mask composed of the following values:
 135 .TP
 136 .B FAN_ACCESS
 137 Create an event when a file or directory (but see BUGS) is accessed (read).
 138 .TP
 139 .B FAN_MODIFY
 140 Create an event when a file is modified (write).
 141 .TP
 142 .B FAN_CLOSE_WRITE
 143 Create an event when a writable file is closed.
 144 .TP
 145 .B FAN_CLOSE_NOWRITE
 146 Create an event when a read-only file or directory is closed.
 147 .TP
 148 .B FAN_OPEN
 149 Create an event when a file or directory is opened.
 150 .TP
 151 .B FAN_OPEN_PERM
 152 Create an event when a permission to open a file or directory is requested.
 153 An fanotify file descriptor created with
 154 .B FAN_CLASS_PRE_CONTENT
 155 or
 156 .B FAN_CLASS_CONTENT
 157 is required.
 158 .TP
 159 .B FAN_ACCESS_PERM
 160 Create an event when a permission to read a file or directory is requested.
 161 An fanotify file descriptor created with
 162 .B FAN_CLASS_PRE_CONTENT
 163 or
 164 .B FAN_CLASS_CONTENT
 165 is required.
 166 .TP
 167 .B FAN_ONDIR
 168 Events for directories shall be created, for example when
 169 .BR opendir (2),
 170 .BR readdir (2)
 171 (but see BUGS), and
 172 .BR closedir (2)
 173 are called.
 174 Without this flag, only events for files are created.
 175 .TP
 176 .B FAN_EVENT_ON_CHILD
 177 Events for the immediate children of marked directories shall be created.
 178 The flag has no effect when marking mounts.
 179 Note that events are not generated for children of the subdirectories
 180 of marked directories.
 181 To monitor complete directory trees it is necessary to mark the relevant
 182 mount.
 183 .PP
 184 The following composed value is defined:
 185 .TP
 186 .B FAN_CLOSE
 187 A file is closed
 188 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
 189 .PP
 190 The filesystem object to be marked is determined by the file descriptor
 191 .I dirfd
 192 and the pathname specified in
 193 .IR pathname :
 194 .IP * 3
 195 If
 196 .I pathname
 197 is NULL,
 198 .I dirfd
 199 defines the filesystem object to be marked.
 200 .IP *
 201 If
 202 .I pathname
 203 is NULL, and
 204 .I dirfd
 205 takes the special value
 206 .BR AT_FDCWD ,
 207 the current working directory is to be marked.
 208 .IP *
 209 If
 210 .I pathname
 211 is absolute, it defines the filesystem object to be marked, and
 212 .I dirfd
 213 is ignored.
 214 .IP *
 215 If
 216 .I pathname
 217 is relative, and
 218 .I dirfd
 219 does not have the value
 220 .BR AT_FDCWD ,
 221 then the filesystem object to be marked is determined by interpreting
 222 .I pathname
 223 relative the directory referred to by
 224 .IR dirfd .
 225 .IP *
 226 If
 227 .I pathname
 228 is relative, and
 229 .I dirfd
 230 has the value
 231 .BR AT_FDCWD,
 232 then the filesystem object to be marked is determined by interpreting
 233 .I pathname
 234 relative the current working directory.
 235 .SH RETURN VALUE
 236 On success,
 237 .BR fanotify_mark ()
 238 returns 0.
 239 On error, \-1 is returned, and
 240 .I errno
 241 is set to indicate the error.
 242 .SH ERRORS
 243 .TP
 244 .B EBADF
 245 An invalid file descriptor was passed in
 246 .IR fanotify_fd .
 247 .TP
 248 .B EINVAL
 249 An invalid value was passed in
 250 .IR flags
 251 or
 252 .IR mask ,
 253 or
 254 .I fanotify_fd
 255 was not an fanotify file descriptor.
 256 .TP
 257 .B EINVAL
 258 The fanotify file descriptor was opened with
 259 .B FAN_CLASS_NOTIF
 260 and mask contains a flag for permission events
 261 .RB ( FAN_OPEN_PERM
 262 or
 263 .BR FAN_ACCESS_PERM ).
 264 .TP
 265 .B ENOENT
 266 The filesystem object indicated by
 267 .IR dirfd
 268 and
 269 .IR pathname
 270 does not exist.
 271 This error also occurs when trying to remove a mark from an object which is not
 272 marked.
 273 .TP
 274 .B ENOMEM
 275 The necessary memory could not be allocated.
 276 .TP
 277 .B ENOSPC
 278 The number of marks exceeds the limit of 8192 and
 279 .B FAN_UNLIMITED_MARKS
 280 was not specified in the call to
 281 .BR fanotify_init (2).
 282 .TP
 283 .B ENOSYS
 284 This kernel does not implement
 285 .BR fanotify_mark ().
 286 To make the fanotify API available,
 287 .B CONFIG_FANOTIFY
 288 has to be enabled in the Linux configuration.
 289 .TP
 290 .B ENOTDIR
 291 .I flags
 292 contains
 293 .BR FAN_MARK_ONLYDIR ,
 294 and
 295 .I dirfd
 296 and
 297 .I pathname
 298 do not specify a directory.
 299 .SH VERSIONS
 300 .BR fanotify_mark ()
 301 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 302 2.6.37.
 303 .SH CONFORMING TO
 304 This system call is Linux-specific.
 305 .SH BUGS
 306 As of Linux 3.15,
 307 the following bugs exist:
 308 .IP * 3
 309 .\" FIXME: Patch is in next-20140424.
 310 If
 311 .I flags
 312 contains
 313 .BR FAN_MARK_FLUSH ,
 314 .I dfd
 315 and
 316 .I pathname
 317 must indicate a filesystem object, even though this object is not used.
 318 .IP *
 319 .\" FIXME: Patch is in next-20140424.
 320 .BR readdir (2)
 321 does not result in a
 322 .B FAN_ACCESS
 323 event.
 324 .IP *
 325 .\" FIXME: Patch proposed.
 326 If
 327 .BR fanotify_mark (2)
 328 is called with
 329 .B FAN_MARK_FLUSH,
 330 .I flags
 331 is not checked for invalid values.
 332 .SH SEE ALSO
 333 .BR fanotify_init (2),
 334 .BR fanotify (7)