Skip to contentSkip to conversation

aio_suspend.3: SYNOPSIS: Use 'restrict' in prototypes

PATCH Superseded Alejandro Colomar 2 participants 5 messages Feb 18, 2021 – Feb 20, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 aio_suspend.3: SYNOPSIS: Use 'restrict' in prototypes

POSIX does NOT specify aio_suspend() to use 'restrict'. However, glibc uses 'restrict'.
Users might be surprised by this! Let's use it here too!

......

.../glibc$ grep_glibc_prototype aio_suspend
rt/aio.h:167:
extern int aio_suspend (const struct aiocb *const __list[], int __nent,
const struct timespec *__restrict __timeout)
__nonnull ((1));
.../glibc$

---

Hello Michael,

I sent this patch separately because it's a bit different, and would like someone from glibc to check it.
I CCd Ulrich, who added 'restrict' to the function in glibc.

Thanks,

Alex

---
 man3/aio_suspend.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
man3/aio_suspend.3 +2 -1
index 76a05f48e..dcae51e1c 100644
@@ -31,7 +31,8 @@ aio_suspend \- wait for asynchronous I/O operation or timeout
 .B "#include <aio.h>"
 .PP
 .BI "int aio_suspend(const struct aiocb * const " aiocb_list [],
-.BI "                int " nitems ", const struct timespec *" timeout );
+.BI "                int " nitems \
+", const struct timespec *restrict " timeout );
 .PP
 Link with \fI\-lrt\fP.
 .fi
Signature · 1 line
2.30.1.721.g45526154a5
#1 lore raw

Hello Alex,

Quoted 3 lines · Alejandro Colomar

POSIX does NOT specify aio_suspend() to use 'restrict'. However, glibc uses 'restrict'.
Users might be surprised by this! Let's use it here too!

Thanks for spotting this. Perhaps if we apply this, the patch should include something in CONFORMING TO to note that POSIX doesn't specify 'restrict'. What do you think?

Cheers,

Michael

Quoted 43 lines

......

.../glibc$ grep_glibc_prototype aio_suspend
rt/aio.h:167:
extern int aio_suspend (const struct aiocb *const __list[], int __nent,
const struct timespec *__restrict __timeout)
__nonnull ((1));
.../glibc$

---

Hello Michael,

I sent this patch separately because it's a bit different, and would like someone from glibc to check it.
I CCd Ulrich, who added 'restrict' to the function in glibc.

Thanks,

Alex

---
 man3/aio_suspend.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
man3/aio_suspend.3 +2 -1
index 76a05f48e..dcae51e1c 100644
@@ -31,7 +31,8 @@ aio_suspend \- wait for asynchronous I/O operation or timeout
 .B "#include <aio.h>"
 .PP
 .BI "int aio_suspend(const struct aiocb * const " aiocb_list [],
-.BI "                int " nitems ", const struct timespec *" timeout );
+.BI "                int " nitems \
+", const struct timespec *restrict " timeout );
 .PP
 Link with \fI\-lrt\fP.
 .fi
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 11 lines · Michael Kerrisk (man-pages)

Hello Alex,

Quoted 3 lines · Alejandro Colomar

POSIX does NOT specify aio_suspend() to use 'restrict'. However, glibc uses 'restrict'.
Users might be surprised by this! Let's use it here too!

Thanks for spotting this. Perhaps if we apply this, the patch should include something in CONFORMING TO to note that POSIX doesn't specify 'restrict'. What do you think?

Hi Michael,

I was about to ask exactly that in the email, but I forgot :) Yes.

Cheers,

Alex

Quoted 50 lines

Cheers,

Michael

Quoted 43 lines

......

.../glibc$ grep_glibc_prototype aio_suspend
rt/aio.h:167:
extern int aio_suspend (const struct aiocb *const __list[], int __nent,
const struct timespec *__restrict __timeout)
__nonnull ((1));
.../glibc$

---

Hello Michael,

I sent this patch separately because it's a bit different, and would like someone from glibc to check it.
I CCd Ulrich, who added 'restrict' to the function in glibc.

Thanks,

