File Coverage

blib/lib/File/CreationTime.pm
Criterion Covered Total %
statement 7 9 77.7
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 10 12 83.3


line stmt bran cond sub pod time code
1             package File::CreationTime;
2              
3 3     3   75000 use warnings;
  3         7  
  3         85  
4 3     3   17 use strict;
  3         5  
  3         103  
5 3     3   4130 use File::Attributes qw(get_attribute set_attribute);
  0            
  0            
6              
7             use Exporter;
8             our @ISA = 'Exporter';
9             our @EXPORT = qw(creation_time);
10             our @EXPORT_OK = qw(creation_time);
11              
12             =head1 NAME
13              
14             File::CreationTime - Keeps track of file creation times
15              
16             =head1 VERSION
17              
18             Version 2.04
19              
20             =cut
21              
22             our $VERSION = '2.04';
23              
24             =head1 SYNOPSIS
25              
26             Keeps track of creation times on filesystems that don't normally
27             provide such information.
28              
29             use File::CreationTime;
30              
31             my $file = '/path/to/file';
32             print "$file was created: ". creation_time($file). "\n";
33              
34             =head1 EXPORT
35              
36             =head2 creation_time
37              
38             =head1 FUNCTIONS
39              
40             =head2 creation_time
41              
42             creation_time('/path/to/file')
43              
44             Returns the creation time of /path/to/file in seconds past the epoch.
45             Requires permission to modify extended filesystem attributes the first
46             time the function is called. All subsequent invocations require read
47             access only.
48              
49             =cut
50              
51             sub creation_time {
52             my $filename = shift;
53             my $ATTRIBUTE = "creation_time";
54              
55             die "$filename does not exist" if !-e $filename;
56            
57             my $ctime;
58             eval {
59             if($^O =~ 'darwin'){
60             eval {
61             require MacOSX::File::Info;
62             $ctime = MacOSX::File::Info->get($filename)->ctime();
63             }
64             }
65            
66             # fallback to attrs if the OS X method fails
67             $ctime ||= get_attribute($filename, $ATTRIBUTE);
68             };
69            
70             return $ctime if defined $ctime;
71            
72             # no ctime attr? create one.
73             my $mtime = (stat $filename)[9]; # 9 is mtime
74            
75             eval {
76             set_attribute($filename, $ATTRIBUTE, $mtime);
77             };
78             warn "Failed to set attribute $ATTRIBUTE on $filename: $@" if $@;
79             return $mtime;
80             }
81              
82             =head1 ACCURACY
83              
84             The algorithm used to determine the creation time is as follows. The
85             first time creation_time is called, an extended filesystem attribute
86             called creation_time is created and is set to contain the time that
87             the file was most recently modified. As such, if you have a file
88             that's several years old, then modify it, then call creation_time, the
89             file's creation time will obviously be wrong. However, if you create
90             a file, call creation_time, wait several years, modify the file, then
91             call creation_time again, the result will be accurate.
92              
93             On OS X, this method is not used. Instead, the actual creation time
94             is provided via C<< MacOSX::File::Info->ctime >>.
95              
96             =head1 DIAGNOSTICS
97              
98             =head2 [path] does not exist
99              
100             You passed [path] to creation_time, but it doesn't exist (or you can't
101             read it).
102              
103             =head2 Failed to set attribute user.creation_time on [file]
104              
105             Couldn't create the attribute for some reason. Does your filesystem
106             support extended filesystem attributes?
107              
108             =head1 SEE ALSO
109              
110             L handles storing the creation_time
111             attribute.
112              
113             =head1 BUGS
114              
115             I'd like to support OSes that actually give you the file creation
116             time. As of version 2.04, OS X is supported in this way. If you know
117             how to make this work on your OS, tell me how or send me a patch.
118              
119             Other comments and patches are always welcome.
120              
121             =head2 REPORTING
122              
123             Please report any bugs or feature requests to
124             C, or through the web interface at
125             L.
126             I will be notified, and then you'll automatically be notified of progress on
127             your bug as I make changes.
128              
129             =head1 AUTHOR
130              
131             Jonathan Rockway, C<< >>.
132              
133             =head1 CONTRIBUTORS
134              
135             Dave Cardwell added OS X support.
136              
137             =head1 COPYRIGHT & LICENSE
138              
139             Copyright 2005 Jonathan T. Rockway.
140              
141             This program is Free software; you can redistribute it and/or modify it
142             under the same terms as Perl itself.
143              
144             =cut
145              
146             1; # End of File::CreationTime