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