1.\" Copyright (c) 1988, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the American National Standards Committee X3, on Information 6.\" Processing Systems. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)tmpnam.3 8.2 (Berkeley) 11/17/93 33.\" $FreeBSD: src/lib/libc/stdio/tmpnam.3,v 1.20 2007/03/16 21:46:24 maxim Exp $ 34.\" $DragonFly: src/lib/libc/stdio/tmpnam.3,v 1.4 2008/09/24 19:48:40 swildner Exp $ 35.\" 36.Dd March 18, 2007 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+ . 67The file is created in the directory determined by the environment variable 68.Ev TMPDIR 69if set. 70The default location if 71.Ev TMPDIR 72is not set is 73.Pa /tmp . 74.Pp 75The 76.Fn tmpnam 77function 78returns a pointer to a file name, in the 79.Dv P_tmpdir 80directory, which 81did not reference an existing file at some indeterminate point in the 82past. 83.Dv P_tmpdir 84is defined in the include file 85.In stdio.h . 86If the argument 87.Fa str 88is 89.Pf non- Dv NULL , 90the file name is copied to the buffer it references. 91Otherwise, the file name is copied to a static buffer. 92In either case, 93.Fn tmpnam 94returns a pointer to the file name. 95.Pp 96The buffer referenced by 97.Fa str 98is expected to be at least 99.Dv L_tmpnam 100bytes in length. 101.Dv L_tmpnam 102is defined in the include file 103.In stdio.h . 104.Pp 105The 106.Fn tempnam 107function 108is similar to 109.Fn tmpnam , 110but provides the ability to specify the directory which will 111contain the temporary file and the file name prefix. 112.Pp 113The environment variable 114.Ev TMPDIR 115(if set), the argument 116.Fa tmpdir 117(if 118.Pf non- Dv NULL ) , 119the directory 120.Dv P_tmpdir , 121and the directory 122.Pa /tmp 123are tried, in the listed order, as directories in which to store the 124temporary file. 125.Pp 126The argument 127.Fa prefix , 128if 129.Pf non- Dv NULL , 130is used to specify a file name prefix, which will be the 131first part of the created file name. 132The 133.Fn tempnam 134function 135allocates memory in which to store the file name; the returned pointer 136may be used as a subsequent argument to 137.Xr free 3 . 138.Sh RETURN VALUES 139The 140.Fn tmpfile 141function 142returns a pointer to an open file stream on success, and a 143.Dv NULL 144pointer 145on error. 146.Pp 147The 148.Fn tmpnam 149and 150.Fn tempnam 151functions 152return a pointer to a file name on success, and a 153.Dv NULL 154pointer 155on error. 156.Sh ENVIRONMENT 157.Bl -tag -width Ds 158.It Ev TMPDIR 159.Pf [ Fn tempnam 160only] 161If set, 162the directory in which the temporary file is stored. 163.Ev TMPDIR 164is ignored for processes 165for which 166.Xr issetugid 2 167is true. 168.El 169.Sh COMPATIBILITY 170These interfaces are provided from System V and 171.Tn ANSI 172compatibility only. 173.Pp 174Most historic implementations of these functions provide 175only a limited number of possible temporary file names 176(usually 26) 177before file names will start being recycled. 178System V implementations of these functions 179(and of 180.Xr mktemp 3 ) 181use the 182.Xr access 2 183system call to determine whether or not the temporary file 184may be created. 185This has obvious ramifications for setuid or setgid programs, 186complicating the portable use of these interfaces in such programs. 187.Pp 188The 189.Fn tmpfile 190interface should not be used in software expected to be used on other systems 191if there is any possibility that the user does not wish the temporary file to 192be publicly readable and writable. 193.Sh ERRORS 194The 195.Fn tmpfile 196function 197may fail and set the global variable 198.Va errno 199for any of the errors specified for the library functions 200.Xr fdopen 3 201or 202.Xr mkstemp 3 . 203.Pp 204The 205.Fn tmpnam 206function 207may fail and set 208.Va errno 209for any of the errors specified for the library function 210.Xr mktemp 3 . 211.Pp 212The 213.Fn tempnam 214function 215may fail and set 216.Va errno 217for any of the errors specified for the library functions 218.Xr malloc 3 219or 220.Xr mktemp 3 . 221.Sh SECURITY CONSIDERATIONS 222The 223.Fn tmpnam 224and 225.Fn tempnam 226functions are susceptible to a race condition 227occurring between the selection of the file name 228and the creation of the file, 229which allows malicious users 230to potentially overwrite arbitrary files in the system, 231depending on the level of privilege of the running program. 232Additionally, there is no means by which 233file permissions may be specified. 234It is strongly suggested that 235.Xr mkstemp 3 236be used in place of these functions. 237.Sh SEE ALSO 238.Xr mkstemp 3 , 239.Xr mktemp 3 240.Sh STANDARDS 241The 242.Fn tmpfile 243and 244.Fn tmpnam 245functions 246conform to 247.St -isoC . 248