]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da | 4 | .\" |
4c1c5274 | 5 | .TH tempnam 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
6 | .SH NAME |
7 | tempnam \- create a name for a temporary file | |
99fd3650 AC |
8 | .SH LIBRARY |
9 | Standard C library | |
8fc3b2cf | 10 | .RI ( libc ", " \-lc ) |
fea681da MK |
11 | .SH SYNOPSIS |
12 | .nf | |
13 | .B #include <stdio.h> | |
68e4db0a | 14 | .PP |
fea681da MK |
15 | .BI "char *tempnam(const char *" dir ", const char *" pfx ); |
16 | .fi | |
68e4db0a | 17 | .PP |
d39ad78f | 18 | .RS -4 |
cc4615cc MK |
19 | Feature Test Macro Requirements for glibc (see |
20 | .BR feature_test_macros (7)): | |
d39ad78f | 21 | .RE |
68e4db0a | 22 | .PP |
cc4615cc | 23 | .BR tempnam (): |
9d281e06 | 24 | .nf |
51c612fb MK |
25 | Since glibc 2.19: |
26 | _DEFAULT_SOURCE | |
27 | Glibc 2.19 and earlier: | |
28 | _BSD_SOURCE || _SVID_SOURCE | |
9d281e06 | 29 | .fi |
fea681da | 30 | .SH DESCRIPTION |
47ce47ea MK |
31 | .I "Never use this function." |
32 | Use | |
33 | .BR mkstemp (3) | |
34 | or | |
35 | .BR tmpfile (3) | |
36 | instead. | |
847e0d88 | 37 | .PP |
fea681da | 38 | The |
63aa9df0 | 39 | .BR tempnam () |
fea681da MK |
40 | function returns a pointer to a string that is a valid filename, |
41 | and such that a file with this name did not exist when | |
63aa9df0 | 42 | .BR tempnam () |
fea681da MK |
43 | checked. |
44 | The filename suffix of the pathname generated will start with | |
45 | .I pfx | |
46 | in case | |
47 | .I pfx | |
48 | is a non-NULL string of at most five bytes. | |
49 | The directory prefix part of the pathname generated is required to | |
2d986c92 | 50 | be "appropriate" (often that at least implies writable). |
847e0d88 | 51 | .PP |
fea681da | 52 | Attempts to find an appropriate directory go through the following |
c13182ef | 53 | steps: |
0c629015 | 54 | .TP 3 |
c631f73d | 55 | a) |
097585ed MK |
56 | In case the environment variable |
57 | .B TMPDIR | |
58 | exists and | |
fea681da | 59 | contains the name of an appropriate directory, that is used. |
c631f73d MK |
60 | .TP |
61 | b) | |
62 | Otherwise, if the | |
fea681da MK |
63 | .I dir |
64 | argument is non-NULL and appropriate, it is used. | |
c631f73d MK |
65 | .TP |
66 | c) | |
67 | Otherwise, | |
fea681da MK |
68 | .I P_tmpdir |
69 | (as defined in | |
70 | .IR <stdio.h> ) | |
71 | is used when appropriate. | |
c631f73d MK |
72 | .TP |
73 | d) | |
74 | Finally an implementation-defined directory may be used. | |
c13182ef | 75 | .PP |
c631f73d MK |
76 | The string returned by |
77 | .BR tempnam () | |
78 | is allocated using | |
79 | .BR malloc (3) | |
80 | and hence should be freed by | |
81 | .BR free (3). | |
47297adb | 82 | .SH RETURN VALUE |
f528275c | 83 | On success, the |
63aa9df0 | 84 | .BR tempnam () |
52e58375 MK |
85 | function returns a pointer to a unique temporary filename. |
86 | It returns NULL if a unique name cannot be generated, with | |
87 | .I errno | |
855d489a | 88 | set to indicate the error. |
fea681da MK |
89 | .SH ERRORS |
90 | .TP | |
91 | .B ENOMEM | |
92 | Allocation of storage failed. | |
3fdf5198 PH |
93 | .SH ATTRIBUTES |
94 | For an explanation of the terms used in this section, see | |
95 | .BR attributes (7). | |
c466875e MK |
96 | .ad l |
97 | .nh | |
3fdf5198 PH |
98 | .TS |
99 | allbox; | |
c466875e | 100 | lbx lb lb |
3fdf5198 PH |
101 | l l l. |
102 | Interface Attribute Value | |
103 | T{ | |
104 | .BR tempnam () | |
105 | T} Thread safety MT-Safe env | |
106 | .TE | |
c466875e MK |
107 | .hy |
108 | .ad | |
109 | .sp 1 | |
3113c7f3 | 110 | .SH STANDARDS |
44a2c328 | 111 | SVr4, 4.3BSD, POSIX.1-2001. |
d458f965 MK |
112 | POSIX.1-2008 marks |
113 | .BR tempnam () | |
114 | as obsolete. | |
fea681da | 115 | .SH NOTES |
c13182ef | 116 | Although |
2777b1ca | 117 | .BR tempnam () |
c631f73d MK |
118 | generates names that are difficult to guess, |
119 | it is nevertheless possible that between the time that | |
2777b1ca | 120 | .BR tempnam () |
c631f73d MK |
121 | returns a pathname, and the time that the program opens it, |
122 | another program might create that pathname using | |
c13182ef | 123 | .BR open (2), |
c631f73d MK |
124 | or create it as a symbolic link. |
125 | This can lead to security holes. | |
c13182ef | 126 | To avoid such possibilities, use the |
c631f73d MK |
127 | .BR open (2) |
128 | .B O_EXCL | |
c13182ef MK |
129 | flag to open the pathname. |
130 | Or better yet, use | |
c631f73d MK |
131 | .BR mkstemp (3) |
132 | or | |
133 | .BR tmpfile (3). | |
847e0d88 | 134 | .PP |
097585ed MK |
135 | SUSv2 does not mention the use of |
136 | .BR TMPDIR ; | |
137 | glibc will use it only | |
880f5b4b | 138 | when the program is not set-user-ID. |
68e1685c | 139 | On SVr4, the directory used under \fBd)\fP is |
0daa9e92 | 140 | .I /tmp |
c631f73d | 141 | (and this is what glibc does). |
dd3568a1 | 142 | .PP |
c631f73d | 143 | Because it dynamically allocates memory used to return the pathname, |
4733f53c | 144 | .BR tempnam () |
c631f73d MK |
145 | is reentrant, and thus thread safe, unlike |
146 | .BR tmpnam (3). | |
dd3568a1 | 147 | .PP |
fea681da | 148 | The |
63aa9df0 | 149 | .BR tempnam () |
fea681da | 150 | function generates a different string each time it is called, |
097585ed MK |
151 | up to |
152 | .B TMP_MAX | |
153 | (defined in | |
fea681da | 154 | .IR <stdio.h> ) |
c13182ef | 155 | times. |
097585ed | 156 | If it is called more than |
0daa9e92 | 157 | .B TMP_MAX |
097585ed | 158 | times, |
d9bfdb9c | 159 | the behavior is implementation defined. |
dd3568a1 | 160 | .PP |
c631f73d MK |
161 | .BR tempnam () |
162 | uses at most the first five bytes from | |
163 | .IR pfx . | |
847e0d88 | 164 | .PP |
7bc7af37 MK |
165 | The glibc implementation of |
166 | .BR tempnam () | |
26cd31fd | 167 | fails with the error |
7bc7af37 MK |
168 | .B EEXIST |
169 | upon failure to find a unique name. | |
fea681da | 170 | .SH BUGS |
ec5a588f | 171 | The precise meaning of "appropriate" is undefined; |
fea681da | 172 | it is unspecified how accessibility of a directory is determined. |
47297adb | 173 | .SH SEE ALSO |
fea681da MK |
174 | .BR mkstemp (3), |
175 | .BR mktemp (3), | |
176 | .BR tmpfile (3), | |
177 | .BR tmpnam (3) |