FFI::C::Stat(3)

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.