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. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)tmpnam.3    8.2 (Berkeley) 11/17/93
  37 .\" $FreeBSD: src/lib/libc/stdio/tmpnam.3,v 1.16 2004/06/21 19:38:25 mpp Exp $
  38 .\"
  39 .Dd November 17, 1993
  40 .Dt TMPFILE 3
  41 .Os
  42 .Sh NAME
  43 .Nm tempnam ,
  44 .Nm tmpfile ,
  45 .Nm tmpnam
  46 .Nd temporary file routines
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In stdio.h
  51 .Ft FILE *
  52 .Fo tmpfile
  53 .Fa void
  54 .Fc
  55 .Ft char *
  56 .Fo tmpnam
  57 .Fa "char *s"
  58 .Fc
  59 .Ft char *
  60 .Fo tempnam
  61 .Fa "const char *dir"
  62 .Fa "const char *pfx"
  63 .Fc
  64 .Sh DESCRIPTION
  65 The
  66 .Fn tmpfile
  67 function
  68 returns a pointer to a stream associated with a file descriptor returned
  69 by the routine
  70 .Xr mkstemp 3 .
  71 The created file is unlinked before
  72 .Fn tmpfile
  73 returns, causing the file to be automatically deleted when the last
  74 reference to it is closed.
  75 The file is opened with the access value
  76 .Ql w+ .
  77 If the environment variable
  78 .Ev TMPDIR
  79 is defined,
  80 the file is created in the specified directory.
  81 The default location, if
  82 .Ev TMPDIR
  83 is not set, is
  84 .Pa /tmp .
  85 .Pp
  86 The
  87 .Fn tmpnam
  88 function
  89 returns a pointer to a file name, in the
  90 .Dv P_tmpdir
  91 directory, which
  92 did not reference an existing file at some indeterminate point in the
  93 past.
  94 .Dv P_tmpdir
  95 is defined in the include file
  96 .In stdio.h .
  97 If the argument
  98 .Fa s
  99 is
 100 .Pf non- Dv NULL ,
 101 the file name is copied to the buffer it references.
 102 Otherwise, the file name is copied to a static buffer.
 103 In either case,
 104 .Fn tmpnam
 105 returns a pointer to the file name.
 106 .Pp
 107 The buffer referenced by
 108 .Fa s
 109 is expected to be at least
 110 .Dv L_tmpnam
 111 bytes in length.
 112 .Dv L_tmpnam
 113 is defined in the include file
 114 .In stdio.h .
 115 .Pp
 116 The
 117 .Fn tempnam
 118 function
 119 is similar to
 120 .Fn tmpnam ,
 121 but provides the ability to specify the directory which will
 122 contain the temporary file and the file name prefix.
 123 .Pp
 124 The environment variable
 125 .Ev TMPDIR
 126 (if set), the argument
 127 .Fa dir
 128 (if
 129 .Pf non- Dv NULL ) ,
 130 the directory
 131 .Dv P_tmpdir ,
 132 and the directory
 133 .Pa /tmp
 134 are tried, in the listed order, as directories in which to store the
 135 temporary file.
 136 .Pp
 137 The argument
 138 .Fa pfx ,
 139 if
 140 .Pf non- Dv NULL ,
 141 is used to specify a file name prefix, which will be the
 142 first part of the created file name.
 143 The
 144 .Fn tempnam
 145 function
 146 allocates memory in which to store the file name; the returned pointer
 147 may be used as a subsequent argument to
 148 .Xr free 3 .
 149 .Sh RETURN VALUES
 150 The
 151 .Fn tmpfile
 152 function
 153 returns a pointer to an open file stream on success, and a
 154 .Dv NULL
 155 pointer
 156 on error.
 157 .Pp
 158 The
 159 .Fn tmpnam
 160 and
 161 .Fn tempfile
 162 functions
 163 return a pointer to a file name on success, and a
 164 .Dv NULL
 165 pointer
 166 on error.
 167 .Sh ERRORS
 168 The
 169 .Fn tmpfile
 170 function
 171 may fail and set the global variable
 172 .Va errno
 173 for any of the errors specified for the library functions
 174 .Xr fdopen 3
 175 or
 176 .Xr mkstemp 3 .
 177 .Pp
 178 The
 179 .Fn tmpnam
 180 function
 181 may fail and set
 182 .Va errno
 183 for any of the errors specified for the library function
 184 .Xr mktemp 3 .
 185 .Pp
 186 The
 187 .Fn tempnam
 188 function
 189 may fail and set
 190 .Va errno
 191 for any of the errors specified for the library functions
 192 .Xr malloc 3
 193 or
 194 .Xr mktemp 3 .
 195 .Sh SECURITY CONSIDERATIONS
 196 The
 197 .Fn tmpnam
 198 and
 199 .Fn tempnam
 200 functions are susceptible to a race condition
 201 occurring between the selection of the file name
 202 and the creation of the file,
 203 which allows malicious users
 204 to potentially overwrite arbitrary files in the system,
 205 depending on the level of privilege of the running program.
 206 Additionally, there is no means by which
 207 file permissions may be specified.
 208 It is strongly suggested that
 209 .Xr mkstemp 3
 210 be used in place of these functions.
 211 (See
 212 the FSA.)
 213 .Sh COMPATIBILITY
 214 These interfaces are provided from System V and
 215 .Tn ANSI
 216 compatibility only.
 217 .Pp
 218 Most historic implementations of these functions provide
 219 only a limited number of possible temporary file names
 220 (usually 26)
 221 before file names will start being recycled.
 222 System V implementations of these functions
 223 (and of
 224 .Xr mktemp 3 )
 225 use the
 226 .Xr access 2
 227 system call to determine whether or not the temporary file
 228 may be created.
 229 This has obvious ramifications for setuid or setgid programs,
 230 complicating the portable use of these interfaces in such programs.
 231 .Pp
 232 The
 233 .Fn tmpfile
 234 interface should not be used in software expected to be used on other systems
 235 if there is any possibility that the user does not wish the temporary file to
 236 be publicly readable and writable.
 237 .Sh SEE ALSO
 238 .Xr mkstemp 3 ,
 239 .Xr mktemp 3
 240 .Sh STANDARDS
 241 The
 242 .Fn tmpfile
 243 and
 244 .Fn tmpnam
 245 functions
 246 conform to
 247 .St -isoC .