NAME

Win32API::File::Time - Set file times, even on open or readonly files.

SYNOPSIS

use Win32API::File::Time qw{:win};
($atime, $mtime, $ctime) = GetFileTime ($filename);
SetFileTime ($filename, $atime, $mtime, $ctime);

or

use Win32API::File::Time qw{utime};
utime ($atime, $mtime, $filename) or die $^E;

DESCRIPTION

The purpose of Win32API::File::Time is to provide maximal access to the file creation, modification, and access times under MSWin32.

Under Windows, the Perl utime module will not modify the time of an open file, nor a read-only file. The comments in win32.c indicate that this is the intended functionality, at least for read-only files.

This module will modify the time on both open files and read-only files. Caveat implementor.

This module is based on the SetFileTime function in kernel32.dll. Perl's utime built-in also makes explicit use of this function if the "C" run-time version of utime fails. The difference is in how the filehandle is created. The Perl built-in requests access GENERIC_READ | GENERIC_WRITE when modifying file dates, whereas this module requests access FILE_WRITE_ATTRIBUTES.

Nothing is exported by default, but all documented subroutines are exportable. In addition, the following export tags are supported:

:all => exports everything exportable
:win => exports GetFileTime and SetFileTime

Wide system calls are implemented but not currently supported.

($atime, $mtime, $ctime) = GetFileTime ($filename);

This subroutine returns the access, modification, and creation times of the given file. If it fails, nothing is returned, and the error code can be found in $^E.

No, there's no additional functionality here versus the stat built-in. But it was useful for development and testing, and has been exposed for orthogonality's sake.

SetFileTime (filename, atime, mtime, ctime);

This subroutine sets the access, modification, and creation times of the given file. The return is true for success, and false for failure. In the latter case, $^E will contain the error.

If you don't want to set all of the times, pass 0 or undef for the times you don't want to set. For example,

$now = time ();
SetFileTime ($filename, $now, $now);

is equivalent to the "touch" command for the given file.

utime ($atime, $mtime, $filename, ...)

This subroutine overrides the built-in of the same name. It does exactly the same thing, but has a different idea than the built-in about what files are legal to change.

Like the core utime, it returns the number of files successfully modified. If not all files can be modified, $^E contains the last error encountered.

HISTORY

0.001 Initial release

BUGS

Sometimes the access time returned by GetFileTime is a few seconds different than the access time returned by the stat built-in. I have no explanation for this. The built-in stat seems to be based on the "C" run-time stat (); what that's doing I know not.

ACKNOWLEDGMENTS

This module would not exist without the following people:

Aldo Calpini, who gave us Win32::API.

Jenda Krynicky, whose "How2 create a PPM distribution" (http://jenda.krynicky.cz/perl/PPM.html) gave me a leg up on both PPM and tar distributions.

Rob Casey, the author of the similar module Win32::FileTime, which taught me how to manipulate the blasted times once I got them.

Last, in the place of honor, the folks of Cygwin (http://www.cygwin.com/), especially those who worked on times.cc in the Cygwin core. This is the only implementation of utime I could find which did what I wanted it to do.

AUTHOR

Thomas R. Wyant, III (Thomas.R.Wyant-III@usa.dupont.com)

COPYRIGHT

Copyright 2004 by E. I. DuPont de Nemours and Company, Inc. All rights reserved.

This module is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself.