lib/libc/stdio/mktemp.3

   1 .\"     $NetBSD: mktemp.3,v 1.24 2003/10/15 19:44:51 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)mktemp.3    8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd July 28, 1998
  33 .Dt MKTEMP 3
  34 .Os
  35 .Sh NAME
  36 .Nm mktemp ,
  37 .Nm mkstemp ,
  38 .Nm mkdtemp
  39 .Nd make unique temporary file or directory name
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In stdlib.h
  44 .Ft char *
  45 .Fn mktemp "char *template"
  46 .Ft int
  47 .Fn mkstemp "char *template"
  48 .Ft char *
  49 .Fn mkdtemp "char *template"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn mktemp
  53 function
  54 takes the given file name template and overwrites a portion of it
  55 to create a file name.
  56 This file name is unique and suitable for use
  57 by the application.
  58 The template may be any file name with some number of
  59 .So Li X
  60 .Sc Ns s
  61 appended
  62 to it, for example
  63 .Pa /tmp/temp.XXXXXX .
  64 The trailing
  65 .So Li X
  66 .Sc Ns s
  67 are replaced with the current process number and/or a
  68 unique letter combination.
  69 The number of unique file names
  70 .Fn mktemp
  71 can return depends on the number of
  72 .So Li X
  73 .Sc Ns s
  74 provided.
  75 Although the
  76 .Nx
  77 implementation of the functions will accept any number of trailing
  78 .So Li X
  79 .Sc Ns s ,
  80 for portability reasons one should use only six.
  81 Using six
  82 .So Li X
  83 .Sc Ns s
  84 will result in
  85 .Fn mktemp
  86 testing roughly 26 ** 6 (308915776) combinations.
  87 .Pp
  88 The
  89 .Fn mkstemp
  90 function
  91 makes the same replacement to the template and creates the template file,
  92 mode 0600, returning a file descriptor opened for reading and writing.
  93 This avoids the race between testing for a file's existence and opening it
  94 for use.
  95 .Pp
  96 The
  97 .Fn mkdtemp
  98 function
  99 is similar to
 100 .Fn mkstemp ,
 101 but it creates a mode 0700 directory instead and returns the path.
 102 .Pp
 103 Please note that the permissions of the file or directory being created are
 104 subject to the restrictions imposed by the
 105 .Xr umask 2
 106 system call.
 107 It may thus happen that the created file is unreadable and/or unwritable.
 108 .Sh RETURN VALUES
 109 The
 110 .Fn mktemp
 111 and
 112 .Fn mkdtemp
 113 functions
 114 return a pointer to the template on success and
 115 .Dv NULL
 116 on failure.
 117 The
 118 .Fn mkstemp
 119 function
 120 returns \-1 if no suitable file could be created.
 121 If either call fails an error code is placed in the global variable
 122 .Va errno .
 123 .Sh EXAMPLES
 124 Quite often a programmer will want to replace a use of
 125 .Fn mktemp
 126 with
 127 .Fn mkstemp ,
 128 usually to avoid the problems described above.
 129 Doing this correctly requires a good understanding of the code in question.
 130 .Pp
 131 For instance, code of this form:
 132 .Bd -literal -offset indent
 133 char sfn[15] = "";
 134 FILE *sfp;
 135
 136 strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn);
 137 if (mktemp(sfn) == NULL || (sfp = fopen(sfn, "w+")) == NULL) {
 138         fprintf(stderr, "%s: %s\en", sfn, strerror(errno));
 139         return (NULL);
 140 }
 141 return (sfp);
 142 .Ed
 143 .Pp
 144 should be rewritten like this:
 145 .Bd -literal -offset indent
 146 char sfn[15] = "";
 147 FILE *sfp;
 148 int fd = -1;
 149
 150 strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn);
 151 if ((fd = mkstemp(sfn)) == -1 ||
 152     (sfp = fdopen(fd, "w+")) == NULL) {
 153         if (fd != -1) {
 154                 unlink(sfn);
 155                 close(fd);
 156         }
 157         fprintf(stderr, "%s: %s\en", sfn, strerror(errno));
 158         return (NULL);
 159 }
 160 return (sfp);
 161 .Ed
 162 .Pp
 163 Often one will find code which uses
 164 .Fn mktemp
 165 very early on, perhaps to globally initialize the template nicely, but the
 166 code which calls
 167 .Xr open 2
 168 or
 169 .Xr fopen 3
 170 on that filename will occur much later.
 171 (In almost all cases, the use of
 172 .Xr fopen 3
 173 will mean that the flags
 174 .Dv O_CREAT
 175 |
 176 .Dv O_EXCL
 177 are not given to
 178 .Xr open 2 ,
 179 and thus a symbolic link race becomes possible, hence making
 180 necessary the use of
 181 .Xr fdopen 3
 182 as seen above).
 183 Furthermore, one must be careful about code which opens, closes, and then
 184 re-opens the file in question.
 185 Finally, one must ensure that upon error the temporary file is
 186 removed correctly.
 187 .Pp
 188 There are also cases where modifying the code to use
 189 .Fn mktemp ,
 190 in concert with
 191 .Xr open 2
 192 using the flags
 193 .Dv O_CREAT
 194 |
 195 .Dv O_EXCL ,
 196 is better, as long as the code retries a new template if
 197 .Xr open 2
 198 fails with an
 199 .Va errno
 200 of
 201 .Er EEXIST .
 202 .Sh ERRORS
 203 The
 204 .Fn mktemp ,
 205 .Fn mkstemp
 206 and
 207 .Fn mkdtemp
 208 functions
 209 may set
 210 .Va errno
 211 to one of the following values:
 212 .Bl -tag -width Er
 213 .It Bq Er ENOTDIR
 214 The pathname portion of the template is not an existing directory.
 215 .El
 216 .Pp
 217 The
 218 .Fn mktemp ,
 219 .Fn mkstemp
 220 and
 221 .Fn mkdtemp
 222 functions
 223 may also set
 224 .Va errno
 225 to any value specified by the
 226 .Xr stat 2
 227 function.
 228 .Pp
 229 The
 230 .Fn mkstemp
 231 function
 232 may also set
 233 .Va errno
 234 to any value specified by the
 235 .Xr open 2
 236 function.
 237 .Pp
 238 The
 239 .Fn mkdtemp
 240 function
 241 may also set
 242 .Va errno
 243 to any value specified by the
 244 .Xr mkdir 2
 245 function.
 246 .Sh SEE ALSO
 247 .Xr chmod 2 ,
 248 .Xr getpid 2 ,
 249 .Xr open 2 ,
 250 .Xr stat 2 ,
 251 .Xr umask 2
 252 .Sh HISTORY
 253 A
 254 .Fn mktemp
 255 function appeared in
 256 .At v7 .
 257 .Pp
 258 The
 259 .Fn mkstemp
 260 function appeared in
 261 .Bx 4.4 .
 262 .Pp
 263 The
 264 .Fn mkdtemp
 265 function appeared in
 266 .Nx 1.4 .
 267 .Sh BUGS
 268 For
 269 .Fn mktemp
 270 there is an obvious race between file name selection and file
 271 creation and deletion: the program is typically written to call
 272 .Xr tmpnam 3 ,
 273 .Xr tempnam 3 ,
 274 or
 275 .Fn mktemp .
 276 Subsequently, the program calls
 277 .Xr open 2
 278 or
 279 .Xr fopen 3
 280 and erroneously opens a file (or symbolic link, fifo or other
 281 device) that the attacker has created in the expected file location.
 282 Hence
 283 .Fn mkstemp
 284 is recommended, since it atomically creates the file.
 285 An attacker can guess the filenames produced by
 286 .Fn mktemp .
 287 Whenever it is possible,
 288 .Fn mkstemp
 289 or
 290 .Fn mkdtemp
 291 should be used instead.
 292 .Pp
 293 For this reason,
 294 .Xr ld 1
 295 will output a warning message whenever it links code that uses
 296 .Fn mktemp .
 297 .Pp
 298 The
 299 .Fn mkdtemp
 300 function is nonstandard and should not be used if portability is required.
 301 .Sh SECURITY CONSIDERATIONS
 302 The use of
 303 .Fn mktemp
 304 should generally be avoided, as a hostile process can exploit a race
 305 condition in the time between the generation of a temporary filename by
 306 .Fn mktemp
 307 and the invoker's use of the temporary name.
 308 A link-time warning will be issued advising the use of
 309 .Fn mkstemp
 310 or
 311 .Fn mkdtemp
 312 instead.
 313 .\" .SH STANDARDS
 314 .\" .St -p1003.1-2003