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: src/lib/libc/stdio/mktemp.3,v 1.22 2007/01/09 00:28:07 imp Exp $
  30 .\" $DragonFly: src/lib/libc/stdio/mktemp.3,v 1.3 2006/02/17 19:35:06 swildner Exp $
  31 .\"
  32 .Dd February 11, 1998
  33 .Dt MKTEMP 3
  34 .Os
  35 .Sh NAME
  36 .Nm mktemp
  37 .Nd make temporary file name (unique)
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In unistd.h
  42 .Ft char *
  43 .Fn mktemp "char *template"
  44 .Ft int
  45 .Fn mkstemp "char *template"
  46 .Ft int
  47 .Fn mkstemps "char *template" "int suffixlen"
  48 .Ft char *
  49 .Fn mkdtemp "char *template"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn mktemp
  53 function
  54 takes the given file name template and overwrites a portion of it
  55 to create a file name.
  56 This file name is guaranteed not to exist at the time of function invocation
  57 and is suitable for use
  58 by the application.
  59 The template may be any file name with some number of
  60 .Ql X Ns s
  61 appended
  62 to it, for example
  63 .Pa /tmp/temp.XXXXXX .
  64 The trailing
  65 .Ql X Ns s
  66 are replaced with a
  67 unique alphanumeric combination.
  68 The number of unique file names
  69 .Fn mktemp
  70 can return depends on the number of
  71 .Ql X Ns s
  72 provided; six
  73 .Ql X Ns s
  74 will
  75 result in
  76 .Fn mktemp
  77 selecting one of 56800235584 (62 ** 6) possible temporary file names.
  78 .Pp
  79 The
  80 .Fn mkstemp
  81 function
  82 makes the same replacement to the template and creates the template file,
  83 mode 0600, returning a file descriptor opened for reading and writing.
  84 This avoids the race between testing for a file's existence and opening it
  85 for use.
  86 .Pp
  87 The
  88 .Fn mkstemps
  89 function acts the same as
  90 .Fn mkstemp ,
  91 except it permits a suffix to exist in the template.
  92 The template should be of the form
  93 .Pa /tmp/tmpXXXXXXsuffix .
  94 The
  95 .Fn mkstemps
  96 function
  97 is told the length of the suffix string.
  98 .Pp
  99 The
 100 .Fn mkdtemp
 101 function makes the same replacement to the template as in
 102 .Fn mktemp
 103 and creates the template directory, mode 0700.
 104 .Sh RETURN VALUES
 105 The
 106 .Fn mktemp
 107 and
 108 .Fn mkdtemp
 109 functions return a pointer to the template on success and
 110 .Dv NULL
 111 on failure.
 112 The
 113 .Fn mkstemp
 114 and
 115 .Fn mkstemps
 116 functions
 117 return \-1 if no suitable file could be created.
 118 If either call fails an error code is placed in the global variable
 119 .Va errno .
 120 .Sh ERRORS
 121 The
 122 .Fn mkstemp ,
 123 .Fn mkstemps
 124 and
 125 .Fn mkdtemp
 126 functions
 127 may set
 128 .Va errno
 129 to one of the following values:
 130 .Bl -tag -width Er
 131 .It Bq Er ENOTDIR
 132 The pathname portion of the template is not an existing directory.
 133 .El
 134 .Pp
 135 The
 136 .Fn mkstemp ,
 137 .Fn mkstemps
 138 and
 139 .Fn mkdtemp
 140 functions
 141 may also set
 142 .Va errno
 143 to any value specified by the
 144 .Xr stat 2
 145 function.
 146 .Pp
 147 The
 148 .Fn mkstemp
 149 and
 150 .Fn mkstemps
 151 functions
 152 may also set
 153 .Va errno
 154 to any value specified by the
 155 .Xr open 2
 156 function.
 157 .Pp
 158 The
 159 .Fn mkdtemp
 160 function
 161 may also set
 162 .Va errno
 163 to any value specified by the
 164 .Xr mkdir 2
 165 function.
 166 .Sh NOTES
 167 A common problem that results in a core dump is that the programmer
 168 passes in a read-only string to
 169 .Fn mktemp ,
 170 .Fn mkstemp ,
 171 .Fn mkstemps
 172 or
 173 .Fn mkdtemp .
 174 This is common with programs that were developed before
 175 .St -isoC
 176 compilers were common.
 177 For example, calling
 178 .Fn mkstemp
 179 with an argument of
 180 .Qq /tmp/tempfile.XXXXXX
 181 will result in a core dump due to
 182 .Fn mkstemp
 183 attempting to modify the string constant that was given.
 184 If the program in question makes heavy use of that type
 185 of function call, you do have the option of compiling the program
 186 so that it will store string constants in a writable segment of memory.
 187 See
 188 .Xr gcc 1
 189 for more information.
 190 .Sh SEE ALSO
 191 .Xr chmod 2 ,
 192 .Xr getpid 2 ,
 193 .Xr mkdir 2 ,
 194 .Xr open 2 ,
 195 .Xr stat 2
 196 .Sh HISTORY
 197 A
 198 .Fn mktemp
 199 function appeared in
 200 .At v7 .
 201 The
 202 .Fn mkstemp
 203 function appeared in
 204 .Bx 4.4 .
 205 The
 206 .Fn mkdtemp
 207 function first appeared in
 208 .Ox 2.2 ,
 209 and later in
 210 .Fx 3.2 .
 211 The
 212 .Fn mkstemps
 213 function first appeared in
 214 .Ox 2.4 ,
 215 and later in
 216 .Fx 3.4 .
 217 .Sh BUGS
 218 This family of functions produces filenames which can be guessed,
 219 though the risk is minimized when large numbers of
 220 .Ql X Ns s
 221 are used to
 222 increase the number of possible temporary filenames.
 223 This makes the race in
 224 .Fn mktemp ,
 225 between testing for a file's existence (in the
 226 .Fn mktemp
 227 function call)
 228 and opening it for use
 229 (later in the user application)
 230 particularly dangerous from a security perspective.
 231 Whenever it is possible,
 232 .Fn mkstemp
 233 should be used instead, since it does not have the race condition.
 234 If
 235 .Fn mkstemp
 236 cannot be used, the filename created by
 237 .Fn mktemp
 238 should be created using the
 239 .Dv O_EXCL
 240 flag to
 241 .Xr open 2
 242 and the return status of the call should be tested for failure.
 243 This will ensure that the program does not continue blindly
 244 in the event that an attacker has already created the file
 245 with the intention of manipulating or reading its contents.
 246 .Pp
 247 The implementation of these functions calls
 248 .Xr arc4random 3 ,
 249 which is not reentrant.
 250 You must provide your own locking around this and other consumers of the
 251 .Xr arc4random 3
 252 API.