[PATCH 00/20] man3: SYNOPSIS: Use 'restrict' in prototypes (batch 1)

[PATCH 00/20] man3: SYNOPSIS: Use 'restrict' in prototypes (batch 1)

[Alejandro Colomar]

Hi Michael,

This are the first pages of man3 with 'restrict'.
I'm sending you these already, becuase otherwise I'd accumulate
too many patches in the end.

I have fixed from the first page until ftw.3.

Spin off:
	I found different terms for parameters that refer to a same thing
	in different functions (usually a '[const] char *'):
	 - filename
	 - file
	 - path
	 - pathname
	 - Maybe others; I don't know

	For 'FILE *' we have more or less the same,
	although this one is much more standard (>90% use 'stream'):
	 - stream
	 - streamp
	 - s
	 - fp
	 - file
	 - filehandle
	 - A few others in specific cases

	What would you do about it?

Thanks,

Alex

---

I'll copy here the commands again to find them easily next time.

For reading the man_pages SYNOPSIS:

.../linux/man-pages$ man_section man2 SYNOPSIS |less;

For reading the glibc prototypes:

.../gnu/glibc$ man_lsfunc ../../linux/man-pages/man2 \
  |while read -r syscall; do
          echo "=============================  ${syscall}";
          grep_glibc_prototype ${syscall};
  done \
  |sed -e 's/\bextern //' -e 's/\b_*//g' \
  |less;

---
Alejandro Colomar (20):
  argz_add.3: SYNOPSIS: Use 'restrict' in prototypes
  asprintf.3: SYNOPSIS: Use 'restrict' in prototypes
  memccpy.3: SYNOPSIS: Use 'restrict' in prototypes
  memcpy.3: SYNOPSIS: Use 'restrict' in prototypes
  crypt.3: SYNOPSIS: Use 'restrict' in prototypes
  ctime.3: SYNOPSIS: Use 'restrict' in prototypes
  ctime.3: SYNOPSIS: Use 'restrict' in prototypes
  dlinfo.3: SYNOPSIS: Use 'restrict' in prototypes
  dlsym.3: SYNOPSIS: Use 'restrict' in prototypes; add missing 'const'
    too
  drand48_r.3: SYNOPSIS: Use 'restrict' in prototypes
  ecvt_r.3: SYNOPSIS: Use 'restrict' in prototypes
  ecvt.3: SYNOPSIS: Use 'restrict' in prototypes
  envz_add.3: SYNOPSIS: Use 'restrict' in prototypes
  fgetc.3: SYNOPSIS: Use 'restrict' in prototypes
  fgetws.3: SYNOPSIS: Use 'restrict' in prototypes
  fopencookie.3: SYNOPSIS: Use 'restrict' in prototypes
  fopen.3: SYNOPSIS: Use 'restrict' in prototypes
  fputws.3: SYNOPSIS: Use 'restrict' in prototypes
  fread.3: SYNOPSIS: Use 'restrict' in prototypes
  fseek.3: SYNOPSIS: Use 'restrict' in prototypes

 man3/argz_add.3    | 41 +++++++++++++++++++++++------------------
 man3/asprintf.3    |  5 +++--
 man3/crypt.3       |  2 +-
 man3/ctime.3       | 16 ++++++++++++----
 man3/dlinfo.3      |  3 ++-
 man3/dlsym.3       |  5 +++--
 man3/drand48_r.3   | 22 ++++++++++++++--------
 man3/ecvt.3        |  6 ++++--
 man3/ecvt_r.3      | 18 ++++++++++--------
 man3/envz_add.3    | 25 +++++++++++++------------
 man3/fgetc.3       |  2 +-
 man3/fgetws.3      |  3 ++-
 man3/fopen.3       |  7 +++++--
 man3/fopencookie.3 |  2 +-
 man3/fputws.3      |  2 +-
 man3/fread.3       |  9 +++++----
 man3/fseek.3       |  2 +-
 man3/memccpy.3     |  3 ++-
 man3/memcpy.3      |  3 ++-
 19 files changed, 105 insertions(+), 71 deletions(-)

-- 
2.30.1.721.g45526154a5

[PATCH 01/20] argz_add.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Glibc uses 'restrict' for some of the functions in this page:

=============================  argz_add
string/argz.h:76:
error_t argz_add (char **restrict argz,
                         size_t *restrict argz_len,
                         const char *restrict str) THROW;
=============================  argz_add_sep
string/argz.h:82:
error_t argz_add_sep (char **restrict argz,
                             size_t *restrict argz_len,
                             const char *restrict string, int delim)
     THROW;
=============================  argz_append
string/argz.h:70:
error_t argz_append (char **restrict argz,
                            size_t *restrict argz_len,
                            const char *restrict buf, size_t buf_len)
     THROW;
=============================  argz_count
string/argz.h:54:
size_t argz_count (const char *argz, size_t len)
     THROW attribute_pure__;
=============================  argz_create
string/argz.h:40:
error_t argz_create (char *const argv[], char **restrict argz,
                            size_t *restrict len) THROW;
=============================  argz_create_sep
string/argz.h:47:
error_t argz_create_sep (const char *restrict string,
                                int sep, char **restrict argz,
                                size_t *restrict len) THROW;
=============================  argz_delete
string/argz.h:88:
void argz_delete (char **restrict argz,
                         size_t *restrict argz_len,
                         char *restrict entry) THROW;
