---
name: "APR::Finfo"
section: "3pm"
platform: "linux"
package: "libapache2-mod-perl2"
version: "2.0.13-2+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/APR::Finfo"
---

# APR::Finfo(3pm)

Perl API for APR fileinfo structure

## NAME

APR::Finfo - Perl API for APR fileinfo structure

## 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

APR fileinfo structure provides somewhat similar information to Perl's `stat()` call, but you will want to use this module's API to query an already `"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 `"PerlMapToStorageHandler"`, `"$r->finfo"` already contains the cached values from the apr's `stat()` call. So you don't want to perform it again, but 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.