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