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