man3/tempnam.3

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