[PATCH] io_cancel.2, io_destroy.2, io_getevents.2, io_cancel.2, io_submit.2: SYNOPSIS: s/io_context_t/aio_context_t/

[PATCH] io_cancel.2, io_destroy.2, io_getevents.2, io_cancel.2, io_submit.2: SYNOPSIS: s/io_context_t/aio_context_t/

[Alejandro Colomar]

Linux uses aio_context_t for these syscalls,
and it's the type provided by <linux/aio_abi.h>.
Use it in the SYNOPSIS.

libaio uses 'io_context_t', but that difference is already noted in NOTES.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man2/io_cancel.2    | 2 +-
 man2/io_destroy.2   | 2 +-
 man2/io_getevents.2 | 2 +-
 man2/io_setup.2     | 2 +-
 man2/io_submit.2    | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index 68129896e..ccf252594 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -11,7 +11,7 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .PP
-.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
+.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
 .BI "              struct io_event *" result );
 .fi
 .PP
diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index e7cdf0203..e9c93b652 100644
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -11,7 +11,7 @@ io_destroy \- destroy an asynchronous I/O context
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .PP
-.BI "int io_destroy(io_context_t " ctx_id );
+.BI "int io_destroy(aio_context_t " ctx_id );
 .fi
 .PP
 .IR Note :
diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index cf616593b..10dfbc005 100644
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -12,7 +12,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
 .BR "#include <linux/aio_abi.h>" "         /* Defines needed types */"
 .BR "#include <linux/time.h>" "            /* Defines 'struct timespec' */"
 .PP
-.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
+.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
 .BI "                 struct io_event *" events \
 ", struct timespec *" timeout );
 .fi
diff --git a/man2/io_setup.2 b/man2/io_setup.2
index 7b07b51c1..f9860fda5 100644
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -11,7 +11,7 @@ io_setup \- create an asynchronous I/O context
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .PP
-.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctx_idp );
+.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
 .fi
 .PP
 .IR Note :
diff --git a/man2/io_submit.2 b/man2/io_submit.2
index 7fbc9d7ae..22bdd31fc 100644
--- a/man2/io_submit.2
+++ b/man2/io_submit.2
@@ -12,7 +12,7 @@ io_submit \- submit asynchronous I/O blocks for processing
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .PP
-.BI "int io_submit(io_context_t " ctx_id ", long " nr \
+.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
 ", struct iocb **" iocbpp );
 .fi
 .PP
-- 
2.28.0

Re: [PATCH] io_cancel.2, io_destroy.2, io_getevents.2, io_cancel.2, io_submit.2: SYNOPSIS: s/io_context_t/aio_context_t/

[Michael Kerrisk (man-pages)]

On 11/1/20 2:55 PM, Alejandro Colomar wrote:
> Linux uses aio_context_t for these syscalls,
> and it's the type provided by <linux/aio_abi.h>.
> Use it in the SYNOPSIS.
> 
> libaio uses 'io_context_t', but that difference is already noted in NOTES.

Hey Alex,

I think your patch is correct. But I see that I changed these prototypes
a few years back after reports from Jeff Moyer and Andi Kleen. The
situation is confusing.

Could I ask you to rewrite this patch to add the following
immediately after the DESCRIPTION heading in each page:

[[
Note: this page describes the raw Linux system call interface.
the wrapper functions provided by _libaio_ use a differnt type for
the _ctx_id_ argument. See NOTES.
]]

This will save me or someone else in the future perhaps 
reverting your fix!

Thanks,

Michael

> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man2/io_cancel.2    | 2 +-
>  man2/io_destroy.2   | 2 +-
>  man2/io_getevents.2 | 2 +-
>  man2/io_setup.2     | 2 +-
>  man2/io_submit.2    | 2 +-
>  5 files changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
> index 68129896e..ccf252594 100644
> --- a/man2/io_cancel.2
> +++ b/man2/io_cancel.2
> @@ -11,7 +11,7 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
>  .nf
>  .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
>  .PP
> -.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
> +.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
>  .BI "              struct io_event *" result );
>  .fi
>  .PP
> diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
> index e7cdf0203..e9c93b652 100644
> --- a/man2/io_destroy.2
> +++ b/man2/io_destroy.2
> @@ -11,7 +11,7 @@ io_destroy \- destroy an asynchronous I/O context
>  .nf
>  .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
>  .PP
> -.BI "int io_destroy(io_context_t " ctx_id );
> +.BI "int io_destroy(aio_context_t " ctx_id );
>  .fi
>  .PP
>  .IR Note :
> diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
> index cf616593b..10dfbc005 100644
> --- a/man2/io_getevents.2
> +++ b/man2/io_getevents.2
> @@ -12,7 +12,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
>  .BR "#include <linux/aio_abi.h>" "         /* Defines needed types */"
>  .BR "#include <linux/time.h>" "            /* Defines 'struct timespec' */"
>  .PP
> -.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
> +.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
>  .BI "                 struct io_event *" events \
>  ", struct timespec *" timeout );
>  .fi
> diff --git a/man2/io_setup.2 b/man2/io_setup.2
> index 7b07b51c1..f9860fda5 100644
> --- a/man2/io_setup.2
> +++ b/man2/io_setup.2
> @@ -11,7 +11,7 @@ io_setup \- create an asynchronous I/O context
>  .nf
>  .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
>  .PP
> -.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctx_idp );
> +.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
>  .fi
>  .PP
>  .IR Note :
> diff --git a/man2/io_submit.2 b/man2/io_submit.2
> index 7fbc9d7ae..22bdd31fc 100644
> --- a/man2/io_submit.2
> +++ b/man2/io_submit.2
> @@ -12,7 +12,7 @@ io_submit \- submit asynchronous I/O blocks for processing
>  .nf
>  .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
>  .PP
> -.BI "int io_submit(io_context_t " ctx_id ", long " nr \
> +.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
>  ", struct iocb **" iocbpp );
>  .fi
>  .PP
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH v2] io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2: SYNOPSIS: s/io_context_t/aio_context_t/

[Alejandro Colomar]

Linux uses aio_context_t for these syscalls,
and it's the type provided by <linux/aio_abi.h>.
Use it in the SYNOPSIS.

libaio uses 'io_context_t', but that difference is already noted in NOTES.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---


On 2020-11-01 19:02, Michael Kerrisk (man-pages) wrote:
> On 11/1/20 2:55 PM, Alejandro Colomar wrote:
>> Linux uses aio_context_t for these syscalls,
>> and it's the type provided by <linux/aio_abi.h>.
>> Use it in the SYNOPSIS.
>>
>> libaio uses 'io_context_t', but that difference is already noted in NOTES.
>
> Hey Alex,
>
> I think your patch is correct. But I see that I changed these prototypes
> a few years back after reports from Jeff Moyer and Andi Kleen. The
> situation is confusing.
>
> Could I ask you to rewrite this patch to add the following
> immediately after the DESCRIPTION heading in each page:
>
> [[
> Note: this page describes the raw Linux system call interface.
> the wrapper functions provided by _libaio_ use a differnt type for
> the _ctx_id_ argument. See NOTES.
> ]]
>
> This will save me or someone else in the future perhaps
> reverting your fix!
>
> Thanks,
>
> Michael

Sure :)

Cheers,

Alex


 man2/io_cancel.2    | 11 ++++++++++-
 man2/io_destroy.2   | 11 ++++++++++-
 man2/io_getevents.2 | 11 ++++++++++-
 man2/io_setup.2     | 11 ++++++++++-
 man2/io_submit.2    | 11 ++++++++++-
 5 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index 68129896e..6ce41bf7a 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -11,13 +11,22 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .PP
-.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
+.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
 .BI "              struct io_event *" result );
 .fi
 .PP
 .IR Note :
 There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
+.IR Note :
+this page describes the raw Linux system call interface.
+The wrapper functions provided by
+.I libaio
+use a different type for the
+.I ctx_id
+argument.
+See NOTES.
+.PP
 The
 .BR io_cancel ()
 system call
diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index e7cdf0203..fed749c49 100644
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -11,12 +11,21 @@ io_destroy \- destroy an asynchronous I/O context
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .PP
-.BI "int io_destroy(io_context_t " ctx_id );
+.BI "int io_destroy(aio_context_t " ctx_id );
 .fi
 .PP
 .IR Note :
 There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
+.IR Note :
+this page describes the raw Linux system call interface.
+The wrapper functions provided by
+.I libaio
+use a different type for the
+.I ctx_id
+argument.
+See NOTES.
+.PP
 The
 .BR io_destroy ()
 system call
diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index cf616593b..2b13234c1 100644
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -12,7 +12,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
 .BR "#include <linux/aio_abi.h>" "         /* Defines needed types */"
 .BR "#include <linux/time.h>" "            /* Defines 'struct timespec' */"
 .PP
-.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
+.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
 .BI "                 struct io_event *" events \
 ", struct timespec *" timeout );
 .fi
@@ -20,6 +20,15 @@ io_getevents \- read asynchronous I/O events from the completion queue
 .IR Note :
 There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
+.IR Note :
+this page describes the raw Linux system call interface.
+The wrapper functions provided by
+.I libaio
+use a different type for the
+.I ctx_id
+argument.
+See NOTES.
+.PP
 The
 .BR io_getevents ()
 system call
diff --git a/man2/io_setup.2 b/man2/io_setup.2
index 7b07b51c1..25ff61c65 100644
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -11,12 +11,21 @@ io_setup \- create an asynchronous I/O context
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .PP
-.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctx_idp );
+.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
 .fi
 .PP
 .IR Note :
 There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
+.IR Note :
+this page describes the raw Linux system call interface.
+The wrapper functions provided by
+.I libaio
+use a different type for the
+.I ctx_idp
+argument.
+See NOTES.
+.PP
 The
 .BR io_setup ()
 system call
diff --git a/man2/io_submit.2 b/man2/io_submit.2
index 7fbc9d7ae..36dc483e8 100644
--- a/man2/io_submit.2
+++ b/man2/io_submit.2
@@ -12,13 +12,22 @@ io_submit \- submit asynchronous I/O blocks for processing
 .nf
 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
 .PP
-.BI "int io_submit(io_context_t " ctx_id ", long " nr \
+.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
 ", struct iocb **" iocbpp );
 .fi
 .PP
 .IR Note :
 There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
+.IR Note :
+this page describes the raw Linux system call interface.
+The wrapper functions provided by
+.I libaio
+use a different type for the
+.I ctx_id
+argument.
+See NOTES.
+.PP
 The
 .BR io_submit ()
 system call
-- 
2.28.0

Re: [PATCH v2] io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2: SYNOPSIS: s/io_context_t/aio_context_t/

[Michael Kerrisk (man-pages)]

Hi Alex,

On 11/2/20 12:31 AM, Alejandro Colomar wrote:
> Linux uses aio_context_t for these syscalls,
> and it's the type provided by <linux/aio_abi.h>.
> Use it in the SYNOPSIS.
> 
> libaio uses 'io_context_t', but that difference is already noted in NOTES.
> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Thanks. Patch applied.

Cheers,

Michael

