[PATCH] grantpt.3: explicitly mention #define _XOPEN_SOURCE requirement

[PATCH] grantpt.3: explicitly mention #define _XOPEN_SOURCE requirement

[Emanuele Torre]

Like the unlockpt(3) function, grantpt(3) requires _XOPEN_SOURCE to be
defined before including stdlib.h.

unlockpt.3 explicitly shows this requirement in its SYNOPSIS:

    SYNOPSIS
           #define _XOPEN_SOURCE
           #include <stdlib.h>

           int unlockpt(int fd);

But grantpt.3 did not:

    SYNOPSIS
           #include <stdlib.h>

           int grantpt(int fd);

o/
 emanuele6
---
 man/man3/grantpt.3 | 1 +
 1 file changed, 1 insertion(+)

diff --git a/man/man3/grantpt.3 b/man/man3/grantpt.3
index 94526691b..f2d70ebd6 100644
--- a/man/man3/grantpt.3
+++ b/man/man3/grantpt.3
@@ -11,6 +11,7 @@ Standard C library
 .RI ( libc ", " \-lc )
 .SH SYNOPSIS
 .nf
+.B #define _XOPEN_SOURCE
 .B #include <stdlib.h>
 .P
 .BI "int grantpt(int " fd ");"
-- 
2.45.1

Re: [PATCH] grantpt.3: explicitly mention #define _XOPEN_SOURCE requirement

[Alejandro Colomar]

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

Hi Emanuele,

On Sun, May 26, 2024 at 08:42:18AM GMT, Emanuele Torre wrote:
> Like the unlockpt(3) function, grantpt(3) requires _XOPEN_SOURCE to be
> defined before including stdlib.h.
> 
> unlockpt.3 explicitly shows this requirement in its SYNOPSIS:
> 
>     SYNOPSIS
>            #define _XOPEN_SOURCE
>            #include <stdlib.h>
> 
>            int unlockpt(int fd);
> 
> But grantpt.3 did not:
> 
>     SYNOPSIS
>            #include <stdlib.h>
> 
>            int grantpt(int fd);
> 
> o/
>  emanuele6

Patch applied; thanks.

Have a lovely day!
Alex

> ---
>  man/man3/grantpt.3 | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/man/man3/grantpt.3 b/man/man3/grantpt.3
> index 94526691b..f2d70ebd6 100644
> --- a/man/man3/grantpt.3
> +++ b/man/man3/grantpt.3
> @@ -11,6 +11,7 @@ Standard C library
>  .RI ( libc ", " \-lc )
>  .SH SYNOPSIS
>  .nf
> +.B #define _XOPEN_SOURCE
>  .B #include <stdlib.h>
>  .P
>  .BI "int grantpt(int " fd ");"
> -- 
> 2.45.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] grantpt.3: explicitly mention #define _XOPEN_SOURCE requirement

[Emanuele Torre]

On Sun, May 26, 2024 at 12:39:07PM +0200, Alejandro Colomar wrote:
> Hi Emanuele,
> 
> On Sun, May 26, 2024 at 08:42:18AM GMT, Emanuele Torre wrote:
> > Like the unlockpt(3) function, grantpt(3) requires _XOPEN_SOURCE to be
> > defined before including stdlib.h.
> > 
> > unlockpt.3 explicitly shows this requirement in its SYNOPSIS:
> > 
> >     SYNOPSIS
> >            #define _XOPEN_SOURCE
> >            #include <stdlib.h>
> > 
> >            int unlockpt(int fd);
> > 
> > But grantpt.3 did not:
> > 
> >     SYNOPSIS
> >            #include <stdlib.h>
> > 
> >            int grantpt(int fd);
> > 
> > o/
> >  emanuele6
> 
> Patch applied; thanks.

I've just noticed that ptsname.3 is also missing  #define _XOPEN_SOURCE
in its synopsis; however  #define _XOPEN_SOURCE  does not seem to work.

Even if _XOPEN_SOURCE is defined, #include <stdlib.h> does not include
the prototype of ptsname(3).  It seems to only be included when
_GNU_SOURCE is defined.

This may be a glibc bug because ptsname(3) is supposed to be a POSIX XSI
function like grantpt(3) and unlockpt(3).  Only ptsname_r(3) is an
extension.

