man3/tempnam.3

   1 '\" t
   2 .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH tempnam 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 tempnam \- create a name for a temporary file
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <stdio.h>
  15 .P
  16 .BI "char *tempnam(const char *" dir ", const char *" pfx );
  17 .fi
  18 .P
  19 .RS -4
  20 Feature Test Macro Requirements for glibc (see
  21 .BR feature_test_macros (7)):
  22 .RE
  23 .P
  24 .BR tempnam ():
  25 .nf
  26     Since glibc 2.19:
  27         _DEFAULT_SOURCE
  28     glibc 2.19 and earlier:
  29         _BSD_SOURCE || _SVID_SOURCE
  30 .fi
  31 .SH DESCRIPTION
  32 .I "Never use this function."
  33 Use
  34 .BR mkstemp (3)
  35 or
  36 .BR tmpfile (3)
  37 instead.
  38 .P
  39 The
  40 .BR tempnam ()
  41 function returns a pointer to a string that is a valid filename,
  42 and such that a file with this name did not exist when
  43 .BR tempnam ()
  44 checked.
  45 The filename suffix of the pathname generated will start with
  46 .I pfx
  47 in case
  48 .I pfx
  49 is a non-NULL string of at most five bytes.
  50 The directory prefix part of the pathname generated is required to
  51 be "appropriate" (often that at least implies writable).
  52 .P
  53 Attempts to find an appropriate directory go through the following
  54 steps:
  55 .TP 3
  56 a)
  57 In case the environment variable
  58 .B TMPDIR
  59 exists and
  60 contains the name of an appropriate directory, that is used.
  61 .TP
  62 b)
  63 Otherwise, if the
  64 .I dir
  65 argument is non-NULL and appropriate, it is used.
  66 .TP
  67 c)
  68 Otherwise,
  69 .I P_tmpdir
  70 (as defined in
  71 .IR <stdio.h> )
  72 is used when appropriate.
  73 .TP
  74 d)
  75 Finally an implementation-defined directory may be used.
  76 .P
  77 The string returned by
  78 .BR tempnam ()
  79 is allocated using
  80 .BR malloc (3)
  81 and hence should be freed by
  82 .BR free (3).
  83 .SH RETURN VALUE
  84 On success, the
  85 .BR tempnam ()
  86 function returns a pointer to a unique temporary filename.
  87 It returns NULL if a unique name cannot be generated, with
  88 .I errno
  89 set to indicate the error.
  90 .SH ERRORS
  91 .TP
  92 .B ENOMEM
  93 Allocation of storage failed.
  94 .SH ATTRIBUTES
  95 For an explanation of the terms used in this section, see
  96 .BR attributes (7).
  97 .TS
  98 allbox;
  99 lbx lb lb
 100 l l l.
 101 Interface       Attribute       Value
 102 T{
 103 .na
 104 .nh
 105 .BR tempnam ()
 106 T}      Thread safety   MT-Safe env
 107 .TE
 108 .SH STANDARDS
 109 POSIX.1-2008.
 110 .SH HISTORY
 111 SVr4, 4.3BSD, POSIX.1-2001.
 112 Obsoleted in POSIX.1-2008.
 113 .SH NOTES
 114 Although
 115 .BR tempnam ()
 116 generates names that are difficult to guess,
 117 it is nevertheless possible that between the time that
 118 .BR tempnam ()
 119 returns a pathname, and the time that the program opens it,
 120 another program might create that pathname using
 121 .BR open (2),
 122 or create it as a symbolic link.
 123 This can lead to security holes.
 124 To avoid such possibilities, use the
 125 .BR open (2)
 126 .B O_EXCL
 127 flag to open the pathname.
 128 Or better yet, use
 129 .BR mkstemp (3)
 130 or
 131 .BR tmpfile (3).
 132 .P
 133 SUSv2 does not mention the use of
 134 .BR TMPDIR ;
 135 glibc will use it only
 136 when the program is not set-user-ID.
 137 On SVr4, the directory used under \fBd)\fP is
 138 .I /tmp
 139 (and this is what glibc does).
 140 .P
 141 Because it dynamically allocates memory used to return the pathname,
 142 .BR tempnam ()
 143 is reentrant, and thus thread safe, unlike
 144 .BR tmpnam (3).
 145 .P
 146 The
 147 .BR tempnam ()
 148 function generates a different string each time it is called,
 149 up to
 150 .B TMP_MAX
 151 (defined in
 152 .IR <stdio.h> )
 153 times.
 154 If it is called more than
 155 .B TMP_MAX
 156 times,
 157 the behavior is implementation defined.
 158 .P
 159 .BR tempnam ()
 160 uses at most the first five bytes from
 161 .IR pfx .
 162 .P
 163 The glibc implementation of
 164 .BR tempnam ()
 165 fails with the error
 166 .B EEXIST
 167 upon failure to find a unique name.
 168 .SH BUGS
 169 The precise meaning of "appropriate" is undefined;
 170 it is unspecified how accessibility of a directory is determined.
 171 .SH SEE ALSO
 172 .BR mkstemp (3),
 173 .BR mktemp (3),
 174 .BR tmpfile (3),
 175 .BR tmpnam (3)