man2/fanotify_init.2

   1 .\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .TH fanotify_init 2 (date) "Linux man-pages (unreleased)"
   5 .SH NAME
   6 fanotify_init \- create and initialize fanotify group
   7 .SH LIBRARY
   8 Standard C library
   9 .RI ( libc ", " \-lc )
  10 .SH SYNOPSIS
  11 .nf
  12 .BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
  13 .B #include <sys/fanotify.h>
  14 .P
  15 .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
  16 .fi
  17 .SH DESCRIPTION
  18 For an overview of the fanotify API, see
  19 .BR fanotify (7).
  20 .P
  21 .BR fanotify_init ()
  22 initializes a new fanotify group and returns a file descriptor for the event
  23 queue associated with the group.
  24 .P
  25 The file descriptor is used in calls to
  26 .BR fanotify_mark (2)
  27 to specify the files, directories, mounts, or filesystems for which fanotify
  28 events shall be created.
  29 These events are received by reading from the file descriptor.
  30 Some events are only informative, indicating that a file has been accessed.
  31 Other events can be used to determine whether
  32 another application is permitted to access a file or directory.
  33 Permission to access filesystem objects is granted by writing to the file
  34 descriptor.
  35 .P
  36 Multiple programs may be using the fanotify interface at the same time to
  37 monitor the same files.
  38 .P
  39 The number of fanotify groups per user is limited.
  40 See
  41 .BR fanotify (7)
  42 for details about this limit.
  43 .P
  44 The
  45 .I flags
  46 argument contains a multi-bit field defining the notification class of the
  47 listening application and further single bit fields specifying the behavior
  48 of the file descriptor.
  49 .P
  50 If multiple listeners for permission events exist,
  51 the notification class is used to establish the sequence
  52 in which the listeners receive the events.
  53 .P
  54 Only one of the following notification classes may be specified in
  55 .IR flags :
  56 .TP
  57 .B FAN_CLASS_PRE_CONTENT
  58 This value allows the receipt of events notifying that a file has been
  59 accessed and events for permission decisions if a file may be accessed.
  60 It is intended for event listeners that need to access files before they
  61 contain their final data.
  62 This notification class might be used by hierarchical storage managers,
  63 for example.
  64 Use of this flag requires the
  65 .B CAP_SYS_ADMIN
  66 capability.
  67 .TP
  68 .B FAN_CLASS_CONTENT
  69 This value allows the receipt of events notifying that a file has been
  70 accessed and events for permission decisions if a file may be accessed.
  71 It is intended for event listeners that need to access files when they
  72 already contain their final content.
  73 This notification class might be used by malware detection programs, for
  74 example.
  75 Use of this flag requires the
  76 .B CAP_SYS_ADMIN
  77 capability.
  78 .TP
  79 .B FAN_CLASS_NOTIF
  80 This is the default value.
  81 It does not need to be specified.
  82 This value only allows the receipt of events notifying that a file has been
  83 accessed.
  84 Permission decisions before the file is accessed are not possible.
  85 .P
  86 Listeners with different notification classes will receive events in the
  87 order
  88 .BR FAN_CLASS_PRE_CONTENT ,
  89 .BR FAN_CLASS_CONTENT ,
  90 .BR FAN_CLASS_NOTIF .
  91 The order of notification for listeners in the same notification class
  92 is undefined.
  93 .P
  94 The following bits can additionally be set in
  95 .IR flags :
  96 .TP
  97 .B FAN_CLOEXEC
  98 Set the close-on-exec flag
  99 .RB ( FD_CLOEXEC )
 100 on the new file descriptor.
 101 See the description of the
 102 .B O_CLOEXEC
 103 flag in
 104 .BR open (2).
 105 .TP
 106 .B FAN_NONBLOCK
 107 Enable the nonblocking flag
 108 .RB ( O_NONBLOCK )
 109 for the file descriptor.
 110 Reading from the file descriptor will not block.
 111 Instead, if no data is available,
 112 .BR read (2)
 113 fails with the error
 114 .BR EAGAIN .
 115 .TP
 116 .B FAN_UNLIMITED_QUEUE
 117 Remove the limit on the number of events in the event queue.
 118 See
 119 .BR fanotify (7)
 120 for details about this limit.
 121 Use of this flag requires the
 122 .B CAP_SYS_ADMIN
 123 capability.
 124 .TP
 125 .B FAN_UNLIMITED_MARKS
 126 Remove the limit on the number of fanotify marks per user.
 127 See
 128 .BR fanotify (7)
 129 for details about this limit.
 130 Use of this flag requires the
 131 .B CAP_SYS_ADMIN
 132 capability.
 133 .TP
 134 .BR FAN_REPORT_TID " (since Linux 4.20)"
 135 .\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29
 136 Report thread ID (TID) instead of process ID (PID)
 137 in the
 138 .I pid
 139 field of the
 140 .I "struct fanotify_event_metadata"
 141 supplied to
 142 .BR read (2)
 143 (see
 144 .BR fanotify (7)).
 145 Use of this flag requires the
 146 .B CAP_SYS_ADMIN
 147 capability.
 148 .TP
 149 .BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
 150 .\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
 151 Enable generation of audit log records about access mediation performed by
 152 permission events.
 153 The permission event response has to be marked with the
 154 .B FAN_AUDIT
 155 flag for an audit log record to be generated.
 156 Use of this flag requires the
 157 .B CAP_AUDIT_WRITE
 158 capability.
 159 .TP
 160 .BR FAN_REPORT_FID " (since Linux 5.1)"
 161 .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
 162 This value allows the receipt of events which contain additional information
 163 about the underlying filesystem object correlated to an event.
 164 An additional record of type
 165 .B FAN_EVENT_INFO_TYPE_FID
 166 encapsulates the information about the object and is included alongside the
 167 generic event metadata structure.
 168 The file descriptor that is used to represent the object correlated to an
 169 event is instead substituted with a file handle.
 170 It is intended for applications that may find the use of a file handle to
 171 identify an object more suitable than a file descriptor.
 172 Additionally, it may be used for applications monitoring a directory or a
 173 filesystem that are interested in the directory entry modification events
 174 .BR FAN_CREATE ,
 175 .BR FAN_DELETE ,
 176 .BR FAN_MOVE ,
 177 and
 178 .BR FAN_RENAME ,
 179 or in events such as
 180 .BR FAN_ATTRIB ,
 181 .BR FAN_DELETE_SELF ,
 182 and
 183 .BR FAN_MOVE_SELF .
 184 All the events above require an fanotify group that identifies filesystem
 185 objects by file handles.
 186 Note that without the flag
 187 .BR FAN_REPORT_TARGET_FID ,
 188 for the directory entry modification events,
 189 there is an information record that identifies the modified directory
 190 and not the created/deleted/moved child object.
 191 The use of
 192 .B FAN_CLASS_CONTENT
 193 or
 194 .B FAN_CLASS_PRE_CONTENT
 195 is not permitted with this flag and will result in the error
 196 .BR EINVAL .
 197 See
 198 .BR fanotify (7)
 199 for additional details.
 200 .TP
 201 .BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
 202 .\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f
 203 Events for fanotify groups initialized with this flag will contain
 204 (see exceptions below) additional information about a directory object
 205 correlated to an event.
 206 An additional record of type
 207 .B FAN_EVENT_INFO_TYPE_DFID
 208 encapsulates the information about the directory object and is included
 209 alongside the generic event metadata structure.
 210 For events that occur on a non-directory object, the additional structure
 211 includes a file handle that identifies the parent directory filesystem object.
 212 Note that there is no guarantee that the directory filesystem object will be
 213 found at the location described by the file handle information at the time
 214 the event is received.
 215 When combined with the flag
 216 .BR FAN_REPORT_FID ,
 217 two records may be reported with events that occur on a non-directory object,
 218 one to identify the non-directory object itself and one to identify the parent
 219 directory object.
 220 Note that in some cases, a filesystem object does not have a parent,
 221 for example, when an event occurs on an unlinked but open file.
 222 In that case, with the
 223 .B FAN_REPORT_FID
 224 flag, the event will be reported with only one record to identify the
 225 non-directory object itself, because there is no directory associated with
 226 the event.
 227 Without the
 228 .B FAN_REPORT_FID
 229 flag, no event will be reported.
 230 See
 231 .BR fanotify (7)
 232 for additional details.
 233 .TP
 234 .BR FAN_REPORT_NAME " (since Linux 5.9)"
 235 .\" commit 929943b38daf817f2e6d303ea04401651fc3bc05
 236 Events for fanotify groups initialized with this flag will contain additional
 237 information about the name of the directory entry correlated to an event.
 238 This flag must be provided in conjunction with the flag
 239 .BR FAN_REPORT_DIR_FID .
 240 Providing this flag value without
 241 .B FAN_REPORT_DIR_FID
 242 will result in the error
 243 .BR EINVAL .
 244 This flag may be combined with the flag
 245 .BR FAN_REPORT_FID .
 246 An additional record of type
 247 .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
 248 which encapsulates the information about the directory entry, is included
 249 alongside the generic event metadata structure and substitutes the additional
 250 information record of type
 251 .BR FAN_EVENT_INFO_TYPE_DFID .
 252 The additional record includes a file handle that identifies a directory
 253 filesystem object followed by a name that identifies an entry in that
 254 directory.
 255 For the directory entry modification events
 256 .BR FAN_CREATE ,
 257 .BR FAN_DELETE ,
 258 and
 259 .BR FAN_MOVE ,
 260 the reported name is that of the created/deleted/moved directory entry.
 261 The event
 262 .B FAN_RENAME
 263 may contain two information records.
 264 One of type
 265 .B FAN_EVENT_INFO_TYPE_OLD_DFID_NAME
 266 identifying the old directory entry,
 267 and another of type
 268 .B FAN_EVENT_INFO_TYPE_NEW_DFID_NAME
 269 identifying the new directory entry.
 270 For other events that occur on a directory object, the reported file handle
 271 is that of the directory object itself and the reported name is '.'.
 272 For other events that occur on a non-directory object, the reported file handle
 273 is that of the parent directory object and the reported name is the name of a
 274 directory entry where the object was located at the time of the event.
 275 The rationale behind this logic is that the reported directory file handle can
 276 be passed to
 277 .BR open_by_handle_at (2)
 278 to get an open directory file descriptor and that file descriptor along with
 279 the reported name can be used to call
 280 .BR fstatat (2).
 281 The same rule that applies to record type
 282 .B FAN_EVENT_INFO_TYPE_DFID
 283 also applies to record type
 284 .BR FAN_EVENT_INFO_TYPE_DFID_NAME :
 285 if a non-directory object has no parent, either the event will not be reported
 286 or it will be reported without the directory entry information.
 287 Note that there is no guarantee that the filesystem object will be found at the
 288 location described by the directory entry information at the time the event is
 289 received.
 290 See
 291 .BR fanotify (7)
 292 for additional details.
 293 .TP
 294 .B FAN_REPORT_DFID_NAME
 295 This is a synonym for
 296 .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
 297 .TP
 298 .BR FAN_REPORT_TARGET_FID " (since Linux 5.17)"
 299 .\" commit d61fd650e9d206a71fda789f02a1ced4b19944c4
 300 Events for fanotify groups initialized with this flag
 301 will contain additional information about the child
 302 correlated with directory entry modification events.
 303 This flag must be provided in conjunction with the flags
 304 .BR FAN_REPORT_FID ,
 305 .B FAN_REPORT_DIR_FID
 306 and
 307 .BR FAN_REPORT_NAME .
 308 or else the error
 309 .B EINVAL
 310 will be returned.
 311 For the directory entry modification events
 312 .BR FAN_CREATE ,
 313 .BR FAN_DELETE ,
 314 .BR FAN_MOVE ,
 315 and
 316 .BR FAN_RENAME ,
 317 an additional record of type
 318 .BR FAN_EVENT_INFO_TYPE_FID ,
 319 is reported in addition to the information records of type
 320 .BR FAN_EVENT_INFO_TYPE_DFID ,
 321 .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
 322 .BR FAN_EVENT_INFO_TYPE_OLD_DFID_NAME ,
 323 and
 324 .BR FAN_EVENT_INFO_TYPE_NEW_DFID_NAME .
 325 The additional record includes a file handle
 326 that identifies the filesystem child object
 327 that the directory entry is referring to.
 328 .TP
 329 .B FAN_REPORT_DFID_NAME_TARGET
 330 This is a synonym for
 331 .RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
 332 .TP
 333 .BR FAN_REPORT_PIDFD " (since Linux 5.15)"
 334 .\" commit af579beb666aefb17e9a335c12c788c92932baf1
 335 Events for fanotify groups initialized with this flag will contain
 336 an additional information record alongside the generic
 337 .I fanotify_event_metadata
 338 structure.
 339 This information record will be of type
 340 .B FAN_EVENT_INFO_TYPE_PIDFD
 341 and will contain a pidfd for the process that
 342 was responsible for generating an event.
 343 A pidfd returned in this information record object is
 344 no different to the pidfd that is returned when calling
 345 .BR pidfd_open (2).
 346 Usage of this information record are for applications that
 347 may be interested in reliably determining whether
 348 the process responsible for generating an event
 349 has been recycled or terminated.
 350 The use of the
 351 .B FAN_REPORT_TID
 352 flag along with
 353 .B FAN_REPORT_PIDFD
 354 is currently not supported and
 355 attempting to do so will result in the error
 356 .B EINVAL
 357 being returned.
 358 This limitation is currently imposed by the pidfd API
 359 as it currently only supports
 360 the creation of pidfds for thread-group leaders.
 361 Creating pidfds for non-thread-group leaders
 362 may be supported at some point in the future,
 363 so this restriction may eventually be lifted.
 364 For more details on information records,
 365 see
 366 .BR fanotify (7).
 367 .P
 368 The
 369 .I event_f_flags
 370 argument
 371 defines the file status flags that will be set on the open file descriptions
 372 that are created for fanotify events.
 373 For details of these flags, see the description of the
 374 .I flags
 375 values in
 376 .BR open (2).
 377 .I event_f_flags
 378 includes a multi-bit field for the access mode.
 379 This field can take the following values:
 380 .TP
 381 .B O_RDONLY
 382 This value allows only read access.
 383 .TP
 384 .B O_WRONLY
 385 This value allows only write access.
 386 .TP
 387 .B O_RDWR
 388 This value allows read and write access.
 389 .P
 390 Additional bits can be set in
 391 .IR event_f_flags .
 392 The most useful values are:
 393 .TP
 394 .B O_LARGEFILE
 395 Enable support for files exceeding 2\ GB.
 396 Failing to set this flag will result in an
 397 .B EOVERFLOW
 398 error when trying to open a large file which is monitored by
 399 an fanotify group on a 32-bit system.
 400 .TP
 401 .BR O_CLOEXEC " (since Linux 3.18)"
 402 .\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
 403 Enable the close-on-exec flag for the file descriptor.
 404 See the description of the
 405 .B O_CLOEXEC
 406 flag in
 407 .BR open (2)
 408 for reasons why this may be useful.
 409 .P
 410 The following are also allowable:
 411 .BR O_APPEND ,
 412 .BR O_DSYNC ,
 413 .BR O_NOATIME ,
 414 .BR O_NONBLOCK ,
 415 and
 416 .BR O_SYNC .
 417 Specifying any other flag in
 418 .I event_f_flags
 419 yields the error
 420 .B EINVAL
 421 (but see BUGS).
 422 .SH RETURN VALUE
 423 On success,
 424 .BR fanotify_init ()
 425 returns a new file descriptor.
 426 On error, \-1 is returned, and
 427 .I errno
 428 is set to indicate the error.
 429 .SH ERRORS
 430 .TP
 431 .B EINVAL
 432 An invalid value was passed in
 433 .I flags
 434 or
 435 .IR event_f_flags .
 436 .B FAN_ALL_INIT_FLAGS
 437 (deprecated since Linux 4.20)
 438 .\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4
 439 defines all allowable bits for
 440 .IR flags .
 441 .TP
 442 .B EMFILE
 443 The number of fanotify groups for this user exceeds the limit.
 444 See
 445 .BR fanotify (7)
 446 for details about this limit.
 447 .TP
 448 .B EMFILE
 449 The per-process limit on the number of open file descriptors has been reached.
 450 .TP
 451 .B ENOMEM
 452 The allocation of memory for the notification group failed.
 453 .TP
 454 .B ENOSYS
 455 This kernel does not implement
 456 .BR fanotify_init ().
 457 The fanotify API is available only if the kernel was configured with
 458 .BR CONFIG_FANOTIFY .
 459 .TP
 460 .B EPERM
 461 The operation is not permitted because the caller lacks a required capability.
 462 .SH VERSIONS
 463 Prior to Linux 5.13,
 464 .\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7
 465 calling
 466 .BR fanotify_init ()
 467 required the
 468 .B CAP_SYS_ADMIN
 469 capability.
 470 Since Linux 5.13,
 471 .\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7
 472 users may call
 473 .BR fanotify_init ()
 474 without the
 475 .B CAP_SYS_ADMIN
 476 capability to create and initialize
 477 an fanotify group with limited functionality.
 478 .TP
 479 The limitations imposed on an event listener created by a user without the
 480 .B CAP_SYS_ADMIN
 481 capability are as follows:
 482 .RS
 483 .IP \[bu] 3
 484 The user cannot request for an unlimited event queue by using
 485 .BR FAN_UNLIMITED_QUEUE .
 486 .IP \[bu]
 487 The user cannot request for an unlimited number of marks by using
 488 .BR FAN_UNLIMITED_MARKS .
 489 .IP \[bu]
 490 The user cannot request to use either notification classes
 491 .B FAN_CLASS_CONTENT
 492 or
 493 .BR FAN_CLASS_PRE_CONTENT .
 494 This means that user cannot request permission events.
 495 .IP \[bu]
 496 The user is required to create a group that identifies filesystem objects by
 497 file handles, for example, by providing the
 498 .B FAN_REPORT_FID
 499 flag.
 500 .IP \[bu]
 501 The user is limited to only mark inodes.
 502 The ability to mark a mount or filesystem via
 503 .BR fanotify_mark ()
 504 through the use of
 505 .B FAN_MARK_MOUNT
 506 or
 507 .B FAN_MARK_FILESYSTEM
 508 is not permitted.
 509 .IP \[bu]
 510 The event object in the event queue is limited in terms of the information
 511 that is made available to the unprivileged user.
 512 A user will also not receive the pid that generated the event, unless the
 513 listening process itself generated the event.
 514 .RE
 515 .SH STANDARDS
 516 Linux.
 517 .SH HISTORY
 518 Linux 2.6.37.
 519 .\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37.
 520 .SH BUGS
 521 The following bug was present before Linux 3.18:
 522 .IP \[bu] 3
 523 .\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
 524 The
 525 .B O_CLOEXEC
 526 is ignored when passed in
 527 .IR event_f_flags .
 528 .P
 529 The following bug was present before Linux 3.14:
 530 .IP \[bu] 3
 531 .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580
 532 The
 533 .I event_f_flags
 534 argument is not checked for invalid flags.
 535 Flags that are intended only for internal use,
 536 such as
 537 .BR FMODE_EXEC ,
 538 can be set, and will consequently be set for the file descriptors
 539 returned when reading from the fanotify file descriptor.
 540 .SH SEE ALSO
 541 .BR fanotify_mark (2),
 542 .BR fanotify (7)