Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1988, 1991 The Regents of the University of California. |
ecd109e0 KB |
2 | .\" All rights reserved. |
3 | .\" | |
043368e6 KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" the American National Standards Committee X3, on Information | |
6 | .\" Processing Systems. | |
7 | .\" | |
4789dcfb | 8 | .\" %sccs.include.redist.man% |
ecd109e0 | 9 | .\" |
043368e6 | 10 | .\" @(#)tmpnam.3 5.14 (Berkeley) %G% |
ecd109e0 | 11 | .\" |
ae59e04c CL |
12 | .Dd |
13 | .Dt TMPFILE 3 | |
14 | .Os | |
15 | .Sh NAME | |
16 | .Nm tempnam , | |
17 | .Nm tmpfile , | |
18 | .Nm tmpnam | |
19 | .Nd temporary file routines | |
20 | .Sh SYNOPSIS | |
21 | .Fd #include <stdio.h> | |
22 | .Ft FILE * | |
23 | .Fn tmpfile void | |
24 | .Ft char * | |
25 | .Fn tmpnam "char *str" | |
26 | .Ft char * | |
27 | .Fn tempnam "const char *tmpdir" "const char *prefix" | |
28 | .Sh DESCRIPTION | |
29 | The | |
30 | .Fn tmpfile | |
31 | function | |
96ea859a KB |
32 | returns a pointer to a stream associated with a file descriptor returned |
33 | by the routine | |
ae59e04c | 34 | .Xr mkstemp 3 . |
4789dcfb | 35 | The created file is unlinked before |
ae59e04c | 36 | .Fn tmpfile |
96ea859a KB |
37 | returns, causing the file to be automatically deleted when the last |
38 | reference to it is closed. | |
ae59e04c CL |
39 | The file is opened with the access value |
40 | .Ql w+ . | |
41 | .Pp | |
42 | The | |
43 | .Fn tmpnam | |
44 | function | |
45 | returns a pointer to a file name, in the | |
46 | .Dv P_tmpdir | |
47 | directory, which | |
4789dcfb KB |
48 | did not reference an existing file at some indeterminate point in the |
49 | past. | |
ae59e04c CL |
50 | .Dv P_tmpdir |
51 | is defined in the include file | |
52 | .Aq Pa stdio.h . | |
4789dcfb | 53 | If the argument |
ae59e04c CL |
54 | .Fa s |
55 | is | |
56 | .Pf non- Dv NULL , | |
57 | the file name is copied to the buffer it references. | |
96ea859a | 58 | Otherwise, the file name is copied to a static buffer. |
4789dcfb | 59 | In either case, |
ae59e04c | 60 | .Fn tmpnam |
96ea859a | 61 | returns a pointer to the file name. |
ae59e04c | 62 | .Pp |
96ea859a | 63 | The buffer referenced by |
ae59e04c CL |
64 | .Fa s |
65 | is expected to be at least | |
66 | .Dv L_tmpnam | |
67 | bytes in length. | |
68 | .Dv L_tmpnam | |
69 | is defined in the include file | |
70 | .Aq Pa stdio.h . | |
71 | .Pp | |
72 | The | |
73 | .Fn tempnam | |
74 | function | |
4789dcfb | 75 | is similar to |
ae59e04c | 76 | .Fn tmpnam , |
4789dcfb KB |
77 | but provides the ability to specify the directory which will |
78 | contain the temporary file and the file name prefix. | |
ae59e04c CL |
79 | .Pp |
80 | The environment variable | |
81 | .Ev TMPDIR | |
82 | (if set), the argument | |
83 | .Fa dir | |
84 | (if | |
85 | .Pf non- Dv NULL ) , | |
86 | the directory | |
87 | .Dv P_tmpdir , | |
88 | and the directory | |
89 | .Pa /tmp | |
4789dcfb KB |
90 | are tried, in the listed order, as directories in which to store the |
91 | temporary file. | |
ae59e04c | 92 | .Pp |
4789dcfb | 93 | The argument |
ae59e04c CL |
94 | .Fa prefix , |
95 | if | |
96 | .Pf non- Dv NULL , | |
97 | is used to specify a file name prefix, which will be the | |
4789dcfb | 98 | first part of the created file name. |
ae59e04c | 99 | .Fn Tempnam |
96ea859a KB |
100 | allocates memory in which to store the file name; the returned pointer |
101 | may be used as a subsequent argument to | |
ae59e04c CL |
102 | .Xr free 3 . |
103 | .Sh RETURN VALUES | |
104 | The | |
105 | .Fn tmpfile | |
106 | function | |
107 | returns a pointer to an open file stream on success, and a | |
108 | .Dv NULL | |
109 | pointer | |
96ea859a | 110 | on error. |
ae59e04c CL |
111 | .Pp |
112 | The | |
113 | .Fn tmpnam | |
4789dcfb | 114 | and |
ae59e04c CL |
115 | .Fn tempfile |
116 | functions | |
117 | return a pointer to a file name on success, and a | |
118 | .Dv NULL | |
119 | pointer | |
96ea859a | 120 | on error. |
ae59e04c CL |
121 | .Sh ERRORS |
122 | The | |
123 | .Fn tmpfile | |
124 | function | |
125 | may fail and set the global variable | |
126 | .Va errno | |
96ea859a | 127 | for any of the errors specified for the library functions |
ae59e04c | 128 | .Xr fdopen 3 |
96ea859a | 129 | or |
ae59e04c CL |
130 | .Xr mkstemp 3 . |
131 | .Pp | |
132 | The | |
133 | .Fn tmpnam | |
134 | function | |
96ea859a | 135 | may fail and set |
ae59e04c | 136 | .Va errno |
96ea859a | 137 | for any of the errors specified for the library function |
ae59e04c CL |
138 | .Xr mktemp 3 . |
139 | .Pp | |
140 | The | |
141 | .Fn tempnam | |
142 | function | |
96ea859a | 143 | may fail and set |
ae59e04c | 144 | .Va errno |
96ea859a | 145 | for any of the errors specified for the library functions |
ae59e04c | 146 | .Xr malloc 3 |
96ea859a | 147 | or |
ae59e04c CL |
148 | .Xr mktemp 3 . |
149 | .Sh SEE ALSO | |
150 | .Xr mkstemp 3 , | |
151 | .Xr mktemp 3 | |
152 | .Sh STANDARDS | |
4789dcfb | 153 | The |
ae59e04c CL |
154 | .Fn tmpfile |
155 | and | |
156 | .Fn tmpnam | |
157 | functions | |
158 | conform to | |
159 | .St -ansiC . | |
160 | .Sh BUGS | |
161 | These interfaces are provided for System V and | |
162 | .Tn ANSI | |
163 | compatibility only. | |
164 | The | |
165 | .Xr mkstemp 3 | |
4789dcfb | 166 | interface is strongly preferred. |
ae59e04c | 167 | .Pp |
96ea859a | 168 | There are four important problems with these interfaces (as well as |
4789dcfb | 169 | with the historic |
ae59e04c | 170 | .Xr mktemp 3 |
4789dcfb KB |
171 | interface). |
172 | First, there is an obvious race between file name selection and file | |
96ea859a KB |
173 | creation and deletion. |
174 | Second, most historic implementations provide only a limited number | |
175 | of possible temporary file names (usually 26) before file names will | |
176 | start being recycled. | |
177 | Third, the System V implementations of these functions (and of | |
ae59e04c | 178 | .Xr mktemp ) |
4789dcfb | 179 | use the |
ae59e04c | 180 | .Xr access 2 |
96ea859a | 181 | function to determine whether or not the temporary file may be created. |
4789dcfb KB |
182 | This has obvious ramifications for setuid or setgid programs, complicating |
183 | the portable use of these interfaces in such programs. | |
96ea859a KB |
184 | Finally, there is no specification of the permissions with which the |
185 | temporary files are created. | |
ae59e04c | 186 | .Pp |
96ea859a KB |
187 | This implementation does not have these flaws, but portable software |
188 | cannot depend on that. | |
189 | In particular, the | |
ae59e04c | 190 | .Fn tmpfile |
96ea859a KB |
191 | interface should not be used in software expected to be used on other systems |
192 | if there is any possibility that the user does not wish the temporary file to | |
193 | be publicly readable and writable. |