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
| 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: head/lib/libc/stdio/mktemp.3 252838 2013-07-05 20:24:50Z jilles $
| 29.\" $FreeBSD: head/lib/libc/stdio/mktemp.3 254151 2013-08-09 17:24:23Z jilles $
|
30.\"
| 30.\"
|
31.Dd July 5, 2013
| 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"
| 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"
|
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 53function 54takes the given file name template and overwrites a portion of it 55to create a file name. 56This file name is guaranteed not to exist at the time of function invocation 57and is suitable for use 58by the application. 59The template may be any file name with some number of 60.Ql X Ns s 61appended 62to it, for example 63.Pa /tmp/temp.XXXXXX . 64The trailing 65.Ql X Ns s 66are replaced with a 67unique alphanumeric combination. 68The number of unique file names 69.Fn mktemp 70can return depends on the number of 71.Ql X Ns s 72provided; six 73.Ql X Ns s 74will 75result in 76.Fn mktemp 77selecting one of 56800235584 (62 ** 6) possible temporary file names. 78.Pp 79The 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
| 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
|
88.Fn mkstemps
| 110.Fn mkstemps
|
89function acts the same as 90.Fn mkstemp , 91except it permits a suffix to exist in the template.
| 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.
|
92The template should be of the form 93.Pa /tmp/tmpXXXXXXsuffix . 94The 95.Fn mkstemps
| 119The template should be of the form 120.Pa /tmp/tmpXXXXXXsuffix . 121The 122.Fn mkstemps
|
| 123and 124.Fn mkostemps
|
96function
| 125function
|
97is told the length of the suffix string.
| 126are 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
| 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
|
113.Fn mkstemp 114and
| 142.Fn mkstemp , 143.Fn mkostemp
|
115.Fn mkstemps
| 144.Fn mkstemps
|
| 145and 146.Fn mkostemps
|
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 ,
| 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 ,
|
123.Fn mkstemps
| 154.Fn mkostemp , 155.Fn mkstemps , 156.Fn mkostemps
|
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
| 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
|
136.Fn mkstemp ,
| 184.Fn mkstemp ,
|
137.Fn mkstemps
| 185.Fn mkostemp , 186.Fn mkstemps , 187.Fn mkostemps
|
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
| 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
|
148.Fn mkstemp 149and
| 198.Fn mkstemp , 199.Fn mkostemp ,
|
150.Fn mkstemps
| 200.Fn mkstemps
|
| 201and 202.Fn mkostemps
|
151functions 152may also set 153.Va errno 154to any value specified by the 155.Xr open 2 156function. 157.Pp 158The 159.Fn mkdtemp 160function 161may also set 162.Va errno 163to any value specified by the 164.Xr mkdir 2 165function. 166.Sh NOTES 167A common problem that results in a core dump is that the programmer 168passes in a read-only string to 169.Fn mktemp , 170.Fn mkstemp , 171.Fn mkstemps 172or 173.Fn mkdtemp . 174This is common with programs that were developed before 175.St -isoC 176compilers were common. 177For example, calling 178.Fn mkstemp 179with an argument of 180.Qq /tmp/tempfile.XXXXXX 181will result in a core dump due to 182.Fn mkstemp 183attempting to modify the string constant that was given. 184.Pp 185The 186.Fn mkdtemp , 187.Fn mkstemp 188and 189.Fn mktemp 190function prototypes are also available from 191.In unistd.h . 192.Sh SEE ALSO 193.Xr chmod 2 , 194.Xr getpid 2 , 195.Xr mkdir 2 , 196.Xr open 2 , 197.Xr stat 2 198.Sh STANDARDS 199The 200.Fn mkstemp 201and 202.Fn mkdtemp 203functions are expected to conform to 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
| 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 ,
|
212.Fn mkstemps
| 265.Fn mkstemps
|
213function does not conform to any standard.
| 266and 267.Fn mkostemps 268functions do 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 222.Bx 4.4 . 223The 224.Fn mkdtemp 225function first appeared in 226.Ox 2.2 , 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 .
| 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 .
|
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
| 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
|
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.
| 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.
|