/ 
File-stat-Extra-0.003
River stage zero No dependents
⭐ Starred 0 GitHub stars
/ File::stat::Extra

NAME

File::stat::Extra - An extension of the File::stat module, provides additional methods.

VERSION

version 0.003

SYNOPSIS

use File::stat::Extra;

$st = lstat($file) or die "No $file: $!";

if ($st->isLink) {
    print "$file is a symbolic link";
}

if (-x $st) {
    print "$file is executable";
}

use Fcntl 'S_IRUSR';
if ( $st->cando(S_IRUSR, 1) ) {
    print "My effective uid can read $file";
}

if ($st == stat($file)) {
    printf "%s and $file are the same", $st->file;
}

DESCRIPTION

This module's default exports override the core stat() and lstat() functions, replacing them with versions that return File::stat::Extra objects when called in scalar context. In list context the same 13 item list is returned as with the original stat and lstat functions.

File::stat::Extra is an extension of the File::stat module.

  • Returns non-object result in list context.

  • You can now pass in bare file handles to stat and lstat under use strict.

  • File tests -t -T, and -B have been implemented too.

  • Convenience functions filetype and permissions for direct access to filetype and permission parts of the mode field.

  • Named access to common file tests (isRegular / isFile, isDir, isLink, isBlock, isChar, isFIFO / isPipe, isSocket).

  • Access to the name of the file / file handle used for the stat (file, abs_file / target).

FUNCTIONS

stat( FILEHANDLE )

stat( DIRHANDLE )

stat( EXPR )

lstat( FILEHANDLE )

lstat( DIRHANDLE )

lstat( EXPR )

When called in list context, these functions behave as the original stat and lstat functions, returning the 13 element stat list. When called in scalar context, a File::stat::Extra object is returned with the methods as outlined below.

METHODS

dev

ino

mode

uid

gid

rdev

size

atime

mtime

ctime

blksize

blocks

These methods provide named acced to the same fields in the original stat result. Just like the original File::stat.

cando( ACCESS, EFFECTIVE )

Interprets the mode, uid and gid fields, and returns whether or not the current process would be allowed the specified access.

ACCESS is one of S_IRUSR, S_IWUSR or S_IXUSR from the Fcntl module, and EFFECTIVE indicates whether to use effective (true) or real (false) ids.

file

Returns the full path to the original file (or the filehandle) on which stat or lstat was called.

Note: Symlinks are not resolved. And, like rel2abs, neither are x/../y constructs. Use the abs_file / target methods to resolve these too.

abs_file

target

Returns the absolute path of the file. In case of a file handle, this is returned unaltered.

permissions

Returns just the permissions (including setuid/setgid/sticky bits) of the mode stat field.

filetype

Returns just the filetype of the mode stat field.

isFile

isRegular

Returns true if the file is a regular file (same as -f file test).

isDir

Returns true if the file is a directory (same as -d file test).

Returns true if the file is a symbolic link (same as -l file test).

Note: Only relevant when lstat was used!

isBlock

Returns true if the file is a block special file (same as -b file test).

isChar

Returns true if the file is a character special file (same as -c file test).

isFIFO

isPipe

Returns true if the file is a FIFO file or, in case of a file handle, a pipe (same as -p file test).

isSocket

Returns true if the file is a socket file (same as -S file test).

-X operator

You can use the file test operators on the File::stat::Extra object just as you would on a file (handle). However, instead of querying the file system, these operators will use the information from the object itself.

Note: in case of the special file tests -t, -T, and -B, the file (handle) is tested the first time the operator is used. After the first time, the initial result is re-used.

Unary "" (stringification) and other operators

The unary "" operator is overloaded to return the the device and inode numbers separated by a . (dev.ino). This yields a uniqe file identifier.

All other operators are automagically generated based on this representation, meaning you can easily compare two File::stat::Extra objects to see if they are the same (hardlinked) file.

WARNINGS

When a file (handle) can not be (l)stat-ed, a warning Unable to stat: %s. To disable this warning, specify

no warnings "File::stat::Extra";

The following warnings are inhereted from File::stat, these can all be disabled with

no warnings "File::stat";
File::stat ignores use filetest 'access'

You have tried to use one of the -rwxRWX filetests with use filetest 'access' in effect. File::stat will ignore the pragma, and just use the information in the mode member as usual.

File::stat ignores VMS ACLs

VMS systems have a permissions structure that cannot be completely represented in a stat buffer, and unlike on other systems the builtin filetest operators respect this. The File::stat overloads, however, do not, since the information required is not available.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/HayoBaan/File-stat-Extra/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

COMPATIBILITY

As with File::stat, you can no longer use the implicit $_ or the special filehandle _ with this module's versions of stat and lstat.

Currently File::stat::Extra only provides an object interface, the File::stat $st_* variables and st_cando funtion are not available. This may change in a future version of this module.

SEE ALSO

  • File::stat for the module for which File::stat::Extra is the extension.

  • stat and lstat for the original stat and lstat functions.

AUTHOR

Hayo Baan <info@hayobaan.nl>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Hayo Baan.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.