| blob | 37718ddbc8255c28037638a786d60216ec8694a6 |
1 .\" $NetBSD: mktemp.3,v 1.28 2010/05/14 03:22:49 joerg Exp $
2 .\"
3 .\" Copyright (c) 1989, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)mktemp.3 8.1 (Berkeley) 6/4/93
31 .\"
32 .Dd April 29, 2010
33 .Dt MKTEMP 3
34 .Os
35 .Sh NAME
36 .Nm mktemp ,
37 .Nm mkstemp ,
38 .Nm mkdtemp
39 .Nd make unique temporary file or directory name
40 .Sh LIBRARY
41 .Lb libc
42 .Sh SYNOPSIS
43 .In stdlib.h
44 .Ft char *
45 .Fn mktemp "char *template"
46 .Ft int
47 .Fn mkstemp "char *template"
48 .Ft char *
49 .Fn mkdtemp "char *template"
50 .Sh DESCRIPTION
51 The
52 .Fn mktemp
53 function
54 takes the given file name template and overwrites a portion of it
55 to create a file name.
56 This file name is unique and suitable for use
57 by the application.
58 The template may be any file name with some number of
59 .So Li X
60 .Sc Ns s
61 appended
62 to it, for example
63 .Pa /tmp/temp.XXXXXX .
64 The trailing
65 .So Li X
66 .Sc Ns s
67 are replaced with the current process number and/or a
68 unique letter combination.
69 The number of unique file names
70 .Fn mktemp
71 can return depends on the number of
72 .So Li X
73 .Sc Ns s
74 provided.
75 Although the
76 .Nx
77 implementation of the functions will accept any number of trailing
78 .So Li X
79 .Sc Ns s ,
80 for portability reasons one should use only six.
81 Using six
82 .So Li X
83 .Sc Ns s
84 will result in
85 .Fn mktemp
86 testing roughly 26 ** 6 (308915776) combinations.
87 .Pp
88 The
89 .Fn mkstemp
90 function
91 makes the same replacement to the template and creates the template file,
92 mode 0600, returning a file descriptor opened for reading and writing.
93 This avoids the race between testing for a file's existence and opening it
94 for use.
95 .Pp
96 The
97 .Fn mkdtemp
98 function
99 is similar to
100 .Fn mkstemp ,
101 but it creates a mode 0700 directory instead and returns the path.
102 .Pp
103 Please note that the permissions of the file or directory being created are
104 subject to the restrictions imposed by the
105 .Xr umask 2
106 system call.
107 It may thus happen that the created file is unreadable and/or unwritable.
108 .Sh RETURN VALUES
109 The
110 .Fn mktemp
111 and
112 .Fn mkdtemp
113 functions
114 return a pointer to the template on success and
115 .Dv NULL
116 on failure.
117 The
118 .Fn mkstemp
119 function
120 returns \-1 if no suitable file could be created.
121 If either call fails an error code is placed in the global variable
122 .Va errno .
123 .Sh EXAMPLES
124 Quite often a programmer will want to replace a use of
125 .Fn mktemp
126 with
127 .Fn mkstemp ,
128 usually to avoid the problems described above.
129 Doing this correctly requires a good understanding of the code in question.
130 .Pp
131 For instance, code of this form:
132 .Bd -literal -offset indent
133 char sfn[15] = "";
134 FILE *sfp;
136 strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn);
137 if (mktemp(sfn) == NULL || (sfp = fopen(sfn, "w+")) == NULL) {
138 fprintf(stderr, "%s: %s\en", sfn, strerror(errno));
139 return (NULL);
140 }
141 return (sfp);
142 .Ed
143 .Pp
144 should be rewritten like this:
145 .Bd -literal -offset indent
146 char sfn[15] = "";
147 FILE *sfp;
148 int fd = -1;
150 strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn);
151 if ((fd = mkstemp(sfn)) == -1 ||
152 (sfp = fdopen(fd, "w+")) == NULL) {
153 if (fd != -1) {
154 unlink(sfn);
155 close(fd);
156 }
157 fprintf(stderr, "%s: %s\en", sfn, strerror(errno));
158 return (NULL);
159 }
160 return (sfp);
161 .Ed
162 .Pp
163 Often one will find code which uses
164 .Fn mktemp
165 very early on, perhaps to globally initialize the template nicely, but the
166 code which calls
167 .Xr open 2
168 or
169 .Xr fopen 3
170 on that filename will occur much later.
171 (In almost all cases, the use of
172 .Xr fopen 3
173 will mean that the flags
174 .Dv O_CREAT
175 |
176 .Dv O_EXCL
177 are not given to
178 .Xr open 2 ,
179 and thus a symbolic link race becomes possible, hence making
180 necessary the use of
181 .Xr fdopen 3
182 as seen above).
183 Furthermore, one must be careful about code which opens, closes, and then
184 re-opens the file in question.
185 Finally, one must ensure that upon error the temporary file is
186 removed correctly.
187 .Pp
188 There are also cases where modifying the code to use
189 .Fn mktemp ,
190 in concert with
191 .Xr open 2
192 using the flags
193 .Dv O_CREAT
194 |
195 .Dv O_EXCL ,
196 is better, as long as the code retries a new template if
197 .Xr open 2
198 fails with an
199 .Va errno
200 of
201 .Er EEXIST .
202 .Sh ERRORS
203 The
204 .Fn mktemp ,
205 .Fn mkstemp
206 and
207 .Fn mkdtemp
208 functions
209 may set
210 .Va errno
211 to one of the following values:
212 .Bl -tag -width Er
213 .It Bq Er ENOTDIR
214 The pathname portion of the template is not an existing directory.
215 .El
216 .Pp
217 The
218 .Fn mktemp ,
219 .Fn mkstemp
220 and
221 .Fn mkdtemp
222 functions
223 may also set
224 .Va errno
225 to any value specified by the
226 .Xr stat 2
227 function.
228 .Pp
229 The
230 .Fn mkstemp
231 function
232 may also set
233 .Va errno
234 to any value specified by the
235 .Xr open 2
236 function.
237 .Pp
238 The
239 .Fn mkdtemp
240 function
241 may also set
242 .Va errno
243 to any value specified by the
244 .Xr mkdir 2
245 function.
246 .Sh SEE ALSO
247 .Xr chmod 2 ,
248 .Xr getpid 2 ,
249 .Xr open 2 ,
250 .Xr stat 2 ,
251 .Xr umask 2
252 .Sh STANDARDS
253 The
254 .Fn mktemp
255 conforms to
256 .St -p1003.1-2001 .
257 It was however removed from the specification in the
258 .St -p1003.1-2008
259 revision.
260 The
261 .Fn mkstemp
262 and
263 .Fn mkdtemp
264 functions conform to
265 .St -p1003.1-2004
266 and
267 .St -p1003.1-2008 ,
268 respectively.
269 .Sh HISTORY
270 A
271 .Fn mktemp
272 function appeared in
273 .At v7 .
274 .Pp
275 The
276 .Fn mkstemp
277 function appeared in
278 .Bx 4.4 .
279 .Pp
280 The
281 .Fn mkdtemp
282 function appeared in
283 .Nx 1.4 .
284 .Sh BUGS
285 For
286 .Fn mktemp
287 there is an obvious race between file name selection and file
288 creation and deletion: the program is typically written to call
289 .Xr tmpnam 3 ,
290 .Xr tempnam 3 ,
291 or
292 .Fn mktemp .
293 Subsequently, the program calls
294 .Xr open 2
295 or
296 .Xr fopen 3
297 and erroneously opens a file (or symbolic link, fifo or other
298 device) that the attacker has created in the expected file location.
299 Hence
300 .Fn mkstemp
301 is recommended, since it atomically creates the file.
302 An attacker can guess the filenames produced by
303 .Fn mktemp .
304 Whenever it is possible,
305 .Fn mkstemp
306 or
307 .Fn mkdtemp
308 should be used instead.
309 .Pp
310 For this reason,
311 .Xr ld 1
312 will output a warning message whenever it links code that uses
313 .Fn mktemp .
314 .Pp
315 The
316 .Fn mkdtemp
317 function is nonstandard and should not be used if portability is required.
318 .Sh SECURITY CONSIDERATIONS
319 The use of
320 .Fn mktemp
321 should generally be avoided, as a hostile process can exploit a race
322 condition in the time between the generation of a temporary filename by
323 .Fn mktemp
324 and the invoker's use of the temporary name.
325 A link-time warning will be issued advising the use of
326 .Fn mkstemp
327 or
328 .Fn mkdtemp
329 instead.