Alex

---
  man3/aio_suspend.3 | 3 ++-
  1 file changed, 2 insertions(+), 1 deletion(-)
man3/aio_suspend.3 +2 -1
index 76a05f48e..dcae51e1c 100644
@@ -31,7 +31,8 @@ aio_suspend \- wait for asynchronous I/O operation or timeout
  .B "#include <aio.h>"
  .PP
  .BI "int aio_suspend(const struct aiocb * const " aiocb_list [],
-.BI "                int " nitems ", const struct timespec *" timeout );
+.BI "                int " nitems \
+", const struct timespec *restrict " timeout );
  .PP
  Link with \fI\-lrt\fP.
  .fi
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#3 lore raw

PATCH v2 1/1 aio_suspend.3: SYNOPSIS: Use 'restrict' in prototypes

POSIX does NOT specify aio_suspend() to use 'restrict'. However, glibc uses 'restrict'.
Users might be surprised by this! Let's use it here too!

......

.../glibc$ grep_glibc_prototype aio_suspend
rt/aio.h:167:
extern int aio_suspend (const struct aiocb *const __list[], int __nent,
const struct timespec *__restrict __timeout)
__nonnull ((1));
.../glibc$

---

v2:
- wsfix + srcfix: Avoid breaking the line in the prototype
- Note the difference between POSIX and glibc in CONFORMING TO.

---
 man3/aio_suspend.3 | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
man3/aio_suspend.3 +6 -2
index 76a05f48e..e0355a449 100644
@@ -30,8 +30,8 @@ aio_suspend \- wait for asynchronous I/O operation or timeout
 .PP
 .B "#include <aio.h>"
 .PP
-.BI "int aio_suspend(const struct aiocb * const " aiocb_list [],
-.BI "                int " nitems ", const struct timespec *" timeout );
+.BI "int aio_suspend(const struct aiocb *const " aiocb_list "[], int " nitems ,
+.BI "                const struct timespec *restrict " timeout );
 .PP
 Link with \fI\-lrt\fP.
 .fi
@@ -122,6 +122,10 @@ T}	Thread safety	MT-Safe
 .sp 1
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008.
+.PP
+POSIX doesn't specify the parameters to be
+.IR restrict ;
+that is specific to glibc.
 .SH NOTES
 One can achieve polling by using a non-NULL
 .I timeout
Signature · 1 line
2.30.1.721.g45526154a5
#4 lore raw
Quoted 3 lines · Alejandro Colomar

POSIX does NOT specify aio_suspend() to use 'restrict'. However, glibc uses 'restrict'.
Users might be surprised by this! Let's use it here too!

Hi Alex.

Patch applied. Thanks!

Cheers,

Michael

Quoted 49 lines

......

.../glibc$ grep_glibc_prototype aio_suspend
rt/aio.h:167:
extern int aio_suspend (const struct aiocb *const __list[], int __nent,
const struct timespec *__restrict __timeout)
__nonnull ((1));
.../glibc$

---

v2:
- wsfix + srcfix: Avoid breaking the line in the prototype
- Note the difference between POSIX and glibc in CONFORMING TO.

---
 man3/aio_suspend.3 | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
man3/aio_suspend.3 +6 -2
index 76a05f48e..e0355a449 100644
@@ -30,8 +30,8 @@ aio_suspend \- wait for asynchronous I/O operation or timeout
 .PP
 .B "#include <aio.h>"
 .PP
-.BI "int aio_suspend(const struct aiocb * const " aiocb_list [],
-.BI "                int " nitems ", const struct timespec *" timeout );
+.BI "int aio_suspend(const struct aiocb *const " aiocb_list "[], int " nitems ,
+.BI "                const struct timespec *restrict " timeout );
 .PP
 Link with \fI\-lrt\fP.
 .fi
@@ -122,6 +122,10 @@ T}	Thread safety	MT-Safe
 .sp 1
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008.
+.PP
+POSIX doesn't specify the parameters to be
+.IR restrict ;
+that is specific to glibc.
 .SH NOTES
 One can achieve polling by using a non-NULL
 .I timeout
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/