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 .BI "                  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 the 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 other flag but
  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 The
 113 .I pathname
 114 indicates a mount point to be marked.
 115 If the path is not itself a mount point, the mount point containing the path
 116 will be marked.
 117 All directories, subdirectories, and the contained files of the mount point
 118 will be monitored.
 119 .TP
 120 .B FAN_MARK_IGNORED_MASK
 121 The events in
 122 .I mask
 123 shall be added to or removed from the ignore mask.
 124 .TP
 125 .B FAN_MARK_IGNORED_SURV_MODIFY
 126 The ignore mask shall survive modify events.
 127 If this flag is not set, the ignore mask is cleared when a modify event occurs
 128 for the ignored file or directory.
 129 .PP
 130 .I mask
 131 defines which events shall be listened to (or which shall be ignored).
 132 It is a bit mask composed of the following values:
 133 .TP
 134 .B FAN_ACCESS
 135 Create an event when a file or directory (but see BUGS) is accessed (read).
 136 .TP
 137 .B FAN_MODIFY
 138 Create an event when a file is modified (write).
 139 .TP
 140 .B FAN_CLOSE_WRITE
 141 Create an event when a writable file is closed.
 142 .TP
 143 .B FAN_CLOSE_NOWRITE
 144 Create an event when a read-only file or directory is closed.
 145 .TP
 146 .B FAN_OPEN
 147 Create an event when a file or directory is opened.
 148 .TP
 149 .B FAN_OPEN_PERM
 150 Create an event when a permission to open a file or directory is requested.
 151 An fanotify file descriptor created with
 152 .B FAN_CLASS_PRE_CONTENT
 153 or
 154 .B FAN_CLASS_CONTENT
 155 is required.
 156 .TP
 157 .B FAN_ACCESS_PERM
 158 Create an event when a permission to read a file or directory is requested.
 159 An fanotify file descriptor created with
 160 .B FAN_CLASS_PRE_CONTENT
 161 or
 162 .B FAN_CLASS_CONTENT
 163 is required.
 164 .TP
 165 .B FAN_ONDIR
 166 Events for directories shall be created, for example when
 167 .BR opendir (2),
 168 .BR readdir (2)
 169 (but see BUGS), and
 170 .BR closedir (2)
 171 are called.
 172 Without this flag only events for files are created.
 173 .TP
 174 .B FAN_EVENT_ON_CHILD
 175 Events for the immediate children of marked directories shall be created.
 176 The flag has no effect when marking mounts.
 177 Note that events are not generated for children of the subdirectories
 178 of marked directories.
 179 To monitor complete directory trees it is necessary to mark the relevant
 180 mount.
 181 .PP
 182 The following composed value is defined:
 183 .TP
 184 .B FAN_CLOSE
 185 A file is closed
 186 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
 187 .PP
 188 The filesystem object to be marked is determined by the file descriptor
 189 .I dirfd
 190 and the pathname specified in
 191 .IR pathname :
 192 .IP * 3
 193 If
 194 .I pathname
 195 is NULL,
 196 .I dirfd
 197 defines the filesystem object to be marked.
 198 .IP *
 199 If
 200 .I pathname
 201 is NULL, and
 202 .I dirfd
 203 takes the special value
 204 .BR AT_FDCWD ,
 205 the current working directory is to be marked.
 206 .IP *
 207 If
 208 .I pathname
 209 is absolute, it defines the filesystem object to be marked, and
 210 .I dirfd
 211 is ignored.
 212 .IP *
 213 If
 214 .I pathname
 215 is relative, and
 216 .I dirfd
 217 does not have the value
 218 .BR AT_FDCWD ,
 219 then the filesystem object to be marked is determined by interpreting
 220 .I pathname
 221 relative the directory referred to by
 222 .IR dirfd .
 223 .IP *
 224 If
 225 .I pathname
 226 is relative, and
 227 .I dirfd
 228 has the value
 229 .BR AT_FDCWD,
 230 then the filesystem object to be marked is determined by interpreting
 231 .I pathname
 232 relative the current working directory.
 233 .SH RETURN VALUE
 234 On success,
 235 .BR fanotify_mark ()
 236 returns 0.
 237 In case of an error, \-1 is returned, and
 238 .I errno
 239 is set to indicate the error.
 240 .SH ERRORS
 241 .TP
 242 .B EBADF
 243 An invalid file descriptor was passed in
 244 .IR fanotify_fd .
 245 .TP
 246 .B EINVAL
 247 An invalid value was passed in
 248 .IR flags
 249 or
 250 .IR mask ,
 251 or
 252 .I fanotify_fd
 253 was not an fanotify file descriptor.
 254 .TP
 255 .B EINVAL
 256 The fanotify file descriptor was opened with
 257 .B FAN_CLASS_NOTIF
 258 and mask contains a flag for permission events
 259 .RB ( FAN_OPEN_PERM
 260 or
 261 .BR FAN_ACCESS_PERM ).
 262 .TP
 263 .B ENOENT
 264 The filesystem object indicated by
 265 .IR dirfd
 266 and
 267 .IR pathname
 268 does not exist.
 269 This error also occurs when trying to remove a mark from an object which is not
 270 marked.
 271 .TP
 272 .B ENOMEM
 273 The necessary memory could not be allocated.
 274 .TP
 275 .B ENOSPC
 276 The number of marks exceeds the limit of 8192 and
 277 .B FAN_UNLIMITED_MARKS
 278 was not specified in the call to
 279 .BR fanotify_init (2).
 280 .TP
 281 .B ENOTDIR
 282 .I flags
 283 contains
 284 .BR FAN_MARK_ONLYDIR ,
 285 and
 286 .I dirfd
 287 and
 288 .I pathname
 289 do not specify a directory.
 290 .SH VERSIONS
 291 .BR fanotify_mark ()
 292 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 293 2.6.37.
 294 .SH CONFORMING TO
 295 This system call is Linux-specific.
 296 .SH BUGS
 297 As of Linux 3.15,
 298 the following bugs exist:
 299 .IP * 3
 300 .\" FIXME: Patch is in next-20140424.
 301 If
 302 .I flags
 303 contains
 304 .BR FAN_MARK_FLUSH ,
 305 .I dfd
 306 and
 307 .I pathname
 308 must indicate a valid path.
 309 This path is not used.
 310 .IP *
 311 .\" FIXME: Patch is in next-20140424.
 312 .BR readdir (2)
 313 does not result in a
 314 .B FAN_ACCESS
 315 event.
 316 .IP *
 317 .\" FIXME: Patch proposed.
 318 If
 319 .BR fanotify_mark (2)
 320 is called with
 321 .B FAN_MARK_FLUSH,
 322 .I flags
 323 is not checked for invalid values.
 324 .SH SEE ALSO
 325 .BR fanotify_init (2),
 326 .BR fanotify (7)