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