original/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-10-02 "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
  43 is to be 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 all non-mount marks from the fanotify group.
  74 If
  75 .I flags
  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,
  88 the call fails with the error
  89 .BR EINVAL .
  90 .PP
  91 In addition,
  92 zero or more of the following values may be ORed into
  93 .IR flags :
  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,
 130 the ignore mask is cleared when a modify event occurs
 131 for the ignored file or directory.
 132 .PP
 133 .I mask
 134 defines which events shall be listened for (or which shall be ignored).
 135 It is a bit mask composed of the following values:
 136 .TP
 137 .B FAN_ACCESS
 138 Create an event when a file or directory (but see BUGS) is accessed (read).
 139 .TP
 140 .B FAN_MODIFY
 141 Create an event when a file is modified (write).
 142 .TP
 143 .B FAN_CLOSE_WRITE
 144 Create an event when a writable file is closed.
 145 .TP
 146 .B FAN_CLOSE_NOWRITE
 147 Create an event when a read-only file or directory is closed.
 148 .TP
 149 .B FAN_OPEN
 150 Create an event when a file or directory is opened.
 151 .TP
 152 .B FAN_OPEN_PERM
 153 Create an event when a permission to open a file or directory is requested.
 154 An fanotify file descriptor created with
 155 .B FAN_CLASS_PRE_CONTENT
 156 or
 157 .B FAN_CLASS_CONTENT
 158 is required.
 159 .TP
 160 .B FAN_ACCESS_PERM
 161 Create an event when a permission to read a file or directory is requested.
 162 An fanotify file descriptor created with
 163 .B FAN_CLASS_PRE_CONTENT
 164 or
 165 .B FAN_CLASS_CONTENT
 166 is required.
 167 .TP
 168 .B FAN_ONDIR
 169 Create events for directories\(emfor example, when
 170 .BR opendir (3),
 171 .BR readdir (3)
 172 (but see BUGS), and
 173 .BR closedir (3)
 174 are called.
 175 Without this flag, only events for files are created.
 176 .TP
 177 .B FAN_EVENT_ON_CHILD
 178 Events for the immediate children of marked directories shall be created.
 179 The flag has no effect when marking mounts.
 180 Note that events are not generated for children of the subdirectories
 181 of marked directories.
 182 To monitor complete directory trees it is necessary to mark the relevant
 183 mount.
 184 .PP
 185 The following composed value is defined:
 186 .TP
 187 .B FAN_CLOSE
 188 A file is closed
 189 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
 190 .PP
 191 The filesystem object to be marked is determined by the file descriptor
 192 .I dirfd
 193 and the pathname specified in
 194 .IR pathname :
 195 .IP * 3
 196 If
 197 .I pathname
 198 is NULL,
 199 .I dirfd
 200 defines the filesystem object to be marked.
 201 .IP *
 202 If
 203 .I pathname
 204 is NULL, and
 205 .I dirfd
 206 takes the special value
 207 .BR AT_FDCWD ,
 208 the current working directory is to be marked.
 209 .IP *
 210 If
 211 .I pathname
 212 is absolute, it defines the filesystem object to be marked, and
 213 .I dirfd
 214 is ignored.
 215 .IP *
 216 If
 217 .I pathname
 218 is relative, and
 219 .I dirfd
 220 does not have the value
 221 .BR AT_FDCWD ,
 222 then the filesystem object to be marked is determined by interpreting
 223 .I pathname
 224 relative the directory referred to by
 225 .IR dirfd .
 226 .IP *
 227 If
 228 .I pathname
 229 is relative, and
 230 .I dirfd
 231 has the value
 232 .BR AT_FDCWD ,
 233 then the filesystem object to be marked is determined by interpreting
 234 .I pathname
 235 relative the current working directory.
 236 .SH RETURN VALUE
 237 On success,
 238 .BR fanotify_mark ()
 239 returns 0.
 240 On error, \-1 is returned, and
 241 .I errno
 242 is set to indicate the error.
 243 .SH ERRORS
 244 .TP
 245 .B EBADF
 246 An invalid file descriptor was passed in
 247 .IR fanotify_fd .
 248 .TP
 249 .B EINVAL
 250 An invalid value was passed in
 251 .IR flags
 252 or
 253 .IR mask ,
 254 or
 255 .I fanotify_fd
 256 was not an fanotify file descriptor.
 257 .TP
 258 .B EINVAL
 259 The fanotify file descriptor was opened with
 260 .B FAN_CLASS_NOTIF
 261 and mask contains a flag for permission events
 262 .RB ( FAN_OPEN_PERM
 263 or
 264 .BR FAN_ACCESS_PERM ).
 265 .TP
 266 .B ENOENT
 267 The filesystem object indicated by
 268 .IR dirfd
 269 and
 270 .IR pathname
 271 does not exist.
 272 This error also occurs when trying to remove a mark from an object
 273 which is not marked.
 274 .TP
 275 .B ENOMEM
 276 The necessary memory could not be allocated.
 277 .TP
 278 .B ENOSPC
 279 The number of marks exceeds the limit of 8192 and the
 280 .B FAN_UNLIMITED_MARKS
 281 flag was not specified when the fanotify file descriptor was created with
 282 .BR fanotify_init (2).
 283 .TP
 284 .B ENOSYS
 285 This kernel does not implement
 286 .BR fanotify_mark ().
 287 The fanotify API is available only if the kernel was configured with
 288 .BR CONFIG_FANOTIFY .
 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 The following bugs were present in Linux kernels before version 3.16:
 307 .IP * 3
 308 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
 309 If
 310 .I flags
 311 contains
 312 .BR FAN_MARK_FLUSH ,
 313 .I dirfd
 314 and
 315 .I pathname
 316 must specify a valid filesystem object, even though this object is not used.
 317 .IP *
 318 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
 319 .BR readdir (2)
 320 does not generate a
 321 .B FAN_ACCESS
 322 event.
 323 .IP *
 324 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
 325 If
 326 .BR fanotify_mark (2)
 327 is called with
 328 .BR FAN_MARK_FLUSH ,
 329 .I flags
 330 is not checked for invalid values.
 331 .SH SEE ALSO
 332 .BR fanotify_init (2),
 333 .BR fanotify (7)
 334 .SH COLOPHON
 335 This page is part of release 3.79 of the Linux
 336 .I man-pages
 337 project.
 338 A description of the project,
 339 information about reporting bugs,
 340 and the latest version of this page,
 341 can be found at
 342 \%http://www.kernel.org/doc/man\-pages/.