]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .TH TEMPNAM 3 1999-06-14 "" "Linux Programmer's Manual" | |
24 | .SH NAME | |
25 | tempnam \- create a name for a temporary file | |
26 | .SH SYNOPSIS | |
27 | .nf | |
28 | .B #include <stdio.h> | |
29 | .sp | |
30 | .BI "char *tempnam(const char *" dir ", const char *" pfx ); | |
31 | .fi | |
32 | .SH DESCRIPTION | |
33 | The | |
63aa9df0 | 34 | .BR tempnam () |
fea681da MK |
35 | function returns a pointer to a string that is a valid filename, |
36 | and such that a file with this name did not exist when | |
63aa9df0 | 37 | .BR tempnam () |
fea681da MK |
38 | checked. |
39 | The filename suffix of the pathname generated will start with | |
40 | .I pfx | |
41 | in case | |
42 | .I pfx | |
43 | is a non-NULL string of at most five bytes. | |
44 | The directory prefix part of the pathname generated is required to | |
45 | be `appropriate' (often that at least implies writable). | |
c631f73d | 46 | |
fea681da | 47 | Attempts to find an appropriate directory go through the following |
c13182ef | 48 | steps: |
c631f73d MK |
49 | .TP |
50 | a) | |
51 | In case the environment variable TMPDIR exists and | |
fea681da | 52 | contains the name of an appropriate directory, that is used. |
c631f73d MK |
53 | .TP |
54 | b) | |
55 | Otherwise, if the | |
fea681da MK |
56 | .I dir |
57 | argument is non-NULL and appropriate, it is used. | |
c631f73d MK |
58 | .TP |
59 | c) | |
60 | Otherwise, | |
fea681da MK |
61 | .I P_tmpdir |
62 | (as defined in | |
63 | .IR <stdio.h> ) | |
64 | is used when appropriate. | |
c631f73d MK |
65 | .TP |
66 | d) | |
67 | Finally an implementation-defined directory may be used. | |
c13182ef | 68 | .PP |
c631f73d MK |
69 | The string returned by |
70 | .BR tempnam () | |
71 | is allocated using | |
72 | .BR malloc (3) | |
73 | and hence should be freed by | |
74 | .BR free (3). | |
fea681da MK |
75 | .SH "RETURN VALUE" |
76 | The | |
63aa9df0 | 77 | .BR tempnam () |
c13182ef | 78 | function returns a pointer to a unique temporary |
fea681da MK |
79 | filename, or NULL if a unique name cannot be generated. |
80 | .SH ERRORS | |
81 | .TP | |
82 | .B ENOMEM | |
83 | Allocation of storage failed. | |
fea681da | 84 | .SH NOTES |
c13182ef | 85 | Although |
c631f73d MK |
86 | .BR tempnam (3) |
87 | generates names that are difficult to guess, | |
88 | it is nevertheless possible that between the time that | |
89 | .BR tempnam (3) | |
90 | returns a pathname, and the time that the program opens it, | |
91 | another program might create that pathname using | |
c13182ef | 92 | .BR open (2), |
c631f73d MK |
93 | or create it as a symbolic link. |
94 | This can lead to security holes. | |
c13182ef | 95 | To avoid such possibilities, use the |
c631f73d MK |
96 | .BR open (2) |
97 | .B O_EXCL | |
c13182ef MK |
98 | flag to open the pathname. |
99 | Or better yet, use | |
c631f73d MK |
100 | .BR mkstemp (3) |
101 | or | |
102 | .BR tmpfile (3). | |
103 | ||
fea681da | 104 | SUSv2 does not mention the use of TMPDIR; glibc will use it only |
880f5b4b | 105 | when the program is not set-user-ID. |
68e1685c | 106 | On SVr4, the directory used under \fBd)\fP is |
c13182ef | 107 | .IR /tmp |
c631f73d MK |
108 | (and this is what glibc does). |
109 | .LP | |
110 | Because it dynamically allocates memory used to return the pathname, | |
4733f53c | 111 | .BR tempnam () |
c631f73d MK |
112 | is reentrant, and thus thread safe, unlike |
113 | .BR tmpnam (3). | |
fea681da MK |
114 | .LP |
115 | The | |
63aa9df0 | 116 | .BR tempnam () |
fea681da MK |
117 | function generates a different string each time it is called, |
118 | up to TMP_MAX (defined in | |
119 | .IR <stdio.h> ) | |
c13182ef MK |
120 | times. |
121 | If it is called more than TMP_MAX times, | |
fea681da MK |
122 | the behaviour is implementation defined. |
123 | .LP | |
c631f73d MK |
124 | .BR tempnam () |
125 | uses at most the first five bytes from | |
126 | .IR pfx . | |
7bc7af37 MK |
127 | |
128 | The glibc implementation of | |
129 | .BR tempnam () | |
c13182ef | 130 | will fail with the error |
7bc7af37 MK |
131 | .B EEXIST |
132 | upon failure to find a unique name. | |
fea681da MK |
133 | .SH BUGS |
134 | The precise meaning of `appropriate' is undefined; | |
135 | it is unspecified how accessibility of a directory is determined. | |
c631f73d | 136 | |
c13182ef MK |
137 | Never use this function. |
138 | Use | |
fea681da | 139 | .BR mkstemp (3) |
c631f73d MK |
140 | or |
141 | .BR tmpfile (3) | |
fea681da MK |
142 | instead. |
143 | .SH "CONFORMING TO" | |
68e1685c | 144 | SVr4, 4.3BSD, POSIX.1-2001 |
fea681da MK |
145 | .SH "SEE ALSO" |
146 | .BR mkstemp (3), | |
147 | .BR mktemp (3), | |
148 | .BR tmpfile (3), | |
149 | .BR tmpnam (3) |