original/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  2014-02-27 "" "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 CONFORMING TO
 106 SVr4, 4.3BSD, POSIX.1-2001.
 107 POSIX.1-2008 marks
 108 .BR tempnam ()
 109 as obsolete.
 110 .SH NOTES
 111 Although
 112 .BR tempnam ()
 113 generates names that are difficult to guess,
 114 it is nevertheless possible that between the time that
 115 .BR tempnam ()
 116 returns a pathname, and the time that the program opens it,
 117 another program might create that pathname using
 118 .BR open (2),
 119 or create it as a symbolic link.
 120 This can lead to security holes.
 121 To avoid such possibilities, use the
 122 .BR open (2)
 123 .B O_EXCL
 124 flag to open the pathname.
 125 Or better yet, use
 126 .BR mkstemp (3)
 127 or
 128 .BR tmpfile (3).
 129
 130 SUSv2 does not mention the use of
 131 .BR TMPDIR ;
 132 glibc will use it only
 133 when the program is not set-user-ID.
 134 On SVr4, the directory used under \fBd)\fP is
 135 .I /tmp
 136 (and this is what glibc does).
 137 .LP
 138 Because it dynamically allocates memory used to return the pathname,
 139 .BR tempnam ()
 140 is reentrant, and thus thread safe, unlike
 141 .BR tmpnam (3).
 142 .LP
 143 The
 144 .BR tempnam ()
 145 function generates a different string each time it is called,
 146 up to
 147 .B TMP_MAX
 148 (defined in
 149 .IR <stdio.h> )
 150 times.
 151 If it is called more than
 152 .B TMP_MAX
 153 times,
 154 the behavior is implementation defined.
 155 .LP
 156 .BR tempnam ()
 157 uses at most the first five bytes from
 158 .IR pfx .
 159
 160 The glibc implementation of
 161 .BR tempnam ()
 162 will fail with the error
 163 .B EEXIST
 164 upon failure to find a unique name.
 165 .SH BUGS
 166 The precise meaning of "appropriate" is undefined;
 167 it is unspecified how accessibility of a directory is determined.
 168 .SH SEE ALSO
 169 .BR mkstemp (3),
 170 .BR mktemp (3),
 171 .BR tmpfile (3),
 172 .BR tmpnam (3)
 173 .SH COLOPHON
 174 This page is part of release 3.67 of the Linux
 175 .I man-pages
 176 project.
 177 A description of the project,
 178 information about reporting bugs,
 179 and the latest version of this page,
 180 can be found at
 181 \%http://www.kernel.org/doc/man\-pages/.