lib/libcr/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.5.2.5 2001/12/14 18:33:57 ru 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 .Aq Pa 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 .Aq Pa 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 .Fn Tempnam
 136 allocates memory in which to store the file name; the returned pointer
 137 may be used as a subsequent argument to
 138 .Xr free 3 .
 139 .Sh RETURN VALUES
 140 The
 141 .Fn tmpfile
 142 function
 143 returns a pointer to an open file stream on success, and a
 144 .Dv NULL
 145 pointer
 146 on error.
 147 .Pp
 148 The
 149 .Fn tmpnam
 150 and
 151 .Fn tempfile
 152 functions
 153 return a pointer to a file name on success, and a
 154 .Dv NULL
 155 pointer
 156 on error.
 157 .Sh ERRORS
 158 The
 159 .Fn tmpfile
 160 function
 161 may fail and set the global variable
 162 .Va errno
 163 for any of the errors specified for the library functions
 164 .Xr fdopen 3
 165 or
 166 .Xr mkstemp 3 .
 167 .Pp
 168 The
 169 .Fn tmpnam
 170 function
 171 may fail and set
 172 .Va errno
 173 for any of the errors specified for the library function
 174 .Xr mktemp 3 .
 175 .Pp
 176 The
 177 .Fn tempnam
 178 function
 179 may fail and set
 180 .Va errno
 181 for any of the errors specified for the library functions
 182 .Xr malloc 3
 183 or
 184 .Xr mktemp 3 .
 185 .Sh SEE ALSO
 186 .Xr mkstemp 3 ,
 187 .Xr mktemp 3
 188 .Sh STANDARDS
 189 The
 190 .Fn tmpfile
 191 and
 192 .Fn tmpnam
 193 functions
 194 conform to
 195 .St -isoC .
 196 .Sh BUGS
 197 These interfaces are provided for System V and
 198 .Tn ANSI
 199 compatibility only.
 200 The
 201 .Xr mkstemp 3
 202 interface is strongly preferred.
 203 .Pp
 204 There are four important problems with these interfaces (as well as
 205 with the historic
 206 .Xr mktemp 3
 207 interface).
 208 First, there is an obvious race between file name selection and file
 209 creation and deletion.
 210 Second, most historic implementations provide only a limited number
 211 of possible temporary file names (usually 26) before file names will
 212 start being recycled.
 213 Third, the System V implementations of these functions (and of
 214 .Xr mktemp 3 )
 215 use the
 216 .Xr access 2
 217 function to determine whether or not the temporary file may be created.
 218 This has obvious ramifications for setuid or setgid programs, complicating
 219 the portable use of these interfaces in such programs.
 220 Finally, there is no specification of the permissions with which the
 221 temporary files are created.
 222 .Pp
 223 This implementation does not have these flaws, but portable software
 224 cannot depend on that.
 225 In particular, the
 226 .Fn tmpfile
 227 interface should not be used in software expected to be used on other systems
 228 if there is any possibility that the user does not wish the temporary file to
 229 be publicly readable and writable.