=============================  argz_extract
string/argz.h:61:
void argz_extract (const char *restrict argz, size_t len,
                          char **restrict argv) THROW;
=============================  argz_insert
string/argz.h:98:
error_t argz_insert (char **restrict argz,
                            size_t *restrict argz_len,
                            char *restrict before,
                            const char *restrict entry) THROW;
=============================  argz_next
string/argz.h:128:
char *argz_next (const char *restrict argz, size_t argz_len,
                        const char *restrict entry) THROW;
=============================  argz_replace
string/argz.h:106:
error_t argz_replace (char **restrict argz,
                             size_t *restrict argz_len,
                             const char *restrict str,
                             const char *restrict with,
                             unsigned int *restrict replace_count);
=============================  argz_stringify
string/argz.h:67:
void argz_stringify (char *argz, size_t len, int sep) THROW;

Let's use it here too.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/argz_add.3 | 41 +++++++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/man3/argz_add.3 b/man3/argz_add.3
index c326f9cdb..a6fbde95b 100644
--- a/man3/argz_add.3
+++ b/man3/argz_add.3
@@ -16,35 +16,40 @@ argz_next, argz_replace, argz_stringify \- functions to handle an argz list
 .nf
 .B "#include <argz.h>"
 .PP
-.BI "error_t argz_add(char **" argz ", size_t *" argz_len \
-", const char *" str );
+.BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len ",
+.BI "                const char *restrict " str );
 .PP
-.BI "error_t argz_add_sep(char **" argz ", size_t *" argz_len ,
-.BI "                     const char *" str ", int " delim );
+.BI "error_t argz_add_sep(char **restrict " argz \
+", size_t *restrict " argz_len ,
+.BI "                const char *restrict " str ", int " delim );
 .PP
-.BI "error_t argz_append(char **" argz ", size_t *" argz_len ,
-.BI "                     const char *" buf ", size_t " buf_len );
+.BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len ,
+.BI "                const char *restrict " buf ", size_t " buf_len );
 .PP
 .BI "size_t argz_count(const char *" argz ", size_t " argz_len );
 .PP
-.BI "error_t argz_create(char * const " argv "[], char **" argz ,
-.BI "                     size_t *" argz_len );
+.BI "error_t argz_create(char *const " argv "[], char **restrict " argz ,
+.BI "                size_t *restrict " argz_len );
 .PP
-.BI "error_t argz_create_sep(const char *" str ", int " sep ", char **" argz ,
-.BI "                     size_t *" argz_len );
+.BI "error_t argz_create_sep(const char *restrict " str ", int " sep ,
+.BI "                char **restrict " argz ", size_t *restrict " argz_len );
 .PP
-.BI "void argz_delete(char **" argz ", size_t *" argz_len ", char *" entry );
+.BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len ,
+.BI "                char *restrict " entry );
 .PP
-.BI "void argz_extract(const char *" argz ", size_t " argz_len ", char **" argv );
+.BI "void argz_extract(const char *restrict " argz ", size_t " argz_len ,
+.BI "                char **restrict " argv );
 .PP
-.BI "error_t argz_insert(char **" argz ", size_t *" argz_len ", char *" before ,
-.BI "                     const char *" entry );
+.BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len ,
+.BI "                char *restrict " before ", const char *restrict " entry );
 .PP
-.BI "char *argz_next(const char *" argz ", size_t " argz_len ", const char *" entry );
+.BI "char *argz_next(const char *restrict " argz ", size_t " argz_len ,
+.BI "                const char *restrict " entry );
 .PP
-.BI "error_t argz_replace(char **" argz ", size_t *" argz_len \
-", const char *" str ,
-.BI "                     const char *" with ", unsigned int *" replace_count );
+.BI "error_t argz_replace(char **restrict " argz \
+", size_t *restrict " argz_len ,
+.BI "                const char *restrict " str ", const char *restrict " with ,
+.BI "                unsigned int *restrict " replace_count );
 .PP
 .BI "void argz_stringify(char *" argz ", size_t " len ", int " sep );
 .fi
-- 
2.30.1.721.g45526154a5

[PATCH 02/20] asprintf.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Glibc uses 'restrict' for [v]asprintf().
Let's use it here too.

......

.../glibc$ grep_glibc_prototype asprintf
libio/stdio.h:372:
extern int asprintf (char **__restrict __ptr,
		     const char *__restrict __fmt, ...)
     __THROWNL __attribute__ ((__format__ (__printf__, 2, 3))) __wur;
.../glibc$ grep_glibc_prototype vasprintf
libio/stdio.h:366:
extern int vasprintf (char **__restrict __ptr, const char *__restrict __f,
		      __gnuc_va_list __arg)
     __THROWNL __attribute__ ((__format__ (__printf__, 2, 0))) __wur;
.../glibc$

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/asprintf.3 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/man3/asprintf.3 b/man3/asprintf.3
index b682a7793..d09c2437e 100644
--- a/man3/asprintf.3
+++ b/man3/asprintf.3
@@ -32,8 +32,9 @@ asprintf, vasprintf \- print to allocated string
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 .B #include <stdio.h>
 .PP
