man2/fanotify_mark.2

   1 .\" Copyright (C) 2013,  Heinrich Schuchardt <xypron.glpk@gmx.de>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .TH FANOTIFY_MARK 2 2022-09-09 "Linux man-pages (unreleased)"
   5 .SH NAME
   6 fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem
   7 object
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <sys/fanotify.h>
  14 .PP
  15 .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags ,
  16 .BI "                  uint64_t " mask ", int " dirfd \
  17 ", const char *" pathname );
  18 .fi
  19 .SH DESCRIPTION
  20 For an overview of the fanotify API, see
  21 .BR fanotify (7).
  22 .PP
  23 .BR fanotify_mark ()
  24 adds, removes, or modifies an fanotify mark on a filesystem object.
  25 The caller must have read permission on the filesystem object that
  26 is to be marked.
  27 .PP
  28 The
  29 .I fanotify_fd
  30 argument is a file descriptor returned by
  31 .BR fanotify_init (2).
  32 .PP
  33 .I flags
  34 is a bit mask describing the modification to perform.
  35 It must include exactly one of the following values:
  36 .TP
  37 .B FAN_MARK_ADD
  38 The events in
  39 .I mask
  40 will be added to the mark mask (or to the ignore mask).
  41 .I mask
  42 must be nonempty or the error
  43 .B EINVAL
  44 will occur.
  45 .TP
  46 .B FAN_MARK_REMOVE
  47 The events in argument
  48 .I mask
  49 will be removed from the mark mask (or from the ignore mask).
  50 .I mask
  51 must be nonempty or the error
  52 .B EINVAL
  53 will occur.
  54 .TP
  55 .B FAN_MARK_FLUSH
  56 Remove either all marks for filesystems, all marks for mounts, or all
  57 marks for directories and files from the fanotify group.
  58 If
  59 .I flags
  60 contains
  61 .BR FAN_MARK_MOUNT ,
  62 all marks for mounts are removed from the group.
  63 If
  64 .I flags
  65 contains
  66 .BR FAN_MARK_FILESYSTEM ,
  67 all marks for filesystems are removed from the group.
  68 Otherwise, all marks for directories and files are removed.
  69 No flag other than, and at most one of, the flags
  70 .B FAN_MARK_MOUNT
  71 or
  72 .B FAN_MARK_FILESYSTEM
  73 can be used in conjunction with
  74 .BR FAN_MARK_FLUSH .
  75 .I mask
  76 is ignored.
  77 .PP
  78 If none of the values above is specified, or more than one is specified,
  79 the call fails with the error
  80 .BR EINVAL .
  81 .PP
  82 In addition,
  83 zero or more of the following values may be ORed into
  84 .IR flags :
  85 .TP
  86 .B FAN_MARK_DONT_FOLLOW
  87 If
  88 .I pathname
  89 is a symbolic link, mark the link itself, rather than the file to which it
  90 refers.
  91 (By default,
  92 .BR fanotify_mark ()
  93 dereferences
  94 .I pathname
  95 if it is a symbolic link.)
  96 .TP
  97 .B FAN_MARK_ONLYDIR
  98 If the filesystem object to be marked is not a directory, the error
  99 .B ENOTDIR
 100 shall be raised.
 101 .TP
 102 .B FAN_MARK_MOUNT
 103 Mark the mount specified by
 104 .IR pathname .
 105 If
 106 .I pathname
 107 is not itself a mount point, the mount containing
 108 .I pathname
 109 will be marked.
 110 All directories, subdirectories, and the contained files of the mount
 111 will be monitored.
 112 The events which require that filesystem objects are identified by file handles,
 113 such as
 114 .BR FAN_CREATE ,
 115 .BR FAN_ATTRIB ,
 116 .BR FAN_MOVE ,
 117 and
 118 .BR FAN_DELETE_SELF ,
 119 cannot be provided as a
 120 .I mask
 121 when
 122 .I flags
 123 contains
 124 .BR FAN_MARK_MOUNT .
 125 Attempting to do so will result in the error
 126 .B EINVAL
 127 being returned.
 128 Use of this flag requires the
 129 .B CAP_SYS_ADMIN
 130 capability.
 131 .TP
 132 .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
 133 .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
 134 Mark the filesystem specified by
 135 .IR pathname .
 136 The filesystem containing
 137 .I pathname
 138 will be marked.
 139 All the contained files and directories of the filesystem from any mount
 140 point will be monitored.
 141 Use of this flag requires the
 142 .B CAP_SYS_ADMIN
 143 capability.
 144 .TP
 145 .B FAN_MARK_IGNORED_MASK
 146 The events in
 147 .I mask
 148 shall be added to or removed from the ignore mask.
 149 .TP
 150 .B FAN_MARK_IGNORED_SURV_MODIFY
 151 The ignore mask shall survive modify events.
 152 If this flag is not set,
 153 the ignore mask is cleared when a modify event occurs
 154 for the ignored file or directory.
 155 .TP
 156 .BR FAN_MARK_EVICTABLE " (since Linux 5.19)"
 157 .\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c
 158 When an inode mark is created with this flag,
 159 the inode object will not be pinned to the inode cache,
 160 therefore,
 161 allowing the inode object to be evicted from the inode cache
 162 when the memory pressure on the system is high.
 163 The eviction of the inode object
 164 results in the evictable mark also being lost.
 165 When the mask of an evictable inode mark is updated
 166 without using the
 167 .B FAN_MARK_EVICATBLE
 168 flag,
 169 the marked inode is pinned to inode cache
 170 and the mark is no longer evictable.
 171 When the mask of a non-evictable inode mark is updated
 172 with the
 173 .B FAN_MARK_EVICTABLE
 174 flag,
 175 the inode mark remains non-evictable
 176 and the update fails with
 177 .B EEXIST
 178 error.
 179 Mounts and filesystems are not evictable objects,
 180 therefore,
 181 an attempt to create a mount mark or a filesystem mark
 182 with the
 183 .B FAN_MARK_EVICTABLE
 184 flag,
 185 will result in the error
 186 .BR EINVAL .
 187 For example,
 188 inode marks can be used in combination with mount marks
 189 to reduce the amount of events from noninteresting paths.
 190 The event listener reads events,
 191 checks if the path reported in the event is of interest,
 192 and if it is not,
 193 the listener sets a mark with an ignore mask on the directory.
 194 Evictable inode marks allow using this method for a large number of directories
 195 without the concern of pinning all inodes and exhausting the system's memory.
 196 .PP
 197 .I mask
 198 defines which events shall be listened for (or which shall be ignored).
 199 It is a bit mask composed of the following values:
 200 .TP
 201 .B FAN_ACCESS
 202 Create an event when a file or directory (but see BUGS) is accessed (read).
 203 .TP
 204 .B FAN_MODIFY
 205 Create an event when a file is modified (write).
 206 .TP
 207 .B FAN_CLOSE_WRITE
 208 Create an event when a writable file is closed.
 209 .TP
 210 .B FAN_CLOSE_NOWRITE
 211 Create an event when a read-only file or directory is closed.
 212 .TP
 213 .B FAN_OPEN
 214 Create an event when a file or directory is opened.
 215 .TP
 216 .BR FAN_OPEN_EXEC " (since Linux 5.0)"
 217 .\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa
 218 Create an event when a file is opened with the intent to be executed.
 219 See NOTES for additional details.
 220 .TP
 221 .BR FAN_ATTRIB " (since Linux 5.1)"
 222 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 223 Create an event when the metadata for a file or directory has changed.
 224 An fanotify group that identifies filesystem objects by file handles
 225 is required.
 226 .TP
 227 .BR FAN_CREATE " (since Linux 5.1)"
 228 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 229 Create an event when a file or directory has been created in a marked
 230 parent directory.
 231 An fanotify group that identifies filesystem objects by file handles
 232 is required.
 233 .TP
 234 .BR FAN_DELETE " (since Linux 5.1)"
 235 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 236 Create an event when a file or directory has been deleted in a marked
 237 parent directory.
 238 An fanotify group that identifies filesystem objects by file handles
 239 is required.
 240 .TP
 241 .BR FAN_DELETE_SELF " (since Linux 5.1)"
 242 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 243 Create an event when a marked file or directory itself is deleted.
 244 An fanotify group that identifies filesystem objects by file handles
 245 is required.
 246 .TP
 247 .BR FAN_FS_ERROR " (since Linux 5.16)"
 248 .\" commit 9709bd548f11a092d124698118013f66e1740f9b
 249 Create an event when a filesystem error
 250 leading to inconsistent filesystem metadata is detected.
 251 An additional information record of type
 252 .B FAN_EVENT_INFO_TYPE_ERROR
 253 is returned for each event in the read buffer.
 254 An fanotify group that identifies filesystem objects by file handles
 255 is required.
 256 .IP
 257 Events of such type are dependent on support
 258 from the underlying filesystem.
 259 At the time of writing,
 260 only the
 261 .B ext4
 262 filesystem reports
 263 .B FAN_FS_ERROR
 264 events.
 265 .IP
 266 See
 267 .BR fanotify (7)
 268 for additional details.
 269 .TP
 270 .BR FAN_MOVED_FROM " (since Linux 5.1)"
 271 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 272 Create an event when a file or directory has been moved from a marked
 273 parent directory.
 274 An fanotify group that identifies filesystem objects by file handles
 275 is required.
 276 .TP
 277 .BR FAN_MOVED_TO " (since Linux 5.1)"
 278 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 279 Create an event when a file or directory has been moved to a marked parent
 280 directory.
 281 An fanotify group that identifies filesystem objects by file handles
 282 is required.
 283 .TP
 284 .BR FAN_RENAME " (since Linux 5.17)"
 285 .\" commit 8cc3b1ccd930fe6971e1527f0c4f1bdc8cb56026
 286 This event contains the same information provided by events
 287 .B FAN_MOVED_FROM
 288 and
 289 .BR FAN_MOVED_TO ,
 290 however is represented by a single event with up to two information records.
 291 An fanotify group that identifies filesystem objects by file handles
 292 is required.
 293 If the filesystem object to be marked is not a directory, the error
 294 .B ENOTDIR
 295 shall be raised.
 296 .TP
 297 .BR FAN_MOVE_SELF " (since Linux 5.1)"
 298 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 299 Create an event when a marked file or directory itself has been moved.
 300 An fanotify group that identifies filesystem objects by file handles
 301 is required.
 302 .TP
 303 .B FAN_OPEN_PERM
 304 Create an event when a permission to open a file or directory is requested.
 305 An fanotify file descriptor created with
 306 .B FAN_CLASS_PRE_CONTENT
 307 or
 308 .B FAN_CLASS_CONTENT
 309 is required.
 310 .TP
 311 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
 312 .\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9
 313 Create an event when a permission to open a file for execution is
 314 requested.
 315 An fanotify file descriptor created with
 316 .B FAN_CLASS_PRE_CONTENT
 317 or
 318 .B FAN_CLASS_CONTENT
 319 is required.
 320 See NOTES for additional details.
 321 .TP
 322 .B FAN_ACCESS_PERM
 323 Create an event when a permission to read a file or directory is requested.
 324 An fanotify file descriptor created with
 325 .B FAN_CLASS_PRE_CONTENT
 326 or
 327 .B FAN_CLASS_CONTENT
 328 is required.
 329 .TP
 330 .B FAN_ONDIR
 331 Create events for directories\(emfor example, when
 332 .BR opendir (3),
 333 .BR readdir (3)
 334 (but see BUGS), and
 335 .BR closedir (3)
 336 are called.
 337 Without this flag, events are created only for files.
 338 In the context of directory entry events, such as
 339 .BR FAN_CREATE ,
 340 .BR FAN_DELETE ,
 341 .BR FAN_MOVED_FROM ,
 342 and
 343 .BR FAN_MOVED_TO ,
 344 specifying the flag
 345 .B FAN_ONDIR
 346 is required in order to create events when subdirectory entries are
 347 modified (i.e.,
 348 .BR mkdir (2)/
 349 .BR rmdir (2)).
 350 .TP
 351 .B FAN_EVENT_ON_CHILD
 352 Events for the immediate children of marked directories shall be created.
 353 The flag has no effect when marking mounts and filesystems.
 354 Note that events are not generated for children of the subdirectories
 355 of marked directories.
 356 More specifically, the directory entry modification events
 357 .BR FAN_CREATE ,
 358 .BR FAN_DELETE ,
 359 .BR FAN_MOVED_FROM ,
 360 and
 361 .B FAN_MOVED_TO
 362 are not generated for any entry modifications performed inside subdirectories
 363 of marked directories.
 364 Note that the events
 365 .B FAN_DELETE_SELF
 366 and
 367 .B FAN_MOVE_SELF
 368 are not generated for children of marked directories.
 369 To monitor complete directory trees it is necessary to mark the relevant
 370 mount or filesystem.
 371 .PP
 372 The following composed values are defined:
 373 .TP
 374 .B FAN_CLOSE
 375 A file is closed
 376 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
 377 .TP
 378 .B FAN_MOVE
 379 A file or directory has been moved
 380 .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ).
 381 .PP
 382 The filesystem object to be marked is determined by the file descriptor
 383 .I dirfd
 384 and the pathname specified in
 385 .IR pathname :
 386 .IP * 3
 387 If
 388 .I pathname
 389 is NULL,
 390 .I dirfd
 391 defines the filesystem object to be marked.
 392 .IP *
 393 If
 394 .I pathname
 395 is NULL, and
 396 .I dirfd
 397 takes the special value
 398 .BR AT_FDCWD ,
 399 the current working directory is to be marked.
 400 .IP *
 401 If
 402 .I pathname
 403 is absolute, it defines the filesystem object to be marked, and
 404 .I dirfd
 405 is ignored.
 406 .IP *
 407 If
 408 .I pathname
 409 is relative, and
 410 .I dirfd
 411 does not have the value
 412 .BR AT_FDCWD ,
 413 then the filesystem object to be marked is determined by interpreting
 414 .I pathname
 415 relative the directory referred to by
 416 .IR dirfd .
 417 .IP *
 418 If
 419 .I pathname
 420 is relative, and
 421 .I dirfd
 422 has the value
 423 .BR AT_FDCWD ,
 424 then the filesystem object to be marked is determined by interpreting
 425 .I pathname
 426 relative to the current working directory.
 427 (See
 428 .BR openat (2)
 429 for an explanation of why the
 430 .I dirfd
 431 argument is useful.)
 432 .SH RETURN VALUE
 433 On success,
 434 .BR fanotify_mark ()
 435 returns 0.
 436 On error, \-1 is returned, and
 437 .I errno
 438 is set to indicate the error.
 439 .SH ERRORS
 440 .TP
 441 .B EBADF
 442 An invalid file descriptor was passed in
 443 .IR fanotify_fd .
 444 .TP
 445 .B EBADF
 446 .I pathname
 447 is relative but
 448 .I dirfd
 449 is neither
 450 .B AT_FDCWD
 451 nor a valid file descriptor.
 452 .TP
 453 .B EEXIST
 454 The filesystem object indicated by
 455 .I dirfd
 456 and
 457 .I pathname
 458 has a mark that was updated without the
 459 .B FAN_MARK_EVICTABLE
 460 flag,
 461 and the user attempted to update the mark with
 462 .B FAN_MARK_EVICTABLE
 463 flag.
 464 .TP
 465 .B EINVAL
 466 An invalid value was passed in
 467 .I flags
 468 or
 469 .IR mask ,
 470 or
 471 .I fanotify_fd
 472 was not an fanotify file descriptor.
 473 .TP
 474 .B EINVAL
 475 The fanotify file descriptor was opened with
 476 .B FAN_CLASS_NOTIF
 477 or the fanotify group identifies filesystem objects by file handles
 478 and mask contains a flag for permission events
 479 .RB ( FAN_OPEN_PERM
 480 or
 481 .BR FAN_ACCESS_PERM ).
 482 .TP
 483 .B EINVAL
 484 The group was initialized without
 485 .B FAN_REPORT_FID
 486 but one or more event types specified in the
 487 .I mask
 488 require it.
 489 .TP
 490 .B ENODEV
 491 The filesystem object indicated by
 492 .I pathname
 493 is not associated with a filesystem that supports
 494 .I fsid
 495 (e.g.,
 496 .BR fuse (4)).
 497 .BR tmpfs (5)
 498 did not support
 499 .I fsid
 500 prior to Linux 5.13.
 501 .\" commit 59cda49ecf6c9a32fae4942420701b6e087204f6
 502 This error can be returned only with an fanotify group that identifies
 503 filesystem objects by file handles.
 504 .TP
 505 .B ENOENT
 506 The filesystem object indicated by
 507 .I dirfd
 508 and
 509 .I pathname
 510 does not exist.
 511 This error also occurs when trying to remove a mark from an object
 512 which is not marked.
 513 .TP
 514 .B ENOMEM
 515 The necessary memory could not be allocated.
 516 .TP
 517 .B ENOSPC
 518 The number of marks for this user exceeds the limit and the
 519 .B FAN_UNLIMITED_MARKS
 520 flag was not specified when the fanotify file descriptor was created with
 521 .BR fanotify_init (2).
 522 See
 523 .BR fanotify (7)
 524 for details about this limit.
 525 .TP
 526 .B ENOSYS
 527 This kernel does not implement
 528 .BR fanotify_mark ().
 529 The fanotify API is available only if the kernel was configured with
 530 .BR CONFIG_FANOTIFY .
 531 .TP
 532 .B ENOTDIR
 533 .I flags
 534 contains
 535 .BR FAN_MARK_ONLYDIR ,
 536 and
 537 .I dirfd
 538 and
 539 .I pathname
 540 do not specify a directory.
 541 .TP
 542 .B ENOTDIR
 543 .I mask
 544 contains
 545 .BR FAN_RENAME ,
 546 and
 547 .I dirfd
 548 and
 549 .I pathname
 550 do not specify a directory.
 551 .TP
 552 .B ENOTDIR
 553 The fanotify group was initialized with flag
 554 .BR FAN_REPORT_TARGET_FID ,
 555 .I mask
 556 contains directory entry modification events
 557 (e.g.,
 558 .BR FAN_CREATE ,
 559 .BR FAN_DELETE ),
 560 or directory event flags
 561 (e.g.,
 562 .BR FAN_ONDIR ,
 563 .BR FAN_EVENT_ON_CHILD ),
 564 and
 565 .I dirfd
 566 and
 567 .I pathname
 568 do not specify a directory.
 569 .TP
 570 .B EOPNOTSUPP
 571 The object indicated by
 572 .I pathname
 573 is associated with a filesystem that does not support the encoding of file
 574 handles.
 575 This error can be returned only with an fanotify group that identifies
 576 filesystem objects by file handles.
 577 .TP
 578 .B EPERM
 579 The operation is not permitted because the caller lacks a required capability.
 580 .TP
 581 .B EXDEV
 582 The filesystem object indicated by
 583 .I pathname
 584 resides within a filesystem subvolume (e.g.,
 585 .BR btrfs (5))
 586 which uses a different
 587 .I fsid
 588 than its root superblock.
 589 This error can be returned only with an fanotify group that identifies
 590 filesystem objects by file handles.
 591 .SH VERSIONS
 592 .BR fanotify_mark ()
 593 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 594 2.6.37.
 595 .SH STANDARDS
 596 This system call is Linux-specific.
 597 .SH NOTES
 598 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
 599 When using either
 600 .B FAN_OPEN_EXEC
 601 or
 602 .B FAN_OPEN_EXEC_PERM
 603 within the
 604 .IR mask ,
 605 events of these types will be returned only when the direct execution of a
 606 program occurs.
 607 More specifically, this means that events of these types will be generated
 608 for files that are opened using
 609 .BR execve (2),
 610 .BR execveat (2),
 611 or
 612 .BR uselib (2).
 613 Events of these types will not be raised in the situation where an
 614 interpreter is passed (or reads) a file for interpretation.
 615 .PP
 616 Additionally, if a mark has also been placed on the Linux dynamic
 617 linker, a user should also expect to receive an event for it when
 618 an ELF object has been successfully opened using
 619 .BR execve (2)
 620 or
 621 .BR execveat (2).
 622 .PP
 623 For example, if the following ELF binary were to be invoked and a
 624 .B FAN_OPEN_EXEC
 625 mark has been placed on /:
 626 .PP
 627 .in +4n
 628 .EX
 629 $ /bin/echo foo
 630 .EE
 631 .in
 632 .PP
 633 The listening application in this case would receive
 634 .B FAN_OPEN_EXEC
 635 events for both the ELF binary and interpreter, respectively:
 636 .PP
 637 .in +4n
 638 .EX
 639 /bin/echo
 640 /lib64/ld\-linux\-x86\-64.so.2
 641 .EE
 642 .in
 643 .SH BUGS
 644 The following bugs were present in Linux kernels before version 3.16:
 645 .IP * 3
 646 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
 647 If
 648 .I flags
 649 contains
 650 .BR FAN_MARK_FLUSH ,
 651 .IR dirfd ,
 652 and
 653 .I pathname
 654 must specify a valid filesystem object, even though this object is not used.
 655 .IP *
 656 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
 657 .BR readdir (2)
 658 does not generate a
 659 .B FAN_ACCESS
 660 event.
 661 .IP *
 662 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
 663 If
 664 .BR fanotify_mark ()
 665 is called with
 666 .BR FAN_MARK_FLUSH ,
 667 .I flags
 668 is not checked for invalid values.
 669 .SH SEE ALSO
 670 .BR fanotify_init (2),
 671 .BR fanotify (7)