NAME

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

VERSION

    version 0.010

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

 nlink

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

 isLink

    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.

    The overloaded filetests are only supported from Perl version 5.12 and
    higer. The named access to these tests can still be used though.

    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 and no further testing of the file
    (handle) is performed.

 Unary "" (stringification) operator

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

 Comparison operators <=>, cmp, and ~~

    The comparison operators use the string representation of the
    File::stat::Extra object. So, to see if two File::stat::Extra object
    point to the same (hardlinked) file, you can simply say something like
    this:

        print 'Same file' if $obj1 == $obj2;

    For objects created from an stat of a symbolic link, the actual
    destination of the link is used in the comparison! If you want to
    compare the actual symlink file, use lstat instead.

    Note: All comparisons (also the numeric versions) are performed on the
    full stringified versions of the object. This to prevent files on the
    same device, but with an inode number ending in a zero to compare
    equally while they aren't (e.g., 5.10 and 5.100 compare equal
    numerically but denote a different file).

    Note: the smartmatch ~~ operator is only overloaded on Perl version
    5.10 and above.

 Other operators

    As the other operators (+, -, *, etc.) are meaningless, they have not
    been overloaded and will cause a run-time error.

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

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.