Re: Should aiocb(3type) say something about the order of fields?

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 1755 bytes --]

Hi Jonathan,

On 2026-02-14T11:51:36+0000, Jonathan Wakely wrote:
> https://man7.org/linux/man-pages/man3/aiocb.3type.html doesn't tell
> you that the order shown there is not the real order used on linux.

Hmmm, this was explained in system_data_types(7).  When the page was
split into many, that information remained there (and I still have
pending the move of the remaining two types in that page).

That page says:
     The structures described in this manual  page  shall  contain,  at
     least, the members shown in their definition, in no particular or‐
     der.

My intention was (and still is) to move that page to intro(3type), and
keep system_data_types as a link page to intro(3type).

> It
> does tell you to look at aio(7), which says:
> 
>     struct aiocb {
>        /* The order of these fields is implementation-dependent */

How about '/* members in no particular order */'?

>        ...
>        /* Various implementation-internal fields not shown */

I'd replace the second comment by '/* ... */'

>     };
> 
> I think it would be helpful to repeat that in aiocb(3type) so you
> don't need to go to a second page to get that info. If aiocb(3type)
> shows actual C code with a struct definition it's reasonable to assume
> that it is accurate, which isn't the case here. The comments in the
> aio(7) page make that clearer.
> 
> The Glibc manual
> <https://sourceware.org/glibc/manual/latest/html_node/Asynchronous-I_002fO.html>
> just names the fields (not showing an actual struct definition) and
> doesn't imply anything about the order.

I prefer the actual struct definition.  I think it's more readable.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]