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.
--- 12 unchanged lines hidden (view full) ---
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: head/lib/libc/stdio/mktemp.3 252838 2013-07-05 20:24:50Z jilles $
30.\"
31.Dd July 5, 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 char *
46.Fn mkdtemp "char *template"
47.In unistd.h
48.Ft int
49.Fn mkstemps "char *template" "int suffixlen"
50.Sh DESCRIPTION
51The
52.Fn mktemp
--- 27 unchanged lines hidden (view full) ---
80.Fn mkstemp
81function
82makes the same replacement to the template and creates the template file,
83mode 0600, returning a file descriptor opened for reading and writing.
84This avoids the race between testing for a file's existence and opening it
85for use.
86.Pp
87The
88.Fn mkstemps
89function acts the same as
90.Fn mkstemp ,
91except it permits a suffix to exist in the template.
92The template should be of the form
93.Pa /tmp/tmpXXXXXXsuffix .
94The
95.Fn mkstemps
96function
97is told the length of the suffix string.
98.Pp
99The
100.Fn mkdtemp
101function makes the same replacement to the template as in
102.Fn mktemp
103and creates the template directory, mode 0700.
104.Sh RETURN VALUES
105The
106.Fn mktemp
107and
108.Fn mkdtemp
109functions return a pointer to the template on success and
110.Dv NULL
111on failure.
112The
113.Fn mkstemp
114and
115.Fn mkstemps
116functions
117return \-1 if no suitable file could be created.
118If either call fails an error code is placed in the global variable
119.Va errno .
120.Sh ERRORS
121The
122.Fn mkstemp ,
123.Fn mkstemps
124and
125.Fn mkdtemp
126functions
127may set
128.Va errno
129to one of the following values:
130.Bl -tag -width Er
131.It Bq Er ENOTDIR
132The pathname portion of the template is not an existing directory.
133.El
134.Pp
135The
136.Fn mkstemp ,
137.Fn mkstemps
138and
139.Fn mkdtemp
140functions
141may also set
142.Va errno
143to any value specified by the
144.Xr stat 2
145function.
146.Pp
147The
148.Fn mkstemp
149and
150.Fn mkstemps
151functions
152may also set
153.Va errno
154to any value specified by the
155.Xr open 2
156function.
157.Pp
158The
--- 45 unchanged lines hidden (view full) ---
204.St -p1003.1-2008 .
205The
206.Fn mktemp
207function is expected to conform to
208.St -p1003.1-2001
209and is not specified by
210.St -p1003.1-2008 .
211The
212.Fn mkstemps
213function does not conform to any standard.
214.Sh HISTORY
215A
216.Fn mktemp
217function appeared in
218.At v7 .
219The
220.Fn mkstemp
221function appeared in
--- 5 unchanged lines hidden (view full) ---
227and later in
228.Fx 3.2 .
229The
230.Fn mkstemps
231function first appeared in
232.Ox 2.4 ,
233and later in
234.Fx 3.4 .
235.Sh BUGS
236This family of functions produces filenames which can be guessed,
237though the risk is minimized when large numbers of
238.Ql X Ns s
239are used to
240increase the number of possible temporary filenames.
241This makes the race in
242.Fn mktemp ,
243between testing for a file's existence (in the
244.Fn mktemp
245function call)
246and opening it for use
247(later in the user application)
248particularly dangerous from a security perspective.
249Whenever it is possible,
250.Fn mkstemp
251should be used instead, since it does not have the race condition.
252If
253.Fn mkstemp
254cannot be used, the filename created by
255.Fn mktemp
256should be created using the
257.Dv O_EXCL
258flag to
259.Xr open 2
260and the return status of the call should be tested for failure.
261This will ensure that the program does not continue blindly
262in the event that an attacker has already created the file
263with the intention of manipulating or reading its contents.
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.
--- 12 unchanged lines hidden (view full) ---
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: head/lib/libc/stdio/mktemp.3 252838 2013-07-05 20:24:50Z jilles $
30.\"
31.Dd July 5, 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 char *
46.Fn mkdtemp "char *template"
47.In unistd.h
48.Ft int
49.Fn mkstemps "char *template" "int suffixlen"
50.Sh DESCRIPTION
51The
52.Fn mktemp
--- 27 unchanged lines hidden (view full) ---
80.Fn mkstemp
81function
82makes the same replacement to the template and creates the template file,
83mode 0600, returning a file descriptor opened for reading and writing.
84This avoids the race between testing for a file's existence and opening it
85for use.
86.Pp
87The
88.Fn mkstemps
89function acts the same as
90.Fn mkstemp ,
91except it permits a suffix to exist in the template.
92The template should be of the form
93.Pa /tmp/tmpXXXXXXsuffix .
94The
95.Fn mkstemps
96function
97is told the length of the suffix string.
98.Pp
99The
100.Fn mkdtemp
101function makes the same replacement to the template as in
102.Fn mktemp
103and creates the template directory, mode 0700.
104.Sh RETURN VALUES
105The
106.Fn mktemp
107and
108.Fn mkdtemp
109functions return a pointer to the template on success and
110.Dv NULL
111on failure.
112The
113.Fn mkstemp
114and
115.Fn mkstemps
116functions
117return \-1 if no suitable file could be created.
118If either call fails an error code is placed in the global variable
119.Va errno .
120.Sh ERRORS
121The
122.Fn mkstemp ,
123.Fn mkstemps
124and
125.Fn mkdtemp
126functions
127may set
128.Va errno
129to one of the following values:
130.Bl -tag -width Er
131.It Bq Er ENOTDIR
132The pathname portion of the template is not an existing directory.
133.El
134.Pp
135The
136.Fn mkstemp ,
137.Fn mkstemps
138and
139.Fn mkdtemp
140functions
141may also set
142.Va errno
143to any value specified by the
144.Xr stat 2
145function.
146.Pp
147The
148.Fn mkstemp
149and
150.Fn mkstemps
151functions
152may also set
153.Va errno
154to any value specified by the
155.Xr open 2
156function.
157.Pp
158The
--- 45 unchanged lines hidden (view full) ---
204.St -p1003.1-2008 .
205The
206.Fn mktemp
207function is expected to conform to
208.St -p1003.1-2001
209and is not specified by
210.St -p1003.1-2008 .
211The
212.Fn mkstemps
213function does not conform to any standard.
214.Sh HISTORY
215A
216.Fn mktemp
217function appeared in
218.At v7 .
219The
220.Fn mkstemp
221function appeared in
--- 5 unchanged lines hidden (view full) ---
227and later in
228.Fx 3.2 .
229The
230.Fn mkstemps
231function first appeared in
232.Ox 2.4 ,
233and later in
234.Fx 3.4 .
235.Sh BUGS
236This family of functions produces filenames which can be guessed,
237though the risk is minimized when large numbers of
238.Ql X Ns s
239are used to
240increase the number of possible temporary filenames.
241This makes the race in
242.Fn mktemp ,
243between testing for a file's existence (in the
244.Fn mktemp
245function call)
246and opening it for use
247(later in the user application)
248particularly dangerous from a security perspective.
249Whenever it is possible,
250.Fn mkstemp
251should be used instead, since it does not have the race condition.
252If
253.Fn mkstemp
254cannot be used, the filename created by
255.Fn mktemp
256should be created using the
257.Dv O_EXCL
258flag to
259.Xr open 2
260and the return status of the call should be tested for failure.
261This will ensure that the program does not continue blindly
262in the event that an attacker has already created the file
263with the intention of manipulating or reading its contents.