man2/fanotify_init.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_INIT 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 fanotify_init \- create and initialize fanotify group
  27 .SH SYNOPSIS
  28 .nf
  29 .BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
  30 .B #include <sys/fanotify.h>
  31 .PP
  32 .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
  33 .fi
  34 .SH DESCRIPTION
  35 For an overview of the fanotify API, see
  36 .BR fanotify (7).
  37 .PP
  38 .BR fanotify_init ()
  39 initializes a new fanotify group and returns a file descriptor for the event
  40 queue associated with the group.
  41 .PP
  42 The file descriptor is used in calls to
  43 .BR fanotify_mark (2)
  44 to specify the files, directories, mounts, or filesystems for which fanotify
  45 events shall be created.
  46 These events are received by reading from the file descriptor.
  47 Some events are only informative, indicating that a file has been accessed.
  48 Other events can be used to determine whether
  49 another application is permitted to access a file or directory.
  50 Permission to access filesystem objects is granted by writing to the file
  51 descriptor.
  52 .PP
  53 Multiple programs may be using the fanotify interface at the same time to
  54 monitor the same files.
  55 .PP
  56 In the current implementation, the number of fanotify groups per user is
  57 limited to 128.
  58 This limit cannot be overridden.
  59 .PP
  60 Calling
  61 .BR fanotify_init ()
  62 requires the
  63 .B CAP_SYS_ADMIN
  64 capability.
  65 This constraint might be relaxed in future versions of the API.
  66 Therefore, certain additional capability checks have been implemented as
  67 indicated below.
  68 .PP
  69 The
  70 .I flags
  71 argument contains a multi-bit field defining the notification class of the
  72 listening application and further single bit fields specifying the behavior
  73 of the file descriptor.
  74 .PP
  75 If multiple listeners for permission events exist,
  76 the notification class is used to establish the sequence
  77 in which the listeners receive the events.
  78 .PP
  79 Only one of the following notification classes may be specified in
  80 .IR flags :
  81 .TP
  82 .B FAN_CLASS_PRE_CONTENT
  83 This value allows the receipt of events notifying that a file has been
  84 accessed and events for permission decisions if a file may be accessed.
  85 It is intended for event listeners that need to access files before they
  86 contain their final data.
  87 This notification class might be used by hierarchical storage managers,
  88 for example.
  89 .TP
  90 .B FAN_CLASS_CONTENT
  91 This value allows the receipt of events notifying that a file has been
  92 accessed and events for permission decisions if a file may be accessed.
  93 It is intended for event listeners that need to access files when they
  94 already contain their final content.
  95 This notification class might be used by malware detection programs, for
  96 example.
  97 .TP
  98 .B FAN_CLASS_NOTIF
  99 This is the default value.
 100 It does not need to be specified.
 101 This value only allows the receipt of events notifying that a file has been
 102 accessed.
 103 Permission decisions before the file is accessed are not possible.
 104 .PP
 105 Listeners with different notification classes will receive events in the
 106 order
 107 .BR FAN_CLASS_PRE_CONTENT ,
 108 .BR FAN_CLASS_CONTENT ,
 109 .BR FAN_CLASS_NOTIF .
 110 The order of notification for listeners in the same notification class
 111 is undefined.
 112 .PP
 113 The following bits can additionally be set in
 114 .IR flags :
 115 .TP
 116 .B FAN_CLOEXEC
 117 Set the close-on-exec flag
 118 .RB ( FD_CLOEXEC )
 119 on the new file descriptor.
 120 See the description of the
 121 .B O_CLOEXEC
 122 flag in
 123 .BR open (2).
 124 .TP
 125 .B FAN_NONBLOCK
 126 Enable the nonblocking flag
 127 .RB ( O_NONBLOCK )
 128 for the file descriptor.
 129 Reading from the file descriptor will not block.
 130 Instead, if no data is available,
 131 .BR read (2)
 132 fails with the error
 133 .BR EAGAIN .
 134 .TP
 135 .B FAN_UNLIMITED_QUEUE
 136 Remove the limit of 16384 events for the event queue.
 137 Use of this flag requires the
 138 .B CAP_SYS_ADMIN
 139 capability.
 140 .TP
 141 .B FAN_UNLIMITED_MARKS
 142 Remove the limit of 8192 marks.
 143 Use of this flag requires the
 144 .B CAP_SYS_ADMIN
 145 capability.
 146 .TP
 147 .BR FAN_REPORT_TID " (since Linux 4.20)"
 148 .\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29
 149 Report thread ID (TID) instead of process ID (PID)
 150 in the
 151 .I pid
 152 field of the
 153 .I "struct fanotify_event_metadata"
 154 supplied to
 155 .BR read (2)
 156 (see
 157 .BR fanotify (7)).
 158 .TP
 159 .BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
 160 .\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
 161 Enable generation of audit log records about access mediation performed by
 162 permission events.
 163 The permission event response has to be marked with the
 164 .B FAN_AUDIT
 165 flag for an audit log record to be generated.
 166 .TP
 167 .BR FAN_REPORT_FID " (since Linux 5.1)"
 168 .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
 169 This value allows the receipt of events which contain additional information
 170 about the underlying filesystem object correlated to an event.
 171 An additional record of type
 172 .BR FAN_EVENT_INFO_TYPE_FID
 173 encapsulates the information about the object and is included alongside the
 174 generic event metadata structure.
 175 The file descriptor that is used to represent the object correlated to an
 176 event is instead substituted with a file handle.
 177 It is intended for applications that may find the use of a file handle to
 178 identify an object more suitable than a file descriptor.
 179 Additionally, it may be used for applications monitoring a directory or a
 180 filesystem that are interested in the directory entry modification events
 181 .BR FAN_CREATE ,
 182 .BR FAN_DELETE ,
 183 and
 184 .BR FAN_MOVE ,
 185 or in events such as
 186 .BR FAN_ATTRIB ,
 187 .BR FAN_DELETE_SELF ,
 188 and
 189 .BR FAN_MOVE_SELF .
 190 All the events above require an fanotify group that identifies filesystem
 191 objects by file handles.
 192 Note that for the directory entry modification events the reported file handle
 193 identifies the modified directory and not the created/deleted/moved child
 194 object.
 195 The use of
 196 .BR FAN_CLASS_CONTENT
 197 or
 198 .BR FAN_CLASS_PRE_CONTENT
 199 is not permitted with this flag and will result in the error
 200 .BR EINVAL .
 201 See
 202 .BR fanotify (7)
 203 for additional details.
 204 .TP
 205 .BR FAN_REPORT_DIR_FID " (since Linux 5.9)"
 206 Events for fanotify groups initialized with this flag will contain
 207 (see exceptions below) additional information about a directory object
 208 correlated to an event.
 209 An additional record of type
 210 .BR FAN_EVENT_INFO_TYPE_DFID
 211 encapsulates the information about the directory object and is included
 212 alongside the generic event metadata structure.
 213 For events that occur on a non-directory object, the additional structure
 214 includes a file handle that identifies the parent directory filesystem object.
 215 Note that there is no guarantee that the directory filesystem object will be
 216 found at the location described by the file handle information at the time
 217 the event is received.
 218 When combined with the flag
 219 .BR FAN_REPORT_FID ,
 220 two records may be reported with events that occur on a non-directory object,
 221 one to identify the non-directory object itself and one to identify the parent
 222 directory object.
 223 Note that in some cases, a filesystem object does not have a parent,
 224 for example, when an event occurs on an unlinked but open file.
 225 In that case, with the
 226 .BR FAN_REPORT_FID
 227 flag, the event will be reported with only one record to identify the
 228 non-directory object itself, because there is no directory associated with
 229 the event.
 230 Without the
 231 .BR FAN_REPORT_FID
 232 flag, no event will be reported.
 233 See
 234 .BR fanotify (7)
 235 for additional details.
 236 .TP
 237 .BR FAN_REPORT_NAME " (since Linux 5.9)"
 238 Events for fanotify groups initialized with this flag will contain additional
 239 information about the name of the directory entry correlated to an event.
 240 This flag must be provided in conjunction with the flag
 241 .BR FAN_REPORT_DIR_FID .
 242 Providing this flag value without
 243 .BR FAN_REPORT_DIR_FID
 244 will result in the error
 245 .BR EINVAL .
 246 This flag may be combined with the flag
 247 .BR FAN_REPORT_FID .
 248 An additional record of type
 249 .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
 250 which encapsulates the information about the directory entry, is included
 251 alongside the generic event metadata structure and substitutes the additional
 252 information record of type
 253 .BR FAN_EVENT_INFO_TYPE_DFID .
 254 The additional record includes a file handle that identifies a directory
 255 filesystem object followed by a name that identifies an entry in that
 256 directory.
 257 For the directory entry modification events
 258 .BR FAN_CREATE ,
 259 .BR FAN_DELETE ,
 260 and
 261 .BR FAN_MOVE ,
 262 the reported name is that of the created/deleted/moved directory entry.
 263 For other events that occur on a directory object, the reported file handle
 264 is that of the directory object itself and the reported name is '.'.
 265 For other events that occur on a non-directory object, the reported file handle
 266 is that of the parent directory object and the reported name is the name of a
 267 directory entry where the object was located at the time of the event.
 268 The rationale behind this logic is that the reported directory file handle can
 269 be passed to
 270 .BR open_by_handle_at (2)
 271 to get an open directory file descriptor and that file descriptor along with
 272 the reported name can be used to call
 273 .BR fstatat (2).
 274 The same rule that applies to record type
 275 .BR FAN_EVENT_INFO_TYPE_DFID
 276 also applies to record type
 277 .BR FAN_EVENT_INFO_TYPE_DFID_NAME :
 278 if a non-directory object has no parent, either the event will not be reported
 279 or it will be reported without the directory entry information.
 280 Note that there is no guarantee that the filesystem object will be found at the
 281 location described by the directory entry information at the time the event is
 282 received.
 283 See
 284 .BR fanotify (7)
 285 for additional details.
 286 .TP
 287 .B FAN_REPORT_DFID_NAME
 288 This is a synonym for
 289 .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ).
 290 .PP
 291 The
 292 .I event_f_flags
 293 argument
 294 defines the file status flags that will be set on the open file descriptions
 295 that are created for fanotify events.
 296 For details of these flags, see the description of the
 297 .I flags
 298 values in
 299 .BR open (2).
 300 .I event_f_flags
 301 includes a multi-bit field for the access mode.
 302 This field can take the following values:
 303 .TP
 304 .B O_RDONLY
 305 This value allows only read access.
 306 .TP
 307 .B O_WRONLY
 308 This value allows only write access.
 309 .TP
 310 .B O_RDWR
 311 This value allows read and write access.
 312 .PP
 313 Additional bits can be set in
 314 .IR event_f_flags .
 315 The most useful values are:
 316 .TP
 317 .B O_LARGEFILE
 318 Enable support for files exceeding 2\ GB.
 319 Failing to set this flag will result in an
 320 .B EOVERFLOW
 321 error when trying to open a large file which is monitored by
 322 an fanotify group on a 32-bit system.
 323 .TP
 324 .BR O_CLOEXEC " (since Linux 3.18)"
 325 .\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
 326 Enable the close-on-exec flag for the file descriptor.
 327 See the description of the
 328 .B O_CLOEXEC
 329 flag in
 330 .BR open (2)
 331 for reasons why this may be useful.
 332 .PP
 333 The following are also allowable:
 334 .BR O_APPEND ,
 335 .BR O_DSYNC ,
 336 .BR O_NOATIME ,
 337 .BR O_NONBLOCK ,
 338 and
 339 .BR O_SYNC .
 340 Specifying any other flag in
 341 .I event_f_flags
 342 yields the error
 343 .B EINVAL
 344 (but see BUGS).
 345 .SH RETURN VALUE
 346 On success,
 347 .BR fanotify_init ()
 348 returns a new file descriptor.
 349 On error, \-1 is returned, and
 350 .I errno
 351 is set to indicate the error.
 352 .SH ERRORS
 353 .TP
 354 .B EINVAL
 355 An invalid value was passed in
 356 .I flags
 357 or
 358 .IR event_f_flags .
 359 .B FAN_ALL_INIT_FLAGS
 360 (deprecated since Linux kernel version 4.20)
 361 .\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4
 362 defines all allowable bits for
 363 .IR flags .
 364 .TP
 365 .B EMFILE
 366 The number of fanotify groups for this user exceeds 128.
 367 .TP
 368 .B EMFILE
 369 The per-process limit on the number of open file descriptors has been reached.
 370 .TP
 371 .B ENOMEM
 372 The allocation of memory for the notification group failed.
 373 .TP
 374 .B ENOSYS
 375 This kernel does not implement
 376 .BR fanotify_init ().
 377 The fanotify API is available only if the kernel was configured with
 378 .BR CONFIG_FANOTIFY .
 379 .TP
 380 .B EPERM
 381 The operation is not permitted because the caller lacks the
 382 .B CAP_SYS_ADMIN
 383 capability.
 384 .SH VERSIONS
 385 .BR fanotify_init ()
 386 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 387 2.6.37.
 388 .SH CONFORMING TO
 389 This system call is Linux-specific.
 390 .SH BUGS
 391 The following bug was present in Linux kernels before version 3.18:
 392 .IP * 3
 393 .\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
 394 The
 395 .B O_CLOEXEC
 396 is ignored when passed in
 397 .IR event_f_flags .
 398 .PP
 399 The following bug was present in Linux kernels before version 3.14:
 400 .IP * 3
 401 .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580
 402 The
 403 .I event_f_flags
 404 argument is not checked for invalid flags.
 405 Flags that are intended only for internal use,
 406 such as
 407 .BR FMODE_EXEC ,
 408 can be set, and will consequently be set for the file descriptors
 409 returned when reading from the fanotify file descriptor.
 410 .SH SEE ALSO
 411 .BR fanotify_mark (2),
 412 .BR fanotify (7)