ptsname.3: accommodate upcoming POSIX Issue 8 ptsname_r

POSIX has accepted a proposal[1] to add glibc-compatible ptsname_r.  It
indicates an error by returning the error number, rather than returning
-1 and setting errno.  Update RETURN VALUES in ptsname_r's man page now
to encourage folks to test that the return value != 0 rather than == -1.

[1] https://www.austingroupbugs.net/bug_view_page.php?bug_id=508

Reported by:	Collin Funk
Reviewed by:	kib
Sponsored by:	The FreeBSD Foundation
Differential Revision: https://reviews.freebsd.org/D42204

(cherry picked from commit a5ed6a815e38d6c622cd97a6020592ded579cf7a)

1 files changed, 15 insertions, 2 deletions

diff --git a/lib/libc/stdlib/ptsname.3 b/lib/libc/stdlib/ptsname.3
index 532ce9e92ae0..df23e9ae6129 100644
--- a/lib/libc/stdlib/ptsname.3
+++ b/lib/libc/stdlib/ptsname.3
@@ -29,7 +29,7 @@
 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 17, 2020
+.Dd October 14, 2023
 .Dt PTSNAME 3
 .Os
 .Sh NAME
@@ -104,7 +104,7 @@ function clears the lock held on the pseudo-terminal pair
 for the master device specified with
 .Fa fildes .
 .Sh RETURN VALUES
-.Rv -std grantpt ptsname_r unlockpt
+.Rv -std grantpt unlockpt
 .Pp
 The
 .Fn ptsname
@@ -112,6 +112,19 @@ function returns a pointer to the name
 of the slave device on success; otherwise a
 .Dv NULL
 pointer is returned.
+.Pp
+The
+.Fn ptsname_r
+function returns the value 0 if successful;
+otherwise a nonzero value is returned and the global variable
+.Va errno
+is set to indicate the error.
+Note:
+.Fn ptsname_r
+was previously documented as returning -1 on error.
+In the future it will be changed to return an error number, for POSIX
+compatibility.
+Therefore, callers should not check for -1.
 .Sh ERRORS
 The
 .Fn grantpt ,