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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)mktemp.3    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd February 11, 1998
  36 .Dt MKTEMP 3
  37 .Os
  38 .Sh NAME
  39 .Nm mktemp
  40 .Nd make temporary file name (unique)
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .Fd #include <unistd.h>
  45 .Ft char *
  46 .Fn mktemp "char *template"
  47 .Ft int
  48 .Fn mkstemp "char *template"
  49 .Ft int
  50 .Fn mkstemps "char *template" "int suffixlen"
  51 .Ft char *
  52 .Fn mkdtemp "char *template"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn mktemp
  56 function
  57 takes the given file name template and overwrites a portion of it
  58 to create a file name.
  59 This file name is unique and suitable for use
  60 by the application.
  61 The template may be any file name with some number of
  62 .Ql X Ns s
  63 appended
  64 to it, for example
  65 .Pa /tmp/temp.XXXX .
  66 The trailing
  67 .Ql X Ns s
  68 are replaced with the current process number and/or a
  69 unique letter combination.
  70 The number of unique file names
  71 .Fn mktemp
  72 can return depends on the number of
  73 .Ql X Ns s
  74 provided; six
  75 .Ql X Ns s
  76 will
  77 result in
  78 .Fn mktemp
  79 testing roughly 26 ** 6 combinations.
  80 .Pp
  81 The
  82 .Fn mkstemp
  83 function
  84 makes the same replacement to the template and creates the template file,
  85 mode 0600, returning a file descriptor opened for reading and writing.
  86 This avoids the race between testing for a file's existence and opening it
  87 for use.
  88 .Pp
  89 The
  90 .Fn mkstemps
  91 function acts the same as
  92 .Fn mkstemp ,
  93 except it permits a suffix to exist in the template.
  94 The template should be of the form
  95 .Pa /tmp/tmpXXXXXXsuffix .
  96 .Fn mkstemps
  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 .Xr mktemp 3
 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 -ansiC
 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 BUGS
 191 This family of functions produces filenames which can be guessed.
 192 This makes the race in
 193 .Fn mktemp ,
 194 between testing for a file's existence and opening it for use,
 195 particularly dangerous from a security perspective.
 196 Whenever it is possible,
 197 .Fn mkstemp
 198 should be used instead.
 199 .Sh SEE ALSO
 200 .Xr chmod 2 ,
 201 .Xr getpid 2 ,
 202 .Xr mkdir 2 ,
 203 .Xr open 2 ,
 204 .Xr stat 2
 205 .Sh HISTORY
 206 A
 207 .Fn mktemp
 208 function appeared in
 209 .At v7 .
 210 The
 211 .Fn mkdtemp
 212 function first appeared in
 213 .Ox 2.2 ,
 214 and later in
 215 .Fx 3.2 .
 216 The
 217 .Fn mkstemps
 218 function first appeared in
 219 .Ox 2.4 ,
 220 and later in
 221 .Fx 3.4 .