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