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