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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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/