Re: [PATCH v3] fanotify.7, fanotify_init.2, fanotify_mark.2: Document FAN_REPORT_FID and directory modification events

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hello Matthew,

On 6/9/19 10:44 AM, Matthew Bobrowski wrote:
Hi Michael,

On Sat, Jun 08, 2019 at 01:58:00PM +0200, Michael Kerrisk (man-pages) wrote:

[...]

+.BR FAN_REPORT_FID " (since Linux 5.1)"
+.\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
+This value allows the receipt of events which contain additional information
+about the underlying object correlated to an event.

In a few places, I changed "object" to "filesystem object", just to
reduce the chance of ambiguity a little.

Good thought. This does read better.

Okay.

[...]

diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 3c6e9565a..ce7aa9804 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2

[...]

+Depending on whether
+.BR FAN_REPORT_FID
+is supplied as one of the flags when calling
+.BR fanotify_init (2)
+determines what structure(s) are returned for an event within the read
+buffer.

The wording here in the preceding sentence is a bit off:

      "Depending on... determines"

Can you clarify?

OK. So, if FAN_REPORT_FID is provided as a flag to fanotify_init(), then
the use of this flag influences what data structure(s) an event listener
can expect to receive for each event i.e.

- For an event listener that does _not_ make use of the FAN_REPORT_FID
   flag should expect to _only_ receive the data structure of type
   fanotify_event_metadata used to describe a single event.

However, on the other hand.

- For an event listener that _does_ make use of the FAN_REPORT_FID flag
   should expect to receive data structures of type
   fanotify_event_metadata and fanotify_event_info_fid used to describe a
   single event.

With that being said, depending on whether FAN_REPORT_FID is, or is not
specified, determines the type of data structures that an event
listener can expect to receive for a single event.

I'm happy to reword this if necessary.


Okay -- if you could send a patch against current Git, that would
be great.

[...]

-The following output was recorded while editing the file
+The second program (fanotify_fid.c) is an example of fanotify being used
+with
+.B FAN_REPORT_FID
+enabled.
+It attempts to mark the object that is passed as a command-line argument

Why the wording "It attempts to mark the" vs "It marks"?

Your wording implies that the attempt may fail, but if that
is the case, I thing some further words are needed here.

That's correct. I was in fact implying that this could fail and that's
certainly the reality. However, for the sake of illustration, I do think
it can be changed to "It marks" as oppose to "It attempts to mark". I
don't really have any strong points as to why it can't be changed "It
marks".

Okay -- changed.

+and waits until an event of type
+.B FAN_CREATE
+has occurred.
+Depending on whether a file or directory is created depends on what mask
+is returned in the event mask.

That last sentence is not quite right. Is one of these alternatives
correct?

"Whether or not a filesystem object (a file or directory) was created
depends on what mask is returned in the event mask."

"The event mask indicates which type of filesystem object--either
a file or a directory--was created".

This ^ is more accurate. Let's go with that.

Okay. Changed.

[...]


+        /* metadata->fd is set to FAN_NOFD when FAN_REPORT_FID is enabled.
+         * To obtain a file descriptor for the file object corresponding to
+         * an event you can use the struct file_handle that's provided
+         * within the fanotify_event_info_fid in conjunction with the
+         * open_by_handle_at(2) system call. A check for -ESTALE is done
+         * to accommodate for the situation where the file handle was
+         * deleted for the object prior to this system call.

Would that last sentence read better as:

"... where the file handle for the object was deleted prior to
this system call."

?

Yes, that's definitely better.

Okay -- changed.

Cheers,

Michael



[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux