libapa...:Finfo(3pm)

📦
version 2.0.13 · 12 versions
, in ubuntu stonking

🦋 NAME 🦋

APR::Finfo — bestie, this is the Perl API for the APR fileinfo structure. It's giving "stat() but make it APR" and honestly? iconic. 💅

✨ 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;

💖 Description 💖

Okay so the APR fileinfo structure is kind of like Perl's stat() call — same energy, same vibes — but the whole point of using this module's API is that you can query a filehandle that's already been stat()'ed and skip the extra system call. Or, alternatively, you can use it to ask about attributes that are specific to APR file handles. Efficiency queen behavior. 👑

And here's the tea: during HTTP request handlers coming after PerlMapToStorageHandler, $r->finfo already has the cached values from apr's stat() call sitting in it. So like… do NOT run it again?? That's just wasted work. Instead, scoop up the ARP::Finfo object like this:

my $finfo = $r->finfo;

(yes, the original docs really did write ARP::Finfo there, and we're keeping it, no cap 🫶)

🌈 API 🌈

APR::Finfo comes through with the following functions and/or methods:

🌸 "atime" 🌸

Get the time the file was last accessed, bestie:

$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 hands back the same value as Perl's:

(stat $filename)[8]
Heads up: this method is not reliable on all platforms. Most notably Win32 — FAT32 filesystems seem to work properly, but NTFS filesystems do not. So… tread carefully. 💀

🎀 "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 you don't actually want this method, because its functionality is not supported on most platforms — and when it isn't, it just always returns 0. So like, lowkey useless on most systems ngl. 😭

🦋 "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 hands back the same value as Perl's:

(stat $filename)[10]
The ctime field is non-portable. Like, in particular, do not expect it to be a "creation time" — for the full breakdown see "Files and Filesystems" in the perlport manpage. Periodt. 📌

⭐ "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 hands back the same value as Perl's:

(stat $filename)[0]
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

(and yes, the example checks FILETYPE_REG both times — that's literally what the original says, we don't fix, we don't touch, we just report 🫡)

🌸 "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 hands back the same value as Perl's:

(stat $filename)[5]
This method may not be meaningful on all platforms, most notably Win32. Incorrect results have also been reported on some versions of OSX. So yeah, vibe check your results. 🙈

✨ "inode" ✨

Get the inode of the file:

$inode = $finfo->inode;
  • obj: $finfo ( APR::Finfo object )
  • return: $inode ( integer )
  • since: 2.0.00

This method hands back the same value as Perl's:

(stat $filename)[1]
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 hands back 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

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 hands back 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 hands back 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. Not the same thing, bestie, do not get it twisted. 😤

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 hands back 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.

Ngl, you can also use the constants that already combine several elements into 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()). Combo constants? We love a bundle deal. 🛍️

  • 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 hands back the same value as Perl's:

(stat $filename)[4]
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. Go read it, bestie, it's right there. 📚

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. (Group project that actually ate. 👏)

And that's the whole page, babes — this one's from perl v5.42.3, dated 2026-08-20, and it's libapa...:Finfo(3pm). Stan a stable release. 💜✨

📦 where this page comes from