NAME

Dyn::Load - FFI to Load Libaries and Access Their Symbols

SYNOPSIS

    use Dyn::Load qw[:all]; # Exports nothing by default
    use Dyn::Call;

    my $lib = dlLoadLibrary( 'path/to/lib.so' );
    my $ptr = dlFindSymbol( $lib, 'add' );
    my $cvm = Dyn::Call::dcNewCallVM(1024);
    Dyn::Call::dcMode( $cvm, 0 );
    Dyn::Call::dcReset( $cvm );
    Dyn::Call::dcArgInt( $cvm, 5 );
    Dyn::Call::dcArgInt( $cvm, 6 );
    Dyn::Call::dcCallInt( $cvm, $ptr ); #  '5 + 6 == 11';
    dlFreeSymbol( $lib );

DESCRIPTION

Dyn::Load wraps the dynload library encapsulates dynamic loading mechanisms and gives access to functions in foreign dynamic libraries and code modules.

Functions

Everything listed here may be imported by name or with the :all tag.

dlLoadLibrary( ... )

Loads a dynamic library at libpath and returns a handle to it for use in dlFreeLibrary( ... ) and dlFindSymbol( ... ) calls.

    my $lib = dlLoadLibrary( 'blah.dll' ); # Or .so, or just... "libmath", idk...

Passing undef for the libpath argument is valid, and returns a handle to the main executable of the calling code. Also, searching libraries in library paths (e.g. by just passing the library's leaf name) should work, however, they are OS specific. Returns a undef on error.

Expected parameters include:

libpath - string

dlFreeLibrary( ... )

Frees the loaded library.

Expected parameters include:

libhandle - pointer returned by dlLoadLibrary( ... )

dlFindSymbol( ... )

This function returns a pointer to a symbol with name symbol in the library with handle libhandle, or returns a undef pointer if the symbol cannot be found. The name is specified as it would appear in C source code (mangled if C++, etc.).

Expected parameters include:

libhandle - pointer returned by dlLoadLibrary( ... )

symbol - name of the symbol

dlGetLibraryPath( ... )

This function can be used to get a copy of the path to the library loaded with handle libhandle.

    my $len = dlGetLibraryPath($libhandle, $sOut, 1024);

The parameter sOut is a pointer to a buffer of size bufSize (in bytes), to hold the output string.

Expected parameters include:

libhandle - pointer returned by dlLoadLibrary( ... )

sOut - pointer to buffer

bufSize - buffer size in bytes

The return value is the size of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be looked up. If bufSize >= return value >1, a null-terminated string with the path to the library should be in sOut. If it returns 0, the library name wasn't able to be found. Please note that this might happen in some rare cases, so make sure to always check.

dlSymsInit( ... )

Returns a handle to the shared object specified by libPath for use with other dlSyms* functions.

    my $dlsym = dlSymsInit();

The dlSyms* functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made for symbol name lookups, not to get symbols' addresses. For that refer to dlFindSymbol( ... ).

Expected parameters include:

libPath - path to the lib

The handle must be freed with dlSymsCleanup( ... ).

dlSymsCleanup( ... )

Frees the handle to the shared object created by dlSymsInit( ... ).

    dlSymsCleanup( $dlsym );

Expected parameters include:

pSyms - shared object

dlSymsCount( ... )

Returns the number of exported symbols in the library.

    my $count = dlSymsCount( $dlsym );

Expected parameters include:

pSyms - shared object created by dlSymsInit( ... ).

dlSymsName( ... )

Returns the name of the symbol at a certain index.

    my $name = dlSymsName( $dlsym, 1 );

Expected parameters include:

pSyms - shared object

index - ordinal index of desired symbol

The name is returned as it would appear in C source code (mangled if C++, etc.).

dlSymsNameFromValue( ... )

Returns the name of the symbol at a certain address.

    my $name = dlSymsNameFromValue( $dlsym, ... );

Expected parameters include:

pSyms - shared object

value - address of desired symbol

The name is returned as it would appear in C source code (mangled if C++, etc.).

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>

cpanm Dyn

perl -MCPAN -e shell
install Dyn