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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)mktemp.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd February 11, 1998 36.Dt MKTEMP 3 37.Os 38.Sh NAME 39.Nm mktemp 40.Nd make temporary file name (unique) 41.Sh SYNOPSIS 42.Fd #include <unistd.h> 43.Ft char * 44.Fn mktemp "char *template" 45.Ft int 46.Fn mkstemp "char *template" 47.Ft int 48.Fn mkstemps "char *template" "int suffixlen" 49.Ft char * 50.Fn mkdtemp "char *template" 51.Sh DESCRIPTION 52The 53.Fn mktemp 54function 55takes the given file name template and overwrites a portion of it 56to create a file name. 57This file name is unique and 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.XXXX . 64The trailing 65.Ql X Ns s 66are replaced with the current process number and/or a 67unique letter 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 77testing roughly 26 ** 6 combinations. 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 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 . 94.Fn mkstemps 95is told the length of the suffix string. 96.Pp 97The 98.Fn mkdtemp 99function makes the same replacement to the template as in 100.Xr mktemp 3 101and creates the template directory, mode 0700. 102.Sh RETURN VALUES 103The 104.Fn mktemp 105and 106.Fn mkdtemp 107functions return a pointer to the template on success and 108.Dv NULL 109on failure. 110The 111.Fn mkstemp 112and 113.Fn mkstemps 114functions 115return \-1 if no suitable file could be created. 116If either call fails an error code is placed in the global variable 117.Va errno . 118.Sh ERRORS 119The 120.Fn mkstemp , 121.Fn mkstemps 122and 123.Fn mkdtemp 124functions 125may set 126.Va errno 127to one of the following values: 128.Bl -tag -width [ENOTDIR] 129.It Bq Er ENOTDIR 130The pathname portion of the template is not an existing directory. 131.El 132.Pp 133The 134.Fn mkstemp , 135.Fn mkstemps 136and 137.Fn mkdtemp 138functions 139may also set 140.Va errno 141to any value specified by the 142.Xr stat 2 143function. 144.Pp 145The 146.Fn mkstemp 147and 148.Fn mkstemps 149functions 150may also set 151.Va errno 152to any value specified by the 153.Xr open 2 154function. 155.Pp 156The 157.Fn mkdtemp 158function 159may also set 160.Va errno 161to any value specified by the 162.Xr mkdir 2 163function. 164.Sh NOTES 165A common problem that results in a core dump is that the programmer 166passes in a read-only string to 167.Fn mktemp , 168.Fn mkstemp , 169.Fn mkstemps 170or 171.Fn mkdtemp . 172This is common with programs that were developed before 173.St -ansiC 174compilers were common. 175For example, calling 176.Fn mkstemp 177with an argument of 178.Qq /tmp/tempfile.XXXXXX 179will result in a core dump due to 180.Fn mkstemp 181attempting to modify the string constant that was given. 182If the program in question makes heavy use of that type 183of function call, you do have the option of compiling the program 184so that it will store string constants in a writable segment of memory. 185See 186.Xr gcc 1 187for more information. 188.Sh BUGS 189This family of functions produces filenames which can be guessed. 190This makes the race in 191.Fn mktemp , 192between testing for a file's existence and opening it for use, 193particularly dangerous from a security perspective. 194Whenever it is possible, 195.Fn mkstemp 196should be used instead. 197.Sh SEE ALSO 198.Xr chmod 2 , 199.Xr getpid 2 , 200.Xr mkdir 2 , 201.Xr open 2 , 202.Xr stat 2 203.Sh HISTORY 204A 205.Fn mktemp 206function appeared in 207.At v7 . 208The 209.Fn mkdtemp 210function first appeared in 211.Ox 2.2 , 212and later in 213.Fx 3.2 . 214The 215.Fn mkstemps 216function first appeared in 217.Ox 2.4 , 218and later in 219.Fx 3.4 . 220