1.\" $OpenBSD: tmpnam.3,v 1.14 2005/07/26 03:30:25 jaredy Exp $ 2.\" 3.\" Copyright (c) 1988, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. 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.Dd November 17, 1993 35.Dt TMPFILE 3 36.Os 37.Sh NAME 38.Nm tempnam , 39.Nm tmpfile , 40.Nm tmpnam 41.Nd temporary file routines 42.Sh SYNOPSIS 43.Fd #include <stdio.h> 44.Ft FILE * 45.Fn tmpfile void 46.Ft char * 47.Fn tmpnam "char *str" 48.Ft char * 49.Fn tempnam "const char *tmpdir" "const char *prefix" 50.Sh DESCRIPTION 51The 52.Fn tmpfile 53function returns a pointer to a stream associated with a file descriptor 54returned by the routine 55.Xr mkstemp 3 . 56The created file is unlinked before 57.Fn tmpfile 58returns, causing the file to be automatically deleted when the last 59reference to it is closed. 60Since 61.Xr mkstemp 3 62creates the file with mode 63.Dv S_IRUSR \*(Ba S_IWUSR , 64after the unlink, 65.Xr fchown 2 66and 67.Xr umask 2 68are used to set the file mode to the expected value. 69The file is opened with the access value 70.Ql w+ . 71.Pp 72The 73.Fn tmpnam 74function returns a pointer to a file name, in the 75.Dv P_tmpdir 76directory, which did not reference an existing file at some 77indeterminate point in the past. 78.Dv P_tmpdir 79is defined in the include file 80.Aq Pa stdio.h . 81If the argument 82.Fa str 83is non-null, the file name is copied to the buffer it references. 84Otherwise, the file name is copied to a static buffer. 85In either case, 86.Fn tmpnam 87returns a pointer to the file name. 88.Pp 89The buffer referenced by 90.Fa str 91is expected to be at least 92.Dv L_tmpnam 93bytes in length. 94.Dv L_tmpnam 95is defined in the include file 96.Aq Pa stdio.h . 97.Pp 98The 99.Fn tempnam 100function is similar to 101.Fn tmpnam , 102but provides the ability to specify the directory which will 103contain the temporary file and the file name prefix. 104.Pp 105The environment variable 106.Ev TMPDIR 107(if set), the argument 108.Fa tmpdir 109(if non-null), 110the directory 111.Dv P_tmpdir , 112and the directory 113.Pa /tmp 114are tried, in the listed order, as directories in which to store the 115temporary file. 116.Pp 117The argument 118.Fa prefix , 119if non-null, is used to specify a file name prefix, which will be the 120first part of the created file name. 121.Fn tempnam 122allocates memory in which to store the file name; the returned pointer 123may be used as a subsequent argument to 124.Xr free 3 . 125.Sh RETURN VALUES 126The 127.Fn tmpfile 128function returns a pointer to an open file stream on success, and a null 129pointer on error. 130.Pp 131The 132.Fn tmpnam 133and 134.Fn tempnam 135functions return a pointer to a file name on success, and a null pointer 136on error. 137.Sh ERRORS 138The 139.Fn tmpfile 140function may fail and set the global variable 141.Va errno 142for any of the errors specified for the library functions 143.Xr fdopen 3 144or 145.Xr mkstemp 3 . 146.Pp 147The 148.Fn tmpnam 149function may fail and set 150.Va errno 151for any of the errors specified for the library function 152.Xr mktemp 3 . 153.Pp 154The 155.Fn tempnam 156function may fail and set 157.Va errno 158for any of the errors specified for the library functions 159.Xr malloc 3 160or 161.Xr mktemp 3 . 162.Sh SEE ALSO 163.Xr mkstemp 3 , 164.Xr mktemp 3 165.Sh STANDARDS 166The 167.Fn tmpfile 168and 169.Fn tmpnam 170functions conform to 171.St -ansiC . 172.Sh BUGS 173.Fn tmpnam 174and 175.Fn tempnam 176are provided for System V and 177.Tn ANSI 178compatibility only. 179These interfaces are typically not used in safe ways. 180The 181.Xr mkstemp 3 182interface is strongly preferred. 183.Pp 184There are four important problems with these interfaces (as well as 185with the historic 186.Xr mktemp 3 187interface). 188First, there is an obvious race between file name selection and file 189creation and deletion: the program is typically written to call 190.Fn tmpnam , 191.Fn tmpname , 192or 193.Xr mktemp 3 . 194Subsequently, the program calls 195.Xr open 2 196or 197.Xr fopen 3 198and erroneously opens a file (or symbolic link, or FIFO or other 199device) that the attacker has placed in the expected file location. 200Hence 201.Xr mkstemp 3 202is recommended, since it atomically creates the file. 203.Pp 204Second, most historic implementations provide only a limited number 205of possible temporary file names (usually 26) before file names will 206start being recycled. 207Third, the System V implementations of these functions (and of 208.Xr mktemp 3 ) 209use the 210.Xr access 2 211function to determine whether or not the temporary file may be created. 212This has obvious ramifications for daemons or setuid/setgid programs, 213complicating the portable use of these interfaces in such programs. 214Finally, there is no specification of the permissions with which the 215temporary files are created. 216.Pp 217This implementation does not have these flaws, but portable software 218cannot depend on that. 219.Pp 220For these reasons, 221.Xr ld 1 222will output a warning message whenever it links code that uses the functions 223.Fn tmpnam 224or 225.Fn tempnam . 226