NAME
FFI::Raw - Perl bindings to the portable FFI library (libffi)
VERSION
version 0.04
SYNOPSIS
use FFI::Raw;
my $cos = FFI::Raw->new(
'libm.so', 'cos',
FFI::Raw::double, # return value
FFI::Raw::double # arg #1
);
say $cos->call(2.0);DESCRIPTION
FFI::Raw provides a low-level foreign function interface (FFI) for Perl based on libffi. In essence, it can access and call functions exported by shared libraries without the need to write C/XS code.
Dynamic symbols can be automatically resolved at runtime so that the only information needed to use FFI::Raw is the name (or path) of the target library, the name of the function to call and its signature (though it is also possible to pass a function pointer obtained, for example, using DynaLoader).
Note that this module has nothing to do with FFI.
CONSTRUCTORS
new
my $ffi = FFI::Raw->new( $library, $function, $return_type, @arg_types )Create a new FFI::Raw object. It loads $library, finds the function $function with return type $return_type and creates a calling interface.
If $library is undef then the function is searched in the main program.
This method also takes a variable number of types, representing the arguments of the wanted function.
new_from_ptr
my $ffi = FFI::Raw->new_from_ptr( $function_ptr, $return_type, @arg_types )Create a new FFI::Raw object from the $function_ptr function pointer.
This method also takes a variable number of types, representing the arguments of the wanted function.
METHODS
call
my $ret = $ffi->call( @args)Execute the FFI::Raw function. This method also takes a variable number of arguments, which are passed to the called function. The argument types must match the types passed to new (or new_from_ptr).
The FFI::Raw object can be used as a CODE reference as well. Dereferencing the object will work just like call():
$cos->call(2.0); # normal call() call
$cos->(2.0); # dereference as CODE refThis works because FFI::Raw overloads the &{} operator.
coderef
my $code = FFI::Raw->coderef;Return a code reference of a given FFI::Raw.
SUBROUTINES
memptr
my $memptr = FFI::Raw::memptr( $length );Create a FFI::Raw::MemPtr. This is a shortcut for FFI::Raw::MemPtr->new(...).
callback
my $callback = FFI::Raw::callback( $coderef, $ret_type, \@arg_types );Create a FFI::Raw::Callback. This is a shortcut for FFI::Raw::Callback->new(...).
TYPES
Caveats on the way types were defined by the original FFI::Raw:
This module uses the common convention that char is 8 bits, short is 16 bits, int is 32 bits, long is 32 bits on a 32bit arch and 64 bits on a 64 bit arch, int64 is 64 bits. While this is probably true on most modern platforms (if not all), it isn't technically guaranteed by the standard. FFI::Platypus itself, differs in that int, long, etc are the native sizes, even if they do not follow this common convention and you need to use sint32, sint64, etc if you want a specific sized type.
This module also assumes that char is signed. Although this is commonly true on many platforms it is not guaranteed by the standard. On Windows, for example the char type is unsigned. FFI::Platypus by contrast follows to the standard where char uses the native behavior, and if you want an signed character type you can use sint8 instead.
void
my $type = FFI::Raw::void();Return a FFI::Raw void type.
int
my $type = FFI::Raw::int();Return a FFI::Raw integer type.
uint
my $type = FFI::Raw::uint();Return a FFI::Raw unsigned integer type.
short
my $type = FFI::Raw::short();Return a FFI::Raw short integer type.
ushort
my $type = FFI::Raw::ushort();Return a FFI::Raw unsigned short integer type.
long
my $type = FFI::Raw::long();Return a FFI::Raw long integer type.
ulong
my $type = FFI::Raw::ulong();Return a FFI::Raw unsigned long integer type.
int64
my $type = FFI::Raw::int64();Return a FFI::Raw 64 bit integer type. This requires Math::Int64 to work.
uint64
my $type = FFI::Raw::uint64();Return a FFI::Raw unsigned 64 bit integer type. This requires Math::Int64 to work.
char
my $type = FFI::Raw::char();Return a FFI::Raw char type.
uchar
my $type = FFI::Raw::uchar();Return a FFI::Raw unsigned char type.
float
my $type = FFI::Raw::float();Return a FFI::Raw float type.
double
my $type = FFI::Raw::double();Return a FFI::Raw double type.
str
my $type = FFI::Raw::str();Return a FFI::Raw string type.
ptr
my $type = FFI::Raw::ptr();Return a FFI::Raw pointer type.
SEE ALSO
FFI::Platypus, Alt::FFI::Raw::Platypus
AUTHOR
Graham Ollis <plicease@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2019 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.