man3/tmpnam.3

   1 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" 2003-11-15, aeb, added tmpnam_r
   6 .\"
   7 .TH tmpnam 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 tmpnam, tmpnam_r \- create a name for a temporary file
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <stdio.h>
  16 .PP
  17 .BI "char *tmpnam(char *" s );
  18 .BI "char *tmpnam_r(char *" s );
  19 .fi
  20 .PP
  21 .RS -4
  22 Feature Test Macro Requirements for glibc (see
  23 .BR feature_test_macros (7)):
  24 .RE
  25 .PP
  26 .BR tmpnam_r ()
  27 .nf
  28     Since glibc 2.19:
  29         _DEFAULT_SOURCE
  30     Up to and including glibc 2.19:
  31         _BSD_SOURCE || _SVID_SOURCE
  32 .fi
  33 .SH DESCRIPTION
  34 .B Note:
  35 avoid using these functions; use
  36 .BR mkstemp (3)
  37 or
  38 .BR tmpfile (3)
  39 instead.
  40 .PP
  41 The
  42 .BR tmpnam ()
  43 function returns a pointer to a string that is a valid filename,
  44 and such that a file with this name did not exist at some point
  45 in time, so that naive programmers may think it
  46 a suitable name for a temporary file.
  47 If the argument
  48 .I s
  49 is NULL, this name is generated in an internal static buffer
  50 and may be overwritten by the next call to
  51 .BR tmpnam ().
  52 If
  53 .I s
  54 is not NULL, the name is copied to the character array (of length
  55 at least
  56 .IR L_tmpnam )
  57 pointed to by
  58 .I s
  59 and the value
  60 .I s
  61 is returned in case of success.
  62 .PP
  63 The created pathname has a directory prefix
  64 .IR P_tmpdir .
  65 (Both
  66 .I L_tmpnam
  67 and
  68 .I P_tmpdir
  69 are defined in
  70 .IR <stdio.h> ,
  71 just like the
  72 .B TMP_MAX
  73 mentioned below.)
  74 .PP
  75 The
  76 .BR tmpnam_r ()
  77 function performs the same task as
  78 .BR tmpnam (),
  79 but returns NULL (to indicate an error) if
  80 .I s
  81 is NULL.
  82 .SH RETURN VALUE
  83 These functions return a pointer to a unique temporary
  84 filename, or NULL if a unique name cannot be generated.
  85 .SH ERRORS
  86 No errors are defined.
  87 .SH ATTRIBUTES
  88 For an explanation of the terms used in this section, see
  89 .BR attributes (7).
  90 .ad l
  91 .nh
  92 .TS
  93 allbox;
  94 lbx lb lb
  95 l l l.
  96 Interface       Attribute       Value
  97 T{
  98 .BR tmpnam ()
  99 T}      Thread safety   MT-Unsafe race:tmpnam/!s
 100 T{
 101 .BR tmpnam_r ()
 102 T}      Thread safety   MT-Safe
 103 .TE
 104 .hy
 105 .ad
 106 .sp 1
 107 .SH STANDARDS
 108 .BR tmpnam ():
 109 SVr4, 4.3BSD, C89, C99, POSIX.1-2001.
 110 POSIX.1-2008 marks
 111 .BR tmpnam ()
 112 as obsolete.
 113 .PP
 114 .BR tmpnam_r ()
 115 is a nonstandard extension that is also available
 116 .\" Appears to be on Solaris
 117 on a few other systems.
 118 .SH NOTES
 119 The
 120 .BR tmpnam ()
 121 function generates a different string each time it is called,
 122 up to
 123 .B TMP_MAX
 124 times.
 125 If it is called more than
 126 .B TMP_MAX
 127 times,
 128 the behavior is implementation defined.
 129 .PP
 130 Although these functions generate names that are difficult to guess,
 131 it is nevertheless possible that between the time that
 132 the pathname is returned and the time that the program opens it,
 133 another program might create that pathname using
 134 .BR open (2),
 135 or create it as a symbolic link.
 136 This can lead to security holes.
 137 To avoid such possibilities, use the
 138 .BR open (2)
 139 .B O_EXCL
 140 flag to open the pathname.
 141 Or better yet, use
 142 .BR mkstemp (3)
 143 or
 144 .BR tmpfile (3).
 145 .PP
 146 Portable applications that use threads cannot call
 147 .BR tmpnam ()
 148 with a NULL argument if either
 149 .B _POSIX_THREADS
 150 or
 151 .B _POSIX_THREAD_SAFE_FUNCTIONS
 152 is defined.
 153 .SH BUGS
 154 Never use these functions.
 155 Use
 156 .BR mkstemp (3)
 157 or
 158 .BR tmpfile (3)
 159 instead.
 160 .SH SEE ALSO
 161 .BR mkstemp (3),
 162 .BR mktemp (3),
 163 .BR tempnam (3),
 164 .BR tmpfile (3)