NAME

    FFI::C::Stat - Object-oriented FFI interface to native stat and lstat

VERSION

    version 0.03

SYNOPSIS

     use FFI::C::Stat;
     
     my $stat = FFI::C::Stat->new("foo.txt");
     print "size = ", $stat->size;

DESCRIPTION

    Perl comes with perfectly good stat, lstat functions, however if you
    are writing FFI bindings for a library that use the C stat structure,
    you are out of luck there. This module provides an FFI friendly
    interface to the C stat function, which uses an object similar to
    File::stat, except the internals are a real C struct that you can pass
    into C APIs that need it.

    Supposing you have a C function:

     void
     my_cfunction(struct stat *s)
     {
       ...
     }

    You can bind my_cfunction like this:

     use FFI::Platypus 1.00;
     
     my $ffi = FFI::Platypus->new( api => 1 );
     $ffi->type('object(FFI::C::Stat)' => 'stat');
     $ffi->attach( my_cfunction => ['stat'] => 'void' );

CONSTRUCTORS

 new

     my $stat = FFI::C::Stat->new(*HANDLE,   %options);
     my $stat = FFI::C::Stat->new($filename, %options);
     my $stat = FFI::C::Stat->new;

    You can create a new instance of this class by calling the new method
    and passing in either a file or directory handle, or by passing in the
    filename path. If you do not pass anything then an uninitialized stat
    will be returned.

    Options:

    symlink

      Use lstat instead of stat, that is if the filename is a symlink, stat
      the symlink instead of the target.

 clone

     my $stat = FFI::C::Stat->clone($other_stat);

    Creates a clone of $stat. The argument $stat can be either a
    FFI::C::Stat instance, or an opaque pointer to a stat structure. The
    latter case is helpful when writing bindings to a method that returns a
    stat structure, since you won't be wanting to free the pointer that
    belongs to the callee.

    C:

     struct stat *
     my_cfunction()
     {
       static struct stat stat;  /* definitely do not want to free static memory */
       ...
       return stat;
     }

    Perl:

     $ffi->attach( my_cfunction => [] => 'opaque' => sub {
       my $xsub = shift;
       my $ptr = $xsub->();
       return FFI::C::Stat->clone($ptr);
     });

    The behavior of passing in undef prior to version 0.03 was undefined
    and could cause a crash. In version 0.03 and later passing in undef
    will return a stat object with all of the bits set to zero (0).

PROPERTIES

 dev

     my $id = $stat->dev;

    The ID of device containing file.

 ino

     my $inode = $stat->ino;

    The inode number.

 mode

     my $mode = $stat->mode;

    The file type and mode.

 nlink

     my $n = $stat->nlink;

    The number of hard links.

 uid

     my $uid = $stat->uid;

    The User ID owner.

 gid

     my $gid = $stat->gid;

    The Group ID owner.

 rdev

     my $id = $stat->rdev;

    The ID of device (if special file)

 size

     my $size = $stat->size;

    Returns the size of the file in bytes.

 atime

     my $time = $stat->atime;

    The time of last access.

 mtime

     my $time = $stat->mtime;

    The time of last modification.

 ctime

     my $time = $stat->ctime;

    The time of last status change.

 blksize

     my $size = $stat->blksize;

    The filesystem-specific preferred I/O block size.

 blocks

     my $count = $stat->blocks;

    Number of blocks allocated.

AUTHOR

    Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2021-2023 by Graham Ollis.

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