[PATCH v1 0/6] Split io_setup(3) from io_setup.2.

[Alejandro Colomar <alx@kernel.org>]

Hi!

I plan to split documentation of io_* system calls from their libaio
wrapper (which will be moved to io_*(3), as they're library functions).
I'm CCing linux-aio@, just so they're aware, and Guillem, which seems to
be the maintainer of the Debian package.

If you (libaio) want to get ownership of the man3 manual pages I'm
creating, feel free to steal them.  If you prefer that I keep them in
this repo, that's fine too; I'm happy to keep them.

I have made sure to not duplicate information, so for example
io_setup(3)'s ERRORS refers to io_setup(2).  I don't care too much
whether io_setup(3) should refer to io_setup(2) or vice versa, so for
now I've made io_setup(3) defer to the system call (as that's the real
source of truth).  If you have a preference, please let me know.

I have left ctx_idp undocumented in the libaio wrapper, because other
than having a different type (which is visible in the synopsis), I don't
know anything about it.  I can see that the system call documentation
doesn't apply, because by being a pointer to an incomplete structure,
users can't bzero(3) it.  So clearly, the documentation that applies to
the system call doesn't apply to the wrapper (one of the strong reasons
to split the manual page).

This sample patch set only touches io_setup(2/3), but I may/will do this
with other io_*(2) APIs implemented by libaio.  I'm even considering it
for some pages that document significant differences between system
calls and glibc wrappers.

Any comments?


Have a lovely day!
Alex

Alejandro Colomar (6):
  man/man2/io_setup.2: Reduce parameter name
  man/man2/io_setup.2: Update reference (proc(5) => proc_sys_fs(5))
  man/man2/io_setup.2: ERRORS: Split EINVAL
  man/man2/io_setup.2: ERRORS: It is *ctx_idp that must be initialized
  man/man2/io_setup.2: Use syscall(2) in the SYNOPSIS
  man/man*/io_setup.[23]: Split io_setup(3) from io_setup.2

 man/man2/io_setup.2 | 84 ++++++++++++++++-----------------------------
 man/man3/io_setup.3 | 40 +++++++++++++++++++++
 2 files changed, 70 insertions(+), 54 deletions(-)
 create mode 100644 man/man3/io_setup.3

Range-diff against v0:
-:  -------- > 1:  6e23fd87 man/man2/io_setup.2: Reduce parameter name
-:  -------- > 2:  978c3109 man/man2/io_setup.2: Update reference (proc(5) => proc_sys_fs(5))
-:  -------- > 3:  28e8dc04 man/man2/io_setup.2: ERRORS: Split EINVAL
-:  -------- > 4:  31b6dec8 man/man2/io_setup.2: ERRORS: It is *ctx_idp that must be initialized
-:  -------- > 5:  7811fd45 man/man2/io_setup.2: Use syscall(2) in the SYNOPSIS
-:  -------- > 6:  c6fcae43 man/man*/io_setup.[23]: Split io_setup(3) from io_setup.2
-- 
2.53.0