=head1 NAME

APR::Finfo - Perl API for APR fileinfo structure

XXX: Besides working through the doc we need to get good constant
names from libapr (needs apr patching)


=head1 Synopsis

  use APR::Finfo ();

META: to be completed




=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::Apache::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<stat>

Get the specified file's stats.  The file is specified by filename,
instead of using a pre-opened file.

  $finfo = stat($fname, $wanted_fields, $pool);

=over 4

=item arg1: C<$fname> ( string )

The path to the file to C<stat()>.

=item arg2: C<$wanted> ( string )

The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values

XXX

=item arg3: C<$pool> ( integer )

the pool to use to allocate the new file.

=item ret: C<$finfo>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item since: 1.99_12

=back





=head2 C<pool>

META: Autogenerated - needs to be reviewed/completed

Allocates memory and closes lingering handles in the specified pool

  $ret = $obj->pool($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval>
( C<L<APR::Pool|docs::2.0::api::APR::Pool>> )

=item since: 1.99_12

=back





=head2 C<valid>

META: Autogenerated - needs to be reviewed/completed

The bitmask describing valid fields of this apr_finfo_t structure
including all available 'wanted' fields and potentially more

  $ret = $obj->valid($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<protection>

META: Autogenerated - needs to be reviewed/completed

The access permissions of the file.  Mimics Unix access rights.

  $ret = $obj->protection($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<filetype>

META: Autogenerated - needs to be reviewed/completed

The type of file.  One of APR_REG, APR_DIR, APR_CHR, APR_BLK, APR_PIPE,
APR_LNK or APR_SOCK.  If the type is undetermined, the value is APR_NOFILE.
If the type cannot be determined, the value is APR_UNKFILE.

  $ret = $obj->filetype($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<user>

META: Autogenerated - needs to be reviewed/completed

The user id that owns the file

  $ret = $obj->user($newval);

Note that this method may not be meaningful on all platforms,
most notably Win32.

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<group>

META: Autogenerated - needs to be reviewed/completed

The group id that owns the file

  $ret = $obj->group($newval);

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.

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<inode>

META: Autogenerated - needs to be reviewed/completed

The inode of the file.

  $ret = $obj->inode($newval);

Note that this method may not be meaningful on all platforms,
most notably Win32.

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<device>

META: Autogenerated - needs to be reviewed/completed

The id of the device the file is on.

  $ret = $obj->device($newval);

Note that this method may not be meaningful on all platforms,
most notably Win32.

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval>
(number)

=item since: 1.99_12

=back





=head2 C<nlink>

META: Autogenerated - needs to be reviewed/completed

The number of hard links to the file.

  $ret = $obj->nlink($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<size>

META: Autogenerated - needs to be reviewed/completed

The size of the file

  $ret = $obj->size($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<csize>

META: Autogenerated - needs to be reviewed/completed

The storage size consumed by the file

  $ret = $obj->csize($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval> ( integer )

=item since: 1.99_12

=back





=head2 C<atime>

META: Autogenerated - needs to be reviewed/completed

The time the file was last accessed

  $ret = $obj->atime($newval);

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.

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval>
(number)

=item since: 1.99_12

=back





=head2 C<mtime>

META: Autogenerated - needs to be reviewed/completed

The time the file was last modified

  $ret = $obj->mtime($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval>
(number)

=item since: 1.99_12

=back





=head2 C<ctime>

META: Autogenerated - needs to be reviewed/completed

The time the file was last changed

  $ret = $obj->ctime($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval>
(number)

=item since: 1.99_12

=back





=head2 C<fname>

META: Autogenerated - needs to be reviewed/completed

The pathname of the file (possibly unrooted)

  $ret = $obj->fname($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval>
( string )

=item since: 1.99_12

=back





=head2 C<name>

META: Autogenerated - needs to be reviewed/completed

The file's name (no path) in filesystem case

  $ret = $obj->name($newval);

=over 4

=item obj: C<$obj>
( C<L<APR::Finfo|docs::2.0::api::APR::Finfo>> )

=item arg1: C<$newval>
( string )

=item since: 1.99_12

=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

