[PATCH] copy_file_range.2: SYNOPSIS: Fix prototype parameter types

[PATCH] copy_file_range.2: SYNOPSIS: Fix prototype parameter types

[Alejandro Colomar]

Glibc uses 'off64_t' instead of 'loff_t'.

This patch doesn't change the types in the code example,
because it uses the Linux syscall, and not the glibc wrapper.

......

$ syscall='copy_file_range';
$ ret='ssize_t';
$ find glibc/ -type f -name '*.h' \
  |xargs pcregrep -Mn "(?s)^[\w\s]*${ret}\s*${syscall}\s*\(.*?;";
glibc/posix/unistd.h:1121:
ssize_t copy_file_range (int __infd, __off64_t *__pinoff,
			 int __outfd, __off64_t *__poutoff,
			 size_t __length, unsigned int __flags);

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

diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2
index 1692aa44a..6f4708c4b 100644
--- a/man2/copy_file_range.2
+++ b/man2/copy_file_range.2
@@ -30,8 +30,8 @@ copy_file_range \- Copy a range of data from one file to another
 .B #define _GNU_SOURCE
 .B #include <unistd.h>
 .PP
-.BI "ssize_t copy_file_range(int " fd_in ", loff_t *" off_in ,
-.BI "                        int " fd_out ", loff_t *" off_out ,
+.BI "ssize_t copy_file_range(int " fd_in ", off64_t *" off_in ,
+.BI "                        int " fd_out ", off64_t *" off_out ,
 .BI "                        size_t " len ", unsigned int " flags );
 .fi
 .SH DESCRIPTION
-- 
2.29.2

Re: [PATCH] copy_file_range.2: SYNOPSIS: Fix prototype parameter types

[Michael Kerrisk (man-pages)]

Hi Alex,

On 12/30/20 10:41 PM, Alejandro Colomar wrote:
> Glibc uses 'off64_t' instead of 'loff_t'.

Okay.

> This patch doesn't change the types in the code example,
> because it uses the Linux syscall, and not the glibc wrapper.

I think the example probably also needs fixing then. There's
no longer a need for syscall(2) in this example, I think.

Thanks,

Michael

> ......
> 
> $ syscall='copy_file_range';
> $ ret='ssize_t';
> $ find glibc/ -type f -name '*.h' \
>   |xargs pcregrep -Mn "(?s)^[\w\s]*${ret}\s*${syscall}\s*\(.*?;";
> glibc/posix/unistd.h:1121:
> ssize_t copy_file_range (int __infd, __off64_t *__pinoff,
> 			 int __outfd, __off64_t *__poutoff,
> 			 size_t __length, unsigned int __flags);
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
>  man2/copy_file_range.2 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2
> index 1692aa44a..6f4708c4b 100644
> --- a/man2/copy_file_range.2
> +++ b/man2/copy_file_range.2
> @@ -30,8 +30,8 @@ copy_file_range \- Copy a range of data from one file to another
>  .B #define _GNU_SOURCE
>  .B #include <unistd.h>
>  .PP
> -.BI "ssize_t copy_file_range(int " fd_in ", loff_t *" off_in ,
> -.BI "                        int " fd_out ", loff_t *" off_out ,
> +.BI "ssize_t copy_file_range(int " fd_in ", off64_t *" off_in ,
> +.BI "                        int " fd_out ", off64_t *" off_out ,
>  .BI "                        size_t " len ", unsigned int " flags );
>  .fi
>  .SH DESCRIPTION
> 


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

Re: [PATCH] copy_file_range.2: SYNOPSIS: Fix prototype parameter types

[Alejandro Colomar (man-pages)]

On 12/30/20 11:43 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 12/30/20 10:41 PM, Alejandro Colomar wrote:
>> Glibc uses 'off64_t' instead of 'loff_t'.
> 
> Okay.
> 
>> This patch doesn't change the types in the code example,
>> because it uses the Linux syscall, and not the glibc wrapper.
> 
> I think the example probably also needs fixing then. There's
> no longer a need for syscall(2) in this example, I think.

Hi Michael,

I thought the same, but glibc 2.26 is still supported,
and lacks the wrapper.
Would you change it already?

Thanks,

Alex

> 
> Thanks,
> 
> Michael
> 
>> ......
>>
>> $ syscall='copy_file_range';
>> $ ret='ssize_t';
>> $ find glibc/ -type f -name '*.h' \
>>   |xargs pcregrep -Mn "(?s)^[\w\s]*${ret}\s*${syscall}\s*\(.*?;";
>> glibc/posix/unistd.h:1121:
>> ssize_t copy_file_range (int __infd, __off64_t *__pinoff,
>> 			 int __outfd, __off64_t *__poutoff,
>> 			 size_t __length, unsigned int __flags);
>>
>> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
>> ---
>>  man2/copy_file_range.2 | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2
>> index 1692aa44a..6f4708c4b 100644
>> --- a/man2/copy_file_range.2
>> +++ b/man2/copy_file_range.2
>> @@ -30,8 +30,8 @@ copy_file_range \- Copy a range of data from one file to another
>>  .B #define _GNU_SOURCE
>>  .B #include <unistd.h>
>>  .PP
>> -.BI "ssize_t copy_file_range(int " fd_in ", loff_t *" off_in ,
>> -.BI "                        int " fd_out ", loff_t *" off_out ,
>> +.BI "ssize_t copy_file_range(int " fd_in ", off64_t *" off_in ,
>> +.BI "                        int " fd_out ", off64_t *" off_out ,
>>  .BI "                        size_t " len ", unsigned int " flags );
>>  .fi
>>  .SH DESCRIPTION
>>
> 
> 

Re: [PATCH] copy_file_range.2: SYNOPSIS: Fix prototype parameter types

[Michael Kerrisk (man-pages)]

Hi Alex,

On 12/31/20 12:20 AM, Alejandro Colomar (man-pages) wrote:
> 
> 
> On 12/30/20 11:43 PM, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On 12/30/20 10:41 PM, Alejandro Colomar wrote:
>>> Glibc uses 'off64_t' instead of 'loff_t'.
>>
>> Okay.
>>
>>> This patch doesn't change the types in the code example,
>>> because it uses the Linux syscall, and not the glibc wrapper.
>>
>> I think the example probably also needs fixing then. There's
>> no longer a need for syscall(2) in this example, I think.
> 
> Hi Michael,
> 
> I thought the same, but glibc 2.26 is still supported,
> and lacks the wrapper.
> Would you change it already?

Yes.

Thanks,

Michael


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

Re: [PATCH] copy_file_range.2: SYNOPSIS: Fix prototype parameter types

[Alejandro Colomar (man-pages)]

Hi Michael,

I'm fixing the example, and I trying to see if I can remove some of the
headers with the change.  However, it's difficult to find that for sure,
at least from the manual pages alone.  I think that's one of the biggest
inconsistencies in the pages and I'd like to fix that some day.

Also, I'll resend the old patch documenting off64_t in
system_data_types(7), given that this interface uses it.

For the SYNOPSIS sections of man2 and man3,
I'll try to have a single header,
and if there are some other headers needed (for type definitions, or
other), I'll add a comment to all of them, so that it's clear why each
header is needed.

See stat(2) as an example of what I don't like:

[[
SYNOPSIS
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <unistd.h>

       int stat(const char *pathname, struct stat *statbuf);
       int fstat(int fd, struct stat *statbuf);
       int lstat(const char *pathname, struct stat *statbuf);

       #include <fcntl.h>           /* Definition of AT_* constants */
       #include <sys/stat.h>

       int fstatat(int dirfd, const char *pathname, struct stat *statbuf,
                   int flags);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       lstat():
           /* glibc 2.19 and earlier */ _BSD_SOURCE
               || /* Since glibc 2.20 */ _DEFAULT_SOURCE
               || _XOPEN_SOURCE >= 500
               || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L

       fstatat():
           Since glibc 2.10:
               _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

]]

Why should one include all of those headers?
Which has the function definition?
And what do the others provide?

Cheers,

Alex


On 12/31/20 9:58 AM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 12/31/20 12:20 AM, Alejandro Colomar (man-pages) wrote:
>>
>>
>> On 12/30/20 11:43 PM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex,
>>>
>>> On 12/30/20 10:41 PM, Alejandro Colomar wrote:
>>>> Glibc uses 'off64_t' instead of 'loff_t'.
>>>
>>> Okay.
>>>
>>>> This patch doesn't change the types in the code example,
>>>> because it uses the Linux syscall, and not the glibc wrapper.
>>>
>>> I think the example probably also needs fixing then. There's
>>> no longer a need for syscall(2) in this example, I think.
>>
>> Hi Michael,
>>
>> I thought the same, but glibc 2.26 is still supported,
>> and lacks the wrapper.
>> Would you change it already?
> 
> Yes.
> 
> Thanks,
> 
> Michael
> 
> 

