README

Development of this module has moved to https://github.com/Perl-Toolchain-Gang/File-Temp


File::Temp - provides functions for generating temporary files

This is release V0.23 of File::Temp. This module can be used to
generate temporary files (providing a filename and filehandle) or directories.
Possible race conditions are avoided and some security checks are performed
(eg making sure the sticky bit is set on world writeable temp directories).

It could be considered to be in a late beta state since it has only been
tested on six operating systems. The Windows implementation is not
yet at release quality since currently files are only deleted when
the program exits (via an END block), this differs from the Unix
implementation where files can be deleted when the file is closed.

The object-oriented implementation can get around this problem by
making use of the object destructor to delete the file or directory
and is the recommended interface.

Please let me know if it fails on other operating systems.

INSTALLATION

 % perl Makefile.PL
 % make
 % make test
 % make install

TEST FAILURES

Test failures from lib/security saying "system possibly insecure"

Firstly, test failures from the ftmp-security are not necessarily
serious or indicative of a real security threat.  That being said,
they bear investigating.

The tests may fail for the following reasons.   Note that each of the
tests is run both in the building directory and the temporary
directory, as returned by File::Spec->tmpdir().

(1) If the directory the tests are being run is owned by somebody else
than the user running the tests, or root (uid 0).  This failure can
happen if the Perl source code distribution is unpacked in a way that
the user ids in the distribution package are used as-is.  Some tar
programs do this.

(2) If the directory the test are being run in is writable by group
or by other (remember: with UNIX/POSIX semantics, write access to
a directory means the right to add/remove files in that directory),
and there is no sticky bit set in the directory.  'Sticky bit' is
a feature used in some UNIXes to give extra protection to files: if
the bit is on a directory, no one but the owner (or the root) can remove
that file even if the permissions of the directory would allow file
removal by others.  This failure can happen if the permissions in the
directory simply are a bit too liberal for the tests' liking.  This
may or may not be a real problem: it depends on the permissions policy
used on this particular directory/project/system/site.  This failure
can also happen if the system either doesn't support the sticky bit
(this is the case with many non-UNIX platforms: in principle the
File::Temp should know about these platforms and skip the tests), or
if the system supports the sticky bit but for some reason or reasons
it is not being used.  This is for example the case with HP-UX: as of
HP-UX release 11.00, the sticky bit is very much supported, but HP-UX
doesn't use it on its /tmp directory as shipped.  Also as with the
permissions, some local policy might dictate that the stickiness is
not used.

(3) If the system supports the POSIX 'chown giveaway' feature and if
any of the parent directories of the temporary file back to the root
directory are 'unsafe', using the definitions given above in (1) and
(2).

See the documentation for the File::Temp module for more information
about the various security aspects.

REQUIREMENTS

Requires perl 5.6.0 or newer.
Perl 5.6.0 will give access to extra security checks.

Written completely in Perl. XS is not required.

File::Spec greater than or equal to 0.8 is required.
Fcntl from perl5.5.670 or higher [but will work without it].
The above two modules are standard on Perl 5.6

PLATFORMS

Tested on the following platforms:

 MacOSX 10.6.5, perl 5.12.2
 Linux CentOS 5.2, perl 5.8.9

Earlier versions were tested on:

 SUSe Linux 9.1, perl 5.8.3
 Redhat Linux 9, perl 5.8.0
 RedHat Linux 7, perl 5.6.0
 Solaris 2.6, perl 5.6.0
 Windows NT 4, perl 5.6.0
 VMS, perl5.7.0
 OS/2, perl5.7.0
 DOS/DJGPP, perl5.7.0

 RedHat Linux 6.1, perl 5.005_03
 Digital Unix 4.0, perl 5.005_03

File::Temp is a standard Perl module as of perl 5.7.0 and 5.6.1.

Still may need work on non-Unix platforms to adjust test severity (for example
stickyness test does not work on NT, and neither does unlink on an open
file). MEDIUM and HIGH security checks have only been tested on Unix.
Porting notes are provided at the start of Temp.pm.

FILE::PATH PROBLEM

In perl releases prior to perl 5.6.1 File::Temp will fail to remove
directory paths if taint checking is enabled. The problem is a bug in
the implementation of File::Path's rmtree function that is fixed in
version 1.05 of File::Path. The build system now requires v2.06 of
File::Path or newer.

AUTHOR

Tim Jenness <tjenness@cpan.org>

Copyright (C) 1999 - 2010 Tim Jenness and the UK Particle Physics and
Astronomy Research Council. All Rights Reserved.  This program is free
software; you can redistribute it and/or modify it under the same
terms as Perl itself.

CHANGES IN THIS RELEASE

