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 2016-10-08 "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 .PP
  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 ()
  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 marks for filesystems, all marks for mounts, or all
  74 marks for directories and files from the fanotify group.
  75 If
  76 .I flags
  77 contains
  78 .BR FAN_MARK_MOUNT ,
  79 all marks for mounts are removed from the group.
  80 If
  81 .I flags
  82 contains
  83 .BR FAN_MARK_FILESYSTEM ,
  84 all marks for filesystems are removed from the group.
  85 Otherwise, all marks for directories and files are removed.
  86 No flag other than and at most one of the flags
  87 .B FAN_MARK_MOUNT
  88 or
  89 .B FAN_MARK_FILESYSTEM
  90 can be used in conjunction with
  91 .BR FAN_MARK_FLUSH .
  92 .I mask
  93 is ignored.
  94 .PP
  95 If none of the values above is specified, or more than one is specified,
  96 the call fails with the error
  97 .BR EINVAL .
  98 .PP
  99 In addition,
 100 zero or more of the following values may be ORed into
 101 .IR flags :
 102 .TP
 103 .B FAN_MARK_DONT_FOLLOW
 104 If
 105 .I pathname
 106 is a symbolic link, mark the link itself, rather than the file to which it
 107 refers.
 108 (By default,
 109 .BR fanotify_mark ()
 110 dereferences
 111 .I pathname
 112 if it is a symbolic link.)
 113 .TP
 114 .B FAN_MARK_ONLYDIR
 115 If the filesystem object to be marked is not a directory, the error
 116 .B ENOTDIR
 117 shall be raised.
 118 .TP
 119 .B FAN_MARK_MOUNT
 120 Mark the mount point specified by
 121 .IR pathname .
 122 If
 123 .I pathname
 124 is not itself a mount point, the mount point containing
 125 .I pathname
 126 will be marked.
 127 All directories, subdirectories, and the contained files of the mount point
 128 will be monitored.
 129 .TP
 130 .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
 131 .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
 132 Mark the filesystem specified by
 133 .IR pathname .
 134 The filesystem containing
 135 .I pathname
 136 will be marked.
 137 All the contained files and directories of the filesystem from any mount
 138 point will be monitored.
 139 .TP
 140 .B FAN_MARK_IGNORED_MASK
 141 The events in
 142 .I mask
 143 shall be added to or removed from the ignore mask.
 144 .TP
 145 .B FAN_MARK_IGNORED_SURV_MODIFY
 146 The ignore mask shall survive modify events.
 147 If this flag is not set,
 148 the ignore mask is cleared when a modify event occurs
 149 for the ignored file or directory.
 150 .PP
 151 .I mask
 152 defines which events shall be listened for (or which shall be ignored).
 153 It is a bit mask composed of the following values:
 154 .TP
 155 .B FAN_ACCESS
 156 Create an event when a file or directory (but see BUGS) is accessed (read).
 157 .TP
 158 .B FAN_MODIFY
 159 Create an event when a file is modified (write).
 160 .TP
 161 .B FAN_CLOSE_WRITE
 162 Create an event when a writable file is closed.
 163 .TP
 164 .B FAN_CLOSE_NOWRITE
 165 Create an event when a read-only file or directory is closed.
 166 .TP
 167 .B FAN_OPEN
 168 Create an event when a file or directory is opened.
 169 .TP
 170 .B FAN_OPEN_EXEC " (since Linux 5.0)"
 171 Create an event when a file is opened with the intent to be executed.
 172 See NOTES for additional details.
 173 .TP
 174 .B FAN_Q_OVERFLOW
 175 Create an event when an overflow of the event queue occurs.
 176 The size of the event queue is limited to 16384 entries if
 177 .B FAN_UNLIMITED_QUEUE
 178 is not set in
 179 .BR fanotify_init (2).
 180 .TP
 181 .B FAN_OPEN_PERM
 182 Create an event when a permission to open a file or directory is requested.
 183 An fanotify file descriptor created with
 184 .B FAN_CLASS_PRE_CONTENT
 185 or
 186 .B FAN_CLASS_CONTENT
 187 is required.
 188 .TP
 189 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
 190 Create an event when a permission to open a file for execution is
 191 requested.
 192 An fanotify file descriptor created with
 193 .B FAN_CLASS_PRE_CONTENT
 194 or
 195 .B FAN_CLASS_CONTENT
 196 is required.
 197 See NOTES for additional details.
 198 .TP
 199 .B FAN_ACCESS_PERM
 200 Create an event when a permission to read a file or directory is requested.
 201 An fanotify file descriptor created with
 202 .B FAN_CLASS_PRE_CONTENT
 203 or
 204 .B FAN_CLASS_CONTENT
 205 is required.
 206 .TP
 207 .B FAN_ONDIR
 208 Create events for directories\(emfor example, when
 209 .BR opendir (3),
 210 .BR readdir (3)
 211 (but see BUGS), and
 212 .BR closedir (3)
 213 are called.
 214 Without this flag, only events for files are created.
 215 .TP
 216 .B FAN_EVENT_ON_CHILD
 217 Events for the immediate children of marked directories shall be created.
 218 The flag has no effect when marking mounts and filesystems.
 219 Note that events are not generated for children of the subdirectories
 220 of marked directories.
 221 To monitor complete directory trees it is necessary to mark the relevant
 222 mount.
 223 .PP
 224 The following composed value is defined:
 225 .TP
 226 .B FAN_CLOSE
 227 A file is closed
 228 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
 229 .PP
 230 The filesystem object to be marked is determined by the file descriptor
 231 .I dirfd
 232 and the pathname specified in
 233 .IR pathname :
 234 .IP * 3
 235 If
 236 .I pathname
 237 is NULL,
 238 .I dirfd
 239 defines the filesystem object to be marked.
 240 .IP *
 241 If
 242 .I pathname
 243 is NULL, and
 244 .I dirfd
 245 takes the special value
 246 .BR AT_FDCWD ,
 247 the current working directory is to be marked.
 248 .IP *
 249 If
 250 .I pathname
 251 is absolute, it defines the filesystem object to be marked, and
 252 .I dirfd
 253 is ignored.
 254 .IP *
 255 If
 256 .I pathname
 257 is relative, and
 258 .I dirfd
 259 does not have the value
 260 .BR AT_FDCWD ,
 261 then the filesystem object to be marked is determined by interpreting
 262 .I pathname
 263 relative the directory referred to by
 264 .IR dirfd .
 265 .IP *
 266 If
 267 .I pathname
 268 is relative, and
 269 .I dirfd
 270 has the value
 271 .BR AT_FDCWD ,
 272 then the filesystem object to be marked is determined by interpreting
 273 .I pathname
 274 relative the current working directory.
 275 .SH RETURN VALUE
 276 On success,
 277 .BR fanotify_mark ()
 278 returns 0.
 279 On error, \-1 is returned, and
 280 .I errno
 281 is set to indicate the error.
 282 .SH ERRORS
 283 .TP
 284 .B EBADF
 285 An invalid file descriptor was passed in
 286 .IR fanotify_fd .
 287 .TP
 288 .B EINVAL
 289 An invalid value was passed in
 290 .IR flags
 291 or
 292 .IR mask ,
 293 or
 294 .I fanotify_fd
 295 was not an fanotify file descriptor.
 296 .TP
 297 .B EINVAL
 298 The fanotify file descriptor was opened with
 299 .B FAN_CLASS_NOTIF
 300 and mask contains a flag for permission events
 301 .RB ( FAN_OPEN_PERM
 302 or
 303 .BR FAN_ACCESS_PERM ).
 304 .TP
 305 .B ENOENT
 306 The filesystem object indicated by
 307 .IR dirfd
 308 and
 309 .IR pathname
 310 does not exist.
 311 This error also occurs when trying to remove a mark from an object
 312 which is not marked.
 313 .TP
 314 .B ENOMEM
 315 The necessary memory could not be allocated.
 316 .TP
 317 .B ENOSPC
 318 The number of marks exceeds the limit of 8192 and the
 319 .B FAN_UNLIMITED_MARKS
 320 flag was not specified when the fanotify file descriptor was created with
 321 .BR fanotify_init (2).
 322 .TP
 323 .B ENOSYS
 324 This kernel does not implement
 325 .BR fanotify_mark ().
 326 The fanotify API is available only if the kernel was configured with
 327 .BR CONFIG_FANOTIFY .
 328 .TP
 329 .B ENOTDIR
 330 .I flags
 331 contains
 332 .BR FAN_MARK_ONLYDIR ,
 333 and
 334 .I dirfd
 335 and
 336 .I pathname
 337 do not specify a directory.
 338 .SH VERSIONS
 339 .BR fanotify_mark ()
 340 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 341 2.6.37.
 342 .SH CONFORMING TO
 343 This system call is Linux-specific.
 344 .SH NOTES
 345 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
 346 When using either
 347 .B FAN_OPEN_EXEC
 348 or
 349 .B FAN_OPEN_EXEC_PERM
 350 within the
 351 .IR mask ,
 352 events of these types will be returned only when the direct execution of a
 353 program occurs.
 354 More specifically, this means that events of these types will be generated
 355 for files that are opened using
 356 .BR execve (2),
 357 .BR execveat (2),
 358 or
 359 .BR uselib (2).
 360 Events of these types will not be raised in the situation where an
 361 interpreter is passed (or reads) a script file for interpretation.
 362 .PP
 363 Additionally, if a mark has also been placed on the Linux dynamic
 364 linker, a user should also expect to receive an event for it when
 365 an ELF object has been successfully opened using
 366 .BR execve (2)
 367 or
 368 .BR execveat (2).
 369 .PP
 370 For example, if the following ELF binary were to be invoked and a
 371 .BR FAN_OPEN_EXEC
 372 mark has been placed on /:
 373 .PP
 374 .in +4n
 375 .EX
 376 $ /bin/echo foo
 377 .EE
 378 .in
 379 .PP
 380 The listening application in this case would receive
 381 .BR FAN_OPEN_EXEC
 382 events for both the ELF binary and interpreter, respectively:
 383 .PP
 384 .in +4n
 385 .EX
 386 /bin/echo
 387 /lib64/ld-linux-x86-64.so.2
 388 .EE
 389 .in
 390 .SH BUGS
 391 The following bugs were present in Linux kernels before version 3.16:
 392 .IP * 3
 393 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
 394 If
 395 .I flags
 396 contains
 397 .BR FAN_MARK_FLUSH ,
 398 .I dirfd
 399 and
 400 .I pathname
 401 must specify a valid filesystem object, even though this object is not used.
 402 .IP *
 403 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
 404 .BR readdir (2)
 405 does not generate a
 406 .B FAN_ACCESS
 407 event.
 408 .IP *
 409 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
 410 If
 411 .BR fanotify_mark ()
 412 is called with
 413 .BR FAN_MARK_FLUSH ,
 414 .I flags
 415 is not checked for invalid values.
 416 .SH SEE ALSO
 417 .BR fanotify_init (2),
 418 .BR fanotify (7)