1.\" $OpenBSD: tmpnam.3,v 1.19 2014/01/21 03:15:45 schwarze 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 $Mdocdate: January 21 2014 $ 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.In 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.In 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.In 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 ENVIRONMENT 138.Bl -tag -width Ds 139.It Ev TMPDIR 140.Pf [ Fn tempnam 141only] 142If set, 143the directory in which the temporary file is stored. 144.Ev TMPDIR 145is ignored for processes 146for which 147.Xr issetugid 2 148is true. 149.El 150.Sh ERRORS 151The 152.Fn tmpfile 153function may fail and set the global variable 154.Va errno 155for any of the errors specified for the library functions 156.Xr fdopen 3 157or 158.Xr mkstemp 3 . 159.Pp 160The 161.Fn tmpnam 162function may fail and set 163.Va errno 164for any of the errors specified for the library function 165.Xr mktemp 3 . 166.Pp 167The 168.Fn tempnam 169function may 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 issetugid 2 , 177.Xr mkstemp 3 , 178.Xr mktemp 3 179.Sh STANDARDS 180The 181.Fn tmpfile 182and 183.Fn tmpnam 184functions conform to 185.St -ansiC . 186.Sh BUGS 187.Fn tmpnam 188and 189.Fn tempnam 190are provided for System V and 191.Tn ANSI 192compatibility only. 193These interfaces are typically not used in safe ways. 194The 195.Xr mkstemp 3 196interface is strongly preferred. 197.Pp 198There are four important problems with these interfaces (as well as 199with the historic 200.Xr mktemp 3 201interface). 202First, there is an obvious race between file name selection and file 203creation and deletion: the program is typically written to call 204.Fn tmpnam , 205.Fn tempnam , 206or 207.Xr mktemp 3 . 208Subsequently, the program calls 209.Xr open 2 210or 211.Xr fopen 3 212and erroneously opens a file (or symbolic link, or FIFO or other 213device) that the attacker has placed in the expected file location. 214Hence 215.Xr mkstemp 3 216is recommended, since it atomically creates the file. 217.Pp 218Second, most historic implementations provide only a limited number 219of possible temporary file names (usually 26) before file names will 220start being recycled. 221Third, the System V implementations of these functions (and of 222.Xr mktemp 3 ) 223use the 224.Xr access 2 225function to determine whether or not the temporary file may be created. 226This has obvious ramifications for daemons or setuid/setgid programs, 227complicating the 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 does not have these flaws, but portable software 232cannot depend on that. 233.Pp 234For these reasons, 235.Xr ld 1 236will output a warning message whenever it links code that uses the functions 237.Fn tmpnam 238or 239.Fn tempnam . 240