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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)mktemp.3 8.1 (Berkeley) 6/4/93 29.\" $FreeBSD: head/lib/libc/stdio/mktemp.3 254151 2013-08-09 17:24:23Z jilles $ 30.\" 31.Dd July 29, 2016 32.Dt MKTEMP 3 33.Os 34.Sh NAME 35.Nm mktemp 36.Nd make temporary file name (unique) 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In stdlib.h 41.Ft char * 42.Fn mktemp "char *template" 43.Ft int 44.Fn mkstemp "char *template" 45.Ft int 46.Fn mkostemp "char *template" "int oflags" 47.Ft int 48.Fn mkostemps "char *template" "int suffixlen" "int oflags" 49.Ft char * 50.Fn mkdtemp "char *template" 51.In unistd.h 52.Ft int 53.Fn mkstemps "char *template" "int suffixlen" 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 mkostemp 93function is like 94.Fn mkstemp 95but allows specifying additional 96.Xr open 2 97flags (defined in 98.In fcntl.h ) . 99The permitted flags are 100.Dv O_APPEND , 101.Dv O_DIRECT , 102.Dv O_SHLOCK , 103.Dv O_EXLOCK , 104.Dv O_SYNC 105and 106.Dv O_CLOEXEC . 107.Pp 108The 109.Fn mkstemps 110and 111.Fn mkostemps 112functions act the same as 113.Fn mkstemp 114and 115.Fn mkostemp 116respectively, 117except they permit a suffix to exist in the template. 118The template should be of the form 119.Pa /tmp/tmpXXXXXXsuffix . 120The 121.Fn mkstemps 122and 123.Fn mkostemps 124function 125are told the length of the suffix string. 126.Pp 127The 128.Fn mkostemps 129function is like 130.Fn mkstemps 131but allows specifying additional 132.Xr open 2 133flags such as 134.Dv O_CLOEXEC . 135.Pp 136The 137.Fn mkdtemp 138function makes the same replacement to the template as in 139.Fn mktemp 140and creates the template directory, mode 0700. 141.Sh RETURN VALUES 142The 143.Fn mktemp 144and 145.Fn mkdtemp 146functions return a pointer to the template on success and 147.Dv NULL 148on failure. 149The 150.Fn mkstemp , 151.Fn mkostemp , 152.Fn mkstemps 153and 154.Fn mkostemps 155functions 156return \-1 if no suitable file could be created. 157If either call fails an error code is placed in the global variable 158.Va errno . 159.Sh ERRORS 160The 161.Fn mkstemp , 162.Fn mkostemp , 163.Fn mkstemps , 164.Fn mkostemps 165and 166.Fn mkdtemp 167functions 168may set 169.Va errno 170to one of the following values: 171.Bl -tag -width Er 172.It Bq Er ENOTDIR 173The pathname portion of the template is not an existing directory. 174.El 175.Pp 176The 177.Fn mkostemp 178and 179.Fn mkostemps 180functions 181may also set 182.Va errno 183to the following value: 184.Bl -tag -width Er 185.It Bq Er EINVAL 186The 187.Fa oflags 188argument is invalid. 189.El 190.Pp 191The 192.Fn mkstemp , 193.Fn mkostemp , 194.Fn mkstemps , 195.Fn mkostemps 196and 197.Fn mkdtemp 198functions 199may also set 200.Va errno 201to any value specified by the 202.Xr stat 2 203function. 204.Pp 205The 206.Fn mkstemp , 207.Fn mkostemp , 208.Fn mkstemps 209and 210.Fn mkostemps 211functions 212may also set 213.Va errno 214to any value specified by the 215.Xr open 2 216function. 217.Pp 218The 219.Fn mkdtemp 220function 221may also set 222.Va errno 223to any value specified by the 224.Xr mkdir 2 225function. 226.Sh NOTES 227A common problem that results in a core dump is that the programmer 228passes in a read-only string to 229.Fn mktemp , 230.Fn mkstemp , 231.Fn mkstemps 232or 233.Fn mkdtemp . 234This is common with programs that were developed before 235.St -isoC 236compilers were common. 237For example, calling 238.Fn mkstemp 239with an argument of 240.Qq /tmp/tempfile.XXXXXX 241will result in a core dump due to 242.Fn mkstemp 243attempting to modify the string constant that was given. 244.Pp 245The 246.Fn mkdtemp , 247.Fn mkstemp 248and 249.Fn mktemp 250function prototypes are also available from 251.In unistd.h . 252.Sh SEE ALSO 253.Xr chmod 2 , 254.Xr getpid 2 , 255.Xr mkdir 2 , 256.Xr open 2 , 257.Xr stat 2 258.Sh STANDARDS 259The 260.Fn mkstemp 261and 262.Fn mkdtemp 263functions are expected to conform to 264.St -p1003.1-2008 . 265The 266.Fn mktemp 267function is expected to conform to 268.St -p1003.1-2001 269and is not specified by 270.St -p1003.1-2008 . 271.Sh HISTORY 272A 273.Fn mktemp 274function appeared in 275.At v7 . 276The 277.Fn mkstemp 278function appeared in 279.Bx 4.4 . 280The 281.Fn mkdtemp 282function first appeared in 283.Ox 2.2 , 284and later in 285.Fx 3.2 . 286The 287.Fn mkstemps 288function first appeared in 289.Ox 2.4 , 290and later in 291.Fx 3.4 . 292The 293.Fn mkostemp 294and 295.Fn mkostemps 296functions appeared in 297.Fx 10.0 298and were imported to 299.Dx 4.6 . 300.Sh BUGS 301This family of functions produces filenames which can be guessed, 302though the risk is minimized when large numbers of 303.Ql X Ns s 304are used to 305increase the number of possible temporary filenames. 306This makes the race in 307.Fn mktemp , 308between testing for a file's existence (in the 309.Fn mktemp 310function call) 311and opening it for use 312(later in the user application) 313particularly dangerous from a security perspective. 314Whenever it is possible, 315.Fn mkstemp 316or 317.Fn mkostemp 318should be used instead, since it does not have the race condition. 319If 320.Fn mkstemp 321cannot be used, the filename created by 322.Fn mktemp 323should be created using the 324.Dv O_EXCL 325flag to 326.Xr open 2 327and the return status of the call should be tested for failure. 328This will ensure that the program does not continue blindly 329in the event that an attacker has already created the file 330with the intention of manipulating or reading its contents. 331