1.\" $OpenBSD: tmpnam.3,v 1.23 2019/08/30 23:33:45 deraadt 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: August 30 2019 $ 35.Dt TMPNAM 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. 60The file is opened with the access value 61.Ql w+ . 62.Pp 63The 64.Fn tmpnam 65function returns a pointer to a file name, in the 66.Dv P_tmpdir 67directory, which did not reference an existing file at some 68indeterminate point in the past. 69.Dv P_tmpdir 70is defined in the include file 71.In stdio.h . 72If the argument 73.Fa str 74is non-null, the file name is copied to the buffer it references. 75Otherwise, the file name is copied to a static buffer. 76In either case, 77.Fn tmpnam 78returns a pointer to the file name. 79.Pp 80The buffer referenced by 81.Fa str 82is expected to be at least 83.Dv L_tmpnam 84bytes in length. 85.Dv L_tmpnam 86is defined in the include file 87.In stdio.h . 88.Pp 89The 90.Fn tempnam 91function is similar to 92.Fn tmpnam , 93but provides the ability to specify the directory which will 94contain the temporary file and the file name prefix. 95.Pp 96The environment variable 97.Ev TMPDIR 98(if set), the argument 99.Fa tmpdir 100(if non-null), 101the directory 102.Dv P_tmpdir , 103and the directory 104.Pa /tmp 105are tried, in the listed order, as directories in which to store the 106temporary file. 107.Pp 108The argument 109.Fa prefix , 110if non-null, is used to specify a file name prefix, which will be the 111first part of the created file name. 112.Fn tempnam 113allocates memory in which to store the file name; the returned pointer 114may be used as a subsequent argument to 115.Xr free 3 . 116.Sh RETURN VALUES 117The 118.Fn tmpfile 119function returns a pointer to an open file stream on success, and a null 120pointer on error. 121.Pp 122The 123.Fn tmpnam 124and 125.Fn tempnam 126functions return a pointer to a file name on success, and a null pointer 127on error. 128.Sh ENVIRONMENT 129.Bl -tag -width Ds 130.It Ev TMPDIR 131.Pf [ Fn tempnam 132only] 133If set, 134the directory in which the temporary file is stored. 135.Ev TMPDIR 136is ignored for processes 137for which 138.Xr issetugid 2 139is true. 140.El 141.Sh ERRORS 142The 143.Fn tmpfile 144function may fail and set the global variable 145.Va errno 146for any of the errors specified for the library functions 147.Xr fdopen 3 148or 149.Xr mkstemp 3 . 150.Pp 151The 152.Fn tmpnam 153function may fail and set 154.Va errno 155for any of the errors specified for the library function 156.Xr mktemp 3 . 157.Pp 158The 159.Fn tempnam 160function may fail and set 161.Va errno 162for any of the errors specified for the library functions 163.Xr malloc 3 164or 165.Xr mktemp 3 . 166.Sh SEE ALSO 167.Xr issetugid 2 , 168.Xr mkstemp 3 , 169.Xr mktemp 3 170.Sh STANDARDS 171The 172.Fn tmpfile 173and 174.Fn tmpnam 175functions conform to 176.St -ansiC . 177.Sh BUGS 178.Fn tmpnam 179and 180.Fn tempnam 181are provided for System V and ANSI compatibility only. 182These interfaces are typically not used in safe ways. 183The 184.Xr mkstemp 3 185interface is strongly preferred. 186.Pp 187There are four important problems with these interfaces (as well as 188with the historic 189.Xr mktemp 3 190interface). 191First, there is an obvious race between file name selection and file 192creation and deletion: the program is typically written to call 193.Fn tmpnam , 194.Fn tempnam , 195or 196.Xr mktemp 3 . 197Subsequently, the program calls 198.Xr open 2 199or 200.Xr fopen 3 201and erroneously opens a file (or symbolic link, or FIFO or other 202device) that the attacker has placed in the expected file location. 203Hence 204.Xr mkstemp 3 205is recommended, since it atomically creates the file. 206.Pp 207Second, most historic implementations provide only a limited number 208of possible temporary file names (usually 26) before file names will 209start being recycled. 210Third, the System V implementations of these functions (and of 211.Xr mktemp 3 ) 212use the 213.Xr access 2 214function to determine whether or not the temporary file may be created. 215This has obvious ramifications for daemons or setuid/setgid programs, 216complicating the portable use of these interfaces in such programs. 217Finally, there is no specification of the permissions with which the 218temporary files are created. 219.Pp 220This implementation does not have these flaws, but portable software 221cannot depend on that. 222.Pp 223For these reasons, 224.Xr ld 1 225will output a warning message whenever it links code that uses the functions 226.Fn tmpnam 227or 228.Fn tempnam . 229