/ 
Apache2-SSI-v0.2.9
River stage zero No dependents
/ Apache2::SSI::Finfo

NAME

Apache2::SSI::Finfo - Apache2 Server Side Include File Info Object Class

SYNOPSIS

my $finfo = Apache2::SSI::Finfo->new( '/some/file/path.html' );
# or with Apache
use Apache2::RequestRec ();
use apache2::RequestUtil ();
my $r = Apache2::RequestUtil->request;
my $finfo = Apache2::SSI::Finfo->new( '/some/file/path.html', apache_request => $r );
# Direct access to APR::Finfo
my $apr = $finfo->apr_finfo;
# Get access time as a DateTime object
$finfo->atime;
# Block site
$finfo->blksize;
# Number of blocks
$finfo->blocks;
if( $finfo->can_read )
{
    # Do something
}
# Can also use
$finfo->can_write;
$finfo->can_exec;
$finfo->csize;
# Inode change time as a DateTime object
$finfo->ctime;
$finfo->dev;
if( $finfo->exists )
{
    # Do something
}
print "File path is: ", $finfo->filepath;
if( $finfo->filetype == Apache2::SSI::Finfo::FILETYPE_NOFILE )
{
    # File does not exist
}
# Same as $finfo->filepath
print "File path is: ", $finfo->fname;
print "File group id is: ", $finfo->gid;
# Can also use $finfo->group which will yield the same result
$finfo->ino;
# or $finfo->inode;
if( $finfo->is_block )
{
    # Do something
}
elsif( $finfo->is_char )
{
    # Do something else
}
elsif( $finfo->is_dir )
{
    # It's a directory
}
elsif( $finfo->is_file )
{
    # It's a regular file
}
elsif( $finfo->is_link )
{
    # A file alias
}
elsif( $info->is_pipe )
{
    # A Unix pipe !
}
elsif( $finfo->is_socket )
{
    # It's a socket
}
elsif( ( $info->mode & 0100 ) )
{
    # Can execute
}
$finfo->mtime->strftime( '%A %d %B %Y %H:%m:%S' );
print "File base name is: ", $finfo->name;
printf "File has %d links\n", $finfo->nlink;
print "File permission in hexadecimal: ", $finfo->protection;
$finfo->rdev;
$finfo->size;
my $new_object = $finfo->stat( '/some/other/file.txt' );
# Get the user id
$finfo->uid;
# Or
$finfo->user;

VERSION

v0.1.3

DESCRIPTION

This class provides a file info object oriented consistant whether it is accessed from Apache/mod_perl2 environment or from outside of it.

The other advantage is that even if a non-existing file is provided, an object is returned. Obviously many of this module's methods will return an empty value since the file does not actually exist. This is an advantage, because one cannot create an APR::Finfo object over a non-existing file.

METHODS

new

This instantiate an object that is used to access other key methods. It takes a file path followed by the following parameters:

apache_request

This is the Apache2::RequestRec object that is provided if running under mod_perl.

it can be retrieved from "request" in Apache2::RequestUtil or via "r" in Apache2::Filter

You can get this Apache2::RequestRec object by requiring Apache2::RequestUtil and calling its class method "request" in Apache2::RequestUtil such as Apache2::RequestUtil-request> and assuming you have set PerlOptions +GlobalRequest in your Apache Virtual Host configuration.

Note that there is a main request object and subprocess request object, so to find out which one you are dealing with, use "is_initial_req" in Apache2::RequestUtil, such as:

use Apache2::RequestUtil (); # extends Apache2::RequestRec objects
my $r = $r->is_initial_req ? $r : $r->main;

apache_request

Sets or gets the Apache2::RequestRec object. As explained in the "new" method, you can get this Apache object by requiring the package Apache2::RequestUtil and calling "request" in Apache2::RequestUtil such as Apache2::RequestUtil-request> assuming you have set PerlOptions +GlobalRequest in your Apache Virtual Host configuration.

When running under Apache mod_perl this is set automatically from the special "handler" method, such as:

my $r = $f->r; # $f is the Apache2::Filter object provided by Apache

apr_finfo

Sets or gets the APR::Finfo object when running under Apache/mod_perl. Note that this value might be empty if the file does not exist. This is mentioned here for completeness only.

atime

Returns the file last access time as a Apache2::SSI::Datetime object, which stringifies to its value in second since epoch. Apache2::SSI::Datetime is just a wrapper around DateTime to allow a DateTime to be used in comparison with another non DateTime value.

