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