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 2019-03-06 "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 This value cannot be used if the
 130 .I fanotify_fd
 131 file descriptor has been initialized with the flag
 132 .BR FAN_REPORT_FID
 133 or if any of the new directory modification events are provided as a
 134 .IR mask .
 135 Attempting to do so will result in the error
 136 .B EINVAL
 137 being returned.
 138 .TP
 139 .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
 140 .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
 141 Mark the filesystem specified by
 142 .IR pathname .
 143 The filesystem containing
 144 .I pathname
 145 will be marked.
 146 All the contained files and directories of the filesystem from any mount
 147 point will be monitored.
 148 .TP
 149 .B FAN_MARK_IGNORED_MASK
 150 The events in
 151 .I mask
 152 shall be added to or removed from the ignore mask.
 153 .TP
 154 .B FAN_MARK_IGNORED_SURV_MODIFY
 155 The ignore mask shall survive modify events.
 156 If this flag is not set,
 157 the ignore mask is cleared when a modify event occurs
 158 for the ignored file or directory.
 159 .PP
 160 .I mask
 161 defines which events shall be listened for (or which shall be ignored).
 162 It is a bit mask composed of the following values:
 163 .TP
 164 .B FAN_ACCESS
 165 Create an event when a file or directory (but see BUGS) is accessed (read).
 166 .TP
 167 .B FAN_MODIFY
 168 Create an event when a file is modified (write).
 169 .TP
 170 .B FAN_CLOSE_WRITE
 171 Create an event when a writable file is closed.
 172 .TP
 173 .B FAN_CLOSE_NOWRITE
 174 Create an event when a read-only file or directory is closed.
 175 .TP
 176 .B FAN_OPEN
 177 Create an event when a file or directory is opened.
 178 .TP
 179 .B FAN_OPEN_EXEC " (since Linux 5.0)"
 180 Create an event when a file is opened with the intent to be executed.
 181 See NOTES for additional details.
 182 .TP
 183 .B FAN_ATTRIB
 184 Create an event when the metadata for a file or directory has changed.
 185 .TP
 186 .B FAN_CREATE
 187 Create an event when a file or directory has been created in a marked
 188 parent directory.
 189 .TP
 190 .B FAN_DELETE
 191 Create an event when a file or directory has been deleted in a marked
 192 parent directory.
 193 .TP
 194 .B FAN_DELETE_SELF
 195 Create an event when a marked file or directory itself is deleted.
 196 .TP
 197 .B FAN_MOVED_FROM
 198 Create an event when a file or directory has been moved from a marked
 199 parent directory.
 200 .TP
 201 .B FAN_MOVED_TO
 202 Create an event when a file or directory has been moved to a marked parent
 203 directory.
 204 .TP
 205 .B FAN_Q_OVERFLOW
 206 Create an event when an overflow of the event queue occurs.
 207 The size of the event queue is limited to 16384 entries if
 208 .B FAN_UNLIMITED_QUEUE
 209 is not set in
 210 .BR fanotify_init (2).
 211 .TP
 212 .B FAN_OPEN_PERM
 213 Create an event when a permission to open a file or directory is requested.
 214 An fanotify file descriptor created with
 215 .B FAN_CLASS_PRE_CONTENT
 216 or
 217 .B FAN_CLASS_CONTENT
 218 is required.
 219 .TP
 220 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
 221 Create an event when a permission to open a file for execution is
 222 requested.
 223 An fanotify file descriptor created with
 224 .B FAN_CLASS_PRE_CONTENT
 225 or
 226 .B FAN_CLASS_CONTENT
 227 is required.
 228 See NOTES for additional details.
 229 .TP
 230 .B FAN_ACCESS_PERM
 231 Create an event when a permission to read a file or directory is requested.
 232 An fanotify file descriptor created with
 233 .B FAN_CLASS_PRE_CONTENT
 234 or
 235 .B FAN_CLASS_CONTENT
 236 is required.
 237 .TP
 238 .B FAN_ONDIR
 239 Create events for directories\(emfor example, when
 240 .BR opendir (3),
 241 .BR readdir (3)
 242 (but see BUGS), and
 243 .BR closedir (3)
 244 are called.
 245 Without this flag, only events for files are created.
 246 The
 247 .BR FAN_ONDIR
 248 flag is reported in an event mask only if the
 249 .I fanotify_fd
 250 file descriptor has been initialized with the flag
 251 .BR FAN_REPORT_FID .
 252 In the context of directory entry events, such as
 253 .BR FAN_CREATE ,
 254 .BR FAN_DELETE ,
 255 .BR FAN_MOVED_FROM ,
 256 and
 257 .BR FAN_MOVED_TO
 258 for example, specifying the flag
 259 .BR FAN_ONDIR
 260 is required in order to create events when subdirectory entries are
 261 modified (i.e.,
 262 .BR mkdir (2)/
 263 .BR rmdir (2)).
 264 Subdirectory entry modification events will never be merged with
 265 nonsubdirectory entry modification events.
 266 This flag is never reported individually within an event and is always
 267 supplied in conjunction with another event type.
 268 .TP
 269 .B FAN_EVENT_ON_CHILD
 270 Events for the immediate children of marked directories shall be created.
 271 The flag has no effect when marking mounts and filesystems.
 272 Note that events are not generated for children of the subdirectories
 273 of marked directories.
 274 To monitor complete directory trees it is necessary to mark the relevant
 275 mount.
 276 .PP
 277 The following composed values are defined:
 278 .TP
 279 .B FAN_CLOSE
 280 A file is closed
 281 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
 282 .TP
 283 .B FAN_MOVE
 284 A file or directory has been moved
 285 .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ).
 286 .PP
 287 The filesystem object to be marked is determined by the file descriptor
 288 .I dirfd
 289 and the pathname specified in
 290 .IR pathname :
 291 .IP * 3
 292 If
 293 .I pathname
 294 is NULL,
 295 .I dirfd
 296 defines the filesystem object to be marked.
 297 .IP *
 298 If
 299 .I pathname
 300 is NULL, and
 301 .I dirfd
 302 takes the special value
 303 .BR AT_FDCWD ,
 304 the current working directory is to be marked.
 305 .IP *
 306 If
 307 .I pathname
 308 is absolute, it defines the filesystem object to be marked, and
 309 .I dirfd
 310 is ignored.
 311 .IP *
 312 If
 313 .I pathname
 314 is relative, and
 315 .I dirfd
 316 does not have the value
 317 .BR AT_FDCWD ,
 318 then the filesystem object to be marked is determined by interpreting
 319 .I pathname
 320 relative the directory referred to by
 321 .IR dirfd .
 322 .IP *
 323 If
 324 .I pathname
 325 is relative, and
 326 .I dirfd
 327 has the value
 328 .BR AT_FDCWD ,
 329 then the filesystem object to be marked is determined by interpreting
 330 .I pathname
 331 relative the current working directory.
 332 .SH RETURN VALUE
 333 On success,
 334 .BR fanotify_mark ()
 335 returns 0.
 336 On error, \-1 is returned, and
 337 .I errno
 338 is set to indicate the error.
 339 .SH ERRORS
 340 .TP
 341 .B EBADF
 342 An invalid file descriptor was passed in
 343 .IR fanotify_fd .
 344 .TP
 345 .B EINVAL
 346 An invalid value was passed in
 347 .IR flags
 348 or
 349 .IR mask ,
 350 or
 351 .I fanotify_fd
 352 was not an fanotify file descriptor.
 353 .TP
 354 .B EINVAL
 355 The fanotify file descriptor was opened with
 356 .B FAN_CLASS_NOTIF
 357 or
 358 .B FAN_REPORT_FID
 359 and mask contains a flag for permission events
 360 .RB ( FAN_OPEN_PERM
 361 or
 362 .BR FAN_ACCESS_PERM ).
 363 .TP
 364 .B ENOENT
 365 The filesystem object indicated by
 366 .IR dirfd
 367 and
 368 .IR pathname
 369 does not exist.
 370 This error also occurs when trying to remove a mark from an object
 371 which is not marked.
 372 .TP
 373 .B ENOMEM
 374 The necessary memory could not be allocated.
 375 .TP
 376 .B ENOSPC
 377 The number of marks exceeds the limit of 8192 and the
 378 .B FAN_UNLIMITED_MARKS
 379 flag was not specified when the fanotify file descriptor was created with
 380 .BR fanotify_init (2).
 381 .TP
 382 .B ENOSYS
 383 This kernel does not implement
 384 .BR fanotify_mark ().
 385 The fanotify API is available only if the kernel was configured with
 386 .BR CONFIG_FANOTIFY .
 387 .TP
 388 .B ENOTDIR
 389 .I flags
 390 contains
 391 .BR FAN_MARK_ONLYDIR ,
 392 and
 393 .I dirfd
 394 and
 395 .I pathname
 396 do not specify a directory.
 397 .TP
 398 .B EXDEV
 399 The filesystem object indicated by
 400 .I pathname
 401 resides within a filesystem subvolume (e.g.,
 402 .BR btrfs (5))
 403 which uses a different
 404 .I fsid
 405 than its root superblock.
 406 This error can be returned only when an fanotify file descriptor returned
 407 by
 408 .BR fanotify_init (2)
 409 has been created with
 410 .BR FAN_REPORT_FID .
 411 .TP
 412 .B ENODEV
 413 The filesystem object indicated by
 414 .I pathname
 415 is not associated with a filesystem that supports
 416 .I fsid
 417 (e.g.,
 418 .BR tmpfs (5)).
 419 This error can be returned only when an fanotify file descriptor returned
 420 by
 421 .BR fanotify_init (2)
 422 has been created with
 423 .BR FAN_REPORT_FID .
 424 .TP
 425 .B EOPNOTSUPP
 426 The object indicated by
 427 .I pathname
 428 is associated with a filesystem that does not support the encoding of file
 429 handles.
 430 This error can be returned only when an fanotify file descriptor returned
 431 by
 432 .BR fanotify_init (2)
 433 has been created with
 434 .BR FAN_REPORT_FID .
 435 .SH VERSIONS
 436 .BR fanotify_mark ()
 437 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 438 2.6.37.
 439 .SH CONFORMING TO
 440 This system call is Linux-specific.
 441 .SH NOTES
 442 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
 443 When using either
 444 .B FAN_OPEN_EXEC
 445 or
 446 .B FAN_OPEN_EXEC_PERM
 447 within the
 448 .IR mask ,
 449 events of these types will be returned only when the direct execution of a
 450 program occurs.
 451 More specifically, this means that events of these types will be generated
 452 for files that are opened using
 453 .BR execve (2),
 454 .BR execveat (2),
 455 or
 456 .BR uselib (2).
 457 Events of these types will not be raised in the situation where an
 458 interpreter is passed (or reads) a script file for interpretation.
 459 .PP
 460 Additionally, if a mark has also been placed on the Linux dynamic
 461 linker, a user should also expect to receive an event for it when
 462 an ELF object has been successfully opened using
 463 .BR execve (2)
 464 or
 465 .BR execveat (2).
 466 .PP
 467 For example, if the following ELF binary were to be invoked and a
 468 .BR FAN_OPEN_EXEC
 469 mark has been placed on /:
 470 .PP
 471 .in +4n
 472 .EX
 473 $ /bin/echo foo
 474 .EE
 475 .in
 476 .PP
 477 The listening application in this case would receive
 478 .BR FAN_OPEN_EXEC
 479 events for both the ELF binary and interpreter, respectively:
 480 .PP
 481 .in +4n
 482 .EX
 483 /bin/echo
 484 /lib64/ld-linux-x86-64.so.2
 485 .EE
 486 .in
 487 .SH BUGS
 488 The following bugs were present in Linux kernels before version 3.16:
 489 .IP * 3
 490 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
 491 If
 492 .I flags
 493 contains
 494 .BR FAN_MARK_FLUSH ,
 495 .I dirfd
 496 and
 497 .I pathname
 498 must specify a valid filesystem object, even though this object is not used.
 499 .IP *
 500 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
 501 .BR readdir (2)
 502 does not generate a
 503 .B FAN_ACCESS
 504 event.
 505 .IP *
 506 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
 507 If
 508 .BR fanotify_mark ()
 509 is called with
 510 .BR FAN_MARK_FLUSH ,
 511 .I flags
 512 is not checked for invalid values.
 513 .SH SEE ALSO
 514 .BR fanotify_init (2),
 515 .BR fanotify (7)