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