stdio/FreeBSD/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 .Fn tmpfile void
  53 .Ft char *
  54 .Fn tmpnam "char *str"
  55 .Ft char *
  56 .Fn tempnam "const char *tmpdir" "const char *prefix"
  57 .Sh DESCRIPTION
  58 The
  59 .Fn tmpfile
  60 function
  61 returns a pointer to a stream associated with a file descriptor returned
  62 by the routine
  63 .Xr mkstemp 3 .
  64 The created file is unlinked before
  65 .Fn tmpfile
  66 returns, causing the file to be automatically deleted when the last
  67 reference to it is closed.
  68 The file is opened with the access value
  69 .Ql w+ .
  70 The file is created in the directory determined by the environment variable
  71 .Ev TMPDIR
  72 if set.
  73 The default location if
  74 .Ev TMPDIR
  75 is not set is
  76 .Pa /tmp .
  77 .Pp
  78 The
  79 .Fn tmpnam
  80 function
  81 returns a pointer to a file name, in the
  82 .Dv P_tmpdir
  83 directory, which
  84 did not reference an existing file at some indeterminate point in the
  85 past.
  86 .Dv P_tmpdir
  87 is defined in the include file
  88 .In stdio.h .
  89 If the argument
  90 .Fa str
  91 is
  92 .Pf non- Dv NULL ,
  93 the file name is copied to the buffer it references.
  94 Otherwise, the file name is copied to a static buffer.
  95 In either case,
  96 .Fn tmpnam
  97 returns a pointer to the file name.
  98 .Pp
  99 The buffer referenced by
 100 .Fa str
 101 is expected to be at least
 102 .Dv L_tmpnam
 103 bytes in length.
 104 .Dv L_tmpnam
 105 is defined in the include file
 106 .In stdio.h .
 107 .Pp
 108 The
 109 .Fn tempnam
 110 function
 111 is similar to
 112 .Fn tmpnam ,
 113 but provides the ability to specify the directory which will
 114 contain the temporary file and the file name prefix.
 115 .Pp
 116 The environment variable
 117 .Ev TMPDIR
 118 (if set), the argument
 119 .Fa tmpdir
 120 (if
 121 .Pf non- Dv NULL ) ,
 122 the directory
 123 .Dv P_tmpdir ,
 124 and the directory
 125 .Pa /tmp
 126 are tried, in the listed order, as directories in which to store the
 127 temporary file.
 128 .Pp
 129 The argument
 130 .Fa prefix ,
 131 if
 132 .Pf non- Dv NULL ,
 133 is used to specify a file name prefix, which will be the
 134 first part of the created file name.
 135 The
 136 .Fn tempnam
 137 function
 138 allocates memory in which to store the file name; the returned pointer
 139 may be used as a subsequent argument to
 140 .Xr free 3 .
 141 .Sh RETURN VALUES
 142 The
 143 .Fn tmpfile
 144 function
 145 returns a pointer to an open file stream on success, and a
 146 .Dv NULL
 147 pointer
 148 on error.
 149 .Pp
 150 The
 151 .Fn tmpnam
 152 and
 153 .Fn tempfile
 154 functions
 155 return a pointer to a file name on success, and a
 156 .Dv NULL
 157 pointer
 158 on error.
 159 .Sh ERRORS
 160 The
 161 .Fn tmpfile
 162 function
 163 may fail and set the global variable
 164 .Va errno
 165 for any of the errors specified for the library functions
 166 .Xr fdopen 3
 167 or
 168 .Xr mkstemp 3 .
 169 .Pp
 170 The
 171 .Fn tmpnam
 172 function
 173 may fail and set
 174 .Va errno
 175 for any of the errors specified for the library function
 176 .Xr mktemp 3 .
 177 .Pp
 178 The
 179 .Fn tempnam
 180 function
 181 may fail and set
 182 .Va errno
 183 for any of the errors specified for the library functions
 184 .Xr malloc 3
 185 or
 186 .Xr mktemp 3 .
 187 .Sh SECURITY CONSIDERATIONS
 188 The
 189 .Fn tmpnam
 190 and
 191 .Fn tempnam
 192 functions are susceptible to a race condition
 193 occurring between the selection of the file name
 194 and the creation of the file,
 195 which allows malicious users
 196 to potentially overwrite arbitrary files in the system,
 197 depending on the level of privilege of the running program.
 198 Additionally, there is no means by which
 199 file permissions may be specified.
 200 It is strongly suggested that
 201 .Xr mkstemp 3
 202 be used in place of these functions.
 203 (See
 204 the FSA.)
 205 .Sh COMPATIBILITY
 206 These interfaces are provided from System V and
 207 .Tn ANSI
 208 compatibility only.
 209 .Pp
 210 Most historic implementations of these functions provide
 211 only a limited number of possible temporary file names
 212 (usually 26)
 213 before file names will start being recycled.
 214 System V implementations of these functions
 215 (and of
 216 .Xr mktemp 3 )
 217 use the
 218 .Xr access 2
 219 system call to determine whether or not the temporary file
 220 may be created.
 221 This has obvious ramifications for setuid or setgid programs,
 222 complicating the portable use of these interfaces in such programs.
 223 .Pp
 224 The
 225 .Fn tmpfile
 226 interface should not be used in software expected to be used on other systems
 227 if there is any possibility that the user does not wish the temporary file to
 228 be publicly readable and writable.
 229 .Sh SEE ALSO
 230 .Xr mkstemp 3 ,
 231 .Xr mktemp 3
 232 .Rs
 233 .%T "The FreeBSD Security Architecture"
 234 .Re
 235 (See
 236 .Pa "/usr/share/doc/{to be determined}" . )
 237 .Sh STANDARDS
 238 The
 239 .Fn tmpfile
 240 and
 241 .Fn tmpnam
 242 functions
 243 conform to
 244 .St -isoC .