1.\" $NetBSD: mktemp.3,v 1.30 2014/06/19 09:30:33 wiz Exp $ 2.\" 3.\" Copyright (c) 1989, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)mktemp.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd June 18, 2014 33.Dt MKTEMP 3 34.Os 35.Sh NAME 36.Nm mktemp , 37.Nm mkstemp , 38.Nm mkstemps , 39.Nm mkostemp , 40.Nm mkostemps , 41.Nm mkdtemp 42.Nd make unique temporary file or directory name 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft char * 48.Fn mktemp "char *template" 49.Ft int 50.Fn mkstemp "char *template" 51.Ft int 52.Fn mkostemp "char *template" "int oflags" 53.Ft int 54.Fn mkostemps "char *template" "int suffixlen" "int oflags" 55.Ft char * 56.Fn mkdtemp "char *template" 57.In unistd.h 58.Ft int 59.Fn mkstemps "char *template" "int suffixlen" 60.Sh DESCRIPTION 61The 62.Fn mktemp 63function 64takes the given file name template and overwrites a portion of it 65to create a file name. 66This file name is unique and suitable for use 67by the application. 68The template may be any file name with some number of 69.So Li X 70.Sc Ns s 71appended 72to it, for example 73.Pa /tmp/temp.XXXXXX . 74The trailing 75.So Li X 76.Sc Ns s 77are replaced with the current process number and/or a 78unique letter combination. 79The number of unique file names 80.Fn mktemp 81can return depends on the number of 82.So Li X 83.Sc Ns s 84provided. 85Although the 86.Nx 87implementation of the functions will accept any number of trailing 88.So Li X 89.Sc Ns s , 90for portability reasons one should use only six. 91Using six 92.So Li X 93.Sc Ns s 94will result in 95.Fn mktemp 96testing roughly 26 ** 6 (308915776) combinations. 97.Pp 98The 99.Fn mkstemp 100function 101makes the same replacement to the template and creates the template file, 102mode 0600, returning a file descriptor opened for reading and writing. 103This avoids the race between testing for a file's existence and opening it 104for use. 105The 106.Fn mkostemp 107function 108is like 109.Fn mkstemp 110but allows specifying additional 111.Xr open 2 112flags (defined in 113.In fcntl.h ) . 114The permitted flags are 115.Dv O_APPEND , 116.Dv O_DIRECT , 117.Dv O_SHLOCK , 118.Dv O_EXLOCK , 119.Dv O_SYNC 120and 121.Dv O_CLOEXEC . 122.Pp 123The 124.Fn mkstemps 125and 126.Fn mkostemps 127functions act the same as 128.Fn mkstemp 129and 130.Fn mkostemp 131respectively, 132except they permit a suffix to exist in the template. 133The template should be of the form 134.Pa /tmp/tmpXXXXXXsuffix . 135The 136.Fn mkstemps 137and 138.Fn mkostemps 139function 140are told the length of the suffix string. 141.Pp 142The 143.Fn mkdtemp 144function 145is similar to 146.Fn mkstemp , 147but it creates a mode 0700 directory instead and returns the path. 148.Pp 149Please note that the permissions of the file or directory being created are 150subject to the restrictions imposed by the 151.Xr umask 2 152system call. 153It may thus happen that the created file is unreadable and/or unwritable. 154.Sh RETURN VALUES 155The 156.Fn mktemp 157and 158.Fn mkdtemp 159functions 160return a pointer to the template on success and 161.Dv NULL 162on failure. 163The 164.Fn mkstemp , 165.Fn mkostemp , 166.Fn mkstemps 167and 168.Fn mkostemps 169functions 170returns \-1 if no suitable file could be created. 171If either call fails an error code is placed in the global variable 172.Va errno . 173.Sh EXAMPLES 174Quite often a programmer will want to replace a use of 175.Fn mktemp 176with 177.Fn mkstemp , 178usually to avoid the problems described above. 179Doing this correctly requires a good understanding of the code in question. 180.Pp 181For instance, code of this form: 182.Bd -literal -offset indent 183char sfn[15] = ""; 184FILE *sfp; 185 186strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn); 187if (mktemp(sfn) == NULL || (sfp = fopen(sfn, "w+")) == NULL) { 188 fprintf(stderr, "%s: %s\en", sfn, strerror(errno)); 189 return (NULL); 190} 191return (sfp); 192.Ed 193.Pp 194should be rewritten like this: 195.Bd -literal -offset indent 196char sfn[15] = ""; 197FILE *sfp; 198int fd = -1; 199 200strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn); 201if ((fd = mkstemp(sfn)) == -1 || 202 (sfp = fdopen(fd, "w+")) == NULL) { 203 if (fd != -1) { 204 unlink(sfn); 205 close(fd); 206 } 207 fprintf(stderr, "%s: %s\en", sfn, strerror(errno)); 208 return (NULL); 209} 210return (sfp); 211.Ed 212.Pp 213Often one will find code which uses 214.Fn mktemp 215very early on, perhaps to globally initialize the template nicely, but the 216code which calls 217.Xr open 2 218or 219.Xr fopen 3 220on that filename will occur much later. 221(In almost all cases, the use of 222.Xr fopen 3 223will mean that the flags 224.Dv O_CREAT 225| 226.Dv O_EXCL 227are not given to 228.Xr open 2 , 229and thus a symbolic link race becomes possible, hence making 230necessary the use of 231.Xr fdopen 3 232as seen above). 233Furthermore, one must be careful about code which opens, closes, and then 234re-opens the file in question. 235Finally, one must ensure that upon error the temporary file is 236removed correctly. 237.Pp 238There are also cases where modifying the code to use 239.Fn mktemp , 240in concert with 241.Xr open 2 242using the flags 243.Dv O_CREAT 244| 245.Dv O_EXCL , 246is better, as long as the code retries a new template if 247.Xr open 2 248fails with an 249.Va errno 250of 251.Er EEXIST . 252.Sh ERRORS 253The 254.Fn mkstemp , 255.Fn mkostemp , 256.Fn mkstemps , 257.Fn mkostemps 258and 259.Fn mkdtemp 260functions 261may set 262.Va errno 263to one of the following values: 264.Bl -tag -width Er 265.It Bq Er ENOTDIR 266The pathname portion of the template is not an existing directory. 267.El 268.Pp 269The 270.Fn mktemp , 271.Fn mkstemp 272and 273.Fn mkdtemp 274functions 275may also set 276.Va errno 277to any value specified by the 278.Xr stat 2 279function. 280.Pp 281The 282.Fn mkstemp 283function 284may also set 285.Va errno 286to any value specified by the 287.Xr open 2 288function. 289.Pp 290The 291.Fn mkdtemp 292function 293may also set 294.Va errno 295to any value specified by the 296.Xr mkdir 2 297function. 298.Sh SEE ALSO 299.Xr chmod 2 , 300.Xr getpid 2 , 301.Xr open 2 , 302.Xr stat 2 , 303.Xr umask 2 304.Sh STANDARDS 305The 306.Fn mktemp 307conforms to 308.St -p1003.1-2001 . 309It was however removed from the specification in the 310.St -p1003.1-2008 311revision. 312The 313.Fn mkstemp 314and 315.Fn mkdtemp 316functions conform to 317.St -p1003.1-2004 318and 319.St -p1003.1-2008 , 320respectively. 321.Sh HISTORY 322A 323.Fn mktemp 324function appeared in 325.At v7 . 326.Pp 327The 328.Fn mkstemp 329function appeared in 330.Bx 4.4 . 331.Pp 332The 333.Fn mkdtemp 334function appeared in 335.Nx 1.4 . 336The 337.Fn mkstemps 338function first appeared in 339.Ox 2.4 , 340and later in 341.Fx 3.4 342and 343.Nx 7.0 . 344The 345.Fn mkostemp 346and 347.Fn mkostemps 348functions appeared in 349.Fx 10.0 350and 351.Nx 7.0 . 352.Sh BUGS 353For 354.Fn mktemp 355there is an obvious race between file name selection and file 356creation and deletion: the program is typically written to call 357.Xr tmpnam 3 , 358.Xr tempnam 3 , 359or 360.Fn mktemp . 361Subsequently, the program calls 362.Xr open 2 363or 364.Xr fopen 3 365and erroneously opens a file (or symbolic link, fifo or other 366device) that the attacker has created in the expected file location. 367Hence 368.Fn mkstemp 369is recommended, since it atomically creates the file. 370An attacker can guess the filenames produced by 371.Fn mktemp . 372Whenever it is possible, 373.Fn mkstemp 374or 375.Fn mkdtemp 376should be used instead. 377.Pp 378For this reason, 379.Xr ld 1 380will output a warning message whenever it links code that uses 381.Fn mktemp . 382.Pp 383The 384.Fn mkdtemp 385function is nonstandard and should not be used if portability is required. 386.Sh SECURITY CONSIDERATIONS 387The use of 388.Fn mktemp 389should generally be avoided, as a hostile process can exploit a race 390condition in the time between the generation of a temporary filename by 391.Fn mktemp 392and the invoker's use of the temporary name. 393A link-time warning will be issued advising the use of 394.Fn mkstemp 395or 396.Fn mkdtemp 397instead. 398