5 File::Temp - return name and handle of a temporary file safely
11 This section is at the top in order to provide easier access to
12 porters. It is not expected to be rendered by a standard pod
13 formatting tool. Please skip straight to the SYNOPSIS section if you
14 are not trying to port this module to a new platform.
16 This module is designed to be portable across operating systems and it
17 currently supports Unix, VMS, DOS, OS/2, Windows and Mac OS
18 (Classic). When porting to a new OS there are generally three main
19 issues that have to be solved:
25 Can the OS unlink an open file? If it can not then the
26 C<_can_unlink_opened_file> method should be modified.
30 Are the return values from C<stat> reliable? By default all the
31 return values from C<stat> are compared when unlinking a temporary
32 file using the filename and the handle. Operating systems other than
33 unix do not always have valid entries in all fields. If C<unlink0> fails
34 then the C<stat> comparison should be modified accordingly.
38 Security. Systems that can not support a test for the sticky bit
39 on a directory can not use the MEDIUM and HIGH security tests.
40 The C<_can_do_level> method should be modified accordingly.
48 use File::Temp qw/ tempfile tempdir /;
51 ($fh, $filename) = tempfile();
53 ($fh, $filename) = tempfile( $template, DIR => $dir);
54 ($fh, $filename) = tempfile( $template, SUFFIX => '.dat');
57 $dir = tempdir( CLEANUP => 1 );
58 ($fh, $filename) = tempfile( DIR => $dir );
65 $fh = new File::Temp( TEMPLATE => $template );
66 $fname = $fh->filename;
68 $tmp = new File::Temp( UNLINK => 0, SUFFIX => '.dat' );
69 print $tmp "Some data\n";
70 print "Filename is $tmp\n";
72 The following interfaces are provided for compatibility with
73 existing APIs. They should not be used in new code.
77 use File::Temp qw/ :mktemp /;
79 ($fh, $file) = mkstemp( "tmpfileXXXXX" );
80 ($fh, $file) = mkstemps( "tmpfileXXXXXX", $suffix);
82 $tmpdir = mkdtemp( $template );
84 $unopened_file = mktemp( $template );
88 use File::Temp qw/ :POSIX /;
93 ($fh, $file) = tmpnam();
95 Compatibility functions:
97 $unopened_file = File::Temp::tempnam( $dir, $pfx );
101 C<File::Temp> can be used to create and open temporary files in a safe
102 way. There is both a function interface and an object-oriented
103 interface. The File::Temp constructor or the tempfile() function can
104 be used to return the name and the open filehandle of a temporary
105 file. The tempdir() function can be used to create a temporary
108 The security aspect of temporary file creation is emphasized such that
109 a filehandle and filename are returned together. This helps guarantee
110 that a race condition can not occur where the temporary file is
111 created by another process between checking for the existence of the
112 file and its opening. Additional security levels are provided to
113 check, for example, that the sticky bit is set on world writable
114 directories. See L<"safe_level"> for more information.
116 For compatibility with popular C library functions, Perl implementations of
117 the mkstemp() family of functions are provided. These are, mkstemp(),
118 mkstemps(), mkdtemp() and mktemp().
120 Additionally, implementations of the standard L<POSIX|POSIX>
121 tmpnam() and tmpfile() functions are provided if required.
123 Implementations of mktemp(), tmpnam(), and tempnam() are provided,
124 but should be used with caution since they return only a filename
125 that was valid when function was called, so cannot guarantee
126 that the file will not exist by the time the caller opens the filename.
130 # 5.6.0 gives us S_IWOTH, S_IWGRP, our and auto-vivifying filehandls
131 # People would like a version on 5.005 so give them what they want :-)
136 use File::Path qw/ rmtree /;
139 require VMS::Stdio if $^O eq 'VMS';
141 # Need the Symbol package if we are running older perl
142 require Symbol if $] < 5.006;
144 ### For the OO interface
145 use base qw/ IO::Handle /;
146 use overload '""' => "STRINGIFY";
149 # use 'our' on v5.6.0
150 use vars qw($VERSION @EXPORT_OK %EXPORT_TAGS $DEBUG $KEEP_ALL);
155 # We are exporting functions
157 use base qw/Exporter/;
159 # Export list - to allow fine tuning of export table
174 # Groups of functions for export
177 'POSIX' => [qw/ tmpnam tmpfile /],
178 'mktemp' => [qw/ mktemp mkstemp mkstemps mkdtemp/],
181 # add contents of these tags to @EXPORT
182 Exporter::export_tags('POSIX','mktemp');
186 $VERSION = '0.16_01';
188 # This is a list of characters that can be used in random filenames
190 my @CHARS = (qw/ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
191 a b c d e f g h i j k l m n o p q r s t u v w x y z
192 0 1 2 3 4 5 6 7 8 9 _
195 # Maximum number of tries to make a temp file before failing
197 use constant MAX_TRIES => 1000;
199 # Minimum number of X characters that should be in a template
200 use constant MINX => 4;
202 # Default template when no template supplied
204 use constant TEMPXXX => 'X' x 10;
206 # Constants for the security level
208 use constant STANDARD => 0;
209 use constant MEDIUM => 1;
210 use constant HIGH => 2;
212 # OPENFLAGS. If we defined the flag to use with Sysopen here this gives
213 # us an optimisation when many temporary files are requested
215 my $OPENFLAGS = O_CREAT | O_EXCL | O_RDWR;
217 unless ($^O eq 'MacOS') {
218 for my $oflag (qw/ NOFOLLOW BINARY LARGEFILE EXLOCK NOINHERIT /) {
219 my ($bit, $func) = (0, "Fcntl::O_" . $oflag);
221 $OPENFLAGS |= $bit if eval {
222 # Make sure that redefined die handlers do not cause problems
224 local $SIG{__DIE__} = sub {};
225 local $SIG{__WARN__} = sub {};
232 # On some systems the O_TEMPORARY flag can be used to tell the OS
233 # to automatically remove the file when it is closed. This is fine
234 # in most cases but not if tempfile is called with UNLINK=>0 and
235 # the filename is requested -- in the case where the filename is to
236 # be passed to another routine. This happens on windows. We overcome
237 # this by using a second open flags variable
239 my $OPENTEMPFLAGS = $OPENFLAGS;
240 unless ($^O eq 'MacOS') {
241 for my $oflag (qw/ TEMPORARY /) {
242 my ($bit, $func) = (0, "Fcntl::O_" . $oflag);
244 $OPENTEMPFLAGS |= $bit if eval {
245 # Make sure that redefined die handlers do not cause problems
247 local $SIG{__DIE__} = sub {};
248 local $SIG{__WARN__} = sub {};
255 # INTERNAL ROUTINES - not to be used outside of package
257 # Generic routine for getting a temporary filename
258 # modelled on OpenBSD _gettemp() in mktemp.c
260 # The template must contain X's that are to be replaced
261 # with the random values
265 # TEMPLATE - string containing the XXXXX's that is converted
266 # to a random filename and opened if required
268 # Optionally, a hash can also be supplied containing specific options
269 # "open" => if true open the temp file, else just return the name
271 # "mkdir"=> if true, we are creating a temp directory rather than tempfile
273 # "suffixlen" => number of characters at end of PATH to be ignored.
275 # "unlink_on_close" => indicates that, if possible, the OS should remove
276 # the file as soon as it is closed. Usually indicates
277 # use of the O_TEMPORARY flag to sysopen.
278 # Usually irrelevant on unix
280 # Optionally a reference to a scalar can be passed into the function
281 # On error this will be used to store the reason for the error
282 # "ErrStr" => \$errstr
284 # "open" and "mkdir" can not both be true
285 # "unlink_on_close" is not used when "mkdir" is true.
287 # The default options are equivalent to mktemp().
290 # filehandle - open file handle (if called with doopen=1, else undef)
291 # temp name - name of the temp file or directory
294 # ($fh, $name) = _gettemp($template, "open" => 1);
296 # for the current version, failures are associated with
297 # stored in an error string and returned to give the reason whilst debugging
298 # This routine is not called by any external function
301 croak 'Usage: ($fh, $name) = _gettemp($template, OPTIONS);'
302 unless scalar(@_) >= 1;
304 # the internal error string - expect it to be overridden
305 # Need this in case the caller decides not to supply us a value
306 # need an anonymous scalar
314 "unlink_on_close" => 0,
315 "ErrStr" => \$tempErrStr,
319 my $template = shift;
320 if (ref($template)) {
321 # Use a warning here since we have not yet merged ErrStr
322 carp "File::Temp::_gettemp: template must not be a reference";
326 # Check that the number of entries on stack are even
327 if (scalar(@_) % 2 != 0) {
328 # Use a warning here since we have not yet merged ErrStr
329 carp "File::Temp::_gettemp: Must have even number of options";
333 # Read the options and merge with defaults
334 %options = (%options, @_) if @_;
336 # Make sure the error string is set to undef
337 ${$options{ErrStr}} = undef;
339 # Can not open the file and make a directory in a single call
340 if ($options{"open"} && $options{"mkdir"}) {
341 ${$options{ErrStr}} = "doopen and domkdir can not both be true\n";
345 # Find the start of the end of the Xs (position of last X)
346 # Substr starts from 0
347 my $start = length($template) - 1 - $options{"suffixlen"};
349 # Check that we have at least MINX x X (eg 'XXXX") at the end of the string
350 # (taking suffixlen into account). Any fewer is insecure.
352 # Do it using substr - no reason to use a pattern match since
353 # we know where we are looking and what we are looking for
355 if (substr($template, $start - MINX + 1, MINX) ne 'X' x MINX) {
356 ${$options{ErrStr}} = "The template must end with at least ".
357 MINX . " 'X' characters\n";
361 # Replace all the X at the end of the substring with a
362 # random character or just all the XX at the end of a full string.
363 # Do it as an if, since the suffix adjusts which section to replace
364 # and suffixlen=0 returns nothing if used in the substr directly
365 # and generate a full path from the template
367 my $path = _replace_XX($template, $options{"suffixlen"});
370 # Split the path into constituent parts - eventually we need to check
371 # whether the directory exists
372 # We need to know whether we are making a temp directory
375 my ($volume, $directories, $file);
376 my $parent; # parent directory
377 if ($options{"mkdir"}) {
378 # There is no filename at the end
379 ($volume, $directories, $file) = File::Spec->splitpath( $path, 1);
381 # The parent is then $directories without the last directory
382 # Split the directory and put it back together again
383 my @dirs = File::Spec->splitdir($directories);
385 # If @dirs only has one entry (i.e. the directory template) that means
386 # we are in the current directory
388 $parent = File::Spec->curdir;
391 if ($^O eq 'VMS') { # need volume to avoid relative dir spec
392 $parent = File::Spec->catdir($volume, @dirs[0..$#dirs-1]);
393 $parent = 'sys$disk:[]' if $parent eq '';
396 # Put it back together without the last one
397 $parent = File::Spec->catdir(@dirs[0..$#dirs-1]);
399 # ...and attach the volume (no filename)
400 $parent = File::Spec->catpath($volume, $parent, '');
407 # Get rid of the last filename (use File::Basename for this?)
408 ($volume, $directories, $file) = File::Spec->splitpath( $path );
410 # Join up without the file part
411 $parent = File::Spec->catpath($volume,$directories,'');
413 # If $parent is empty replace with curdir
414 $parent = File::Spec->curdir
415 unless $directories ne '';
419 # Check that the parent directories exist
420 # Do this even for the case where we are simply returning a name
421 # not a file -- no point returning a name that includes a directory
422 # that does not exist or is not writable
424 unless (-d $parent) {
425 ${$options{ErrStr}} = "Parent directory ($parent) is not a directory";
428 unless (-w $parent) {
429 ${$options{ErrStr}} = "Parent directory ($parent) is not writable\n";
434 # Check the stickiness of the directory and chown giveaway if required
435 # If the directory is world writable the sticky bit
438 if (File::Temp->safe_level == MEDIUM) {
440 unless (_is_safe($parent,\$safeerr)) {
441 ${$options{ErrStr}} = "Parent directory ($parent) is not safe ($safeerr)";
444 } elsif (File::Temp->safe_level == HIGH) {
446 unless (_is_verysafe($parent, \$safeerr)) {
447 ${$options{ErrStr}} = "Parent directory ($parent) is not safe ($safeerr)";
453 # Now try MAX_TRIES time to open the file
454 for (my $i = 0; $i < MAX_TRIES; $i++) {
456 # Try to open the file if requested
457 if ($options{"open"}) {
460 # If we are running before perl5.6.0 we can not auto-vivify
462 $fh = &Symbol::gensym;
465 # Try to make sure this will be marked close-on-exec
466 # XXX: Win32 doesn't respect this, nor the proper fcntl,
467 # but may have O_NOINHERIT. This may or may not be in Fcntl.
470 # Store callers umask
476 # Attempt to open the file
477 my $open_success = undef;
478 if ( $^O eq 'VMS' and $options{"unlink_on_close"} && !$KEEP_ALL) {
479 # make it auto delete on close by setting FAB$V_DLT bit
480 $fh = VMS::Stdio::vmssysopen($path, $OPENFLAGS, 0600, 'fop=dlt');
483 my $flags = ( ($options{"unlink_on_close"} && !$KEEP_ALL) ?
486 $open_success = sysopen($fh, $path, $flags, 0600);
488 if ( $open_success ) {
491 umask($umask) if defined $umask;
493 # Opened successfully - return file handle and name
498 umask($umask) if defined $umask;
500 # Error opening file - abort with error
501 # if the reason was anything but EEXIST
502 unless ($!{EEXIST}) {
503 ${$options{ErrStr}} = "Could not create temp file $path: $!";
507 # Loop round for another try
510 } elsif ($options{"mkdir"}) {
512 # Store callers umask
518 # Open the temp directory
519 if (mkdir( $path, 0700)) {
522 umask($umask) if defined $umask;
528 umask($umask) if defined $umask;
530 # Abort with error if the reason for failure was anything
532 unless ($!{EEXIST}) {
533 ${$options{ErrStr}} = "Could not create directory $path: $!";
537 # Loop round for another try
543 # Return true if the file can not be found
544 # Directory has been checked previously
546 return (undef, $path) unless -e $path;
548 # Try again until MAX_TRIES
552 # Did not successfully open the tempfile/dir
553 # so try again with a different set of random letters
554 # No point in trying to increment unless we have only
555 # 1 X say and the randomness could come up with the same
556 # file MAX_TRIES in a row.
558 # Store current attempt - in principal this implies that the
559 # 3rd time around the open attempt that the first temp file
560 # name could be generated again. Probably should store each
561 # attempt and make sure that none are repeated
563 my $original = $path;
564 my $counter = 0; # Stop infinite loop
569 # Generate new name from original template
570 $path = _replace_XX($template, $options{"suffixlen"});
574 } until ($path ne $original || $counter > $MAX_GUESS);
576 # Check for out of control looping
577 if ($counter > $MAX_GUESS) {
578 ${$options{ErrStr}} = "Tried to get a new temp name different to the previous value $MAX_GUESS times.\nSomething wrong with template?? ($template)";
584 # If we get here, we have run out of tries
585 ${ $options{ErrStr} } = "Have exceeded the maximum number of attempts ("
586 . MAX_TRIES . ") to open temp file/dir";
592 # Internal routine to return a random character from the
593 # character list. Does not do an srand() since rand()
594 # will do one automatically
596 # No arguments. Return value is the random character
598 # No longer called since _replace_XX runs a few percent faster if
599 # I inline the code. This is important if we are creating thousands of
604 $CHARS[ int( rand( $#CHARS ) ) ];
608 # Internal routine to replace the XXXX... with random characters
609 # This has to be done by _gettemp() every time it fails to
610 # open a temp file/dir
612 # Arguments: $template (the template with XXX),
613 # $ignore (number of characters at end to ignore)
615 # Returns: modified template
619 croak 'Usage: _replace_XX($template, $ignore)'
620 unless scalar(@_) == 2;
622 my ($path, $ignore) = @_;
624 # Do it as an if, since the suffix adjusts which section to replace
625 # and suffixlen=0 returns nothing if used in the substr directly
626 # Alternatively, could simply set $ignore to length($path)-1
627 # Don't want to always use substr when not required though.
630 substr($path, 0, - $ignore) =~ s/X(?=X*\z)/$CHARS[ int( rand( $#CHARS ) ) ]/ge;
632 $path =~ s/X(?=X*\z)/$CHARS[ int( rand( $#CHARS ) ) ]/ge;
637 # Internal routine to force a temp file to be writable after
638 # it is created so that we can unlink it. Windows seems to occassionally
639 # force a file to be readonly when written to certain temp locations
640 sub _force_writable {
645 umask($umask) if defined $umask;
649 # internal routine to check to see if the directory is safe
650 # First checks to see if the directory is not owned by the
651 # current user or root. Then checks to see if anyone else
652 # can write to the directory and if so, checks to see if
653 # it has the sticky bit set
655 # Will not work on systems that do not support sticky bit
657 #Args: directory path to check
658 # Optionally: reference to scalar to contain error message
659 # Returns true if the path is safe and false otherwise.
660 # Returns undef if can not even run stat() on the path
662 # This routine based on version written by Tom Christiansen
664 # Presumably, by the time we actually attempt to create the
665 # file or directory in this directory, it may not be safe
666 # anymore... Have to run _is_safe directly after the open.
674 my @info = stat($path);
675 unless (scalar(@info)) {
676 $$err_ref = "stat(path) returned no values";
679 return 1 if $^O eq 'VMS'; # owner delete control at file level
681 # Check to see whether owner is neither superuser (or a system uid) nor me
682 # Use the real uid from the $< variable
684 if ($info[4] > File::Temp->top_system_uid() && $info[4] != $<) {
686 Carp::cluck(sprintf "uid=$info[4] topuid=%s \$<=$< path='$path'",
687 File::Temp->top_system_uid());
689 $$err_ref = "Directory owned neither by root nor the current user"
694 # check whether group or other can write file
695 # use 066 to detect either reading or writing
696 # use 022 to check writability
697 # Do it with S_IWOTH and S_IWGRP for portability (maybe)
699 if (($info[2] & &Fcntl::S_IWGRP) || # Is group writable?
700 ($info[2] & &Fcntl::S_IWOTH) ) { # Is world writable?
701 # Must be a directory
703 $$err_ref = "Path ($path) is not a directory"
707 # Must have sticky bit set
709 $$err_ref = "Sticky bit not set on $path when dir is group|world writable"
718 # Internal routine to check whether a directory is safe
719 # for temp files. Safer than _is_safe since it checks for
720 # the possibility of chown giveaway and if that is a possibility
721 # checks each directory in the path to see if it is safe (with _is_safe)
723 # If _PC_CHOWN_RESTRICTED is not set, does the full test of each
726 # Takes optional second arg as scalar ref to error reason
730 # Need POSIX - but only want to bother if really necessary due to overhead
734 print "_is_verysafe testing $path\n" if $DEBUG;
735 return 1 if $^O eq 'VMS'; # owner delete control at file level
739 # Should Get the value of _PC_CHOWN_RESTRICTED if it is defined
740 # and If it is not there do the extensive test
741 my $chown_restricted;
742 $chown_restricted = &POSIX::_PC_CHOWN_RESTRICTED()
743 if eval { &POSIX::_PC_CHOWN_RESTRICTED(); 1};
745 # If chown_resticted is set to some value we should test it
746 if (defined $chown_restricted) {
748 # Return if the current directory is safe
749 return _is_safe($path,$err_ref) if POSIX::sysconf( $chown_restricted );
753 # To reach this point either, the _PC_CHOWN_RESTRICTED symbol
754 # was not avialable or the symbol was there but chown giveaway
755 # is allowed. Either way, we now have to test the entire tree for
758 # Convert path to an absolute directory if required
759 unless (File::Spec->file_name_is_absolute($path)) {
760 $path = File::Spec->rel2abs($path);
763 # Split directory into components - assume no file
764 my ($volume, $directories, undef) = File::Spec->splitpath( $path, 1);
766 # Slightly less efficient than having a function in File::Spec
767 # to chop off the end of a directory or even a function that
768 # can handle ../ in a directory tree
769 # Sometimes splitdir() returns a blank at the end
770 # so we will probably check the bottom directory twice in some cases
771 my @dirs = File::Spec->splitdir($directories);
773 # Concatenate one less directory each time around
774 foreach my $pos (0.. $#dirs) {
775 # Get a directory name
776 my $dir = File::Spec->catpath($volume,
777 File::Spec->catdir(@dirs[0.. $#dirs - $pos]),
781 print "TESTING DIR $dir\n" if $DEBUG;
783 # Check the directory
784 return 0 unless _is_safe($dir,$err_ref);
793 # internal routine to determine whether unlink works on this
794 # platform for files that are currently open.
795 # Returns true if we can, false otherwise.
797 # Currently WinNT, OS/2 and VMS can not unlink an opened file
798 # On VMS this is because the O_EXCL flag is used to open the
799 # temporary file. Currently I do not know enough about the issues
800 # on VMS to decide whether O_EXCL is a requirement.
802 sub _can_unlink_opened_file {
804 if ($^O eq 'MSWin32' || $^O eq 'os2' || $^O eq 'VMS' || $^O eq 'dos' || $^O eq 'MacOS') {
812 # internal routine to decide which security levels are allowed
813 # see safe_level() for more information on this
815 # Controls whether the supplied security level is allowed
817 # $cando = _can_do_level( $level )
824 # Always have to be able to do STANDARD
825 return 1 if $level == STANDARD;
827 # Currently, the systems that can do HIGH or MEDIUM are identical
828 if ( $^O eq 'MSWin32' || $^O eq 'os2' || $^O eq 'cygwin' || $^O eq 'dos' || $^O eq 'MacOS' || $^O eq 'mpeix') {
836 # This routine sets up a deferred unlinking of a specified
837 # filename and filehandle. It is used in the following cases:
838 # - Called by unlink0 if an opened file can not be unlinked
839 # - Called by tempfile() if files are to be removed on shutdown
840 # - Called by tempdir() if directories are to be removed on shutdown
843 # _deferred_unlink( $fh, $fname, $isdir );
845 # - filehandle (so that it can be expclicitly closed if open
846 # - filename (the thing we want to remove)
847 # - isdir (flag to indicate that we are being given a directory)
848 # [and hence no filehandle]
850 # Status is not referred to since all the magic is done with an END block
853 # Will set up two lexical variables to contain all the files to be
854 # removed. One array for files, another for directories They will
855 # only exist in this block.
857 # This means we only have to set up a single END block to remove
860 # in order to prevent child processes inadvertently deleting the parent
861 # temp files we use a hash to store the temp files and directories
862 # created by a particular process id.
864 # %files_to_unlink contains values that are references to an array of
865 # array references containing the filehandle and filename associated with
867 my (%files_to_unlink, %dirs_to_unlink);
869 # Set up an end block to use these arrays
874 # Cleanup function. Always triggered on END but can be invoked
879 my @files = (exists $files_to_unlink{$$} ?
880 @{ $files_to_unlink{$$} } : () );
881 foreach my $file (@files) {
882 # close the filehandle without checking its state
883 # in order to make real sure that this is closed
884 # if its already closed then I dont care about the answer
885 # probably a better way to do this
886 close($file->[0]); # file handle is [0]
888 if (-f $file->[1]) { # file name is [1]
889 _force_writable( $file->[1] ); # for windows
890 unlink $file->[1] or warn "Error removing ".$file->[1];
894 my @dirs = (exists $dirs_to_unlink{$$} ?
895 @{ $dirs_to_unlink{$$} } : () );
896 foreach my $dir (@dirs) {
898 rmtree($dir, $DEBUG, 0);
903 @{ $files_to_unlink{$$} } = ()
904 if exists $files_to_unlink{$$};
905 @{ $dirs_to_unlink{$$} } = ()
906 if exists $dirs_to_unlink{$$};
911 # This is the sub called to register a file for deferred unlinking
912 # This could simply store the input parameters and defer everything
913 # until the END block. For now we do a bit of checking at this
914 # point in order to make sure that (1) we have a file/dir to delete
915 # and (2) we have been called with the correct arguments.
916 sub _deferred_unlink {
918 croak 'Usage: _deferred_unlink($fh, $fname, $isdir)'
919 unless scalar(@_) == 3;
921 my ($fh, $fname, $isdir) = @_;
923 warn "Setting up deferred removal of $fname\n"
926 # If we have a directory, check that it is a directory
931 # Directory exists so store it
932 # first on VMS turn []foo into [.foo] for rmtree
933 $fname = VMS::Filespec::vmspath($fname) if $^O eq 'VMS';
934 $dirs_to_unlink{$$} = []
935 unless exists $dirs_to_unlink{$$};
936 push (@{ $dirs_to_unlink{$$} }, $fname);
939 carp "Request to remove directory $fname could not be completed since it does not exist!\n" if $^W;
946 # file exists so store handle and name for later removal
947 $files_to_unlink{$$} = []
948 unless exists $files_to_unlink{$$};
949 push(@{ $files_to_unlink{$$} }, [$fh, $fname]);
952 carp "Request to remove file $fname could not be completed since it is not there!\n" if $^W;
962 =head1 OBJECT-ORIENTED INTERFACE
964 This is the primary interface for interacting with
965 C<File::Temp>. Using the OO interface a temporary file can be created
966 when the object is constructed and the file can be removed when the
967 object is no longer required.
969 Note that there is no method to obtain the filehandle from the
970 C<File::Temp> object. The object itself acts as a filehandle. Also,
971 the object is configured such that it stringifies to the name of the
978 Create a temporary file object.
980 my $tmp = new File::Temp();
982 by default the object is constructed as if C<tempfile>
983 was called without options, but with the additional behaviour
984 that the temporary file is removed by the object destructor
985 if UNLINK is set to true (the default).
987 Supported arguments are the same as for C<tempfile>: UNLINK
988 (defaulting to true), DIR and SUFFIX. Additionally, the filename
989 template is specified using the TEMPLATE option. The OPEN option
990 is not supported (the file is always opened).
992 $tmp = new File::Temp( TEMPLATE => 'tempXXXXX',
996 Arguments are case insensitive.
1002 my $class = ref($proto) || $proto;
1004 # read arguments and convert keys to upper case
1006 %args = map { uc($_), $args{$_} } keys %args;
1008 # see if they are unlinking (defaulting to yes)
1009 my $unlink = (exists $args{UNLINK} ? $args{UNLINK} : 1 );
1010 delete $args{UNLINK};
1012 # template (store it in an error so that it will
1013 # disappear from the arg list of tempfile
1014 my @template = ( exists $args{TEMPLATE} ? $args{TEMPLATE} : () );
1015 delete $args{TEMPLATE};
1020 # Open the file and retain file handle and file name
1021 my ($fh, $path) = tempfile( @template, %args );
1023 print "Tmp: $fh - $path\n" if $DEBUG;
1025 # Store the filename in the scalar slot
1028 # Store unlink information in hash slot (plus other constructor info)
1034 # final method-based configuration
1035 $fh->unlink_on_destroy( $unlink );
1042 Return the name of the temporary file associated with this object.
1044 $filename = $tmp->filename;
1046 This method is called automatically when the object is used as
1058 return $self->filename;
1061 =item B<unlink_on_destroy>
1063 Control whether the file is unlinked when the object goes out of scope.
1064 The file is removed if this value is true and $KEEP_ALL is not.
1066 $fh->unlink_on_destroy( 1 );
1068 Default is for the file to be removed.
1072 sub unlink_on_destroy {
1075 ${*$self}{UNLINK} = shift;
1077 return ${*$self}{UNLINK};
1082 When the object goes out of scope, the destructor is called. This
1083 destructor will attempt to unlink the file (using C<unlink1>)
1084 if the constructor was called with UNLINK set to 1 (the default state
1085 if UNLINK is not specified).
1087 No error is given if the unlink fails.
1089 If the global variable $KEEP_ALL is true, the file will not be removed.
1095 if (${*$self}{UNLINK} && !$KEEP_ALL) {
1096 print "# ---------> Unlinking $self\n" if $DEBUG;
1098 # The unlink1 may fail if the file has been closed
1099 # by the caller. This leaves us with the decision
1100 # of whether to refuse to remove the file or simply
1101 # do an unlink without test. Seems to be silly
1102 # to do this when we are trying to be careful
1104 _force_writable( $self->filename ); # for windows
1105 unlink1( $self, $self->filename )
1106 or unlink($self->filename);
1114 This section describes the recommended interface for generating
1115 temporary files and directories.
1121 This is the basic function to generate temporary files.
1122 The behaviour of the file can be changed using various options:
1125 ($fh, $filename) = tempfile();
1127 Create a temporary file in the directory specified for temporary
1128 files, as specified by the tmpdir() function in L<File::Spec>.
1130 ($fh, $filename) = tempfile($template);
1132 Create a temporary file in the current directory using the supplied
1133 template. Trailing `X' characters are replaced with random letters to
1134 generate the filename. At least four `X' characters must be present
1135 at the end of the template.
1137 ($fh, $filename) = tempfile($template, SUFFIX => $suffix)
1139 Same as previously, except that a suffix is added to the template
1140 after the `X' translation. Useful for ensuring that a temporary
1141 filename has a particular extension when needed by other applications.
1142 But see the WARNING at the end.
1144 ($fh, $filename) = tempfile($template, DIR => $dir);
1146 Translates the template as before except that a directory name
1149 ($fh, $filename) = tempfile($template, UNLINK => 1);
1151 Return the filename and filehandle as before except that the file is
1152 automatically removed when the program exits (dependent on
1153 $KEEP_ALL). Default is for the file to be removed if a file handle is
1154 requested and to be kept if the filename is requested. In a scalar
1155 context (where no filename is returned) the file is always deleted
1156 either (depending on the operating system) on exit or when it is
1157 closed (unless $KEEP_ALL is true when the temp file is created).
1159 Use the object-oriented interface if fine-grained control of when
1160 a file is removed is required.
1162 If the template is not specified, a template is always
1163 automatically generated. This temporary file is placed in tmpdir()
1164 (L<File::Spec>) unless a directory is specified explicitly with the
1167 $fh = tempfile( $template, DIR => $dir );
1169 If called in scalar context, only the filehandle is returned and the
1170 file will automatically be deleted when closed on operating systems
1171 that support this (see the description of tmpfile() elsewhere in this
1172 document). This is the preferred mode of operation, as if you only
1173 have a filehandle, you can never create a race condition by fumbling
1174 with the filename. On systems that can not unlink an open file or can
1175 not mark a file as temporary when it is opened (for example, Windows
1176 NT uses the C<O_TEMPORARY> flag) the file is marked for deletion when
1177 the program ends (equivalent to setting UNLINK to 1). The C<UNLINK>
1178 flag is ignored if present.
1180 (undef, $filename) = tempfile($template, OPEN => 0);
1182 This will return the filename based on the template but
1183 will not open this file. Cannot be used in conjunction with
1184 UNLINK set to true. Default is to always open the file
1185 to protect from possible race conditions. A warning is issued
1186 if warnings are turned on. Consider using the tmpnam()
1187 and mktemp() functions described elsewhere in this document
1188 if opening the file is not required.
1190 Options can be combined as required.
1196 # Can not check for argument count since we can have any
1201 "DIR" => undef, # Directory prefix
1202 "SUFFIX" => '', # Template suffix
1203 "UNLINK" => 0, # Do not unlink file on exit
1204 "OPEN" => 1, # Open file
1207 # Check to see whether we have an odd or even number of arguments
1208 my $template = (scalar(@_) % 2 == 1 ? shift(@_) : undef);
1210 # Read the options and merge with defaults
1211 %options = (%options, @_) if @_;
1213 # First decision is whether or not to open the file
1214 if (! $options{"OPEN"}) {
1216 warn "tempfile(): temporary filename requested but not opened.\nPossibly unsafe, consider using tempfile() with OPEN set to true\n"
1221 if ($options{"DIR"} and $^O eq 'VMS') {
1223 # on VMS turn []foo into [.foo] for concatenation
1224 $options{"DIR"} = VMS::Filespec::vmspath($options{"DIR"});
1227 # Construct the template
1229 # Have a choice of trying to work around the mkstemp/mktemp/tmpnam etc
1230 # functions or simply constructing a template and using _gettemp()
1231 # explicitly. Go for the latter
1233 # First generate a template if not defined and prefix the directory
1234 # If no template must prefix the temp directory
1235 if (defined $template) {
1236 if ($options{"DIR"}) {
1238 $template = File::Spec->catfile($options{"DIR"}, $template);
1244 if ($options{"DIR"}) {
1246 $template = File::Spec->catfile($options{"DIR"}, TEMPXXX);
1250 $template = File::Spec->catfile(File::Spec->tmpdir, TEMPXXX);
1257 $template .= $options{"SUFFIX"};
1259 # Determine whether we should tell _gettemp to unlink the file
1260 # On unix this is irrelevant and can be worked out after the file is
1261 # opened (simply by unlinking the open filehandle). On Windows or VMS
1262 # we have to indicate temporary-ness when we open the file. In general
1263 # we only want a true temporary file if we are returning just the
1264 # filehandle - if the user wants the filename they probably do not
1265 # want the file to disappear as soon as they close it (which may be
1266 # important if they want a child process to use the file)
1267 # For this reason, tie unlink_on_close to the return context regardless
1269 my $unlink_on_close = ( wantarray ? 0 : 1);
1272 my ($fh, $path, $errstr);
1273 croak "Error in tempfile() using $template: $errstr"
1274 unless (($fh, $path) = _gettemp($template,
1275 "open" => $options{'OPEN'},
1277 "unlink_on_close" => $unlink_on_close,
1278 "suffixlen" => length($options{'SUFFIX'}),
1279 "ErrStr" => \$errstr,
1282 # Set up an exit handler that can do whatever is right for the
1283 # system. This removes files at exit when requested explicitly or when
1284 # system is asked to unlink_on_close but is unable to do so because
1285 # of OS limitations.
1286 # The latter should be achieved by using a tied filehandle.
1287 # Do not check return status since this is all done with END blocks.
1288 _deferred_unlink($fh, $path, 0) if $options{"UNLINK"};
1293 if ($options{'OPEN'}) {
1294 return ($fh, $path);
1296 return (undef, $path);
1301 # Unlink the file. It is up to unlink0 to decide what to do with
1302 # this (whether to unlink now or to defer until later)
1303 unlink0($fh, $path) or croak "Error unlinking file $path using unlink0";
1305 # Return just the filehandle.
1314 This is the recommended interface for creation of temporary directories.
1315 The behaviour of the function depends on the arguments:
1317 $tempdir = tempdir();
1319 Create a directory in tmpdir() (see L<File::Spec|File::Spec>).
1321 $tempdir = tempdir( $template );
1323 Create a directory from the supplied template. This template is
1324 similar to that described for tempfile(). `X' characters at the end
1325 of the template are replaced with random letters to construct the
1326 directory name. At least four `X' characters must be in the template.
1328 $tempdir = tempdir ( DIR => $dir );
1330 Specifies the directory to use for the temporary directory.
1331 The temporary directory name is derived from an internal template.
1333 $tempdir = tempdir ( $template, DIR => $dir );
1335 Prepend the supplied directory name to the template. The template
1336 should not include parent directory specifications itself. Any parent
1337 directory specifications are removed from the template before
1338 prepending the supplied directory.
1340 $tempdir = tempdir ( $template, TMPDIR => 1 );
1342 Using the supplied template, create the temporary directory in
1343 a standard location for temporary files. Equivalent to doing
1345 $tempdir = tempdir ( $template, DIR => File::Spec->tmpdir);
1347 but shorter. Parent directory specifications are stripped from the
1348 template itself. The C<TMPDIR> option is ignored if C<DIR> is set
1349 explicitly. Additionally, C<TMPDIR> is implied if neither a template
1350 nor a directory are supplied.
1352 $tempdir = tempdir( $template, CLEANUP => 1);
1354 Create a temporary directory using the supplied template, but
1355 attempt to remove it (and all files inside it) when the program
1356 exits. Note that an attempt will be made to remove all files from
1357 the directory even if they were not created by this module (otherwise
1358 why ask to clean it up?). The directory removal is made with
1359 the rmtree() function from the L<File::Path|File::Path> module.
1360 Of course, if the template is not specified, the temporary directory
1361 will be created in tmpdir() and will also be removed at program exit.
1369 # Can not check for argument count since we can have any
1374 "CLEANUP" => 0, # Remove directory on exit
1375 "DIR" => '', # Root directory
1376 "TMPDIR" => 0, # Use tempdir with template
1379 # Check to see whether we have an odd or even number of arguments
1380 my $template = (scalar(@_) % 2 == 1 ? shift(@_) : undef );
1382 # Read the options and merge with defaults
1383 %options = (%options, @_) if @_;
1385 # Modify or generate the template
1387 # Deal with the DIR and TMPDIR options
1388 if (defined $template) {
1390 # Need to strip directory path if using DIR or TMPDIR
1391 if ($options{'TMPDIR'} || $options{'DIR'}) {
1393 # Strip parent directory from the filename
1395 # There is no filename at the end
1396 $template = VMS::Filespec::vmspath($template) if $^O eq 'VMS';
1397 my ($volume, $directories, undef) = File::Spec->splitpath( $template, 1);
1399 # Last directory is then our template
1400 $template = (File::Spec->splitdir($directories))[-1];
1402 # Prepend the supplied directory or temp dir
1403 if ($options{"DIR"}) {
1405 $template = File::Spec->catdir($options{"DIR"}, $template);
1407 } elsif ($options{TMPDIR}) {
1410 $template = File::Spec->catdir(File::Spec->tmpdir, $template);
1418 if ($options{"DIR"}) {
1420 $template = File::Spec->catdir($options{"DIR"}, TEMPXXX);
1424 $template = File::Spec->catdir(File::Spec->tmpdir, TEMPXXX);
1430 # Create the directory
1433 if ($^O eq 'VMS') { # dir names can end in delimiters
1434 $template =~ m/([\.\]:>]+)$/;
1435 $suffixlen = length($1);
1437 if ( ($^O eq 'MacOS') && (substr($template, -1) eq ':') ) {
1438 # dir name has a trailing ':'
1443 croak "Error in tempdir() using $template: $errstr"
1444 unless ((undef, $tempdir) = _gettemp($template,
1447 "suffixlen" => $suffixlen,
1448 "ErrStr" => \$errstr,
1451 # Install exit handler; must be dynamic to get lexical
1452 if ( $options{'CLEANUP'} && -d $tempdir) {
1453 _deferred_unlink(undef, $tempdir, 1);
1456 # Return the dir name
1463 =head1 MKTEMP FUNCTIONS
1465 The following functions are Perl implementations of the
1466 mktemp() family of temp file generation system calls.
1472 Given a template, returns a filehandle to the temporary file and the name
1475 ($fh, $name) = mkstemp( $template );
1477 In scalar context, just the filehandle is returned.
1479 The template may be any filename with some number of X's appended
1480 to it, for example F</tmp/temp.XXXX>. The trailing X's are replaced
1481 with unique alphanumeric combinations.
1489 croak "Usage: mkstemp(template)"
1492 my $template = shift;
1494 my ($fh, $path, $errstr);
1495 croak "Error in mkstemp using $template: $errstr"
1496 unless (($fh, $path) = _gettemp($template,
1500 "ErrStr" => \$errstr,
1504 return ($fh, $path);
1514 Similar to mkstemp(), except that an extra argument can be supplied
1515 with a suffix to be appended to the template.
1517 ($fh, $name) = mkstemps( $template, $suffix );
1519 For example a template of C<testXXXXXX> and suffix of C<.dat>
1520 would generate a file similar to F<testhGji_w.dat>.
1522 Returns just the filehandle alone when called in scalar context.
1528 croak "Usage: mkstemps(template, suffix)"
1532 my $template = shift;
1535 $template .= $suffix;
1537 my ($fh, $path, $errstr);
1538 croak "Error in mkstemps using $template: $errstr"
1539 unless (($fh, $path) = _gettemp($template,
1542 "suffixlen" => length($suffix),
1543 "ErrStr" => \$errstr,
1547 return ($fh, $path);
1556 Create a directory from a template. The template must end in
1557 X's that are replaced by the routine.
1559 $tmpdir_name = mkdtemp($template);
1561 Returns the name of the temporary directory created.
1562 Returns undef on failure.
1564 Directory must be removed by the caller.
1572 croak "Usage: mkdtemp(template)"
1575 my $template = shift;
1577 if ($^O eq 'VMS') { # dir names can end in delimiters
1578 $template =~ m/([\.\]:>]+)$/;
1579 $suffixlen = length($1);
1581 if ( ($^O eq 'MacOS') && (substr($template, -1) eq ':') ) {
1582 # dir name has a trailing ':'
1585 my ($junk, $tmpdir, $errstr);
1586 croak "Error creating temp directory from template $template\: $errstr"
1587 unless (($junk, $tmpdir) = _gettemp($template,
1590 "suffixlen" => $suffixlen,
1591 "ErrStr" => \$errstr,
1600 Returns a valid temporary filename but does not guarantee
1601 that the file will not be opened by someone else.
1603 $unopened_file = mktemp($template);
1605 Template is the same as that required by mkstemp().
1611 croak "Usage: mktemp(template)"
1614 my $template = shift;
1616 my ($tmpname, $junk, $errstr);
1617 croak "Error getting name to temp file from template $template: $errstr"
1618 unless (($junk, $tmpname) = _gettemp($template,
1622 "ErrStr" => \$errstr,
1630 =head1 POSIX FUNCTIONS
1632 This section describes the re-implementation of the tmpnam()
1633 and tmpfile() functions described in L<POSIX>
1634 using the mkstemp() from this module.
1636 Unlike the L<POSIX|POSIX> implementations, the directory used
1637 for the temporary file is not specified in a system include
1638 file (C<P_tmpdir>) but simply depends on the choice of tmpdir()
1639 returned by L<File::Spec|File::Spec>. On some implementations this
1640 location can be set using the C<TMPDIR> environment variable, which
1642 If this is a problem, simply use mkstemp() and specify a template.
1648 When called in scalar context, returns the full name (including path)
1649 of a temporary file (uses mktemp()). The only check is that the file does
1650 not already exist, but there is no guarantee that that condition will
1655 When called in list context, a filehandle to the open file and
1656 a filename are returned. This is achieved by calling mkstemp()
1657 after constructing a suitable template.
1659 ($fh, $file) = tmpnam();
1661 If possible, this form should be used to prevent possible
1664 See L<File::Spec/tmpdir> for information on the choice of temporary
1665 directory for a particular operating system.
1671 # Retrieve the temporary directory name
1672 my $tmpdir = File::Spec->tmpdir;
1674 croak "Error temporary directory is not writable"
1677 # Use a ten character template and append to tmpdir
1678 my $template = File::Spec->catfile($tmpdir, TEMPXXX);
1681 return mkstemp($template);
1683 return mktemp($template);
1690 Returns the filehandle of a temporary file.
1694 The file is removed when the filehandle is closed or when the program
1695 exits. No access to the filename is provided.
1697 If the temporary file can not be created undef is returned.
1698 Currently this command will probably not work when the temporary
1699 directory is on an NFS file system.
1705 # Simply call tmpnam() in a list context
1706 my ($fh, $file) = tmpnam();
1708 # Make sure file is removed when filehandle is closed
1709 # This will fail on NFS
1719 =head1 ADDITIONAL FUNCTIONS
1721 These functions are provided for backwards compatibility
1722 with common tempfile generation C library functions.
1724 They are not exported and must be addressed using the full package
1731 Return the name of a temporary file in the specified directory
1732 using a prefix. The file is guaranteed not to exist at the time
1733 the function was called, but such guarantees are good for one
1734 clock tick only. Always use the proper form of C<sysopen>
1735 with C<O_CREAT | O_EXCL> if you must open such a filename.
1737 $filename = File::Temp::tempnam( $dir, $prefix );
1739 Equivalent to running mktemp() with $dir/$prefixXXXXXXXX
1740 (using unix file convention as an example)
1742 Because this function uses mktemp(), it can suffer from race conditions.
1748 croak 'Usage tempnam($dir, $prefix)' unless scalar(@_) == 2;
1750 my ($dir, $prefix) = @_;
1752 # Add a string to the prefix
1753 $prefix .= 'XXXXXXXX';
1755 # Concatenate the directory to the file
1756 my $template = File::Spec->catfile($dir, $prefix);
1758 return mktemp($template);
1764 =head1 UTILITY FUNCTIONS
1766 Useful functions for dealing with the filehandle and filename.
1772 Given an open filehandle and the associated filename, make a safe
1773 unlink. This is achieved by first checking that the filename and
1774 filehandle initially point to the same file and that the number of
1775 links to the file is 1 (all fields returned by stat() are compared).
1776 Then the filename is unlinked and the filehandle checked once again to
1777 verify that the number of links on that file is now 0. This is the
1778 closest you can come to making sure that the filename unlinked was the
1779 same as the file whose descriptor you hold.
1782 or die "Error unlinking file $path safely";
1784 Returns false on error. The filehandle is not closed since on some
1785 occasions this is not required.
1787 On some platforms, for example Windows NT, it is not possible to
1788 unlink an open file (the file must be closed first). On those
1789 platforms, the actual unlinking is deferred until the program ends and
1790 good status is returned. A check is still performed to make sure that
1791 the filehandle and filename are pointing to the same thing (but not at
1792 the time the end block is executed since the deferred removal may not
1793 have access to the filehandle).
1795 Additionally, on Windows NT not all the fields returned by stat() can
1796 be compared. For example, the C<dev> and C<rdev> fields seem to be
1797 different. Also, it seems that the size of the file returned by stat()
1798 does not always agree, with C<stat(FH)> being more accurate than
1799 C<stat(filename)>, presumably because of caching issues even when
1800 using autoflush (this is usually overcome by waiting a while after
1801 writing to the tempfile before attempting to C<unlink0> it).
1803 Finally, on NFS file systems the link count of the file handle does
1804 not always go to zero immediately after unlinking. Currently, this
1805 command is expected to fail on NFS disks.
1807 This function is disabled if the global variable $KEEP_ALL is true
1808 and an unlink on open file is supported. If the unlink is to be deferred
1809 to the END block, the file is still registered for removal.
1815 croak 'Usage: unlink0(filehandle, filename)'
1816 unless scalar(@_) == 2;
1819 my ($fh, $path) = @_;
1821 cmpstat($fh, $path) or return 0;
1823 # attempt remove the file (does not work on some platforms)
1824 if (_can_unlink_opened_file()) {
1826 # return early (Without unlink) if we have been instructed to retain files.
1827 return 1 if $KEEP_ALL;
1829 # XXX: do *not* call this on a directory; possible race
1830 # resulting in recursive removal
1831 croak "unlink0: $path has become a directory!" if -d $path;
1832 unlink($path) or return 0;
1834 # Stat the filehandle
1837 print "Link count = $fh[3] \n" if $DEBUG;
1839 # Make sure that the link count is zero
1840 # - Cygwin provides deferred unlinking, however,
1841 # on Win9x the link count remains 1
1842 # On NFS the link count may still be 1 but we cant know that
1844 return ( $fh[3] == 0 or $^O eq 'cygwin' ? 1 : 0);
1847 _deferred_unlink($fh, $path, 0);
1855 Compare C<stat> of filehandle with C<stat> of provided filename. This
1856 can be used to check that the filename and filehandle initially point
1857 to the same file and that the number of links to the file is 1 (all
1858 fields returned by stat() are compared).
1861 or die "Error comparing handle with file";
1863 Returns false if the stat information differs or if the link count is
1866 On certain platforms, e.g. Windows, not all the fields returned by stat()
1867 can be compared. For example, the C<dev> and C<rdev> fields seem to be
1868 different in Windows. Also, it seems that the size of the file
1869 returned by stat() does not always agree, with C<stat(FH)> being more
1870 accurate than C<stat(filename)>, presumably because of caching issues
1871 even when using autoflush (this is usually overcome by waiting a while
1872 after writing to the tempfile before attempting to C<unlink0> it).
1874 Not exported by default.
1880 croak 'Usage: cmpstat(filehandle, filename)'
1881 unless scalar(@_) == 2;
1884 my ($fh, $path) = @_;
1886 warn "Comparing stat\n"
1889 # Stat the filehandle - which may be closed if someone has manually
1890 # closed the file. Can not turn off warnings without using $^W
1891 # unless we upgrade to 5.006 minimum requirement
1899 if ($fh[3] > 1 && $^W) {
1900 carp "unlink0: fstat found too many links; SB=@fh" if $^W;
1904 my @path = stat $path;
1907 carp "unlink0: $path is gone already" if $^W;
1911 # this is no longer a file, but may be a directory, or worse
1913 confess "panic: $path is no longer a file: SB=@fh";
1916 # Do comparison of each member of the array
1917 # On WinNT dev and rdev seem to be different
1918 # depending on whether it is a file or a handle.
1919 # Cannot simply compare all members of the stat return
1920 # Select the ones we can use
1921 my @okstat = (0..$#fh); # Use all by default
1922 if ($^O eq 'MSWin32') {
1923 @okstat = (1,2,3,4,5,7,8,9,10);
1924 } elsif ($^O eq 'os2') {
1925 @okstat = (0, 2..$#fh);
1926 } elsif ($^O eq 'VMS') { # device and file ID are sufficient
1928 } elsif ($^O eq 'dos') {
1929 @okstat = (0,2..7,11..$#fh);
1930 } elsif ($^O eq 'mpeix') {
1931 @okstat = (0..4,8..10);
1934 # Now compare each entry explicitly by number
1936 print "Comparing: $_ : $fh[$_] and $path[$_]\n" if $DEBUG;
1937 # Use eq rather than == since rdev, blksize, and blocks (6, 11,
1938 # and 12) will be '' on platforms that do not support them. This
1939 # is fine since we are only comparing integers.
1940 unless ($fh[$_] eq $path[$_]) {
1941 warn "Did not match $_ element of stat\n" if $DEBUG;
1951 Similar to C<unlink0> except after file comparison using cmpstat, the
1952 filehandle is closed prior to attempting to unlink the file. This
1953 allows the file to be removed without using an END block, but does
1954 mean that the post-unlink comparison of the filehandle state provided
1955 by C<unlink0> is not available.
1958 or die "Error closing and unlinking file";
1960 Usually called from the object destructor when using the OO interface.
1962 Not exported by default.
1964 This function is disabled if the global variable $KEEP_ALL is true.
1969 croak 'Usage: unlink1(filehandle, filename)'
1970 unless scalar(@_) == 2;
1973 my ($fh, $path) = @_;
1975 cmpstat($fh, $path) or return 0;
1978 close( $fh ) or return 0;
1980 # Make sure the file is writable (for windows)
1981 _force_writable( $path );
1983 # return early (without unlink) if we have been instructed to retain files.
1984 return 1 if $KEEP_ALL;
1987 return unlink($path);
1992 Calling this function will cause any temp files or temp directories
1993 that are registered for removal to be removed. This happens automatically
1994 when the process exits but can be triggered manually if the caller is sure
1995 that none of the temp files are required. This method can be registered as
1998 On OSes where temp files are automatically removed when the temp file
1999 is closed, calling this function will have no effect other than to remove
2000 temporary directories (which may include temporary files).
2002 File::Temp::cleanup();
2004 Not exported by default.
2008 =head1 PACKAGE VARIABLES
2010 These functions control the global state of the package.
2016 Controls the lengths to which the module will go to check the safety of the
2017 temporary file or directory before proceeding.
2024 Do the basic security measures to ensure the directory exists and
2025 is writable, that the umask() is fixed before opening of the file,
2026 that temporary files are opened only if they do not already exist, and
2027 that possible race conditions are avoided. Finally the L<unlink0|"unlink0">
2028 function is used to remove files safely.
2032 In addition to the STANDARD security, the output directory is checked
2033 to make sure that it is owned either by root or the user running the
2034 program. If the directory is writable by group or by other, it is then
2035 checked to make sure that the sticky bit is set.
2037 Will not work on platforms that do not support the C<-k> test
2042 In addition to the MEDIUM security checks, also check for the
2043 possibility of ``chown() giveaway'' using the L<POSIX|POSIX>
2044 sysconf() function. If this is a possibility, each directory in the
2045 path is checked in turn for safeness, recursively walking back to the
2048 For platforms that do not support the L<POSIX|POSIX>
2049 C<_PC_CHOWN_RESTRICTED> symbol (for example, Windows NT) it is
2050 assumed that ``chown() giveaway'' is possible and the recursive test
2055 The level can be changed as follows:
2057 File::Temp->safe_level( File::Temp::HIGH );
2059 The level constants are not exported by the module.
2061 Currently, you must be running at least perl v5.6.0 in order to
2062 run with MEDIUM or HIGH security. This is simply because the
2063 safety tests use functions from L<Fcntl|Fcntl> that are not
2064 available in older versions of perl. The problem is that the version
2065 number for Fcntl is the same in perl 5.6.0 and in 5.005_03 even though
2066 they are different versions.
2068 On systems that do not support the HIGH or MEDIUM safety levels
2069 (for example Win NT or OS/2) any attempt to change the level will
2070 be ignored. The decision to ignore rather than raise an exception
2071 allows portable programs to be written with high security in mind
2072 for the systems that can support this without those programs failing
2073 on systems where the extra tests are irrelevant.
2075 If you really need to see whether the change has been accepted
2076 simply examine the return value of C<safe_level>.
2078 $newlevel = File::Temp->safe_level( File::Temp::HIGH );
2079 die "Could not change to high security"
2080 if $newlevel != File::Temp::HIGH;
2085 # protect from using the variable itself
2086 my $LEVEL = STANDARD;
2091 if (($level != STANDARD) && ($level != MEDIUM) && ($level != HIGH)) {
2092 carp "safe_level: Specified level ($level) not STANDARD, MEDIUM or HIGH - ignoring\n" if $^W;
2094 # Dont allow this on perl 5.005 or earlier
2095 if ($] < 5.006 && $level != STANDARD) {
2096 # Cant do MEDIUM or HIGH checks
2097 croak "Currently requires perl 5.006 or newer to do the safe checks";
2099 # Check that we are allowed to change level
2100 # Silently ignore if we can not.
2101 $LEVEL = $level if _can_do_level($level);
2110 This is the highest UID on the current system that refers to a root
2111 UID. This is used to make sure that the temporary directory is
2112 owned by a system UID (C<root>, C<bin>, C<sys> etc) rather than
2115 This is required since on many unix systems C</tmp> is not owned
2118 Default is to assume that any UID less than or equal to 10 is a root
2121 File::Temp->top_system_uid(10);
2122 my $topid = File::Temp->top_system_uid;
2124 This value can be adjusted to reduce security checking if required.
2125 The value is only relevant when C<safe_level> is set to MEDIUM or higher.
2130 my $TopSystemUID = 10;
2131 $TopSystemUID = 197108 if $^O eq 'interix'; # "Administrator"
2132 sub top_system_uid {
2136 croak "top_system_uid: UIDs should be numeric"
2137 unless $newuid =~ /^\d+$/s;
2138 $TopSystemUID = $newuid;
2140 return $TopSystemUID;
2146 Controls whether temporary files and directories should be retained
2147 regardless of any instructions in the program to remove them
2148 automatically. This is useful for debugging but should not be used in
2151 $File::Temp::KEEP_ALL = 1;
2153 Default is for files to be removed as requested by the caller.
2155 In some cases, files will only be retained if this variable is true
2156 when the file is created. This means that you can not create a temporary
2157 file, set this variable and expect the temp file to still be around
2158 when the program exits.
2162 Controls whether debugging messages should be enabled.
2164 $File::Temp::DEBUG = 1;
2166 Default is for debugging mode to be disabled.
2172 For maximum security, endeavour always to avoid ever looking at,
2173 touching, or even imputing the existence of the filename. You do not
2174 know that that filename is connected to the same file as the handle
2175 you have, and attempts to check this can only trigger more race
2176 conditions. It's far more secure to use the filehandle alone and
2177 dispense with the filename altogether.
2179 If you need to pass the handle to something that expects a filename
2180 then, on a unix system, use C<"/dev/fd/" . fileno($fh)> for arbitrary
2181 programs, or more generally C<< "+<=&" . fileno($fh) >> for Perl
2182 programs. You will have to clear the close-on-exec bit on that file
2183 descriptor before passing it to another process.
2185 use Fcntl qw/F_SETFD F_GETFD/;
2186 fcntl($tmpfh, F_SETFD, 0)
2187 or die "Can't clear close-on-exec flag on temp fh: $!\n";
2189 =head2 Temporary files and NFS
2191 Some problems are associated with using temporary files that reside
2192 on NFS file systems and it is recommended that a local filesystem
2193 is used whenever possible. Some of the security tests will most probably
2194 fail when the temp file is not local. Additionally, be aware that
2195 the performance of I/O operations over NFS will not be as good as for
2200 In some cases files created by File::Temp are removed from within an
2201 END block. Since END blocks are triggered when a child process exits
2202 (unless C<POSIX::_exit()> is used by the child) File::Temp takes care
2203 to only remove those temp files created by a particular process ID. This
2204 means that a child will not attempt to remove temp files created by the
2209 The file returned by File::Temp will have been opened in binary mode
2210 if such a mode is available. If that is not correct, use the binmode()
2211 function to change the mode of the filehandle.
2215 Originally began life in May 1999 as an XS interface to the system
2216 mkstemp() function. In March 2000, the OpenBSD mkstemp() code was
2217 translated to Perl for total control of the code's
2218 security checking, to ensure the presence of the function regardless of
2219 operating system and to help with portability. The module was shipped
2220 as a standard part of perl from v5.6.1.
2224 L<POSIX/tmpnam>, L<POSIX/tmpfile>, L<File::Spec>, L<File::Path>
2226 See L<IO::File> and L<File::MkTemp>, L<Apachae::TempFile> for
2227 different implementations of temporary file handling.
2231 Tim Jenness E<lt>tjenness@cpan.orgE<gt>
2233 Copyright (C) 1999-2005 Tim Jenness and the UK Particle Physics and
2234 Astronomy Research Council. All Rights Reserved. This program is free
2235 software; you can redistribute it and/or modify it under the same
2236 terms as Perl itself.
2238 Original Perl implementation loosely based on the OpenBSD C code for
2239 mkstemp(). Thanks to Tom Christiansen for suggesting that this module
2240 should be written and providing ideas for code improvements and
2241 security enhancements.