=head1 NAME
APR::Finfo - Perl API for APR fileinfo structure
=head1 Synopsis
use APR::Finfo ();
use APR::Const -compile => qw(FINFO_NORM);
my $finfo = APR::Finfo::stat("/tmp/test", APR::Const::FINFO_NORM, $pool);
$device = $finfo->device; # (stat $file)[0]
$inode = $finfo->inode; # (stat $file)[1]
# stat returns an octal number while protection is hex
$prot = $finfo->protection; # (stat $file)[2]
$nlink = $finfo->nlink; # (stat $file)[3]
$gid = $finfo->group; # (stat $file)[4]
$uid = $finfo->user; # (stat $file)[5]
$size = $finfo->size; # (stat $file)[7]
$atime = $finfo->atime; # (stat $file)[8]
$mtime = $finfo->mtime; # (stat $file)[9]
$ctime = $finfo->ctime; # (stat $file)[10]
$csize = $finfo->csize; # consumed size: not portable!
$filetype = $finfo->filetype; # file/dir/socket/etc
$fname = $finfo->fname;
$name = $finfo->name; # in filesystem case:
# valid fields that can be queried
$valid = $finfo->valid;
=head1 Description
APR fileinfo structure provides somewhat similar information to Perl's
C<stat()> call, but you will want to use this module's API to query an
already C<stat()'ed> filehandle to avoid an extra system call or to
query attributes specific to APR file handles.
During the HTTP request handlers coming after
C<L<PerlMapToStorageHandler|docs::2.0::user::handlers::http/PerlMapToStorageHandler>>,
C<L<$r-E<gt>finfo|docs::2.0::api::Apache2::RequestRec/C_finfo_>>
already contains the cached values from the apr's C<stat()> call. So
you don't want to perform it again, but instead get the C<ARP::Finfo>
object via:
my $finfo = $r->finfo;
=head1 API
C<APR::Finfo> provides the following functions and/or methods:
=head2 C<atime>
Get the time the file was last accessed:
$atime = $finfo->atime;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$atime> ( integer )
Last access time in seconds since the epoch
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[8]
Note that this method may not be reliable on all platforms, most
notably Win32 -- FAT32 filesystems appear to work properly, but NTFS
filesystems do not.
=head2 C<csize>
Get the storage size consumed by the file
$csize = $finfo->csize;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$csize> ( integer )
=item since: 2.0.00
=back
Chances are that you don't want to use this method, since its
functionality is not supported on most platforms (in which case it
always returns 0).
=head2 C<ctime>
Get the time the file was last changed
$ctime = $finfo->ctime;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$ctime> ( integer )
Inode change time in seconds since the epoch
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[10]
The ctime field is non-portable. In particular, you cannot expect it
to be a "creation time", see "Files and Filesystems" in the
I<perlport> manpage for details.
=head2 C<device>
Get the id of the device the file is on.
$device = $finfo->device;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$device> ( integer )
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[0]
Note that this method is non-portable. It doesn't work on all
platforms, most notably Win32.
=head2 C<filetype>
Get the type of file.
$filetype = $finfo->filetype;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$filetype> ( C<L<:filetype
constant|docs::2.0::api::APR::Const/C__filetype_>> )
=item since: 2.0.00
=back
For example:
use APR::Pool;
use APR::Finfo;
use APR::Const -compile => qw(FILETYPE_DIR FILETYPE_REG FINFO_NORM);
my $pool = APR::Pool->new();
my $finfo = APR::Finfo::stat("/tmp", APR::Const::FINFO_NORM, $pool);
my $finfo = $finfo->filetype;
if ($finfo == APR::Const::FILETYPE_REG) {
print "regular file";
}
elsif ($finfo == APR::Const::FILETYPE_REG) {
print "directory";
}
else {
print "other file";
}
Since F</tmp> is a directory, this will print:
directory
=head2 C<fname>
Get the pathname of the file (possibly unrooted)
$fname = $finfo->fname;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$filetype> ( string )
=item since: 2.0.00
=back
=head2 C<group>
Get the group id that owns the file:
$gid = $finfo->group;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$gid> ( number )
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[5]
Note that this method may not be meaningful on all platforms, most
notably Win32. Incorrect results have also been reported on some
versions of OSX.
=head2 C<inode>
Get the inode of the file.
$inode = $finfo->inode;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$inode> ( integer )
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[1]
Note that this method may not be meaningful on all platforms, most
notably Win32.
=head2 C<mtime>
The time the file was last modified
$mtime = $finfo->mtime;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$mtime> ( integer )
Last modify time in seconds since the epoch
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[9]
=head2 C<name>
Get the file's name (no path) in filesystem case:
$name = $finfo->name;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$device> ( string )
=item since: 2.0.00
=back
=head2 C<nlink>
Get the number of hard links to the file.
$nlink = $finfo->nlink;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$nlink> ( integer )
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[3]
=head2 C<protection>
Get the access permissions of the file. Mimics Unix access rights.
$prot = $finfo->protection;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$prot> ( C<L<:fprot
constant|docs::2.0::api::APR::Const/C__fprot_>> )
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[2]
Note: Perl's stat returns an octal number while
mod_perl's C<protection> returns a hex number.
See perldoc -f stat and APR's file_io for more information
on each.
=head2 C<size>
Get the size of the file
$size = $finfo->size;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$size> ( integer )
Total size of file, in bytes
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[7]
=head2 C<stat>
Get the specified file's stats.
$finfo = APR::Finfo::stat($fname, $wanted_fields, $p);
=over 4
=item arg1: C<$fname> ( string )
The path to the file to C<stat()>.
=item arg2: C<$wanted_fields> ( C<L<:finfo
constant|docs::2.0::api::APR::Const/C__finfo_>> )
The desired fields, as a bitmask flag of
C<L<APR::FINFO_*|docs::2.0::api::APR::Const/C__finfo_>> constants.
Notice that you can also use the constants that already combine
several elements in one. For example
C<L<APR::Const::FINFO_PROT|docs::2.0::api::APR::Const/C_APR__Const__FINFO_PROT_>>
asks for all protection bits,
C<L<APR::Const::FINFO_MIN|docs::2.0::api::APR::Const/C_APR__Const__FINFO_MIN_>> asks
for the following fields: type, mtime, ctime, atime, size and
C<L<APR::Const::FINFO_NORM|docs::2.0::api::APR::Const/C_APR__Const__FINFO_NORM_>>
asks for all atomic unix C<apr_stat()> fields (similar to perl's
C<stat()>).
=item arg3: C<$p> ( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )
the pool to use to allocate the file stat structure.
=item ret: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item since: 2.0.00
=back
For example, here is how to get most of the C<stat> fields:
use APR::Pool ();
use APR::Finfo ();
use APR::Const -compile => qw(FINFO_NORM);
my $pool = APR::Pool->new();
my $finfo = APR::Finfo::stat("/tmp/test", APR::Const::FINFO_NORM, $pool);
=head2 C<user>
Get the user id that owns the file:
$uid = $finfo->user;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item return: C<$uid> ( number )
=item since: 2.0.00
=back
This method returns the same value as Perl's:
(stat $filename)[4]
Note that this method may not be meaningful on all platforms,
most notably Win32.
=head2 C<valid>
The bitmask describing valid fields of this apr_finfo_t structure
including all available 'wanted' fields and potentially more
$valid = $finfo->valid;
=over 4
=item obj: C<$finfo>
( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
=item arg1: C<$valid> ( bitmask )
This bitmask flag should be bit-OR'ed against C<L<:finfo
constant|docs::2.0::api::APR::Const/C__finfo_>> constants.
=item since: 2.0.00
=back
=head1 See Also
L<mod_perl 2.0 documentation|docs::2.0::index>.
=head1 Copyright
mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.
=head1 Authors
L<The mod_perl development team and numerous
contributors|about::contributors::people>.
=cut