[PATCH] Various pages: Consistently use 'unsigned int'

[Alejandro Colomar]

Most pages use 'unsigned int' (and the kernel too).
Make them all do so.

$ find man? -type f \
  |xargs sed -i \
	-e 's/unsigned \*/unsigned int */g'
	-e 's/unsigned "/unsigned int "/g';

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man2/getcpu.2     | 4 ++--
 man2/io_setup.2   | 2 +-
 man2/mbind.2      | 2 +-
 man3/cfree.3      | 2 +-
 man3/des_crypt.3  | 8 ++++----
 man3/getrpcport.3 | 2 +-
 man3/random.3     | 4 ++--
 man3/xdr.3        | 2 +-
 8 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/man2/getcpu.2 b/man2/getcpu.2
index fc36b43b5..46e4d53ff 100644
--- a/man2/getcpu.2
+++ b/man2/getcpu.2
@@ -16,8 +16,8 @@ getcpu \- determine CPU and NUMA node on which the calling thread is running
 .nf
 .B #include <linux/getcpu.h>
 .PP
-.BI "int getcpu(unsigned *" cpu ", unsigned *" node \
-", struct getcpu_cache *" tcache );
+.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node ,
+.BI "           struct getcpu_cache *" tcache );
 .fi
 .SH DESCRIPTION
 The
diff --git a/man2/io_setup.2 b/man2/io_setup.2
index e08d19bb8..bd52a5311 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 "long io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
+.BI "long io_setup(unsigned int " nr_events ", aio_context_t *" ctx_idp );
 .fi
 .PP
 .IR Note :
diff --git a/man2/mbind.2 b/man2/mbind.2
index bf66dfc6c..d98969e7f 100644
--- a/man2/mbind.2
+++ b/man2/mbind.2
@@ -41,7 +41,7 @@ mbind \- set memory policy for a memory range
 .PP
 .BI "long mbind(void *" addr ", unsigned long " len  ", int " mode ,
 .BI "           const unsigned long *" nodemask  ", unsigned long " maxnode ,
-.BI "           unsigned " flags );
+.BI "           unsigned int " flags );
 .PP
 Link with \fI\-lnuma\fP.
 .fi
diff --git a/man3/cfree.3 b/man3/cfree.3
index 2a09527a7..74223db71 100644
--- a/man3/cfree.3
+++ b/man3/cfree.3
@@ -36,7 +36,7 @@ cfree \- free allocated memory
 .BI "void cfree(void *" ptr );
 .PP
 /* In SCO OpenServer */
-.BI "void cfree(char *" ptr ", unsigned " num ", unsigned " size );
+.BI "void cfree(char *" ptr ", unsigned int " num ", unsigned int " size );
 .PP
 /* In Solaris watchmalloc.so.1 */
 .BI "void cfree(void *" ptr ", size_t " nelem ", size_t " elsize );
diff --git a/man3/des_crypt.3 b/man3/des_crypt.3
index 7f34c1585..66fe78337 100644
--- a/man3/des_crypt.3
+++ b/man3/des_crypt.3
@@ -21,11 +21,11 @@ DES encryption
 .\" .B #include <des_crypt.h>
 .B #include <rpc/des_crypt.h>
 .PP
-.BI "int ecb_crypt(char *" key ", char *" data ", unsigned " datalen ,
-.BI "              unsigned " mode );
+.BI "int ecb_crypt(char *" key ", char *" data ", unsigned int " datalen ,
+.BI "              unsigned int " mode );
 .PP
-.BI "int cbc_crypt(char *" key ", char *" data ", unsigned " datalen ,
-.BI "              unsigned " mode ", char *" ivec );
+.BI "int cbc_crypt(char *" key ", char *" data ", unsigned int " datalen ,
+.BI "              unsigned int " mode ", char *" ivec );
 .PP
 .BI "void des_setparity(char *" key );
 .PP
