package File::CreationTime;
use warnings;
use strict;
use File::Attributes qw(get_attribute set_attribute);
use Exporter;
our @ISA = 'Exporter';
our @EXPORT = qw(creation_time);
our @EXPORT_OK = qw(creation_time);
=head1 NAME
File::CreationTime - Keeps track of file creation times
=head1 VERSION
Version 2.04
=cut
our $VERSION = '2.04';
=head1 SYNOPSIS
Keeps track of creation times on filesystems that don't normally
provide such information.
use File::CreationTime;
my $file = '/path/to/file';
print "$file was created: ". creation_time($file). "\n";
=head1 EXPORT
=head2 creation_time
=head1 FUNCTIONS
=head2 creation_time
creation_time('/path/to/file')
Returns the creation time of /path/to/file in seconds past the epoch.
Requires permission to modify extended filesystem attributes the first
time the function is called. All subsequent invocations require read
access only.
=cut
sub creation_time {
my $filename = shift;
my $ATTRIBUTE = "creation_time";
die "$filename does not exist" if !-e $filename;
my $ctime;
eval {
if($^O =~ 'darwin'){
eval {
require MacOSX::File::Info;
$ctime = MacOSX::File::Info->get($filename)->ctime();
}
}
# fallback to attrs if the OS X method fails
$ctime ||= get_attribute($filename, $ATTRIBUTE);
};
return $ctime if defined $ctime;
# no ctime attr? create one.
my $mtime = (stat $filename)[9]; # 9 is mtime
eval {
set_attribute($filename, $ATTRIBUTE, $mtime);
};
warn "Failed to set attribute $ATTRIBUTE on $filename: $@" if $@;
return $mtime;
}
=head1 ACCURACY
The algorithm used to determine the creation time is as follows. The
first time creation_time is called, an extended filesystem attribute
called creation_time is created and is set to contain the time that
the file was most recently modified. As such, if you have a file
that's several years old, then modify it, then call creation_time, the
file's creation time will obviously be wrong. However, if you create
a file, call creation_time, wait several years, modify the file, then
call creation_time again, the result will be accurate.
On OS X, this method is not used. Instead, the actual creation time
is provided via C<< MacOSX::File::Info->ctime >>.
=head1 DIAGNOSTICS
=head2 [path] does not exist
You passed [path] to creation_time, but it doesn't exist (or you can't
read it).
=head2 Failed to set attribute user.creation_time on [file]
Couldn't create the attribute for some reason. Does your filesystem
support extended filesystem attributes?
=head1 SEE ALSO
L<File::Attributes|File::Attributes> handles storing the creation_time
attribute.
=head1 BUGS
I'd like to support OSes that actually give you the file creation
time. As of version 2.04, OS X is supported in this way. If you know
how to make this work on your OS, tell me how or send me a patch.
Other comments and patches are always welcome.
=head2 REPORTING
Please report any bugs or feature requests to
C<bug-file-creationtime@rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-creationTime>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
=head1 AUTHOR
Jonathan Rockway, C<< <jrockway AT cpan.org> >>.
=head1 CONTRIBUTORS
Dave Cardwell added OS X support.
=head1 COPYRIGHT & LICENSE
Copyright 2005 Jonathan T. Rockway.
This program is Free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
=cut
1; # End of File::CreationTime