original/man3/tmpnam.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 .\" 2003-11-15, aeb, added tmpnam_r
  26 .\"
  27 .TH TMPNAM 3  2014-02-27 "" "Linux Programmer's Manual"
  28 .SH NAME
  29 tmpnam, tmpnam_r \- create a name for a temporary file
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <stdio.h>
  33 .sp
  34 .BI "char *tmpnam(char *" s );
  35 .fi
  36 .SH DESCRIPTION
  37 .B Note:
  38 Avoid use of
  39 .BR tmpnam ();
  40 use
  41 .BR mkstemp (3)
  42 or
  43 .BR tmpfile (3)
  44 instead.
  45
  46 The
  47 .BR tmpnam ()
  48 function returns a pointer to a string that is a valid filename,
  49 and such that a file with this name did not exist at some point
  50 in time, so that naive programmers may think it
  51 a suitable name for a temporary file.
  52 If the argument
  53 .I s
  54 is NULL, this name is generated in an internal static buffer
  55 and may be overwritten by the next call to
  56 .BR tmpnam ().
  57 If
  58 .I s
  59 is not NULL, the name is copied to the character array (of length
  60 at least
  61 .IR L_tmpnam )
  62 pointed to by
  63 .I s
  64 and the value
  65 .I s
  66 is returned in case of success.
  67 .LP
  68 The pathname that is created, has a directory prefix
  69 .IR P_tmpdir .
  70 (Both
  71 .I L_tmpnam
  72 and
  73 .I P_tmpdir
  74 are defined in
  75 .IR <stdio.h> ,
  76 just like the
  77 .B TMP_MAX
  78 mentioned below.)
  79 .SH RETURN VALUE
  80 The
  81 .BR tmpnam ()
  82 function returns a pointer to a unique temporary
  83 filename, or NULL if a unique name cannot be generated.
  84 .SH ERRORS
  85 No errors are defined.
  86 .SH ATTRIBUTES
  87 .SS Multithreading (see pthreads(7))
  88 The
  89 .BR tmpnam ()
  90 function is thread-safe with exceptions.
  91 It is not thread-safe if called with a NULL parameter.
  92 .LP
  93 The
  94 .BR tmpnam_r ()
  95 function is thread-safe.
  96 .SH CONFORMING TO
  97 SVr4, 4.3BSD, C89, C99, POSIX.1-2001.
  98 POSIX.1-2008 marks
  99 .BR tmpnam ()
 100 as obsolete.
 101 .SH NOTES
 102 The
 103 .BR tmpnam ()
 104 function generates a different string each time it is called,
 105 up to
 106 .B TMP_MAX
 107 times.
 108 If it is called more than
 109 .B TMP_MAX
 110 times,
 111 the behavior is implementation defined.
 112 .LP
 113 Although
 114 .BR tmpnam ()
 115 generates names that are difficult to guess,
 116 it is nevertheless possible that between the time that
 117 .BR tmpnam ()
 118 returns a pathname, and the time that the program opens it,
 119 another program might create that pathname using
 120 .BR open (2),
 121 or create it as a symbolic link.
 122 This can lead to security holes.
 123 To avoid such possibilities, use the
 124 .BR open (2)
 125 .B O_EXCL
 126 flag to open the pathname.
 127 Or better yet, use
 128 .BR mkstemp (3)
 129 or
 130 .BR tmpfile (3).
 131 .LP
 132 Portable applications that use threads cannot call
 133 .BR tmpnam ()
 134 with a NULL argument if either
 135 .B _POSIX_THREADS
 136 or
 137 .B _POSIX_THREAD_SAFE_FUNCTIONS
 138 is defined.
 139 .LP
 140 A POSIX draft proposed to use a function
 141 .BR tmpnam_r ()
 142 defined by
 143 .sp
 144 .nf
 145 .in +4n
 146 char *
 147 tmpnam_r(char *s)
 148 {
 149     return s ? tmpnam(s) : NULL;
 150 }
 151 .in
 152 .fi
 153 .sp
 154 apparently as a warning not to use NULL.
 155 A few systems implement it.
 156 To get a glibc prototype for this function from
 157 .IR <stdio.h> ,
 158 define
 159 .B _SVID_SOURCE
 160 or
 161 .B _BSD_SOURCE
 162 (before including
 163 .I any
 164 header file).
 165 .SH BUGS
 166 Never use this function.
 167 Use
 168 .BR mkstemp (3)
 169 or
 170 .BR tmpfile (3)
 171 instead.
 172 .SH SEE ALSO
 173 .BR mkstemp (3),
 174 .BR mktemp (3),
 175 .BR tempnam (3),
 176 .BR tmpfile (3)
 177 .SH COLOPHON
 178 This page is part of release 3.78 of the Linux
 179 .I man-pages
 180 project.
 181 A description of the project,
 182 information about reporting bugs,
 183 and the latest version of this page,
 184 can be found at
 185 \%http://www.kernel.org/doc/man\-pages/.