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:
dlFreeLibrary( ... )
Frees the loaded library.
Expected parameters include:
libhandle
- pointer returned bydlLoadLibrary( ... )
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 bydlLoadLibrary( ... )
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 bydlLoadLibrary( ... )
sOut
- pointer to bufferbufSize
- 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:
The handle must be freed with dlSymsCleanup( ... )
.
dlSymsCleanup( ... )
Frees the handle to the shared object created by dlSymsInit( ... )
.
dlSymsCleanup( $dlsym );
Expected parameters include:
dlSymsCount( ... )
Returns the number of exported symbols in the library.
my $count = dlSymsCount( $dlsym );
Expected parameters include:
dlSymsName( ... )
Returns the name of the symbol at a certain index.
my $name = dlSymsName( $dlsym, 1 );
Expected parameters include:
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:
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>