docs::a...R::Finfo(3)

🌸 NAME 🌸

Okay bestie, this page is docs::a...R::Finfo(3) — User Contributed Perl Documentation — and the main character is APR::Finfo, the Perl API for the APR fileinfo structure. 💅✨

✨ Synopsis ✨

Here's the whole vibe check, copied exactly because every field matters:

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;

💖 Description 💖

The APR fileinfo structure provides somewhat similar information to Perl's stat() call — but you'll want to use this module's API to query an already "stat()'ed" filehandle, so you can avoid an extra system call or query attributes specific to APR file handles. ✨

During the HTTP request handlers coming after "PerlMapToStorageHandler", "$r->finfo" already contains the cached values from the apr's stat() call. So you don't want to perform it again — instead get the "ARP::Finfo" object via:

my $finfo = $r->finfo;

🦋 API 🦋

APR::Finfo provides the following functions and/or methods:

💫 atime 💫

Get the time the file was last accessed:

$atime = $finfo->atime;

• obj: $finfo ( "APR::Finfo object" )
• return: $atime ( integer ) — Last access time in seconds since the epoch
• since: 2.0.00

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. 😭

🧚 csize 🧚

Get the storage size consumed by the file:

$csize = $finfo->csize;

• obj: $finfo ( "APR::Finfo object" )
• return: $csize ( integer )
• since: 2.0.00

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). 💀

🎀 ctime 🎀

Get the time the file was last changed:

$ctime = $finfo->ctime;

• obj: $finfo ( "APR::Finfo object" )
• return: $ctime ( integer ) — Inode change time in seconds since the epoch
• since: 2.0.00

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 perlport manpage for details. 💀

🦋 device 🦋

Get the id of the device the file is on:

$device = $finfo->device;

• obj: $finfo ( "APR::Finfo object" )
• return: $device ( integer )
• since: 2.0.00

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. 🙈

🌈 filetype 🌈

Get the type of file:

$filetype = $finfo->filetype;

• obj: $finfo ( "APR::Finfo object" )
• return: $filetype ( ":filetype constant" )
• since: 2.0.00

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 /tmp is a directory, this will print:

directory

🍓 fname 🍓

Get the pathname of the file (possibly unrooted):

$fname = $finfo->fname;

• obj: $finfo ( "APR::Finfo object" )
• return: $filetype ( string )
• since: 2.0.00

💜 group 💜

Get the group id that owns the file:

$gid = $finfo->group;

• obj: $finfo ( "APR::Finfo object" )
• return: $gid ( number )
• since: 2.0.00

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. 😬

⭐ inode ⭐

Get the inode of the file:

$inode = $finfo->inode;

• obj: $finfo ( "APR::Finfo object" )
• return: $inode ( integer )
• since: 2.0.00

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. 🙈

🌸 mtime 🌸

The time the file was last modified:

$mtime = $finfo->mtime;

• obj: $finfo ( "APR::Finfo object" )
• return: $mtime ( integer ) — Last modify time in seconds since the epoch
• since: 2.0.00

This method returns the same value as Perl's:

(stat $filename)[9]

🫶 name 🫶

Get the file's name (no path) in filesystem case:

$name = $finfo->name;

• obj: $finfo ( "APR::Finfo object" )
• return: $device ( string )
• since: 2.0.00

🔥 nlink 🔥

Get the number of hard links to the file:

$nlink = $finfo->nlink;

• obj: $finfo ( "APR::Finfo object" )
• return: $nlink ( integer )
• since: 2.0.00

This method returns the same value as Perl's:

(stat $filename)[3]

👑 protection 👑

Get the access permissions of the file. Mimics Unix access rights:

$prot = $finfo->protection;

• obj: $finfo ( "APR::Finfo object" )
• return: $prot ( ":fprot constant" )
• since: 2.0.00

This method returns the same value as Perl's:

(stat $filename)[2]

Note: Perl's stat returns an octal number while mod_perl's "protection" returns a hex number.

See perldoc -f stat and APR's file_io for more information on each. ✨

🧚 size 🧚

Get the size of the file:

$size = $finfo->size;

• obj: $finfo ( "APR::Finfo object" )
• return: $size ( integer ) — Total size of file, in bytes
• since: 2.0.00

This method returns the same value as Perl's:

(stat $filename)[7]

💅 stat 💅

Get the specified file's stats:

$finfo = APR::Finfo::stat($fname, $wanted_fields, $p);

• arg1: $fname ( string ) — The path to the file to stat().
• arg2: $wanted_fields ( ":finfo constant" ) — The desired fields, as a bitmask flag of "APR::FINFO_*" constants.

Notice that you can also use the constants that already combine several elements in one. For example "APR::Const::FINFO_PROT" asks for all protection bits, "APR::Const::FINFO_MIN" asks for the following fields: type, mtime, ctime, atime, size and "APR::Const::FINFO_NORM" asks for all atomic unix apr_stat() fields (similar to perl's stat()).

• arg3: $p ( "APR::Pool object" ) — the pool to use to allocate the file stat structure.
• ret: $finfo ( "APR::Finfo object" )
• since: 2.0.00

For example, here is how to get most of the "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);

🌟 user 🌟

Get the user id that owns the file:

$uid = $finfo->user;

• obj: $finfo ( "APR::Finfo object" )
• return: $uid ( number )
• since: 2.0.00

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. 🙈

🎀 valid 🎀

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

$valid = $finfo->valid;

• obj: $finfo ( "APR::Finfo object" )
• arg1: $valid ( bitmask ) — This bitmask flag should be bit-OR'ed against ":finfo constant" constants.
• since: 2.0.00

🌈 See Also 🌈

mod_perl 2.0 documentation.

🎀 Copyright 🎀

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

👑 Authors 👑

The mod_perl development team and numerous contributors.

---

That's the whole page, bestie! This one is docs::a...R::Finfo(3) from perl v5.42.3, dated 2023-10-21. Go query those file stats and slay. 💖✨