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