/ 
Win32API-File-Time-0.010
River stage zero No dependents
/ Win32API::File::Time

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 read and modify the time on open files, read-only files, and directories. Caveat user.

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 (based on the truth of ${^WIDE_SYSTEM_CALLS}) but not currently supported. In other words: I wrote the code, but haven't tested it and don't have any plans to. Feedback will be accepted, and implemented when I get a sufficient supply of tuits.

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

NOTE

It has been a while since I had access to a Microsoft Windows system of any sort, and various strange expedients have been used to allow me to continue to support this module. Requests for co-maintainership, or ownership of the module, are welcome.

By OS, the situation is:

ReactOS

ReactOS is an alpha-quality open-source clean-room OS implementing the Microsoft Windows API. When it started out it was targeting NT 4.0. Lately they seem to be targeting Windows 2003. ReactOS is found at https://reactos.org/.

With about 0.4.11 this has become good enough that using it to support this module is not completely out of the question. However, the last I checked I was unable to read the creation time. Since this worked under Microsoft Windows the last time I had access to that OS, I presume this failure is a ReactOS thing.

The problem here is that I know of no definitive way to distinguish between ReactOS and Microsoft Windows. Early versions of ReactOS defined the OS environment variable as 'ReactOS', but more recent ones call it 'Windows_NT'. At the moment there is ad-hocery in t/file.t that detects ReactOS by feeling around the system drive looking for files with that name. The default installation makes %SystemRoot% 'C:\ReactOS', and this is what we look for. If you change this, you will need to create file C:\ReactOS yourself or the creation time check will be run, and it will fail.

Cygwin

I am unable to install this on ReactOS. Support is on a best-effort basis, and the requester may have to be more-than-usually involved in developing any change.

Microsoft Windows

I do not have access to such a system. If ReactOS proves inadequate for a particular purpose, support will be on the same basis as Cygwin.

Anything else

Regression testing is done using a mock Win32::API. Anything outside this needs either ReactOS or another pair of hands.

BUGS

As implemented, GetFileTime() constitutes an access, and therefore updates the access time.

The stat() builtin, on the other hand, doesn't report an access time change even after GetFileTime() has been used. In fact, it looks to me very much like stat() reports the modification time in element [8] of the list, but I find this nowhere documented.

FAT file time resolution is 2 seconds at best, as documented at https://docs.microsoft.com/en-us/windows/win32/sysinfo/file-times. Access time resolution seems to be to the nearest day.

Support is by the author. Please file bug reports at https://github.com/trwyant/perl-Win32API-File-Time/issues, or in electronic mail to the author.

ACKNOWLEDGMENTS

This module would not exist without the following people:

Aldo Calpini, who gave us Win32::API.

Tye McQueen, who gave us Win32API::File.

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.

The folks of ActiveState (http://www.activestate.com/, formerly known as Hip Communications), who found a way to reconcile Windows' and Perl's subtly different ideas of what time it is.

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 AND LICENSE

Copyright (C) 2004-2005 by E. I. DuPont de Nemours and Company, Inc. All rights reserved.

Copyright (C) 2007, 2010, 2016-2017, 2019-2021 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.