


File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


NAME
       File::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



2001-05-24                 perl v5.6.1                          1





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


       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.




2001-05-24                 perl v5.6.1                          2





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


             ($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() else-
           where 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 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 );




2001-05-24                 perl v5.6.1                          3





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


           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 direc-
           tory 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.



2001-05-24                 perl v5.6.1                          4





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


             ($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,



2001-05-24                 perl v5.6.1                          5





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


       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.



2001-05-24                 perl v5.6.1                          6





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


             $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.




2001-05-24                 perl v5.6.1                          7





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


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.



2001-05-24                 perl v5.6.1                          8





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


           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.





2001-05-24                 perl v5.6.1                          9





File::Temp(3p)   Perl Programmers Reference Guide  File::Temp(3p)


           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-05-24                 perl v5.6.1                         10


