Skip to contentSkip to conversation

io_setup.2: SYNOPSIS: return long

PATCH In review Alejandro Colomar 2 participants 8 messages Nov 1, 2020 – Nov 13, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 io_setup.2: SYNOPSIS: return long

The Linux kernel uses a long as the return type for this syscall. As glibc provides no wrapper, use the same types the kernel uses.

---

Hi Michael,

Please apply this patch after "s/io_contexxt_t/aio_context_t/".

Cheers,

Alex

 man2/io_setup.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/io_setup.2 +1 -1
index f9860fda5..1a89de220 100644
@@ -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 ", aio_context_t *" ctx_idp );
+.BI "long io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
 .fi
 .PP
 .IR Note :
Signature · 1 line
2.28.0
#1 lore raw

Hi Alex,

Quoted 2 lines · Alejandro Colomar

The Linux kernel uses a long as the return type for this syscall. As glibc provides no wrapper, use the same types the kernel uses.

I think we need this patch for all of the io* pages, right?

Thanks,

Michael

Quoted 28 lines

---

Hi Michael,

Please apply this patch after "s/io_contexxt_t/aio_context_t/".

Cheers,

Alex

 man2/io_setup.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/io_setup.2 +1 -1
index f9860fda5..1a89de220 100644
@@ -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 ", aio_context_t *" ctx_idp );
+.BI "long io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
 .fi
 .PP
 .IR Note :
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#2 lore raw
Quoted 7 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 2 lines · Alejandro Colomar

The Linux kernel uses a long as the return type for this syscall. As glibc provides no wrapper, use the same types the kernel uses.

I think we need this patch for all of the io* pages, right?

Hi Michael,

For some reason, no. AFAICS, only io_setup() really uses 'long'.

Then there's io_submit(), which also declares a 'long', but gets that value from io_submit_one(), which returns an 'int';
we could use either 'long' or 'int'
in the manual page too for this one.

And then there are the others, which use plain 'int'.

See at the end of this email the sources for this answer.

Cheers,

Alex

Quoted 4 lines

Thanks,

Michael

fs/aio.c:1312:
SYSCALL_DEFINE2(io_setup, unsigned, nr_events, aio_context_t __user *, ctxp)

{
	struct kioctx *ioctx = NULL;
	unsigned long ctx;
	long ret;
...
	return ret;
}

fs/aio.c:1381:
SYSCALL_DEFINE1(io_destroy, aio_context_t, ctx)

{
	struct kioctx *ioctx = lookup_ioctx(ctx);
	if (likely(NULL != ioctx)) {
		struct ctx_rq_wait wait;
		int ret;
...
		return ret;
	}
	pr_debug("EINVAL: invalid context id\n");
	return -EINVAL;
}

fs/aio.c:1855:
static int io_submit_one(struct kioctx *ctx, struct iocb __user *user_iocb,
bool compat)

fs/aio.c:1914:
SYSCALL_DEFINE3(io_submit, aio_context_t, ctx_id, long, nr,
struct iocb __user * __user *, iocbpp)

{
	struct kioctx *ctx;
	long ret = 0;
	int i = 0;
	struct blk_plug plug;
...
		ret = io_submit_one(ctx, user_iocb, false);
...
	return i ? i : ret;
}

fs/aio.c:2008:
SYSCALL_DEFINE3(io_cancel, aio_context_t, ctx_id, struct iocb __user *, iocb,
struct io_event __user *, result)

{
	struct kioctx *ctx;
	struct aio_kiocb *kiocb;
	int ret = -EINVAL;

...

	return ret;
}

fs/aio.c:2084:
SYSCALL_DEFINE5(io_getevents, aio_context_t, ctx_id,
long, min_nr,
long, nr,
struct io_event __user *, events, struct __kernel_timespec __user *, timeout)

{
	struct timespec64	ts;
	int			ret;
...
	return ret;
}
#3 lore raw

Hi Alex,

Quoted 5 lines · Alejandro Colomar
Quoted 3 lines · Michael Kerrisk (man-pages)

Hi Alex,

On 11/1/20 2:59 PM, Alejandro Colomar wrote:

Quoted 8 lines
Quoted 4 lines
Quoted 2 lines

