1.\" $NetBSD: tmpnam.3,v 1.5 1998/02/05 18:49:37 perry 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. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)tmpnam.3 8.2 (Berkeley) 11/17/93 39.\" 40.Dd March 24, 1997 41.Dt TMPFILE 3 42.Os 43.Sh NAME 44.Nm tempnam , 45.Nm tmpfile , 46.Nm tmpnam 47.Nd temporary file routines 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.Fd #include <stdio.h> 52.Ft FILE * 53.Fn tmpfile void 54.Ft char * 55.Fn tmpnam "char *str" 56.Ft char * 57.Fn tempnam "const char *tmpdir" "const char *prefix" 58.Sh DESCRIPTION 59The 60.Fn tmpfile 61function 62returns a pointer to a stream associated with a file descriptor returned 63by the routine 64.Xr mkstemp 3 . 65The created file is unlinked before 66.Fn tmpfile 67returns, causing the file to be automatically deleted when the last 68reference to it is closed. 69The file is opened with the access value 70.Ql w+ . 71.Pp 72The 73.Fn tmpnam 74function 75returns a pointer to a file name, in the 76.Dv P_tmpdir 77directory, which 78did not reference an existing file at some indeterminate point in the 79past. 80.Dv P_tmpdir 81is defined in the include file 82.Aq Pa stdio.h . 83If the argument 84.Fa s 85is 86.Pf non- Dv NULL , 87the file name is copied to the buffer it references. 88Otherwise, the file name is copied to a static buffer. 89In either case, 90.Fn tmpnam 91returns a pointer to the file name. 92.Pp 93The buffer referenced by 94.Fa s 95is expected to be at least 96.Dv L_tmpnam 97bytes in length. 98.Dv L_tmpnam 99is defined in the include file 100.Aq Pa stdio.h . 101.Pp 102The 103.Fn tempnam 104function 105is similar to 106.Fn tmpnam , 107but provides the ability to specify the directory which will 108contain the temporary file and the file name prefix. 109.Pp 110The environment variable 111.Ev TMPDIR 112(if set), the argument 113.Fa tmpdir 114(if 115.Pf non- Dv NULL ) , 116the directory 117.Dv P_tmpdir , 118and the directory 119.Pa /tmp 120are tried, in the listed order, as directories in which to store the 121temporary file. 122.Pp 123The argument 124.Fa prefix , 125if 126.Pf non- Dv NULL , 127is used to specify a file name prefix, which will be the 128first part of the created file name. 129.Fn tempnam 130allocates memory in which to store the file name; the returned pointer 131may be used as a subsequent argument to 132.Xr free 3 . 133.Sh RETURN VALUES 134The 135.Fn tmpfile 136function 137returns a pointer to an open file stream on success, and a 138.Dv NULL 139pointer 140on error. 141.Pp 142The 143.Fn tmpnam 144and 145.Fn tempfile 146functions 147return a pointer to a file name on success, and a 148.Dv NULL 149pointer 150on error. 151.Sh ERRORS 152The 153.Fn tmpfile 154function 155may fail and set the global variable 156.Va errno 157for any of the errors specified for the library functions 158.Xr fdopen 3 159or 160.Xr mkstemp 3 . 161.Pp 162The 163.Fn tmpnam 164function 165may fail and set 166.Va errno 167for any of the errors specified for the library function 168.Xr mktemp 3 . 169.Pp 170The 171.Fn tempnam 172function 173may fail and set 174.Va errno 175for any of the errors specified for the library functions 176.Xr malloc 3 177or 178.Xr mktemp 3 . 179.Sh SEE ALSO 180.Xr mkstemp 3 , 181.Xr mktemp 3 182.Sh STANDARDS 183The 184.Fn tmpfile 185and 186.Fn tmpnam 187functions 188conform to 189.St -ansiC . 190.Sh BUGS 191These interfaces are provided for System V and 192.Tn ANSI 193compatibility only. 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. 204Second, most historic implementations provide only a limited number 205of possible temporary file names (usually 26) before file names will 206start being recycled. 207Third, the System V implementations of these functions (and of 208.Xr mktemp ) 209use the 210.Xr access 2 211function to determine whether or not the temporary file may be created. 212This has obvious ramifications for setuid or setgid programs, complicating 213the portable use of these interfaces in such programs. 214Finally, there is no specification of the permissions with which the 215temporary files are created. 216.Pp 217This implementation of 218.Fn tmpfile 219does not have these flaws, 220and that of 221.Fn tmpnam 222and 223.Fn tempnam 224only have the first limitation, but portable software 225cannot depend on that. 226In particular, the 227.Fn tmpfile 228interface should not be used in software expected to be used on other systems 229if there is any possibility that the user does not wish the temporary file to 230be publicly readable and writable. 231.Pp 232A link-time warning will be issued if 233.Fn tmpnam 234or 235.Fn tempnam 236is used, and advises the use of 237.Fn mkstemp 238instead. 239