For example:

if( $finfo->atime > time() + 86400 )
{
    print( "You are traveling in the future\n" );
}

blksize

Returns the preferred I/O size in bytes for interacting with the file. You can also use block_size.

blocks

Returns the actual number of system-specific blocks allocated on disk (often, but not always, 512 bytes each).

can_read

Returns true if the the effective user can read the file.

can_write

Returns true if the the effective user can write to the file.

can_exec

Returns true if the the effective user can execute the file. Same as "execute"

can_execute

Returns true if the the effective user can execute the file. Same as "exec"

csize

Returns the total size of file, in bytes. Same as "size"

ctime

Returns the file inode change time as a Apache2::SSI::Datetime object, which stringifies to its value in second since epoch. Apache2::SSI::Datetime is just a wrapper around DateTime to allow a DateTime to be used in comparison with another non DateTime value.

dev

Returns the device number of filesystem. Same as "dev"

device

Returns the device number of filesystem. Same as "device"

exists

Returns true if the filetype is not "FILETYPE_NOFILE"

filepath

Returns the file path as a string. Same as "fname"

filetype

Returns the file type which is one of the "CONSTANTS" below.

fname

Returns the file path as a string. Same as "filepath"

gid

Returns the numeric group ID of file's owner. Same as "group"

group

Returns the numeric group ID of file's owner. Same as "gid"

inode

Returns the inode number.

is_block

Returns true if this is a block file, false otherwise.

is_char

Returns true if this is a character file, false otherwise.

is_dir

Returns true if this is a directory, false otherwise.

is_file

Returns true if this is a regular file, false otherwise.

Returns true if this is a symbolic link, false otherwise.

is_pipe

Returns true if this is a pipe, false otherwise.

is_socket

Returns true if this is a socket, false otherwise.

mime_type

Using Apache2::SSI::File::Type, this guess the file mime type and returns it.

mode

Returns the file mode. This is equivalent to the mode & 07777, ie without the file type bit.

So you could do something like:

if( $finfo->mode & 0100 )
{
    print( "Owner can execute\n" );
}
if( $finfo->mode & 0001 )
{
    print( "Everyone can execute too!\n" );
}

mtime

Returns the file last modify time as a Apache2::SSI::Datetime object, which stringifies to its value in second since epoch. Apache2::SSI::Datetime is just a wrapper around DateTime to allow a DateTime to be used in comparison with another non DateTime value.

name

Returns the file base name. So if the file is /home/john/www/some/file.html this would return file.html

Interesting to note that "name" in APR::Finfo which is advertised as returning the file base name, actually returns just an empty string. With this module, this uses a workaround to provide the proper value. It use "basename" in File::Basename on the value returned by "fname"

Returns the number of (hard) links to the file.

protection

rdev

Returns the device identifier (special files only).

size

Returns the total size of file, in bytes. Same as "csize"

stat

Provided with a file path and this returns a new Apache2::SSI::Finfo object.

uid

user

Returns the numeric user ID of file's owner. Same as "uid"

uid

Returns the numeric user ID of file's owner. Same as "user"

CONSTANTS

FILETYPE_NOFILE

File type constant to indicate the file does not exist.

FILETYPE_REG

Regular file

FILETYPE_DIR

The element is a directory

FILETYPE_CHR

The element is a character block

FILETYPE_BLK

A block device

FILETYPE_PIPE

The file is a FIFO or a pipe

FILETYPE_LNK

The file is a symbolic link

FILETYPE_SOCK

The file is a (unix domain) socket

FILETYPE_UNKFILE

The file is of some other unknown type or the type cannot be determined

AUTHOR

Jacques Deguest <jack@deguest.jp>

CPAN ID: jdeguest

https://gitlab.com/jackdeguest/Apache2-SSI

SEE ALSO

Apache2::SSI::File, Apache2::SSI::URI, Apache2::SSI

mod_include, mod_perl(3), APR::Finfo, "stat" in perlfunc https://httpd.apache.org/docs/current/en/mod/mod_include.html, https://httpd.apache.org/docs/current/en/howto/ssi.html, https://httpd.apache.org/docs/current/en/expr.html https://perl.apache.org/docs/2.0/user/handlers/filters.html#C_PerlOutputFilterHandler_

COPYRIGHT & LICENSE

Copyright (c) 2020-2021 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.