diff mbox

makedev(3): point people at sys/sysmacros.h

Message ID 1461045163-21248-1-git-send-email-vapier@gentoo.org
State Not Applicable
Headers show

Commit Message

Mike Frysinger April 19, 2016, 5:52 a.m. UTC
Defining these functions via sys/types.h violates POSIX namespace
requirements, so we want to disentangle it from that header.  Since
glibc has basically always used this header, update the docs to have
people include that instead.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>
---
 man3/makedev.3 | 16 ++++------------
 1 file changed, 4 insertions(+), 12 deletions(-)

Comments

Michael Kerrisk (man-pages) April 20, 2016, 11:31 a.m. UTC | #1
Hi Mike,

I don't object to the patch, but...

On 04/19/2016 06:52 AM, Mike Frysinger wrote:
> Defining these functions via sys/types.h violates POSIX namespace
> requirements, 

What do the previous lines mean? Violate namespace requirements how?

Cheers,

Michael


> so we want to disentangle it from that header.  Since
> glibc has basically always used this header, update the docs to have
> people include that instead.
>
> Signed-off-by: Mike Frysinger <vapier@gentoo.org>
> ---
>  man3/makedev.3 | 16 ++++------------
>  1 file changed, 4 insertions(+), 12 deletions(-)
> 
> diff --git a/man3/makedev.3 b/man3/makedev.3
> index f91f4b5..3d26d15 100644
> --- a/man3/makedev.3
> +++ b/man3/makedev.3
> @@ -28,23 +28,13 @@
>  makedev, major, minor \- manage a device number
>  .SH SYNOPSIS
>  .nf
> -.B #include <sys/types.h>
> +.B #include <sys/sysmacros.h>
>  
>  .BI "dev_t makedev(unsigned int " maj ", unsigned int " min );
>  
>  .BI "unsigned int major(dev_t " dev );
>  .BI "unsigned int minor(dev_t " dev );
>  .fi
> -.sp
> -.BR makedev (),
> -.BR major (),
> -.BR minor ():
> -.nf
> -    Since glibc 2.19:
> -        _DEFAULT_SOURCE
> -    In glibc up to and including 2.19:
> -        _BSD_SOURCE
> -.fi
>  .SH DESCRIPTION
>  A device ID consists of two parts:
>  a major ID, identifying the class of the device,
> @@ -90,7 +80,9 @@ and
>  .BR minor ()
>  functions are not specified in POSIX.1,
>  but are present on many other systems.
> -.\" The BSDs, HP-UX, Solaris, AIX, Irix
> +.\" The BSDs, HP-UX, Solaris, AIX, Irix.
> +.\" The header location is inconsistent:
> +.\" Could be sys/mkdev.h, sys/sysmacros.h, or sys/types.h.
>  .SH NOTES
>  These interfaces are defined as macros.
>  Since glibc 2.3.3,
>
Zack Weinberg April 20, 2016, 11:47 a.m. UTC | #2
On Wed, Apr 20, 2016 at 7:31 AM, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> On 04/19/2016 06:52 AM, Mike Frysinger wrote:
>> Defining these functions via sys/types.h violates POSIX namespace
>> requirements,
>
> What do the previous lines mean? Violate namespace requirements how?

I think it's technically not true that they violate POSIX namespace
requirements, since they're only defined in the non-conforming modes.

The reason I originally proposed the change is that libstdc++
force-enables _GNU_SOURCE, which means people writing in C++ _can't_
avoid these nonstandard macros by using a strict conformance mode.

zw
Michael Kerrisk (man-pages) April 20, 2016, 12:38 p.m. UTC | #3
On 04/20/2016 01:47 PM, Zack Weinberg wrote:
> On Wed, Apr 20, 2016 at 7:31 AM, Michael Kerrisk (man-pages)
> <mtk.manpages@gmail.com> wrote:
>> On 04/19/2016 06:52 AM, Mike Frysinger wrote:
>>> Defining these functions via sys/types.h violates POSIX namespace
>>> requirements,
>>
>> What do the previous lines mean? Violate namespace requirements how?
> 
> I think it's technically not true that they violate POSIX namespace
> requirements, since they're only defined in the non-conforming modes.
> 
> The reason I originally proposed the change is that libstdc++
> force-enables _GNU_SOURCE, which means people writing in C++ _can't_
> avoid these nonstandard macros by using a strict conformance mode.

Thanks for the explanation, Zack. I applied Mike's patch.

Cheers,

Michael
diff mbox

Patch

diff --git a/man3/makedev.3 b/man3/makedev.3
index f91f4b5..3d26d15 100644
--- a/man3/makedev.3
+++ b/man3/makedev.3
@@ -28,23 +28,13 @@ 
 makedev, major, minor \- manage a device number
 .SH SYNOPSIS
 .nf
-.B #include <sys/types.h>
+.B #include <sys/sysmacros.h>
 
 .BI "dev_t makedev(unsigned int " maj ", unsigned int " min );
 
 .BI "unsigned int major(dev_t " dev );
 .BI "unsigned int minor(dev_t " dev );
 .fi
-.sp
-.BR makedev (),
-.BR major (),
-.BR minor ():
-.nf
-    Since glibc 2.19:
-        _DEFAULT_SOURCE
-    In glibc up to and including 2.19:
-        _BSD_SOURCE
-.fi
 .SH DESCRIPTION
 A device ID consists of two parts:
 a major ID, identifying the class of the device,
@@ -90,7 +80,9 @@  and
 .BR minor ()
 functions are not specified in POSIX.1,
 but are present on many other systems.
-.\" The BSDs, HP-UX, Solaris, AIX, Irix
+.\" The BSDs, HP-UX, Solaris, AIX, Irix.
+.\" The header location is inconsistent:
+.\" Could be sys/mkdev.h, sys/sysmacros.h, or sys/types.h.
 .SH NOTES
 These interfaces are defined as macros.
 Since glibc 2.3.3,