diff --git a/man3/getrpcport.3 b/man3/getrpcport.3
index 2eba5d30a..d5753d39b 100644
--- a/man3/getrpcport.3
+++ b/man3/getrpcport.3
@@ -13,7 +13,7 @@ getrpcport \- get RPC port number
 .B "#include <rpc/rpc.h>"
 .PP
 .BI "int getrpcport(const char *" host ", unsigned long " prognum ,
-.BI "               unsigned long " versnum ", unsigned " proto );
+.BI "               unsigned long " versnum ", unsigned int " proto );
 .fi
 .SH DESCRIPTION
 .BR getrpcport ()
diff --git a/man3/random.3 b/man3/random.3
index d1b8e1981..c9066e446 100644
--- a/man3/random.3
+++ b/man3/random.3
@@ -39,9 +39,9 @@ random, srandom, initstate, setstate \- random number generator
 .PP
 .B long random(void);
 .PP
-.BI "void srandom(unsigned " seed );
+.BI "void srandom(unsigned int " seed );
 .PP
-.BI "char *initstate(unsigned " seed ", char *" state ", size_t " n );
+.BI "char *initstate(unsigned int " seed ", char *" state ", size_t " n );
 .PP
 .BI "char *setstate(char *" state );
 .fi
diff --git a/man3/xdr.3 b/man3/xdr.3
index 713827567..978a50660 100644
--- a/man3/xdr.3
+++ b/man3/xdr.3
@@ -433,7 +433,7 @@ C characters and their external representations.
 This routine returns one if it succeeds, zero otherwise.
 .PP
 .nf
-.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned *" up );
+.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up );
 .fi
 .IP
 A filter primitive that translates between C
-- 
2.29.2

[PATCH v2] copy_file_range.2: Document glibc wrapper instead of kernel syscall

[Alejandro Colomar]

Glibc uses 'off64_t' instead of 'loff_t'.

......

Glibc prototype:

$ syscall='copy_file_range';
$ ret='ssize_t';
$ find glibc/ -type f -name '*.h' \
  |xargs pcregrep -Mn "(?s)^[\w\s]*${ret}\s*${syscall}\s*\(.*?;";
glibc/posix/unistd.h:1121:
ssize_t copy_file_range (int __infd, __off64_t *__pinoff,
			 int __outfd, __off64_t *__poutoff,
			 size_t __length, unsigned int __flags);

......

Testing example:

$ man ./man2/copy_file_range.2 \
  |sed -n '/^EXAMPLES/,/^SEE ALSO/p' \
  |head -n -1 \
  |tail -n +2 \
  >copy_file_range.c
$ gcc -Wall -Wextra -Werror -pedantic
copy_file_range.c -o copy_file_range
$ ./copy_file_range 
Usage: ./copy_file_range <source> <destination>
$ tee a >/dev/null
asdf
$ tee b >/dev/null
qwerty
zxcvbn
$ ./copy_file_range a b
$ cat a
asdf
$ cat b
asdf


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

diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2
index 1692aa44a..611a39b80 100644
--- a/man2/copy_file_range.2
+++ b/man2/copy_file_range.2
@@ -30,8 +30,8 @@ copy_file_range \- Copy a range of data from one file to another
 .B #define _GNU_SOURCE
 .B #include <unistd.h>
 .PP
-.BI "ssize_t copy_file_range(int " fd_in ", loff_t *" off_in ,
-.BI "                        int " fd_out ", loff_t *" off_out ,
+.BI "ssize_t copy_file_range(int " fd_in ", off64_t *" off_in ,
+.BI "                        int " fd_out ", off64_t *" off_out ,
 .BI "                        size_t " len ", unsigned int " flags );
 .fi
 .SH DESCRIPTION
@@ -233,26 +233,14 @@ or server-side-copy (in the case of NFS).
 #include <stdio.h>
 #include <stdlib.h>
 #include <sys/stat.h>
-#include <sys/syscall.h>
 #include <unistd.h>
 
