File::Temp(3) Perl Programmers Reference Guide File::Temp(3)NAMEFile::Temp - return name and handle of a temporary file
safely
SYNOPSIS
use File::Temp qw/ tempfile tempdir /;
$dir = tempdir( CLEANUP => 1 );
($fh, $filename) = tempfile( DIR => $dir );
($fh, $filename) = tempfile( $template, DIR => $dir);
($fh, $filename) = tempfile( $template, SUFFIX => '.dat');
$fh = tempfile();
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();
($fh, $file) = tmpfile();
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. 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 tem
porary directory.
The security aspect of temporary file creation is empha
sized 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 the section on "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 tmp_
nam() 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.
FUNCTIONS
This section describes the recommended interface for gen
erating 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, $filename) = tempfile();
Create a temporary file in the directory specified
for temporary files, as specified by the tmpdir()
function in the File::Spec manpage.
($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 in 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 direc
tory name is specified.
($fh, $filename) = tempfile($template, UNLINK => 1);
Return the filename and filehandle as before except
that the file is automatically removed when the pro
gram exits. Default is for the file to be removed if a
file handle is requested and to be kept if the file
name is requested. In a scalar context (where no file
name is returned) the file is always deleted either on
exit or when it is closed.
If the template is not specified, a template is always
automatically generated. This temporary file is placed
in tmpdir() (the File::Spec manpage) unless a direc
tory is specified explicitly with the DIR option.
$fh = tempfile( $template, DIR => $dir );
If called in scalar context, only the filehandle is
returned and the file will automatically be deleted
when closed (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 pro
gram 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 con
junction with UNLINK set to true. Default is to always
open the file to protect from possible race condi
tions. 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.
Options can be combined as required.
tempdir
This is the recommended interface for creation of tem
porary directories. The behaviour of the function
depends on the arguments:
$tempdir = tempdir();
Create a directory in tmpdir() (see File::Spec).
$tempdir = tempdir( $template );
Create a directory from the supplied template. This
template is similar to that described for tempfile().
`X' characters at the end of the template are replaced
with random letters to construct the directory name.
At least four `X' characters must be in the template.
$tempdir = tempdir ( DIR => $dir );
Specifies the directory to use for the temporary
directory. The temporary directory name is derived
from an internal template.
$tempdir = tempdir ( $template, DIR => $dir );
Prepend the supplied directory name to the template.
The template should not include parent directory spec
ifications itself. Any parent directory specifications
are removed from the template before prepending the
supplied directory.
$tempdir = tempdir ( $template, TMPDIR => 1 );
Using the supplied template, creat the temporary
directory in a standard location for temporary files.
Equivalent to doing
$tempdir = tempdir ( $template, DIR => File::Spec->tmpdir);
but shorter. Parent directory specifications are
stripped from the template itself. The "TMPDIR" option
is ignored if "DIR" is set explicitly. Additionally,
"TMPDIR" is implied if neither a template nor a
directory are supplied.
$tempdir = tempdir( $template, CLEANUP => 1);
Create a temporary directory using the supplied tem
plate, but attempt to remove it (and all files inside
it) when the program exits. Note that an attempt will
be made to remove all files from the directory even if
they were not created by this module (otherwise why
ask to clean it up?). The directory removal is made
with the rmtree() function from the File::Path module.
Of course, if the template is not specified, the tem
porary directory will be created in tmpdir() and will
also be removed at program exit.
MKTEMP FUNCTIONS
The following functions are Perl implementations of the
mktemp() family of temp file generation system calls.
mkstemp
Given a template, returns a filehandle to the tempo
rary file and the name of the file.
($fh, $name) = mkstemp( $template );
In scalar context, just the filehandle is returned.
The template may be any filename with some number of
X's appended to it, for example /tmp/temp.XXXX. The
trailing X's are replaced with unique alphanumeric
combinations.
mkstemps
Similar to mkstemp(), except that an extra argument
can be supplied with a suffix to be appended to the
template.
($fh, $name) = mkstemps( $template, $suffix );
For example a template of "testXXXXXX" and suffix of
".dat" would generate a file similar to
testhGji_w.dat.
Returns just the filehandle alone when called in
scalar context.
mkdtemp
Create a directory from a template. The template must
end in X's that are replaced by the routine.
$tmpdir_name = mkdtemp($template);
Returns the name of the temporary directory created.
Returns undef on failure.
Directory must be removed by the caller.
mktemp
Returns a valid temporary filename but does not guar
antee that the file will not be opened by someone
else.
$unopened_file = mktemp($template);
Template is the same as that required by mkstemp().
POSIX FUNCTIONS
This section describes the re-implementation of the tmp_
nam() and tmpfile() functions described in the POSIX man
page using the mkstemp() from this module.
Unlike the POSIX implementations, the directory used for
the temporary file is not specified in a system include
file ("P_tmpdir") but simply depends on the choice of
tmpdir() returned by File::Spec. On some implementations
this location can be set using the "TMPDIR" environment
variable, which may not be secure. If this is a problem,
simply use mkstemp() and specify a template.
tmpnam
When called in scalar context, returns the full name
(including path) of a temporary file (uses mktemp()).
The only check is that the file does not already
exist, but there is no guarantee that that condition
will continue to apply.
$file = tmpnam();
When called in list context, a filehandle to the open
file and a filename are returned. This is achieved by
calling mkstemp() after constructing a suitable tem
plate.
($fh, $file) = tmpnam();
If possible, this form should be used to prevent pos
sible race conditions.
See the tmpdir entry in the File::Spec manpage for
information on the choice of temporary directory for a
particular operating system.
tmpfile
In scalar context, returns the filehandle of a tempo
rary file.
$fh = tmpfile();
The file is removed when the filehandle is closed or
when the program exits. No access to the filename is
provided.
If the temporary file can not be created undef is
returned. Currently this command will probably not
work when the temporary directory is on an NFS file
system.
ADDITIONAL FUNCTIONS
These functions are provided for backwards compatibility
with common tempfile generation C library functions.
They are not exported and must be addressed using the full
package name.
tempnam
Return the name of a temporary file in the specified
directory using a prefix. The file is guaranteed not
to exist at the time the function was called, but such
guarantees are good for one clock tick only. Always
use the proper form of "sysopen" with "O_CREAT |
O_EXCL" if you must open such a filename.
$filename = File::Temp::tempnam( $dir, $prefix );
Equivalent to running mktemp() with $dir/$pre
fixXXXXXXXX (using unix file convention as an example)
Because this function uses mktemp(), it can suffer
from race conditions.
UTILITY FUNCTIONS
Useful functions for dealing with the filehandle and file
name.
unlink0
Given an open filehandle and the associated filename,
make a safe unlink. This is achieved by first checking
that the filename and filehandle initially point to
the same file and that the number of links to the file
is 1 (all fields returned by stat() are compared).
Then the filename is unlinked and the filehandle
checked once again to verify that the number of links
on that file is now 0. This is the closest you can
come to making sure that the filename unlinked was the
same as the file whose descriptor you hold.
unlink0($fh, $path) or die "Error unlinking file $path safely";
Returns false on error. The filehandle is not closed
since on some occasions this is not required.
On some platforms, for example Windows NT, it is not
possible to unlink an open file (the file must be
closed first). On those platforms, the actual unlink
ing is deferred until the program ends and good status
is returned. A check is still performed to make sure
that the filehandle and filename are pointing to the
same thing (but not at the time the end block is exe
cuted since the deferred removal may not have access
to the filehandle).
Additionally, on Windows NT not all the fields
returned by stat() can be compared. For example, the
"dev" and "rdev" fields seem to be different. Also,
it seems that the size of the file returned by stat()
does not always agree, with "stat(FH)" being more
accurate than "stat(filename)", presumably because of
caching issues even when using autoflush (this is usu
ally overcome by waiting a while after writing to the
tempfile before attempting to "unlink0" it).
Finally, on NFS file systems the link count of the
file handle does not always go to zero immediately
after unlinking. Currently, this command is expected
to fail on NFS disks.
PACKAGE VARIABLES
These functions control the global state of the package.
safe_level
Controls the lengths to which the module will go to
check the safety of the temporary file or directory
before proceeding. Options are:
STANDARD
Do the basic security measures to ensure the
directory exists and is writable, that the
umask() is fixed before opening of the file,
that temporary files are opened only if they
do not already exist, and that possible race
conditions are avoided. Finally the unlink0
function is used to remove files safely.
MEDIUM In addition to the STANDARD security, the out
put directory is checked to make sure that it
is owned either by root or the user running
the program. If the directory is writable by
group or by other, it is then checked to make
sure that the sticky bit is set.
Will not work on platforms that do not support
the "-k" test for sticky bit.
HIGH In addition to the MEDIUM security checks,
also check for the possibility of ``chown()
giveaway'' using the POSIX sysconf() function.
If this is a possibility, each directory in
the path is checked in turn for safeness,
recursively walking back to the root direc
tory.
For platforms that do not support the POSIX
"_PC_CHOWN_RESTRICTED" symbol (for example,
Windows NT) it is assumed that ``chown() give
away'' is possible and the recursive test is
performed.
The level can be changed as follows:
File::Temp->safe_level( File::Temp::HIGH );
The level constants are not exported by the module.
Currently, you must be running at least perl v5.6.0 in
order to run with MEDIUM or HIGH security. This is
simply because the safety tests use functions from
Fcntl that are not available in older versions of
perl. The problem is that the version number for Fcntl
is the same in perl 5.6.0 and in 5.005_03 even though
they are different versions.
On systems that do not support the HIGH or MEDIUM
safety levels (for example Win NT or OS/2) any attempt
to change the level will be ignored. The decision to
ignore rather than raise an exception allows portable
programs to be written with high security in mind for
the systems that can support this without those pro
grams failing on systems where the extra tests are
irrelevant.
If you really need to see whether the change has been
accepted simply examine the return value of
"safe_level".
$newlevel = File::Temp->safe_level( File::Temp::HIGH );
die "Could not change to high security"
if $newlevel != File::Temp::HIGH;
TopSystemUID
This is the highest UID on the current system that
refers to a root UID. This is used to make sure that
the temporary directory is owned by a system UID
("root", "bin", "sys" etc) rather than simply by root.
This is required since on many unix systems "/tmp" is
not owned by root.
Default is to assume that any UID less than or equal
to 10 is a root UID.
File::Temp->top_system_uid(10);
my $topid = File::Temp->top_system_uid;
This value can be adjusted to reduce security checking
if required. The value is only relevant when
"safe_level" is set to MEDIUM or higher.
WARNING
For maximum security, endeavour always to avoid ever look
ing at, touching, or even imputing the existence of the
filename. You do not know that that filename is connected
to the same file as the handle you have, and attempts to
check this can only trigger more race conditions. It's
far more secure to use the filehandle alone and dispense
with the filename altogether.
If you need to pass the handle to something that expects a
filename then, on a unix system, use ""/dev/fd/" .
fileno($fh)" for arbitrary programs, or more generally
""+<=&" . fileno($fh)" for Perl programs. You will have
to clear the close-on-exec bit on that file descriptor
before passing it to another process.
use Fcntl qw/F_SETFD F_GETFD/;
fcntl($tmpfh, F_SETFD, 0)
or die "Can't clear close-on-exec flag on temp fh: $!\n";
Temporary files and NFS
Some problems are associated with using temporary files
that reside on NFS file systems and it is recommended that
a local filesystem is used whenever possible. Some of the
security tests will most probably fail when the temp file
is not local. Additionally, be aware that the performance
of I/O operations over NFS will not be as good as for a
local disk.
HISTORY
Originally began life in May 1999 as an XS interface to
the system mkstemp() function. In March 2000, the OpenBSD
mkstemp() code was translated to Perl for total control of
the code's security checking, to ensure the presence of
the function regardless of operating system and to help
with portability.
SEE ALSO
the tmpnam entry in the POSIX manpage, the tmpfile entry
in the POSIX manpage, the File::Spec manpage, the
File::Path manpage
See the IO::File manpage and the File::MkTemp manpage for
different implementations of temporary file handling.
AUTHOR
Tim Jenness <t.jenness@jach.hawaii.edu>
Copyright (C) 1999-2001 Tim Jenness and the UK Particle
Physics and Astronomy Research Council. All Rights
Reserved. This program is free software; you can redis
tribute it and/or modify it under the same terms as Perl
itself.
Original Perl implementation loosely based on the OpenBSD
C code for mkstemp(). Thanks to Tom Christiansen for sug
gesting that this module should be written and providing
ideas for code improvements and security enhancements.
2001-03-03 perl v5.6.1 File::Temp(3)
