lib/libc/stdio/tmpnam.3

   1 .\" Copyright (c) 1988, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. 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 .\"     @(#)tmpnam.3    8.2 (Berkeley) 11/17/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd August 7, 2020
  36 .Dt TMPFILE 3
  37 .Os
  38 .Sh NAME
  39 .Nm tempnam ,
  40 .Nm tmpfile ,
  41 .Nm tmpnam
  42 .Nd temporary file routines
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In stdio.h
  47 .Ft FILE *
  48 .Fn tmpfile void
  49 .Ft char *
  50 .Fn tmpnam "char *str"
  51 .Ft char *
  52 .Fn tempnam "const char *tmpdir" "const char *prefix"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn tmpfile
  56 function
  57 returns a pointer to a stream associated with a file descriptor returned
  58 by the routine
  59 .Xr mkstemp 3 .
  60 The created file is unlinked before
  61 .Fn tmpfile
  62 returns, causing the file to be automatically deleted when the last
  63 reference to it is closed.
  64 The file is opened with the access value
  65 .Ql w+ .
  66 The file is created in the directory determined by the environment variable
  67 .Ev TMPDIR
  68 if set.
  69 The default location if
  70 .Ev TMPDIR
  71 is not set is
  72 .Pa /tmp .
  73 .Pp
  74 The
  75 .Fn tmpnam
  76 function
  77 returns a pointer to a file name, in the
  78 .Dv P_tmpdir
  79 directory, which
  80 did not reference an existing file at some indeterminate point in the
  81 past.
  82 .Dv P_tmpdir
  83 is defined in the include file
  84 .In stdio.h .
  85 If the argument
  86 .Fa str
  87 is
  88 .Pf non- Dv NULL ,
  89 the file name is copied to the buffer it references.
  90 Otherwise, the file name is copied to a static buffer.
  91 In either case,
  92 .Fn tmpnam
  93 returns a pointer to the file name.
  94 .Pp
  95 The buffer referenced by
  96 .Fa str
  97 is expected to be at least
  98 .Dv L_tmpnam
  99 bytes in length.
 100 .Dv L_tmpnam
 101 is defined in the include file
 102 .In stdio.h .
 103 .Pp
 104 The
 105 .Fn tempnam
 106 function
 107 is similar to
 108 .Fn tmpnam ,
 109 but provides the ability to specify the directory which will
 110 contain the temporary file and the file name prefix.
 111 .Pp
 112 The environment variable
 113 .Ev TMPDIR
 114 (if set), the argument
 115 .Fa tmpdir
 116 (if
 117 .Pf non- Dv NULL ) ,
 118 the directory
 119 .Dv P_tmpdir ,
 120 and the directory
 121 .Pa /tmp
 122 are tried, in the listed order, as directories in which to store the
 123 temporary file.
 124 .Pp
 125 The argument
 126 .Fa prefix ,
 127 if
 128 .Pf non- Dv NULL ,
 129 is used to specify a file name prefix, which will be the
 130 first part of the created file name.
 131 The
 132 .Fn tempnam
 133 function
 134 allocates memory in which to store the file name; the returned pointer
 135 may be used as a subsequent argument to
 136 .Xr free 3 .
 137 .Sh RETURN VALUES
 138 The
 139 .Fn tmpfile
 140 function
 141 returns a pointer to an open file stream on success, and a
 142 .Dv NULL
 143 pointer
 144 on error.
 145 .Pp
 146 The
 147 .Fn tmpnam
 148 and
 149 .Fn tempfile
 150 functions
 151 return a pointer to a file name on success, and a
 152 .Dv NULL
 153 pointer
 154 on error.
 155 .Sh ENVIRONMENT
 156 .Bl -tag -width Ds
 157 .It Ev TMPDIR
 158 .Pf [ Fn tempnam
 159 and
 160 .Fn tmpfile
 161 only]
 162 If set,
 163 the directory in which the temporary file is stored.
 164 .Ev TMPDIR
 165 is ignored for processes
 166 for which
 167 .Xr issetugid 2
 168 is true.
 169 .El
 170 .Sh COMPATIBILITY
 171 These interfaces are provided from System V and
 172 .Tn ANSI
 173 compatibility only.
 174 .Pp
 175 Most historic implementations of these functions provide
 176 only a limited number of possible temporary file names
 177 (usually 26)
 178 before file names will start being recycled.
 179 System V implementations of these functions
 180 (and of
 181 .Xr mktemp 3 )
 182 use the
 183 .Xr access 2
 184 system call to determine whether or not the temporary file
 185 may be created.
 186 This has obvious ramifications for setuid or setgid programs,
 187 complicating the portable use of these interfaces in such programs.
 188 .Pp
 189 The
 190 .Fn tmpfile
 191 interface should not be used in software expected to be used on other systems
 192 if there is any possibility that the user does not wish the temporary file to
 193 be publicly readable and writable.
 194 .Sh ERRORS
 195 The
 196 .Fn tmpfile
 197 function
 198 may fail and set the global variable
 199 .Va errno
 200 for any of the errors specified for the library functions
 201 .Xr fdopen 3
 202 or
 203 .Xr mkstemp 3 .
 204 .Pp
 205 The
 206 .Fn tmpnam
 207 function
 208 may fail and set
 209 .Va errno
 210 for any of the errors specified for the library function
 211 .Xr mktemp 3 .
 212 .Pp
 213 The
 214 .Fn tempnam
 215 function
 216 may fail and set
 217 .Va errno
 218 for any of the errors specified for the library functions
 219 .Xr malloc 3
 220 or
 221 .Xr mktemp 3 .
 222 .Sh SEE ALSO
 223 .Xr mkstemp 3 ,
 224 .Xr mktemp 3
 225 .Sh STANDARDS
 226 The
 227 .Fn tmpfile
 228 and
 229 .Fn tmpnam
 230 functions
 231 conform to
 232 .St -isoC .
 233 .Sh SECURITY CONSIDERATIONS
 234 The
 235 .Fn tmpnam
 236 and
 237 .Fn tempnam
 238 functions are susceptible to a race condition
 239 occurring between the selection of the file name
 240 and the creation of the file,
 241 which allows malicious users
 242 to potentially overwrite arbitrary files in the system,
 243 depending on the level of privilege of the running program.
 244 Additionally, there is no means by which
 245 file permissions may be specified.
 246 It is strongly suggested that
 247 .Xr mkstemp 3
 248 be used in place of these functions.