| Message ID | ZDan06Yc9Xex3rfq@starmint |
|---|---|
| State | New |
| Headers | show |
| Series | [1/1] document posix_openpt | expand |
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.
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.
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.
On Wed, Apr 26, 2023 at 01:20:45PM +0100, Adhemerval Zanella Netto wrote: > 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. Thank you!
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;