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