view release on metacpan or  search on metacpan

lib/Affix.pm  view on Meta::CPAN

Normal Perl signatures do not convey the type of arguments a native function
expects and what it returns so you must define them with our final attribute:
C<:Signature>

    use Affix;
    sub add :Native("calculator") :Signature([Int, Int] => Int);

Here, we have declared that the function takes two 32-bit integers and returns
a 32-bit integer. You can find the other types that you may pass L<further down
this page|/Types>.

=head2 ABI/API version

If you write C<:Native('foo')>, Affix will search C<libfoo.so> under Unix like
system (C<libfoo.dynlib> on macOS, C<foo.dll> on Windows). In most modern
system it will require you or the user of your module to install the
development package because it's recommended to always provide an API/ABI
version to a shared library, so C<libfoo.so> ends often being a symbolic link
provided only by a development package.

To avoid that, the C<:Native> attribute allows you to specify the API/ABI
version. It can be a full version or just a part of it. (Try to stick to Major
version, some BSD code does not care for Minor.)

    use Affix;
    sub foo1 :Native('foo', v1); # Will try to load libfoo.so.1
    sub foo2 :Native('foo', v1.2.3); # Will try to load libfoo.so.1.2.3

    sub pow : Native('m', v6) : Signature([Double, Double] => Double);

=head2 Library Paths and Names

The C<:Native> attribute, C<affix( ... )>, and C<wrap( ... )> all accept the
library name, the full path, or a subroutine returning either of the two. When
using the library name, the name is assumed to be prepended with lib and
appended with C<.so> (or just appended with C<.dll> on Windows), and will be
searched for in the paths in the C<LD_LIBRARY_PATH> (C<PATH> on Windows)
environment variable.

You can also put an incomplete path like C<'./foo'> and Affix will
automatically put the right extension according to the platform specification.
If you wish to suppress this expansion, simply pass the string as the body of a
block.

    sub bar :Native({ './lib/Non Standard Naming Scheme' });

B<BE CAREFUL>: the C<:Native> attribute and constant might be evaluated at
compile time.

=head2 Calling into the standard library

If you want to call a function that's already loaded, either from the standard
library or from your own program, you can omit the library value or pass and
explicit C<undef>.

For example on a UNIX-like operating system, you could use the following code
to print the home directory of the current user:

    use Affix;
    use Data::Dumper;
    typedef PwStruct => Struct [
        name  => Str,     # username
        pass  => Str,     # hashed pass if shadow db isn't in use
        uuid  => UInt,    # user
        guid  => UInt,    # group
        gecos => Str,     # real name
        dir   => Str,     # ~/
        shell => Str      # bash, etc.
    ];
    sub getuid : Native : Signature([]=>Int);
    sub getpwuid : Native : Signature([Int]=>Pointer[PwStruct]);
    my $data = main::getpwuid( getuid() );
    print Dumper( ptr2sv( $data, Pointer [ PwStruct() ] ) );

=head1 Memory Functions

To help toss raw data around, some standard memory related functions are
exposed here. You may import them by name or with the C<:memory> or C<:all>
tags.

=head2 C<malloc( ... )>

    my $ptr = malloc( $size );

Allocates C<$size> bytes of uninitialized storage.

=head2 C<calloc( ... )>

    my $ptr = calloc( $num, $size );

Allocates memory for an array of C<$num> objects of C<$size> and initializes
all bytes in the allocated storage to zero.

=head2 C<realloc( ... )>

    $ptr = realloc( $ptr, $new_size );

Reallocates the given area of memory. It must be previously allocated by
C<malloc( ... )>, C<calloc( ... )>, or C<realloc( ... )> and not yet freed with
a call to C<free( ... )> or C<realloc( ... )>. Otherwise, the results are
undefined.

=head2 C<free( ... )>

    free( $ptr );

Deallocates the space previously allocated by C<malloc( ... )>, C<calloc( ...
)>, or C<realloc( ... )>.

=head2 C<memchr( ... )>

    memchr( $ptr, $ch, $count );

Finds the first occurrence of C<$ch> in the initial C<$count> bytes (each
interpreted as unsigned char) of the object pointed to by C<$ptr>.

=head2 C<memcmp( ... )>

    my $cmp = memcmp( $lhs, $rhs, $count );