-/* On versions of glibc before 2.27, we must invoke copy_file_range()
-   using syscall(2) */
-
-static loff_t
-copy_file_range(int fd_in, loff_t *off_in, int fd_out,
-                loff_t *off_out, size_t len, unsigned int flags)
-{
-    return syscall(__NR_copy_file_range, fd_in, off_in, fd_out,
-                   off_out, len, flags);
-}
-
 int
 main(int argc, char **argv)
 {
     int fd_in, fd_out;
     struct stat stat;
-    loff_t len, ret;
+    off64_t len, ret;
 
     if (argc != 3) {
         fprintf(stderr, "Usage: %s <source> <destination>\en", argv[0]);
-- 
2.29.2

Re: [PATCH v2] copy_file_range.2: Document glibc wrapper instead of kernel syscall

[Michael Kerrisk (man-pages)]

Hello Alex,

On 12/31/20 2:24 PM, Alejandro Colomar wrote:
> Glibc uses 'off64_t' instead of 'loff_t'.
> 
> ......
> 
> Glibc prototype:
> 
> $ syscall='copy_file_range';
> $ ret='ssize_t';
> $ find glibc/ -type f -name '*.h' \
>   |xargs pcregrep -Mn "(?s)^[\w\s]*${ret}\s*${syscall}\s*\(.*?;";
> glibc/posix/unistd.h:1121:
> ssize_t copy_file_range (int __infd, __off64_t *__pinoff,
> 			 int __outfd, __off64_t *__poutoff,
> 			 size_t __length, unsigned int __flags);
> 
> ......
> 
> Testing example:
> 
> $ man ./man2/copy_file_range.2 \
>   |sed -n '/^EXAMPLES/,/^SEE ALSO/p' \
>   |head -n -1 \
>   |tail -n +2 \
>   >copy_file_range.c
> $ gcc -Wall -Wextra -Werror -pedantic
> copy_file_range.c -o copy_file_range
> $ ./copy_file_range 
> Usage: ./copy_file_range <source> <destination>
> $ tee a >/dev/null
> asdf
> $ tee b >/dev/null
> qwerty
> zxcvbn
> $ ./copy_file_range a b
> $ cat a
> asdf
> $ cat b
> asdf
> 
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Thanks! Patch applied.

Cheers,

Michael

> ---
>  man2/copy_file_range.2 | 18 +++---------------
>  1 file changed, 3 insertions(+), 15 deletions(-)
> 
> diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2
> index 1692aa44a..611a39b80 100644
> --- a/man2/copy_file_range.2
> +++ b/man2/copy_file_range.2
> @@ -30,8 +30,8 @@ copy_file_range \- Copy a range of data from one file to another
>  .B #define _GNU_SOURCE
>  .B #include <unistd.h>
>  .PP
> -.BI "ssize_t copy_file_range(int " fd_in ", loff_t *" off_in ,
> -.BI "                        int " fd_out ", loff_t *" off_out ,
> +.BI "ssize_t copy_file_range(int " fd_in ", off64_t *" off_in ,
> +.BI "                        int " fd_out ", off64_t *" off_out ,
>  .BI "                        size_t " len ", unsigned int " flags );
>  .fi
>  .SH DESCRIPTION
> @@ -233,26 +233,14 @@ or server-side-copy (in the case of NFS).
>  #include <stdio.h>
>  #include <stdlib.h>
>  #include <sys/stat.h>
> -#include <sys/syscall.h>
>  #include <unistd.h>
>  
> -/* On versions of glibc before 2.27, we must invoke copy_file_range()
> -   using syscall(2) */
> -
> -static loff_t
> -copy_file_range(int fd_in, loff_t *off_in, int fd_out,
> -                loff_t *off_out, size_t len, unsigned int flags)
> -{
> -    return syscall(__NR_copy_file_range, fd_in, off_in, fd_out,
> -                   off_out, len, flags);
> -}
> -
>  int
>  main(int argc, char **argv)
>  {
>      int fd_in, fd_out;
>      struct stat stat;
> -    loff_t len, ret;
> +    off64_t len, ret;
>  
>      if (argc != 3) {
>          fprintf(stderr, "Usage: %s <source> <destination>\en", argv[0]);
> 


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

Re: [PATCH] Various pages: Consistently use 'unsigned int'

[Michael Kerrisk (man-pages)]

Hi Alex,

On 12/31/20 2:01 PM, Alejandro Colomar wrote:
> Most pages use 'unsigned int' (and the kernel too).
> Make them all do so.
> 
> $ find man? -type f \
>   |xargs sed -i \
> 	-e 's/unsigned \*/unsigned int */g'
> 	-e 's/unsigned "/unsigned int "/g';
> 
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Good work. Patch applied (manually, because I shot myself in 
the foot with the other recent work in SYNOPSIS).

Cheers,

Michael

> ---
>  man2/getcpu.2     | 4 ++--
>  man2/io_setup.2   | 2 +-
>  man2/mbind.2      | 2 +-
>  man3/cfree.3      | 2 +-
>  man3/des_crypt.3  | 8 ++++----
>  man3/getrpcport.3 | 2 +-
>  man3/random.3     | 4 ++--
>  man3/xdr.3        | 2 +-
>  8 files changed, 13 insertions(+), 13 deletions(-)
> 
> diff --git a/man2/getcpu.2 b/man2/getcpu.2
> index fc36b43b5..46e4d53ff 100644
> --- a/man2/getcpu.2
> +++ b/man2/getcpu.2
> @@ -16,8 +16,8 @@ getcpu \- determine CPU and NUMA node on which the calling thread is running
>  .nf
>  .B #include <linux/getcpu.h>
>  .PP
> -.BI "int getcpu(unsigned *" cpu ", unsigned *" node \
> -", struct getcpu_cache *" tcache );
> +.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node ,
> +.BI "           struct getcpu_cache *" tcache );
>  .fi
>  .SH DESCRIPTION
>  The
> diff --git a/man2/io_setup.2 b/man2/io_setup.2
> index e08d19bb8..bd52a5311 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 "long io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
> +.BI "long io_setup(unsigned int " nr_events ", aio_context_t *" ctx_idp );
>  .fi
>  .PP
>  .IR Note :
> diff --git a/man2/mbind.2 b/man2/mbind.2
> index bf66dfc6c..d98969e7f 100644
> --- a/man2/mbind.2
> +++ b/man2/mbind.2
> @@ -41,7 +41,7 @@ mbind \- set memory policy for a memory range
>  .PP
>  .BI "long mbind(void *" addr ", unsigned long " len  ", int " mode ,
>  .BI "           const unsigned long *" nodemask  ", unsigned long " maxnode ,
> -.BI "           unsigned " flags );
> +.BI "           unsigned int " flags );
>  .PP
>  Link with \fI\-lnuma\fP.
>  .fi
> diff --git a/man3/cfree.3 b/man3/cfree.3
> index 2a09527a7..74223db71 100644
> --- a/man3/cfree.3
> +++ b/man3/cfree.3
> @@ -36,7 +36,7 @@ cfree \- free allocated memory
>  .BI "void cfree(void *" ptr );
>  .PP
>  /* In SCO OpenServer */
> -.BI "void cfree(char *" ptr ", unsigned " num ", unsigned " size );
> +.BI "void cfree(char *" ptr ", unsigned int " num ", unsigned int " size );
>  .PP
>  /* In Solaris watchmalloc.so.1 */
>  .BI "void cfree(void *" ptr ", size_t " nelem ", size_t " elsize );
> diff --git a/man3/des_crypt.3 b/man3/des_crypt.3
> index 7f34c1585..66fe78337 100644
> --- a/man3/des_crypt.3
> +++ b/man3/des_crypt.3
> @@ -21,11 +21,11 @@ DES encryption
>  .\" .B #include <des_crypt.h>
>  .B #include <rpc/des_crypt.h>
>  .PP
> -.BI "int ecb_crypt(char *" key ", char *" data ", unsigned " datalen ,
> -.BI "              unsigned " mode );
> +.BI "int ecb_crypt(char *" key ", char *" data ", unsigned int " datalen ,
> +.BI "              unsigned int " mode );
>  .PP
> -.BI "int cbc_crypt(char *" key ", char *" data ", unsigned " datalen ,
> -.BI "              unsigned " mode ", char *" ivec );
> +.BI "int cbc_crypt(char *" key ", char *" data ", unsigned int " datalen ,
> +.BI "              unsigned int " mode ", char *" ivec );
>  .PP
>  .BI "void des_setparity(char *" key );
>  .PP
> diff --git a/man3/getrpcport.3 b/man3/getrpcport.3
> index 2eba5d30a..d5753d39b 100644
> --- a/man3/getrpcport.3
> +++ b/man3/getrpcport.3
> @@ -13,7 +13,7 @@ getrpcport \- get RPC port number
>  .B "#include <rpc/rpc.h>"
>  .PP
>  .BI "int getrpcport(const char *" host ", unsigned long " prognum ,
> -.BI "               unsigned long " versnum ", unsigned " proto );
> +.BI "               unsigned long " versnum ", unsigned int " proto );
>  .fi
>  .SH DESCRIPTION
>  .BR getrpcport ()
> diff --git a/man3/random.3 b/man3/random.3
> index d1b8e1981..c9066e446 100644
> --- a/man3/random.3
> +++ b/man3/random.3
> @@ -39,9 +39,9 @@ random, srandom, initstate, setstate \- random number generator
>  .PP
>  .B long random(void);
>  .PP
> -.BI "void srandom(unsigned " seed );
> +.BI "void srandom(unsigned int " seed );
>  .PP
> -.BI "char *initstate(unsigned " seed ", char *" state ", size_t " n );
> +.BI "char *initstate(unsigned int " seed ", char *" state ", size_t " n );
>  .PP
>  .BI "char *setstate(char *" state );
>  .fi
> diff --git a/man3/xdr.3 b/man3/xdr.3
> index 713827567..978a50660 100644
> --- a/man3/xdr.3
> +++ b/man3/xdr.3
> @@ -433,7 +433,7 @@ C characters and their external representations.
>  This routine returns one if it succeeds, zero otherwise.
>  .PP
>  .nf
> -.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned *" up );
> +.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up );
>  .fi
>  .IP
>  A filter primitive that translates between C
> 


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

