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

[Alejandro Colomar <alx@kernel.org>]

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