lib/libc/stdio/mktemp.3

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)mktemp.3    8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: head/lib/libc/stdio/mktemp.3 254151 2013-08-09 17:24:23Z jilles $
  30 .\"
  31 .Dd July 29, 2016
  32 .Dt MKTEMP 3
  33 .Os
  34 .Sh NAME
  35 .Nm mktemp
  36 .Nd make temporary file name (unique)
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In stdlib.h
  41 .Ft char *
  42 .Fn mktemp "char *template"
  43 .Ft int
  44 .Fn mkstemp "char *template"
  45 .Ft int
  46 .Fn mkostemp "char *template" "int oflags"
  47 .Ft int
  48 .Fn mkostemps "char *template" "int suffixlen" "int oflags"
  49 .Ft char *
  50 .Fn mkdtemp "char *template"
  51 .In unistd.h
  52 .Ft int
  53 .Fn mkstemps "char *template" "int suffixlen"
  54 .Sh DESCRIPTION
  55 The
  56 .Fn mktemp
  57 function
  58 takes the given file name template and overwrites a portion of it
  59 to create a file name.
  60 This file name is guaranteed not to exist at the time of function invocation
  61 and is suitable for use
  62 by the application.
  63 The template may be any file name with some number of
  64 .Ql X Ns s
  65 appended
  66 to it, for example
  67 .Pa /tmp/temp.XXXXXX .
  68 The trailing
  69 .Ql X Ns s
  70 are replaced with a
  71 unique alphanumeric combination.
  72 The number of unique file names
  73 .Fn mktemp
  74 can return depends on the number of
  75 .Ql X Ns s
  76 provided; six
  77 .Ql X Ns s
  78 will
  79 result in
  80 .Fn mktemp
  81 selecting one of 56800235584 (62 ** 6) possible temporary file names.
  82 .Pp
  83 The
  84 .Fn mkstemp
  85 function
  86 makes the same replacement to the template and creates the template file,
  87 mode 0600, returning a file descriptor opened for reading and writing.
  88 This avoids the race between testing for a file's existence and opening it
  89 for use.
  90 .Pp
  91 The
  92 .Fn mkostemp
  93 function is like
  94 .Fn mkstemp
  95 but allows specifying additional
  96 .Xr open 2
  97 flags (defined in
  98 .In fcntl.h ) .
  99 The permitted flags are
 100 .Dv O_APPEND ,
 101 .Dv O_DIRECT ,
 102 .Dv O_SHLOCK ,
 103 .Dv O_EXLOCK ,
 104 .Dv O_SYNC
 105 and
 106 .Dv O_CLOEXEC .
 107 .Pp
 108 The
 109 .Fn mkstemps
 110 and
 111 .Fn mkostemps
 112 functions act the same as
 113 .Fn mkstemp
 114 and
 115 .Fn mkostemp
 116 respectively,
 117 except they permit a suffix to exist in the template.
 118 The template should be of the form
 119 .Pa /tmp/tmpXXXXXXsuffix .
 120 The
 121 .Fn mkstemps
 122 and
 123 .Fn mkostemps
 124 function
 125 are told the length of the suffix string.
 126 .Pp
 127 The
 128 .Fn mkostemps
 129 function is like
 130 .Fn mkstemps
 131 but allows specifying additional
 132 .Xr open 2
 133 flags such as
 134 .Dv O_CLOEXEC .
 135 .Pp
 136 The
 137 .Fn mkdtemp
 138 function makes the same replacement to the template as in
 139 .Fn mktemp
 140 and creates the template directory, mode 0700.
 141 .Sh RETURN VALUES
 142 The
 143 .Fn mktemp
 144 and
 145 .Fn mkdtemp
 146 functions return a pointer to the template on success and
 147 .Dv NULL
 148 on failure.
 149 The
 150 .Fn mkstemp ,
 151 .Fn mkostemp ,
 152 .Fn mkstemps
 153 and
 154 .Fn mkostemps
 155 functions
 156 return \-1 if no suitable file could be created.
 157 If either call fails an error code is placed in the global variable
 158 .Va errno .
 159 .Sh ERRORS
 160 The
 161 .Fn mkstemp ,
 162 .Fn mkostemp ,
 163 .Fn mkstemps ,
 164 .Fn mkostemps
 165 and
 166 .Fn mkdtemp
 167 functions
 168 may set
 169 .Va errno
 170 to one of the following values:
 171 .Bl -tag -width Er
 172 .It Bq Er ENOTDIR
 173 The pathname portion of the template is not an existing directory.
 174 .El
 175 .Pp
 176 The
 177 .Fn mkostemp
 178 and
 179 .Fn mkostemps
 180 functions
 181 may also set
 182 .Va errno
 183 to the following value:
 184 .Bl -tag -width Er
 185 .It Bq Er EINVAL
 186 The
 187 .Fa oflags
 188 argument is invalid.
 189 .El
 190 .Pp
 191 The
 192 .Fn mkstemp ,
 193 .Fn mkostemp ,
 194 .Fn mkstemps ,
 195 .Fn mkostemps
 196 and
 197 .Fn mkdtemp
 198 functions
 199 may also set
 200 .Va errno
 201 to any value specified by the
 202 .Xr stat 2
 203 function.
 204 .Pp
 205 The
 206 .Fn mkstemp ,
 207 .Fn mkostemp ,
 208 .Fn mkstemps
 209 and
 210 .Fn mkostemps
 211 functions
 212 may also set
 213 .Va errno
 214 to any value specified by the
 215 .Xr open 2
 216 function.
 217 .Pp
 218 The
 219 .Fn mkdtemp
 220 function
 221 may also set
 222 .Va errno
 223 to any value specified by the
 224 .Xr mkdir 2
 225 function.
 226 .Sh NOTES
 227 A common problem that results in a core dump is that the programmer
 228 passes in a read-only string to
 229 .Fn mktemp ,
 230 .Fn mkstemp ,
 231 .Fn mkstemps
 232 or
 233 .Fn mkdtemp .
 234 This is common with programs that were developed before
 235 .St -isoC
 236 compilers were common.
 237 For example, calling
 238 .Fn mkstemp
 239 with an argument of
 240 .Qq /tmp/tempfile.XXXXXX
 241 will result in a core dump due to
 242 .Fn mkstemp
 243 attempting to modify the string constant that was given.
 244 .Pp
 245 The
 246 .Fn mkdtemp ,
 247 .Fn mkstemp
 248 and
 249 .Fn mktemp
 250 function prototypes are also available from
 251 .In unistd.h .
 252 .Sh SEE ALSO
 253 .Xr chmod 2 ,
 254 .Xr getpid 2 ,
 255 .Xr mkdir 2 ,
 256 .Xr open 2 ,
 257 .Xr stat 2
 258 .Sh STANDARDS
 259 The
 260 .Fn mkstemp
 261 and
 262 .Fn mkdtemp
 263 functions are expected to conform to
 264 .St -p1003.1-2008 .
 265 The
 266 .Fn mktemp
 267 function is expected to conform to
 268 .St -p1003.1-2001
 269 and is not specified by
 270 .St -p1003.1-2008 .
 271 .Sh HISTORY
 272 A
 273 .Fn mktemp
 274 function appeared in
 275 .At v7 .
 276 The
 277 .Fn mkstemp
 278 function appeared in
 279 .Bx 4.4 .
 280 The
 281 .Fn mkdtemp
 282 function first appeared in
 283 .Ox 2.2 ,
 284 and later in
 285 .Fx 3.2 .
 286 The
 287 .Fn mkstemps
 288 function first appeared in
 289 .Ox 2.4 ,
 290 and later in
 291 .Fx 3.4 .
 292 The
 293 .Fn mkostemp
 294 and
 295 .Fn mkostemps
 296 functions appeared in
 297 .Fx 10.0
 298 and were imported to
 299 .Dx 4.6 .
 300 .Sh BUGS
 301 This family of functions produces filenames which can be guessed,
 302 though the risk is minimized when large numbers of
 303 .Ql X Ns s
 304 are used to
 305 increase the number of possible temporary filenames.
 306 This makes the race in
 307 .Fn mktemp ,
 308 between testing for a file's existence (in the
 309 .Fn mktemp
 310 function call)
 311 and opening it for use
 312 (later in the user application)
 313 particularly dangerous from a security perspective.
 314 Whenever it is possible,
 315 .Fn mkstemp
 316 or
 317 .Fn mkostemp
 318 should be used instead, since it does not have the race condition.
 319 If
 320 .Fn mkstemp
 321 cannot be used, the filename created by
 322 .Fn mktemp
 323 should be created using the
 324 .Dv O_EXCL
 325 flag to
 326 .Xr open 2
 327 and the return status of the call should be tested for failure.
 328 This will ensure that the program does not continue blindly
 329 in the event that an attacker has already created the file
 330 with the intention of manipulating or reading its contents.