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