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 .\" 4. 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: src/lib/libc/stdio/tmpnam.3,v 1.20 2007/03/16 21:46:24 maxim Exp $
  34 .\"
  35 .Dd March 18, 2007
  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 only]
 160 If set,
 161 the directory in which the temporary file is stored.
 162 .Ev TMPDIR
 163 is ignored for processes
 164 for which
 165 .Xr issetugid 2
 166 is true.
 167 .El
 168 .Sh COMPATIBILITY
 169 These interfaces are provided from System V and
 170 .Tn ANSI
 171 compatibility only.
 172 .Pp
 173 Most historic implementations of these functions provide
 174 only a limited number of possible temporary file names
 175 (usually 26)
 176 before file names will start being recycled.
 177 System V implementations of these functions
 178 (and of
 179 .Xr mktemp 3 )
 180 use the
 181 .Xr access 2
 182 system call to determine whether or not the temporary file
 183 may be created.
 184 This has obvious ramifications for setuid or setgid programs,
 185 complicating the portable use of these interfaces in such programs.
 186 .Pp
 187 The
 188 .Fn tmpfile
 189 interface should not be used in software expected to be used on other systems
 190 if there is any possibility that the user does not wish the temporary file to
 191 be publicly readable and writable.
 192 .Sh ERRORS
 193 The
 194 .Fn tmpfile
 195 function
 196 may fail and set the global variable
 197 .Va errno
 198 for any of the errors specified for the library functions
 199 .Xr fdopen 3
 200 or
 201 .Xr mkstemp 3 .
 202 .Pp
 203 The
 204 .Fn tmpnam
 205 function
 206 may fail and set
 207 .Va errno
 208 for any of the errors specified for the library function
 209 .Xr mktemp 3 .
 210 .Pp
 211 The
 212 .Fn tempnam
 213 function
 214 may fail and set
 215 .Va errno
 216 for any of the errors specified for the library functions
 217 .Xr malloc 3
 218 or
 219 .Xr mktemp 3 .
 220 .Sh SECURITY CONSIDERATIONS
 221 The
 222 .Fn tmpnam
 223 and
 224 .Fn tempnam
 225 functions are susceptible to a race condition
 226 occurring between the selection of the file name
 227 and the creation of the file,
 228 which allows malicious users
 229 to potentially overwrite arbitrary files in the system,
 230 depending on the level of privilege of the running program.
 231 Additionally, there is no means by which
 232 file permissions may be specified.
 233 It is strongly suggested that
 234 .Xr mkstemp 3
 235 be used in place of these functions.
 236 (See
 237 the FSA.)
 238 .Sh SEE ALSO
 239 .Xr mkstemp 3 ,
 240 .Xr mktemp 3
 241 .Sh STANDARDS
 242 The
 243 .Fn tmpfile
 244 and
 245 .Fn tmpnam
 246 functions
 247 conform to
 248 .St -isoC .