Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for file::temp (redhat section 3pm)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

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

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

	 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 = tmpfile();

       Compatibility functions:

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

       "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 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 exam-
       ple, that the sticky bit is set on world writable directories.  See "safe_level" for more

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

       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 can-
       not guarantee that the file will not exist by the time the caller opens the filename.

       This section describes the recommended interface for generating temporary files and direc-

	   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 File::Spec.

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

	   Create a temporary file in the current directory using the supplied template.  Trail-
	   ing `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' trans-
	   lation.  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, UNLINK => 1);

	   Return the filename and filehandle as before except that the file is automatically
	   removed when the program exits. 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 on exit or when it is

	   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( $template, DIR => $dir );

	   If called in scalar context, only the filehandle is returned and the file will auto-
	   matically 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 program ends (equivalent to setting UNLINK to 1). The "UNLINK" flag is ignored if

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

	   This will return the filename based on the template but will not open this file.  Can-
	   not 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.

	   Options can be combined as required.

	   This is the recommended interface for creation of temporary directories.  The behav-
	   iour 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 specifications itself. Any parent directory specifications are
	   removed from the template before prepending the supplied directory.

	     $tempdir = tempdir ( $template, TMPDIR => 1 );

	   Using the supplied template, create 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 template, 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 (oth-
	   erwise why ask to clean it up?). The directory removal is made with the rmtree() func-
	   tion from the File::Path module.  Of course, if the template is not specified, the
	   temporary directory will be created in tmpdir() and will also be removed at program

       The following functions are Perl implementations of the mktemp() family of temp file gen-
       eration system calls.

	   Given a template, returns a filehandle to the temporary 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.

	   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 sim-
	   ilar to testhGji_w.dat.

	   Returns just the filehandle alone when called in scalar context.

	   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.

	   Returns a valid temporary filename but does not guarantee that the file will not be
	   opened by someone else.

	     $unopened_file = mktemp($template);

	   Template is the same as that required by mkstemp().

       This section describes the re-implementation of the tmpnam() and tmpfile() functions
       described in POSIX using the mkstemp() from this module.

       Unlike the POSIX implementations, the directory used for the temporary file is not speci-
       fied 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.

	   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-

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

	   If possible, this form should be used to prevent possible race conditions.

	   See "tmpdir" in File::Spec for information on the choice of temporary directory for a
	   particular operating system.

	   Returns the filehandle of a temporary 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.

       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.

	   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 guaran-
	   tees 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/$prefixXXXXXXXX (using unix file convention
	   as an example)

	   Because this function uses mktemp(), it can suffer from race conditions.

       Useful functions for dealing with the filehandle and filename.

	   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 descrip-
	   tor 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 unlinking 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 executed since the deferred removal may not have access to the

	   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 usually 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

       These functions control the global state of the package.

	   Controls the lengths to which the module will go to check the safety of the temporary
	   file or directory before proceeding.  Options are:

		   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 output 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 possi-
		   bility, each directory in the path is checked in turn for safeness, recur-
		   sively walking back to the root directory.

		   For platforms that do not support the POSIX "_PC_CHOWN_RESTRICTED" symbol (for
		   example, Windows NT) it is assumed that ``chown() giveaway'' 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

	   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 programs 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;

	   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.

	     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.

       For maximum security, endeavour always to avoid ever looking at, touching, or even imput-
       ing 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 file-
       name altogether.

       If you need to pass the handle to something that expects a filename then, on a unix sys-
       tem, 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 secu-
       rity 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.

       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.

       "tmpnam" in POSIX, "tmpfile" in POSIX, File::Spec, File::Path

       See IO::File and File::MkTemp for different implementations of temporary file handling.

       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 redistribute 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 suggesting that this module should be written and providing ideas for
       code improvements and security enhancements.

perl v5.8.0				    2002-06-01				  File::Temp(3pm)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 01:44 PM.