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 .\" 4. 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 August 8, 2013
  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
  94 is like
  95 .Fn mkstemp
  96 but allows specifying additional
  97 .Xr open 2
  98 flags (defined in
  99 .In fcntl.h ) .
 100 The permitted flags are
 101 .Dv O_APPEND ,
 102 .Dv O_DIRECT ,
 103 .Dv O_SHLOCK ,
 104 .Dv O_EXLOCK ,
 105 .Dv O_SYNC
 106 and
 107 .Dv O_CLOEXEC .
 108 .Pp
 109 The
 110 .Fn mkstemps
 111 and
 112 .Fn mkostemps
 113 functions act the same as
 114 .Fn mkstemp
 115 and
 116 .Fn mkostemp
 117 respectively,
 118 except they permit a suffix to exist in the template.
 119 The template should be of the form
 120 .Pa /tmp/tmpXXXXXXsuffix .
 121 The
 122 .Fn mkstemps
 123 and
 124 .Fn mkostemps
 125 function
 126 are told the length of the suffix string.
 127 .Pp
 128 The
 129 .Fn mkdtemp
 130 function makes the same replacement to the template as in
 131 .Fn mktemp
 132 and creates the template directory, mode 0700.
 133 .Sh RETURN VALUES
 134 The
 135 .Fn mktemp
 136 and
 137 .Fn mkdtemp
 138 functions return a pointer to the template on success and
 139 .Dv NULL
 140 on failure.
 141 The
 142 .Fn mkstemp ,
 143 .Fn mkostemp
 144 .Fn mkstemps
 145 and
 146 .Fn mkostemps
 147 functions
 148 return \-1 if no suitable file could be created.
 149 If either call fails an error code is placed in the global variable
 150 .Va errno .
 151 .Sh ERRORS
 152 The
 153 .Fn mkstemp ,
 154 .Fn mkostemp ,
 155 .Fn mkstemps ,
 156 .Fn mkostemps
 157 and
 158 .Fn mkdtemp
 159 functions
 160 may set
 161 .Va errno
 162 to one of the following values:
 163 .Bl -tag -width Er
 164 .It Bq Er ENOTDIR
 165 The pathname portion of the template is not an existing directory.
 166 .El
 167 .Pp
 168 The
 169 .Fn mkostemp
 170 and
 171 .Fn mkostemps
 172 functions
 173 may also set
 174 .Va errno
 175 to the following value:
 176 .Bl -tag -width Er
 177 .It Bq Er EINVAL
 178 The
 179 .Fa oflags
 180 argument is invalid.
 181 .El
 182 .Pp
 183 The
 184 .Fn mkstemp ,
 185 .Fn mkostemp ,
 186 .Fn mkstemps ,
 187 .Fn mkostemps
 188 and
 189 .Fn mkdtemp
 190 functions
 191 may also set
 192 .Va errno
 193 to any value specified by the
 194 .Xr stat 2
 195 function.
 196 .Pp
 197 The
 198 .Fn mkstemp ,
 199 .Fn mkostemp ,
 200 .Fn mkstemps
 201 and
 202 .Fn mkostemps
 203 functions
 204 may also set
 205 .Va errno
 206 to any value specified by the
 207 .Xr open 2
 208 function.
 209 .Pp
 210 The
 211 .Fn mkdtemp
 212 function
 213 may also set
 214 .Va errno
 215 to any value specified by the
 216 .Xr mkdir 2
 217 function.
 218 .Sh NOTES
 219 A common problem that results in a core dump is that the programmer
 220 passes in a read-only string to
 221 .Fn mktemp ,
 222 .Fn mkstemp ,
 223 .Fn mkstemps
 224 or
 225 .Fn mkdtemp .
 226 This is common with programs that were developed before
 227 .St -isoC
 228 compilers were common.
 229 For example, calling
 230 .Fn mkstemp
 231 with an argument of
 232 .Qq /tmp/tempfile.XXXXXX
 233 will result in a core dump due to
 234 .Fn mkstemp
 235 attempting to modify the string constant that was given.
 236 .Pp
 237 The
 238 .Fn mkdtemp ,
 239 .Fn mkstemp
 240 and
 241 .Fn mktemp
 242 function prototypes are also available from
 243 .In unistd.h .
 244 .Sh SEE ALSO
 245 .Xr chmod 2 ,
 246 .Xr getpid 2 ,
 247 .Xr mkdir 2 ,
 248 .Xr open 2 ,
 249 .Xr stat 2
 250 .Sh STANDARDS
 251 The
 252 .Fn mkstemp
 253 and
 254 .Fn mkdtemp
 255 functions are expected to conform to
 256 .St -p1003.1-2008 .
 257 The
 258 .Fn mktemp
 259 function is expected to conform to
 260 .St -p1003.1-2001
 261 and is not specified by
 262 .St -p1003.1-2008 .
 263 The
 264 .Fn mkostemp ,
 265 .Fn mkstemps
 266 and
 267 .Fn mkostemps
 268 functions do not conform to any standard.
 269 .Sh HISTORY
 270 A
 271 .Fn mktemp
 272 function appeared in
 273 .At v7 .
 274 The
 275 .Fn mkstemp
 276 function appeared in
 277 .Bx 4.4 .
 278 The
 279 .Fn mkdtemp
 280 function first appeared in
 281 .Ox 2.2 ,
 282 and later in
 283 .Fx 3.2 .
 284 The
 285 .Fn mkstemps
 286 function first appeared in
 287 .Ox 2.4 ,
 288 and later in
 289 .Fx 3.4 .
 290 The
 291 .Fn mkostemp
 292 and
 293 .Fn mkostemps
 294 functions appeared in
 295 .Fx 10.0 .
 296 .Sh BUGS
 297 This family of functions produces filenames which can be guessed,
 298 though the risk is minimized when large numbers of
 299 .Ql X Ns s
 300 are used to
 301 increase the number of possible temporary filenames.
 302 This makes the race in
 303 .Fn mktemp ,
 304 between testing for a file's existence (in the
 305 .Fn mktemp
 306 function call)
 307 and opening it for use
 308 (later in the user application)
 309 particularly dangerous from a security perspective.
 310 Whenever it is possible,
 311 .Fn mkstemp
 312 or
 313 .Fn mkostemp
 314 should be used instead, since it does not have the race condition.
 315 If
 316 .Fn mkstemp
 317 cannot be used, the filename created by
 318 .Fn mktemp
 319 should be created using the
 320 .Dv O_EXCL
 321 flag to
 322 .Xr open 2
 323 and the return status of the call should be tested for failure.
 324 This will ensure that the program does not continue blindly
 325 in the event that an attacker has already created the file
 326 with the intention of manipulating or reading its contents.