-.BI "int asprintf(char **" strp ", const char *" fmt ", ...);"
-.BI "int vasprintf(char **" strp ", const char *" fmt ", va_list " ap );
+.BI "int asprintf(char **restrict " strp ", const char *restrict " fmt ", ...);"
+.BI "int vasprintf(char **restrict " strp ", const char *restrict " fmt ,
+.BI "              va_list " ap );
 .fi
 .SH DESCRIPTION
 The functions
-- 
2.30.1.721.g45526154a5

[PATCH 03/20] memccpy.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

POSIX specifies that the parameters of memccpy()
shall be 'restrict'.  Glibc uses 'restrict' too.
Let's use it here too.

......

.../glibc$ grep_glibc_prototype memccpy
string/string.h:54:
extern void *memccpy (void *__restrict __dest, const void *__restrict __src,
		      int __c, size_t __n)
    __THROW __nonnull ((1, 2)) __attr_access ((__write_only__, 1, 4));
.../glibc$

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/memccpy.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man3/memccpy.3 b/man3/memccpy.3
index bea746f7f..ed28503c0 100644
--- a/man3/memccpy.3
+++ b/man3/memccpy.3
@@ -34,7 +34,8 @@ memccpy \- copy memory area
 .nf
 .B #include <string.h>
 .PP
-.BI "void *memccpy(void *" dest ", const void *" src ", int " c ", size_t " n );
+.BI "void *memccpy(void *restrict " dest ", const void *restrict " src ,
+.BI "              int " c ", size_t " n );
 .fi
 .SH DESCRIPTION
 The
-- 
2.30.1.721.g45526154a5

[PATCH 04/20] memcpy.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

POSIX specifies that the parameters of memcpy()
shall be 'restrict'.  Glibc uses 'restrict' too.
Let's use it here too.

It's especially important in memcpy(),
as it's been a historical source of bugs.

......

.../glibc$ grep_glibc_prototype memcpy
posix/regex_internal.h:746:
{
  memcpy (dest, src, sizeof (bitset_t));
string/string.h:43:
extern void *memcpy (void *__restrict __dest, const void *__restrict __src,
		     size_t __n) __THROW __nonnull ((1, 2));
.../glibc$

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/memcpy.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man3/memcpy.3 b/man3/memcpy.3
index 523465ae8..369f9f9d0 100644
--- a/man3/memcpy.3
+++ b/man3/memcpy.3
@@ -35,7 +35,8 @@ memcpy \- copy memory area
 .nf
 .B #include <string.h>
 .PP
-.BI "void *memcpy(void *" dest ", const void *" src ", size_t " n );
+.BI "void *memcpy(void *restrict " dest ", const void *restrict " src \
+", size_t " n );
 .fi
 .SH DESCRIPTION
 The
-- 
2.30.1.721.g45526154a5

[PATCH 05/20] crypt.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Glibc uses 'restrict' for the 3rd parameter of crypt_r().
Let's use it here too.

......

.../glibc$ grep_glibc_prototype crypt_t
crypt/crypt.h:63:
extern char *crypt_r (const char *__phrase, const char *__salt,
		      struct crypt_data * __restrict __data)
     __THROW __nonnull ((1, 2, 3));
.../glibc$

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/crypt.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/crypt.3 b/man3/crypt.3
index a73c8facc..7a9b3e9ad 100644
--- a/man3/crypt.3
+++ b/man3/crypt.3
@@ -45,7 +45,7 @@ crypt, crypt_r \- password and data encryption
 .B #include <crypt.h>
 .PP
 .BI "char *crypt_r(const char *" key ", const char *" salt ,
-.BI "              struct crypt_data *" data );
+.BI "              struct crypt_data *restrict " data );
 .fi
 .PP
 Link with \fI\-lcrypt\fP.
-- 
2.30.1.721.g45526154a5

[PATCH 06/20] ctime.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

POSIX specifies that the parameters of asctime_r(), gmtime_r(),
and localtime_r() shall be restrict.  Glibc uses 'restrict' too.
Let's use it here too.

ctime_r will be covered in a future commit,
as the glibc implementation differs from POSIX.

......

=============================  asctime
timezone/private.h:501:
char *asctime(struct tm const *);
time/time.h:139:
char *asctime (const struct tm *tp) THROW;
=============================  asctime_r
timezone/private.h:502:
char *asctime_r(struct tm const *restrict, char *restrict);
timezone/private.h:522:
char *asctime_r(struct tm const *restrict, char *restrict);
timezone/private.h:711:
char *asctime_r(struct tm const *, char *);
time/time.h:149:
char *asctime_r (const struct tm *restrict tp,
                        char *restrict buf) THROW;
=============================  ctime
timezone/private.h:503:
char *ctime(time_t const *);
time/time.h:142:
char *ctime (const time_t *timer) THROW;
=============================  ctime_r
timezone/private.h:504:
char *ctime_r(time_t const *, char *);
timezone/private.h:712:
char *ctime_r(time_t const *, char *);
time/time.h:153:
char *ctime_r (const time_t *restrict timer,
                      char *restrict buf) THROW;
=============================  gmtime
timezone/private.h:512:
struct tm *gmtime(time_t const *);
time/time.h:119:
struct tm *gmtime (const time_t *timer) THROW;
=============================  gmtime_r
timezone/private.h:513:
struct tm *gmtime_r(time_t const *restrict, struct tm *restrict);
time/time.h:128:
struct tm *gmtime_r (const time_t *restrict timer,
                            struct tm *restrict tp) THROW;