The Linux kernel uses a long as the return type for this syscall. As glibc provides no wrapper, use the same types the kernel uses.

I think we need this patch for all of the io* pages, right?

Hi Michael,

For some reason, no. AFAICS, only io_setup() really uses 'long'.

But is not SYSCALL_DEFINEX() producing a prototype with return value 'long' in all the cases? (I have not checked, I just presume so.)

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#4 lore raw
Quoted 11 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 8 lines · Alejandro Colomar
Quoted 6 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 2 lines · Alejandro Colomar

The Linux kernel uses a long as the return type for this syscall. As glibc provides no wrapper, use the same types the kernel uses.

Quoted 8 lines
Quoted 5 lines
Quoted 1 line

I think we need this patch for all of the io* pages, right?

Hi Michael,

For some reason, no. AFAICS, only io_setup() really uses 'long'.

But is not SYSCALL_DEFINEX() producing a prototype with return value 'long' in all the cases? (I have not checked, I just presume so.)

Hi Michael,

Well, yes.
SYSCALL_DEFINEx() produces a return type of long
for _all_ syscalls, AFAICS.
(as I said before, that macro is a bit obscure, but I can read that).

Would you like to change all syscall man pages (without a wrapper) to use long as the return type?

Thanks.

Alex

Quoted 8 lines

Thanks,

Michael

#5 lore raw

Ping: Re: [PATCH] io_setup.2: SYNOPSIS: return long

Ping.

Quoted 46 lines · Alejandro Colomar
Quoted 14 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 10 lines · Alejandro Colomar

On 2020-11-02 08:37, Michael Kerrisk (man-pages) wrote:
  > Hi Alex,
  >
  > On 11/1/20 2:59 PM, Alejandro Colomar wrote:
  >> The Linux kernel uses a long as the return type for this syscall. >> As glibc provides no wrapper, use the same types the kernel uses. >
  > I think we need this patch for all of the io* pages, right?

Quoted 6 lines
Quoted 3 lines

Hi Michael,

For some reason, no.  AFAICS, only io_setup() really uses 'long'.

But is not SYSCALL_DEFINEX() producing a prototype with return value 'long' in all the cases? (I have not checked, I just presume so.)

Hi Michael,

Well, yes.
SYSCALL_DEFINEx() produces a return type of long
for _all_ syscalls, AFAICS.
(as I said before, that macro is a bit obscure, but I can read that).

Would you like to change all syscall man pages (without a wrapper) to use long as the return type?

Thanks.

Alex

Quoted 8 lines

Thanks,

Michael

#6 lore raw
In reply to Alejandro Colomar
Quoted 14 lines · Alejandro Colomar
Quoted 11 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 8 lines · Alejandro Colomar
Quoted 6 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 2 lines · Alejandro Colomar

The Linux kernel uses a long as the return type for this syscall. As glibc provides no wrapper, use the same types the kernel uses.

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 1 line

I think we need this patch for all of the io* pages, right?

Hi Michael,

For some reason, no. AFAICS, only io_setup() really uses 'long'.

Ahhh -- now I get what you mean.

Quoted 5 lines
Quoted 2 lines

But is not SYSCALL_DEFINEX() producing a prototype with return value 'long' in all the cases? (I have not checked, I just presume so.)

Hi Michael,

Quoted 7 lines

Well, yes.
SYSCALL_DEFINEx() produces a return type of long
for _all_ syscalls, AFAICS.
(as I said before, that macro is a bit obscure, but I can read that).

Would you like to change all syscall man pages (without a wrapper) to use long as the return type?

I guess not.

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#7 lore raw
In reply to Alejandro Colomar

Hi Alex,

Quoted 4 lines · Alejandro Colomar

The Linux kernel uses a long as the return type for this syscall. As glibc provides no wrapper, use the same types the kernel uses.

Thanks. Patch applied.

Cheers,

Michael

Quoted 27 lines

---

Hi Michael,

Please apply this patch after "s/io_contexxt_t/aio_context_t/".

Cheers,

Alex

 man2/io_setup.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man2/io_setup.2 +1 -1
index f9860fda5..1a89de220 100644
@@ -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 ", aio_context_t *" ctx_idp );
+.BI "long io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
 .fi
 .PP
 .IR Note :
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/