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