1.\" $NetBSD: mktemp.3,v 1.17 2002/10/01 17:24:05 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)mktemp.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd July 28, 1998 37.Dt MKTEMP 3 38.Os 39.Sh NAME 40.Nm mktemp , 41.Nm mkstemp , 42.Nm mkdtemp 43.Nd make unique temporary file or directory name 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.Fd #include \*[Lt]stdlib.h\*[Gt] 48.Ft char * 49.Fn mktemp "char *template" 50.Ft int 51.Fn mkstemp "char *template" 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 unique and 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.XXXX . 67The trailing 68.Ql X Ns s 69are replaced with the current process number and/or a 70unique letter 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 80testing roughly 26 ** 6 combinations. 81At least 6 82.So Li X 83.Sc Ns s 84should be used, though 10 is much better. 85.Pp 86The 87.Fn mkstemp 88function 89makes the same replacement to the template and creates the template file, 90mode 0600, returning a file descriptor opened for reading and writing. 91This avoids the race between testing for a file's existence and opening it 92for use. 93.Pp 94The 95.Fn mkdtemp 96function 97is similar to 98.Fn mkstemp , 99but it creates a mode 0700 directory instead and returns the path. 100.Pp 101Please note that the permissions of the file or directory being created are 102subject to the restrictions imposed by the 103.Xr umask 2 104system call. 105It may thus happen that the created file is unreadable and/or unwritable. 106.Sh RETURN VALUES 107The 108.Fn mktemp 109and 110.Fn mkdtemp 111functions 112return a pointer to the template on success and 113.Dv NULL 114on failure. 115The 116.Fn mkstemp 117function 118returns \-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 EXAMPLES 122Quite often a programmer will want to replace a use of 123.Fn mktemp 124with 125.Fn mkstemp , 126usually to avoid the problems described above. 127Doing this correctly requires a good understanding of the code in question. 128.Pp 129For instance, code of this form: 130.Bd -literal -offset indent 131char sfn[15] = ""; 132FILE *sfp; 133 134strcpy(sfn, "/tmp/ed.XXXXXX"); 135if (mktemp(sfn) == NULL || (sfp = fopen(sfn, "w+")) == NULL) { 136 fprintf(stderr, "%s: %s\en", sfn, strerror(errno)); 137 return (NULL); 138} 139return (sfp); 140.Ed 141.Pp 142should be rewritten like this: 143.Bd -literal -offset indent 144char sfn[15] = ""; 145FILE *sfp; 146int fd = -1; 147 148strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn); 149if ((fd = mkstemp(sfn)) == -1 || 150 (sfp = fdopen(fd, "w+")) == NULL) { 151 if (fd != -1) { 152 unlink(sfn); 153 close(fd); 154 } 155 fprintf(stderr, "%s: %s\en", sfn, strerror(errno)); 156 return (NULL); 157} 158return (sfp); 159.Ed 160.Pp 161Often one will find code which uses 162.Fn mktemp 163very early on, perhaps to globally initialize the template nicely, but the 164code which calls 165.Xr open 2 166or 167.Xr fopen 3 168on that filename will occur much later. 169(In almost all cases, the use of 170.Xr fopen 3 171will mean that the flags 172.Dv O_CREAT 173| 174.Dv O_EXCL 175are not given to 176.Xr open 2 , 177and thus a symbolic link race becomes possible, hence making 178necessary the use of 179.Xr fdopen 3 180as seen above). 181Furthermore, one must be careful about code which opens, closes, and then 182re-opens the file in question. 183Finally, one must ensure that upon error the temporary file is 184removed correctly. 185.Pp 186There are also cases where modifying the code to use 187.Fn mktemp , 188in concert with 189.Xr open 2 190using the flags 191.Dv O_CREAT 192| 193.Dv O_EXCL , 194is better, as long as the code retries a new template if 195.Xr open 2 196fails with an 197.Va errno 198of 199.Er EEXIST . 200.Sh ERRORS 201The 202.Fn mktemp , 203.Fn mkstemp 204and 205.Fn mkdtemp 206functions 207may set 208.Va errno 209to one of the following values: 210.Bl -tag -width Er 211.It Bq Er ENOTDIR 212The pathname portion of the template is not an existing directory. 213.El 214.Pp 215The 216.Fn mktemp , 217.Fn mkstemp 218and 219.Fn mkdtemp 220functions 221may also set 222.Va errno 223to any value specified by the 224.Xr stat 2 225function. 226.Pp 227The 228.Fn mkstemp 229function 230may also set 231.Va errno 232to any value specified by the 233.Xr open 2 234function. 235.Pp 236The 237.Fn mkdtemp 238function 239may also set 240.Va errno 241to any value specified by the 242.Xr mkdir 2 243function. 244.Sh SEE ALSO 245.Xr chmod 2 , 246.Xr getpid 2 , 247.Xr open 2 , 248.Xr stat 2 , 249.Xr umask 2 250.Sh HISTORY 251A 252.Fn mktemp 253function appeared in 254.At v7 . 255.Pp 256The 257.Fn mkstemp 258function appeared in 259.Bx 4.4 . 260.Pp 261The 262.Fn mkdtemp 263function appeared in 264.Nx 1.4 . 265.Sh BUGS 266For 267.Fn mktemp 268there is an obvious race between file name selection and file 269creation and deletion: the program is typically written to call 270.Xr tmpnam 3 , 271.Xr tempnam 3 , 272or 273.Fn mktemp . 274Subsequently, the program calls 275.Xr open 2 276or 277.Xr fopen 3 278and erroneously opens a file (or symbolic link, fifo or other 279device) that the attacker has created in the expected file location. 280Hence 281.Fn mkstemp 282is recommended, since it atomically creates the file. 283An attacker can guess the filenames produced by 284.Fn mktemp . 285Whenever it is possible, 286.Fn mkstemp 287or 288.Fn mkdtemp 289should be used instead. 290.Pp 291For this reason, 292.Xr ld 8 293will output a warning message whenever it links code that uses the 294.Fn mktemp . 295.Pp 296The 297.Fn mkdtemp 298function is nonstandard and should not be used if portability is required. 299.Sh SECURITY CONSIDERATIONS 300The use of 301.Fn mktemp 302should generally be avoided, as a hostile process can exploit a race 303condition in the time between the generation of a temporary filename by 304.Fn mktemp 305and the invoker's use of the temporary name. 306A link-time warning will be issued advising the use of 307.Fn mkstemp 308or 309.Fn mkdtemp 310instead. 311