Re: [PATCH v1 6/6] man/man*/io_setup.[23]: Split io_setup(3) from io_setup.2

[Alejandro Colomar <alx@kernel.org>]

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

Hi Guillem!

On 2026-04-09T18:50:43+0200, Guillem Jover wrote:
> Hi!
> 
> On Wed, 2026-04-08 at 11:18:51 +0200, Alejandro Colomar wrote:
> > This simplifies the documentation of the system call.
> > Let the wrapper be documented as io_setup(3).
> > 
> > Cc: Guillem Jover <guillem@debian.org>
> > Cc: <linux-aio@kvack.org>
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> >  man/man2/io_setup.2 | 60 ++++++++++++---------------------------------
> >  man/man3/io_setup.3 | 40 ++++++++++++++++++++++++++++++
> >  2 files changed, 56 insertions(+), 44 deletions(-)
> >  create mode 100644 man/man3/io_setup.3
> 
> > @@ -87,35 +81,12 @@ .SH ERRORS
> >  .BR io_setup ()
> >  is not implemented on this architecture.
> >  .SH VERSIONS
> > -glibc does not provide a wrapper for this system call.
> > -You could invoke it using
> > -.BR syscall (2).
> > -But instead, you probably want to use the
> > -.BR io_setup ()
> > -wrapper function provided by
> > -.\" http://git.fedorahosted.org/git/?p=libaio.git
> > -.IR libaio .
> > -.P
> > -Note that the
> > +.UR https://pagure.io/libaio
> 
> The pagure.io site is being decommissioned in few months, and I've
> been meaning to ask where the project will be moved for its hosting.

Thanks!  Please let me know if you learn anything about this.

> > diff --git a/man/man3/io_setup.3 b/man/man3/io_setup.3
> > new file mode 100644
> > index 00000000..28b59550
> > --- /dev/null
> > +++ b/man/man3/io_setup.3
> > @@ -0,0 +1,40 @@
> > +.\" Copyright, the authors of the Linux man-pages project
> > +.\"
> > +.\" SPDX-License-Identifier: GPL-2.0-or-later
> > +.\"
> > +.TH io_setup 3 (date) "Linux man-pages (unreleased)"
> > +.SH NAME
> > +io_setup \- create an asynchronous I/O context
> > +.SH LIBRARY
> > +Asynchronous I/O library
> > +.RI ( libaio ,\~ \-laio )
> > +.SH SYNOPSIS
> > +.nf
> > +.B #include <libaio.h>
> > +.P
> > +.BI "long\~io_setup(unsigned int " n ", io_context_t *" ctx_idp );
> > +.fi
> > +.SH DESCRIPTION
> > +.BR io_setup ()
> > +creates an asynchronous I/O context suitable for concurrently processing
> > +.I n
> > +operations.
> > +.SH RETURN VALUE
> > +On success,
> > +.BR io_setup ()
> > +returns 0.
> > +On error,
> > +a negative error code is returned to indicate the error.
> > +.SH ERRORS
> > +See
> > +.BR io_setup (2).
> > +.SH STANDARDS
> > +libaio.
> > +.SH HISTORY
> > +libaio.
> > +.SH SEE ALSO
> > +.BR io (3),
> > +.BR io_setup (2),
> > +.BR aio (7)
> > +.\" .SH AUTHOR
> > +.\" Kent Yoder.
> 
> I think it makes sense to split the syscall from the actual library
> function man pages,

Thanks!  I'll go on with this.

> and IMO it would make sense to move the .3 man pages
> for the wrapper functions to libaio, as it's the project providing them.

On the other hand, it depends on how much work a project will spend on
their manual pages.  To me, it's just a small percentage of extra pages,
so I'm fine handling them if it would mean a lot of work to the project.

I might need their feedback every now and then, but since I don't expect
the APIs to change much if at all, I guess I won't need that much help.

We can do whatever they prefer to do.

> I think though it would be nice to have them being self-contained, and
> only refer to the syscall man page for reference, but not to delegate
> content.

This means more maintenance work.  It's harder to keep them in sync.

And it's also harder to spot the actual differences.  I tend to prefer
referencing other pages.  Of course, there's a limit to that; you don't
want to read 10 or 20 pages to understand an API; but 2 pages could be
reasonable, depending on the case.


Have a lovely night!
Alex

> 
> Thanks,
> Guillem

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

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