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 initialized 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 .B FAN_OPEN_PERM
 248 Create an event when a permission to open a file or directory is 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 .TP
 255 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
 256 .\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9
 257 Create an event when a permission to open a file for execution is
 258 requested.
 259 An fanotify file descriptor created with
 260 .B FAN_CLASS_PRE_CONTENT
 261 or
 262 .B FAN_CLASS_CONTENT
 263 is required.
 264 See NOTES for additional details.
 265 .TP
 266 .B FAN_ACCESS_PERM
 267 Create an event when a permission to read a file or directory is requested.
 268 An fanotify file descriptor created with
 269 .B FAN_CLASS_PRE_CONTENT
 270 or
 271 .B FAN_CLASS_CONTENT
 272 is required.
 273 .TP
 274 .B FAN_ONDIR
 275 Create events for directories\(emfor example, when
 276 .BR opendir (3),
 277 .BR readdir (3)
 278 (but see BUGS), and
 279 .BR closedir (3)
 280 are called.
 281 Without this flag, events are created only for files.
 282 In the context of directory entry events, such as
 283 .BR FAN_CREATE ,
 284 .BR FAN_DELETE ,
 285 .BR FAN_MOVED_FROM ,
 286 and
 287 .BR FAN_MOVED_TO ,
 288 specifying the flag
 289 .BR FAN_ONDIR
 290 is required in order to create events when subdirectory entries are
 291 modified (i.e.,
 292 .BR mkdir (2)/
 293 .BR rmdir (2)).
 294 .TP
 295 .B FAN_EVENT_ON_CHILD
 296 Events for the immediate children of marked directories shall be created.
 297 The flag has no effect when marking mounts and filesystems.
 298 Note that events are not generated for children of the subdirectories
 299 of marked directories.
 300 More specifically, the directory entry modification events
 301 .BR FAN_CREATE ,
 302 .BR FAN_DELETE ,
 303 .BR FAN_MOVED_FROM ,
 304 and
 305 .BR FAN_MOVED_TO
 306 are not generated for any entry modifications performed inside subdirectories
 307 of marked directories.
 308 Note that the events
 309 .BR FAN_DELETE_SELF
 310 and
 311 .BR FAN_MOVE_SELF
 312 are not generated for children of marked directories.
 313 To monitor complete directory trees it is necessary to mark the relevant
 314 mount or filesystem.
 315 .PP
 316 The following composed values are defined:
 317 .TP
 318 .B FAN_CLOSE
 319 A file is closed
 320 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
 321 .TP
 322 .B FAN_MOVE
 323 A file or directory has been moved
 324 .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ).
 325 .PP
 326 The filesystem object to be marked is determined by the file descriptor
 327 .I dirfd
 328 and the pathname specified in
 329 .IR pathname :
 330 .IP * 3
 331 If
 332 .I pathname
 333 is NULL,
 334 .I dirfd
 335 defines the filesystem object to be marked.
 336 .IP *
 337 If
 338 .I pathname
 339 is NULL, and
 340 .I dirfd
 341 takes the special value
 342 .BR AT_FDCWD ,
 343 the current working directory is to be marked.
 344 .IP *
 345 If
 346 .I pathname
 347 is absolute, it defines the filesystem object to be marked, and
 348 .I dirfd
 349 is ignored.
 350 .IP *
 351 If
 352 .I pathname
 353 is relative, and
 354 .I dirfd
 355 does not have the value
 356 .BR AT_FDCWD ,
 357 then the filesystem object to be marked is determined by interpreting
 358 .I pathname
 359 relative the directory referred to by
 360 .IR dirfd .
 361 .IP *
 362 If
 363 .I pathname
 364 is relative, and
 365 .I dirfd
 366 has the value
 367 .BR AT_FDCWD ,
 368 then the filesystem object to be marked is determined by interpreting
 369 .I pathname
 370 relative the current working directory.
 371 .SH RETURN VALUE
 372 On success,
 373 .BR fanotify_mark ()
 374 returns 0.
 375 On error, \-1 is returned, and
 376 .I errno
 377 is set to indicate the error.
 378 .SH ERRORS
 379 .TP
 380 .B EBADF
 381 An invalid file descriptor was passed in
 382 .IR fanotify_fd .
 383 .TP
 384 .B EINVAL
 385 An invalid value was passed in
 386 .IR flags
 387 or
 388 .IR mask ,
 389 or
 390 .I fanotify_fd
 391 was not an fanotify file descriptor.
 392 .TP
 393 .B EINVAL
 394 The fanotify file descriptor was opened with
 395 .B FAN_CLASS_NOTIF
 396 or
 397 .B FAN_REPORT_FID
 398 and mask contains a flag for permission events
 399 .RB ( FAN_OPEN_PERM
 400 or
 401 .BR FAN_ACCESS_PERM ).
 402 .TP
 403 .B ENODEV
 404 The filesystem object indicated by
 405 .I pathname
 406 is not associated with a filesystem that supports
 407 .I fsid
 408 (e.g.,
 409 .BR tmpfs (5)).
 410 This error can be returned only when an fanotify file descriptor returned
 411 by
 412 .BR fanotify_init (2)
 413 has been created with
 414 .BR FAN_REPORT_FID .
 415 .TP
 416 .B ENOENT
 417 The filesystem object indicated by
 418 .IR dirfd
 419 and
 420 .IR pathname
 421 does not exist.
 422 This error also occurs when trying to remove a mark from an object
 423 which is not marked.
 424 .TP
 425 .B ENOMEM
 426 The necessary memory could not be allocated.
 427 .TP
 428 .B ENOSPC
 429 The number of marks exceeds the limit of 8192 and the
 430 .B FAN_UNLIMITED_MARKS
 431 flag was not specified when the fanotify file descriptor was created with
 432 .BR fanotify_init (2).
 433 .TP
 434 .B ENOSYS
 435 This kernel does not implement
 436 .BR fanotify_mark ().
 437 The fanotify API is available only if the kernel was configured with
 438 .BR CONFIG_FANOTIFY .
 439 .TP
 440 .B ENOTDIR
 441 .I flags
 442 contains
 443 .BR FAN_MARK_ONLYDIR ,
 444 and
 445 .I dirfd
 446 and
 447 .I pathname
 448 do not specify a directory.
 449 .TP
 450 .B EOPNOTSUPP
 451 The object indicated by
 452 .I pathname
 453 is associated with a filesystem that does not support the encoding of file
 454 handles.
 455 This error can be returned only when an fanotify file descriptor returned
 456 by
 457 .BR fanotify_init (2)
 458 has been created with
 459 .BR FAN_REPORT_FID .
 460 .TP
 461 .B EXDEV
 462 The filesystem object indicated by
 463 .I pathname
 464 resides within a filesystem subvolume (e.g.,
 465 .BR btrfs (5))
 466 which uses a different
 467 .I fsid
 468 than its root superblock.
 469 This error can be returned only when an fanotify file descriptor returned
 470 by
 471 .BR fanotify_init (2)
 472 has been created with
 473 .BR FAN_REPORT_FID .
 474 .SH VERSIONS
 475 .BR fanotify_mark ()
 476 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 477 2.6.37.
 478 .SH CONFORMING TO
 479 This system call is Linux-specific.
 480 .SH NOTES
 481 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
 482 When using either
 483 .B FAN_OPEN_EXEC
 484 or
 485 .B FAN_OPEN_EXEC_PERM
 486 within the
 487 .IR mask ,
 488 events of these types will be returned only when the direct execution of a
 489 program occurs.
 490 More specifically, this means that events of these types will be generated
 491 for files that are opened using
 492 .BR execve (2),
 493 .BR execveat (2),
 494 or
 495 .BR uselib (2).
 496 Events of these types will not be raised in the situation where an
 497 interpreter is passed (or reads) a file for interpretation.
 498 .PP
 499 Additionally, if a mark has also been placed on the Linux dynamic
 500 linker, a user should also expect to receive an event for it when
 501 an ELF object has been successfully opened using
 502 .BR execve (2)
 503 or
 504 .BR execveat (2).
 505 .PP
 506 For example, if the following ELF binary were to be invoked and a
 507 .BR FAN_OPEN_EXEC
 508 mark has been placed on /:
 509 .PP
 510 .in +4n
 511 .EX
 512 $ /bin/echo foo
 513 .EE
 514 .in
 515 .PP
 516 The listening application in this case would receive
 517 .BR FAN_OPEN_EXEC
 518 events for both the ELF binary and interpreter, respectively:
 519 .PP
 520 .in +4n
 521 .EX
 522 /bin/echo
 523 /lib64/ld-linux-x86-64.so.2
 524 .EE
 525 .in
 526 .SH BUGS
 527 The following bugs were present in Linux kernels before version 3.16:
 528 .IP * 3
 529 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
 530 If
 531 .I flags
 532 contains
 533 .BR FAN_MARK_FLUSH ,
 534 .I dirfd
 535 and
 536 .I pathname
 537 must specify a valid filesystem object, even though this object is not used.
 538 .IP *
 539 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
 540 .BR readdir (2)
 541 does not generate a
 542 .B FAN_ACCESS
 543 event.
 544 .IP *
 545 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
 546 If
 547 .BR fanotify_mark ()
 548 is called with
 549 .BR FAN_MARK_FLUSH ,
 550 .I flags
 551 is not checked for invalid values.
 552 .SH SEE ALSO
 553 .BR fanotify_init (2),
 554 .BR fanotify (7)