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

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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
> 
>