ptsname.3: Fix description of failure behaviour of ptsname_r()

The Linux man page for ptsname_r, when describing the behaviour
in the error case, is
  - not consistent with the future POSIX standard (POSIX Issue 8).
  - not consistent with musl libc.

Find attached a patch to
  - keep it consistent with what glibc does,
  - make it consistent with musl libc,
  - make it consistent with the future POSIX standard (POSIX
    Issue 8).

Details:

glibc's implementation of ptsname_r, when it fails, returns the
error code as return value AND sets errno. See
https://sourceware.org/git/?p=glibc.git;a=blob;f=login/ptsname.c
https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/mach/hurd/ptsname.c
https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/unix/sysv/linux/ptsname.c

musl's implementation of ptsname_r, when it fails, returns the error code
but does NOT set errno. See
https://git.musl-libc.org/cgit/musl/tree/src/misc/pty.c

The proposal to add ptsname_r to POSIX, with text

  "If successful, the ptsname_r( ) function shall return zero.
   Otherwise, an error number shall be returned to indicate the
   error."

has been accepted for inclusion in POSIX Issue 8.
http://austingroupbugs.net/view.php?id=508

Therefore a portable program should look at the return value from
ptsname_r, NOT the errno value. The current text in the man page
suggests to look at the errno value, which is wrong (because of
musl libc) and not future-proof (because of future POSIX).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/ptsname.3 b/man3/ptsname.3
index 394138b7a4c11f03e409ce4c4beb14ba0c6d22b0..0137fe741f37da18ef3ede07a804cd601ab1e6b6 100644 (file)
--- a/man3/ptsname.3
+++ b/man3/ptsname.3
@@ -63,12 +63,9 @@ On failure, NULL is returned.
 On success,
 .BR ptsname_r ()
 returns 0.
-On failure, a nonzero value is returned
-and
-.I errno
-is set to indicate the error.
-.\" In fact the errno value is also returned as the function
-.\" result -- MTK, Dec 04
+On failure, an error number is returned to indicate the error.
+.\" In glibc, the error number is not only returned as the return value
+.\" but also stored in errno. But this is not true for musl libc.
 .SH ERRORS
 .TP
 .B EINVAL