1.\" $NetBSD: tmpnam.3,v 1.11 2002/08/20 16:10:01 wiz 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.\" @(#)tmpnam.3 8.2 (Berkeley) 11/17/93 39.\" 40.Dd August 11, 2002 41.Dt TMPFILE 3 42.Os 43.Sh NAME 44.Nm tempnam , 45.Nm tmpfile , 46.Nm tmpnam 47.Nd temporary file routines 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.Fd #include \*[Lt]stdio.h\*[Gt] 52.Ft FILE * 53.Fn tmpfile void 54.Ft char * 55.Fn tmpnam "char *str" 56.Ft char * 57.Fn tempnam "const char *tmpdir" "const char *prefix" 58.Sh DESCRIPTION 59The 60.Fn tmpfile 61function 62returns a pointer to a stream associated with a file descriptor returned 63by the routine 64.Xr mkstemp 3 . 65The created file is unlinked before 66.Fn tmpfile 67returns, causing the file to be automatically deleted when the last 68reference to it is closed. 69The file is opened with the access value 70.Ql w+ . 71.Pp 72The 73.Fn tmpnam 74function 75returns a pointer to a file name, in the 76.Dv P_tmpdir 77directory, which 78did not reference an existing file at some indeterminate point in the 79past. 80.Dv P_tmpdir 81is defined in the include file 82.Aq Pa stdio.h . 83If the argument 84.Fa s 85is 86.Pf non- Dv NULL , 87the 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 s 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 105is similar to 106.Fn tmpnam , 107but provides the ability to specify the directory which will 108contain the temporary file and the file name prefix. 109.Pp 110The environment variable 111.Ev TMPDIR 112(if set), the argument 113.Fa tmpdir 114(if 115.Pf non- Dv NULL ) , 116the directory 117.Dv P_tmpdir , 118and the directory 119.Pa /tmp 120are tried, in the listed order, as directories in which to store the 121temporary file. 122.Pp 123The argument 124.Fa prefix , 125if 126.Pf non- Dv NULL , 127is used to specify a file name prefix, which will be the 128first part of the created file name. 129.Fn tempnam 130allocates memory in which to store the file name; the returned pointer 131may be used as a subsequent argument to 132.Xr free 3 . 133.Sh RETURN VALUES 134The 135.Fn tmpfile 136function 137returns a pointer to an open file stream on success, and a 138.Dv NULL 139pointer 140on error. 141.Pp 142The 143.Fn tmpnam 144and 145.Fn tempnam 146functions 147return a pointer to a file name on success, and a 148.Dv NULL 149pointer 150on error. 151.Sh ERRORS 152The 153.Fn tmpfile 154function 155may fail and set the global variable 156.Va errno 157for any of the errors specified for the library functions 158.Xr fdopen 3 159or 160.Xr mkstemp 3 . 161.Pp 162The 163.Fn tmpnam 164function 165may fail and set 166.Va errno 167for any of the errors specified for the library function 168.Xr mktemp 3 . 169.Pp 170The 171.Fn tempnam 172function 173may fail and set 174.Va errno 175for any of the errors specified for the library functions 176.Xr malloc 3 177or 178.Xr mktemp 3 . 179.Sh SEE ALSO 180.Xr mkstemp 3 , 181.Xr mktemp 3 182.Sh STANDARDS 183The 184.Fn tmpfile 185and 186.Fn tmpnam 187functions 188conform to 189.St -ansiC . 190.Sh BUGS 191These interfaces are provided for 192.At V 193and 194.Tn ANSI 195compatibility only. 196The 197.Xr mkstemp 3 198interface is strongly preferred. 199.Sh SECURITY CONSIDERATIONS 200There are four important problems with these interfaces (as well as 201with the historic 202.Xr mktemp 3 203interface). 204First, there is an obvious race between file name selection and file 205creation and deletion: the program is typically written to call 206.Fn tmpnam , 207.Fn tmpname , 208or 209.Xr mktemp 3 . 210Subsequently, the program calls 211.Xr open 2 212or 213.Xr fopen 3 214and erroneously opens a file (or symbolic link, or fifo or other 215device) that the attacker has placed in the expected file location. 216Hence 217.Xr mkstemp 3 218is recommended, since it atomically creates the file. 219.Pp 220Second, most historic implementations provide only a limited number 221of possible temporary file names (usually 26) before file names will 222start being recycled. 223Third, the 224.At V 225implementations of these functions (and of 226.Xr mktemp 3 ) 227use the 228.Xr access 2 229system call to determine whether or not the temporary file may be created. 230This has obvious ramifications for setuid or setgid programs, complicating 231the portable use of these interfaces in such programs. 232Finally, there is no specification of the permissions with which the 233temporary files are created. 234.Pp 235This implementation of 236.Fn tmpfile 237does not have these flaws, 238and that of 239.Fn tmpnam 240and 241.Fn tempnam 242only have the first limitation, but portable software 243cannot depend on that. 244In particular, the 245.Fn tmpfile 246interface should not be used in software expected to be used on other systems 247if there is any possibility that the user does not wish the temporary file to 248be publicly readable and writable. 249.Pp 250A link-time warning will be issued if 251.Fn tmpnam 252or 253.Fn tempnam 254is used, and advises the use of 255.Fn mkstemp 256instead. 257