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