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/
