Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "File::Temp 3" | |
132 | .TH File::Temp 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | File::Temp \- return name and handle of a temporary file safely | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 1 | |
138 | \& use File::Temp qw/ tempfile tempdir /; | |
139 | .Ve | |
140 | .PP | |
141 | .Vb 2 | |
142 | \& $fh = tempfile(); | |
143 | \& ($fh, $filename) = tempfile(); | |
144 | .Ve | |
145 | .PP | |
146 | .Vb 2 | |
147 | \& ($fh, $filename) = tempfile( $template, DIR => $dir); | |
148 | \& ($fh, $filename) = tempfile( $template, SUFFIX => '.dat'); | |
149 | .Ve | |
150 | .PP | |
151 | .Vb 2 | |
152 | \& $dir = tempdir( CLEANUP => 1 ); | |
153 | \& ($fh, $filename) = tempfile( DIR => $dir ); | |
154 | .Ve | |
155 | .PP | |
156 | Object interface: | |
157 | .PP | |
158 | .Vb 2 | |
159 | \& require File::Temp; | |
160 | \& use File::Temp (); | |
161 | .Ve | |
162 | .PP | |
163 | .Vb 2 | |
164 | \& $fh = new File::Temp($template); | |
165 | \& $fname = $fh->filename; | |
166 | .Ve | |
167 | .PP | |
168 | .Vb 3 | |
169 | \& $tmp = new File::Temp( UNLINK => 0, SUFFIX => '.dat' ); | |
170 | \& print $tmp "Some data\en"; | |
171 | \& print "Filename is $tmp\en"; | |
172 | .Ve | |
173 | .PP | |
174 | The following interfaces are provided for compatibility with | |
175 | existing APIs. They should not be used in new code. | |
176 | .PP | |
177 | MkTemp family: | |
178 | .PP | |
179 | .Vb 1 | |
180 | \& use File::Temp qw/ :mktemp /; | |
181 | .Ve | |
182 | .PP | |
183 | .Vb 2 | |
184 | \& ($fh, $file) = mkstemp( "tmpfileXXXXX" ); | |
185 | \& ($fh, $file) = mkstemps( "tmpfileXXXXXX", $suffix); | |
186 | .Ve | |
187 | .PP | |
188 | .Vb 1 | |
189 | \& $tmpdir = mkdtemp( $template ); | |
190 | .Ve | |
191 | .PP | |
192 | .Vb 1 | |
193 | \& $unopened_file = mktemp( $template ); | |
194 | .Ve | |
195 | .PP | |
196 | \&\s-1POSIX\s0 functions: | |
197 | .PP | |
198 | .Vb 1 | |
199 | \& use File::Temp qw/ :POSIX /; | |
200 | .Ve | |
201 | .PP | |
202 | .Vb 2 | |
203 | \& $file = tmpnam(); | |
204 | \& $fh = tmpfile(); | |
205 | .Ve | |
206 | .PP | |
207 | .Vb 1 | |
208 | \& ($fh, $file) = tmpnam(); | |
209 | .Ve | |
210 | .PP | |
211 | Compatibility functions: | |
212 | .PP | |
213 | .Vb 1 | |
214 | \& $unopened_file = File::Temp::tempnam( $dir, $pfx ); | |
215 | .Ve | |
216 | .SH "DESCRIPTION" | |
217 | .IX Header "DESCRIPTION" | |
218 | \&\f(CW\*(C`File::Temp\*(C'\fR can be used to create and open temporary files in a safe | |
219 | way. There is both a function interface and an object-oriented | |
220 | interface. The File::Temp constructor or the \fItempfile()\fR function can | |
221 | be used to return the name and the open filehandle of a temporary | |
222 | file. The \fItempdir()\fR function can be used to create a temporary | |
223 | directory. | |
224 | .PP | |
225 | The security aspect of temporary file creation is emphasized such that | |
226 | a filehandle and filename are returned together. This helps guarantee | |
227 | that a race condition can not occur where the temporary file is | |
228 | created by another process between checking for the existence of the | |
229 | file and its opening. Additional security levels are provided to | |
230 | check, for example, that the sticky bit is set on world writable | |
231 | directories. See \*(L"safe_level\*(R" for more information. | |
232 | .PP | |
233 | For compatibility with popular C library functions, Perl implementations of | |
234 | the \fImkstemp()\fR family of functions are provided. These are, \fImkstemp()\fR, | |
235 | \&\fImkstemps()\fR, \fImkdtemp()\fR and \fImktemp()\fR. | |
236 | .PP | |
237 | Additionally, implementations of the standard \s-1POSIX\s0 | |
238 | \&\fItmpnam()\fR and \fItmpfile()\fR functions are provided if required. | |
239 | .PP | |
240 | Implementations of \fImktemp()\fR, \fItmpnam()\fR, and \fItempnam()\fR are provided, | |
241 | but should be used with caution since they return only a filename | |
242 | that was valid when function was called, so cannot guarantee | |
243 | that the file will not exist by the time the caller opens the filename. | |
244 | .SH "OBJECT-ORIENTED INTERFACE" | |
245 | .IX Header "OBJECT-ORIENTED INTERFACE" | |
246 | This is the primary interface for interacting with | |
247 | \&\f(CW\*(C`File::Temp\*(C'\fR. Using the \s-1OO\s0 interface a temporary file can be created | |
248 | when the object is constructed and the file can be removed when the | |
249 | object is no longer required. | |
250 | .PP | |
251 | Note that there is no method to obtain the filehandle from the | |
252 | \&\f(CW\*(C`File::Temp\*(C'\fR object. The object itself acts as a filehandle. Also, | |
253 | the object is configured such that it stringifies to the name of the | |
254 | temporary file. | |
255 | .IP "\fBnew\fR" 4 | |
256 | .IX Item "new" | |
257 | Create a temporary file object. | |
258 | .Sp | |
259 | .Vb 1 | |
260 | \& my $tmp = new File::Temp(); | |
261 | .Ve | |
262 | .Sp | |
263 | by default the object is constructed as if \f(CW\*(C`tempfile\*(C'\fR | |
264 | was called without options, but with the additional behaviour | |
265 | that the temporary file is removed by the object destructor | |
266 | if \s-1UNLINK\s0 is set to true (the default). | |
267 | .Sp | |
268 | Supported arguments are the same as for \f(CW\*(C`tempfile\*(C'\fR: \s-1UNLINK\s0 | |
269 | (defaulting to true), \s-1DIR\s0 and \s-1SUFFIX\s0. Additionally, the filename | |
270 | template is specified using the \s-1TEMPLATE\s0 option. The \s-1OPEN\s0 option | |
271 | is not supported (the file is always opened). | |
272 | .Sp | |
273 | .Vb 3 | |
274 | \& $tmp = new File::Temp( TEMPLATE => 'tempXXXXX', | |
275 | \& DIR => 'mydir', | |
276 | \& SUFFIX => '.dat'); | |
277 | .Ve | |
278 | .Sp | |
279 | Arguments are case insensitive. | |
280 | .IP "\fBfilename\fR" 4 | |
281 | .IX Item "filename" | |
282 | Return the name of the temporary file associated with this object. | |
283 | .Sp | |
284 | .Vb 1 | |
285 | \& $filename = $tmp->filename; | |
286 | .Ve | |
287 | .Sp | |
288 | This method is called automatically when the object is used as | |
289 | a string. | |
290 | .IP "\fBunlink_on_destroy\fR" 4 | |
291 | .IX Item "unlink_on_destroy" | |
292 | Control whether the file is unlinked when the object goes out of scope. | |
293 | The file is removed if this value is true and \f(CW$KEEP_ALL\fR is not. | |
294 | .Sp | |
295 | .Vb 1 | |
296 | \& $fh->unlink_on_destroy( 1 ); | |
297 | .Ve | |
298 | .Sp | |
299 | Default is for the file to be removed. | |
300 | .IP "\fB\s-1DESTROY\s0\fR" 4 | |
301 | .IX Item "DESTROY" | |
302 | When the object goes out of scope, the destructor is called. This | |
303 | destructor will attempt to unlink the file (using \f(CW\*(C`unlink1\*(C'\fR) | |
304 | if the constructor was called with \s-1UNLINK\s0 set to 1 (the default state | |
305 | if \s-1UNLINK\s0 is not specified). | |
306 | .Sp | |
307 | No error is given if the unlink fails. | |
308 | .Sp | |
309 | If the global variable \f(CW$KEEP_ALL\fR is true, the file will not be removed. | |
310 | .SH "FUNCTIONS" | |
311 | .IX Header "FUNCTIONS" | |
312 | This section describes the recommended interface for generating | |
313 | temporary files and directories. | |
314 | .IP "\fBtempfile\fR" 4 | |
315 | .IX Item "tempfile" | |
316 | This is the basic function to generate temporary files. | |
317 | The behaviour of the file can be changed using various options: | |
318 | .Sp | |
319 | .Vb 2 | |
320 | \& $fh = tempfile(); | |
321 | \& ($fh, $filename) = tempfile(); | |
322 | .Ve | |
323 | .Sp | |
324 | Create a temporary file in the directory specified for temporary | |
325 | files, as specified by the \fItmpdir()\fR function in File::Spec. | |
326 | .Sp | |
327 | .Vb 1 | |
328 | \& ($fh, $filename) = tempfile($template); | |
329 | .Ve | |
330 | .Sp | |
331 | Create a temporary file in the current directory using the supplied | |
332 | template. Trailing `X' characters are replaced with random letters to | |
333 | generate the filename. At least four `X' characters must be present | |
334 | at the end of the template. | |
335 | .Sp | |
336 | .Vb 1 | |
337 | \& ($fh, $filename) = tempfile($template, SUFFIX => $suffix) | |
338 | .Ve | |
339 | .Sp | |
340 | Same as previously, except that a suffix is added to the template | |
341 | after the `X' translation. Useful for ensuring that a temporary | |
342 | filename has a particular extension when needed by other applications. | |
343 | But see the \s-1WARNING\s0 at the end. | |
344 | .Sp | |
345 | .Vb 1 | |
346 | \& ($fh, $filename) = tempfile($template, DIR => $dir); | |
347 | .Ve | |
348 | .Sp | |
349 | Translates the template as before except that a directory name | |
350 | is specified. | |
351 | .Sp | |
352 | .Vb 1 | |
353 | \& ($fh, $filename) = tempfile($template, UNLINK => 1); | |
354 | .Ve | |
355 | .Sp | |
356 | Return the filename and filehandle as before except that the file is | |
357 | automatically removed when the program exits (dependent on | |
358 | \&\f(CW$KEEP_ALL\fR). Default is for the file to be removed if a file handle is | |
359 | requested and to be kept if the filename is requested. In a scalar | |
360 | context (where no filename is returned) the file is always deleted | |
361 | either (depending on the operating system) on exit or when it is | |
362 | closed (unless \f(CW$KEEP_ALL\fR is true when the temp file is created). | |
363 | .Sp | |
364 | Use the object-oriented interface if fine-grained control of when | |
365 | a file is removed is required. | |
366 | .Sp | |
367 | If the template is not specified, a template is always | |
368 | automatically generated. This temporary file is placed in \fItmpdir()\fR | |
369 | (File::Spec) unless a directory is specified explicitly with the | |
370 | \&\s-1DIR\s0 option. | |
371 | .Sp | |
372 | .Vb 1 | |
373 | \& $fh = tempfile( $template, DIR => $dir ); | |
374 | .Ve | |
375 | .Sp | |
376 | If called in scalar context, only the filehandle is returned and the | |
377 | file will automatically be deleted when closed on operating systems | |
378 | that support this (see the description of \fItmpfile()\fR elsewhere in this | |
379 | document). This is the preferred mode of operation, as if you only | |
380 | have a filehandle, you can never create a race condition by fumbling | |
381 | with the filename. On systems that can not unlink an open file or can | |
382 | not mark a file as temporary when it is opened (for example, Windows | |
383 | \&\s-1NT\s0 uses the \f(CW\*(C`O_TEMPORARY\*(C'\fR flag) the file is marked for deletion when | |
384 | the program ends (equivalent to setting \s-1UNLINK\s0 to 1). The \f(CW\*(C`UNLINK\*(C'\fR | |
385 | flag is ignored if present. | |
386 | .Sp | |
387 | .Vb 1 | |
388 | \& (undef, $filename) = tempfile($template, OPEN => 0); | |
389 | .Ve | |
390 | .Sp | |
391 | This will return the filename based on the template but | |
392 | will not open this file. Cannot be used in conjunction with | |
393 | \&\s-1UNLINK\s0 set to true. Default is to always open the file | |
394 | to protect from possible race conditions. A warning is issued | |
395 | if warnings are turned on. Consider using the \fItmpnam()\fR | |
396 | and \fImktemp()\fR functions described elsewhere in this document | |
397 | if opening the file is not required. | |
398 | .Sp | |
399 | Options can be combined as required. | |
400 | .IP "\fBtempdir\fR" 4 | |
401 | .IX Item "tempdir" | |
402 | This is the recommended interface for creation of temporary directories. | |
403 | The behaviour of the function depends on the arguments: | |
404 | .Sp | |
405 | .Vb 1 | |
406 | \& $tempdir = tempdir(); | |
407 | .Ve | |
408 | .Sp | |
409 | Create a directory in \fItmpdir()\fR (see File::Spec). | |
410 | .Sp | |
411 | .Vb 1 | |
412 | \& $tempdir = tempdir( $template ); | |
413 | .Ve | |
414 | .Sp | |
415 | Create a directory from the supplied template. This template is | |
416 | similar to that described for \fItempfile()\fR. `X' characters at the end | |
417 | of the template are replaced with random letters to construct the | |
418 | directory name. At least four `X' characters must be in the template. | |
419 | .Sp | |
420 | .Vb 1 | |
421 | \& $tempdir = tempdir ( DIR => $dir ); | |
422 | .Ve | |
423 | .Sp | |
424 | Specifies the directory to use for the temporary directory. | |
425 | The temporary directory name is derived from an internal template. | |
426 | .Sp | |
427 | .Vb 1 | |
428 | \& $tempdir = tempdir ( $template, DIR => $dir ); | |
429 | .Ve | |
430 | .Sp | |
431 | Prepend the supplied directory name to the template. The template | |
432 | should not include parent directory specifications itself. Any parent | |
433 | directory specifications are removed from the template before | |
434 | prepending the supplied directory. | |
435 | .Sp | |
436 | .Vb 1 | |
437 | \& $tempdir = tempdir ( $template, TMPDIR => 1 ); | |
438 | .Ve | |
439 | .Sp | |
440 | Using the supplied template, create the temporary directory in | |
441 | a standard location for temporary files. Equivalent to doing | |
442 | .Sp | |
443 | .Vb 1 | |
444 | \& $tempdir = tempdir ( $template, DIR => File::Spec->tmpdir); | |
445 | .Ve | |
446 | .Sp | |
447 | but shorter. Parent directory specifications are stripped from the | |
448 | template itself. The \f(CW\*(C`TMPDIR\*(C'\fR option is ignored if \f(CW\*(C`DIR\*(C'\fR is set | |
449 | explicitly. Additionally, \f(CW\*(C`TMPDIR\*(C'\fR is implied if neither a template | |
450 | nor a directory are supplied. | |
451 | .Sp | |
452 | .Vb 1 | |
453 | \& $tempdir = tempdir( $template, CLEANUP => 1); | |
454 | .Ve | |
455 | .Sp | |
456 | Create a temporary directory using the supplied template, but | |
457 | attempt to remove it (and all files inside it) when the program | |
458 | exits. Note that an attempt will be made to remove all files from | |
459 | the directory even if they were not created by this module (otherwise | |
460 | why ask to clean it up?). The directory removal is made with | |
461 | the \fIrmtree()\fR function from the File::Path module. | |
462 | Of course, if the template is not specified, the temporary directory | |
463 | will be created in \fItmpdir()\fR and will also be removed at program exit. | |
464 | .SH "MKTEMP FUNCTIONS" | |
465 | .IX Header "MKTEMP FUNCTIONS" | |
466 | The following functions are Perl implementations of the | |
467 | \&\fImktemp()\fR family of temp file generation system calls. | |
468 | .IP "\fBmkstemp\fR" 4 | |
469 | .IX Item "mkstemp" | |
470 | Given a template, returns a filehandle to the temporary file and the name | |
471 | of the file. | |
472 | .Sp | |
473 | .Vb 1 | |
474 | \& ($fh, $name) = mkstemp( $template ); | |
475 | .Ve | |
476 | .Sp | |
477 | In scalar context, just the filehandle is returned. | |
478 | .Sp | |
479 | The template may be any filename with some number of X's appended | |
480 | to it, for example \fI/tmp/temp.XXXX\fR. The trailing X's are replaced | |
481 | with unique alphanumeric combinations. | |
482 | .IP "\fBmkstemps\fR" 4 | |
483 | .IX Item "mkstemps" | |
484 | Similar to \fImkstemp()\fR, except that an extra argument can be supplied | |
485 | with a suffix to be appended to the template. | |
486 | .Sp | |
487 | .Vb 1 | |
488 | \& ($fh, $name) = mkstemps( $template, $suffix ); | |
489 | .Ve | |
490 | .Sp | |
491 | For example a template of \f(CW\*(C`testXXXXXX\*(C'\fR and suffix of \f(CW\*(C`.dat\*(C'\fR | |
492 | would generate a file similar to \fItesthGji_w.dat\fR. | |
493 | .Sp | |
494 | Returns just the filehandle alone when called in scalar context. | |
495 | .IP "\fBmkdtemp\fR" 4 | |
496 | .IX Item "mkdtemp" | |
497 | Create a directory from a template. The template must end in | |
498 | X's that are replaced by the routine. | |
499 | .Sp | |
500 | .Vb 1 | |
501 | \& $tmpdir_name = mkdtemp($template); | |
502 | .Ve | |
503 | .Sp | |
504 | Returns the name of the temporary directory created. | |
505 | Returns undef on failure. | |
506 | .Sp | |
507 | Directory must be removed by the caller. | |
508 | .IP "\fBmktemp\fR" 4 | |
509 | .IX Item "mktemp" | |
510 | Returns a valid temporary filename but does not guarantee | |
511 | that the file will not be opened by someone else. | |
512 | .Sp | |
513 | .Vb 1 | |
514 | \& $unopened_file = mktemp($template); | |
515 | .Ve | |
516 | .Sp | |
517 | Template is the same as that required by \fImkstemp()\fR. | |
518 | .SH "POSIX FUNCTIONS" | |
519 | .IX Header "POSIX FUNCTIONS" | |
520 | This section describes the re-implementation of the \fItmpnam()\fR | |
521 | and \fItmpfile()\fR functions described in \s-1POSIX\s0 | |
522 | using the \fImkstemp()\fR from this module. | |
523 | .PP | |
524 | Unlike the \s-1POSIX\s0 implementations, the directory used | |
525 | for the temporary file is not specified in a system include | |
526 | file (\f(CW\*(C`P_tmpdir\*(C'\fR) but simply depends on the choice of \fItmpdir()\fR | |
527 | returned by File::Spec. On some implementations this | |
528 | location can be set using the \f(CW\*(C`TMPDIR\*(C'\fR environment variable, which | |
529 | may not be secure. | |
530 | If this is a problem, simply use \fImkstemp()\fR and specify a template. | |
531 | .IP "\fBtmpnam\fR" 4 | |
532 | .IX Item "tmpnam" | |
533 | When called in scalar context, returns the full name (including path) | |
534 | of a temporary file (uses \fImktemp()\fR). The only check is that the file does | |
535 | not already exist, but there is no guarantee that that condition will | |
536 | continue to apply. | |
537 | .Sp | |
538 | .Vb 1 | |
539 | \& $file = tmpnam(); | |
540 | .Ve | |
541 | .Sp | |
542 | When called in list context, a filehandle to the open file and | |
543 | a filename are returned. This is achieved by calling \fImkstemp()\fR | |
544 | after constructing a suitable template. | |
545 | .Sp | |
546 | .Vb 1 | |
547 | \& ($fh, $file) = tmpnam(); | |
548 | .Ve | |
549 | .Sp | |
550 | If possible, this form should be used to prevent possible | |
551 | race conditions. | |
552 | .Sp | |
553 | See \*(L"tmpdir\*(R" in File::Spec for information on the choice of temporary | |
554 | directory for a particular operating system. | |
555 | .IP "\fBtmpfile\fR" 4 | |
556 | .IX Item "tmpfile" | |
557 | Returns the filehandle of a temporary file. | |
558 | .Sp | |
559 | .Vb 1 | |
560 | \& $fh = tmpfile(); | |
561 | .Ve | |
562 | .Sp | |
563 | The file is removed when the filehandle is closed or when the program | |
564 | exits. No access to the filename is provided. | |
565 | .Sp | |
566 | If the temporary file can not be created undef is returned. | |
567 | Currently this command will probably not work when the temporary | |
568 | directory is on an \s-1NFS\s0 file system. | |
569 | .SH "ADDITIONAL FUNCTIONS" | |
570 | .IX Header "ADDITIONAL FUNCTIONS" | |
571 | These functions are provided for backwards compatibility | |
572 | with common tempfile generation C library functions. | |
573 | .PP | |
574 | They are not exported and must be addressed using the full package | |
575 | name. | |
576 | .IP "\fBtempnam\fR" 4 | |
577 | .IX Item "tempnam" | |
578 | Return the name of a temporary file in the specified directory | |
579 | using a prefix. The file is guaranteed not to exist at the time | |
580 | the function was called, but such guarantees are good for one | |
581 | clock tick only. Always use the proper form of \f(CW\*(C`sysopen\*(C'\fR | |
582 | with \f(CW\*(C`O_CREAT | O_EXCL\*(C'\fR if you must open such a filename. | |
583 | .Sp | |
584 | .Vb 1 | |
585 | \& $filename = File::Temp::tempnam( $dir, $prefix ); | |
586 | .Ve | |
587 | .Sp | |
588 | Equivalent to running \fImktemp()\fR with \f(CW$dir\fR/$prefixXXXXXXXX | |
589 | (using unix file convention as an example) | |
590 | .Sp | |
591 | Because this function uses \fImktemp()\fR, it can suffer from race conditions. | |
592 | .SH "UTILITY FUNCTIONS" | |
593 | .IX Header "UTILITY FUNCTIONS" | |
594 | Useful functions for dealing with the filehandle and filename. | |
595 | .IP "\fBunlink0\fR" 4 | |
596 | .IX Item "unlink0" | |
597 | Given an open filehandle and the associated filename, make a safe | |
598 | unlink. This is achieved by first checking that the filename and | |
599 | filehandle initially point to the same file and that the number of | |
600 | links to the file is 1 (all fields returned by \fIstat()\fR are compared). | |
601 | Then the filename is unlinked and the filehandle checked once again to | |
602 | verify that the number of links on that file is now 0. This is the | |
603 | closest you can come to making sure that the filename unlinked was the | |
604 | same as the file whose descriptor you hold. | |
605 | .Sp | |
606 | .Vb 2 | |
607 | \& unlink0($fh, $path) | |
608 | \& or die "Error unlinking file $path safely"; | |
609 | .Ve | |
610 | .Sp | |
611 | Returns false on error. The filehandle is not closed since on some | |
612 | occasions this is not required. | |
613 | .Sp | |
614 | On some platforms, for example Windows \s-1NT\s0, it is not possible to | |
615 | unlink an open file (the file must be closed first). On those | |
616 | platforms, the actual unlinking is deferred until the program ends and | |
617 | good status is returned. A check is still performed to make sure that | |
618 | the filehandle and filename are pointing to the same thing (but not at | |
619 | the time the end block is executed since the deferred removal may not | |
620 | have access to the filehandle). | |
621 | .Sp | |
622 | Additionally, on Windows \s-1NT\s0 not all the fields returned by \fIstat()\fR can | |
623 | be compared. For example, the \f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`rdev\*(C'\fR fields seem to be | |
624 | different. Also, it seems that the size of the file returned by \fIstat()\fR | |
625 | does not always agree, with \f(CW\*(C`stat(FH)\*(C'\fR being more accurate than | |
626 | \&\f(CW\*(C`stat(filename)\*(C'\fR, presumably because of caching issues even when | |
627 | using autoflush (this is usually overcome by waiting a while after | |
628 | writing to the tempfile before attempting to \f(CW\*(C`unlink0\*(C'\fR it). | |
629 | .Sp | |
630 | Finally, on \s-1NFS\s0 file systems the link count of the file handle does | |
631 | not always go to zero immediately after unlinking. Currently, this | |
632 | command is expected to fail on \s-1NFS\s0 disks. | |
633 | .Sp | |
634 | This function is disabled if the global variable \f(CW$KEEP_ALL\fR is true | |
635 | and an unlink on open file is supported. If the unlink is to be deferred | |
636 | to the \s-1END\s0 block, the file is still registered for removal. | |
637 | .IP "\fBcmpstat\fR" 4 | |
638 | .IX Item "cmpstat" | |
639 | Compare \f(CW\*(C`stat\*(C'\fR of filehandle with \f(CW\*(C`stat\*(C'\fR of provided filename. This | |
640 | can be used to check that the filename and filehandle initially point | |
641 | to the same file and that the number of links to the file is 1 (all | |
642 | fields returned by \fIstat()\fR are compared). | |
643 | .Sp | |
644 | .Vb 2 | |
645 | \& cmpstat($fh, $path) | |
646 | \& or die "Error comparing handle with file"; | |
647 | .Ve | |
648 | .Sp | |
649 | Returns false if the stat information differs or if the link count is | |
650 | greater than 1. | |
651 | .Sp | |
652 | On certain platofms, eg Windows, not all the fields returned by \fIstat()\fR | |
653 | can be compared. For example, the \f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`rdev\*(C'\fR fields seem to be | |
654 | different in Windows. Also, it seems that the size of the file | |
655 | returned by \fIstat()\fR does not always agree, with \f(CW\*(C`stat(FH)\*(C'\fR being more | |
656 | accurate than \f(CW\*(C`stat(filename)\*(C'\fR, presumably because of caching issues | |
657 | even when using autoflush (this is usually overcome by waiting a while | |
658 | after writing to the tempfile before attempting to \f(CW\*(C`unlink0\*(C'\fR it). | |
659 | .Sp | |
660 | Not exported by default. | |
661 | .IP "\fBunlink1\fR" 4 | |
662 | .IX Item "unlink1" | |
663 | Similar to \f(CW\*(C`unlink0\*(C'\fR except after file comparison using cmpstat, the | |
664 | filehandle is closed prior to attempting to unlink the file. This | |
665 | allows the file to be removed without using an \s-1END\s0 block, but does | |
666 | mean that the post-unlink comparison of the filehandle state provided | |
667 | by \f(CW\*(C`unlink0\*(C'\fR is not available. | |
668 | .Sp | |
669 | .Vb 2 | |
670 | \& unlink1($fh, $path) | |
671 | \& or die "Error closing and unlinking file"; | |
672 | .Ve | |
673 | .Sp | |
674 | Usually called from the object destructor when using the \s-1OO\s0 interface. | |
675 | .Sp | |
676 | Not exported by default. | |
677 | .Sp | |
678 | This function is disabled if the global variable \f(CW$KEEP_ALL\fR is true. | |
679 | .IP "\fBcleanup\fR" 4 | |
680 | .IX Item "cleanup" | |
681 | Calling this function will cause any temp files or temp directories | |
682 | that are registered for removal to be removed. This happens automatically | |
683 | when the process exits but can be triggered manually if the caller is sure | |
684 | that none of the temp files are required. This method can be registered as | |
685 | an Apache callback. | |
686 | .Sp | |
687 | On OSes where temp files are automatically removed when the temp file | |
688 | is closed, calling this function will have no effect other than to remove | |
689 | temporary directories (which may include temporary files). | |
690 | .Sp | |
691 | .Vb 1 | |
692 | \& File::Temp::cleanup(); | |
693 | .Ve | |
694 | .Sp | |
695 | Not exported by default. | |
696 | .SH "PACKAGE VARIABLES" | |
697 | .IX Header "PACKAGE VARIABLES" | |
698 | These functions control the global state of the package. | |
699 | .IP "\fBsafe_level\fR" 4 | |
700 | .IX Item "safe_level" | |
701 | Controls the lengths to which the module will go to check the safety of the | |
702 | temporary file or directory before proceeding. | |
703 | Options are: | |
704 | .RS 4 | |
705 | .IP "\s-1STANDARD\s0" 8 | |
706 | .IX Item "STANDARD" | |
707 | Do the basic security measures to ensure the directory exists and | |
708 | is writable, that the \fIumask()\fR is fixed before opening of the file, | |
709 | that temporary files are opened only if they do not already exist, and | |
710 | that possible race conditions are avoided. Finally the unlink0 | |
711 | function is used to remove files safely. | |
712 | .IP "\s-1MEDIUM\s0" 8 | |
713 | .IX Item "MEDIUM" | |
714 | In addition to the \s-1STANDARD\s0 security, the output directory is checked | |
715 | to make sure that it is owned either by root or the user running the | |
716 | program. If the directory is writable by group or by other, it is then | |
717 | checked to make sure that the sticky bit is set. | |
718 | .Sp | |
719 | Will not work on platforms that do not support the \f(CW\*(C`\-k\*(C'\fR test | |
720 | for sticky bit. | |
721 | .IP "\s-1HIGH\s0" 8 | |
722 | .IX Item "HIGH" | |
723 | In addition to the \s-1MEDIUM\s0 security checks, also check for the | |
724 | possibility of ``\fIchown()\fR giveaway'' using the \s-1POSIX\s0 | |
725 | \&\fIsysconf()\fR function. If this is a possibility, each directory in the | |
726 | path is checked in turn for safeness, recursively walking back to the | |
727 | root directory. | |
728 | .Sp | |
729 | For platforms that do not support the \s-1POSIX\s0 | |
730 | \&\f(CW\*(C`_PC_CHOWN_RESTRICTED\*(C'\fR symbol (for example, Windows \s-1NT\s0) it is | |
731 | assumed that ``\fIchown()\fR giveaway'' is possible and the recursive test | |
732 | is performed. | |
733 | .RE | |
734 | .RS 4 | |
735 | .Sp | |
736 | The level can be changed as follows: | |
737 | .Sp | |
738 | .Vb 1 | |
739 | \& File::Temp->safe_level( File::Temp::HIGH ); | |
740 | .Ve | |
741 | .Sp | |
742 | The level constants are not exported by the module. | |
743 | .Sp | |
744 | Currently, you must be running at least perl v5.6.0 in order to | |
745 | run with \s-1MEDIUM\s0 or \s-1HIGH\s0 security. This is simply because the | |
746 | safety tests use functions from Fcntl that are not | |
747 | available in older versions of perl. The problem is that the version | |
748 | number for Fcntl is the same in perl 5.6.0 and in 5.005_03 even though | |
749 | they are different versions. | |
750 | .Sp | |
751 | On systems that do not support the \s-1HIGH\s0 or \s-1MEDIUM\s0 safety levels | |
752 | (for example Win \s-1NT\s0 or \s-1OS/2\s0) any attempt to change the level will | |
753 | be ignored. The decision to ignore rather than raise an exception | |
754 | allows portable programs to be written with high security in mind | |
755 | for the systems that can support this without those programs failing | |
756 | on systems where the extra tests are irrelevant. | |
757 | .Sp | |
758 | If you really need to see whether the change has been accepted | |
759 | simply examine the return value of \f(CW\*(C`safe_level\*(C'\fR. | |
760 | .Sp | |
761 | .Vb 3 | |
762 | \& $newlevel = File::Temp->safe_level( File::Temp::HIGH ); | |
763 | \& die "Could not change to high security" | |
764 | \& if $newlevel != File::Temp::HIGH; | |
765 | .Ve | |
766 | .RE | |
767 | .IP "TopSystemUID" 4 | |
768 | .IX Item "TopSystemUID" | |
769 | This is the highest \s-1UID\s0 on the current system that refers to a root | |
770 | \&\s-1UID\s0. This is used to make sure that the temporary directory is | |
771 | owned by a system \s-1UID\s0 (\f(CW\*(C`root\*(C'\fR, \f(CW\*(C`bin\*(C'\fR, \f(CW\*(C`sys\*(C'\fR etc) rather than | |
772 | simply by root. | |
773 | .Sp | |
774 | This is required since on many unix systems \f(CW\*(C`/tmp\*(C'\fR is not owned | |
775 | by root. | |
776 | .Sp | |
777 | Default is to assume that any \s-1UID\s0 less than or equal to 10 is a root | |
778 | \&\s-1UID\s0. | |
779 | .Sp | |
780 | .Vb 2 | |
781 | \& File::Temp->top_system_uid(10); | |
782 | \& my $topid = File::Temp->top_system_uid; | |
783 | .Ve | |
784 | .Sp | |
785 | This value can be adjusted to reduce security checking if required. | |
786 | The value is only relevant when \f(CW\*(C`safe_level\*(C'\fR is set to \s-1MEDIUM\s0 or higher. | |
787 | .IP "\fB$KEEP_ALL\fR" 4 | |
788 | .IX Item "$KEEP_ALL" | |
789 | Controls whether temporary files and directories should be retained | |
790 | regardless of any instructions in the program to remove them | |
791 | automatically. This is useful for debugging but should not be used in | |
792 | production code. | |
793 | .Sp | |
794 | .Vb 1 | |
795 | \& $File::Temp::KEEP_ALL = 1; | |
796 | .Ve | |
797 | .Sp | |
798 | Default is for files to be removed as requested by the caller. | |
799 | .Sp | |
800 | In some cases, files will only be retained if this variable is true | |
801 | when the file is created. This means that you can not create a temporary | |
802 | file, set this variable and expect the temp file to still be around | |
803 | when the program exits. | |
804 | .IP "\fB$DEBUG\fR" 4 | |
805 | .IX Item "$DEBUG" | |
806 | Controls whether debugging messages should be enabled. | |
807 | .Sp | |
808 | .Vb 1 | |
809 | \& $File::Temp::DEBUG = 1; | |
810 | .Ve | |
811 | .Sp | |
812 | Default is for debugging mode to be disabled. | |
813 | .SH "WARNING" | |
814 | .IX Header "WARNING" | |
815 | For maximum security, endeavour always to avoid ever looking at, | |
816 | touching, or even imputing the existence of the filename. You do not | |
817 | know that that filename is connected to the same file as the handle | |
818 | you have, and attempts to check this can only trigger more race | |
819 | conditions. It's far more secure to use the filehandle alone and | |
820 | dispense with the filename altogether. | |
821 | .PP | |
822 | If you need to pass the handle to something that expects a filename | |
823 | then, on a unix system, use \f(CW\*(C`"/dev/fd/" . fileno($fh)\*(C'\fR for arbitrary | |
824 | programs, or more generally \f(CW\*(C`"+<=&" . fileno($fh)\*(C'\fR for Perl | |
825 | programs. You will have to clear the close-on-exec bit on that file | |
826 | descriptor before passing it to another process. | |
827 | .PP | |
828 | .Vb 3 | |
829 | \& use Fcntl qw/F_SETFD F_GETFD/; | |
830 | \& fcntl($tmpfh, F_SETFD, 0) | |
831 | \& or die "Can't clear close-on-exec flag on temp fh: $!\en"; | |
832 | .Ve | |
833 | .Sh "Temporary files and \s-1NFS\s0" | |
834 | .IX Subsection "Temporary files and NFS" | |
835 | Some problems are associated with using temporary files that reside | |
836 | on \s-1NFS\s0 file systems and it is recommended that a local filesystem | |
837 | is used whenever possible. Some of the security tests will most probably | |
838 | fail when the temp file is not local. Additionally, be aware that | |
839 | the performance of I/O operations over \s-1NFS\s0 will not be as good as for | |
840 | a local disk. | |
841 | .Sh "Forking" | |
842 | .IX Subsection "Forking" | |
843 | In some cases files created by File::Temp are removed from within an | |
844 | \&\s-1END\s0 block. Since \s-1END\s0 blocks are triggered when a child process exits | |
845 | (unless \f(CW\*(C`POSIX::_exit()\*(C'\fR is used by the child) File::Temp takes care | |
846 | to only remove those temp files created by a particular process \s-1ID\s0. This | |
847 | means that a child will not attempt to remove temp files created by the | |
848 | parent process. | |
849 | .Sh "\s-1BINMODE\s0" | |
850 | .IX Subsection "BINMODE" | |
851 | The file returned by File::Temp will have been opened in binary mode | |
852 | if such a mode is available. If that is not correct, use the \fIbinmode()\fR | |
853 | function to change the mode of the filehandle. | |
854 | .SH "HISTORY" | |
855 | .IX Header "HISTORY" | |
856 | Originally began life in May 1999 as an \s-1XS\s0 interface to the system | |
857 | \&\fImkstemp()\fR function. In March 2000, the OpenBSD \fImkstemp()\fR code was | |
858 | translated to Perl for total control of the code's | |
859 | security checking, to ensure the presence of the function regardless of | |
860 | operating system and to help with portability. The module was shipped | |
861 | as a standard part of perl from v5.6.1. | |
862 | .SH "SEE ALSO" | |
863 | .IX Header "SEE ALSO" | |
864 | \&\*(L"tmpnam\*(R" in \s-1POSIX\s0, \*(L"tmpfile\*(R" in \s-1POSIX\s0, File::Spec, File::Path | |
865 | .PP | |
866 | See IO::File and File::MkTemp, Apachae::TempFile for | |
867 | different implementations of temporary file handling. | |
868 | .SH "AUTHOR" | |
869 | .IX Header "AUTHOR" | |
870 | Tim Jenness <tjenness@cpan.org> | |
871 | .PP | |
872 | Copyright (C) 1999\-2005 Tim Jenness and the \s-1UK\s0 Particle Physics and | |
873 | Astronomy Research Council. All Rights Reserved. This program is free | |
874 | software; you can redistribute it and/or modify it under the same | |
875 | terms as Perl itself. | |
876 | .PP | |
877 | Original Perl implementation loosely based on the OpenBSD C code for | |
878 | \&\fImkstemp()\fR. Thanks to Tom Christiansen for suggesting that this module | |
879 | should be written and providing ideas for code improvements and | |
880 | security enhancements. |