* [PATCH 1/1] document posix_openpt
@ 2023-04-12 12:45 Gavin Smith
2023-04-19 12:43 ` Adhemerval Zanella Netto
0 siblings, 1 reply; 5+ messages in thread
From: Gavin Smith @ 2023-04-12 12:45 UTC (permalink / raw)
To: libc-alpha
I copied the safety information from getpt, as I couldn't get this
information in full from anywhere else.
Your patch submission guide is contradictory as to whether to
use Signed-off-by or not
(https://sourceware.org/glibc/wiki/Contribution%20checklist):
> ... you just add a line saying:
> Signed-off-by: ...
> The project does not support or use "Signed-off-by" lines
commit be1468aa984d91e55db7719034ca9b8e53a7a136
Author: Gavin Smith <gavinsmith0123@gmail.com>
Date: Wed Apr 12 13:36:47 2023 +0100
manual: document posix_openpt (bug 17010)
* manual/terminal.texi (Allocation):
Document posix_openpt. State that getpt is similar to posix_openpt.
Use posix_openpt instead of getpt in example.
Signed-off-by: Gavin Smith <gavinsmith0123@gmail.com>
diff --git a/manual/terminal.texi b/manual/terminal.texi
index 7293bfb393..bdaee56053 100644
--- a/manual/terminal.texi
+++ b/manual/terminal.texi
@@ -1947,6 +1947,33 @@ This subsection describes functions for allocating a pseudo-terminal,
and for making this pseudo-terminal available for actual use. These
functions are declared in the header file @file{stdlib.h}.
+@deftypefun int posix_openpt (int @var{flags})
+@standards{POSIX.1, stdlib.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
+
+@code{posix_openpt} returns a new file descriptor for the next
+available master pseudo-terminal. In the case of an error, it returns
+a value of @math{-1} instead, and sets @code{errno} to indicate
+the error. @xref{Opening and Closing Files} for possible values
+of @code{errno}.
+
+@var{flags} is a bit mask created from a bitwise OR of zero or more
+of the following flags:
+
+@table @code
+@item O_RDWR
+Open the device for both reading and writing. It is usual to specify
+this flag.
+@item O_NOCTTY
+Do not make the device the controlling terminal for the process.
+@end table
+
+These flags are defined in @file{fcntl.h}. @xref{Access Modes}.
+
+For this function to be available, @code{_XOPEN_SOURCE} must be defined
+to a value greater than @samp{600}. @xref{Feature Test Macros}.
+@end deftypefun
+
@deftypefun int getpt (void)
@standards{GNU, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
@@ -1957,6 +1984,10 @@ functions are declared in the header file @file{stdlib.h}.
@c a devfs, and returns the fd; static variables devpts_mounted and
@c have_no_dev_ptmx are safely initialized so as to avoid repeated
@c tests.
+
+@code{getpt} is similar to @code{posix_openpt}. This function is a
+GNU extension and should not be used in portable programs.
+
The @code{getpt} function returns a new file descriptor for the next
available master pseudo-terminal. The normal return value from
@code{getpt} is a non-negative integer file descriptor. In the case of
@@ -1967,8 +1998,6 @@ an error, a value of @math{-1} is returned instead. The following
@item ENOENT
There are no free master pseudo-terminals available.
@end table
-
-This function is a GNU extension.
@end deftypefun
@deftypefun int grantpt (int @var{filedes})
@@ -2118,6 +2147,7 @@ This function is a GNU extension.
@end deftypefun
Typical usage of these functions is illustrated by the following example:
+
@smallexample
int
open_pty_pair (int *amaster, int *aslave)
@@ -2125,7 +2155,7 @@ open_pty_pair (int *amaster, int *aslave)
int master, slave;
char *name;
- master = getpt ();
+ master = posix_openpt (O_RDWR | O_NOCTTY);
if (master < 0)
return 0;
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH 1/1] document posix_openpt
2023-04-12 12:45 [PATCH 1/1] document posix_openpt Gavin Smith
@ 2023-04-19 12:43 ` Adhemerval Zanella Netto
2023-04-23 9:35 ` Gavin Smith
0 siblings, 1 reply; 5+ messages in thread
From: Adhemerval Zanella Netto @ 2023-04-19 12:43 UTC (permalink / raw)
To: Gavin Smith, libc-alpha
On 12/04/23 09:45, Gavin Smith via Libc-alpha wrote:
> I copied the safety information from getpt, as I couldn't get this
> information in full from anywhere else.
>
> Your patch submission guide is contradictory as to whether to
> use Signed-off-by or not
> (https://sourceware.org/glibc/wiki/Contribution%20checklist):
>
>> ... you just add a line saying:
>> Signed-off-by: ...
>
>> The project does not support or use "Signed-off-by" lines
>
>
> commit be1468aa984d91e55db7719034ca9b8e53a7a136
> Author: Gavin Smith <gavinsmith0123@gmail.com>
> Date: Wed Apr 12 13:36:47 2023 +0100
>
> manual: document posix_openpt (bug 17010)
>
> * manual/terminal.texi (Allocation):
> Document posix_openpt. State that getpt is similar to posix_openpt.
> Use posix_openpt instead of getpt in example.
>
> Signed-off-by: Gavin Smith <gavinsmith0123@gmail.com>
LGTM, I am just no sure which standard to use.
>
> diff --git a/manual/terminal.texi b/manual/terminal.texi
> index 7293bfb393..bdaee56053 100644
> --- a/manual/terminal.texi
> +++ b/manual/terminal.texi
> @@ -1947,6 +1947,33 @@ This subsection describes functions for allocating a pseudo-terminal,
> and for making this pseudo-terminal available for actual use. These
> functions are declared in the header file @file{stdlib.h}.
>
> +@deftypefun int posix_openpt (int @var{flags})
> +@standards{POSIX.1, stdlib.h}
Shouldn't it be POSIX.2, since it is define for _XOPEN_SOURCE >= 600?
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
> +
> +@code{posix_openpt} returns a new file descriptor for the next
> +available master pseudo-terminal. In the case of an error, it returns
> +a value of @math{-1} instead, and sets @code{errno} to indicate
> +the error. @xref{Opening and Closing Files} for possible values
> +of @code{errno}.
> +
> +@var{flags} is a bit mask created from a bitwise OR of zero or more
> +of the following flags:
> +
> +@table @code
> +@item O_RDWR
> +Open the device for both reading and writing. It is usual to specify
> +this flag.
> +@item O_NOCTTY
> +Do not make the device the controlling terminal for the process.
> +@end table
> +
> +These flags are defined in @file{fcntl.h}. @xref{Access Modes}.
> +
> +For this function to be available, @code{_XOPEN_SOURCE} must be defined
> +to a value greater than @samp{600}. @xref{Feature Test Macros}.
> +@end deftypefun
> +
> @deftypefun int getpt (void)
> @standards{GNU, stdlib.h}
> @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
> @@ -1957,6 +1984,10 @@ functions are declared in the header file @file{stdlib.h}.
> @c a devfs, and returns the fd; static variables devpts_mounted and
> @c have_no_dev_ptmx are safely initialized so as to avoid repeated
> @c tests.
> +
> +@code{getpt} is similar to @code{posix_openpt}. This function is a
> +GNU extension and should not be used in portable programs.
> +
> The @code{getpt} function returns a new file descriptor for the next
> available master pseudo-terminal. The normal return value from
> @code{getpt} is a non-negative integer file descriptor. In the case of
> @@ -1967,8 +1998,6 @@ an error, a value of @math{-1} is returned instead. The following
> @item ENOENT
> There are no free master pseudo-terminals available.
> @end table
> -
> -This function is a GNU extension.
> @end deftypefun
>
> @deftypefun int grantpt (int @var{filedes})
> @@ -2118,6 +2147,7 @@ This function is a GNU extension.
> @end deftypefun
>
> Typical usage of these functions is illustrated by the following example:
> +
> @smallexample
> int
> open_pty_pair (int *amaster, int *aslave)
> @@ -2125,7 +2155,7 @@ open_pty_pair (int *amaster, int *aslave)
> int master, slave;
> char *name;
>
> - master = getpt ();
> + master = posix_openpt (O_RDWR | O_NOCTTY);
> if (master < 0)
> return 0;
>
>
Ok.
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH 1/1] document posix_openpt
2023-04-19 12:43 ` Adhemerval Zanella Netto
@ 2023-04-23 9:35 ` Gavin Smith
2023-04-26 12:20 ` Adhemerval Zanella Netto
0 siblings, 1 reply; 5+ messages in thread
From: Gavin Smith @ 2023-04-23 9:35 UTC (permalink / raw)
To: Adhemerval Zanella Netto; +Cc: libc-alpha
On Wed, Apr 19, 2023 at 09:43:01AM -0300, Adhemerval Zanella Netto wrote:
> LGTM, I am just no sure which standard to use.
>
> >
> > diff --git a/manual/terminal.texi b/manual/terminal.texi
> > index 7293bfb393..bdaee56053 100644
> > --- a/manual/terminal.texi
> > +++ b/manual/terminal.texi
> > @@ -1947,6 +1947,33 @@ This subsection describes functions for allocating a pseudo-terminal,
> > and for making this pseudo-terminal available for actual use. These
> > functions are declared in the header file @file{stdlib.h}.
> >
> > +@deftypefun int posix_openpt (int @var{flags})
> > +@standards{POSIX.1, stdlib.h}
>
> Shouldn't it be POSIX.2, since it is define for _XOPEN_SOURCE >= 600?
I got from the "feature_test_macros" manpage:
(Since glibc 2.2) The value 600 or greater additionally ex‐
poses definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001
base specification plus the XSI extension) and C99 defini‐
tions.
This is why I thought "POSIX.1" was the most appropriate.
POSIX.2 is mentioned in the libc manual, but it doesn't appear to cover
pseudo-terminal functionality:
Some facilities from ‘ISO/IEC 9945-2:1993, the POSIX Shell and
Utilities standard’ (POSIX.2) are also implemented in the GNU C Library.
These include utilities for dealing with regular expressions and other
pattern matching facilities
Existing uses of @standards{POSIX.2, ...} in the manual are consistent
with this.
'./summary.pl --help' doesn't offer any further guidance.
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH 1/1] document posix_openpt
2023-04-23 9:35 ` Gavin Smith
@ 2023-04-26 12:20 ` Adhemerval Zanella Netto
2023-04-26 19:19 ` Gavin Smith
0 siblings, 1 reply; 5+ messages in thread
From: Adhemerval Zanella Netto @ 2023-04-26 12:20 UTC (permalink / raw)
To: Gavin Smith; +Cc: libc-alpha
On 23/04/23 06:35, Gavin Smith wrote:
> On Wed, Apr 19, 2023 at 09:43:01AM -0300, Adhemerval Zanella Netto wrote:
>
>> LGTM, I am just no sure which standard to use.
>>
>>>
>>> diff --git a/manual/terminal.texi b/manual/terminal.texi
>>> index 7293bfb393..bdaee56053 100644
>>> --- a/manual/terminal.texi
>>> +++ b/manual/terminal.texi
>>> @@ -1947,6 +1947,33 @@ This subsection describes functions for allocating a pseudo-terminal,
>>> and for making this pseudo-terminal available for actual use. These
>>> functions are declared in the header file @file{stdlib.h}.
>>>
>>> +@deftypefun int posix_openpt (int @var{flags})
>>> +@standards{POSIX.1, stdlib.h}
>>
>> Shouldn't it be POSIX.2, since it is define for _XOPEN_SOURCE >= 600?
>
> I got from the "feature_test_macros" manpage:
>
> (Since glibc 2.2) The value 600 or greater additionally ex‐
> poses definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001
> base specification plus the XSI extension) and C99 defini‐
> tions.
>
> This is why I thought "POSIX.1" was the most appropriate.
>
> POSIX.2 is mentioned in the libc manual, but it doesn't appear to cover
> pseudo-terminal functionality:
>
> Some facilities from ‘ISO/IEC 9945-2:1993, the POSIX Shell and
> Utilities standard’ (POSIX.2) are also implemented in the GNU C Library.
> These include utilities for dealing with regular expressions and other
> pattern matching facilities
>
> Existing uses of @standards{POSIX.2, ...} in the manual are consistent
> with this.
>
> './summary.pl --help' doesn't offer any further guidance
The posix_openpt was originally added with XPG6 XSI (__USE_XOPEN2KXSI),
which I think it indeed falls on POSIX.1 (although for 2008). So I think
it is correct. I will apply this patch, thanks.
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2023-04-26 19:20 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-04-12 12:45 [PATCH 1/1] document posix_openpt Gavin Smith
2023-04-19 12:43 ` Adhemerval Zanella Netto
2023-04-23 9:35 ` Gavin Smith
2023-04-26 12:20 ` Adhemerval Zanella Netto
2023-04-26 19:19 ` Gavin Smith
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).