You are viewing the version of this documentation from Perl 5.36.3. View the latest version

CONTENTS

NAME

File::Temp - return name and handle of a temporary file safely

VERSION

version 0.2311

SYNOPSIS

use File::Temp qw/ tempfile tempdir /;

$fh = tempfile();
($fh, $filename) = tempfile();

($fh, $filename) = tempfile( $template, DIR => $dir);
($fh, $filename) = tempfile( $template, SUFFIX => '.dat');
($fh, $filename) = tempfile( $template, TMPDIR => 1 );

binmode( $fh, ":utf8" );

$dir = tempdir( CLEANUP => 1 );
($fh, $filename) = tempfile( DIR => $dir );

Object interface:

require File::Temp;
use File::Temp ();
use File::Temp qw/ :seekable /;

$fh = File::Temp->new();
$fname = $fh->filename;

$fh = File::Temp->new(TEMPLATE => $template);
$fname = $fh->filename;

$tmp = File::Temp->new( UNLINK => 0, SUFFIX => '.dat' );
print $tmp "Some data\n";
print "Filename is $tmp\n";
$tmp->seek( 0, SEEK_END );

$dir = File::Temp->newdir(); # CLEANUP => 1 by default

The following interfaces are provided for compatibility with existing APIs. They should not be used in new code.

MkTemp family:

use File::Temp qw/ :mktemp  /;

($fh, $file) = mkstemp( "tmpfileXXXXX" );
($fh, $file) = mkstemps( "tmpfileXXXXXX", $suffix);

$tmpdir = mkdtemp( $template );

$unopened_file = mktemp( $template );

POSIX functions:

use File::Temp qw/ :POSIX /;

$file = tmpnam();
$fh = tmpfile();

($fh, $file) = tmpnam();

Compatibility functions:

$unopened_file = File::Temp::tempnam( $dir, $pfx );

DESCRIPTION

File::Temp can be used to create and open temporary files in a safe way. There is both a function interface and an object-oriented interface. The File::Temp constructor or the tempfile() function can be used to return the name and the open filehandle of a temporary file. The tempdir() function can be used to create a temporary directory.

The security aspect of temporary file creation is emphasized such that a filehandle and filename are returned together. This helps guarantee that a race condition can not occur where the temporary file is created by another process between checking for the existence of the file and its opening. Additional security levels are provided to check, for example, that the sticky bit is set on world writable directories. See "safe_level" for more information.

For compatibility with popular C library functions, Perl implementations of the mkstemp() family of functions are provided. These are, mkstemp(), mkstemps(), mkdtemp() and mktemp().

Additionally, implementations of the standard POSIX tmpnam() and tmpfile() functions are provided if required.

Implementations of mktemp(), tmpnam(), and tempnam() are provided, but should be used with caution since they return only a filename that was valid when function was called, so cannot guarantee that the file will not exist by the time the caller opens the filename.

Filehandles returned by these functions support the seekable methods.

OBJECT-ORIENTED INTERFACE

This is the primary interface for interacting with File::Temp. Using the OO interface a temporary file can be created when the object is constructed and the file can be removed when the object is no longer required.

Note that there is no method to obtain the filehandle from the File::Temp object. The object itself acts as a filehandle. The object isa IO::Handle and isa IO::Seekable so all those methods are available.

Also, the object is configured such that it stringifies to the name of the temporary file and so can be compared to a filename directly. It numifies to the refaddr the same as other handles and so can be compared to other handles with ==.

$fh eq $filename       # as a string
$fh != \*STDOUT        # as a number

Available since 0.14.

new

Create a temporary file object.

my $tmp = File::Temp->new();

by default the object is constructed as if tempfile was called without options, but with the additional behaviour that the temporary file is removed by the object destructor if UNLINK is set to true (the default).

Supported arguments are the same as for tempfile: UNLINK (defaulting to true), DIR, EXLOCK, PERMS and SUFFIX. Additionally, the filename template is specified using the TEMPLATE option. The OPEN option is not supported (the file is always opened).

$tmp = File::Temp->new( TEMPLATE => 'tempXXXXX',
                       DIR => 'mydir',
                       SUFFIX => '.dat');

Arguments are case insensitive.

Can call croak() if an error occurs.

Available since 0.14.

TEMPLATE available since 0.23

newdir

Create a temporary directory using an object oriented interface.

$dir = File::Temp->newdir();

By default the directory is deleted when the object goes out of scope.

Supports the same options as the tempdir function. Note that directories created with this method default to CLEANUP => 1.

$dir = File::Temp->newdir( $template, %options );

A template may be specified either with a leading template or with a TEMPLATE argument.

Available since 0.19.

TEMPLATE available since 0.23.

filename

Return the name of the temporary file associated with this object (if the object was created using the "new" constructor).

$filename = $tmp->filename;

This method is called automatically when the object is used as a string.

Current API available since 0.14

dirname

