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