[patch] fanotify.7: Fix description of FAN_EVENT_NEXT()

[patch] fanotify.7: Fix description of FAN_EVENT_NEXT()

[Michael Kerrisk (man-pages)]

Hi Heinrich,

I realized that the description of FAN_EVENT_NEXT() is not quite correct.
It does not update 'meta', but instead returns a pointer to the next
structure. I tried also to add a bit more detail to the description.
Does the following patch look okay to you?

Cheers,

Michael


--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -309,13 +309,24 @@ against the length of the metadata structure and the
 field of the first metadata structure in the buffer.
 .TP
 .B FAN_EVENT_NEXT(meta, len)
-This macro sets the pointer
-.I meta
-to the next metadata structure using the length indicated in the
+This macro uses the length indicated in the
 .I event_len
-field of the metadata structure and reduces the remaining length of the
-buffer
-.IR len .
+field of the metadata structure pointed to by
+.IR meta
+to calculate the address of the next metadata structure that follows
+.IR meta .
+.I len
+is the number of bytes of metadata that currently remain in the buffer.
+The macro returns a pointer to the next metadata structure that follows
+.IR meta ,
+and reduces
+.I len
+by the number of bytes in the the metadata structure that
+has been skipped over (i.e., it subtracts
+.IR meta\->event_len
+from
+.IR len ).
+.\"
 .SS Monitoring an fanotify file descriptor for events
 When an fanotify event occurs, the fanotify file descriptor indicates as
 readable when passed to

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] fanotify.7: Fix description of FAN_EVENT_NEXT()

[Heinrich Schuchardt]

Hello Michael,

the proposed new description of FAN_EVENT_NEXT is correct.

Should FAN_EVENT_METADATA_LEN also be put into the section with macros?

.B FAN_EVENT_METADATA_LEN
This macro returns the size of structure
.I fanotify_event_metadata
in bytes.
This is the minimum size (and currently the only size) of any event 
metadata.

Best regards

Heinrich

On 19.05.2014 07:20, Michael Kerrisk (man-pages) wrote:
> Hi Heinrich,
>
> I realized that the description of FAN_EVENT_NEXT() is not quite correct.
> It does not update 'meta', but instead returns a pointer to the next
> structure. I tried also to add a bit more detail to the description.
> Does the following patch look okay to you?
>
> Cheers,
>
> Michael
>
>
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -309,13 +309,24 @@ against the length of the metadata structure and the
>   field of the first metadata structure in the buffer.
>   .TP
>   .B FAN_EVENT_NEXT(meta, len)
> -This macro sets the pointer
> -.I meta
> -to the next metadata structure using the length indicated in the
> +This macro uses the length indicated in the
>   .I event_len
> -field of the metadata structure and reduces the remaining length of the
> -buffer
> -.IR len .
> +field of the metadata structure pointed to by
> +.IR meta
> +to calculate the address of the next metadata structure that follows
> +.IR meta .
> +.I len
> +is the number of bytes of metadata that currently remain in the buffer.
> +The macro returns a pointer to the next metadata structure that follows
> +.IR meta ,
> +and reduces
> +.I len
> +by the number of bytes in the the metadata structure that
> +has been skipped over (i.e., it subtracts
> +.IR meta\->event_len
> +from
> +.IR len ).
> +.\"
>   .SS Monitoring an fanotify file descriptor for events
>   When an fanotify event occurs, the fanotify file descriptor indicates as
>   readable when passed to
>

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] fanotify.7: Fix description of FAN_EVENT_NEXT()

[Michael Kerrisk (man-pages)]

Hi Heinrich,

On 05/19/2014 08:58 PM, Heinrich Schuchardt wrote:
> Hello Michael,
> 
> the proposed new description of FAN_EVENT_NEXT is correct.

Thanks for checking. I've added a Reviewed-by for you.

> 
> Should FAN_EVENT_METADATA_LEN also be put into the section with macros?
> 
> .B FAN_EVENT_METADATA_LEN
> This macro returns the size of structure
> .I fanotify_event_metadata
> in bytes.
> This is the minimum size (and currently the only size) of any event 
> metadata.

I'm inclined not to, but I might be wrong. Is there a reason that
user-space might use it?

Cheers,

Michael


> On 19.05.2014 07:20, Michael Kerrisk (man-pages) wrote:
>> Hi Heinrich,
>>
>> I realized that the description of FAN_EVENT_NEXT() is not quite correct.
>> It does not update 'meta', but instead returns a pointer to the next
>> structure. I tried also to add a bit more detail to the description.
>> Does the following patch look okay to you?
>>
>> Cheers,
>>
>> Michael
>>
>>
>> --- a/man7/fanotify.7
>> +++ b/man7/fanotify.7
>> @@ -309,13 +309,24 @@ against the length of the metadata structure and the
>>   field of the first metadata structure in the buffer.
>>   .TP
>>   .B FAN_EVENT_NEXT(meta, len)
>> -This macro sets the pointer
>> -.I meta
>> -to the next metadata structure using the length indicated in the
>> +This macro uses the length indicated in the
>>   .I event_len
>> -field of the metadata structure and reduces the remaining length of the
>> -buffer
>> -.IR len .
>> +field of the metadata structure pointed to by
>> +.IR meta
>> +to calculate the address of the next metadata structure that follows
>> +.IR meta .
>> +.I len
>> +is the number of bytes of metadata that currently remain in the buffer.
>> +The macro returns a pointer to the next metadata structure that follows
>> +.IR meta ,
>> +and reduces
>> +.I len
>> +by the number of bytes in the the metadata structure that
>> +has been skipped over (i.e., it subtracts
>> +.IR meta\->event_len
>> +from
>> +.IR len ).
>> +.\"
>>   .SS Monitoring an fanotify file descriptor for events
>>   When an fanotify event occurs, the fanotify file descriptor indicates as
>>   readable when passed to
>>
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] fanotify.7: Fix description of FAN_EVENT_NEXT()

