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. 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$
  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 .Fd #include <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 .Pp
  71 The
  72 .Fn tmpnam
  73 function
  74 returns a pointer to a file name, in the
  75 .Dv P_tmpdir
  76 directory, which
  77 did not reference an existing file at some indeterminate point in the
  78 past.
  79 .Dv P_tmpdir
  80 is defined in the include file
  81 .Aq Pa stdio.h .
  82 If the argument
  83 .Fa str
  84 is
  85 .Pf non- Dv NULL ,
  86 the file name is copied to the buffer it references.
  87 Otherwise, the file name is copied to a static buffer.
  88 In either case,
  89 .Fn tmpnam
  90 returns a pointer to the file name.
  91 .Pp
  92 The buffer referenced by
  93 .Fa str
  94 is expected to be at least
  95 .Dv L_tmpnam
  96 bytes in length.
  97 .Dv L_tmpnam
  98 is defined in the include file
  99 .Aq Pa stdio.h .
 100 .Pp
 101 The
 102 .Fn tempnam
 103 function
 104 is similar to
 105 .Fn tmpnam ,
 106 but provides the ability to specify the directory which will
 107 contain the temporary file and the file name prefix.
 108 .Pp
 109 The environment variable
 110 .Ev TMPDIR
 111 (if set), the argument
 112 .Fa tmpdir
 113 (if
 114 .Pf non- Dv NULL ) ,
 115 the directory
 116 .Dv P_tmpdir ,
 117 and the directory
 118 .Pa /tmp
 119 are tried, in the listed order, as directories in which to store the
 120 temporary file.
 121 .Pp
 122 The argument
 123 .Fa prefix ,
 124 if
 125 .Pf non- Dv NULL ,
 126 is used to specify a file name prefix, which will be the
 127 first part of the created file name.
 128 .Fn Tempnam
 129 allocates memory in which to store the file name; the returned pointer
 130 may be used as a subsequent argument to
 131 .Xr free 3 .
 132 .Sh RETURN VALUES
 133 The
 134 .Fn tmpfile
 135 function
 136 returns a pointer to an open file stream on success, and a
 137 .Dv NULL
 138 pointer
 139 on error.
 140 .Pp
 141 The
 142 .Fn tmpnam
 143 and
 144 .Fn tempfile
 145 functions
 146 return a pointer to a file name on success, and a
 147 .Dv NULL
 148 pointer
 149 on error.
 150 .Sh ERRORS
 151 The
 152 .Fn tmpfile
 153 function
 154 may fail and set the global variable
 155 .Va errno
 156 for any of the errors specified for the library functions
 157 .Xr fdopen 3
 158 or
 159 .Xr mkstemp 3 .
 160 .Pp
 161 The
 162 .Fn tmpnam
 163 function
 164 may fail and set
 165 .Va errno
 166 for any of the errors specified for the library function
 167 .Xr mktemp 3 .
 168 .Pp
 169 The
 170 .Fn tempnam
 171 function
 172 may fail and set
 173 .Va errno
 174 for any of the errors specified for the library functions
 175 .Xr malloc 3
 176 or
 177 .Xr mktemp 3 .
 178 .Sh SEE ALSO
 179 .Xr mkstemp 3 ,
 180 .Xr mktemp 3
 181 .Sh STANDARDS
 182 The
 183 .Fn tmpfile
 184 and
 185 .Fn tmpnam
 186 functions
 187 conform to
 188 .St -isoC .
 189 .Sh BUGS
 190 These interfaces are provided for System V and
 191 .Tn ANSI
 192 compatibility only.
 193 The
 194 .Xr mkstemp 3
 195 interface is strongly preferred.
 196 .Pp
 197 There are four important problems with these interfaces (as well as
 198 with the historic
 199 .Xr mktemp 3
 200 interface).
 201 First, there is an obvious race between file name selection and file
 202 creation and deletion.
 203 Second, most historic implementations provide only a limited number
 204 of possible temporary file names (usually 26) before file names will
 205 start being recycled.
 206 Third, the System V implementations of these functions (and of
 207 .Xr mktemp 3 )
 208 use the
 209 .Xr access 2
 210 function to determine whether or not the temporary file may be created.
 211 This has obvious ramifications for setuid or setgid programs, complicating
 212 the portable use of these interfaces in such programs.
 213 Finally, there is no specification of the permissions with which the
 214 temporary files are created.
 215 .Pp
 216 This implementation does not have these flaws, but portable software
 217 cannot depend on that.
 218 In particular, the
 219 .Fn tmpfile
 220 interface should not be used in software expected to be used on other systems
 221 if there is any possibility that the user does not wish the temporary file to
 222 be publicly readable and writable.