xref: /freebsd/lib/libc/stdio/mktemp.3 (revision f4b37ed0f8b307b1f3f0f630ca725d68f1dff30d)
1.\" Copyright (c) 1989, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 4. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)mktemp.3	8.1 (Berkeley) 6/4/93
29.\" $FreeBSD$
30.\"
31.Dd August 8, 2013
32.Dt MKTEMP 3
33.Os
34.Sh NAME
35.Nm mktemp
36.Nd make temporary file name (unique)
37.Sh LIBRARY
38.Lb libc
39.Sh SYNOPSIS
40.In stdlib.h
41.Ft char *
42.Fn mktemp "char *template"
43.Ft int
44.Fn mkstemp "char *template"
45.Ft int
46.Fn mkostemp "char *template" "int oflags"
47.Ft int
48.Fn mkostemps "char *template" "int suffixlen" "int oflags"
49.Ft char *
50.Fn mkdtemp "char *template"
51.In unistd.h
52.Ft int
53.Fn mkstemps "char *template" "int suffixlen"
54.Sh DESCRIPTION
55The
56.Fn mktemp
57function
58takes the given file name template and overwrites a portion of it
59to create a file name.
60This file name is guaranteed not to exist at the time of function invocation
61and is suitable for use
62by the application.
63The template may be any file name with some number of
64.Ql X Ns s
65appended
66to it, for example
67.Pa /tmp/temp.XXXXXX .
68The trailing
69.Ql X Ns s
70are replaced with a
71unique alphanumeric combination.
72The number of unique file names
73.Fn mktemp
74can return depends on the number of
75.Ql X Ns s
76provided; six
77.Ql X Ns s
78will
79result in
80.Fn mktemp
81selecting one of 56800235584 (62 ** 6) possible temporary file names.
82.Pp
83The
84.Fn mkstemp
85function
86makes the same replacement to the template and creates the template file,
87mode 0600, returning a file descriptor opened for reading and writing.
88This avoids the race between testing for a file's existence and opening it
89for use.
90.Pp
91The
92.Fn mkostemp
93function
94is like
95.Fn mkstemp
96but allows specifying additional
97.Xr open 2
98flags (defined in
99.In fcntl.h ) .
100The permitted flags are
101.Dv O_APPEND ,
102.Dv O_DIRECT ,
103.Dv O_SHLOCK ,
104.Dv O_EXLOCK ,
105.Dv O_SYNC
106and
107.Dv O_CLOEXEC .
108.Pp
109The
110.Fn mkstemps
111and
112.Fn mkostemps
113functions act the same as
114.Fn mkstemp
115and
116.Fn mkostemp
117respectively,
118except they permit a suffix to exist in the template.
119The template should be of the form
120.Pa /tmp/tmpXXXXXXsuffix .
121The
122.Fn mkstemps
123and
124.Fn mkostemps
125function
126are told the length of the suffix string.
127.Pp
128The
129.Fn mkdtemp
130function makes the same replacement to the template as in
131.Fn mktemp
132and creates the template directory, mode 0700.
133.Sh RETURN VALUES
134The
135.Fn mktemp
136and
137.Fn mkdtemp
138functions return a pointer to the template on success and
139.Dv NULL
140on failure.
141The
142.Fn mkstemp ,
143.Fn mkostemp
144.Fn mkstemps
145and
146.Fn mkostemps
147functions
148return \-1 if no suitable file could be created.
149If either call fails an error code is placed in the global variable
150.Va errno .
151.Sh ERRORS
152The
153.Fn mkstemp ,
154.Fn mkostemp ,
155.Fn mkstemps ,
156.Fn mkostemps
157and
158.Fn mkdtemp
159functions
160may set
161.Va errno
162to one of the following values:
163.Bl -tag -width Er
164.It Bq Er ENOTDIR
165The pathname portion of the template is not an existing directory.
166.El
167.Pp
168The
169.Fn mkostemp
170and
171.Fn mkostemps
172functions
173may also set
174.Va errno
175to the following value:
176.Bl -tag -width Er
177.It Bq Er EINVAL
178The
179.Fa oflags
180argument is invalid.
181.El
182.Pp
183The
184.Fn mkstemp ,
185.Fn mkostemp ,
186.Fn mkstemps ,
187.Fn mkostemps
188and
189.Fn mkdtemp
190functions
191may also set
192.Va errno
193to any value specified by the
194.Xr stat 2
195function.
196.Pp
197The
198.Fn mkstemp ,
199.Fn mkostemp ,
200.Fn mkstemps
201and
202.Fn mkostemps
203functions
204may also set
205.Va errno
206to any value specified by the
207.Xr open 2
208function.
209.Pp
210The
211.Fn mkdtemp
212function
213may also set
214.Va errno
215to any value specified by the
216.Xr mkdir 2
217function.
218.Sh NOTES
219A common problem that results in a core dump is that the programmer
220passes in a read-only string to
221.Fn mktemp ,
222.Fn mkstemp ,
223.Fn mkstemps
224or
225.Fn mkdtemp .
226This is common with programs that were developed before
227.St -isoC
228compilers were common.
229For example, calling
230.Fn mkstemp
231with an argument of
232.Qq /tmp/tempfile.XXXXXX
233will result in a core dump due to
234.Fn mkstemp
235attempting to modify the string constant that was given.
236.Pp
237The
238.Fn mkdtemp ,
239.Fn mkstemp
240and
241.Fn mktemp
242function prototypes are also available from
243.In unistd.h .
244.Sh SEE ALSO
245.Xr chmod 2 ,
246.Xr getpid 2 ,
247.Xr mkdir 2 ,
248.Xr open 2 ,
249.Xr stat 2
250.Sh STANDARDS
251The
252.Fn mkstemp
253and
254.Fn mkdtemp
255functions are expected to conform to
256.St -p1003.1-2008 .
257The
258.Fn mktemp
259function is expected to conform to
260.St -p1003.1-2001
261and is not specified by
262.St -p1003.1-2008 .
263The
264.Fn mkostemp ,
265.Fn mkstemps
266and
267.Fn mkostemps
268functions do not conform to any standard.
269.Sh HISTORY
270A
271.Fn mktemp
272function appeared in
273.At v7 .
274The
275.Fn mkstemp
276function appeared in
277.Bx 4.4 .
278The
279.Fn mkdtemp
280function first appeared in
281.Ox 2.2 ,
282and later in
283.Fx 3.2 .
284The
285.Fn mkstemps
286function first appeared in
287.Ox 2.4 ,
288and later in
289.Fx 3.4 .
290The
291.Fn mkostemp
292and
293.Fn mkostemps
294functions appeared in
295.Fx 10.0 .
296.Sh BUGS
297This family of functions produces filenames which can be guessed,
298though the risk is minimized when large numbers of
299.Ql X Ns s
300are used to
301increase the number of possible temporary filenames.
302This makes the race in
303.Fn mktemp ,
304between testing for a file's existence (in the
305.Fn mktemp
306function call)
307and opening it for use
308(later in the user application)
309particularly dangerous from a security perspective.
310Whenever it is possible,
311.Fn mkstemp
312or
313.Fn mkostemp
314should be used instead, since it does not have the race condition.
315If
316.Fn mkstemp
317cannot be used, the filename created by
318.Fn mktemp
319should be created using the
320.Dv O_EXCL
321flag to
322.Xr open 2
323and the return status of the call should be tested for failure.
324This will ensure that the program does not continue blindly
325in the event that an attacker has already created the file
326with the intention of manipulating or reading its contents.
327