[PATCH 0/3] fanotify man page updates for final v5.7

[PATCH 0/3] fanotify man page updates for final v5.7

[Amir Goldstein]

Hi Michael,

We made a last minute call to disable the FAN_DIR_MODIFY for v5.7.
Here is a man page update with some promissed cleanups.

Thanks,
Amir.

Amir Goldstein (3):
  Revert "fanotify.7, fanotify_mark.2: Document FAN_DIR_MODIFY"
  fanotify_init.2: move out of place entry FAN_REPORT_FID
  fanotify.7, fanotify_mark.2: Clarify FAN_ONDIR in output mask

 man2/fanotify_init.2 | 60 ++++++++++++++---------------
 man2/fanotify_mark.2 | 50 ++----------------------
 man7/fanotify.7      | 91 ++++++++++++++------------------------------
 3 files changed, 61 insertions(+), 140 deletions(-)

-- 
2.17.1

[PATCH 1/3] Revert "fanotify.7, fanotify_mark.2: Document FAN_DIR_MODIFY"

[Amir Goldstein]

This reverts commit a93e5c9593a95d09a1c9deb94dfdecbb970b8162.

FAN_DIR_MODIFY was disabled for v5.7 release by kernel commit
f17936993af0 ("fanotify: turn off support for FAN_DIR_MODIFY").

Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man2/fanotify_mark.2 | 33 --------------------
 man7/fanotify.7      | 73 ++++++--------------------------------------
 2 files changed, 10 insertions(+), 96 deletions(-)

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index bc8120fb2..f3ebb0208 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -244,38 +244,6 @@ An fanotify file descriptor created with
 .B FAN_REPORT_FID
 is required.
 .TP
-.BR FAN_DIR_MODIFY " (since Linux 5.7)"
-.\" commit 44d705b0370b1d581f46ff23e5d33e8b5ff8ec58
-Create an event when one of the entries in a marked directory has been created,
-deleted, or moved.
-This event will encapsulate additional information about the name of the
-modified directory entry.
-It is intended for applications that want to monitor the content of a large
-directory without having to reiterate the directory each time it is modified.
-The directory entry name will follow the directory file handle information in
-the reported event.
-See
-.BR fanotify (7)
-for additional details about the reported event format.
-The
-.BR FAN_DIR_MODIFY
-event will be generated in addition to the events
-.BR FAN_CREATE ,
-.BR FAN_DELETE ,
-.BR FAN_MOVED_FROM ,
-.BR FAN_MOVED_TO
-and will never be merged with the aforementioned events.
-An application receiving this event must not assume that the reported entry name
-exists in the marked directory at the time the event is received and should call
-.BR fstatat (2)
-with the entry name to learn about the current content of the directory entry.
-See
-.BR fanotify (7)
-for an example of its usage.
-An fanotify file descriptor created with
-.BR FAN_REPORT_FID
-is required.
-.TP
 .B FAN_OPEN_PERM
 Create an event when a permission to open a file or directory is requested.
 An fanotify file descriptor created with
@@ -341,7 +309,6 @@ The flag has no effect when marking mounts and filesystems.
 Note that events are not generated for children of the subdirectories
 of marked directories.
 More specifically, the directory entry modification events
-.BR FAN_DIR_MODIFY ,
 .BR FAN_CREATE ,
 .BR FAN_DELETE ,
 .BR FAN_MOVED_FROM ,
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index ac6fbbcae..3c49d67a9 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -324,9 +324,6 @@ A watched file or directory was moved.
 .B FAN_MODIFY
 A file was modified.
 .TP
