Re: [PATCH 4/4] fanotify.7, fanotify_mark.2: Document FAN_DIR_MODIFY

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Amir,

On 4/20/20 8:42 PM, Amir Goldstein wrote:
> Document the details of the new FAN_DIR_MODIFY event, which introduces
> entry name information to the fanotify event reporting format.
> 
> Enhance the fanotify_fid.c example to also report this event.

Thanks. patch applied.

Cheers,

Michael

> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> Reviewed-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>
> Reviewed-by: Jan Kara <jack@suse.cz>
> ---
>  man2/fanotify_mark.2 | 33 ++++++++++++++++++++
>  man7/fanotify.7      | 71 +++++++++++++++++++++++++++++++++++++-------
>  2 files changed, 94 insertions(+), 10 deletions(-)
> 
> diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
> index 7fbcd5e36..e94d8a7e1 100644
> --- a/man2/fanotify_mark.2
> +++ b/man2/fanotify_mark.2
> @@ -244,6 +244,38 @@ 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_Q_OVERFLOW
>  Create an event when an overflow of the event queue occurs.
>  The size of the event queue is limited to 16384 entries if
> @@ -315,6 +347,7 @@ 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 72e7e4fb9..cd258abf4 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -324,6 +324,9 @@ 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
> @@ -395,9 +398,11 @@ 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 .
> -Event listeners can use this field to check that the additional
> -information received for an event is of the correct type.
> +.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.
>  Additionally, the
>  .I fanotify_event_info_header
>  also contains a
> @@ -443,6 +448,14 @@ 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
> @@ -627,9 +640,11 @@ events for the monitored directory itself.
>  Fanotify monitoring of directories is not recursive:
>  to monitor subdirectories under a directory,
>  additional marks must be created.
> -(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.)
> +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.
>  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.
> @@ -923,6 +938,8 @@ 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.
> @@ -939,7 +956,9 @@ 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.
> +directory object and a
> +.B FAN_DIR_MODIFY
> +event being generated and reported with the created file name.
>  Program execution ends once all events captured within the buffer have
>  been processed.
>  .PP
> @@ -949,6 +968,9 @@ 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
> @@ -963,7 +985,9 @@ This specific action results in a
>  .B FAN_CREATE
>  event being generated and is reported with the
>  .B FAN_ONDIR
> -flag set.
> +flag set and a
> +.B FAN_DIR_MODIFY
> +event being generated and reported with the created directory name.
>  .PP
>  .in +4n
>  .EX
> @@ -971,6 +995,9 @@ flag set.
>  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
> @@ -1003,6 +1030,8 @@ 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");
> @@ -1028,7 +1057,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_CREATE | FAN_ONDIR,
> +                        FAN_DIR_MODIFY | FAN_CREATE | FAN_ONDIR,
>                          AT_FDCWD, argv[1]);
>      if (ret == \-1) {
>          perror("fanotify_mark");
> @@ -1055,11 +1084,18 @@ 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) {
> +        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 {
>              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");
>  
> @@ -1100,6 +1136,21 @@ 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/