FFI::C - C data types for FFI
version 0.01
In C:
#include <stdint.h> typedef struct { uint8_t red; uint8_t green; uint8_t blue; } color_value_t; typedef struct { char name[22]; color_value_t value; } named_color_t; typedef named_color_t array_named_color_t[4]; typedef union { uint8_t u8; uint16_t u16; uint32_t u32; uint64_t u64; } anyint_t;
In Perl:
use FFI::C; package ColorValue { FFI::C->struct([ red => 'uint8', green => 'uint8', blue => 'uint8', ]); } package NamedColor { FFI::C->struct([ name => 'string(22)', value => 'color_value_t', ]); } package ArrayNamedColor { FFI::C->array(['named_color_t' => 4]); }; my $array = ArrayNamedColor->new([ { name => "red", value => { red => 255 } }, { name => "green", value => { green => 255 } }, { name => "blue", value => { blue => 255 } }, { name => "purple", value => { red => 255, blue => 255 } }, ]); # dim each color by 1/2 foreach my $color (@$array) { $color->value->red ( $color->value->red / 2 ); $color->value->green( $color->value->green / 2 ); $color->value->blue ( $color->value->blue / 2 ); } # print out the colors foreach my $color (@$array) { printf "%s [%02x %02x %02x]\n", $color->name, $color->value->red, $color->value->green, $color->value->blue; } package AnyInt { FFI::C->union([ u8 => 'uint8', u16 => 'uint16', u32 => 'uint32', u64 => 'uint64', ]); } my $int = AnyInt->new({ u8 => 42 }); print $int->u32;
This distribution provides tools for building classes to interface for common C data types. Arrays, struct, union and nested types based on those are supported.
struct
union
FFI::C->struct($name, \@members); FFI::C->struct(\@members);
Generate a new FFI::C::Struct class with the given @members into the calling package. (@members should be a list of name/type pairs). You may optionally give a $name which will be used for the FFI::Platypus type name for the generated class. If you do not specify a $name, a C style name will be generated from the last segment in the calling package name by converting to snake case and appending a _t to the end.
@members
$name
_t
As an example, given:
package MyLibrary::FooBar { FFI::C->struct([ a => 'uint8', b => 'float', ]); };
You can use MyLibrary::FooBar via the file scoped FFI::Platypus instance using the type foo_bar_t.
MyLibrary::FooBar
foo_bar_t
my $foobar = MyLibrary::FooBar->new({ a => 1, b => 3.14 }); $ffi->function( my_library_func => [ 'foo_bar_t' ] => 'void' )->call($foobar);
FFI::C->union($name, \@members); FFI::C->union(\@members);
This works exactly like the struct method above, except a FFI::C::Union class is generated instead.
FFI::C->array($name, [$type, $count]); FFI::C->array($name, [$type]); FFI::C->array([$type, $count]); FFI::C->array([$type]);
This is similar to struct and union above, except FFI::C::Array is generated. For an array you give it the member type and the element count. The element count is optional for variable length arrays, but keep in mind that when you create such an array you do need to provide a size.
use FFI::Platypus 1.00; use FFI::C; my $ffi = FFI::Platypus->new( api => 1, lib => [undef], ); FFI::C->ffi($ffi); package Unix::TimeStruct { FFI::C->struct(tm => [ tm_sec => 'int', tm_min => 'int', tm_hour => 'int', tm_mday => 'int', tm_mon => 'int', tm_year => 'int', tm_wday => 'int', tm_yday => 'int', tm_isdst => 'int', tm_gmtoff => 'long', _tm_zone => 'opaque', ]); # For now 'string' is unsupported by FFI::C, but we # can cast the time zone from an opaque pointer to # string. sub tm_zone { my $self = shift; $ffi->cast('opaque', 'string', $self->_tm_zone); } # attach the C localtime function $ffi->attach( localtime => ['time_t*'] => 'tm', sub { my($inner, $class, $time) = @_; $time = time unless defined $time; $inner->(\$time); }); } # now we can actually use our My::UnixTime class my $time = Unix::TimeStruct->localtime; printf "time is %d:%d:%d %s\n", $time->tm_hour, $time->tm_min, $time->tm_sec, $time->tm_zone;
FFI::C objects must be passed into C via FFI::Platypus by pointers. So-called "pass-by-value" is not and will not be supported. For "pass-by-value" record types, you should instead use FFI::Platypus::Record.
Graham Ollis <plicease@cpan.org>
This software is copyright (c) 2020 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.
To install FFI::C, copy and paste the appropriate command in to your terminal.
cpanm
cpanm FFI::C
CPAN shell
perl -MCPAN -e shell install FFI::C
For more information on module installation, please visit the detailed CPAN module installation guide.