=============================  localtime
timezone/private.h:514:
struct tm *localtime(time_t const *);
time/time.h:123:
struct tm *localtime (const time_t *timer) THROW;
=============================  localtime_r
timezone/private.h:515:
struct tm *localtime_r(time_t const *restrict, struct tm *restrict);
time/time.h:133:
struct tm *localtime_r (const time_t *restrict timer,
                               struct tm *restrict tp) THROW;
=============================  mktime
timezone/private.h:516:
time_t mktime(struct tm *);
time/time.h:82:
time_t mktime (struct tm *tp) THROW;

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/ctime.3 | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/man3/ctime.3 b/man3/ctime.3
index 9178c809a..cd0ccc98d 100644
--- a/man3/ctime.3
+++ b/man3/ctime.3
@@ -41,16 +41,18 @@ localtime_r \- transform date and time to broken-down time or ASCII
 .B #include <time.h>
 .PP
 .BI "char *asctime(const struct tm *" tm );
-.BI "char *asctime_r(const struct tm *" tm ", char *" buf );
+.BI "char *asctime_r(const struct tm *restrict " tm ", char *restrict " buf );
 .PP
 .BI "char *ctime(const time_t *" timep );
 .BI "char *ctime_r(const time_t *" timep ", char *" buf );
 .PP
 .BI "struct tm *gmtime(const time_t *" timep );
-.BI "struct tm *gmtime_r(const time_t *" timep ", struct tm *" result );
+.BI "struct tm *gmtime_r(const time_t *restrict " timep ,
+.BI "                    struct tm *restrict " result );
 .PP
 .BI "struct tm *localtime(const time_t *" timep );
-.BI "struct tm *localtime_r(const time_t *" timep ", struct tm *" result );
+.BI "struct tm *localtime_r(const time_t *restrict " timep ,
+.BI "                    struct tm *restrict " result );
 .PP
 .BI "time_t mktime(struct tm *" tm );
 .fi
-- 
2.30.1.721.g45526154a5

[PATCH 07/20] ctime.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

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

......

.../glibc$ grep_glibc_prototype ctime_r
timezone/private.h:504:
char *ctime_r(time_t const *, char *);
timezone/private.h:712:
char *ctime_r(time_t const *, char *);
time/time.h:153:
extern char *ctime_r (const time_t *__restrict __timer,
		      char *__restrict __buf) __THROW;
.../glibc$

Cc: <libc-alpha@sourceware.org>
Cc: Ulrich Drepper <drepper@redhat.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/ctime.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/man3/ctime.3 b/man3/ctime.3
index cd0ccc98d..7e4baa390 100644
--- a/man3/ctime.3
+++ b/man3/ctime.3
@@ -44,7 +44,7 @@ localtime_r \- transform date and time to broken-down time or ASCII
 .BI "char *asctime_r(const struct tm *restrict " tm ", char *restrict " buf );
 .PP
 .BI "char *ctime(const time_t *" timep );
-.BI "char *ctime_r(const time_t *" timep ", char *" buf );
+.BI "char *ctime_r(const time_t *restrict " timep ", char *restrict " buf );
 .PP
 .BI "struct tm *gmtime(const time_t *" timep );
 .BI "struct tm *gmtime_r(const time_t *restrict " timep ,
@@ -381,6 +381,12 @@ as obsolete,
 recommending the use of
 .BR strftime (3)
 instead.
+.PP
+POSIX doesn't specify the parameters of
+.BR ctime_r ()
+to be
+.IR restrict ;
+that is specific to glibc.
 .SH NOTES
 The four functions
 .BR asctime (),
-- 
2.30.1.721.g45526154a5

[PATCH 08/20] dlinfo.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Glibc uses 'restrict' for dlinfo().
Let's use it here too.

......

.../glibc$ grep_glibc_prototype dlinfo
dlfcn/dlfcn.h:123:
extern int dlinfo (void *__restrict __handle,
		   int __request, void *__restrict __arg)
     __THROW __nonnull ((1, 3));
.../glibc$

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/dlinfo.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man3/dlinfo.3 b/man3/dlinfo.3
index 194f106ad..b75242f13 100644
--- a/man3/dlinfo.3
+++ b/man3/dlinfo.3
@@ -31,7 +31,8 @@ dlinfo \- obtain information about a dynamically loaded object
 .B #include <link.h>
 .B #include <dlfcn.h>
 .PP
-.BR "int dlinfo(void *" handle ", int " request ", void *" info );
+.BR "int dlinfo(void *restrict " handle ", int " request \
+", void *restrict " info );
 .PP
 Link with \fI\-ldl\fP.
 .fi
-- 
2.30.1.721.g45526154a5

[PATCH 09/20] dlsym.3: SYNOPSIS: Use 'restrict' in prototypes; add missing 'const' too

[Alejandro Colomar]

POSIX specifies that the parameters of dlsym()
shall be 'restrict'.  Glibc uses 'restrict' too.
Let's use it here too.

The glibc specific dlvsym() also uses 'restrict'.
Its 2nd and 3rd parameters are 'const' too.

Fix the prototypes to add these qualifiers.

......

.../glibc$ grep_glibc_prototype dlsym
dlfcn/dlfcn.h:64:
extern void *dlsym (void *__restrict __handle,
		    const char *__restrict __name) __THROW __nonnull ((2));
