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

[Guillem Jover <guillem@debian.org>]

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.

> 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, 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.
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.

Thanks,
Guillem