fanotify.7: BUGS, error handling in fanotify_read

The patch in
http://www.spinics.net/lists/linux-man/msg05589.html
was not accepted.

Michael Kerrisk suggested in a private mail to add a comment in the BUGS section.

Signed-off-by Heinrich Schuchardt <[email protected]>

---
 man7/fanotify.7 | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

man7/fanotify.7 +12 -3

index 2a92908..c6cec7c 100644
@@ -164,7 +164,7 @@ so that multiple events can be retrieved by a single
 The return value of
 .BR read (2)
 is the number of bytes placed in the buffer,
-or \-1 in case of an error.
+or \-1 in case of an error (but see BUGS).
 
 The fields of the
 .I fanotify_event_metadata

@@ -468,7 +468,7 @@ The event queue can overflow.
 In this case, events are lost.
 .SH BUGS
 As of Linux 3.15,
-the following bug exists:
+the following bugs exists:
 .IP * 3
 .\" FIXME: A patch was proposed.
 When an event is generated,

@@ -478,6 +478,16 @@ before passing a file descriptor for that file.
 This poses a security risk, when the
 .B CAP_SYS_ADMIN
 capability is set for programs executed by unprivileged users.
+.IP *
+If a call to
+.BR read( 2 )
+processes multiple events from the fanotify queue and an error occurs, the
+return value will be the cumulated length of the events successfully copied to
+the user space buffer before the error occured.
+The return value will not be \-1.
+.I errno
+will not be set.
+Thus, the user program has no way to detect the error.
 .SH EXAMPLE
 The following program demonstrates the usage of the fanotify API.
 It marks the mount point passed as a command-line argument
--

2.0.0.rc0

Do you have any comments/additions for this man-pages patch?

Quoted 54 lines

The patch in
http://www.spinics.net/lists/linux-man/msg05589.html
was not accepted.

Michael Kerrisk suggested in a private mail to add a comment in the BUGS section.

Signed-off-by Heinrich Schuchardt <[email protected]>

---
 man7/fanotify.7 | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

man7/fanotify.7 +12 -3

index 2a92908..c6cec7c 100644
@@ -164,7 +164,7 @@ so that multiple events can be retrieved by a single
 The return value of
 .BR read (2)
 is the number of bytes placed in the buffer,
-or \-1 in case of an error.
+or \-1 in case of an error (but see BUGS).
 
 The fields of the
 .I fanotify_event_metadata

@@ -468,7 +468,7 @@ The event queue can overflow.
 In this case, events are lost.
 .SH BUGS
 As of Linux 3.15,
-the following bug exists:
+the following bugs exists:
 .IP * 3
 .\" FIXME: A patch was proposed.
 When an event is generated,

@@ -478,6 +478,16 @@ before passing a file descriptor for that file.
 This poses a security risk, when the
 .B CAP_SYS_ADMIN
 capability is set for programs executed by unprivileged users.
+.IP *
+If a call to
+.BR read( 2 )
+processes multiple events from the fanotify queue and an error occurs, the
+return value will be the cumulated length of the events successfully copied to
+the user space buffer before the error occured.
+The return value will not be \-1.
+.I errno
+will not be set.
+Thus, the user program has no way to detect the error.
 .SH EXAMPLE
 The following program demonstrates the usage of the fanotify API.
 It marks the mount point passed as a command-line argument
--

2.0.0.rc0

Signature · 3 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

The patch in
http://www.spinics.net/lists/linux-man/msg05589.html
was not accepted.

Michael Kerrisk suggested in a private mail to add a comment in the BUGS section.

Signed-off-by Heinrich Schuchardt <[email protected]>

---
 man7/fanotify.7 | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

man7/fanotify.7 +12 -2

index 2a92908..c6cec7c 100644
@@ -164,7 +164,7 @@ so that multiple events can be retrieved by a single
 The return value of
 .BR read (2)
 is the number of bytes placed in the buffer,
-or \-1 in case of an error.
+or \-1 in case of an error (but see BUGS).
 
 The fields of the
 .I fanotify_event_metadata

@@ -468,7 +468,7 @@ The event queue can overflow.
 In this case, events are lost.
 .SH BUGS
 As of Linux 3.15,
-the following bug exists:
+the following bugs exists:
 .IP * 3
 .\" FIXME: A patch was proposed.
 When an event is generated,

@@ -478,6 +478,16 @@ before passing a file descriptor for that file.
 This poses a security risk, when the
 .B CAP_SYS_ADMIN
 capability is set for programs executed by unprivileged users.
+.IP *
+If a call to
+.BR read( 2 )
+processes multiple events from the fanotify queue and an error occurs, the
+return value will be the cumulated length of the events successfully copied to
+the user space buffer before the error occured.
+The return value will not be \-1.
+.I errno
+will not be set.
+Thus, the user program has no way to detect the error.
 .SH EXAMPLE
 The following program demonstrates the usage of the fanotify API.
 It marks the mount point passed as a command-line argument