[Heinrich Schuchardt]

On 20.05.2014 09:36, Michael Kerrisk (man-pages) wrote:
> Hi Heinrich,
>
> On 05/19/2014 08:58 PM, Heinrich Schuchardt wrote:
>> Hello Michael,
>>
>> the proposed new description of FAN_EVENT_NEXT is correct.
>
> Thanks for checking. I've added a Reviewed-by for you.
>
>>
>> Should FAN_EVENT_METADATA_LEN also be put into the section with macros?
>>
>> .B FAN_EVENT_METADATA_LEN
>> This macro returns the size of structure
>> .I fanotify_event_metadata
>> in bytes.
>> This is the minimum size (and currently the only size) of any event
>> metadata.
>
> I'm inclined not to, but I might be wrong. Is there a reason that
> user-space might use it?

FAN_EVENT_METADATA_LEN is the minimum size of a buffer used to read 
fanotify events. Of cause the user may use sizeof to calculate it 
himself. Anyway there is already some mentioning of 
FAN_EVENT_METADATA_LEN in fanotify.7.

You remarked inotify read buffers should be 4 byte aligned on some CPUs.
Shouldn't the same hold true for fanotify?

Best regards

Heinrich

>
> Cheers,
>
> Michael
>
>
>> On 19.05.2014 07:20, Michael Kerrisk (man-pages) wrote:
>>> Hi Heinrich,
>>>
>>> I realized that the description of FAN_EVENT_NEXT() is not quite correct.
>>> It does not update 'meta', but instead returns a pointer to the next
>>> structure. I tried also to add a bit more detail to the description.
>>> Does the following patch look okay to you?
>>>
>>> Cheers,
>>>
>>> Michael
>>>
>>>
>>> --- a/man7/fanotify.7
>>> +++ b/man7/fanotify.7
>>> @@ -309,13 +309,24 @@ against the length of the metadata structure and the
>>>    field of the first metadata structure in the buffer.
>>>    .TP
>>>    .B FAN_EVENT_NEXT(meta, len)
>>> -This macro sets the pointer
>>> -.I meta
>>> -to the next metadata structure using the length indicated in the
>>> +This macro uses the length indicated in the
>>>    .I event_len
>>> -field of the metadata structure and reduces the remaining length of the
>>> -buffer
>>> -.IR len .
>>> +field of the metadata structure pointed to by
>>> +.IR meta
>>> +to calculate the address of the next metadata structure that follows
>>> +.IR meta .
>>> +.I len
>>> +is the number of bytes of metadata that currently remain in the buffer.
>>> +The macro returns a pointer to the next metadata structure that follows
>>> +.IR meta ,
>>> +and reduces
>>> +.I len
>>> +by the number of bytes in the the metadata structure that
>>> +has been skipped over (i.e., it subtracts
>>> +.IR meta\->event_len
>>> +from
>>> +.IR len ).
>>> +.\"
>>>    .SS Monitoring an fanotify file descriptor for events
>>>    When an fanotify event occurs, the fanotify file descriptor indicates as
>>>    readable when passed to
>>>
>>
>>
>
>

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] fanotify.7: Fix description of FAN_EVENT_NEXT()

[Michael Kerrisk (man-pages)]

Hi Heinrich,

On Wed, May 21, 2014 at 8:19 AM, Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org> wrote:
> On 20.05.2014 09:36, Michael Kerrisk (man-pages) wrote:
>>
>> Hi Heinrich,
>>
>> On 05/19/2014 08:58 PM, Heinrich Schuchardt wrote:
>>>
>>> Hello Michael,
>>>
>>> the proposed new description of FAN_EVENT_NEXT is correct.
>>
>>
>> Thanks for checking. I've added a Reviewed-by for you.
>>
>>>
>>> Should FAN_EVENT_METADATA_LEN also be put into the section with macros?
>>>
>>> .B FAN_EVENT_METADATA_LEN
>>> This macro returns the size of structure
>>> .I fanotify_event_metadata
>>> in bytes.
>>> This is the minimum size (and currently the only size) of any event
>>> metadata.
>>
>>
>> I'm inclined not to, but I might be wrong. Is there a reason that
>> user-space might use it?
>
>
> FAN_EVENT_METADATA_LEN is the minimum size of a buffer used to read fanotify
> events. Of cause the user may use sizeof to calculate it himself. Anyway
> there is already some mentioning of FAN_EVENT_METADATA_LEN in fanotify.7.

Okay - I added your text to fanotify(7).

> You remarked inotify read buffers should be 4 byte aligned on some CPUs.
> Shouldn't the same hold true for fanotify?

Yes. So, it looks like a fix to fanotify(7) is required. Could you do
that, please?

Thanks,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html