Why does stat(2) say <unistd.h> is needed?

Why does stat(2) say <unistd.h> is needed?

[Jonathan Wakely]

The stat(2) man page says:

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

But I don't see anything there that would require <unistd.h>. POSIX
doesn't require it (and since POSIX.1-2001 no longer requires
<sys/types.h>, saying "Although <sys/types.h> was required for
conforming implementations of previous POSIX specifications, it was
not required for UNIX applications.")

Is the inclusion of <unistd.h> there a mistake?

I've been trying to track down why a libstdc++ header includes
<unistd.h> for no apparent reason, and my best guess is that it's a
result of this man page saying to do it.

Re: Why does stat(2) say <unistd.h> is needed?

[Alejandro Colomar (man-pages)]

Hello Jonathan,

On 2/9/21 12:09 PM, Jonathan Wakely wrote:
> The stat(2) man page says:
> 
> 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);
> 
> But I don't see anything there that would require <unistd.h>. POSIX
> doesn't require it (and since POSIX.1-2001 no longer requires
> <sys/types.h>, saying "Although <sys/types.h> was required for
> conforming implementations of previous POSIX specifications, it was
> not required for UNIX applications.")
> 
> Is the inclusion of <unistd.h> there a mistake?
> 
> I've been trying to track down why a libstdc++ header includes
> <unistd.h> for no apparent reason, and my best guess is that it's a
> result of this man page saying to do it.
>
As far as we can tell, there's no reason to include it.  See 
<https://lore.kernel.org/linux-man/97457bf2-2b29-af4b-c910-2391c69c4134@gmail.com/>.

We haven't fixed it yet, because I'd like to fix all of the pages, and 
that's likely to take months (reading through every manual page in 
senctions 2 & 3, reading thorugh every included header, checking POSIX 
requirements, asking Michael if there may be historical reasons for a 
specific case, ...), but I'll do it some day.

For now, if you submit a patch, I'll merge it.

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Why does stat(2) say <unistd.h> is needed?

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 1549 bytes --]

On 09/02/21 12:27 +0100, Alejandro Colomar (man-pages) wrote:
>Hello Jonathan,
>
>On 2/9/21 12:09 PM, Jonathan Wakely wrote:
>>The stat(2) man page says:
>>
>>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);
>>
>>But I don't see anything there that would require <unistd.h>. POSIX
>>doesn't require it (and since POSIX.1-2001 no longer requires
>><sys/types.h>, saying "Although <sys/types.h> was required for
>>conforming implementations of previous POSIX specifications, it was
>>not required for UNIX applications.")
>>
>>Is the inclusion of <unistd.h> there a mistake?
>>
>>I've been trying to track down why a libstdc++ header includes
>><unistd.h> for no apparent reason, and my best guess is that it's a
>>result of this man page saying to do it.
>>
>As far as we can tell, there's no reason to include it.  See <https://lore.kernel.org/linux-man/97457bf2-2b29-af4b-c910-2391c69c4134@gmail.com/>.
>
>We haven't fixed it yet, because I'd like to fix all of the pages, and 
>that's likely to take months (reading through every manual page in 
>senctions 2 & 3, reading thorugh every included header, checking POSIX 
>requirements, asking Michael if there may be historical reasons for a 
>specific case, ...), but I'll do it some day.
>
>For now, if you submit a patch, I'll merge it.

Attached, thanks.



[-- Attachment #2: 0001-stat.2-Remove-unistd.h-from-synopsis.patch --]
[-- Type: text/plain, Size: 779 bytes --]

From d5b66a6b83302bd4070e3c83fb1dab341b76b728 Mon Sep 17 00:00:00 2001
From: Jonathan Wakely <jwakely@redhat.com>
Date: Tue, 9 Feb 2021 11:46:02 +0000
Subject: [PATCH] stat.2: Remove <unistd.h> from synopsis

There seems to be no reason <unistd.h> is shown here, so remove it.

Signed-off-by: Jonathan Wakely <jwakely@redhat.com>
---
 man2/stat.2 | 1 -
 1 file changed, 1 deletion(-)

diff --git a/man2/stat.2 b/man2/stat.2
index 734c74b04..fed926715 100644
--- a/man2/stat.2
+++ b/man2/stat.2
@@ -43,7 +43,6 @@ stat, fstat, lstat, fstatat \- get file status
 .nf
 .B #include <sys/types.h>
 .B #include <sys/stat.h>
-.B #include <unistd.h>
 .PP
 .BI "int stat(const char *" pathname ", struct stat *" statbuf );
 .BI "int fstat(int " fd ", struct stat *" statbuf );
-- 
2.29.2

Re: Why does stat(2) say <unistd.h> is needed?

[Alejandro Colomar (man-pages)]

On 2/9/21 12:53 PM, Jonathan Wakely wrote:
> On 09/02/21 12:27 +0100, Alejandro Colomar (man-pages) wrote:
>> Hello Jonathan,
>>
>> On 2/9/21 12:09 PM, Jonathan Wakely wrote:
>>> The stat(2) man page says:
>>>
>>> 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);
>>>
>>> But I don't see anything there that would require <unistd.h>. POSIX
>>> doesn't require it (and since POSIX.1-2001 no longer requires
>>> <sys/types.h>, saying "Although <sys/types.h> was required for
>>> conforming implementations of previous POSIX specifications, it was
>>> not required for UNIX applications.")
>>>
>>> Is the inclusion of <unistd.h> there a mistake?
>>>
>>> I've been trying to track down why a libstdc++ header includes
>>> <unistd.h> for no apparent reason, and my best guess is that it's a
>>> result of this man page saying to do it.
>>>
>> As far as we can tell, there's no reason to include it.  See
>> <https://lore.kernel.org/linux-man/97457bf2-2b29-af4b-c910-2391c69c4134@gmail.com/>.
>>
>>
>> We haven't fixed it yet, because I'd like to fix all of the pages, and
>> that's likely to take months (reading through every manual page in
>> senctions 2 & 3, reading thorugh every included header, checking POSIX
>> requirements, asking Michael if there may be historical reasons for a
>> specific case, ...), but I'll do it some day.
>>
>> For now, if you submit a patch, I'll merge it.
> 
> Attached, thanks.
> 
> 

Hi Jonathan,

Patch applied!

However, we normally prefer inline patches, if possible.

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Why does stat(2) say <unistd.h> is needed?

[Michael Kerrisk (man-pages)]

Hi Jonathan!

On 2/9/21 12:09 PM, Jonathan Wakely wrote:
> The stat(2) man page says:
> 
> 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);
> 
> But I don't see anything there that would require <unistd.h>. POSIX
> doesn't require it (and since POSIX.1-2001 no longer requires
> <sys/types.h>, saying "Although <sys/types.h> was required for
> conforming implementations of previous POSIX specifications, it was
> not required for UNIX applications.")
> 
> Is the inclusion of <unistd.h> there a mistake?

I do not know the reasons for it, but it has been there in
the manual page since 1993, and the reasons are thus lost
in the mists of the VCS and mailing list that the project
did not have back then :-}. By now, I'm prepared to classify
it as a mistake.

Thanks,

Michael

> I've been trying to track down why a libstdc++ header includes
> <unistd.h> for no apparent reason, and my best guess is that it's a
> result of this man page saying to do it.
> 


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