https://pubs.opengroup.org/onlinepubs/9699919799/functions/ptsname.html

    $ gcc -fsyntax-only -D_XOPEN_SOURCE -includestdlib.h -x c - <<< 'int main(){ptsname(0);}'
    <stdin>: In function ‘main’:
    <stdin>:1:12: error: implicit declaration of function ‘ptsname’ [-Wimplicit-function-declaration]

    $ gcc -fsyntax-only -D_GNU_SOURCE -includestdlib.h -x c - <<< 'int main(){ptsname(0);}'

I am using the version of glibc packaged by ArchLinux
(package version 2.39+r52+gf8e4623421-1).

I added libc-alpha@sourceware.org to CC in case it is actually a bug.

> 
> Have a lovely day!

You too!  :-)

> Alex

o/
 emanuele6

Re: [PATCH] grantpt.3: explicitly mention #define _XOPEN_SOURCE requirement

[Alejandro Colomar]

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

Hi Emanuele,

On Sun, May 26, 2024 at 04:19:30PM GMT, Emanuele Torre wrote:
> I've just noticed that ptsname.3 is also missing  #define _XOPEN_SOURCE
> in its synopsis; however  #define _XOPEN_SOURCE  does not seem to work.

Did you define it to 500, or an empty value?

You need to define it to an appropriate value.  (The synopsis is a bit
misleading, and we could/should specify the minimum value.)

> > Have a lovely day!
> 
> You too!  :-)

:-)

Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] grantpt.3: explicitly mention #define _XOPEN_SOURCE requirement

[Emanuele Torre]

On Sun, May 26, 2024 at 04:54:26PM +0200, Alejandro Colomar wrote:
> Hi Emanuele,
> 
> On Sun, May 26, 2024 at 04:19:30PM GMT, Emanuele Torre wrote:
> > I've just noticed that ptsname.3 is also missing  #define _XOPEN_SOURCE
> > in its synopsis; however  #define _XOPEN_SOURCE  does not seem to work.
> Did you define it to 500, or an empty value?

empty value.

> 
> You need to define it to an appropriate value.  (The synopsis is a bit
> misleading, and we could/should specify the minimum value.)

I did notice the

    ptsname():
        Since glibc 2.24:
            _XOPEN_SOURCE >= 500
        glibc 2.23 and earlier:
            _XOPEN_SOURCE

But that is the same text that appears in grantpt.3 and unlockpt.3, and
they get included with just _XOPEN_SOURCE.

I also noticed it this morning when I sent my patch for grantpt.3, but I
ignored it assuming I probably misunderstood its meaning since it worked
with just _XOPEN_SOURCE.

Does this mean that my grantpt.3 patch is wrong?

And that  #define _XOPEN_SOURCE  in the synopsys of unlockpt.3 is also
wrong?

I should not use just  #define _XOPEN_SOURCE  without a value in my
programs if I want to use ptsname(3), grantpt(3), unlockpt(3)?

o/
 emanuele6

Re: [PATCH] grantpt.3: explicitly mention #define _XOPEN_SOURCE requirement

[Alejandro Colomar]

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

Hi Emanuele,

On Sun, May 26, 2024 at 05:11:58PM GMT, Emanuele Torre wrote:
> > On Sun, May 26, 2024 at 04:19:30PM GMT, Emanuele Torre wrote:
> > > I've just noticed that ptsname.3 is also missing  #define _XOPEN_SOURCE
> > > in its synopsis; however  #define _XOPEN_SOURCE  does not seem to work.
> > Did you define it to 500, or an empty value?
> 
> empty value.

Hmm.

> > You need to define it to an appropriate value.  (The synopsis is a bit
> > misleading, and we could/should specify the minimum value.)
> 
> I did notice the
> 
>     ptsname():
>         Since glibc 2.24:
>             _XOPEN_SOURCE >= 500
>         glibc 2.23 and earlier:
>             _XOPEN_SOURCE
> 
> But that is the same text that appears in grantpt.3 and unlockpt.3, and
> they get included with just _XOPEN_SOURCE.
> 
> I also noticed it this morning when I sent my patch for grantpt.3, but I
> ignored it assuming I probably misunderstood its meaning since it worked
> with just _XOPEN_SOURCE.

