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