copy_file_range.2: tfix

[thirdparty/man-pages.git] / man2 / fanotify_init.2

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 8539325191129d9a46aa3ac8dd35bf59e19b6f40..0131575ab7a0df3e3a8f87e1a9a1dc906ef7aa54 100644 (file)
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -21,14 +21,14 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
-.TH FANOTIFY_INIT 2 2014-05-18 "Linux" "Linux Programmer's Manual"
+.TH FANOTIFY_INIT 2 2019-08-02 "Linux" "Linux Programmer's Manual"
 .SH NAME
 fanotify_init \- create and initialize fanotify group
 .SH SYNOPSIS
 .B #include <fcntl.h>
 .br
 .B #include <sys/fanotify.h>
-.sp
+.PP
 .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
 .SH DESCRIPTION
 For an overview of the fanotify API, see
@@ -40,8 +40,8 @@ queue associated with the group.
 .PP
 The file descriptor is used in calls to
 .BR fanotify_mark (2)
-to specify the files, directories, and mounts for which fanotify events
-shall be created.
+to specify the files, directories, mounts or filesystems for which fanotify
+events shall be created.
 These events are received by reading from the file descriptor.
 Some events are only informative, indicating that a file has been accessed.
 Other events can be used to determine whether
@@ -94,6 +94,36 @@ already contain their final content.
 This notification class might be used by malware detection programs, for
 example.
 .TP
+.BR FAN_REPORT_FID " (since Linux 5.1)"
+.\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
+This value allows the receipt of events which contain additional information
+about the underlying filesystem object correlated to an event.
+An additional structure encapsulates the information about the object and is
+included alongside the generic event metadata structure.
+The file descriptor that is used to represent the object correlated to an
+event is instead substituted with a file handle.
+It is intended for applications that may find the use of a file handle to
+identify an object more suitable than a file descriptor.
+Additionally, it may be used for applications that are interested in
+directory entry events, such as
+.BR FAN_CREATE ,
+.BR FAN_ATTRIB ,
+.BR FAN_MOVE ,
+and
+.BR FAN_DELETE
+for example.
+Note that the use of directory modification events are not supported when
+monitoring a mount point.
+The use of
+.BR FAN_CLASS_CONTENT
+or
+.BR FAN_CLASS_PRE_CONTENT
+is not permitted with this flag and will result in the error
+.BR EINVAL .
+See
+.BR fanotify (7)
+for additional information.
+.TP
 .B FAN_CLASS_NOTIF
 This is the default value.
 It does not need to be specified.
@@ -128,7 +158,7 @@ for the file descriptor.
 Reading from the file descriptor will not block.
 Instead, if no data is available,
 .BR read (2)
-will fail with the error
+fails with the error
 .BR EAGAIN .
 .TP
 .B FAN_UNLIMITED_QUEUE
@@ -142,6 +172,18 @@ Remove the limit of 8192 marks.
 Use of this flag requires the
 .B CAP_SYS_ADMIN
 capability.
+.TP
+.BR FAN_REPORT_TID " (since Linux 4.20)"
+.\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29
+Report thread ID (TID) instead of process ID (PID)
+in the
+.I pid
+field of the
+.I "struct fanotify_event_metadata"
+supplied to
+.BR read (2)
+(see
+.BR fanotify (7)).
 .PP
 The
 .I event_f_flags
@@ -170,13 +212,14 @@ Additional bits can be set in
 The most useful values are:
 .TP
 .B O_LARGEFILE
-Enable support for files exceeding 2 GB.
+Enable support for files exceeding 2\ GB.
 Failing to set this flag will result in an
 .B EOVERFLOW
 error when trying to open a large file which is monitored by
 an fanotify group on a 32-bit system.
 .TP
-.B O_CLOEXEC
+.BR O_CLOEXEC " (since Linux 3.18)"
+.\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
 Enable the close-on-exec flag for the file descriptor.
 See the description of the
 .B O_CLOEXEC
@@ -211,12 +254,17 @@ An invalid value was passed in
 or
 .IR event_f_flags .
 .B FAN_ALL_INIT_FLAGS
+(deprecated since Linux kernel version 4.20)
+.\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4
 defines all allowable bits for
 .IR flags .
 .TP
 .B EMFILE
 The number of fanotify groups for this user exceeds 128.
 .TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
 .B ENOMEM
 The allocation of memory for the notification group failed.
 .TP
@@ -234,13 +282,20 @@ capability.
 .BR fanotify_init ()
 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 2.6.37.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
 This system call is Linux-specific.
 .SH BUGS
-As of Linux 3.15,
-the following bug exists:
+The following bug was present in Linux kernels before version 3.18:
+.IP * 3
+.\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4
+The
+.B O_CLOEXEC
+is ignored when passed in
+.IR event_f_flags .
+.PP
+The following bug was present in Linux kernels before version 3.14:
 .IP * 3
-.\" FIXME . Patch accepted to mm tree.
+.\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580
 The
 .I event_f_flags
 argument is not checked for invalid flags.
@@ -249,6 +304,6 @@ such as
 .BR FMODE_EXEC ,
 can be set, and will consequently be set for the file descriptors
 returned when reading from the fanotify file descriptor.
-.SH "SEE ALSO"
+.SH SEE ALSO
 .BR fanotify_mark (2),
 .BR fanotify (7)