man3/mkstemp.3

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