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