tmpnam.3: Properly document tmpnam_r(3)

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

diff --git a/man3/tmpnam.3 b/man3/tmpnam.3
index de7d35b8e31faa1d0a2e8357789a4f883b3549a5..0b9d03ba3dff51cb5ef3461804d8b06b55d23488 100644 (file)
--- a/man3/tmpnam.3
+++ b/man3/tmpnam.3
@@ -30,14 +30,32 @@ tmpnam, tmpnam_r \- create a name for a temporary file
 .SH SYNOPSIS
 .nf
 .B #include <stdio.h>
-.sp
+
 .BI "char *tmpnam(char *" s );
+.BI "char *tmpnam_r(char *" s );
 .fi
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR tmpnam_r ()
+.PD 0
+.ad l
+.RS 4
+.TP 4
+Since glibc 2.19:
+_DEFAULT_SOURCE
+.TP
+Up to and including glibc 2.19:
+_BSD_SOURCE || _SVID_SOURCE
+.RE
+.ad
+.PD
 .SH DESCRIPTION
 .B Note:
-Avoid use of
-.BR tmpnam ();
-use
+avoid using these functions; use
 .BR mkstemp (3)
 or
 .BR tmpfile (3)
@@ -76,10 +94,16 @@ are defined in
 just like the
 .B TMP_MAX
 mentioned below.)
-.SH RETURN VALUE
+
 The
-.BR tmpnam ()
-function returns a pointer to a unique temporary
+.BR tmpnam_r ()
+function performs the same task as
+.BR tmpnam (),
+but returns NULL (to indicate an error) if
+.I s
+is NULL.
+.SH RETURN VALUE
+These functions return a pointer to a unique temporary
 filename, or NULL if a unique name cannot be generated.
 .SH ERRORS
 No errors are defined.
@@ -99,10 +123,16 @@ T{
 T}     Thread safety   MT-Safe
 .TE
 .SH CONFORMING TO
+.BR tmpnam ():
 SVr4, 4.3BSD, C89, C99, POSIX.1-2001.
 POSIX.1-2008 marks
 .BR tmpnam ()
 as obsolete.
+
+.BR tmpnam_r ()
+is a nonstandard extension that is also available
+.\" Appears to be on Solaris
+on a few other systems.
 .SH NOTES
 The
 .BR tmpnam ()
@@ -115,12 +145,9 @@ If it is called more than
 times,
 the behavior is implementation defined.
 .LP
-Although
-.BR tmpnam ()
-generates names that are difficult to guess,
+Although these functions generate names that are difficult to guess,
 it is nevertheless possible that between the time that
-.BR tmpnam ()
-returns a pathname, and the time that the program opens it,
+the pathname is returned and the time that the program opens it,
 another program might create that pathname using
 .BR open (2),
 or create it as a symbolic link.
@@ -141,25 +168,8 @@ with a NULL argument if either
 or
 .B _POSIX_THREAD_SAFE_FUNCTIONS
 is defined.
-.LP
-A POSIX draft proposed to use a function
-.BR tmpnam_r ()
-defined by
-.sp
-.nf
-.in +4n
-char *
-tmpnam_r(char *s)
-{
-    return s ? tmpnam(s) : NULL;
-}
-.in
-.fi
-.sp
-apparently as a warning not to use NULL.
-A few systems implement it and an implementation is provided in glibc.
 .SH BUGS
-Never use this function.
+Never use these functions.
 Use
 .BR mkstemp (3)
 or