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 BUGS 194This family of functions produces filenames which can be guessed, 195though the risk is minimized when large numbers of 196.Ql X Ns s 197are used to 198increase the number of possible temporary filenames. 199This makes the race in 200.Fn mktemp , 201between testing for a file's existence (in the 202.Fn mktemp 203function call) 204and opening it for use 205(later in the user application) 206particularly dangerous from a security perspective. 207Whenever it is possible, 208.Fn mkstemp 209should be used instead, since it does not have the race condition. 210If 211.Fn mkstemp 212cannot be used, the filename created by 213.Fn mktemp 214should be created using the 215.Dv O_EXCL 216flag to 217.Xr open 2 218and the return status of the call should be tested for failure. 219This will ensure that the program does not continue blindly 220in the event that an attacker has already created the file 221with the intention of manipulating or reading its contents. 222.Pp 223The implementation of these functions calls 224.Xr arc4random 3 , 225which is not reentrant. 226You must provide your own locking around this and other consumers of the 227.Xr arc4random 3 228API. 229.Sh SEE ALSO 230.Xr chmod 2 , 231.Xr getpid 2 , 232.Xr mkdir 2 , 233.Xr open 2 , 234.Xr stat 2 235.Sh HISTORY 236A 237.Fn mktemp 238function appeared in 239.At v7 . 240The 241.Fn mkstemp 242function appeared in 243.Bx 4.4 . 244The 245.Fn mkdtemp 246function first appeared in 247.Ox 2.2 , 248and later in 249.Fx 3.2 . 250The 251.Fn mkstemps 252function first appeared in 253.Ox 2.4 , 254and later in 255.Fx 3.4 . 256