Skip to contentSkip to conversation

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

DISCUSSION Jonathan Wakely 3 participants 5 messages Feb 9, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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.

#1 lore raw

Hello Jonathan,

Quoted 17 lines · 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.")

Quoted 6 lines

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/[email protected]/>.

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

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#2 lore raw
Quoted 26 lines · Alejandro Colomar (man-pages)

Hello Jonathan,

Quoted 17 lines · 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.")

Quoted 6 lines

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.

Quoted 5 lines

As far as we can tell, there's no reason to include it. See <https://lore.kernel.org/linux-man/[email protected]/>.

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.

From d5b66a6b83302bd4070e3c83fb1dab341b76b728 Mon Sep 17 00:00:00 2001
From: Jonathan Wakely <[email protected]>
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.

---
 man2/stat.2 | 1 -
 1 file changed, 1 deletion(-)
man2/stat.2 +0 -1
index 734c74b04..fed926715 100644
@@ -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 );
Signature · 1 line
2.29.2
#3 lore raw
Quoted 37 lines · Jonathan Wakely
Quoted 36 lines · Alejandro Colomar (man-pages)

Hello Jonathan,

Quoted 17 lines · 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.")

Quoted 6 lines

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/[email protected]/>.

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.

Quoted 5 lines
Quoted 1 line

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

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#4 lore raw
In reply to Jonathan Wakely

Hi Jonathan!

Quoted 11 lines · 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);
Quoted 7 lines

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

Quoted 4 lines

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.

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