fanotify.7: Clarify details of buffer size for read() and 'event_len' field

* Using large buffer sizes for read(2) is orthogonal to the
  discussion of variable-length event structures.
* Move the discussion of the read() return value to follow
  discussion of what the read() actually returns in its buffer.
* Related rewordings.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man7/fanotify.7

@@ -137,9 +137,6 @@ until either a file event occurs or the call is interrupted by a signal
 (see
 .BR signal (7)).
 
-The return value of
-.BR read (2)
-is the length of the filled buffer, or \-1 in case of an error.
 After a successful
 .BR read (2),
 the read buffer contains one or more of the following structures:
@@ -158,6 +155,16 @@ struct fanotify_event_metadata {
 .fi
 .in
 .PP
+For performance reasons, it is recommended to use a large
+buffer size (for example, 4096 bytes),
+so that multiple events can be retrieved by a single
+.BR read (2).
+
+The return value of
+.BR read (2)
+is the number of bytes placed in the buffer,
+or \-1 in case of an error.
+
 The fields of the
 .I fanotify_event_metadata
 structure are as follows:
@@ -169,10 +176,8 @@ In the current implementation, the value of
 .I event_len
 is always
 .BR FAN_EVENT_METADATA_LEN .
-In principle,
-the API design would allow to return variable-length structures.
-Therefore, and for performance reasons, it is recommended to use a larger
-buffer size when reading, for example 4096 bytes.
+However, the API is designed to allow
+variable-length structures to be returned in the future.
 .TP
 .I vers
 This field holds a version number for the structure.