> ---
> 
> 
> On 2020-11-01 19:02, Michael Kerrisk (man-pages) wrote:
>> On 11/1/20 2:55 PM, Alejandro Colomar wrote:
>>> Linux uses aio_context_t for these syscalls,
>>> and it's the type provided by <linux/aio_abi.h>.
>>> Use it in the SYNOPSIS.
>>>
>>> libaio uses 'io_context_t', but that difference is already noted in NOTES.
>>
>> Hey Alex,
>>
>> I think your patch is correct. But I see that I changed these prototypes
>> a few years back after reports from Jeff Moyer and Andi Kleen. The
>> situation is confusing.
>>
>> Could I ask you to rewrite this patch to add the following
>> immediately after the DESCRIPTION heading in each page:
>>
>> [[
>> Note: this page describes the raw Linux system call interface.
>> the wrapper functions provided by _libaio_ use a differnt type for
>> the _ctx_id_ argument. See NOTES.
>> ]]
>>
>> This will save me or someone else in the future perhaps
>> reverting your fix!
>>
>> Thanks,
>>
>> Michael
> 
> Sure :)
> 
> Cheers,
> 
> Alex
> 
> 
>  man2/io_cancel.2    | 11 ++++++++++-
>  man2/io_destroy.2   | 11 ++++++++++-
>  man2/io_getevents.2 | 11 ++++++++++-
>  man2/io_setup.2     | 11 ++++++++++-
>  man2/io_submit.2    | 11 ++++++++++-
>  5 files changed, 50 insertions(+), 5 deletions(-)
> 
> diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
> index 68129896e..6ce41bf7a 100644
> --- a/man2/io_cancel.2
> +++ b/man2/io_cancel.2
> @@ -11,13 +11,22 @@ io_cancel \- cancel an outstanding asynchronous I/O operation
>  .nf
>  .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
>  .PP
> -.BI "int io_cancel(io_context_t " ctx_id ", struct iocb *" iocb ,
> +.BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
>  .BI "              struct io_event *" result );
>  .fi
>  .PP
>  .IR Note :
>  There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
> +.IR Note :
> +this page describes the raw Linux system call interface.
> +The wrapper functions provided by
> +.I libaio
> +use a different type for the
> +.I ctx_id
> +argument.
> +See NOTES.
> +.PP
>  The
>  .BR io_cancel ()
>  system call
> diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
> index e7cdf0203..fed749c49 100644
> --- a/man2/io_destroy.2
> +++ b/man2/io_destroy.2
> @@ -11,12 +11,21 @@ io_destroy \- destroy an asynchronous I/O context
>  .nf
>  .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
>  .PP
> -.BI "int io_destroy(io_context_t " ctx_id );
> +.BI "int io_destroy(aio_context_t " ctx_id );
>  .fi
>  .PP
>  .IR Note :
>  There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
> +.IR Note :
> +this page describes the raw Linux system call interface.
> +The wrapper functions provided by
> +.I libaio
> +use a different type for the
> +.I ctx_id
> +argument.
> +See NOTES.
> +.PP
>  The
>  .BR io_destroy ()
>  system call
> diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
> index cf616593b..2b13234c1 100644
> --- a/man2/io_getevents.2
> +++ b/man2/io_getevents.2
> @@ -12,7 +12,7 @@ io_getevents \- read asynchronous I/O events from the completion queue
>  .BR "#include <linux/aio_abi.h>" "         /* Defines needed types */"
>  .BR "#include <linux/time.h>" "            /* Defines 'struct timespec' */"
>  .PP
> -.BI "int io_getevents(io_context_t " ctx_id ", long " min_nr ", long " nr ,
> +.BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
>  .BI "                 struct io_event *" events \
>  ", struct timespec *" timeout );
>  .fi
> @@ -20,6 +20,15 @@ io_getevents \- read asynchronous I/O events from the completion queue
>  .IR Note :
>  There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
> +.IR Note :
> +this page describes the raw Linux system call interface.
> +The wrapper functions provided by
> +.I libaio
> +use a different type for the
> +.I ctx_id
> +argument.
> +See NOTES.
> +.PP
>  The
>  .BR io_getevents ()
>  system call
> diff --git a/man2/io_setup.2 b/man2/io_setup.2
> index 7b07b51c1..25ff61c65 100644
> --- a/man2/io_setup.2
> +++ b/man2/io_setup.2
> @@ -11,12 +11,21 @@ io_setup \- create an asynchronous I/O context
>  .nf
>  .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
>  .PP
> -.BI "int io_setup(unsigned " nr_events ", io_context_t *" ctx_idp );
> +.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
>  .fi
>  .PP
>  .IR Note :
>  There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
> +.IR Note :
> +this page describes the raw Linux system call interface.
> +The wrapper functions provided by
> +.I libaio
> +use a different type for the
> +.I ctx_idp
> +argument.
> +See NOTES.
> +.PP
>  The
>  .BR io_setup ()
>  system call
> diff --git a/man2/io_submit.2 b/man2/io_submit.2
> index 7fbc9d7ae..36dc483e8 100644
> --- a/man2/io_submit.2
> +++ b/man2/io_submit.2
> @@ -12,13 +12,22 @@ io_submit \- submit asynchronous I/O blocks for processing
>  .nf
>  .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
>  .PP
> -.BI "int io_submit(io_context_t " ctx_id ", long " nr \
> +.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
>  ", struct iocb **" iocbpp );
>  .fi
>  .PP
>  .IR Note :
>  There is no glibc wrapper for this system call; see NOTES.
>  .SH DESCRIPTION
> +.IR Note :
> +this page describes the raw Linux system call interface.
> +The wrapper functions provided by
> +.I libaio
> +use a different type for the
> +.I ctx_id
> +argument.
> +See NOTES.
> +.PP
>  The
>  .BR io_submit ()
>  system call
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/