Return the name of the temporary directory associated with this object (if the object was created using the "newdir" constructor).

$dirname = $tmpdir->dirname;

This method is called automatically when the object is used in string context.

Control whether the file is unlinked when the object goes out of scope. The file is removed if this value is true and $KEEP_ALL is not.

$fh->unlink_on_destroy( 1 );

Default is for the file to be removed.

Current API available since 0.15

DESTROY

When the object goes out of scope, the destructor is called. This destructor will attempt to unlink the file (using unlink1) if the constructor was called with UNLINK set to 1 (the default state if UNLINK is not specified).

No error is given if the unlink fails.

If the object has been passed to a child process during a fork, the file will be deleted when the object goes out of scope in the parent.

For a temporary directory object the directory will be removed unless the CLEANUP argument was used in the constructor (and set to false) or unlink_on_destroy was modified after creation. Note that if a temp directory is your current directory, it cannot be removed - a warning will be given in this case. chdir() out of the directory before letting the object go out of scope.

If the global variable $KEEP_ALL is true, the file or directory will not be removed.

FUNCTIONS

This section describes the recommended interface for generating temporary files and directories.

tempfile

This is the basic function to generate temporary files. The behaviour of the file can be changed using various options:

$fh = tempfile();
($fh, $filename) = tempfile();

Create a temporary file in the directory specified for temporary files, as specified by the tmpdir() function in File::Spec.

($fh, $filename) = tempfile($template);

Create a temporary file in the current directory using the supplied template. Trailing `X' characters are replaced with random letters to generate the filename. At least four `X' characters must be present at the end of the template.

($fh, $filename) = tempfile($template, SUFFIX => $suffix)

Same as previously, except that a suffix is added to the template after the `X' translation. Useful for ensuring that a temporary filename has a particular extension when needed by other applications. But see the WARNING at the end.

($fh, $filename) = tempfile($template, DIR => $dir);

Translates the template as before except that a directory name is specified.

($fh, $filename) = tempfile($template, TMPDIR => 1);

Equivalent to specifying a DIR of "File::Spec->tmpdir", writing the file into the same temporary directory as would be used if no template was specified at all.

($fh, $filename) = tempfile($template, UNLINK => 1);

Return the filename and filehandle as before except that the file is automatically removed when the program exits (dependent on $KEEP_ALL). Default is for the file to be removed if a file handle is requested and to be kept if the filename is requested. In a scalar context (where no filename is returned) the file is always deleted either (depending on the operating system) on exit or when it is closed (unless $KEEP_ALL is true when the temp file is created).

Use the object-oriented interface if fine-grained control of when a file is removed is required.

If the template is not specified, a template is always automatically generated. This temporary file is placed in tmpdir() (File::Spec) unless a directory is specified explicitly with the DIR option.

$fh = tempfile( DIR => $dir );

If called in scalar context, only the filehandle is returned and the file will automatically be deleted when closed on operating systems that support this (see the description of tmpfile() elsewhere in this document). This is the preferred mode of operation, as if you only have a filehandle, you can never create a race condition by fumbling with the filename. On systems that can not unlink an open file or can not mark a file as temporary when it is opened (for example, Windows NT uses the O_TEMPORARY flag) the file is marked for deletion when the program ends (equivalent to setting UNLINK to 1). The UNLINK flag is ignored if present.

(undef, $filename) = tempfile($template, OPEN => 0);

This will return the filename based on the template but will not open this file. Cannot be used in conjunction with UNLINK set to true. Default is to always open the file to protect from possible race conditions. A warning is issued if warnings are turned on. Consider using the tmpnam() and mktemp() functions described elsewhere in this document if opening the file is not required.

To open the temporary filehandle with O_EXLOCK (open with exclusive file lock) use EXLOCK=>1. This is supported only by some operating systems (most notably BSD derived systems). By default EXLOCK will be false. Former File::Temp versions set EXLOCK to true, so to be sure to get an unlocked filehandle also with older versions, explicitly set EXLOCK=>0.

($fh, $filename) = tempfile($template, EXLOCK => 1);

By default, the temp file is created with 0600 file permissions. Use PERMS to change this:

($fh, $filename) = tempfile($template, PERMS => 0666);

Options can be combined as required.

Will croak() if there is an error.

Available since 0.05.

UNLINK flag available since 0.10.

TMPDIR flag available since 0.19.

EXLOCK flag available since 0.19.

PERMS flag available since 0.2310.

tempdir

This is the recommended interface for creation of temporary directories. By default the directory will not be removed on exit (that is, it won't be temporary; this behaviour can not be changed because of issues with backwards compatibility). To enable removal either use the CLEANUP option which will trigger removal on program exit, or consider using the "newdir" method in the object interface which will allow the directory to be cleaned up when the object goes out of scope.

The behaviour of the function depends on the arguments:

$tempdir = tempdir();

Create a directory in tmpdir() (see