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$
  30 .\"
  31 .Dd July 29, 2019
  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 int
  50 .Fn mkostempsat "int dfd" "char *template" "int suffixlen" "int oflags"
  51 .Ft char *
  52 .Fn mkdtemp "char *template"
  53 .In unistd.h
  54 .Ft int
  55 .Fn mkstemps "char *template" "int suffixlen"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn mktemp
  59 function
  60 takes the given file name template and overwrites a portion of it
  61 to create a file name.
  62 This file name is guaranteed not to exist at the time of function invocation
  63 and is suitable for use
  64 by the application.
  65 The template may be any file name with some number of
  66 .Ql X Ns s
  67 appended
  68 to it, for example
  69 .Pa /tmp/temp.XXXXXX .
  70 The trailing
  71 .Ql X Ns s
  72 are replaced with a
  73 unique alphanumeric combination.
  74 The number of unique file names
  75 .Fn mktemp
  76 can return depends on the number of
  77 .Ql X Ns s
  78 provided; six
  79 .Ql X Ns s
  80 will
  81 result in
  82 .Fn mktemp
  83 selecting one of 56800235584 (62 ** 6) possible temporary file names.
  84 .Pp
  85 The
  86 .Fn mkstemp
  87 function
  88 makes the same replacement to the template and creates the template file,
  89 mode 0600, returning a file descriptor opened for reading and writing.
  90 This avoids the race between testing for a file's existence and opening it
  91 for use.
  92 .Pp
  93 The
  94 .Fn mkostemp
  95 function
  96 is like
  97 .Fn mkstemp
  98 but allows specifying additional
  99 .Xr open 2
 100 flags (defined in
 101 .In fcntl.h ) .
 102 The permitted flags are
 103 .Dv O_APPEND ,
 104 .Dv O_DIRECT ,
 105 .Dv O_SHLOCK ,
 106 .Dv O_EXLOCK ,
 107 .Dv O_SYNC
 108 and
 109 .Dv O_CLOEXEC .
 110 .Pp
 111 The
 112 .Fn mkstemps
 113 and
 114 .Fn mkostemps
 115 functions act the same as
 116 .Fn mkstemp
 117 and
 118 .Fn mkostemp
 119 respectively,
 120 except they permit a suffix to exist in the template.
 121 The template should be of the form
 122 .Pa /tmp/tmpXXXXXXsuffix .
 123 The
 124 .Fn mkstemps
 125 and
 126 .Fn mkostemps
 127 function
 128 are told the length of the suffix string.
 129 .Pp
 130 The
 131 .Fn mkostempsat
 132 function acts the same as
 133 .Fn mkostemps
 134 but takes an additional directory descriptor as a parameter.
 135 The temporary file is created relative to the corresponding
 136 directory, or to the current working directory if the special
 137 value
 138 .Dv AT_FDCWD
 139 is specified.
 140 If the template path is an absolute path, the
 141 .Fa dfd
 142 parameter is ignored and the behavior is identical to
 143 .Fn mkostemps .
 144 .Pp
 145 The
 146 .Fn mkdtemp
 147 function makes the same replacement to the template as in
 148 .Fn mktemp
 149 and creates the template directory, mode 0700.
 150 .Sh RETURN VALUES
 151 The
 152 .Fn mktemp
 153 and
 154 .Fn mkdtemp
 155 functions return a pointer to the template on success and
 156 .Dv NULL
 157 on failure.
 158 The
 159 .Fn mkstemp ,
 160 .Fn mkostemp
 161 .Fn mkstemps
 162 and
 163 .Fn mkostemps
 164 functions
 165 return \-1 if no suitable file could be created.
 166 If either call fails an error code is placed in the global variable
 167 .Va errno .
 168 .Sh ERRORS
 169 The
 170 .Fn mkstemp ,
 171 .Fn mkostemp ,
 172 .Fn mkstemps ,
 173 .Fn mkostemps
 174 and
 175 .Fn mkdtemp
 176 functions
 177 may set
 178 .Va errno
 179 to one of the following values:
 180 .Bl -tag -width Er
 181 .It Bq Er ENOTDIR
 182 The pathname portion of the template is not an existing directory.
 183 .El
 184 .Pp
 185 The
 186 .Fn mkostemp
 187 and
 188 .Fn mkostemps
 189 functions
 190 may also set
 191 .Va errno
 192 to the following value:
 193 .Bl -tag -width Er
 194 .It Bq Er EINVAL
 195 The
 196 .Fa oflags
 197 argument is invalid.
 198 .El
 199 .Pp
 200 The
 201 .Fn mkstemp ,
 202 .Fn mkostemp ,
 203 .Fn mkstemps ,
 204 .Fn mkostemps
 205 and
 206 .Fn mkdtemp
 207 functions
 208 may also set
 209 .Va errno
 210 to any value specified by the
 211 .Xr stat 2
 212 function.
 213 .Pp
 214 The
 215 .Fn mkstemp ,
 216 .Fn mkostemp ,
 217 .Fn mkstemps
 218 and
 219 .Fn mkostemps
 220 functions
 221 may also set
 222 .Va errno
 223 to any value specified by the
 224 .Xr open 2
 225 function.
 226 .Pp
 227 The
 228 .Fn mkdtemp
 229 function
 230 may also set
 231 .Va errno
 232 to any value specified by the
 233 .Xr mkdir 2
 234 function.
 235 .Sh NOTES
 236 A common problem that results in a core dump is that the programmer
 237 passes in a read-only string to
 238 .Fn mktemp ,
 239 .Fn mkstemp ,
 240 .Fn mkstemps
 241 or
 242 .Fn mkdtemp .
 243 This is common with programs that were developed before
 244 .St -isoC
 245 compilers were common.
 246 For example, calling
 247 .Fn mkstemp
 248 with an argument of
 249 .Qq /tmp/tempfile.XXXXXX
 250 will result in a core dump due to
 251 .Fn mkstemp
 252 attempting to modify the string constant that was given.
 253 .Pp
 254 The
 255 .Fn mkdtemp ,
 256 .Fn mkstemp
 257 and
 258 .Fn mktemp
 259 function prototypes are also available from
 260 .In unistd.h .
 261 .Sh SEE ALSO
 262 .Xr chmod 2 ,
 263 .Xr getpid 2 ,
 264 .Xr mkdir 2 ,
 265 .Xr open 2 ,
 266 .Xr stat 2
 267 .Sh STANDARDS
 268 The
 269 .Fn mkstemp
 270 and
 271 .Fn mkdtemp
 272 functions are expected to conform to
 273 .St -p1003.1-2008 .
 274 The
 275 .Fn mktemp
 276 function is expected to conform to
 277 .St -p1003.1-2001
 278 and is not specified by
 279 .St -p1003.1-2008 .
 280 The
 281 .Fn mkostemp ,
 282 .Fn mkstemps ,
 283 .Fn mkostemps
 284 and
 285 .Fn mkostempsat
 286 functions do not conform to any standard.
 287 .Sh HISTORY
 288 A
 289 .Fn mktemp
 290 function appeared in
 291 .At v7 .
 292 The
 293 .Fn mkstemp
 294 function appeared in
 295 .Bx 4.4 .
 296 The
 297 .Fn mkdtemp
 298 function first appeared in
 299 .Ox 2.2 ,
 300 and later in
 301 .Fx 3.2 .
 302 The
 303 .Fn mkstemps
 304 function first appeared in
 305 .Ox 2.4 ,
 306 and later in
 307 .Fx 3.4 .
 308 The
 309 .Fn mkostemp
 310 and
 311 .Fn mkostemps
 312 functions appeared in
 313 .Fx 10.0 .
 314 The
 315 .Fn mkostempsat
 316 function appeared in
 317 .Fx 13.0 .
 318 .Sh BUGS
 319 This family of functions produces filenames which can be guessed,
 320 though the risk is minimized when large numbers of
 321 .Ql X Ns s
 322 are used to
 323 increase the number of possible temporary filenames.
 324 This makes the race in
 325 .Fn mktemp ,
 326 between testing for a file's existence (in the
 327 .Fn mktemp
 328 function call)
 329 and opening it for use
 330 (later in the user application)
 331 particularly dangerous from a security perspective.
 332 Whenever it is possible,
 333 .Fn mkstemp ,
 334 .Fn mkostemp
 335 or
 336 .Fn mkostempsat
 337 should be used instead, since they do not have the race condition.
 338 If
 339 .Fn mkstemp
 340 cannot be used, the filename created by
 341 .Fn mktemp
 342 should be created using the
 343 .Dv O_EXCL
 344 flag to
 345 .Xr open 2
 346 and the return status of the call should be tested for failure.
 347 This will ensure that the program does not continue blindly
 348 in the event that an attacker has already created the file
 349 with the intention of manipulating or reading its contents.