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