-.B FAN_DIR_MODIFY
-A directory entry was created, deleted or moved.
-.TP
 .B FAN_CLOSE_WRITE
 A file that was opened for writing
 .RB ( O_WRONLY
@@ -398,11 +395,9 @@ For example, when an fanotify file descriptor is created using
 the
 .I info_type
 field of this header is set to
-.BR FAN_EVENT_INFO_TYPE_FID
-or
-.BR FAN_EVENT_INFO_TYPE_DFID_NAME .
-Event listeners can use this field to check what additional information
-is received for an event.
+.BR FAN_EVENT_INFO_TYPE_FID .
+Event listeners can use this field to check that the additional
+information received for an event is of the correct type.
 Additionally, the
 .I fanotify_event_info_header
 also contains a
@@ -448,14 +443,6 @@ and
 will carry the
 .IR file_handle
 information for the child object if the child object is being watched.
-For the event
-.BR FAN_DIR_MODIFY ,
-the
-.I info_type
-field of this header is set to
-.BR FAN_EVENT_INFO_TYPE_DFID_NAME .
-The file handle describes the modified directory and a null terminated
-name of the modified entry follows directly after the file handle buffer.
 .PP
 The following macros are provided to iterate over a buffer containing
 fanotify event metadata returned by a
@@ -640,11 +627,9 @@ events for the monitored directory itself.
 Fanotify monitoring of directories is not recursive:
 to monitor subdirectories under a directory,
 additional marks must be created.
-The
-.B FAN_DIR_MODIFY
-event can be used for detecting when a subdirectory has been created under
-a marked directory.
-An additional mark must then be set on the newly created subdirectory.
+(But note that the fanotify API provides no way of detecting when a
+subdirectory has been created under a marked directory,
+which makes recursive monitoring difficult.)
 Monitoring mounts offers the capability to monitor a whole directory tree.
 Monitoring filesystems offers the capability to monitor changes made from
 any mount of a filesystem instance.
@@ -938,8 +923,6 @@ The program marks the filesystem object that is passed as
 a command-line argument
 and waits until an event of type
 .B FAN_CREATE
-or
-.B FAN_DIR_MODIFY
 has occurred.
 The event mask indicates which type of filesystem object\(emeither
 a file or a directory\(emwas created.
@@ -956,9 +939,7 @@ This is followed by the creation of a regular file,
 This results in a
 .B FAN_CREATE
 event being generated and reported against the file's parent watched
-directory object and a
-.B FAN_DIR_MODIFY
-event being generated and reported with the created file name.
+directory object.
 Program execution ends once all events captured within the buffer have
 been processed.
 .PP
@@ -968,9 +949,6 @@ been processed.
 Listening for events.
 FAN_CREATE (file created):
         Directory /home/user has been modified.
-FAN_DIR_MODIFY (entry changed):
-        Directory /home/user has been modified.
-        Entry 'testfile.txt' is not a subdirectory.
 All events processed successfully. Program exiting.
 
 $ \fBtouch /home/user/testfile.txt\fP              # In another terminal
@@ -985,9 +963,7 @@ This specific action results in a
 .B FAN_CREATE
 event being generated and is reported with the
 .B FAN_ONDIR
-flag set and a
-.B FAN_DIR_MODIFY
-event being generated and reported with the created directory name.
+flag set.
 .PP
 .in +4n
 .EX
@@ -995,9 +971,6 @@ event being generated and reported with the created directory name.
 Listening for events.
 FAN_CREATE | FAN_ONDIR (subdirectory created):
         Directory /home/user has been modified.
-FAN_DIR_MODIFY (entry changed):
-        Directory /home/user has been modified.
-        Entry 'testdir' is a subdirectory.
 All events processed successfully. Program exiting.
 
 $ \fBmkdir \-p /home/user/testdir\fP          # In another terminal
@@ -1030,8 +1003,6 @@ main(int argc, char **argv)
     struct file_handle *file_handle;
     struct fanotify_event_metadata *metadata;
     struct fanotify_event_info_fid *fid;
-    const char *file_name;
-    struct stat sb;
 
     if (argc != 2) {
         fprintf(stderr, "Invalid number of command line arguments.\en");
@@ -1057,7 +1028,7 @@ main(int argc, char **argv)
     /* Place a mark on the filesystem object supplied in argv[1]. */
 
     ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
-                        FAN_DIR_MODIFY | FAN_CREATE | FAN_ONDIR,
+                        FAN_CREATE | FAN_ONDIR,
                         AT_FDCWD, argv[1]);
     if (ret == \-1) {
         perror("fanotify_mark");
@@ -1084,19 +1055,11 @@ main(int argc, char **argv)
 
         /* Ensure that the event info is of the correct type */
 
-        if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_FID) {
-            file_name = NULL;
-        } else if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
-            file_name = file_handle->f_handle +
-                        file_handle->handle_bytes;
-        } else {
+        if (fid\->hdr.info_type != FAN_EVENT_INFO_TYPE_FID) {
             fprintf(stderr, "Received unexpected event info type.\en");
             exit(EXIT_FAILURE);
         }
 
-        if (metadata\->mask == FAN_DIR_MODIFY)
-            printf("FAN_DIR_MODIFY (entry changed):\en");
-
         if (metadata\->mask == FAN_CREATE)
             printf("FAN_CREATE (file created):\en");
 
@@ -1138,22 +1101,6 @@ main(int argc, char **argv)
         path[path_len] = \(aq\e0\(aq;
         printf("\etDirectory \(aq%s\(aq has been modified.\en", path);
 
-        if (file_name) {
-            ret = fstatat(event_fd, file_name, &sb, 0);
-            if (ret == \-1) {
-                if (errno != ENOENT) {
-                    perror("fstatat");
-                    exit(EXIT_FAILURE);
-                }
-                printf("\etEntry %\(aqs\(aq does not exist.\en", file_name);
-            } else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
-                printf("\etEntry \(aq%s\(aq is a subdirectory.\en", file_name);
-            } else {
-                printf("\etEntry \(aq%s\(aq is not a subdirectory.\en",
-                        file_name);
-            }
-        }
-
         /* Close associated file descriptor for this event */
 
         close(event_fd);
-- 
2.17.1

Re: [PATCH 1/3] Revert "fanotify.7, fanotify_mark.2: Document FAN_DIR_MODIFY"

[Matthew Bobrowski]

On Fri, May 29, 2020 at 12:25:28PM +0300, Amir Goldstein wrote:
> This reverts commit a93e5c9593a95d09a1c9deb94dfdecbb970b8162.
> 
> FAN_DIR_MODIFY was disabled for v5.7 release by kernel commit
> f17936993af0 ("fanotify: turn off support for FAN_DIR_MODIFY").
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

This looks fine to me.

Reviewed-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>

/M

Re: [PATCH 1/3] Revert "fanotify.7, fanotify_mark.2: Document FAN_DIR_MODIFY"

[Michael Kerrisk (man-pages)]

On 5/29/20 11:25 AM, Amir Goldstein wrote:
> This reverts commit a93e5c9593a95d09a1c9deb94dfdecbb970b8162.
> 
> FAN_DIR_MODIFY was disabled for v5.7 release by kernel commit
> f17936993af0 ("fanotify: turn off support for FAN_DIR_MODIFY").

Thanks, Amir. Patch applied.

@ Matthew, thanks of the review (and likewise for the other patches).

Cheers,

Michael

> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
>  man2/fanotify_mark.2 | 33 --------------------
>  man7/fanotify.7      | 73 ++++++--------------------------------------
>  2 files changed, 10 insertions(+), 96 deletions(-)
> 
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index bc8120fb2..f3ebb0208 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -244,38 +244,6 @@ An fanotify file descriptor created with
>  .B FAN_REPORT_FID
>  is required.
>  .TP
> -.BR FAN_DIR_MODIFY " (since Linux 5.7)"
> -.\" commit 44d705b0370b1d581f46ff23e5d33e8b5ff8ec58
> -Create an event when one of the entries in a marked directory has been created,
> -deleted, or moved.
> -This event will encapsulate additional information about the name of the
> -modified directory entry.
> -It is intended for applications that want to monitor the content of a large
> -directory without having to reiterate the directory each time it is modified.
> -The directory entry name will follow the directory file handle information in
> -the reported event.
> -See
> -.BR fanotify (7)
> -for additional details about the reported event format.
> -The
> -.BR FAN_DIR_MODIFY
> -event will be generated in addition to the events
> -.BR FAN_CREATE ,
> -.BR FAN_DELETE ,
> -.BR FAN_MOVED_FROM ,
> -.BR FAN_MOVED_TO
> -and will never be merged with the aforementioned events.
> -An application receiving this event must not assume that the reported entry name
> -exists in the marked directory at the time the event is received and should call
> -.BR fstatat (2)
> -with the entry name to learn about the current content of the directory entry.
> -See
> -.BR fanotify (7)
> -for an example of its usage.
> -An fanotify file descriptor created with
> -.BR FAN_REPORT_FID
> -is required.
> -.TP
>  .B FAN_OPEN_PERM
>  Create an event when a permission to open a file or directory is requested.
>  An fanotify file descriptor created with
> @@ -341,7 +309,6 @@ The flag has no effect when marking mounts and filesystems.
>  Note that events are not generated for children of the subdirectories
>  of marked directories.
>  More specifically, the directory entry modification events
> -.BR FAN_DIR_MODIFY ,
>  .BR FAN_CREATE ,
>  .BR FAN_DELETE ,
>  .BR FAN_MOVED_FROM ,
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index ac6fbbcae..3c49d67a9 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -324,9 +324,6 @@ A watched file or directory was moved.
>  .B FAN_MODIFY
>  A file was modified.
>  .TP
> -.B FAN_DIR_MODIFY
> -A directory entry was created, deleted or moved.
> -.TP
>  .B FAN_CLOSE_WRITE
>  A file that was opened for writing
>  .RB ( O_WRONLY
> @@ -398,11 +395,9 @@ For example, when an fanotify file descriptor is created using
>  the
>  .I info_type
>  field of this header is set to
> -.BR FAN_EVENT_INFO_TYPE_FID
> -or
> -.BR FAN_EVENT_INFO_TYPE_DFID_NAME .
> -Event listeners can use this field to check what additional information
> -is received for an event.
> +.BR FAN_EVENT_INFO_TYPE_FID .
> +Event listeners can use this field to check that the additional
> +information received for an event is of the correct type.
>  Additionally, the
>  .I fanotify_event_info_header
>  also contains a
> @@ -448,14 +443,6 @@ and
>  will carry the
>  .IR file_handle
>  information for the child object if the child object is being watched.
> -For the event
> -.BR FAN_DIR_MODIFY ,
> -the
> -.I info_type
> -field of this header is set to
> -.BR FAN_EVENT_INFO_TYPE_DFID_NAME .
> -The file handle describes the modified directory and a null terminated
> -name of the modified entry follows directly after the file handle buffer.
>  .PP
>  The following macros are provided to iterate over a buffer containing
>  fanotify event metadata returned by a
> @@ -640,11 +627,9 @@ events for the monitored directory itself.
>  Fanotify monitoring of directories is not recursive:
>  to monitor subdirectories under a directory,
>  additional marks must be created.
> -The
> -.B FAN_DIR_MODIFY
> -event can be used for detecting when a subdirectory has been created under
> -a marked directory.
> -An additional mark must then be set on the newly created subdirectory.
> +(But note that the fanotify API provides no way of detecting when a
> +subdirectory has been created under a marked directory,
> +which makes recursive monitoring difficult.)
>  Monitoring mounts offers the capability to monitor a whole directory tree.
>  Monitoring filesystems offers the capability to monitor changes made from
>  any mount of a filesystem instance.
> @@ -938,8 +923,6 @@ The program marks the filesystem object that is passed as
>  a command-line argument
>  and waits until an event of type
>  .B FAN_CREATE
> -or
> -.B FAN_DIR_MODIFY
>  has occurred.
>  The event mask indicates which type of filesystem object\(emeither
>  a file or a directory\(emwas created.
> @@ -956,9 +939,7 @@ This is followed by the creation of a regular file,
>  This results in a
>  .B FAN_CREATE
>  event being generated and reported against the file's parent watched
> -directory object and a
> -.B FAN_DIR_MODIFY
> -event being generated and reported with the created file name.
> +directory object.
>  Program execution ends once all events captured within the buffer have
>  been processed.
>  .PP
> @@ -968,9 +949,6 @@ been processed.
>  Listening for events.
>  FAN_CREATE (file created):
>          Directory /home/user has been modified.
> -FAN_DIR_MODIFY (entry changed):
> -        Directory /home/user has been modified.
> -        Entry 'testfile.txt' is not a subdirectory.
>  All events processed successfully. Program exiting.
>  
>  $ \fBtouch /home/user/testfile.txt\fP              # In another terminal
> @@ -985,9 +963,7 @@ This specific action results in a
>  .B FAN_CREATE
>  event being generated and is reported with the
>  .B FAN_ONDIR
> -flag set and a
> -.B FAN_DIR_MODIFY
> -event being generated and reported with the created directory name.
> +flag set.
>  .PP
>  .in +4n
>  .EX
> @@ -995,9 +971,6 @@ event being generated and reported with the created directory name.
>  Listening for events.
>  FAN_CREATE | FAN_ONDIR (subdirectory created):
>          Directory /home/user has been modified.
> -FAN_DIR_MODIFY (entry changed):
> -        Directory /home/user has been modified.
> -        Entry 'testdir' is a subdirectory.
>  All events processed successfully. Program exiting.
>  
>  $ \fBmkdir \-p /home/user/testdir\fP          # In another terminal
> @@ -1030,8 +1003,6 @@ main(int argc, char **argv)
>      struct file_handle *file_handle;
>      struct fanotify_event_metadata *metadata;
>      struct fanotify_event_info_fid *fid;
> -    const char *file_name;
> -    struct stat sb;
>  
>      if (argc != 2) {
>          fprintf(stderr, "Invalid number of command line arguments.\en");
> @@ -1057,7 +1028,7 @@ main(int argc, char **argv)
>      /* Place a mark on the filesystem object supplied in argv[1]. */
>  
>      ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
> -                        FAN_DIR_MODIFY | FAN_CREATE | FAN_ONDIR,
> +                        FAN_CREATE | FAN_ONDIR,
>                          AT_FDCWD, argv[1]);
>      if (ret == \-1) {
>          perror("fanotify_mark");
> @@ -1084,19 +1055,11 @@ main(int argc, char **argv)
>  
>          /* Ensure that the event info is of the correct type */
>  
> -        if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_FID) {
> -            file_name = NULL;
> -        } else if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
> -            file_name = file_handle->f_handle +
> -                        file_handle->handle_bytes;
> -        } else {
> +        if (fid\->hdr.info_type != FAN_EVENT_INFO_TYPE_FID) {
>              fprintf(stderr, "Received unexpected event info type.\en");
>              exit(EXIT_FAILURE);
>          }
>  
> -        if (metadata\->mask == FAN_DIR_MODIFY)
> -            printf("FAN_DIR_MODIFY (entry changed):\en");
> -
>          if (metadata\->mask == FAN_CREATE)
>              printf("FAN_CREATE (file created):\en");
>  
> @@ -1138,22 +1101,6 @@ main(int argc, char **argv)
>          path[path_len] = \(aq\e0\(aq;
>          printf("\etDirectory \(aq%s\(aq has been modified.\en", path);
>  
> -        if (file_name) {
> -            ret = fstatat(event_fd, file_name, &sb, 0);
> -            if (ret == \-1) {
> -                if (errno != ENOENT) {
> -                    perror("fstatat");
> -                    exit(EXIT_FAILURE);
> -                }
> -                printf("\etEntry %\(aqs\(aq does not exist.\en", file_name);
> -            } else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
> -                printf("\etEntry \(aq%s\(aq is a subdirectory.\en", file_name);
> -            } else {
> -                printf("\etEntry \(aq%s\(aq is not a subdirectory.\en",
> -                        file_name);
> -            }
> -        }
> -
>          /* Close associated file descriptor for this event */
>  
>          close(event_fd);
> 


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

[PATCH 2/3] fanotify_init.2: move out of place entry FAN_REPORT_FID

[Amir Goldstein]

It was inserted in the middle of the FAN_CLASS_ multi flags bit and
broke the multi flag documentation.

Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man2/fanotify_init.2 | 60 ++++++++++++++++++++++----------------------
 1 file changed, 30 insertions(+), 30 deletions(-)

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 0131575ab..5cfeea023 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -94,36 +94,6 @@ 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.
@@ -184,6 +154,36 @@ supplied to
 .BR read (2)
 (see
 .BR fanotify (7)).
+.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.
 .PP
 The
 .I event_f_flags
-- 
2.17.1

Re: [PATCH 2/3] fanotify_init.2: move out of place entry FAN_REPORT_FID

[Matthew Bobrowski]

On Fri, May 29, 2020 at 12:25:29PM +0300, Amir Goldstein wrote:
> It was inserted in the middle of the FAN_CLASS_ multi flags bit and
> broke the multi flag documentation.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

Nice, thank you for tidying this up Amir! Looks good to me.

Reviewed-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>

/M

Re: [PATCH 2/3] fanotify_init.2: move out of place entry FAN_REPORT_FID

[Michael Kerrisk (man-pages)]

On 5/29/20 11:25 AM, Amir Goldstein wrote:
> It was inserted in the middle of the FAN_CLASS_ multi flags bit and
> broke the multi flag documentation.

Thanks, Amir. Patch applied.

Cheers,

Michael


> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
>  man2/fanotify_init.2 | 60 ++++++++++++++++++++++----------------------
>  1 file changed, 30 insertions(+), 30 deletions(-)
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index 0131575ab..5cfeea023 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -94,36 +94,6 @@ 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.
> @@ -184,6 +154,36 @@ supplied to
>  .BR read (2)
>  (see
>  .BR fanotify (7)).
> +.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.
>  .PP
>  The
>  .I event_f_flags
> 


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

[PATCH 3/3] fanotify.7, fanotify_mark.2: Clarify FAN_ONDIR in output mask

[Amir Goldstein]

FAN_ONDIR has been an input only flag before introduing FAN_REPORT_FID.
With FAN_REPORT_FID it can also be in output mask.

Move the text describing its role in output mask to fanotify.7 where the
other output mask bits are documented.

Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
 man2/fanotify_mark.2 | 17 +++--------------
 man7/fanotify.7      | 18 ++++++++++++++++++
 2 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index f3ebb0208..b6c6c34c4 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -278,30 +278,19 @@ Create events for directories\(emfor example, when
 (but see BUGS), and
 .BR closedir (3)
 are called.
-Without this flag, only are created only for files.
-.IP
-The
-.BR FAN_ONDIR
-flag is reported in an event mask only if the
-.I fanotify_fd
-file descriptor has been initialized with the flag
-.BR FAN_REPORT_FID .
+Without this flag, events are created only for files.
 In the context of directory entry events, such as
 .BR FAN_CREATE ,
 .BR FAN_DELETE ,
 .BR FAN_MOVED_FROM ,
 and
-.BR FAN_MOVED_TO
-for example, specifying the flag
+.BR FAN_MOVED_TO ,
+specifying the flag
 .BR FAN_ONDIR
 is required in order to create events when subdirectory entries are
 modified (i.e.,
 .BR mkdir (2)/
 .BR rmdir (2)).
-Subdirectory entry modification events will never be merged with
-nonsubdirectory entry modification events.
-This flag is never reported individually within an event and is always
-supplied in conjunction with another event type.
 .TP
 .B FAN_EVENT_ON_CHILD
 Events for the immediate children of marked directories shall be created.
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 3c49d67a9..100ec3ebd 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -381,6 +381,24 @@ This is a synonym for:
 .IP
     FAN_MOVED_FROM | FAN_MOVED_TO
 .PP
+The following bits may appear in
+.I mask
+only in conjunction with other event type bits:
+.TP
+.B FAN_ONDIR
+The events described in the
+.I mask
+have occurred on a directory object.
+Reporting events on directories requires setting this flag in the mark mask.
+See
+.BR fanotify_mark (2)
+for additional details.
+The
+.BR FAN_ONDIR
+flag is reported in an event mask only if the fanotify group has been
+initialized with the flag
+.BR FAN_REPORT_FID .
+.PP
 The fields of the
 .I fanotify_event_info_fid
 structure are as follows:
-- 
2.17.1

Re: [PATCH 3/3] fanotify.7, fanotify_mark.2: Clarify FAN_ONDIR in output mask

[Matthew Bobrowski]

On Fri, May 29, 2020 at 12:25:30PM +0300, Amir Goldstein wrote:
> FAN_ONDIR has been an input only flag before introduing FAN_REPORT_FID.
> With FAN_REPORT_FID it can also be in output mask.
> 
> Move the text describing its role in output mask to fanotify.7 where the
> other output mask bits are documented.
> 
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>

This also looks good to me!

Reviewed-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>

/M

Re: [PATCH 3/3] fanotify.7, fanotify_mark.2: Clarify FAN_ONDIR in output mask

[Michael Kerrisk (man-pages)]

Hello Amir,

On 5/29/20 11:25 AM, Amir Goldstein wrote:
> FAN_ONDIR has been an input only flag before introduing FAN_REPORT_FID.
> With FAN_REPORT_FID it can also be in output mask.
> 
> Move the text describing its role in output mask to fanotify.7 where the
> other output mask bits are documented.

Thanks. Patch applied.

Cheers,

Michael

> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---
>  man2/fanotify_mark.2 | 17 +++--------------
>  man7/fanotify.7      | 18 ++++++++++++++++++
>  2 files changed, 21 insertions(+), 14 deletions(-)
> 
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index f3ebb0208..b6c6c34c4 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -278,30 +278,19 @@ Create events for directories\(emfor example, when
>  (but see BUGS), and
>  .BR closedir (3)
>  are called.
> -Without this flag, only are created only for files.
> -.IP
> -The
> -.BR FAN_ONDIR
> -flag is reported in an event mask only if the
> -.I fanotify_fd
> -file descriptor has been initialized with the flag
> -.BR FAN_REPORT_FID .
> +Without this flag, events are created only for files.
>  In the context of directory entry events, such as
>  .BR FAN_CREATE ,
>  .BR FAN_DELETE ,
>  .BR FAN_MOVED_FROM ,
>  and
> -.BR FAN_MOVED_TO
> -for example, specifying the flag
> +.BR FAN_MOVED_TO ,
> +specifying the flag
>  .BR FAN_ONDIR
>  is required in order to create events when subdirectory entries are
>  modified (i.e.,
>  .BR mkdir (2)/
>  .BR rmdir (2)).
> -Subdirectory entry modification events will never be merged with
> -nonsubdirectory entry modification events.
> -This flag is never reported individually within an event and is always
> -supplied in conjunction with another event type.
>  .TP
>  .B FAN_EVENT_ON_CHILD
>  Events for the immediate children of marked directories shall be created.
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 3c49d67a9..100ec3ebd 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -381,6 +381,24 @@ This is a synonym for:
>  .IP
>      FAN_MOVED_FROM | FAN_MOVED_TO
>  .PP
> +The following bits may appear in
> +.I mask
> +only in conjunction with other event type bits:
> +.TP
> +.B FAN_ONDIR
> +The events described in the
> +.I mask
> +have occurred on a directory object.
> +Reporting events on directories requires setting this flag in the mark mask.
> +See
> +.BR fanotify_mark (2)
> +for additional details.
> +The
> +.BR FAN_ONDIR
> +flag is reported in an event mask only if the fanotify group has been
> +initialized with the flag
> +.BR FAN_REPORT_FID .
> +.PP
>  The fields of the
>  .I fanotify_event_info_fid
>  structure are as follows:
> 


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

Re: [PATCH 0/3] fanotify man page updates for final v5.7

[Michael Kerrisk (man-pages)]

On Fri, 29 May 2020 at 11:25, Amir Goldstein <amir73il@gmail.com> wrote:
>
> Hi Michael,
>
> We made a last minute call to disable the FAN_DIR_MODIFY for v5.7.
> Here is a man page update with some promissed cleanups.

Thanks, Amir. I'll just hold off a little longer on processing these,
in case there are Acked-bys / review comments.

Cheers,

Michael

> Amir Goldstein (3):
>   Revert "fanotify.7, fanotify_mark.2: Document FAN_DIR_MODIFY"
>   fanotify_init.2: move out of place entry FAN_REPORT_FID
>   fanotify.7, fanotify_mark.2: Clarify FAN_ONDIR in output mask
>
>  man2/fanotify_init.2 | 60 ++++++++++++++---------------
>  man2/fanotify_mark.2 | 50 ++----------------------
>  man7/fanotify.7      | 91 ++++++++++++++------------------------------
>  3 files changed, 61 insertions(+), 140 deletions(-)
>
> --
> 2.17.1
>


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

Re: [PATCH 0/3] fanotify man page updates for final v5.7

[Matthew Bobrowski]

On Wed, Jun 03, 2020 at 12:26:10PM +0200, Michael Kerrisk (man-pages) wrote:
> On Fri, 29 May 2020 at 11:25, Amir Goldstein <amir73il@gmail.com> wrote:
> >
> > Hi Michael,
> >
> > We made a last minute call to disable the FAN_DIR_MODIFY for v5.7.
> > Here is a man page update with some promissed cleanups.
> 
> Thanks, Amir. I'll just hold off a little longer on processing these,
> in case there are Acked-bys / review comments.

Sure, please do. I'm intending to get around to reviewing this series by the
end of the week. 
 
/M