V0.23
      + Use Module::Build instead of MakeMaker for building
      + Fix logic in tempfile.t for testing directory removal
      + tempdir() now returns an absolute path (RT#44924)
      + END directory clean up can now occur if cwd is the tempdir
        (patch from Ed Avis RT#45246)

V0.22
      + Portability fixes in t/fork.t provided by perl5-porters.

V0.21
      + Clean out $FILES_CREATED_BY_OBJECT when the destructor runs. Otherwise
        memory does not get returned. Really bad idea for daemons.
        (Thanks to Maxime Therreault RT #37621)

      + Remove the test on the parent directory to see if a file can
        be written. This will be found out anyway as soon as the file open
       	is attempted. AFS systems may fail a -w test but still allow a file
	      to be created. (thanks to Christopher Ellison)

      + Put an eval around rmtree. Some versions of rmtree croak if
        you attempt to remove a directory that you are inside. (debian bug
	      479317 and RT #35779).

      + seekable test was failing on perl 5.6.0 so we now skip the specific
        test. (thanks to Zefram)

      + Integrate patches from bleadperl for cygwin. (thanks to Jari Aalto
        RT #36376)

V0.20
      + Fix lock.t test that was failing on some systems due to dodgy BEGIN
         block usage (Thanks to Steve Peters and JDHEDDEN - RT #31129)

V0.19
      + Add "newdir" constructor to create a temporary directory
        that will be deleted automatically when the object goes out
        of scope. (RT #15733)

      + tempdir now accepts a TEMPDIR flag for symmetry with tempfile
        (debian bug #351373)

      + Use of exclusive lock can now be disabled by using EXLOCK => 0
        in constructor or tempfile() call. (RT #22702 and #28397)

      + Hopefully really fixed problems with forked processes removing
        temp files and directories created by parent (V0.18 was still broken
        in OO interface) (RT #11067)

      + "_" should now be available as a character from the random character
	generator (RT #41345)

      + Now works again with perl 5.004 (RT#26841 RT#23524)

      + Error message clarified when parent directory does not exist (RT#41346)

      + Fix error message in uid check (RT #14218)

      + Add note concerning binmode to modify encoding of handle returned by tempfile
        (Wolfgang Husmann)

V0.18
      + overload extended to allow compare of object filename directly
        (Rafael Garcia-Suarez)

      + remove umask modification code (potentially thread unsage)
        (Peter Dintelmann, Gisle Aas)

V0.17
      + Now inherits from IO::Seekable (Ricky Myers and Toby Corkindale)

      + Pre-emptive load of Carp::Heavy so that File::Temp can report
        errors when it has run out of file handles (RT #14151)

      + Sebastien Aperghis-Tramoni reports that File::Temp works
        with perl 5.004. (RT #14149)

      + Use effective uid for security check rather than real uid
      (Alexey Tourbin) (RT #14218)

      + Fix Object contructor in SYNOPSIS (Peter Moerch)

      + Documentation updated to note that croak() is called on error
         and that srand should be called after a fork. "e.g." is no longer used.

V0.16
      - Remove leftover debugging statement!
V0.15
      + Can now control whether the temp file is removed or not
        after the object is created using the unlink_on_destroy method.
      + A cleanup() function has been added to allow temp files to be
        tidied up before the END block triggers. (RT#6928; thanks to
        Robert Rothenberg)
      + A global variable $KEEP_ALL can be used to control whether temp
        files are removed on program exit (used for debugging)
      + Add support for Interix from Todd Vierling
      + Processes keep track of which files they are expected to remove
        so that child processes no longer remove the parent's files
        (RT#11067; Daniel Macks)
      - Fix RT bug #8822 (very strange clash with the _ filehandle)
      - Files are chmodded before removal to make sure they are writable
        (RT#6935)
      - The NOFOLLOW flag was not being used when it was supposed to be.
        (thanks to Marc Tardif)
      - The number of retries has been increased.
      - Improved pod and comments
      - Directories are now removed with the correct option to rmtree
        to overcome problems with file permissions (thanks to Slaven Rezic)

V0.14
      - new Object oriented interface. The file can now be deleted
	when the object goes out of scope:
          $tmp = new File::Temp;
	  print $tmp "Some data\n";
          print "Filename is $tmp\n";

      - MPE/IX fixes from Ken Hirsch

V0.13:
      - Documentation tweaks from Slaven Rezic and Jeffrey Friedl
      - MacOS patches from Chris Nandor
      - Test tweak from Andy Dougherty

V0.12:
      - Fix problem with Fcntl warnings on CGI and CGI::Carp 
            [Thanks to John Labovitz <johnl@valiha.inside.sealabs.com>]
      - Remove most of the carp warnings and wrap all information into a
        single croak (this allows security failures to die without 
        additional warnings getting in the way)

V0.11:
      - Fix bug on NT with O_TEMPORARY. The file was removed on close
        rather than on exit

V0.10:
      - More fixes for VMS
      - Add DOS/DJGPP support
      - Make security test less prone to failure on insecure systems
        since we are testing the module rather than the system.
      - Security tests is run in build dir and tmpdir

V0.09:
      - Add VMS support
      - OS/2 can not understand sticky bits

V0.08:
      - Improve performance by a factor of 3 over V0.07
      - Simplify the END block code
      - Ignore requests for HIGH or MEDIUM safety on platforms that 
        can not support it (rather than generating a fatal error)
      - Add OS/2 to list of platforms that can not unlink open file

V0.07:
      - Add support for perl 5.005. On perl 5.005 the HIGH and
        MEDIUM security levels are not supported due to changes in 
        the Fcntl module.

      - A benchmark has been added to the misc directory to compare
        IO::File->new_tmpfile, File::Temp and a simple creation wrapper
        around POSIX::tmpnam. On my Linux system File::Temp::tempfile()
        is an order of magnitude slower than the other two......

V0.06:
      - Add a test suite
      - Fix unlinking during the END blocks (was only removing the
        first file generated)
      - unlink0 can now be run on WinNT - the unlink of the file
        is now deferred to an END block since can not unlink an
        open file on WinNT
      - If the POSIX _PC_CHOWN_RESTRICTED symbol is not available
        it is assumed that "chown giveaway" is allowed.


V0.05: 
      - First release to CPAN