.../glibc$ grep_glibc_prototype dlvsym
dlfcn/dlfcn.h:73:
extern void *dlvsym (void *__restrict __handle,
		     const char *__restrict __name,
		     const char *__restrict __version)
     __THROW __nonnull ((2, 3));
.../glibc$

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/dlsym.3 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/man3/dlsym.3 b/man3/dlsym.3
index ed3804963..d6a73fb5b 100644
--- a/man3/dlsym.3
+++ b/man3/dlsym.3
@@ -29,12 +29,13 @@ dlsym, dlvsym \- obtain address of a symbol in a shared object or executable
 .nf
 .B #include <dlfcn.h>
 .PP
-.BI "void *dlsym(void *" handle ", const char *" symbol );
+.BI "void *dlsym(void *restrict " handle ", const char *restrict " symbol );
 .PP
 .B #define _GNU_SOURCE
 .B #include <dlfcn.h>
 .PP
-.BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version );
+.BI "void *dlvsym(void *restrict " handle ", const char *restrict " symbol ,
+.BI "             const char *restrict " version );
 .PP
 Link with \fI\-ldl\fP.
 .fi
-- 
2.30.1.721.g45526154a5

[PATCH 10/20] drand48_r.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Glibc uses 'restrict' for some of the functions in this page:

=============================  drand48_r
stdlib/stdlib.h:501:
int drand48_r (struct drand48_data *restrict buffer,
                      double *restrict result) THROW nonnull ((1, 2));
=============================  erand48_r
stdlib/stdlib.h:503:
int erand48_r (unsigned short int xsubi[3],
                      struct drand48_data *restrict buffer,
                      double *restrict result) THROW nonnull ((1, 2));
=============================  lrand48_r
stdlib/stdlib.h:508:
int lrand48_r (struct drand48_data *restrict buffer,
                      long int *restrict result)
     THROW nonnull ((1, 2));
=============================  nrand48_r
stdlib/stdlib.h:511:
int nrand48_r (unsigned short int xsubi[3],
                      struct drand48_data *restrict buffer,
                      long int *restrict result)
     THROW nonnull ((1, 2));
=============================  mrand48_r
stdlib/stdlib.h:517:
int mrand48_r (struct drand48_data *restrict buffer,
                      long int *restrict result)
     THROW nonnull ((1, 2));
=============================  jrand48_r
stdlib/stdlib.h:520:
int jrand48_r (unsigned short int xsubi[3],
                      struct drand48_data *restrict buffer,
                      long int *restrict result)
     THROW nonnull ((1, 2));
=============================  srand48_r
stdlib/stdlib.h:526:
int srand48_r (long int seedval, struct drand48_data *buffer)
     THROW nonnull ((2));
=============================  seed48_r
stdlib/stdlib.h:529:
int seed48_r (unsigned short int seed16v[3],
                     struct drand48_data *buffer) THROW nonnull ((1, 2));
=============================  lcong48_r
stdlib/stdlib.h:532:
int lcong48_r (unsigned short int param[7],
                      struct drand48_data *buffer)
     THROW nonnull ((1, 2));

Let's use it here too.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/drand48_r.3 | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/man3/drand48_r.3 b/man3/drand48_r.3
index b2209c5b8..9203498f4 100644
--- a/man3/drand48_r.3
+++ b/man3/drand48_r.3
@@ -33,21 +33,27 @@ srand48_r, seed48_r, lcong48_r
 .nf
 .B #include <stdlib.h>
 .PP
-.BI "int drand48_r(struct drand48_data *" buffer ", double *" result );
+.BI "int drand48_r(struct drand48_data *restrict " buffer ,
+.BI "              double *restrict " result );
 .BI "int erand48_r(unsigned short " xsubi [3] ","
-.BI "              struct drand48_data *"buffer ", double *" result ");"
+.BI "              struct drand48_data *restrict "buffer ,
+.BI "              double *restrict " result ");"
 .PP
-.BI "int lrand48_r(struct drand48_data *" buffer ", long *" result );
+.BI "int lrand48_r(struct drand48_data *restrict " buffer ,
+.BI "              long *restrict " result );
 .BI "int nrand48_r(unsigned short " xsubi[3] ","
-.BI "              struct drand48_data *"buffer ", long *" result ");"
+.BI "              struct drand48_data *restrict "buffer ,
+.BI "              long *restrict " result ");"
 .PP
-.BI "int mrand48_r(struct drand48_data *" buffer ",long *" result ");"
+.BI "int mrand48_r(struct drand48_data *restrict " buffer ,
+.BI "              long *restrict " result ");"
 .BI "int jrand48_r(unsigned short " xsubi[3] ","
-.BI "              struct drand48_data *" buffer ", long *" result ");"
+.BI "              struct drand48_data *restrict " buffer ,
+.BI "              long *restrict " result ");"
 .PP
 .BI "int srand48_r(long int " seedval ", struct drand48_data *" buffer ");"
-.BI "int seed48_r(unsigned short " seed16v[3] ", struct drand48_data *" buffer ");"
-.BI "int lcong48_r(unsigned short " param[7] ", struct drand48_data *" buffer ");"
+.BI "int seed48_r(unsigned short " seed16v[3] ", struct drand48_data *" buffer );
+.BI "int lcong48_r(unsigned short " param[7] ", struct drand48_data *" buffer );
 .fi
 .PP
 .RS -4