I also noticed and ignored it, since I saw the same text in the other
pages.

> Does this mean that my grantpt.3 patch is wrong?
> 
> And that  #define _XOPEN_SOURCE  in the synopsys of unlockpt.3 is also
> wrong?

Regardless of it being correct or not, I think using the definition
used by newer glibc versions is better, so we could update the SYNOPSIS
of all pages to show the requirements of the latest glibc.

> I should not use just  #define _XOPEN_SOURCE  without a value in my
> programs if I want to use ptsname(3), grantpt(3), unlockpt(3)?

TBH, I don't know.  AFAICS, _XOPEN_SOURCE without specifying a value
means POSIX.1‐1990 (maybe? not sure).  That is so obsolete these days
that I don't know what it means.  Does it provide ptsname(3)? I don't
know.  But yeah, I'd say just don't use it.

These days, POSIX.1-2001 is granted everywhere (except maybe some dying
proprietary systems), and even POSIX.1-2008 if you restrict yourself to
Linux and the BSDs.  I suggest using the flags that enable one of these
more recent standards.

Maybe glibc people can say why there's a difference between the
functions, though, which I can't explain.

If you want to send a patch for fixing the SYNOPSIS, please go ahead.

Have a lovely day!
Alex

> 
> o/
>  emanuele6

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] grantpt.3: explicitly mention #define _XOPEN_SOURCE requirement

[Emanuele Torre]

On Sun, May 26, 2024 at 06:38:35PM +0200, Alejandro Colomar wrote:
> Hi Emanuele,
> 
> On Sun, May 26, 2024 at 05:11:58PM GMT, Emanuele Torre wrote:
> > > On Sun, May 26, 2024 at 04:19:30PM GMT, Emanuele Torre wrote:
> > > > I've just noticed that ptsname.3 is also missing  #define _XOPEN_SOURCE
> > > > in its synopsis; however  #define _XOPEN_SOURCE  does not seem to work.
> > > Did you define it to 500, or an empty value?
> > 
> > empty value.
> 
> Hmm.
> 
> > > You need to define it to an appropriate value.  (The synopsis is a bit
> > > misleading, and we could/should specify the minimum value.)
> > 
> > I did notice the
> > 
> >     ptsname():
> >         Since glibc 2.24:
> >             _XOPEN_SOURCE >= 500
> >         glibc 2.23 and earlier:
> >             _XOPEN_SOURCE
> > 
> > But that is the same text that appears in grantpt.3 and unlockpt.3, and
> > they get included with just _XOPEN_SOURCE.
> > 
> > I also noticed it this morning when I sent my patch for grantpt.3, but I
> > ignored it assuming I probably misunderstood its meaning since it worked
> > with just _XOPEN_SOURCE.
> 
> I also noticed and ignored it, since I saw the same text in the other
> pages.

Yes, I copied the line from unlockpt.3 after seeing it there, and seeing
it resolved the issue.

> 
> > Does this mean that my grantpt.3 patch is wrong?
> > 
> > And that  #define _XOPEN_SOURCE  in the synopsys of unlockpt.3 is also
> > wrong?
> 
> Regardless of it being correct or not, I think using the definition
> used by newer glibc versions is better, so we could update the SYNOPSIS
> of all pages to show the requirements of the latest glibc.
> 
> > I should not use just  #define _XOPEN_SOURCE  without a value in my
> > programs if I want to use ptsname(3), grantpt(3), unlockpt(3)?
> 
> TBH, I don't know.  AFAICS, _XOPEN_SOURCE without specifying a value
> means POSIX.1‐1990 (maybe? not sure).  That is so obsolete these days
> that I don't know what it means.  Does it provide ptsname(3)? I don't
> know.  But yeah, I'd say just don't use it.
> 
> These days, POSIX.1-2001 is granted everywhere (except maybe some dying
> proprietary systems), and even POSIX.1-2008 if you restrict yourself to
> Linux and the BSDs.  I suggest using the flags that enable one of these
> more recent standards.

Yes, I guess when necessary it's probably easier to just always use
#define _GNU_SOURCE   instead of messing with _XOPEN_SOURCE,
_POSIX_C_SOURCE, etc.

o/
 emanuele6