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