xref: /freebsd/lib/libc/stdio/mktemp.3 (revision ee12faa062c04a49bf6fe4e6867bad8606e2413f)
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.\" 3. 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.\"
30.Dd July 29, 2019
31.Dt MKTEMP 3
32.Os
33.Sh NAME
34.Nm mktemp
35.Nd make temporary file name (unique)
36.Sh LIBRARY
37.Lb libc
38.Sh SYNOPSIS
39.In stdlib.h
40.Ft char *
41.Fn mktemp "char *template"
42.Ft int
43.Fn mkstemp "char *template"
44.Ft int
45.Fn mkostemp "char *template" "int oflags"
46.Ft int
47.Fn mkostemps "char *template" "int suffixlen" "int oflags"
48.Ft int
49.Fn mkostempsat "int dfd" "char *template" "int suffixlen" "int oflags"
50.Ft char *
51.Fn mkdtemp "char *template"
52.In unistd.h
53.Ft int
54.Fn mkstemps "char *template" "int suffixlen"
55.Sh DESCRIPTION
56The
57.Fn mktemp
58function
59takes the given file name template and overwrites a portion of it
60to create a file name.
61This file name is guaranteed not to exist at the time of function invocation
62and is suitable for use
63by the application.
64The template may be any file name with some number of
65.Ql X Ns s
66appended
67to it, for example
68.Pa /tmp/temp.XXXXXX .
69The trailing
70.Ql X Ns s
71are replaced with a
72unique alphanumeric combination.
73The number of unique file names
74.Fn mktemp
75can return depends on the number of
76.Ql X Ns s
77provided; six
78.Ql X Ns s
79will
80result in
81.Fn mktemp
82selecting one of 56800235584 (62 ** 6) possible temporary file names.
83.Pp
84The
85.Fn mkstemp
86function
87makes the same replacement to the template and creates the template file,
88mode 0600, returning a file descriptor opened for reading and writing.
89This avoids the race between testing for a file's existence and opening it
90for use.
91.Pp
92The
93.Fn mkostemp
94function
95is like
96.Fn mkstemp
97but allows specifying additional
98.Xr open 2
99flags (defined in
100.In fcntl.h ) .
101The permitted flags are
102.Dv O_APPEND ,
103.Dv O_DIRECT ,
104.Dv O_SHLOCK ,
105.Dv O_EXLOCK ,
106.Dv O_SYNC
107and
108.Dv O_CLOEXEC .
109.Pp
110The
111.Fn mkstemps
112and
113.Fn mkostemps
114functions act the same as
115.Fn mkstemp
116and
117.Fn mkostemp
118respectively,
119except they permit a suffix to exist in the template.
120The template should be of the form
121.Pa /tmp/tmpXXXXXXsuffix .
122The
123.Fn mkstemps
124and
125.Fn mkostemps
126function
127are told the length of the suffix string.
128.Pp
129The
130.Fn mkostempsat
131function acts the same as
132.Fn mkostemps
133but takes an additional directory descriptor as a parameter.
134The temporary file is created relative to the corresponding
135directory, or to the current working directory if the special
136value
137.Dv AT_FDCWD
138is specified.
139If the template path is an absolute path, the
140.Fa dfd
141parameter is ignored and the behavior is identical to
142.Fn mkostemps .
143.Pp
144The
145.Fn mkdtemp
146function makes the same replacement to the template as in
147.Fn mktemp
148and creates the template directory, mode 0700.
149.Sh RETURN VALUES
150The
151.Fn mktemp
152and
153.Fn mkdtemp
154functions return a pointer to the template on success and
155.Dv NULL
156on failure.
157The
158.Fn mkstemp ,
159.Fn mkostemp
160.Fn mkstemps
161and
162.Fn mkostemps
163functions
164return \-1 if no suitable file could be created.
165If either call fails an error code is placed in the global variable
166.Va errno .
167.Sh ERRORS
168The
169.Fn mkstemp ,
170.Fn mkostemp ,
171.Fn mkstemps ,
172.Fn mkostemps
173and
174.Fn mkdtemp
175functions
176may set
177.Va errno
178to one of the following values:
179.Bl -tag -width Er
180.It Bq Er ENOTDIR
181The pathname portion of the template is not an existing directory.
182.El
183.Pp
184The
185.Fn mkostemp
186and
187.Fn mkostemps
188functions
189may also set
190.Va errno
191to the following value:
192.Bl -tag -width Er
193.It Bq Er EINVAL
194The
195.Fa oflags
196argument is invalid.
197.El
198.Pp
199The
200.Fn mkstemp ,
201.Fn mkostemp ,
202.Fn mkstemps ,
203.Fn mkostemps
204and
205.Fn mkdtemp
206functions
207may also set
208.Va errno
209to any value specified by the
210.Xr stat 2
211function.
212.Pp
213The
214.Fn mkstemp ,
215.Fn mkostemp ,
216.Fn mkstemps
217and
218.Fn mkostemps
219functions
220may also set
221.Va errno
222to any value specified by the
223.Xr open 2
224function.
225.Pp
226The
227.Fn mkdtemp
228function
229may also set
230.Va errno
231to any value specified by the
232.Xr mkdir 2
233function.
234.Sh NOTES
235A common problem that results in a core dump is that the programmer
236passes in a read-only string to
237.Fn mktemp ,
238.Fn mkstemp ,
239.Fn mkstemps
240or
241.Fn mkdtemp .
242This is common with programs that were developed before
243.St -isoC
244compilers were common.
245For example, calling
246.Fn mkstemp
247with an argument of
248.Qq /tmp/tempfile.XXXXXX
249will result in a core dump due to
250.Fn mkstemp
251attempting to modify the string constant that was given.
252.Pp
253The
254.Fn mkdtemp ,
255.Fn mkstemp
256and
257.Fn mktemp
258function prototypes are also available from
259.In unistd.h .
260.Sh SEE ALSO
261.Xr chmod 2 ,
262.Xr getpid 2 ,
263.Xr mkdir 2 ,
264.Xr open 2 ,
265.Xr stat 2
266.Sh STANDARDS
267The
268.Fn mkstemp
269and
270.Fn mkdtemp
271functions are expected to conform to
272.St -p1003.1-2008 .
273The
274.Fn mktemp
275function is expected to conform to
276.St -p1003.1-2001
277and is not specified by
278.St -p1003.1-2008 .
279The
280.Fn mkostemp ,
281.Fn mkstemps ,
282.Fn mkostemps
283and
284.Fn mkostempsat
285functions do not conform to any standard.
286.Sh HISTORY
287A
288.Fn mktemp
289function appeared in
290.At v7 .
291The
292.Fn mkstemp
293function appeared in
294.Bx 4.4 .
295The
296.Fn mkdtemp
297function first appeared in
298.Ox 2.2 ,
299and later in
300.Fx 3.2 .
301The
302.Fn mkstemps
303function first appeared in
304.Ox 2.4 ,
305and later in
306.Fx 3.4 .
307The
308.Fn mkostemp
309and
310.Fn mkostemps
311functions appeared in
312.Fx 10.0 .
313The
314.Fn mkostempsat
315function appeared in
316.Fx 13.0 .
317.Sh BUGS
318This family of functions produces filenames which can be guessed,
319though the risk is minimized when large numbers of
320.Ql X Ns s
321are used to
322increase the number of possible temporary filenames.
323This makes the race in
324.Fn mktemp ,
325between testing for a file's existence (in the
326.Fn mktemp
327function call)
328and opening it for use
329(later in the user application)
330particularly dangerous from a security perspective.
331Whenever it is possible,
332.Fn mkstemp ,
333.Fn mkostemp
334or
335.Fn mkostempsat
336should be used instead, since they do not have the race condition.
337If
338.Fn mkstemp
339cannot be used, the filename created by
340.Fn mktemp
341should be created using the
342.Dv O_EXCL
343flag to
344.Xr open 2
345and the return status of the call should be tested for failure.
346This will ensure that the program does not continue blindly
347in the event that an attacker has already created the file
348with the intention of manipulating or reading its contents.
349