mod_perl logo perl icon
previous page: APR::Error - Perl API for APR/Apache/mod_perl exceptionspage up: mod_perl 2.0 APInext page: APR::IpSubnet - Perl API for accessing APRs ip_subnet structures

APR::Finfo - Perl API for APR fileinfo structure






mod_perl Pocket Reference

mod_perl Pocket Reference

By Andrew Ford
Writing Apache Modules with Perl and C

Writing Apache Modules with Perl and C

By Lincoln Stein, Doug MacEachern
Embedding Perl in HTML with Mason

Embedding Perl in HTML with Mason

By Dave Rolsky, Ken Williams
mod_perl2 User's Guide

mod_perl2 User's Guide

By Stas Bekman, Jim Brandt
Practical mod_perl

Practical mod_perl

By Stas Bekman, Eric Cholet
The mod_perl Developer's Cookbook

The mod_perl Developer's Cookbook

By Geoffrey Young, Paul Lindner, Randy Kobes


Table of Contents

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;


TOP

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;


TOP

API

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



TOP

atime

Get the time the file was last accessed:

  $atime = $finfo->atime;

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.



TOP

csize

Get the storage size consumed by the file

  $csize = $finfo->csize;

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



TOP

ctime

Get the time the file was last changed

  $ctime = $finfo->ctime;

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.



TOP

device

Get the id of the device the file is on.

  $device = $finfo->device;

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.



TOP

filetype

Get the type of file.

  $filetype = $finfo->filetype;

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


TOP

fname

Get the pathname of the file (possibly unrooted)

  $fname = $finfo->fname;


TOP

group

Get the group id that owns the file:

  $gid = $finfo->group;

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.



TOP

inode

Get the inode of the file.

  $inode = $finfo->inode;

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.



TOP

mtime

The time the file was last modified

  $mtime = $finfo->mtime;

This method returns the same value as Perl's:

  (stat $filename)[9]


TOP

name

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

  $name = $finfo->name;


TOP

nlink

Get the number of hard links to the file.

  $nlink = $finfo->nlink;

This method returns the same value as Perl's:

  (stat $filename)[3]


TOP

protection

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

  $prot = $finfo->protection;

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.



TOP

size

Get the size of the file

  $size = $finfo->size;

This method returns the same value as Perl's:

  (stat $filename)[7]


TOP

stat

Get the specified file's stats.

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

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


TOP

user

Get the user id that owns the file:

  $uid = $finfo->user;

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.



TOP

valid

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

  $valid = $finfo->valid;


TOP

See Also

mod_perl 2.0 documentation.



TOP

Copyright

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



TOP

Authors

The mod_perl development team and numerous contributors.






TOP
previous page: APR::Error - Perl API for APR/Apache/mod_perl exceptionspage up: mod_perl 2.0 APInext page: APR::IpSubnet - Perl API for accessing APRs ip_subnet structures