1.\" $NetBSD: tmpnam.3,v 1.4 1997/03/24 11:39:11 lukem 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 SYNOPSIS 49.Fd #include <stdio.h> 50.Ft FILE * 51.Fn tmpfile void 52.Ft char * 53.Fn tmpnam "char *str" 54.Ft char * 55.Fn tempnam "const char *tmpdir" "const char *prefix" 56.Sh DESCRIPTION 57The 58.Fn tmpfile 59function 60returns a pointer to a stream associated with a file descriptor returned 61by the routine 62.Xr mkstemp 3 . 63The created file is unlinked before 64.Fn tmpfile 65returns, causing the file to be automatically deleted when the last 66reference to it is closed. 67The file is opened with the access value 68.Ql w+ . 69.Pp 70The 71.Fn tmpnam 72function 73returns a pointer to a file name, in the 74.Dv P_tmpdir 75directory, which 76did not reference an existing file at some indeterminate point in the 77past. 78.Dv P_tmpdir 79is defined in the include file 80.Aq Pa stdio.h . 81If the argument 82.Fa s 83is 84.Pf non- Dv NULL , 85the file name is copied to the buffer it references. 86Otherwise, the file name is copied to a static buffer. 87In either case, 88.Fn tmpnam 89returns a pointer to the file name. 90.Pp 91The buffer referenced by 92.Fa s 93is expected to be at least 94.Dv L_tmpnam 95bytes in length. 96.Dv L_tmpnam 97is defined in the include file 98.Aq Pa stdio.h . 99.Pp 100The 101.Fn tempnam 102function 103is similar to 104.Fn tmpnam , 105but provides the ability to specify the directory which will 106contain the temporary file and the file name prefix. 107.Pp 108The environment variable 109.Ev TMPDIR 110(if set), the argument 111.Fa tmpdir 112(if 113.Pf non- Dv NULL ) , 114the directory 115.Dv P_tmpdir , 116and the directory 117.Pa /tmp 118are tried, in the listed order, as directories in which to store the 119temporary file. 120.Pp 121The argument 122.Fa prefix , 123if 124.Pf non- Dv NULL , 125is used to specify a file name prefix, which will be the 126first part of the created file name. 127.Fn tempnam 128allocates memory in which to store the file name; the returned pointer 129may be used as a subsequent argument to 130.Xr free 3 . 131.Sh RETURN VALUES 132The 133.Fn tmpfile 134function 135returns a pointer to an open file stream on success, and a 136.Dv NULL 137pointer 138on error. 139.Pp 140The 141.Fn tmpnam 142and 143.Fn tempfile 144functions 145return a pointer to a file name on success, and a 146.Dv NULL 147pointer 148on error. 149.Sh ERRORS 150The 151.Fn tmpfile 152function 153may 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 163may fail and set 164.Va errno 165for any of the errors specified for the library function 166.Xr mktemp 3 . 167.Pp 168The 169.Fn tempnam 170function 171may fail and set 172.Va errno 173for any of the errors specified for the library functions 174.Xr malloc 3 175or 176.Xr mktemp 3 . 177.Sh SEE ALSO 178.Xr mkstemp 3 , 179.Xr mktemp 3 180.Sh STANDARDS 181The 182.Fn tmpfile 183and 184.Fn tmpnam 185functions 186conform to 187.St -ansiC . 188.Sh BUGS 189These interfaces are provided for System V and 190.Tn ANSI 191compatibility only. 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. 202Second, most historic implementations provide only a limited number 203of possible temporary file names (usually 26) before file names will 204start being recycled. 205Third, the System V implementations of these functions (and of 206.Xr mktemp ) 207use the 208.Xr access 2 209function to determine whether or not the temporary file may be created. 210This has obvious ramifications for setuid or setgid programs, complicating 211the portable use of these interfaces in such programs. 212Finally, there is no specification of the permissions with which the 213temporary files are created. 214.Pp 215This implementation of 216.Fn tmpfile 217does not have these flaws, 218and that of 219.Fn tmpnam 220and 221.Fn tempnam 222only have the first limitation, but portable software 223cannot depend on that. 224In particular, the 225.Fn tmpfile 226interface should not be used in software expected to be used on other systems 227if there is any possibility that the user does not wish the temporary file to 228be publicly readable and writable. 229.Pp 230A link-time warning will be issued if 231.Fn tmpnam 232or 233.Fn tempnam 234is used, and advises the use of 235.Fn mkstemp 236instead. 237