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: src/lib/libc/stdio/mktemp.3,v 1.11.2.6 2001/12/14 18:33:57 ru Exp $ 34.\" $DragonFly: src/lib/libc/stdio/mktemp.3,v 1.3 2006/02/17 19:35:06 swildner Exp $ 35.\" 36.Dd February 11, 1998 37.Dt MKTEMP 3 38.Os 39.Sh NAME 40.Nm mktemp 41.Nd make temporary file name (unique) 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In unistd.h 46.Ft char * 47.Fn mktemp "char *template" 48.Ft int 49.Fn mkstemp "char *template" 50.Ft int 51.Fn mkstemps "char *template" "int suffixlen" 52.Ft char * 53.Fn mkdtemp "char *template" 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 mkstemps 93function acts the same as 94.Fn mkstemp , 95except it permits a suffix to exist in the template. 96The template should be of the form 97.Pa /tmp/tmpXXXXXXsuffix . 98.Fn mkstemps 99is told the length of the suffix string. 100.Pp 101The 102.Fn mkdtemp 103function makes the same replacement to the template as in 104.Xr mktemp 3 105and creates the template directory, mode 0700. 106.Sh RETURN VALUES 107The 108.Fn mktemp 109and 110.Fn mkdtemp 111functions return a pointer to the template on success and 112.Dv NULL 113on failure. 114The 115.Fn mkstemp 116and 117.Fn mkstemps 118functions 119return \-1 if no suitable file could be created. 120If either call fails an error code is placed in the global variable 121.Va errno . 122.Sh ERRORS 123The 124.Fn mkstemp , 125.Fn mkstemps 126and 127.Fn mkdtemp 128functions 129may set 130.Va errno 131to one of the following values: 132.Bl -tag -width Er 133.It Bq Er ENOTDIR 134The pathname portion of the template is not an existing directory. 135.El 136.Pp 137The 138.Fn mkstemp , 139.Fn mkstemps 140and 141.Fn mkdtemp 142functions 143may also set 144.Va errno 145to any value specified by the 146.Xr stat 2 147function. 148.Pp 149The 150.Fn mkstemp 151and 152.Fn mkstemps 153functions 154may also set 155.Va errno 156to any value specified by the 157.Xr open 2 158function. 159.Pp 160The 161.Fn mkdtemp 162function 163may also set 164.Va errno 165to any value specified by the 166.Xr mkdir 2 167function. 168.Sh NOTES 169A common problem that results in a core dump is that the programmer 170passes in a read-only string to 171.Fn mktemp , 172.Fn mkstemp , 173.Fn mkstemps 174or 175.Fn mkdtemp . 176This is common with programs that were developed before 177.St -isoC 178compilers were common. 179For example, calling 180.Fn mkstemp 181with an argument of 182.Qq /tmp/tempfile.XXXXXX 183will result in a core dump due to 184.Fn mkstemp 185attempting to modify the string constant that was given. 186If the program in question makes heavy use of that type 187of function call, you do have the option of compiling the program 188so that it will store string constants in a writable segment of memory. 189See 190.Xr gcc 1 191for more information. 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 HISTORY 199A 200.Fn mktemp 201function appeared in 202.At v7 . 203The 204.Fn mkstemp 205function appeared in 206.Bx 4.4 . 207The 208.Fn mkdtemp 209function first appeared in 210.Ox 2.2 , 211and later in 212.Fx 3.2 . 213The 214.Fn mkstemps 215function first appeared in 216.Ox 2.4 , 217and later in 218.Fx 3.4 . 219.Sh BUGS 220This family of functions produces filenames which can be guessed, 221though the risk is minimized when large numbers of 222.Ql X Ns s 223are used to 224increase the number of possible temporary filenames. 225This makes the race in 226.Fn mktemp , 227between testing for a file's existence (in the 228.Fn mktemp 229function call) 230and opening it for use 231(later in the user application) 232particularly dangerous from a security perspective. 233Whenever it is possible, 234.Fn mkstemp 235should be used instead, since it does not have the race condition. 236If 237.Fn mkstemp 238cannot be used, the filename created by 239.Fn mktemp 240should be created using the 241.Dv O_EXCL 242flag to 243.Xr open 2 244and the return status of the call should be tested for failure. 245This will ensure that the program does not continue blindly 246in the event that an attacker has already created the file 247with the intention of manipulating or reading its contents. 248