* iNotify Man Page: Prefix Header + Tail Array vs C Structure
@ 2015-12-13 12:09 Michael Titke
[not found] ` <566D6009.7050409-X3bqsT2AMO4b1SvskN2V4Q@public.gmane.org>
0 siblings, 1 reply; 5+ messages in thread
From: Michael Titke @ 2015-12-13 12:09 UTC (permalink / raw)
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w; +Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
Hello!
The current version of the manual page describing /inotify/ (as well as
the version installed with Ubuntu 15.04 frozen to Violet Indigo)
contains a descriptive C structure describing the /inotify//messages/:
struct inotify_event {
int wd; /* Watch descriptor */
uint32_t mask; /* Mask describing event */
uint32_t cookie; /* Unique cookie associating related
events (for rename(2)) */
uint32_t len; /* Size of name field */
char name[]; /* Optional null-terminated name */
};
As part of the development of VSI I translated the above structure
without much thinking into a corresponding byte structure description:
(define inotify-event-header
(byte-structure-description
(wd int)
(mask 4) ; [sic! that was an uint32]
(cookie 4)
(len 4)
;(name pointer) ; That's not a pointer but an array: NAME_MAX + 1
))
Now while the prefix (or header) of the message is described adequately
the specification of the tail array as a char name[] would in C be
interpreted as a pointer onto a char. One might insert a length
parameter like char name[NAME_MAX + 1] or exclude that tail array from
the structure and describe the message in terms of /prefix/ or /header/
and /tail array/.
struct inotify_event {
int wd; /* Watch descriptor */
uint32_t mask; /* Mask describing event */
uint32_t cookie; /* Unique cookie associating related
events (for rename(2)) */
uint32_t len; /* Size of name field */
char name[NAME_MAX + 1]; /* Optional
null-terminated name */
};
With that length parameter in the structure the size of the messages is
described adequately but the actual length of the name might be confused
with the maximum size which usually includes some (tail) padding.
I'm sorry but I don't know enough about /iNotify/ to craft a patch for
this. Is this a datagram channel where half-read messages will vanish?
Perhaps I should continue reading the manual page. :-)
Regards,
Michael
--
VSI: https://code.launchpad.net/viper-system-interface
(reason: 550 5.7.1 Content-Policy reject msg: The message contains HTML subpart, therefore we consider it SPAM or Outlook Virus. TEXT/PLAIN is accepted.! BF:<U
PS That's not really up to the standard but "... since hosts aren't
required to relay mail at all ..." someone presumes something.
--
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: iNotify Man Page: Prefix Header + Tail Array vs C Structure
[not found] ` <566D6009.7050409-X3bqsT2AMO4b1SvskN2V4Q@public.gmane.org>
@ 2015-12-13 17:53 ` walter harms
[not found] ` <566DB08E.6090305-fPG8STNUNVg@public.gmane.org>
0 siblings, 1 reply; 5+ messages in thread
From: walter harms @ 2015-12-13 17:53 UTC (permalink / raw)
To: Michael Titke
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
I am not sure that i understood what you want ...
i would answer the question:
* what is the actual size of struct inotify_event ?
inotify(7) says:
the length of each inotify_event structure is thus sizeof(struct inotify_event)+len
hope that helps ..
re,
wh
Am 13.12.2015 13:09, schrieb Michael Titke:
> Hello!
>
> The current version of the manual page describing /inotify/ (as well as
> the version installed with Ubuntu 15.04 frozen to Violet Indigo)
> contains a descriptive C structure describing the /inotify//messages/:
>
> struct inotify_event {
> int wd; /* Watch descriptor */
> uint32_t mask; /* Mask describing event */
> uint32_t cookie; /* Unique cookie associating related
> events (for rename(2)) */
> uint32_t len; /* Size of name field */
> char name[]; /* Optional null-terminated name */
> };
>
> As part of the development of VSI I translated the above structure
> without much thinking into a corresponding byte structure description:
>
> (define inotify-event-header
> (byte-structure-description
> (wd int)
> (mask 4) ; [sic! that was an uint32]
> (cookie 4)
> (len 4)
> ;(name pointer) ; That's not a pointer but an array: NAME_MAX + 1
> ))
>
> Now while the prefix (or header) of the message is described adequately
> the specification of the tail array as a char name[] would in C be
> interpreted as a pointer onto a char. One might insert a length
> parameter like char name[NAME_MAX + 1] or exclude that tail array from
> the structure and describe the message in terms of /prefix/ or /header/
> and /tail array/.
>
> struct inotify_event {
> int wd; /* Watch descriptor */
> uint32_t mask; /* Mask describing event */
> uint32_t cookie; /* Unique cookie associating related
> events (for rename(2)) */
> uint32_t len; /* Size of name field */
> char name[NAME_MAX + 1]; /* Optional
> null-terminated name */
> };
>
> With that length parameter in the structure the size of the messages is
> described adequately but the actual length of the name might be confused
> with the maximum size which usually includes some (tail) padding.
>
> I'm sorry but I don't know enough about /iNotify/ to craft a patch for
> this. Is this a datagram channel where half-read messages will vanish?
> Perhaps I should continue reading the manual page. :-)
>
> Regards,
> Michael
>
> --
> VSI: https://code.launchpad.net/viper-system-interface
>
> (reason: 550 5.7.1 Content-Policy reject msg: The message contains HTML
> subpart, therefore we consider it SPAM or Outlook Virus. TEXT/PLAIN is
> accepted.! BF:<U
>
>
> PS That's not really up to the standard but "... since hosts aren't
> required to relay mail at all ..." someone presumes something.
> --
> 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
--
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: iNotify Man Page: Prefix Header + Tail Array vs C Structure
[not found] ` <566DB08E.6090305-fPG8STNUNVg@public.gmane.org>
@ 2015-12-14 9:46 ` Michael Titke
[not found] ` <566E9009.7030703-X3bqsT2AMO4b1SvskN2V4Q@public.gmane.org>
0 siblings, 1 reply; 5+ messages in thread
From: Michael Titke @ 2015-12-14 9:46 UTC (permalink / raw)
To: wharms-fPG8STNUNVg
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
On 13/12/2015 18:53, walter harms wrote:
> I am not sure that i understood what you want ...
>
> i would answer the question:
>
> * what is the actual size of struct inotify_event ?
>
> inotify(7) says:
> the length of each inotify_event structure is thus sizeof(struct inotify_event)+len
Please fix the manual page: the actual size is sizeof (struct
inotify_event) where struct inotify_event is as described below with a
size parameter for the name field of NAME_MAX+1 and the actual string
contained in that field has a length of /len/ (and is probably NULL
terminated at len+1).
With your answer the actual size would be the length of the fixed prefix
fields (w/o) plus the size of a pointer (sizeof(void*) for the name
field w/o parameter plus len): thus you might be off by the size of a
pointer. Each inotify message has the same width. This only refers to
the structure described in the manual page! An actual sizeof (struct
inotify_event) might yield the correct result as the system headers
probably contain the correct structure. But that diversion is what makes
the manual page a little bit confusing and presenting a pointer instead
of a fixed size array is just plainly wrong.
Please review my original message as well as reference documentation
regarding the C programming language.
HTH,
Michael
>
> hope that helps ..
>
> re,
> wh
>
> Am 13.12.2015 13:09, schrieb Michael Titke:
>> Hello!
>>
>> The current version of the manual page describing /inotify/ (as well as
>> the version installed with Ubuntu 15.04 frozen to Violet Indigo)
>> contains a descriptive C structure describing the /inotify//messages/:
>>
>> struct inotify_event {
>> int wd; /* Watch descriptor */
>> uint32_t mask; /* Mask describing event */
>> uint32_t cookie; /* Unique cookie associating related
>> events (for rename(2)) */
>> uint32_t len; /* Size of name field */
>> char name[]; /* Optional null-terminated name */
>> };
>>
>> As part of the development of VSI I translated the above structure
>> without much thinking into a corresponding byte structure description:
>>
>> (define inotify-event-header
>> (byte-structure-description
>> (wd int)
>> (mask 4) ; [sic! that was an uint32]
>> (cookie 4)
>> (len 4)
>> ;(name pointer) ; That's not a pointer but an array: NAME_MAX + 1
>> ))
>>
>> Now while the prefix (or header) of the message is described adequately
>> the specification of the tail array as a char name[] would in C be
>> interpreted as a pointer onto a char. One might insert a length
>> parameter like char name[NAME_MAX + 1] or exclude that tail array from
>> the structure and describe the message in terms of /prefix/ or /header/
>> and /tail array/.
>>
>> struct inotify_event {
>> int wd; /* Watch descriptor */
>> uint32_t mask; /* Mask describing event */
>> uint32_t cookie; /* Unique cookie associating related
>> events (for rename(2)) */
>> uint32_t len; /* Size of name field */
>> char name[NAME_MAX + 1]; /* Optional
>> null-terminated name */
>> };
>>
>> With that length parameter in the structure the size of the messages is
>> described adequately but the actual length of the name might be confused
>> with the maximum size which usually includes some (tail) padding.
>>
>> I'm sorry but I don't know enough about /iNotify/ to craft a patch for
>> this. Is this a datagram channel where half-read messages will vanish?
>> Perhaps I should continue reading the manual page. :-)
>>
>> Regards,
>> Michael
>>
>> --
>> VSI: https://code.launchpad.net/viper-system-interface
>>
>> (reason: 550 5.7.1 Content-Policy reject msg: The message contains HTML
>> subpart, therefore we consider it SPAM or Outlook Virus. TEXT/PLAIN is
>> accepted.! BF:<U
>>
>>
>> PS That's not really up to the standard but "... since hosts aren't
>> required to relay mail at all ..." someone presumes something.
>> --
>> 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
--
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: iNotify Man Page: Prefix Header + Tail Array vs C Structure
[not found] ` <566E9009.7030703-X3bqsT2AMO4b1SvskN2V4Q@public.gmane.org>
@ 2015-12-14 11:01 ` Michael Kerrisk (man-pages)
[not found] ` <566EA19A.8060309-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
0 siblings, 1 reply; 5+ messages in thread
From: Michael Kerrisk (man-pages) @ 2015-12-14 11:01 UTC (permalink / raw)
To: Michael Titke, wharms-fPG8STNUNVg
Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w, linux-man-u79uwXL29TY76Z2rM5mHXA
Hello Michael,
On 12/14/2015 10:46 AM, Michael Titke wrote:
>
>
> On 13/12/2015 18:53, walter harms wrote:
>> I am not sure that i understood what you want ...
>>
>> i would answer the question:
>>
>> * what is the actual size of struct inotify_event ?
>>
>> inotify(7) says:
>> the length of each inotify_event structure is thus sizeof(struct inotify_event)+len
>
> Please fix the manual page: the actual size is sizeof (struct
> inotify_event) where struct inotify_event is as described below with a
> size parameter for the name field of NAME_MAX+1
If I understand you correctly, what you're saying is not correct.
The 'name' field is variable length,
> and the actual string
> contained in that field has a length of /len/ (and is probably NULL
> terminated at len+1).
Again, if I understand what you are trying to say, this is not
correct. The man page is I think rather clear:
The name field is present only when an event is returned for a
file inside a watched directory; it identifies the file path‐
name relative to the watched directory. This pathname is null-
terminated, and may include further null bytes ('\0') to align
subsequent reads to a suitable address boundary.
The len field counts all of the bytes in name, including the
null bytes; the length of each inotify_event structure is thus
sizeof(struct inotify_event)+len.
> With your answer the actual size would be the length of the fixed prefix
> fields (w/o) plus the size of a pointer (sizeof(void*)
That's not what Walter said.
> for the name
> field w/o parameter plus len): thus you might be off by the size of a
> pointer. Each inotify message has the same width. This only refers to
> the structure described in the manual page! An actual sizeof (struct
> inotify_event) might yield the correct result as the system headers
> probably contain the correct structure.
If you grep through the headers in /usr/include, I think
you'll get a surprise...
> But that diversion is what makes
> the manual page a little bit confusing and presenting a pointer instead
> of a fixed size array is just plainly wrong.
The man page is not presenting a pointer. See below.
> Please review my original message as well as reference documentation
> regarding the C programming language.
Sorry to say, but I think you might want to review the C standard.
The syntax shown in the man page is precisely the C99 way for
declaring a flexible length array at the end of a structure:
https://en.wikipedia.org/wiki/Flexible_array_member
IOW, I think the page is fine.
Cheers,
Michael
>>> The current version of the manual page describing /inotify/ (as well as
>>> the version installed with Ubuntu 15.04 frozen to Violet Indigo)
>>> contains a descriptive C structure describing the /inotify//messages/:
>>>
>>> struct inotify_event {
>>> int wd; /* Watch descriptor */
>>> uint32_t mask; /* Mask describing event */
>>> uint32_t cookie; /* Unique cookie associating related
>>> events (for rename(2)) */
>>> uint32_t len; /* Size of name field */
>>> char name[]; /* Optional null-terminated name */
>>> };
>>>
>>> As part of the development of VSI I translated the above structure
>>> without much thinking into a corresponding byte structure description:
>>>
>>> (define inotify-event-header
>>> (byte-structure-description
>>> (wd int)
>>> (mask 4) ; [sic! that was an uint32]
>>> (cookie 4)
>>> (len 4)
>>> ;(name pointer) ; That's not a pointer but an array: NAME_MAX + 1
>>> ))
>>>
>>> Now while the prefix (or header) of the message is described adequately
>>> the specification of the tail array as a char name[] would in C be
>>> interpreted as a pointer onto a char. One might insert a length
>>> parameter like char name[NAME_MAX + 1] or exclude that tail array from
>>> the structure and describe the message in terms of /prefix/ or /header/
>>> and /tail array/.
>>>
>>> struct inotify_event {
>>> int wd; /* Watch descriptor */
>>> uint32_t mask; /* Mask describing event */
>>> uint32_t cookie; /* Unique cookie associating related
>>> events (for rename(2)) */
>>> uint32_t len; /* Size of name field */
>>> char name[NAME_MAX + 1]; /* Optional
>>> null-terminated name */
>>> };
>>>
>>> With that length parameter in the structure the size of the messages is
>>> described adequately but the actual length of the name might be confused
>>> with the maximum size which usually includes some (tail) padding.
>>>
>>> I'm sorry but I don't know enough about /iNotify/ to craft a patch for
>>> this. Is this a datagram channel where half-read messages will vanish?
>>> Perhaps I should continue reading the manual page. :-)
>>>
>>> Regards,
>>> Michael
>>>
>>> --
>>> VSI: https://code.launchpad.net/viper-system-interface
>>>
>>> (reason: 550 5.7.1 Content-Policy reject msg: The message contains HTML
>>> subpart, therefore we consider it SPAM or Outlook Virus. TEXT/PLAIN is
>>> accepted.! BF:<U
>>>
>>>
>>> PS That's not really up to the standard but "... since hosts aren't
>>> required to relay mail at all ..." someone presumes something.
>>> --
>>> 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
>
>
--
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: iNotify Man Page: Prefix Header + Tail Array vs C Structure
[not found] ` <566EA19A.8060309-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
@ 2015-12-14 12:48 ` Michael Titke
0 siblings, 0 replies; 5+ messages in thread
From: Michael Titke @ 2015-12-14 12:48 UTC (permalink / raw)
To: Michael Kerrisk (man-pages), wharms-fPG8STNUNVg
Cc: linux-man-u79uwXL29TY76Z2rM5mHXA
There won't be any future discussions on this level. Just put a wontfix
on it but stop burbling. There won't be any more reports regarding man
pages. That project is to be criticized by all means.
--
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
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2015-12-14 12:48 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-12-13 12:09 iNotify Man Page: Prefix Header + Tail Array vs C Structure Michael Titke
[not found] ` <566D6009.7050409-X3bqsT2AMO4b1SvskN2V4Q@public.gmane.org>
2015-12-13 17:53 ` walter harms
[not found] ` <566DB08E.6090305-fPG8STNUNVg@public.gmane.org>
2015-12-14 9:46 ` Michael Titke
[not found] ` <566E9009.7030703-X3bqsT2AMO4b1SvskN2V4Q@public.gmane.org>
2015-12-14 11:01 ` Michael Kerrisk (man-pages)
[not found] ` <566EA19A.8060309-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2015-12-14 12:48 ` Michael Titke
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.