1.\" $OpenBSD: tmpnam.3,v 1.21 2015/02/28 21:51:57 bentley 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: February 28 2015 $ 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 | 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 ANSI compatibility only. 191These interfaces are typically not used in safe ways. 192The 193.Xr mkstemp 3 194interface is strongly preferred. 195.Pp 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 System V implementations of these functions (and of 220.Xr mktemp 3 ) 221use the 222.Xr access 2 223function to determine whether or not the temporary file may be created. 224This has obvious ramifications for daemons or setuid/setgid programs, 225complicating the portable use of these interfaces in such programs. 226Finally, there is no specification of the permissions with which the 227temporary files are created. 228.Pp 229This implementation does not have these flaws, but portable software 230cannot depend on that. 231.Pp 232For these reasons, 233.Xr ld 1 234will output a warning message whenever it links code that uses the functions 235.Fn tmpnam 236or 237.Fn tempnam . 238