1.\" $OpenBSD: tmpnam.3,v 1.9 2001/09/22 17:53:59 heko 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. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.Dd November 17, 1993 39.Dt TMPFILE 3 40.Os 41.Sh NAME 42.Nm tempnam , 43.Nm tmpfile , 44.Nm tmpnam 45.Nd temporary file routines 46.Sh SYNOPSIS 47.Fd #include <stdio.h> 48.Ft FILE * 49.Fn tmpfile void 50.Ft char * 51.Fn tmpnam "char *str" 52.Ft char * 53.Fn tempnam "const char *tmpdir" "const char *prefix" 54.Sh DESCRIPTION 55The 56.Fn tmpfile 57function returns a pointer to a stream associated with a file descriptor 58returned by the routine 59.Xr mkstemp 3 . 60The created file is unlinked before 61.Fn tmpfile 62returns, causing the file to be automatically deleted when the last 63reference to it is closed. 64Since 65.Xr mkstemp 3 66creates the file with mode 67.Dv S_IRUSR | S_IWUSR , 68after the unlink 69.Xr fchown 2 70and 71.Xr umask 2 72are used to set the file mode to the expected value. 73The file is opened with the access value 74.Ql w+ . 75.Pp 76The 77.Fn tmpnam 78function returns a pointer to a file name, in the 79.Dv P_tmpdir 80directory, which did not reference an existing file at some 81indeterminate point in the past. 82.Dv P_tmpdir 83is defined in the include file 84.Aq Pa stdio.h . 85If the argument 86.Fa str 87is non-null, the file name is copied to the buffer it references. 88Otherwise, the file name is copied to a static buffer. 89In either case, 90.Fn tmpnam 91returns a pointer to the file name. 92.Pp 93The buffer referenced by 94.Fa str 95is expected to be at least 96.Dv L_tmpnam 97bytes in length. 98.Dv L_tmpnam 99is defined in the include file 100.Aq Pa stdio.h . 101.Pp 102The 103.Fn tempnam 104function is similar to 105.Fn tmpnam , 106but provides the ability to specify the directory which will 107contain the temporary file and the file name prefix. 108.Pp 109The environment variable 110.Ev TMPDIR 111(if set), the argument 112.Fa tmpdir 113(if non-null), 114the directory 115.Dv P_tmpdir , 116and the directory 117.Pa /tmp 118are tried, in the listed order, as directories in which to store the 119temporary file. 120.Pp 121The argument 122.Fa prefix , 123if non-null, is used to specify a file name prefix, which will be the 124first part of the created file name. 125.Fn tempnam 126allocates memory in which to store the file name; the returned pointer 127may be used as a subsequent argument to 128.Xr free 3 . 129.Sh RETURN VALUES 130The 131.Fn tmpfile 132function returns a pointer to an open file stream on success, and a null 133pointer on error. 134.Pp 135The 136.Fn tmpnam 137and 138.Fn tempnam 139functions return a pointer to a file name on success, and a null pointer 140on error. 141.Sh ERRORS 142The 143.Fn tmpfile 144function may fail and set the global variable 145.Va errno 146for any of the errors specified for the library functions 147.Xr fdopen 3 148or 149.Xr mkstemp 3 . 150.Pp 151The 152.Fn tmpnam 153function may fail and set 154.Va errno 155for any of the errors specified for the library function 156.Xr mktemp 3 . 157.Pp 158The 159.Fn tempnam 160function may fail and set 161.Va errno 162for any of the errors specified for the library functions 163.Xr malloc 3 164or 165.Xr mktemp 3 . 166.Sh SEE ALSO 167.Xr mkstemp 3 , 168.Xr mktemp 3 169.Sh STANDARDS 170The 171.Fn tmpfile 172and 173.Fn tmpnam 174functions conform to 175.St -ansiC . 176.Sh BUGS 177.Fn tmpnam 178and 179.Fn tempnam 180are provided for System V and 181.Tn ANSI 182compatibility only. 183These interfaces are typically not used in safe ways. 184The 185.Xr mkstemp 3 186interface is strongly preferred. 187.Pp 188There are four important problems with these interfaces (as well as 189with the historic 190.Xr mktemp 3 191interface). 192First, there is an obvious race between file name selection and file 193creation and deletion: the program is typically written to call 194.Fn tmpnam Ns , 195.Fn tmpname Ns , or 196.Xr mktemp 3 . 197Subsequently, the program calls 198.Xr open 2 199or 200.Xr fopen 3 201and erroneously opens a file (or symbolic link, or fifo or other 202device) that the attacker has placed in the expected file location. 203Hence 204.Xr mkstemp 3 205is recommended, since it atomically creates the file. 206.Pp 207Second, most historic implementations provide only a limited number 208of possible temporary file names (usually 26) before file names will 209start being recycled. 210Third, the System V implementations of these functions (and of 211.Xr mktemp ) 212use the 213.Xr access 2 214function to determine whether or not the temporary file may be created. 215This has obvious ramifications for daemons or setuid/setgid programs, 216complicating the portable use of these interfaces in such programs. 217Finally, there is no specification of the permissions with which the 218temporary files are created. 219.Pp 220This implementation does not have these flaws, but portable software 221cannot depend on that. 222.Pp 223For these reasons, 224.Xr ld 8 225will output a warning message whenever it links code that uses the functions 226.Fn tmpnam 227or 228.Fn tempnam . 229