Debian Codegraph @

upstream/debian-unstable/man3/tempnam.3

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