Libc-1272.250.1.tar.gz

[apple/libc.git] / stdlib / grantpt.3

diff --git a/stdlib/grantpt.3 b/stdlib/grantpt.3
index eb70e740ebe25123f4efc67a8a571d13fd57dae0..2f8c18928978814aa30273e3ac1678f771df4c10 100644 (file)
--- a/stdlib/grantpt.3
+++ b/stdlib/grantpt.3
@@ -38,6 +38,7 @@
 .Nm grantpt ,
 .Nm posix_openpt ,
 .Nm ptsname ,
+.Nm ptsname_r ,
 .Nm unlockpt
 .Nd pseudo-terminal access functions
 .Sh SYNOPSIS
@@ -50,6 +51,12 @@
 .Fo ptsname
 .Fa "int fildes"
 .Fc
+.Ft "int"
+.Fo ptsname_r
+.Fa "int fildes"
+.Fa "char *buffer"
+.Fa "size_t buflen"
+.Fc
 .Ft int
 .Fo unlockpt
 .Fa "int fildes"
@@ -64,11 +71,12 @@
 The
 .Fn grantpt ,
 .Fn ptsname ,
+.Fn ptsname_r ,
 .Fn unlockpt ,
 and
 .Fn posix_openpt
 functions allow access to pseudo-terminal devices.
-The first three functions accept a file descriptor
+The first four functions accept a file descriptor
 that references the master half of a pseudo-terminal pair.
 This file descriptor is created with
 .Fn posix_openpt .
@@ -89,7 +97,9 @@ is left untouched.
 .Pp
 The
 .Fn ptsname
-function returns the full pathname of the slave device
+and
+.Fn ptsname_r
+functions return the full pathname of the slave device
 counterpart to the master device specified with
 .Fa fildes .
 This value can be used
@@ -97,7 +107,11 @@ to subsequently open the appropriate slave after
 .Fn posix_openpt
 and
 .Fn grantpt
-have been called.
+have been called. The
+.Fn ptsname
+function is not guaranteed to be reentrant or thread safe. The
+.Fn ptsname_r
+function takes a buffer and length as arguments to avoid this problem.
 .Pp
 The
 .Fn unlockpt
@@ -134,6 +148,12 @@ pointer is returned and the global variable
 is set to indicate the error.
 .Pp
 The
+.Fn ptsname_r
+function returns 0 if successful.  On failure, it returns -1 and the global variable
+.Va errno
+is set to indicate the error.
+.Pp
+The
 .Fn posix_openpt
 function returns a file descriptor to the first
 available master pseudo-terminal device on success;
@@ -144,6 +164,7 @@ is set to indicate the error.
 The
 .Fn grantpt ,
 .Fn ptsname ,
+.Fn ptsname_r ,
 and
 .Fn unlockpt
 functions may fail and set
@@ -156,6 +177,24 @@ is not a master pseudo-terminal device.
 .El
 .Pp
 In addition, the
+.Fn ptsname_r
+function may set
+.Va errno
+to:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The
+.Va buffer
+argument is NULL.
+.El
+.Bl -tag -width Er
+.It Bq Er ERANGE
+The
+.Va bufsize
+argument is smaller than the length of the string to be returned.
+.El
+.Pp
+In addition, the
 .Fn grantpt
 function may set
 .Va errno
@@ -181,6 +220,7 @@ The system has no available pseudo-terminal devices.
 The
 .Fn grantpt ,
 .Fn ptsname ,
+.Fn ptsname_r ,
 and
 .Fn unlockpt
 functions may also fail and set