1.\" $NetBSD: tmpnam.3,v 1.15 2005/06/18 10:50:25 lukem 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 June 18, 2005 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.Aq Pa 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.Aq Pa 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 . 186.Sh BUGS 187These interfaces are provided for 188.At V 189and 190.Tn ANSI 191compatibility only. 192The 193.Xr mkstemp 3 194interface is strongly preferred. 195.Sh SECURITY CONSIDERATIONS 196There are four important problems with these interfaces (as well as 197with the historic 198.Xr mktemp 3 199interface). 200First, there is an obvious race between file name selection and file 201creation and deletion: the program is typically written to call 202.Fn tmpnam , 203.Fn tempnam , 204or 205.Xr mktemp 3 . 206Subsequently, the program calls 207.Xr open 2 208or 209.Xr fopen 3 210and erroneously opens a file (or symbolic link, or fifo or other 211device) that the attacker has placed in the expected file location. 212Hence 213.Xr mkstemp 3 214is recommended, since it atomically creates the file. 215.Pp 216Second, most historic implementations provide only a limited number 217of possible temporary file names (usually 26) before file names will 218start being recycled. 219Third, the 220.At V 221implementations of these functions (and of 222.Xr mktemp 3 ) 223use the 224.Xr access 2 225system call to determine whether or not the temporary file may be created. 226This has obvious ramifications for setuid or setgid programs, complicating 227the portable use of these interfaces in such programs. 228Finally, there is no specification of the permissions with which the 229temporary files are created. 230.Pp 231This implementation of 232.Fn tmpfile 233does not have these flaws, 234and that of 235.Fn tmpnam 236and 237.Fn tempnam 238only have the first limitation, but portable software 239cannot depend on that. 240In particular, the 241.Fn tmpfile 242interface should not be used in software expected to be used on other systems 243if there is any possibility that the user does not wish the temporary file to 244be publicly readable and writable. 245.Pp 246A link-time warning will be issued if 247.Fn tmpnam 248or 249.Fn tempnam 250is used, and advises the use of 251.Fn mkstemp 252instead. 253