man3/mkstemp.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright (C) 2008, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sat Jul 24 18:48:48 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified 980310, aeb
  12 .\" Modified 990328, aeb
  13 .\" 2008-06-19, mtk, Added mkostemp(); various other changes
  14 .\"
  15 .TH mkstemp 3 (date) "Linux man-pages (unreleased)"
  16 .SH NAME
  17 mkstemp, mkostemp, mkstemps, mkostemps \- create a unique temporary file
  18 .SH LIBRARY
  19 Standard C library
  20 .RI ( libc ", " \-lc )
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <stdlib.h>
  24 .PP
  25 .BI "int mkstemp(char *" template );
  26 .BI "int mkostemp(char *" template ", int " flags );
  27 .BI "int mkstemps(char *" template ", int " suffixlen );
  28 .BI "int mkostemps(char *" template ", int " suffixlen ", int " flags );
  29 .fi
  30 .PP
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .PP
  36 .BR mkstemp ():
  37 .nf
  38     _XOPEN_SOURCE >= 500
  39 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  40         || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
  41         || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  42 .fi
  43 .PP
  44 .BR mkostemp ():
  45 .nf
  46     _GNU_SOURCE
  47 .fi
  48 .PP
  49 .BR mkstemps ():
  50 .nf
  51     /* Glibc since 2.19: */ _DEFAULT_SOURCE
  52         || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  53 .fi
  54 .PP
  55 .BR mkostemps ():
  56 .nf
  57     _GNU_SOURCE
  58 .fi
  59 .SH DESCRIPTION
  60 The
  61 .BR mkstemp ()
  62 function generates a unique temporary filename from
  63 .IR template ,
  64 creates and opens the file,
  65 and returns an open file descriptor for the file.
  66 .PP
  67 The last six characters of
  68 .I template
  69 must be "XXXXXX" and these are replaced with a string that makes the
  70 filename unique.
  71 Since it will be modified,
  72 .I template
  73 must not be a string constant, but should be declared as a character array.
  74 .PP
  75 The file is created with
  76 permissions 0600, that is, read plus write for owner only.
  77 The returned file descriptor provides both read and write access to the file.
  78 The file is opened with the
  79 .BR open (2)
  80 .B O_EXCL
  81 flag, guaranteeing that the caller is the process that creates the file.
  82 .PP
  83 The
  84 .BR mkostemp ()
  85 function is like
  86 .BR mkstemp (),
  87 with the difference that the following bits\(emwith the same meaning as for
  88 .BR open (2)\(emmay
  89 be specified in
  90 .IR flags :
  91 .BR O_APPEND ,
  92 .BR O_CLOEXEC ,
  93 and
  94 .BR O_SYNC .
  95 Note that when creating the file,
  96 .BR mkostemp ()
  97 includes the values
  98 .BR O_RDWR ,
  99 .BR O_CREAT ,
 100 and
 101 .B O_EXCL
 102 in the
 103 .I flags
 104 argument given to
 105 .BR open (2);
 106 including these values in the
 107 .I flags
 108 argument given to
 109 .BR mkostemp ()
 110 is unnecessary, and produces errors on some
 111 .\" Reportedly, FreeBSD
 112 systems.
 113 .PP
 114 The
 115 .BR mkstemps ()
 116 function is like
 117 .BR mkstemp (),
 118 except that the string in
 119 .I template
 120 contains a suffix of
 121 .I suffixlen
 122 characters.
 123 Thus,
 124 .I template
 125 is of the form
 126 .IR "prefixXXXXXXsuffix" ,
 127 and the string XXXXXX is modified as for
 128 .BR mkstemp ().
 129 .PP
 130 The
 131 .BR mkostemps ()
 132 function is to
 133 .BR mkstemps ()
 134 as
 135 .BR mkostemp ()
 136 is to
 137 .BR mkstemp ().
 138 .SH RETURN VALUE
 139 On success, these functions return the file descriptor
 140 of the temporary file.
 141 On error, \-1 is returned, and
 142 .I errno
 143 is set to indicate the error.
 144 .SH ERRORS
 145 .TP
 146 .B EEXIST
 147 Could not create a unique temporary filename.
 148 Now the contents of \fItemplate\fP are undefined.
 149 .TP
 150 .B EINVAL
 151 For
 152 .BR mkstemp ()
 153 and
 154 .BR mkostemp ():
 155 The last six characters of \fItemplate\fP were not XXXXXX;
 156 now \fItemplate\fP is unchanged.
 157 .IP
 158 For
 159 .BR mkstemps ()
 160 and
 161 .BR mkostemps ():
 162 .I template
 163 is less than
 164 .I "(6 + suffixlen)"
 165 characters long, or the last 6 characters before the suffix in
 166 .I template
 167 were not XXXXXX.
 168 .PP
 169 These functions may also fail with any of the errors described for
 170 .BR open (2).
 171 .SH VERSIONS
 172 .BR mkostemp ()
 173 is available since glibc 2.7.
 174 .BR mkstemps ()
 175 and
 176 .BR mkostemps ()
 177 are available since glibc 2.11.
 178 .SH ATTRIBUTES
 179 For an explanation of the terms used in this section, see
 180 .BR attributes (7).
 181 .ad l
 182 .nh
 183 .TS
 184 allbox;
 185 lbx lb lb
 186 l l l.
 187 Interface       Attribute       Value
 188 T{
 189 .BR mkstemp (),
 190 .BR mkostemp (),
 191 .BR mkstemps (),
 192 .BR mkostemps ()
 193 T}      Thread safety   MT-Safe
 194 .TE
 195 .hy
 196 .ad
 197 .sp 1
 198 .SH STANDARDS
 199 .BR mkstemp ():
 200 4.3BSD, POSIX.1-2001.
 201 .PP
 202 .BR mkstemps ():
 203 unstandardized, but appears on several other systems.
 204 .\" mkstemps() appears to be at least on the BSDs, Mac OS X, Solaris,
 205 .\" and Tru64.
 206 .PP
 207 .BR mkostemp ()
 208 and
 209 .BR mkostemps ():
 210 are glibc extensions.
 211 .SH NOTES
 212 In glibc versions 2.06 and earlier, the file is created with permissions 0666,
 213 that is, read and write for all users.
 214 This old behavior may be
 215 a security risk, especially since other UNIX flavors use 0600,
 216 and somebody might overlook this detail when porting programs.
 217 POSIX.1-2008 adds a requirement that the file be created with mode 0600.
 218 .PP
 219 More generally, the POSIX specification of
 220 .BR mkstemp ()
 221 does not say anything
 222 about file modes, so the application should make sure its
 223 file mode creation mask (see
 224 .BR umask (2))
 225 is set appropriately before calling
 226 .BR mkstemp ()
 227 (and
 228 .BR mkostemp ()).
 229 .\"
 230 .\" The prototype for
 231 .\" .BR mkstemp ()
 232 .\" is in
 233 .\" .I <unistd.h>
 234 .\" for libc4, libc5, glibc1; glibc2 follows POSIX.1 and has the prototype in
 235 .\" .IR <stdlib.h> .
 236 .SH SEE ALSO
 237 .BR mkdtemp (3),
 238 .BR mktemp (3),
 239 .BR tempnam (3),
 240 .BR tmpfile (3),
 241 .BR tmpnam (3)