Debian Codegraph @

upstream/debian-unstable/man3/File::Temp.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "File::Temp 3perl"
58 .TH File::Temp 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 File::Temp \- return name and handle of a temporary file safely
65 .SH VERSION
66 .IX Header "VERSION"
67 version 0.2311
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use File::Temp qw/ tempfile tempdir /;
72 \&
73 \& $fh = tempfile();
74 \& ($fh, $filename) = tempfile();
75 \&
76 \& ($fh, $filename) = tempfile( $template, DIR => $dir);
77 \& ($fh, $filename) = tempfile( $template, SUFFIX => \*(Aq.dat\*(Aq);
78 \& ($fh, $filename) = tempfile( $template, TMPDIR => 1 );
79 \&
80 \& binmode( $fh, ":utf8" );
81 \&
82 \& $dir = tempdir( CLEANUP => 1 );
83 \& ($fh, $filename) = tempfile( DIR => $dir );
84 .Ve
85 .PP
86 Object interface:
87 .PP
88 .Vb 3
89 \& require File::Temp;
90 \& use File::Temp ();
91 \& use File::Temp qw/ :seekable /;
92 \&
93 \& $fh = File::Temp\->new();
94 \& $fname = $fh\->filename;
95 \&
96 \& $fh = File::Temp\->new(TEMPLATE => $template);
97 \& $fname = $fh\->filename;
98 \&
99 \& $tmp = File::Temp\->new( UNLINK => 0, SUFFIX => \*(Aq.dat\*(Aq );
100 \& print $tmp "Some data\en";
101 \& print "Filename is $tmp\en";
102 \& $tmp\->seek( 0, SEEK_END );
103 \&
104 \& $dir = File::Temp\->newdir(); # CLEANUP => 1 by default
105 .Ve
106 .PP
107 The following interfaces are provided for compatibility with
108 existing APIs. They should not be used in new code.
109 .PP
110 MkTemp family:
111 .PP
112 .Vb 1
113 \& use File::Temp qw/ :mktemp /;
114 \&
115 \& ($fh, $file) = mkstemp( "tmpfileXXXXX" );
116 \& ($fh, $file) = mkstemps( "tmpfileXXXXXX", $suffix);
117 \&
118 \& $tmpdir = mkdtemp( $template );
119 \&
120 \& $unopened_file = mktemp( $template );
121 .Ve
122 .PP
123 POSIX functions:
124 .PP
125 .Vb 1
126 \& use File::Temp qw/ :POSIX /;
127 \&
128 \& $file = tmpnam();
129 \& $fh = tmpfile();
130 \&
131 \& ($fh, $file) = tmpnam();
132 .Ve
133 .PP
134 Compatibility functions:
135 .PP
136 .Vb 1
137 \& $unopened_file = File::Temp::tempnam( $dir, $pfx );
138 .Ve
139 .SH DESCRIPTION
140 .IX Header "DESCRIPTION"
141 \&\f(CW\*(C`File::Temp\*(C'\fR can be used to create and open temporary files in a safe
142 way. There is both a function interface and an object-oriented
143 interface. The File::Temp constructor or the \fBtempfile()\fR function can
144 be used to return the name and the open filehandle of a temporary
145 file. The \fBtempdir()\fR function can be used to create a temporary
146 directory.
147 .PP
148 The security aspect of temporary file creation is emphasized such that
149 a filehandle and filename are returned together. This helps guarantee
150 that a race condition can not occur where the temporary file is
151 created by another process between checking for the existence of the
152 file and its opening. Additional security levels are provided to
153 check, for example, that the sticky bit is set on world writable
154 directories. See "safe_level" for more information.
155 .PP
156 For compatibility with popular C library functions, Perl implementations of
157 the \fBmkstemp()\fR family of functions are provided. These are, \fBmkstemp()\fR,
158 \&\fBmkstemps()\fR, \fBmkdtemp()\fR and \fBmktemp()\fR.
159 .PP
160 Additionally, implementations of the standard POSIX
161 \&\fBtmpnam()\fR and \fBtmpfile()\fR functions are provided if required.
162 .PP
163 Implementations of \fBmktemp()\fR, \fBtmpnam()\fR, and \fBtempnam()\fR are provided,
164 but should be used with caution since they return only a filename
165 that was valid when function was called, so cannot guarantee
166 that the file will not exist by the time the caller opens the filename.
167 .PP
168 Filehandles returned by these functions support the seekable methods.
169 .SH "OBJECT-ORIENTED INTERFACE"
170 .IX Header "OBJECT-ORIENTED INTERFACE"
171 This is the primary interface for interacting with
172 \&\f(CW\*(C`File::Temp\*(C'\fR. Using the OO interface a temporary file can be created
173 when the object is constructed and the file can be removed when the
174 object is no longer required.
175 .PP
176 Note that there is no method to obtain the filehandle from the
177 \&\f(CW\*(C`File::Temp\*(C'\fR object. The object itself acts as a filehandle. The object
178 isa \f(CW\*(C`IO::Handle\*(C'\fR and isa \f(CW\*(C`IO::Seekable\*(C'\fR so all those methods are
179 available.
180 .PP
181 Also, the object is configured such that it stringifies to the name of the
182 temporary file and so can be compared to a filename directly. It numifies
183 to the \f(CW\*(C`refaddr\*(C'\fR the same as other handles and so can be compared to other
184 handles with \f(CW\*(C`==\*(C'\fR.
185 .PP
186 .Vb 2
187 \& $fh eq $filename # as a string
188 \& $fh != \e*STDOUT # as a number
189 .Ve
190 .PP
191 Available since 0.14.
192 .IP \fBnew\fR 4
193 .IX Item "new"
194 Create a temporary file object.
195 .Sp
196 .Vb 1
197 \& my $tmp = File::Temp\->new();
198 .Ve
199 .Sp
200 by default the object is constructed as if \f(CW\*(C`tempfile\*(C'\fR
201 was called without options, but with the additional behaviour
202 that the temporary file is removed by the object destructor
203 if UNLINK is set to true (the default).
204 .Sp
205 Supported arguments are the same as for \f(CW\*(C`tempfile\*(C'\fR: UNLINK
206 (defaulting to true), DIR, EXLOCK, PERMS and SUFFIX.
207 Additionally, the filename
208 template is specified using the TEMPLATE option. The OPEN option
209 is not supported (the file is always opened).
210 .Sp
211 .Vb 3
212 \& $tmp = File::Temp\->new( TEMPLATE => \*(AqtempXXXXX\*(Aq,
213 \& DIR => \*(Aqmydir\*(Aq,
214 \& SUFFIX => \*(Aq.dat\*(Aq);
215 .Ve
216 .Sp
217 Arguments are case insensitive.
218 .Sp
219 Can call \fBcroak()\fR if an error occurs.
220 .Sp
221 Available since 0.14.
222 .Sp
223 TEMPLATE available since 0.23
224 .IP \fBnewdir\fR 4
225 .IX Item "newdir"
226 Create a temporary directory using an object oriented interface.
227 .Sp
228 .Vb 1
229 \& $dir = File::Temp\->newdir();
230 .Ve
231 .Sp
232 By default the directory is deleted when the object goes out of scope.
233 .Sp
234 Supports the same options as the \f(CW\*(C`tempdir\*(C'\fR function. Note that directories
235 created with this method default to CLEANUP => 1.
236 .Sp
237 .Vb 1
238 \& $dir = File::Temp\->newdir( $template, %options );
239 .Ve
240 .Sp
241 A template may be specified either with a leading template or
242 with a TEMPLATE argument.
243 .Sp
244 Available since 0.19.
245 .Sp
246 TEMPLATE available since 0.23.
247 .IP \fBfilename\fR 4
248 .IX Item "filename"
249 Return the name of the temporary file associated with this object
250 (if the object was created using the "new" constructor).
251 .Sp
252 .Vb 1
253 \& $filename = $tmp\->filename;
254 .Ve
255 .Sp
256 This method is called automatically when the object is used as
257 a string.
258 .Sp
259 Current API available since 0.14
260 .IP \fBdirname\fR 4
261 .IX Item "dirname"
262 Return the name of the temporary directory associated with this
263 object (if the object was created using the "newdir" constructor).
264 .Sp
265 .Vb 1
266 \& $dirname = $tmpdir\->dirname;
267 .Ve
268 .Sp
269 This method is called automatically when the object is used in string context.
270 .IP \fBunlink_on_destroy\fR 4
271 .IX Item "unlink_on_destroy"
272 Control whether the file is unlinked when the object goes out of scope.
273 The file is removed if this value is true and \f(CW$KEEP_ALL\fR is not.
274 .Sp
275 .Vb 1
276 \& $fh\->unlink_on_destroy( 1 );
277 .Ve
278 .Sp
279 Default is for the file to be removed.
280 .Sp
281 Current API available since 0.15
282 .IP \fBDESTROY\fR 4
283 .IX Item "DESTROY"
284 When the object goes out of scope, the destructor is called. This
285 destructor will attempt to unlink the file (using unlink1)
286 if the constructor was called with UNLINK set to 1 (the default state
287 if UNLINK is not specified).
288 .Sp
289 No error is given if the unlink fails.
290 .Sp
291 If the object has been passed to a child process during a fork, the
292 file will be deleted when the object goes out of scope in the parent.
293 .Sp
294 For a temporary directory object the directory will be removed unless
295 the CLEANUP argument was used in the constructor (and set to false) or
296 \&\f(CW\*(C`unlink_on_destroy\*(C'\fR was modified after creation. Note that if a temp
297 directory is your current directory, it cannot be removed \- a warning
298 will be given in this case. \f(CWchdir()\fR out of the directory before
299 letting the object go out of scope.
300 .Sp
301 If the global variable \f(CW$KEEP_ALL\fR is true, the file or directory
302 will not be removed.
303 .SH FUNCTIONS
304 .IX Header "FUNCTIONS"
305 This section describes the recommended interface for generating
306 temporary files and directories.
307 .IP \fBtempfile\fR 4
308 .IX Item "tempfile"
309 This is the basic function to generate temporary files.
310 The behaviour of the file can be changed using various options:
311 .Sp
312 .Vb 2
313 \& $fh = tempfile();
314 \& ($fh, $filename) = tempfile();
315 .Ve
316 .Sp
317 Create a temporary file in the directory specified for temporary
318 files, as specified by the \fBtmpdir()\fR function in File::Spec.
319 .Sp
320 .Vb 1
321 \& ($fh, $filename) = tempfile($template);
322 .Ve
323 .Sp
324 Create a temporary file in the current directory using the supplied
325 template. Trailing `X' characters are replaced with random letters to
326 generate the filename. At least four `X' characters must be present
327 at the end of the template.
328 .Sp
329 .Vb 1
330 \& ($fh, $filename) = tempfile($template, SUFFIX => $suffix)
331 .Ve
332 .Sp
333 Same as previously, except that a suffix is added to the template
334 after the `X' translation. Useful for ensuring that a temporary
335 filename has a particular extension when needed by other applications.
336 But see the WARNING at the end.
337 .Sp
338 .Vb 1
339 \& ($fh, $filename) = tempfile($template, DIR => $dir);
340 .Ve
341 .Sp
342 Translates the template as before except that a directory name
343 is specified.
344 .Sp
345 .Vb 1
346 \& ($fh, $filename) = tempfile($template, TMPDIR => 1);
347 .Ve
348 .Sp
349 Equivalent to specifying a DIR of "File::Spec\->tmpdir", writing the file
350 into the same temporary directory as would be used if no template was
351 specified at all.
352 .Sp
353 .Vb 1
354 \& ($fh, $filename) = tempfile($template, UNLINK => 1);
355 .Ve
356 .Sp
357 Return the filename and filehandle as before except that the file is
358 automatically removed when the program exits (dependent on
359 \&\f(CW$KEEP_ALL\fR). Default is for the file to be removed if a file handle is
360 requested and to be kept if the filename is requested. In a scalar
361 context (where no filename is returned) the file is always deleted
362 either (depending on the operating system) on exit or when it is
363 closed (unless \f(CW$KEEP_ALL\fR is true when the temp file is created).
364 .Sp
365 Use the object-oriented interface if fine-grained control of when
366 a file is removed is required.
367 .Sp
368 If the template is not specified, a template is always
369 automatically generated. This temporary file is placed in \fBtmpdir()\fR
370 (File::Spec) unless a directory is specified explicitly with the
371 DIR option.
372 .Sp
373 .Vb 1
374 \& $fh = tempfile( DIR => $dir );
375 .Ve
376 .Sp
377 If called in scalar context, only the filehandle is returned and the
378 file will automatically be deleted when closed on operating systems
379 that support this (see the description of \fBtmpfile()\fR elsewhere in this
380 document). This is the preferred mode of operation, as if you only
381 have a filehandle, you can never create a race condition by fumbling
382 with the filename. On systems that can not unlink an open file or can
383 not mark a file as temporary when it is opened (for example, Windows
384 NT uses the \f(CW\*(C`O_TEMPORARY\*(C'\fR flag) the file is marked for deletion when
385 the program ends (equivalent to setting UNLINK to 1). The \f(CW\*(C`UNLINK\*(C'\fR
386 flag is ignored if present.
387 .Sp
388 .Vb 1
389 \& (undef, $filename) = tempfile($template, OPEN => 0);
390 .Ve
391 .Sp
392 This will return the filename based on the template but
393 will not open this file. Cannot be used in conjunction with
394 UNLINK set to true. Default is to always open the file
395 to protect from possible race conditions. A warning is issued
396 if warnings are turned on. Consider using the \fBtmpnam()\fR
397 and \fBmktemp()\fR functions described elsewhere in this document
398 if opening the file is not required.
399 .Sp
400 To open the temporary filehandle with O_EXLOCK (open with exclusive
401 file lock) use \f(CW\*(C`EXLOCK=>1\*(C'\fR. This is supported only by some
402 operating systems (most notably BSD derived systems). By default
403 EXLOCK will be false. Former \f(CW\*(C`File::Temp\*(C'\fR versions set EXLOCK to
404 true, so to be sure to get an unlocked filehandle also with older
405 versions, explicitly set \f(CW\*(C`EXLOCK=>0\*(C'\fR.
406 .Sp
407 .Vb 1
408 \& ($fh, $filename) = tempfile($template, EXLOCK => 1);
409 .Ve
410 .Sp
411 By default, the temp file is created with 0600 file permissions.
412 Use \f(CW\*(C`PERMS\*(C'\fR to change this:
413 .Sp
414 .Vb 1
415 \& ($fh, $filename) = tempfile($template, PERMS => 0666);
416 .Ve
417 .Sp
418 Options can be combined as required.
419 .Sp
420 Will \fBcroak()\fR if there is an error.
421 .Sp
422 Available since 0.05.
423 .Sp
424 UNLINK flag available since 0.10.
425 .Sp
426 TMPDIR flag available since 0.19.
427 .Sp
428 EXLOCK flag available since 0.19.
429 .Sp
430 PERMS flag available since 0.2310.
431 .IP \fBtempdir\fR 4
432 .IX Item "tempdir"
433 This is the recommended interface for creation of temporary
434 directories. By default the directory will not be removed on exit
435 (that is, it won't be temporary; this behaviour can not be changed
436 because of issues with backwards compatibility). To enable removal
437 either use the CLEANUP option which will trigger removal on program
438 exit, or consider using the "newdir" method in the object interface which
439 will allow the directory to be cleaned up when the object goes out of
440 scope.
441 .Sp
442 The behaviour of the function depends on the arguments:
443 .Sp
444 .Vb 1
445 \& $tempdir = tempdir();
446 .Ve
447 .Sp
448 Create a directory in \fBtmpdir()\fR (see File::Spec).
449 .Sp
450 .Vb 1
451 \& $tempdir = tempdir( $template );
452 .Ve
453 .Sp
454 Create a directory from the supplied template. This template is
455 similar to that described for \fBtempfile()\fR. `X' characters at the end
456 of the template are replaced with random letters to construct the
457 directory name. At least four `X' characters must be in the template.
458 .Sp
459 .Vb 1
460 \& $tempdir = tempdir ( DIR => $dir );
461 .Ve
462 .Sp
463 Specifies the directory to use for the temporary directory.
464 The temporary directory name is derived from an internal template.
465 .Sp
466 .Vb 1
467 \& $tempdir = tempdir ( $template, DIR => $dir );
468 .Ve
469 .Sp
470 Prepend the supplied directory name to the template. The template
471 should not include parent directory specifications itself. Any parent
472 directory specifications are removed from the template before
473 prepending the supplied directory.
474 .Sp
475 .Vb 1
476 \& $tempdir = tempdir ( $template, TMPDIR => 1 );
477 .Ve
478 .Sp
479 Using the supplied template, create the temporary directory in
480 a standard location for temporary files. Equivalent to doing
481 .Sp
482 .Vb 1
483 \& $tempdir = tempdir ( $template, DIR => File::Spec\->tmpdir);
484 .Ve
485 .Sp
486 but shorter. Parent directory specifications are stripped from the
487 template itself. The \f(CW\*(C`TMPDIR\*(C'\fR option is ignored if \f(CW\*(C`DIR\*(C'\fR is set
488 explicitly. Additionally, \f(CW\*(C`TMPDIR\*(C'\fR is implied if neither a template
489 nor a directory are supplied.
490 .Sp
491 .Vb 1
492 \& $tempdir = tempdir( $template, CLEANUP => 1);
493 .Ve
494 .Sp
495 Create a temporary directory using the supplied template, but
496 attempt to remove it (and all files inside it) when the program
497 exits. Note that an attempt will be made to remove all files from
498 the directory even if they were not created by this module (otherwise
499 why ask to clean it up?). The directory removal is made with
500 the \fBrmtree()\fR function from the File::Path module.
501 Of course, if the template is not specified, the temporary directory
502 will be created in \fBtmpdir()\fR and will also be removed at program exit.
503 .Sp
504 Will \fBcroak()\fR if there is an error.
505 .Sp
506 Current API available since 0.05.
507 .SH "MKTEMP FUNCTIONS"
508 .IX Header "MKTEMP FUNCTIONS"
509 The following functions are Perl implementations of the
510 \&\fBmktemp()\fR family of temp file generation system calls.
511 .IP \fBmkstemp\fR 4
512 .IX Item "mkstemp"
513 Given a template, returns a filehandle to the temporary file and the name
514 of the file.
515 .Sp
516 .Vb 1
517 \& ($fh, $name) = mkstemp( $template );
518 .Ve
519 .Sp
520 In scalar context, just the filehandle is returned.
521 .Sp
522 The template may be any filename with some number of X's appended
523 to it, for example \fI/tmp/temp.XXXX\fR. The trailing X's are replaced
524 with unique alphanumeric combinations.
525 .Sp
526 Will \fBcroak()\fR if there is an error.
527 .Sp
528 Current API available since 0.05.
529 .IP \fBmkstemps\fR 4
530 .IX Item "mkstemps"
531 Similar to \fBmkstemp()\fR, except that an extra argument can be supplied
532 with a suffix to be appended to the template.
533 .Sp
534 .Vb 1
535 \& ($fh, $name) = mkstemps( $template, $suffix );
536 .Ve
537 .Sp
538 For example a template of \f(CW\*(C`testXXXXXX\*(C'\fR and suffix of \f(CW\*(C`.dat\*(C'\fR
539 would generate a file similar to \fItesthGji_w.dat\fR.
540 .Sp
541 Returns just the filehandle alone when called in scalar context.
542 .Sp
543 Will \fBcroak()\fR if there is an error.
544 .Sp
545 Current API available since 0.05.
546 .IP \fBmkdtemp\fR 4
547 .IX Item "mkdtemp"
548 Create a directory from a template. The template must end in
549 X's that are replaced by the routine.
550 .Sp
551 .Vb 1
552 \& $tmpdir_name = mkdtemp($template);
553 .Ve
554 .Sp
555 Returns the name of the temporary directory created.
556 .Sp
557 Directory must be removed by the caller.
558 .Sp
559 Will \fBcroak()\fR if there is an error.
560 .Sp
561 Current API available since 0.05.
562 .IP \fBmktemp\fR 4
563 .IX Item "mktemp"
564 Returns a valid temporary filename but does not guarantee
565 that the file will not be opened by someone else.
566 .Sp
567 .Vb 1
568 \& $unopened_file = mktemp($template);
569 .Ve
570 .Sp
571 Template is the same as that required by \fBmkstemp()\fR.
572 .Sp
573 Will \fBcroak()\fR if there is an error.
574 .Sp
575 Current API available since 0.05.
576 .SH "POSIX FUNCTIONS"
577 .IX Header "POSIX FUNCTIONS"
578 This section describes the re-implementation of the \fBtmpnam()\fR
579 and \fBtmpfile()\fR functions described in POSIX
580 using the \fBmkstemp()\fR from this module.
581 .PP
582 Unlike the POSIX implementations, the directory used
583 for the temporary file is not specified in a system include
584 file (\f(CW\*(C`P_tmpdir\*(C'\fR) but simply depends on the choice of \fBtmpdir()\fR
585 returned by File::Spec. On some implementations this
586 location can be set using the \f(CW\*(C`TMPDIR\*(C'\fR environment variable, which
587 may not be secure.
588 If this is a problem, simply use \fBmkstemp()\fR and specify a template.
589 .IP \fBtmpnam\fR 4
590 .IX Item "tmpnam"
591 When called in scalar context, returns the full name (including path)
592 of a temporary file (uses \fBmktemp()\fR). The only check is that the file does
593 not already exist, but there is no guarantee that that condition will
594 continue to apply.
595 .Sp
596 .Vb 1
597 \& $file = tmpnam();
598 .Ve
599 .Sp
600 When called in list context, a filehandle to the open file and
601 a filename are returned. This is achieved by calling \fBmkstemp()\fR
602 after constructing a suitable template.
603 .Sp
604 .Vb 1
605 \& ($fh, $file) = tmpnam();
606 .Ve
607 .Sp
608 If possible, this form should be used to prevent possible
609 race conditions.
610 .Sp
611 See "tmpdir" in File::Spec for information on the choice of temporary
612 directory for a particular operating system.
613 .Sp
614 Will \fBcroak()\fR if there is an error.
615 .Sp
616 Current API available since 0.05.
617 .IP \fBtmpfile\fR 4
618 .IX Item "tmpfile"
619 Returns the filehandle of a temporary file.
620 .Sp
621 .Vb 1
622 \& $fh = tmpfile();
623 .Ve
624 .Sp
625 The file is removed when the filehandle is closed or when the program
626 exits. No access to the filename is provided.
627 .Sp
628 If the temporary file can not be created undef is returned.
629 Currently this command will probably not work when the temporary
630 directory is on an NFS file system.
631 .Sp
632 Will \fBcroak()\fR if there is an error.
633 .Sp
634 Available since 0.05.
635 .Sp
636 Returning undef if unable to create file added in 0.12.
637 .SH "ADDITIONAL FUNCTIONS"
638 .IX Header "ADDITIONAL FUNCTIONS"
639 These functions are provided for backwards compatibility
640 with common tempfile generation C library functions.
641 .PP
642 They are not exported and must be addressed using the full package
643 name.
644 .IP \fBtempnam\fR 4
645 .IX Item "tempnam"
646 Return the name of a temporary file in the specified directory
647 using a prefix. The file is guaranteed not to exist at the time
648 the function was called, but such guarantees are good for one
649 clock tick only. Always use the proper form of \f(CW\*(C`sysopen\*(C'\fR
650 with \f(CW\*(C`O_CREAT | O_EXCL\*(C'\fR if you must open such a filename.
651 .Sp
652 .Vb 1
653 \& $filename = File::Temp::tempnam( $dir, $prefix );
654 .Ve
655 .Sp
656 Equivalent to running \fBmktemp()\fR with \f(CW$dir\fR/$prefixXXXXXXXX
657 (using unix file convention as an example)
658 .Sp
659 Because this function uses \fBmktemp()\fR, it can suffer from race conditions.
660 .Sp
661 Will \fBcroak()\fR if there is an error.
662 .Sp
663 Current API available since 0.05.
664 .SH "UTILITY FUNCTIONS"
665 .IX Header "UTILITY FUNCTIONS"
666 Useful functions for dealing with the filehandle and filename.
667 .IP \fBunlink0\fR 4
668 .IX Item "unlink0"
669 Given an open filehandle and the associated filename, make a safe
670 unlink. This is achieved by first checking that the filename and
671 filehandle initially point to the same file and that the number of
672 links to the file is 1 (all fields returned by \fBstat()\fR are compared).
673 Then the filename is unlinked and the filehandle checked once again to
674 verify that the number of links on that file is now 0. This is the
675 closest you can come to making sure that the filename unlinked was the
676 same as the file whose descriptor you hold.
677 .Sp
678 .Vb 2
679 \& unlink0($fh, $path)
680 \& or die "Error unlinking file $path safely";
681 .Ve
682 .Sp
683 Returns false on error but \fBcroaks()\fR if there is a security
684 anomaly. The filehandle is not closed since on some occasions this is
685 not required.
686 .Sp
687 On some platforms, for example Windows NT, it is not possible to
688 unlink an open file (the file must be closed first). On those
689 platforms, the actual unlinking is deferred until the program ends and
690 good status is returned. A check is still performed to make sure that
691 the filehandle and filename are pointing to the same thing (but not at
692 the time the end block is executed since the deferred removal may not
693 have access to the filehandle).
694 .Sp
695 Additionally, on Windows NT not all the fields returned by \fBstat()\fR can
696 be compared. For example, the \f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`rdev\*(C'\fR fields seem to be
697 different. Also, it seems that the size of the file returned by \fBstat()\fR
698 does not always agree, with \f(CWstat(FH)\fR being more accurate than
699 \&\f(CWstat(filename)\fR, presumably because of caching issues even when
700 using autoflush (this is usually overcome by waiting a while after
701 writing to the tempfile before attempting to \f(CW\*(C`unlink0\*(C'\fR it).
702 .Sp
703 Finally, on NFS file systems the link count of the file handle does
704 not always go to zero immediately after unlinking. Currently, this
705 command is expected to fail on NFS disks.
706 .Sp
707 This function is disabled if the global variable \f(CW$KEEP_ALL\fR is true
708 and an unlink on open file is supported. If the unlink is to be deferred
709 to the END block, the file is still registered for removal.
710 .Sp
711 This function should not be called if you are using the object oriented
712 interface since the it will interfere with the object destructor deleting
713 the file.
714 .Sp
715 Available Since 0.05.
716 .Sp
717 If can not unlink open file, defer removal until later available since 0.06.
718 .IP \fBcmpstat\fR 4
719 .IX Item "cmpstat"
720 Compare \f(CW\*(C`stat\*(C'\fR of filehandle with \f(CW\*(C`stat\*(C'\fR of provided filename. This
721 can be used to check that the filename and filehandle initially point
722 to the same file and that the number of links to the file is 1 (all
723 fields returned by \fBstat()\fR are compared).
724 .Sp
725 .Vb 2
726 \& cmpstat($fh, $path)
727 \& or die "Error comparing handle with file";
728 .Ve
729 .Sp
730 Returns false if the stat information differs or if the link count is
731 greater than 1. Calls croak if there is a security anomaly.
732 .Sp
733 On certain platforms, for example Windows, not all the fields returned by \fBstat()\fR
734 can be compared. For example, the \f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`rdev\*(C'\fR fields seem to be
735 different in Windows. Also, it seems that the size of the file
736 returned by \fBstat()\fR does not always agree, with \f(CWstat(FH)\fR being more
737 accurate than \f(CWstat(filename)\fR, presumably because of caching issues
738 even when using autoflush (this is usually overcome by waiting a while
739 after writing to the tempfile before attempting to \f(CW\*(C`unlink0\*(C'\fR it).
740 .Sp
741 Not exported by default.
742 .Sp
743 Current API available since 0.14.
744 .IP \fBunlink1\fR 4
745 .IX Item "unlink1"
746 Similar to \f(CW\*(C`unlink0\*(C'\fR except after file comparison using cmpstat, the
747 filehandle is closed prior to attempting to unlink the file. This
748 allows the file to be removed without using an END block, but does
749 mean that the post-unlink comparison of the filehandle state provided
750 by \f(CW\*(C`unlink0\*(C'\fR is not available.
751 .Sp
752 .Vb 2
753 \& unlink1($fh, $path)
754 \& or die "Error closing and unlinking file";
755 .Ve
756 .Sp
757 Usually called from the object destructor when using the OO interface.
758 .Sp
759 Not exported by default.
760 .Sp
761 This function is disabled if the global variable \f(CW$KEEP_ALL\fR is true.
762 .Sp
763 Can call \fBcroak()\fR if there is a security anomaly during the \fBstat()\fR
764 comparison.
765 .Sp
766 Current API available since 0.14.
767 .IP \fBcleanup\fR 4
768 .IX Item "cleanup"
769 Calling this function will cause any temp files or temp directories
770 that are registered for removal to be removed. This happens automatically
771 when the process exits but can be triggered manually if the caller is sure
772 that none of the temp files are required. This method can be registered as
773 an Apache callback.
774 .Sp
775 Note that if a temp directory is your current directory, it cannot be
776 removed. \f(CWchdir()\fR out of the directory first before calling
777 \&\f(CWcleanup()\fR. (For the cleanup at program exit when the CLEANUP flag
778 is set, this happens automatically.)
779 .Sp
780 On OSes where temp files are automatically removed when the temp file
781 is closed, calling this function will have no effect other than to remove
782 temporary directories (which may include temporary files).
783 .Sp
784 .Vb 1
785 \& File::Temp::cleanup();
786 .Ve
787 .Sp
788 Not exported by default.
789 .Sp
790 Current API available since 0.15.
791 .SH "PACKAGE VARIABLES"
792 .IX Header "PACKAGE VARIABLES"
793 These functions control the global state of the package.
794 .IP \fBsafe_level\fR 4
795 .IX Item "safe_level"
796 Controls the lengths to which the module will go to check the safety of the
797 temporary file or directory before proceeding.
798 Options are:
799 .RS 4
800 .IP STANDARD 8
801 .IX Item "STANDARD"
802 Do the basic security measures to ensure the directory exists and is
803 writable, that temporary files are opened only if they do not already
804 exist, and that possible race conditions are avoided. Finally the
805 unlink0 function is used to remove files safely.
806 .IP MEDIUM 8
807 .IX Item "MEDIUM"
808 In addition to the STANDARD security, the output directory is checked
809 to make sure that it is owned either by root or the user running the
810 program. If the directory is writable by group or by other, it is then
811 checked to make sure that the sticky bit is set.
812 .Sp
813 Will not work on platforms that do not support the \f(CW\*(C`\-k\*(C'\fR test
814 for sticky bit.
815 .IP HIGH 8
816 .IX Item "HIGH"
817 In addition to the MEDIUM security checks, also check for the
818 possibility of ``\fBchown()\fR giveaway'' using the POSIX
819 \&\fBsysconf()\fR function. If this is a possibility, each directory in the
820 path is checked in turn for safeness, recursively walking back to the
821 root directory.
822 .Sp
823 For platforms that do not support the POSIX
824 \&\f(CW\*(C`_PC_CHOWN_RESTRICTED\*(C'\fR symbol (for example, Windows NT) it is
825 assumed that ``\fBchown()\fR giveaway'' is possible and the recursive test
826 is performed.
827 .RE
828 .RS 4
829 .Sp
830 The level can be changed as follows:
831 .Sp
832 .Vb 1
833 \& File::Temp\->safe_level( File::Temp::HIGH );
834 .Ve
835 .Sp
836 The level constants are not exported by the module.
837 .Sp
838 Currently, you must be running at least perl v5.6.0 in order to
839 run with MEDIUM or HIGH security. This is simply because the
840 safety tests use functions from Fcntl that are not
841 available in older versions of perl. The problem is that the version
842 number for Fcntl is the same in perl 5.6.0 and in 5.005_03 even though
843 they are different versions.
844 .Sp
845 On systems that do not support the HIGH or MEDIUM safety levels
846 (for example Win NT or OS/2) any attempt to change the level will
847 be ignored. The decision to ignore rather than raise an exception
848 allows portable programs to be written with high security in mind
849 for the systems that can support this without those programs failing
850 on systems where the extra tests are irrelevant.
851 .Sp
852 If you really need to see whether the change has been accepted
853 simply examine the return value of \f(CW\*(C`safe_level\*(C'\fR.
854 .Sp
855 .Vb 3
856 \& $newlevel = File::Temp\->safe_level( File::Temp::HIGH );
857 \& die "Could not change to high security"
858 \& if $newlevel != File::Temp::HIGH;
859 .Ve
860 .Sp
861 Available since 0.05.
862 .RE
863 .IP TopSystemUID 4
864 .IX Item "TopSystemUID"
865 This is the highest UID on the current system that refers to a root
866 UID. This is used to make sure that the temporary directory is
867 owned by a system UID (\f(CW\*(C`root\*(C'\fR, \f(CW\*(C`bin\*(C'\fR, \f(CW\*(C`sys\*(C'\fR etc) rather than
868 simply by root.
869 .Sp
870 This is required since on many unix systems \f(CW\*(C`/tmp\*(C'\fR is not owned
871 by root.
872 .Sp
873 Default is to assume that any UID less than or equal to 10 is a root
874 UID.
875 .Sp
876 .Vb 2
877 \& File::Temp\->top_system_uid(10);
878 \& my $topid = File::Temp\->top_system_uid;
879 .Ve
880 .Sp
881 This value can be adjusted to reduce security checking if required.
882 The value is only relevant when \f(CW\*(C`safe_level\*(C'\fR is set to MEDIUM or higher.
883 .Sp
884 Available since 0.05.
885 .ie n .IP \fR\fB$KEEP_ALL\fR\fB\fR 4
886 .el .IP \fR\f(CB$KEEP_ALL\fR\fB\fR 4
887 .IX Item "$KEEP_ALL"
888 Controls whether temporary files and directories should be retained
889 regardless of any instructions in the program to remove them
890 automatically. This is useful for debugging but should not be used in
891 production code.
892 .Sp
893 .Vb 1
894 \& $File::Temp::KEEP_ALL = 1;
895 .Ve
896 .Sp
897 Default is for files to be removed as requested by the caller.
898 .Sp
899 In some cases, files will only be retained if this variable is true
900 when the file is created. This means that you can not create a temporary
901 file, set this variable and expect the temp file to still be around
902 when the program exits.
903 .ie n .IP \fR\fB$DEBUG\fR\fB\fR 4
904 .el .IP \fR\f(CB$DEBUG\fR\fB\fR 4
905 .IX Item "$DEBUG"
906 Controls whether debugging messages should be enabled.
907 .Sp
908 .Vb 1
909 \& $File::Temp::DEBUG = 1;
910 .Ve
911 .Sp
912 Default is for debugging mode to be disabled.
913 .Sp
914 Available since 0.15.
915 .SH WARNING
916 .IX Header "WARNING"
917 For maximum security, endeavour always to avoid ever looking at,
918 touching, or even imputing the existence of the filename. You do not
919 know that that filename is connected to the same file as the handle
920 you have, and attempts to check this can only trigger more race
921 conditions. It's far more secure to use the filehandle alone and
922 dispense with the filename altogether.
923 .PP
924 If you need to pass the handle to something that expects a filename
925 then on a unix system you can use \f(CW\*(C`"/dev/fd/" . fileno($fh)\*(C'\fR for
926 arbitrary programs. Perl code that uses the 2\-argument version of
927 \&\f(CW\*(C`open\*(C'\fR can be passed \f(CW\*(C`"+<=&" . fileno($fh)\*(C'\fR. Otherwise you
928 will need to pass the filename. You will have to clear the
929 close-on-exec bit on that file descriptor before passing it to another
930 process.
931 .PP
932 .Vb 3
933 \& use Fcntl qw/F_SETFD F_GETFD/;
934 \& fcntl($tmpfh, F_SETFD, 0)
935 \& or die "Can\*(Aqt clear close\-on\-exec flag on temp fh: $!\en";
936 .Ve
937 .SS "Temporary files and NFS"
938 .IX Subsection "Temporary files and NFS"
939 Some problems are associated with using temporary files that reside
940 on NFS file systems and it is recommended that a local filesystem
941 is used whenever possible. Some of the security tests will most probably
942 fail when the temp file is not local. Additionally, be aware that
943 the performance of I/O operations over NFS will not be as good as for
944 a local disk.
945 .SS Forking
946 .IX Subsection "Forking"
947 In some cases files created by File::Temp are removed from within an
948 END block. Since END blocks are triggered when a child process exits
949 (unless \f(CWPOSIX::_exit()\fR is used by the child) File::Temp takes care
950 to only remove those temp files created by a particular process ID. This
951 means that a child will not attempt to remove temp files created by the
952 parent process.
953 .PP
954 If you are forking many processes in parallel that are all creating
955 temporary files, you may need to reset the random number seed using
956 srand(EXPR) in each child else all the children will attempt to walk
957 through the same set of random file names and may well cause
958 themselves to give up if they exceed the number of retry attempts.
959 .SS "Directory removal"
960 .IX Subsection "Directory removal"
961 Note that if you have chdir'ed into the temporary directory and it is
962 subsequently cleaned up (either in the END block or as part of object
963 destruction), then you will get a warning from \fBFile::Path::rmtree()\fR.
964 .SS "Taint mode"
965 .IX Subsection "Taint mode"
966 If you need to run code under taint mode, updating to the latest
967 File::Spec is highly recommended. On Windows, if the directory
968 given by File::Spec::tmpdir isn't writable, File::Temp will attempt
969 to fallback to the user's local application data directory or croak
970 with an error.
971 .SS BINMODE
972 .IX Subsection "BINMODE"
973 The file returned by File::Temp will have been opened in binary mode
974 if such a mode is available. If that is not correct, use the \f(CWbinmode()\fR
975 function to change the mode of the filehandle.
976 .PP
977 Note that you can modify the encoding of a file opened by File::Temp
978 also by using \f(CWbinmode()\fR.
979 .SH HISTORY
980 .IX Header "HISTORY"
981 Originally began life in May 1999 as an XS interface to the system
982 \&\fBmkstemp()\fR function. In March 2000, the OpenBSD \fBmkstemp()\fR code was
983 translated to Perl for total control of the code's
984 security checking, to ensure the presence of the function regardless of
985 operating system and to help with portability. The module was shipped
986 as a standard part of perl from v5.6.1.
987 .PP
988 Thanks to Tom Christiansen for suggesting that this module
989 should be written and providing ideas for code improvements and
990 security enhancements.
991 .SH "SEE ALSO"
992 .IX Header "SEE ALSO"
993 "tmpnam" in POSIX, "tmpfile" in POSIX, File::Spec, File::Path
994 .PP
995 See IO::File and File::MkTemp, Apache::TempFile for
996 different implementations of temporary file handling.
997 .PP
998 See File::Tempdir for an alternative object-oriented wrapper for
999 the \f(CW\*(C`tempdir\*(C'\fR function.
1000 .SH SUPPORT
1001 .IX Header "SUPPORT"
1002 Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Temp>
1003 (or bug\-File\[email protected] <mailto:[email protected]>).
1004 .PP
1005 There is also a mailing list available for users of this distribution, at
1006 <http://lists.perl.org/list/cpan\-workers.html>.
1007 .PP
1008 There is also an irc channel available for users of this distribution, at
1009 \&\f(CW\*(C`#toolchain\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR <irc://irc.perl.org/#toolchain>.
1010 .SH AUTHOR
1011 .IX Header "AUTHOR"
1012 Tim Jenness <[email protected]>
1013 .SH CONTRIBUTORS
1014 .IX Header "CONTRIBUTORS"
1015 .IP \(bu 4
1016 Tim Jenness <[email protected]>
1017 .IP \(bu 4
1018 Karen Etheridge <[email protected]>
1019 .IP \(bu 4
1020 David Golden <[email protected]>
1021 .IP \(bu 4
1022 Slaven Rezic <[email protected]>
1023 .IP \(bu 4
1024 mohawk2 <[email protected]>
1025 .IP \(bu 4
1026 Roy Ivy III <[email protected]>
1027 .IP \(bu 4
1028 Peter Rabbitson <[email protected]>
1029 .IP \(bu 4
1030 Olivier MenguĂ© <[email protected]>
1031 .IP \(bu 4
1032 Peter John Acklam <[email protected]>
1033 .IP \(bu 4
1034 Tim Gim Yee <[email protected]>
1035 .IP \(bu 4
1036 Nicolas R <[email protected]>
1037 .IP \(bu 4
1038 Brian Mowrey <[email protected]>
1039 .IP \(bu 4
1040 Dagfinn Ilmari MannsĂ„ker <[email protected]>
1041 .IP \(bu 4
1042 David Steinbrunner <[email protected]>
1043 .IP \(bu 4
1044 Ed Avis <[email protected]>
1045 .IP \(bu 4
1046 Guillem Jover <[email protected]>
1047 .IP \(bu 4
1048 James E. Keenan <[email protected]>
1049 .IP \(bu 4
1050 Kevin Ryde <[email protected]>
1051 .IP \(bu 4
1052 Ben Tilly <[email protected]>
1053 .SH "COPYRIGHT AND LICENSE"
1054 .IX Header "COPYRIGHT AND LICENSE"
1055 This software is copyright (c) 2020 by Tim Jenness and the UK Particle Physics and Astronomy Research Council.
1056 .PP
1057 This is free software; you can redistribute it and/or modify it under
1058 the same terms as the Perl 5 programming language system itself.