-- 
2.30.1.721.g45526154a5

[PATCH 11/20] ecvt_r.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Glibc uses 'restrict' for these functions

=============================  ecvt_r
stdlib/stdlib.h:902:
int ecvt_r (double value, int ndigit, int *restrict decpt,
                   int *restrict sign, char *restrict buf,
                   size_t len) THROW nonnull ((3, 4, 5));
=============================  fcvt_r
stdlib/stdlib.h:905:
int fcvt_r (double value, int ndigit, int *restrict decpt,
                   int *restrict sign, char *restrict buf,
                   size_t len) THROW nonnull ((3, 4, 5));
=============================  qecvt_r
stdlib/stdlib.h:909:
int qecvt_r (long double value, int ndigit,
                    int *restrict decpt, int *restrict sign,
                    char *restrict buf, size_t len)
     THROW nonnull ((3, 4, 5));
=============================  qfcvt_r
stdlib/stdlib.h:913:
int qfcvt_r (long double value, int ndigit,
                    int *restrict decpt, int *restrict sign,
                    char *restrict buf, size_t len)
     THROW nonnull ((3, 4, 5));

Let's use it here too.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/ecvt_r.3 | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/man3/ecvt_r.3 b/man3/ecvt_r.3
index f56197782..05689c8fc 100644
--- a/man3/ecvt_r.3
+++ b/man3/ecvt_r.3
@@ -34,15 +34,17 @@ ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string
 .nf
 .B #include <stdlib.h>
 .PP
-.BI "int ecvt_r(double " number ", int " ndigits ", int *" decpt ,
-.BI "           int *" sign ", char *" buf ", size_t " len );
-.BI "int fcvt_r(double " number ", int " ndigits ", int *" decpt ,
-.BI "           int *" sign ", char *" buf ", size_t " len );
+.BI "int ecvt_r(double " number ", int " ndigits ", int *restrict " decpt ,
+.BI "           int *restrict " sign ", char *restrict " buf ", size_t " len );
+.BI "int fcvt_r(double " number ", int " ndigits ", int *restrict " decpt ,
+.BI "           int *restrict " sign ", char *restrict " buf ", size_t " len );
 .PP
-.BI "int qecvt_r(long double " number ", int " ndigits ", int *" decpt ,
-.BI "           int *" sign ", char *" buf ", size_t " len );
-.BI "int qfcvt_r(long double " number ", int " ndigits ", int *" decpt ,
-.BI "           int *" sign ", char *" buf ", size_t " len );
+.BI "int qecvt_r(long double " number ", int " ndigits \
+", int *restrict " decpt ,
+.BI "           int *restrict " sign ", char *restrict " buf ", size_t " len );
+.BI "int qfcvt_r(long double " number ", int " ndigits \
+", int *restrict " decpt ,
+.BI "           int *restrict " sign ", char *restrict " buf ", size_t " len );
 .fi
 .PP
 .RS -4
-- 
2.30.1.721.g45526154a5

[PATCH 12/20] ecvt.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

POSIX.1-2001 and glibc use 'restrict' for these functions.
Let's use it here too.

glibc:
=============================  ecvt
stdlib/stdlib.h:872:
char *ecvt (double value, int ndigit, int *restrict decpt,
                   int *restrict sign) THROW nonnull ((3, 4)) wur;
=============================  fcvt
stdlib/stdlib.h:878:
char *fcvt (double value, int ndigit, int *restrict decpt,
                   int *restrict sign) THROW nonnull ((3, 4)) wur;

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/ecvt.3 | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/man3/ecvt.3 b/man3/ecvt.3
index ec4a4b6fc..8d53b1287 100644
--- a/man3/ecvt.3
+++ b/man3/ecvt.3
@@ -36,8 +36,10 @@ ecvt, fcvt \- convert a floating-point number to a string
 .nf
 .B #include <stdlib.h>
 .PP
-.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt ", int *" sign );
-.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.BI "char *ecvt(double " number ", int " ndigits ", int *restrict " decpt ,
+.BI "           int *restrict " sign );
+.BI "char *fcvt(double " number ", int " ndigits ", int *restrict " decpt ,
+.BI "           int *restrict " sign );
 .fi
 .PP
 .RS -4
-- 
2.30.1.721.g45526154a5

[PATCH 13/20] envz_add.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Glibc uses 'restrict' for these functions
Let's use it here too.

=============================  envz_add
string/envz.h:49:
error_t envz_add (char **restrict envz,
                         size_t *restrict envz_len,
                         const char *restrict name,
                         const char *restrict value) THROW;
=============================  envz_entry
string/envz.h:33:
char *envz_entry (const char *restrict envz, size_t envz_len,
                         const char *restrict name)
     THROW attribute_pure__;
=============================  envz_get
string/envz.h:39:
char *envz_get (const char *restrict envz, size_t envz_len,
                       const char *restrict name)
     THROW attribute_pure__;
=============================  envz_merge
string/envz.h:57:
error_t envz_merge (char **restrict envz,
                           size_t *restrict envz_len,
                           const char *restrict envz2,
                           size_t envz2_len, int override) THROW;
