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