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