=============================  envz_remove
string/envz.h:63:
void envz_remove (char **restrict envz,
                         size_t *restrict envz_len,
                         const char *restrict name) THROW;
=============================  envz_strip
string/envz.h:68:
void envz_strip (char **restrict envz,
                        size_t *restrict envz_len) THROW;

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/envz_add.3 | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/man3/envz_add.3 b/man3/envz_add.3
index 23a7a1fe1..cfb56b478 100644
--- a/man3/envz_add.3
+++ b/man3/envz_add.3
@@ -15,23 +15,24 @@ envz_remove, envz_strip \- environment string support
 .nf
 .B "#include <envz.h>"
 .PP
-.BI "error_t envz_add(char **" envz ", size_t *" envz_len ,
-.BI "                 const char *" name ", const char *" value );
+.BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len ,
+.BI "               const char *restrict " name \
+", const char *restrict " value );
 .PP
-.BI "char *envz_entry(const char *" envz ", size_t " envz_len \
-", const char *" name );
+.BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len ,
+.BI "               const char *restrict " name );
 .PP
-.BI "char *envz_get(const char *" envz ", size_t " envz_len \
-", const char *" name );
+.BI "char *envz_get(const char *restrict " envz ", size_t " envz_len ,
+.BI "               const char *restrict " name );
 .PP
-.BI "error_t envz_merge(char **" envz ", size_t *" envz_len ,
-.BI "                 const char *" envz2 ", size_t " envz2_len \
-", int " override );
+.BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len ,
+.BI "               const char *restrict " envz2 ", size_t " envz2_len ,
+.BI "               int " override );
 .PP
-.BI "void envz_remove(char **" envz ", size_t *" envz_len \
-", const char *" name );
+.BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len ,
+.BI "               const char *restrict " name );
 .PP
-.BI "void envz_strip(char **" envz ", size_t *" envz_len );
+.BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len );
 .fi
 .SH DESCRIPTION
 These functions are glibc-specific.
-- 
2.30.1.721.g45526154a5

[PATCH 14/20] fgetc.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Both POSIX and glibc use 'restrict' in fgets().
Let's use it here too.

glibc:
libio/stdio.h:568:
char *fgets (char *restrict s, int n, FILE *restrict stream)
     wur attr_access ((write_only__, 1, 2));

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/fgetc.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/fgetc.3 b/man3/fgetc.3
index 5e0ded168..1aa419935 100644
--- a/man3/fgetc.3
+++ b/man3/fgetc.3
@@ -35,7 +35,7 @@ fgetc, fgets, getc, getchar, ungetc \- input of characters and strings
 .BI "int getc(FILE *" stream );
 .B "int getchar(void);"
 .PP
-.BI "char *fgets(char *" "s" ", int " "size" ", FILE *" "stream" );
+.BI "char *fgets(char *restrict " s ", int " size ", FILE *restrict " stream );
 .PP
 .BI "int ungetc(int " c ", FILE *" stream );
 .fi
-- 
2.30.1.721.g45526154a5

[PATCH 15/20] fgetws.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Both POSIX and glibc use 'restrict' for fgetws().
Let's use it here too.

glibc:
wcsmbs/wchar.h:758:
wchar_t *fgetws (wchar_t *restrict ws, int n,
                        FILE *restrict stream);

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/fgetws.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man3/fgetws.3 b/man3/fgetws.3
index 4ce0fe79b..652507937 100644
--- a/man3/fgetws.3
+++ b/man3/fgetws.3
@@ -22,7 +22,8 @@ fgetws \- read a wide-character string from a FILE stream
 .nf
 .B #include <wchar.h>
 .PP
-.BI "wchar_t *fgetws(wchar_t *" ws ", int " n ", FILE *" stream );
+.BI "wchar_t *fgetws(wchar_t *restrict " ws ", int " n \
+", FILE *restrict " stream );
 .fi
 .SH DESCRIPTION
 The
-- 
2.30.1.721.g45526154a5

[PATCH 16/20] fopencookie.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

glibc uses 'restrict' for fopencookie().
Let's use it here too.

glibc:
libio/stdio.h:285:
FILE *fopencookie (void *restrict magic_cookie,
                          const char *restrict modes,
                          cookie_io_functions_t io_funcs) THROW wur;

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/fopencookie.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/fopencookie.3 b/man3/fopencookie.3
index 35b01493f..07736e3b2 100644
--- a/man3/fopencookie.3
+++ b/man3/fopencookie.3
@@ -31,7 +31,7 @@ fopencookie \- opening a custom stream
 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 .B #include <stdio.h>
 .PP
-.BI "FILE *fopencookie(void *" cookie ", const char *" mode ,
+.BI "FILE *fopencookie(void *restrict " cookie ", const char *restrict " mode ,
 .BI "                  cookie_io_functions_t " io_funcs );
 .fi
 .SH DESCRIPTION
-- 
2.30.1.721.g45526154a5

[PATCH 17/20] fopen.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Both POSIX and glibc use 'restrict' for some of these functions.
Let's use it here too.

glibc:
=============================  fopen
libio/stdio.h:246:
FILE *fopen (const char *restrict filename,
                    const char *restrict modes) wur;
