| blob | 076348a7bf74399429009bf4f416f483ca7fff5a |
1 .\" $NetBSD: mktemp.3,v 1.30 2014/06/19 09:30:33 wiz 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 June 18, 2014
33 .Dt MKTEMP 3
34 .Os
35 .Sh NAME
36 .Nm mktemp ,
37 .Nm mkstemp ,
38 .Nm mkstemps ,
39 .Nm mkostemp ,
40 .Nm mkostemps ,
41 .Nm mkdtemp
42 .Nd make unique temporary file or directory name
43 .Sh LIBRARY
44 .Lb libc
45 .Sh SYNOPSIS
46 .In stdlib.h
47 .Ft char *
48 .Fn mktemp "char *template"
49 .Ft int
50 .Fn mkstemp "char *template"
51 .Ft int
52 .Fn mkostemp "char *template" "int oflags"
53 .Ft int
54 .Fn mkostemps "char *template" "int suffixlen" "int oflags"
55 .Ft char *
56 .Fn mkdtemp "char *template"
57 .In unistd.h
58 .Ft int
59 .Fn mkstemps "char *template" "int suffixlen"
60 .Sh DESCRIPTION
61 The
62 .Fn mktemp
63 function
64 takes the given file name template and overwrites a portion of it
65 to create a file name.
66 This file name is unique and suitable for use
67 by the application.
68 The template may be any file name with some number of
69 .So Li X
70 .Sc Ns s
71 appended
72 to it, for example
73 .Pa /tmp/temp.XXXXXX .
74 The trailing
75 .So Li X
76 .Sc Ns s
77 are replaced with the current process number and/or a
78 unique letter combination.
79 The number of unique file names
80 .Fn mktemp
81 can return depends on the number of
82 .So Li X
83 .Sc Ns s
84 provided.
85 Although the
86 .Nx
87 implementation of the functions will accept any number of trailing
88 .So Li X
89 .Sc Ns s ,
90 for portability reasons one should use only six.
91 Using six
92 .So Li X
93 .Sc Ns s
94 will result in
95 .Fn mktemp
96 testing roughly 26 ** 6 (308915776) combinations.
97 .Pp
98 The
99 .Fn mkstemp
100 function
101 makes the same replacement to the template and creates the template file,
102 mode 0600, returning a file descriptor opened for reading and writing.
103 This avoids the race between testing for a file's existence and opening it
104 for use.
105 The
106 .Fn mkostemp
107 function
108 is like
109 .Fn mkstemp
110 but allows specifying additional
111 .Xr open 2
112 flags (defined in
113 .In fcntl.h ) .
114 The permitted flags are
115 .Dv O_APPEND ,
116 .Dv O_DIRECT ,
117 .Dv O_SHLOCK ,
118 .Dv O_EXLOCK ,
119 .Dv O_SYNC
120 and
121 .Dv O_CLOEXEC .
122 .Pp
123 The
124 .Fn mkstemps
125 and
126 .Fn mkostemps
127 functions act the same as
128 .Fn mkstemp
129 and
130 .Fn mkostemp
131 respectively,
132 except they permit a suffix to exist in the template.
133 The template should be of the form
134 .Pa /tmp/tmpXXXXXXsuffix .
135 The
136 .Fn mkstemps
137 and
138 .Fn mkostemps
139 function
140 are told the length of the suffix string.
141 .Pp
142 The
143 .Fn mkdtemp
144 function
145 is similar to
146 .Fn mkstemp ,
147 but it creates a mode 0700 directory instead and returns the path.
148 .Pp
149 Please note that the permissions of the file or directory being created are
150 subject to the restrictions imposed by the
151 .Xr umask 2
152 system call.
153 It may thus happen that the created file is unreadable and/or unwritable.
154 .Sh RETURN VALUES
155 The
156 .Fn mktemp
157 and
158 .Fn mkdtemp
159 functions
160 return a pointer to the template on success and
161 .Dv NULL
162 on failure.
163 The
164 .Fn mkstemp ,
165 .Fn mkostemp ,
166 .Fn mkstemps
167 and
168 .Fn mkostemps
169 functions
170 returns \-1 if no suitable file could be created.
171 If either call fails an error code is placed in the global variable
172 .Va errno .
173 .Sh EXAMPLES
174 Quite often a programmer will want to replace a use of
175 .Fn mktemp
176 with
177 .Fn mkstemp ,
178 usually to avoid the problems described above.
179 Doing this correctly requires a good understanding of the code in question.
180 .Pp
181 For instance, code of this form:
182 .Bd -literal -offset indent
183 char sfn[15] = "";
184 FILE *sfp;
186 strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn);
187 if (mktemp(sfn) == NULL || (sfp = fopen(sfn, "w+")) == NULL) {
188 fprintf(stderr, "%s: %s\en", sfn, strerror(errno));
189 return (NULL);
190 }
191 return (sfp);
192 .Ed
193 .Pp
194 should be rewritten like this:
195 .Bd -literal -offset indent
196 char sfn[15] = "";
197 FILE *sfp;
198 int fd = -1;
200 strlcpy(sfn, "/tmp/ed.XXXXXX", sizeof sfn);
201 if ((fd = mkstemp(sfn)) == -1 ||
202 (sfp = fdopen(fd, "w+")) == NULL) {
203 if (fd != -1) {
204 unlink(sfn);
205 close(fd);
206 }
207 fprintf(stderr, "%s: %s\en", sfn, strerror(errno));
208 return (NULL);
209 }
210 return (sfp);
211 .Ed
212 .Pp
213 Often one will find code which uses
214 .Fn mktemp
215 very early on, perhaps to globally initialize the template nicely, but the
216 code which calls
217 .Xr open 2
218 or
219 .Xr fopen 3
220 on that filename will occur much later.
221 (In almost all cases, the use of
222 .Xr fopen 3
223 will mean that the flags
224 .Dv O_CREAT
225 |
226 .Dv O_EXCL
227 are not given to
228 .Xr open 2 ,
229 and thus a symbolic link race becomes possible, hence making
230 necessary the use of
231 .Xr fdopen 3
232 as seen above).
233 Furthermore, one must be careful about code which opens, closes, and then
234 re-opens the file in question.
235 Finally, one must ensure that upon error the temporary file is
236 removed correctly.
237 .Pp
238 There are also cases where modifying the code to use
239 .Fn mktemp ,
240 in concert with
241 .Xr open 2
242 using the flags
243 .Dv O_CREAT
244 |
245 .Dv O_EXCL ,
246 is better, as long as the code retries a new template if
247 .Xr open 2
248 fails with an
249 .Va errno
250 of
251 .Er EEXIST .
252 .Sh ERRORS
253 The
254 .Fn mkstemp ,
255 .Fn mkostemp ,
256 .Fn mkstemps ,
257 .Fn mkostemps
258 and
259 .Fn mkdtemp
260 functions
261 may set
262 .Va errno
263 to one of the following values:
264 .Bl -tag -width Er
265 .It Bq Er ENOTDIR
266 The pathname portion of the template is not an existing directory.
267 .El
268 .Pp
269 The
270 .Fn mktemp ,
271 .Fn mkstemp
272 and
273 .Fn mkdtemp
274 functions
275 may also set
276 .Va errno
277 to any value specified by the
278 .Xr stat 2
279 function.
280 .Pp
281 The
282 .Fn mkstemp
283 function
284 may also set
285 .Va errno
286 to any value specified by the
287 .Xr open 2
288 function.
289 .Pp
290 The
291 .Fn mkdtemp
292 function
293 may also set
294 .Va errno
295 to any value specified by the
296 .Xr mkdir 2
297 function.
298 .Sh SEE ALSO
299 .Xr chmod 2 ,
300 .Xr getpid 2 ,
301 .Xr open 2 ,
302 .Xr stat 2 ,
303 .Xr umask 2
304 .Sh STANDARDS
305 The
306 .Fn mktemp
307 conforms to
308 .St -p1003.1-2001 .
309 It was however removed from the specification in the
310 .St -p1003.1-2008
311 revision.
312 The
313 .Fn mkstemp
314 and
315 .Fn mkdtemp
316 functions conform to
317 .St -p1003.1-2004
318 and
319 .St -p1003.1-2008 ,
320 respectively.
321 .Sh HISTORY
322 A
323 .Fn mktemp
324 function appeared in
325 .At v7 .
326 .Pp
327 The
328 .Fn mkstemp
329 function appeared in
330 .Bx 4.4 .
331 .Pp
332 The
333 .Fn mkdtemp
334 function appeared in
335 .Nx 1.4 .
336 The
337 .Fn mkstemps
338 function first appeared in
339 .Ox 2.4 ,
340 and later in
341 .Fx 3.4
342 and
343 .Nx 7.0 .
344 The
345 .Fn mkostemp
346 and
347 .Fn mkostemps
348 functions appeared in
349 .Fx 10.0
350 and
351 .Nx 7.0 .
352 .Sh BUGS
353 For
354 .Fn mktemp
355 there is an obvious race between file name selection and file
356 creation and deletion: the program is typically written to call
357 .Xr tmpnam 3 ,
358 .Xr tempnam 3 ,
359 or
360 .Fn mktemp .
361 Subsequently, the program calls
362 .Xr open 2
363 or
364 .Xr fopen 3
365 and erroneously opens a file (or symbolic link, fifo or other
366 device) that the attacker has created in the expected file location.
367 Hence
368 .Fn mkstemp
369 is recommended, since it atomically creates the file.
370 An attacker can guess the filenames produced by
371 .Fn mktemp .
372 Whenever it is possible,
373 .Fn mkstemp
374 or
375 .Fn mkdtemp
376 should be used instead.
377 .Pp
378 For this reason,
379 .Xr ld 1
380 will output a warning message whenever it links code that uses
381 .Fn mktemp .
382 .Pp
383 The
384 .Fn mkdtemp
385 function is nonstandard and should not be used if portability is required.
386 .Sh SECURITY CONSIDERATIONS
387 The use of
388 .Fn mktemp
389 should generally be avoided, as a hostile process can exploit a race
390 condition in the time between the generation of a temporary filename by
391 .Fn mktemp
392 and the invoker's use of the temporary name.
393 A link-time warning will be issued advising the use of
394 .Fn mkstemp
395 or
396 .Fn mkdtemp
397 instead.