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