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

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

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