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

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

[Jonathan Wakely]

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. It
does tell you to look at aio(7), which says:

    struct aiocb {
       /* The order of these fields is implementation-dependent */
       ...
       /* Various implementation-internal fields not shown */
    };

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.

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

[Alejandro Colomar]

[-- 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 --]

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

[Alejandro Colomar]

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

On 2026-02-14T13:30:05+0100, Alejandro Colomar wrote:
> 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 '/* ... */'

How about this?

	$ diffman-git 
	--- HEAD:man/man3type/aiocb.3type
	+++ ./man/man3type/aiocb.3type
	@@ -10,6 +10,7 @@ SYNOPSIS
	      #include <aio.h>
	 
	      struct aiocb {
	+         /* members in no particular order */
		  int             aio_fildes;     /* File descriptor */
		  off_t           aio_offset;     /* File offset */
		  volatile void  *aio_buf;        /* Location of buffer */
	@@ -17,6 +18,7 @@ SYNOPSIS
		  int             aio_reqprio;    /* Request priority offset */
		  struct sigevent aio_sigevent;   /* Signal number and value */
		  int             aio_lio_opcode; /* Operation to be performed */
	+         /* ... */
	      };
	 
	 DESCRIPTION

> 
> >     };
> > 
> > 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>



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

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