=============================  fdopen
libio/stdio.h:279:
FILE *fdopen (int fd, const char *modes) THROW wur;
=============================  freopen
libio/stdio.h:252:
FILE *freopen (const char *restrict filename,
                      const char *restrict modes,
                      FILE *restrict stream) wur;

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/fopen.3 | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/man3/fopen.3 b/man3/fopen.3
index 65ca99f75..d7af3fe96 100644
--- a/man3/fopen.3
+++ b/man3/fopen.3
@@ -48,9 +48,12 @@ fopen, fdopen, freopen \- stream open functions
 .nf
 .B #include <stdio.h>
 .PP
-.BI "FILE *fopen(const char *" pathname ", const char *" mode );
+.BI "FILE *fopen(const char *restrict " pathname \
+", const char *restrict " mode );
 .BI "FILE *fdopen(int " fd ", const char *" mode );
-.BI "FILE *freopen(const char *" pathname ", const char *" mode ", FILE *" stream );
+.BI "FILE *freopen(const char *restrict " pathname \
+", const char *restrict " mode ,
+.BI "              FILE *restrict " stream );
 .fi
 .PP
 .RS -4
-- 
2.30.1.721.g45526154a5

[PATCH 18/20] fputws.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Both POSIX and glibc use 'restrict' in fputws().
Let's use it here too.

glibc:
=============================  fputws
wcsmbs/wchar.h:765:
int fputws (const wchar_t *restrict ws,
                   FILE *restrict stream);

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/fputws.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/fputws.3 b/man3/fputws.3
index 604c96038..7269353f7 100644
--- a/man3/fputws.3
+++ b/man3/fputws.3
@@ -20,7 +20,7 @@ fputws \- write a wide-character string to a FILE stream
 .nf
 .B #include <wchar.h>
 .PP
-.BI "int fputws(const wchar_t *" ws ", FILE *" stream );
+.BI "int fputws(const wchar_t *restrict " ws ", FILE *restrict " stream );
 .fi
 .SH DESCRIPTION
 The
-- 
2.30.1.721.g45526154a5

[PATCH 19/20] fread.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Both POSIX and glibc use 'restrict' in these functions.
Let's use it here too.

glibc:
=============================  fread
libio/stdio.h:651:
size_t fread (void *restrict ptr, size_t size,
                     size_t n, FILE *restrict stream) wur;
=============================  fwrite
libio/stdio.h:657:
size_t fwrite (const void *restrict ptr, size_t size,
                      size_t n, FILE *restrict s);

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/fread.3 | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/man3/fread.3 b/man3/fread.3
index e3f34b7d1..2b59916c7 100644
--- a/man3/fread.3
+++ b/man3/fread.3
@@ -50,10 +50,11 @@ fread, fwrite \- binary stream input/output
 .nf
 .B #include <stdio.h>
 .PP
-.BI "size_t fread(void *" ptr ", size_t " size ", size_t " nmemb \
-", FILE *" stream );
-.BI "size_t fwrite(const void *" ptr ", size_t " size ", size_t " nmemb ,
-.BI "              FILE *" stream );
+.BI "size_t fread(void *restrict " ptr ", size_t " size ", size_t " nmemb ,
+.BI "             FILE *restrict " stream );
+.BI "size_t fwrite(const void *restrict " ptr ", size_t " size \
+", size_t " nmemb ,
+.BI "             FILE *restrict " stream );
 .fi
 .SH DESCRIPTION
 The function
-- 
2.30.1.721.g45526154a5

[PATCH 20/20] fseek.3: SYNOPSIS: Use 'restrict' in prototypes

[Alejandro Colomar]

Both POSIX and glibc use 'restrict' in fgetpos().
Let's use it here too.

glibc:
=============================  fgetpos
libio/stdio.h:736:
int fgetpos (FILE *restrict stream, fpos_t *restrict pos);

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man3/fseek.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/fseek.3 b/man3/fseek.3
index e8ae7d289..e7d6ed464 100644
--- a/man3/fseek.3
+++ b/man3/fseek.3
@@ -51,7 +51,7 @@ fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
 .PP
 .BI "void rewind(FILE *" stream );
 .PP
-.BI "int fgetpos(FILE *" stream ", fpos_t *" pos );
+.BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos );
 .BI "int fsetpos(FILE *" stream ", const fpos_t *" pos );
 .fi
 .SH DESCRIPTION
-- 
2.30.1.721.g45526154a5

Re: [PATCH 00/20] man3: SYNOPSIS: Use 'restrict' in prototypes (batch 1)

[Michael Kerrisk (man-pages)]

Hello Alex,

On 2/24/21 3:42 PM, Alejandro Colomar wrote:
> Hi Michael,
> 
> This are the first pages of man3 with 'restrict'.
> I'm sending you these already, becuase otherwise I'd accumulate
> too many patches in the end.

Thanks. I have applied all of these.

> I have fixed from the first page until ftw.3.
> 
> Spin off:
> 	I found different terms for parameters that refer to a same thing
> 	in different functions (usually a '[const] char *'):
> 	 - filename
> 	 - file
> 	 - path
> 	 - pathname
> 	 - Maybe others; I don't know
> 
> 	For 'FILE *' we have more or less the same,
> 	although this one is much more standard (>90% use 'stream'):
> 	 - stream
> 	 - streamp
> 	 - s
> 	 - fp
> 	 - file
> 	 - filehandle
> 	 - A few others in specific cases
> 
> 	What would you do about it?
I think it would be best to start a new thread for this...

Thanks,

Michael

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