Re: [PATCH] copy_file_range.2: SYNOPSIS: Fix prototype parameter types

[Michael Kerrisk (man-pages)]

Hi Alex,

On 12/31/20 1:46 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> I'm fixing the example, and I trying to see if I can remove some of the
> headers with the change.  However, it's difficult to find that for sure,
> at least from the manual pages alone.  I think that's one of the biggest
> inconsistencies in the pages and I'd like to fix that some day.
> 
> Also, I'll resend the old patch documenting off64_t in
> system_data_types(7), given that this interface uses it.
> 
> For the SYNOPSIS sections of man2 and man3,
> I'll try to have a single header,
> and if there are some other headers needed (for type definitions, or
> other), I'll add a comment to all of them, so that it's clear why each
> header is needed.
> 
> See stat(2) as an example of what I don't like:
> 
> [[
> SYNOPSIS
>        #include <sys/types.h>
>        #include <sys/stat.h>
>        #include <unistd.h>
> 
>        int stat(const char *pathname, struct stat *statbuf);
>        int fstat(int fd, struct stat *statbuf);
>        int lstat(const char *pathname, struct stat *statbuf);
> 
>        #include <fcntl.h>           /* Definition of AT_* constants */
>        #include <sys/stat.h>
> 
>        int fstatat(int dirfd, const char *pathname, struct stat *statbuf,
>                    int flags);
> 
>    Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
> 
>        lstat():
>            /* glibc 2.19 and earlier */ _BSD_SOURCE
>                || /* Since glibc 2.20 */ _DEFAULT_SOURCE
>                || _XOPEN_SOURCE >= 500
>                || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
> 
>        fstatat():
>            Since glibc 2.10:
>                _POSIX_C_SOURCE >= 200809L
>            Before glibc 2.10:
>                _ATFILE_SOURCE
> 
> ]]
> 
> Why should one include all of those headers?
> Which has the function definition?
> And what do the others provide?

There's a lot of history here, and I do not know all of it.

In old standards, <sys/types.h> was often required for various
APIs. Eg.e., in XPGv4.2 (1994), there is the following spec:

OH  #include <sys/types.h>
    #include <sys/stat.h>
    int stat(const char *path, struct stat *buf);

And the standard says that "OH" means
    "This indicates that the marked header is not required on
     XSI-conformant systems. This is an extension to certain 
     formal standards where the full synopsis is required."

So, it seems that some ancient systems may have requried
this header (<sys/types.h>) for portability, presumably because
<sys/stat.h> did not itself define various types used in the 
'stat' structure (at least on some systems. So, for portability
reasons, the Linux manual page mentions this header file.

I have no explanation of <unistd.h>. That was there when I
inherited the project (and back then there was no version 
control). But it was there back in 1995. Perhaps there's
a historical reason. Perhaps there was a mistake. (No version
control, no mailing list, so who knows.)

I'm not averse to seeing some of this cleaned up.
It's not fun work, of course! Maybe POSIX.1-2001 (as well
as 2008) might need to be checked, since info in that
standard is a snapshot of history that could conceivably still
be relevant now (in terms of portability to implementations
that are older but possibly still relevant).

Cheers,

Michael


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