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