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 2021-08-27 "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 .PP
 156 .I mask
 157 defines which events shall be listened for (or which shall be ignored).
 158 It is a bit mask composed of the following values:
 159 .TP
 160 .B FAN_ACCESS
 161 Create an event when a file or directory (but see BUGS) is accessed (read).
 162 .TP
 163 .B FAN_MODIFY
 164 Create an event when a file is modified (write).
 165 .TP
 166 .B FAN_CLOSE_WRITE
 167 Create an event when a writable file is closed.
 168 .TP
 169 .B FAN_CLOSE_NOWRITE
 170 Create an event when a read-only file or directory is closed.
 171 .TP
 172 .B FAN_OPEN
 173 Create an event when a file or directory is opened.
 174 .TP
 175 .BR FAN_OPEN_EXEC " (since Linux 5.0)"
 176 .\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa
 177 Create an event when a file is opened with the intent to be executed.
 178 See NOTES for additional details.
 179 .TP
 180 .BR FAN_ATTRIB " (since Linux 5.1)"
 181 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 182 Create an event when the metadata for a file or directory has changed.
 183 An fanotify group that identifies filesystem objects by file handles
 184 is required.
 185 .TP
 186 .BR FAN_CREATE " (since Linux 5.1)"
 187 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 188 Create an event when a file or directory has been created in a marked
 189 parent directory.
 190 An fanotify group that identifies filesystem objects by file handles
 191 is required.
 192 .TP
 193 .BR FAN_DELETE " (since Linux 5.1)"
 194 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 195 Create an event when a file or directory has been deleted in a marked
 196 parent directory.
 197 An fanotify group that identifies filesystem objects by file handles
 198 is required.
 199 .TP
 200 .BR FAN_DELETE_SELF " (since Linux 5.1)"
 201 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 202 Create an event when a marked file or directory itself is deleted.
 203 An fanotify group that identifies filesystem objects by file handles
 204 is required.
 205 .TP
 206 .BR FAN_FS_ERROR " (since Linux 5.16)"
 207 .\" commit 9709bd548f11a092d124698118013f66e1740f9b
 208 Create an event when a filesystem error
 209 leading to inconsistent filesystem metadata is detected.
 210 An additional information record of type
 211 .B FAN_EVENT_INFO_TYPE_ERROR
 212 is returned for each event in the read buffer.
 213 An fanotify group that identifies filesystem objects by file handles
 214 is required.
 215 .IP
 216 Events of such type are dependent on support
 217 from the underlying filesystem.
 218 At the time of writing,
 219 only the
 220 .B ext4
 221 filesystem reports
 222 .B FAN_FS_ERROR
 223 events.
 224 .IP
 225 See
 226 .BR fanotify (7)
 227 for additional details.
 228 .TP
 229 .BR FAN_MOVED_FROM " (since Linux 5.1)"
 230 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 231 Create an event when a file or directory has been moved from a marked
 232 parent directory.
 233 An fanotify group that identifies filesystem objects by file handles
 234 is required.
 235 .TP
 236 .BR FAN_MOVED_TO " (since Linux 5.1)"
 237 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 238 Create an event when a file or directory has been moved to a marked parent
 239 directory.
 240 An fanotify group that identifies filesystem objects by file handles
 241 is required.
 242 .TP
 243 .BR FAN_RENAME " (since Linux 5.17)"
 244 .\" commit 8cc3b1ccd930fe6971e1527f0c4f1bdc8cb56026
 245 This event contains the same information provided by events
 246 .B FAN_MOVED_FROM
 247 and
 248 .BR FAN_MOVED_TO ,
 249 however is represented by a single event with up to two information records.
 250 An fanotify group that identifies filesystem objects by file handles
 251 is required.
 252 If the filesystem object to be marked is not a directory, the error
 253 .B ENOTDIR
 254 shall be raised.
 255 .TP
 256 .BR FAN_MOVE_SELF " (since Linux 5.1)"
 257 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
 258 Create an event when a marked file or directory itself has been moved.
 259 An fanotify group that identifies filesystem objects by file handles
 260 is required.
 261 .TP
 262 .B FAN_OPEN_PERM
 263 Create an event when a permission to open a file or directory is requested.
 264 An fanotify file descriptor created with
 265 .B FAN_CLASS_PRE_CONTENT
 266 or
 267 .B FAN_CLASS_CONTENT
 268 is required.
 269 .TP
 270 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
 271 .\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9
 272 Create an event when a permission to open a file for execution is
 273 requested.
 274 An fanotify file descriptor created with
 275 .B FAN_CLASS_PRE_CONTENT
 276 or
 277 .B FAN_CLASS_CONTENT
 278 is required.
 279 See NOTES for additional details.
 280 .TP
 281 .B FAN_ACCESS_PERM
 282 Create an event when a permission to read a file or directory is requested.
 283 An fanotify file descriptor created with
 284 .B FAN_CLASS_PRE_CONTENT
 285 or
 286 .B FAN_CLASS_CONTENT
 287 is required.
 288 .TP
 289 .B FAN_ONDIR
 290 Create events for directories\(emfor example, when
 291 .BR opendir (3),
 292 .BR readdir (3)
 293 (but see BUGS), and
 294 .BR closedir (3)
 295 are called.
 296 Without this flag, events are created only for files.
 297 In the context of directory entry events, such as
 298 .BR FAN_CREATE ,
 299 .BR FAN_DELETE ,
 300 .BR FAN_MOVED_FROM ,
 301 and
 302 .BR FAN_MOVED_TO ,
 303 specifying the flag
 304 .B FAN_ONDIR
 305 is required in order to create events when subdirectory entries are
 306 modified (i.e.,
 307 .BR mkdir (2)/
 308 .BR rmdir (2)).
 309 .TP
 310 .B FAN_EVENT_ON_CHILD
 311 Events for the immediate children of marked directories shall be created.
 312 The flag has no effect when marking mounts and filesystems.
 313 Note that events are not generated for children of the subdirectories
 314 of marked directories.
 315 More specifically, the directory entry modification events
 316 .BR FAN_CREATE ,
 317 .BR FAN_DELETE ,
 318 .BR FAN_MOVED_FROM ,
 319 and
 320 .B FAN_MOVED_TO
 321 are not generated for any entry modifications performed inside subdirectories
 322 of marked directories.
 323 Note that the events
 324 .B FAN_DELETE_SELF
 325 and
 326 .B FAN_MOVE_SELF
 327 are not generated for children of marked directories.
 328 To monitor complete directory trees it is necessary to mark the relevant
 329 mount or filesystem.
 330 .PP
 331 The following composed values are defined:
 332 .TP
 333 .B FAN_CLOSE
 334 A file is closed
 335 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
 336 .TP
 337 .B FAN_MOVE
 338 A file or directory has been moved
 339 .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ).
 340 .PP
 341 The filesystem object to be marked is determined by the file descriptor
 342 .I dirfd
 343 and the pathname specified in
 344 .IR pathname :
 345 .IP * 3
 346 If
 347 .I pathname
 348 is NULL,
 349 .I dirfd
 350 defines the filesystem object to be marked.
 351 .IP *
 352 If
 353 .I pathname
 354 is NULL, and
 355 .I dirfd
 356 takes the special value
 357 .BR AT_FDCWD ,
 358 the current working directory is to be marked.
 359 .IP *
 360 If
 361 .I pathname
 362 is absolute, it defines the filesystem object to be marked, and
 363 .I dirfd
 364 is ignored.
 365 .IP *
 366 If
 367 .I pathname
 368 is relative, and
 369 .I dirfd
 370 does not have the value
 371 .BR AT_FDCWD ,
 372 then the filesystem object to be marked is determined by interpreting
 373 .I pathname
 374 relative the directory referred to by
 375 .IR dirfd .
 376 .IP *
 377 If
 378 .I pathname
 379 is relative, and
 380 .I dirfd
 381 has the value
 382 .BR AT_FDCWD ,
 383 then the filesystem object to be marked is determined by interpreting
 384 .I pathname
 385 relative to the current working directory.
 386 (See
 387 .BR openat (2)
 388 for an explanation of why the
 389 .I dirfd
 390 argument is useful.)
 391 .SH RETURN VALUE
 392 On success,
 393 .BR fanotify_mark ()
 394 returns 0.
 395 On error, \-1 is returned, and
 396 .I errno
 397 is set to indicate the error.
 398 .SH ERRORS
 399 .TP
 400 .B EBADF
 401 An invalid file descriptor was passed in
 402 .IR fanotify_fd .
 403 .TP
 404 .B EBADF
 405 .I pathname
 406 is relative but
 407 .I dirfd
 408 is neither
 409 .B AT_FDCWD
 410 nor a valid file descriptor.
 411 .TP
 412 .B EINVAL
 413 An invalid value was passed in
 414 .I flags
 415 or
 416 .IR mask ,
 417 or
 418 .I fanotify_fd
 419 was not an fanotify file descriptor.
 420 .TP
 421 .B EINVAL
 422 The fanotify file descriptor was opened with
 423 .B FAN_CLASS_NOTIF
 424 or the fanotify group identifies filesystem objects by file handles
 425 and mask contains a flag for permission events
 426 .RB ( FAN_OPEN_PERM
 427 or
 428 .BR FAN_ACCESS_PERM ).
 429 .TP
 430 .B EINVAL
 431 The group was initialized without
 432 .B FAN_REPORT_FID
 433 but one or more event types specified in the
 434 .I mask
 435 require it.
 436 .TP
 437 .B ENODEV
 438 The filesystem object indicated by
 439 .I pathname
 440 is not associated with a filesystem that supports
 441 .I fsid
 442 (e.g.,
 443 .BR fuse (4)).
 444 .BR tmpfs (5)
 445 did not support
 446 .I fsid
 447 prior to Linux 5.13.
 448 .\" commit 59cda49ecf6c9a32fae4942420701b6e087204f6
 449 This error can be returned only with an fanotify group that identifies
 450 filesystem objects by file handles.
 451 .TP
 452 .B ENOENT
 453 The filesystem object indicated by
 454 .I dirfd
 455 and
 456 .I pathname
 457 does not exist.
 458 This error also occurs when trying to remove a mark from an object
 459 which is not marked.
 460 .TP
 461 .B ENOMEM
 462 The necessary memory could not be allocated.
 463 .TP
 464 .B ENOSPC
 465 The number of marks for this user exceeds the limit and the
 466 .B FAN_UNLIMITED_MARKS
 467 flag was not specified when the fanotify file descriptor was created with
 468 .BR fanotify_init (2).
 469 See
 470 .BR fanotify (7)
 471 for details about this limit.
 472 .TP
 473 .B ENOSYS
 474 This kernel does not implement
 475 .BR fanotify_mark ().
 476 The fanotify API is available only if the kernel was configured with
 477 .BR CONFIG_FANOTIFY .
 478 .TP
 479 .B ENOTDIR
 480 .I flags
 481 contains
 482 .BR FAN_MARK_ONLYDIR ,
 483 and
 484 .I dirfd
 485 and
 486 .I pathname
 487 do not specify a directory.
 488 .TP
 489 .B ENOTDIR
 490 .I mask
 491 contains
 492 .BR FAN_RENAME ,
 493 and
 494 .I dirfd
 495 and
 496 .I pathname
 497 do not specify a directory.
 498 .TP
 499 .B ENOTDIR
 500 The fanotify group was initialized with flag
 501 .BR FAN_REPORT_TARGET_FID ,
 502 .I mask
 503 contains directory entry modification events
 504 (e.g.,
 505 .BR FAN_CREATE ,
 506 .BR FAN_DELETE ),
 507 or directory event flags
 508 (e.g.,
 509 .BR FAN_ONDIR ,
 510 .BR FAN_EVENT_ON_CHILD ),
 511 and
 512 .I dirfd
 513 and
 514 .I pathname
 515 do not specify a directory.
 516 .TP
 517 .B EOPNOTSUPP
 518 The object indicated by
 519 .I pathname
 520 is associated with a filesystem that does not support the encoding of file
 521 handles.
 522 This error can be returned only with an fanotify group that identifies
 523 filesystem objects by file handles.
 524 .TP
 525 .B EPERM
 526 The operation is not permitted because the caller lacks a required capability.
 527 .TP
 528 .B EXDEV
 529 The filesystem object indicated by
 530 .I pathname
 531 resides within a filesystem subvolume (e.g.,
 532 .BR btrfs (5))
 533 which uses a different
 534 .I fsid
 535 than its root superblock.
 536 This error can be returned only with an fanotify group that identifies
 537 filesystem objects by file handles.
 538 .SH VERSIONS
 539 .BR fanotify_mark ()
 540 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 541 2.6.37.
 542 .SH STANDARDS
 543 This system call is Linux-specific.
 544 .SH NOTES
 545 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
 546 When using either
 547 .B FAN_OPEN_EXEC
 548 or
 549 .B FAN_OPEN_EXEC_PERM
 550 within the
 551 .IR mask ,
 552 events of these types will be returned only when the direct execution of a
 553 program occurs.
 554 More specifically, this means that events of these types will be generated
 555 for files that are opened using
 556 .BR execve (2),
 557 .BR execveat (2),
 558 or
 559 .BR uselib (2).
 560 Events of these types will not be raised in the situation where an
 561 interpreter is passed (or reads) a file for interpretation.
 562 .PP
 563 Additionally, if a mark has also been placed on the Linux dynamic
 564 linker, a user should also expect to receive an event for it when
 565 an ELF object has been successfully opened using
 566 .BR execve (2)
 567 or
 568 .BR execveat (2).
 569 .PP
 570 For example, if the following ELF binary were to be invoked and a
 571 .B FAN_OPEN_EXEC
 572 mark has been placed on /:
 573 .PP
 574 .in +4n
 575 .EX
 576 $ /bin/echo foo
 577 .EE
 578 .in
 579 .PP
 580 The listening application in this case would receive
 581 .B FAN_OPEN_EXEC
 582 events for both the ELF binary and interpreter, respectively:
 583 .PP
 584 .in +4n
 585 .EX
 586 /bin/echo
 587 /lib64/ld\-linux\-x86\-64.so.2
 588 .EE
 589 .in
 590 .SH BUGS
 591 The following bugs were present in Linux kernels before version 3.16:
 592 .IP * 3
 593 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
 594 If
 595 .I flags
 596 contains
 597 .BR FAN_MARK_FLUSH ,
 598 .IR dirfd ,
 599 and
 600 .I pathname
 601 must specify a valid filesystem object, even though this object is not used.
 602 .IP *
 603 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
 604 .BR readdir (2)
 605 does not generate a
 606 .B FAN_ACCESS
 607 event.
 608 .IP *
 609 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
 610 If
 611 .BR fanotify_mark ()
 612 is called with
 613 .BR FAN_MARK_FLUSH ,
 614 .I flags
 615 is not checked for invalid values.
 616 .SH SEE ALSO
 617 .BR fanotify_init (2),
 618 .BR fanotify (7)