| blob | 3ece3f9904d12828082b90aebabeb995ef8194db |
1 .\" $NetBSD: tmpnam.3,v 1.17 2010/04/30 04:55:10 jruoho 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 .\" @(#)tmpnam.3 8.2 (Berkeley) 11/17/93
35 .\"
36 .Dd April 30, 2010
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
55 The
56 .Fn tmpfile
57 function
58 returns a pointer to a stream associated with a file descriptor returned
59 by the routine
60 .Xr mkstemp 3 .
61 The created file is unlinked before
62 .Fn tmpfile
63 returns, causing the file to be automatically deleted when the last
64 reference to it is closed.
65 The file is opened with the access value
66 .Ql w+ .
67 .Pp
68 The
69 .Fn tmpnam
70 function
71 returns a pointer to a file name, in the
72 .Dv P_tmpdir
73 directory, which
74 did not reference an existing file at some indeterminate point in the
75 past.
76 .Dv P_tmpdir
77 is defined in the include file
78 .In stdio.h .
79 If the argument
80 .Fa s
81 is
82 .Pf non- Dv NULL ,
83 the file name is copied to the buffer it references.
84 Otherwise, the file name is copied to a static buffer.
85 In either case,
86 .Fn tmpnam
87 returns a pointer to the file name.
88 .Pp
89 The buffer referenced by
90 .Fa s
91 is expected to be at least
92 .Dv L_tmpnam
93 bytes in length.
94 .Dv L_tmpnam
95 is defined in the include file
96 .In stdio.h .
97 .Pp
98 The
99 .Fn tempnam
100 function
101 is similar to
102 .Fn tmpnam ,
103 but provides the ability to specify the directory which will
104 contain the temporary file and the file name prefix.
105 .Pp
106 The environment variable
107 .Ev TMPDIR
108 (if set), the argument
109 .Fa tmpdir
110 (if
111 .Pf non- Dv NULL ) ,
112 the directory
113 .Dv P_tmpdir ,
114 and the directory
115 .Pa /tmp
116 are tried, in the listed order, as directories in which to store the
117 temporary file.
118 .Pp
119 The argument
120 .Fa prefix ,
121 if
122 .Pf non- Dv NULL ,
123 is used to specify a file name prefix, which will be the
124 first part of the created file name.
125 .Fn tempnam
126 allocates memory in which to store the file name; the returned pointer
127 may be used as a subsequent argument to
128 .Xr free 3 .
129 .Sh RETURN VALUES
130 The
131 .Fn tmpfile
132 function
133 returns a pointer to an open file stream on success, and a
134 .Dv NULL
135 pointer
136 on error.
137 .Pp
138 The
139 .Fn tmpnam
140 and
141 .Fn tempnam
142 functions
143 return a pointer to a file name on success, and a
144 .Dv NULL
145 pointer
146 on error.
147 .Sh ERRORS
148 The
149 .Fn tmpfile
150 function
151 may fail and set the global variable
152 .Va errno
153 for any of the errors specified for the library functions
154 .Xr fdopen 3
155 or
156 .Xr mkstemp 3 .
157 .Pp
158 The
159 .Fn tmpnam
160 function
161 may fail and set
162 .Va errno
163 for any of the errors specified for the library function
164 .Xr mktemp 3 .
165 .Pp
166 The
167 .Fn tempnam
168 function
169 may fail and set
170 .Va errno
171 for any of the errors specified for the library functions
172 .Xr malloc 3
173 or
174 .Xr mktemp 3 .
175 .Sh SEE ALSO
176 .Xr mkstemp 3 ,
177 .Xr mktemp 3
178 .Sh STANDARDS
179 The
180 .Fn tmpfile
181 and
182 .Fn tmpnam
183 functions
184 conform to
185 .St -ansiC .
186 All described functions also conform to
187 .St -p1003.1-2001 ,
188 albeit the
189 .Fn tempnam
190 and
191 .Fn tmpnam
192 functions have been marked as obsolete in the
193 .St -p1003.1-2008
194 revision.
195 .Sh BUGS
196 These interfaces are provided for
197 .At V
198 and
199 .Tn ANSI
200 compatibility only.
201 The
202 .Xr mkstemp 3
203 interface is strongly preferred.
204 .Sh SECURITY CONSIDERATIONS
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: the program is typically written to call
211 .Fn tmpnam ,
212 .Fn tempnam ,
213 or
214 .Xr mktemp 3 .
215 Subsequently, the program calls
216 .Xr open 2
217 or
218 .Xr fopen 3
219 and erroneously opens a file (or symbolic link, or fifo or other
220 device) that the attacker has placed in the expected file location.
221 Hence
222 .Xr mkstemp 3
223 is recommended, since it atomically creates the file.
224 .Pp
225 Second, most historic implementations provide only a limited number
226 of possible temporary file names (usually 26) before file names will
227 start being recycled.
228 Third, the
229 .At V
230 implementations of these functions (and of
231 .Xr mktemp 3 )
232 use the
233 .Xr access 2
234 system call to determine whether or not the temporary file may be created.
235 This has obvious ramifications for setuid or setgid programs, complicating
236 the portable use of these interfaces in such programs.
237 Finally, there is no specification of the permissions with which the
238 temporary files are created.
239 .Pp
240 This implementation of
241 .Fn tmpfile
242 does not have these flaws,
243 and that of
244 .Fn tmpnam
245 and
246 .Fn tempnam
247 only have the first limitation, but portable software
248 cannot depend on that.
249 In particular, the
250 .Fn tmpfile
251 interface should not be used in software expected to be used on other systems
252 if there is any possibility that the user does not wish the temporary file to
253 be publicly readable and writable.
254 .Pp
255 A link-time warning will be issued if
256 .Fn tmpnam
257 or
258 .Fn tempnam
259 is used, and advises the use of
260 .Fn mkstemp
261 instead.