man3/tmpnam.3

   1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" 2003-11-15, aeb, added tmpnam_r
  26 .\"
  27 .TH TMPNAM 3  2017-09-15 "" "Linux Programmer's Manual"
  28 .SH NAME
  29 tmpnam, tmpnam_r \- create a name for a temporary file
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <stdio.h>
  33 .PP
  34 .BI "char *tmpnam(char *" s );
  35 .BI "char *tmpnam_r(char *" s );
  36 .fi
  37 .PP
  38 .in -4n
  39 Feature Test Macro Requirements for glibc (see
  40 .BR feature_test_macros (7)):
  41 .in
  42 .PP
  43 .BR tmpnam_r ()
  44 .PD 0
  45 .ad l
  46 .RS 4
  47 .TP 4
  48 Since glibc 2.19:
  49 _DEFAULT_SOURCE
  50 .TP
  51 Up to and including glibc 2.19:
  52 _BSD_SOURCE || _SVID_SOURCE
  53 .RE
  54 .ad
  55 .PD
  56 .SH DESCRIPTION
  57 .B Note:
  58 avoid using these functions; use
  59 .BR mkstemp (3)
  60 or
  61 .BR tmpfile (3)
  62 instead.
  63 .PP
  64 The
  65 .BR tmpnam ()
  66 function returns a pointer to a string that is a valid filename,
  67 and such that a file with this name did not exist at some point
  68 in time, so that naive programmers may think it
  69 a suitable name for a temporary file.
  70 If the argument
  71 .I s
  72 is NULL, this name is generated in an internal static buffer
  73 and may be overwritten by the next call to
  74 .BR tmpnam ().
  75 If
  76 .I s
  77 is not NULL, the name is copied to the character array (of length
  78 at least
  79 .IR L_tmpnam )
  80 pointed to by
  81 .I s
  82 and the value
  83 .I s
  84 is returned in case of success.
  85 .PP
  86 The created pathname has a directory prefix
  87 .IR P_tmpdir .
  88 (Both
  89 .I L_tmpnam
  90 and
  91 .I P_tmpdir
  92 are defined in
  93 .IR <stdio.h> ,
  94 just like the
  95 .B TMP_MAX
  96 mentioned below.)
  97 .PP
  98 The
  99 .BR tmpnam_r ()
 100 function performs the same task as
 101 .BR tmpnam (),
 102 but returns NULL (to indicate an error) if
 103 .I s
 104 is NULL.
 105 .SH RETURN VALUE
 106 These functions return a pointer to a unique temporary
 107 filename, or NULL if a unique name cannot be generated.
 108 .SH ERRORS
 109 No errors are defined.
 110 .SH ATTRIBUTES
 111 For an explanation of the terms used in this section, see
 112 .BR attributes (7).
 113 .TS
 114 allbox;
 115 lb lb lb
 116 l l l.
 117 Interface       Attribute       Value
 118 T{
 119 .BR tmpnam ()
 120 T}      Thread safety   MT-Unsafe race:tmpnam/!s
 121 T{
 122 .BR tmpnam_r ()
 123 T}      Thread safety   MT-Safe
 124 .TE
 125 .SH CONFORMING TO
 126 .BR tmpnam ():
 127 SVr4, 4.3BSD, C89, C99, POSIX.1-2001.
 128 POSIX.1-2008 marks
 129 .BR tmpnam ()
 130 as obsolete.
 131 .PP
 132 .BR tmpnam_r ()
 133 is a nonstandard extension that is also available
 134 .\" Appears to be on Solaris
 135 on a few other systems.
 136 .SH NOTES
 137 The
 138 .BR tmpnam ()
 139 function generates a different string each time it is called,
 140 up to
 141 .B TMP_MAX
 142 times.
 143 If it is called more than
 144 .B TMP_MAX
 145 times,
 146 the behavior is implementation defined.
 147 .PP
 148 Although these functions generate names that are difficult to guess,
 149 it is nevertheless possible that between the time that
 150 the pathname is returned and the time that the program opens it,
 151 another program might create that pathname using
 152 .BR open (2),
 153 or create it as a symbolic link.
 154 This can lead to security holes.
 155 To avoid such possibilities, use the
 156 .BR open (2)
 157 .B O_EXCL
 158 flag to open the pathname.
 159 Or better yet, use
 160 .BR mkstemp (3)
 161 or
 162 .BR tmpfile (3).
 163 .PP
 164 Portable applications that use threads cannot call
 165 .BR tmpnam ()
 166 with a NULL argument if either
 167 .B _POSIX_THREADS
 168 or
 169 .B _POSIX_THREAD_SAFE_FUNCTIONS
 170 is defined.
 171 .SH BUGS
 172 Never use these functions.
 173 Use
 174 .BR mkstemp (3)
 175 or
 176 .BR tmpfile (3)
 177 instead.
 178 .SH SEE ALSO
 179 .BR mkstemp (3),
 180 .BR mktemp (3),
 181 .BR tempnam (3),
 182 .BR tmpfile (3)