NAME
FFI::Platypus::DL - Slightly non-portable interface to libdl
VERSION
version 2.04
SYNOPSIS
use FFI::Platypus 2.00;
use FFI::Platypus::DL;
my $handle = dlopen("./libfoo.so", RTLD_PLATYPUS_DEFAULT);
my $address = dlsym($handle, "my_function_named_foo");
my $ffi = FFI::Platypus->new( api => 2 );
$ffi->function($address => [] => 'void')->call;
dlclose($handle);
DESCRIPTION
This module provides an interface to libdl, the dynamic loader on UNIX. The underlying interface has always been used by FFI::Platypus, but it wasn't a public interface until version 0.52. The name was changed with that version when it became a public interface, so be sure to specify that version if you are going to use it.
It is somewhat non-portable for these reasons:
- GNU extensions
-
It provides some GNU extensions to platforms such as Linux that support them.
- Windows
-
It provides an emulation layer on Windows. The emulation layer only supports
RTLD_PLATYPUS_DEFAULT
as a flag. The emulation layer emulates the convention described below of passingundef
as the dynamic library name to mean, use the currently running executable. I've used it without any problems for years, but Windows is not my main development platform.
FUNCTIONS
dlopen
my $handle = dlopen($filename, $flags);
This opens a dynamic library in the context of the dynamic loader. $filename
is the full or relative path to a dynamic library (usually a .so
on Linux and some other UNIXen, a .dll
on Windows and a .dylib
on OS X). $flags
are flags that can be used to alter the behavior of the library and the symbols it contains. The return value is an opaque pointer or $handle
which can be used to look up symbols with dlsym
. The handle should be closed with dlclose
when you are done with it.
By convention if you pass in undef
for the filename, the currently loaded executable will be used instead of a separate dynamic library. This is the easiest and most portable way to find the address of symbols in the standard C library. This convention is baked into most UNIXen, but this capability is emulated in Windows which doesn't come with the capability out of the box.
If there is an error in opening the library then undef
will be returned and the diagnostic for the failure can be retrieved with dlerror
as described below.
Not all flags are supported on all platforms. You can test if a flag is available using can:
if(FFI::Platypus::DL->can('RTLD_LAZY'))
{
...
}
Typically where flags are not mutually exclusive, they can be or'd together:
my $handle = dlopen("libfoo.so", RTLD_LAZY | RTLD_GLOBAL);
Check your operating system documentation for detailed descriptions of these flags.
- RTLD_PLATYPUS_DEFAULT
-
This is the FFI::Platypus default for
dlopen
(NOTE: NOT the libdl default). This is the only flag supported on Windows. For historical reasons, this is usuallyRTLD_LAZY
on Unix and0
on Windows. - RTLD_LAZY
-
Perform lazy binding.
- RTLD_NOW
-
Resolve all symbols before returning from
dlopen
. Error if all symbols cannot resolve. - RTLD_GLOBAL
-
Symbols are shared.
- RTLD_LOCAL
-
Symbols are NOT shared.
- RTLD_NODELETE
-
glibc 2.2 extension.
- RTLD_NOLOAD
-
glibc 2.2 extension.
- RTLD_DEEPBIND
-
glibc 2.3.4 extension.
dlsym
my $opaque = dlsym($handle, $symbol);
This looks up the given $symbol
in the library pointed to by $handle
. If the symbol is found, the address for that symbol is returned as an opaque pointer. This pointer can be passed into the FFI::Platypus function
and attach
methods instead of a function name.
If the symbol cannot be found then undef
will be returned and the diagnostic for the failure can be retrieved with dlerror
as described below.
dlclose
my $status = dlclose($handle);
On success, dlclose
returns 0; on error, it returns a nonzero value, and the diagnostic for the failure can be retrieved with dlerror
as described below.
dlerror
my $error_string = dlerror;
Returns the human readable diagnostic for the reason for the failure for the most recent dl
prefixed function call.
CAVEATS
Some flags for dlopen
are not portable. This module may not be supported platforms added to FFI::Platypus in the future. It does work as far as I know on all of the currently supported platforms.
SEE ALSO
AUTHOR
Author: Graham Ollis <plicease@cpan.org>
Contributors:
Bakkiaraj Murugesan (bakkiaraj)
Dylan Cali (calid)
pipcet
Zaki Mughal (zmughal)
Fitz Elliott (felliott)
Vickenty Fesunov (vyf)
Gregor Herrmann (gregoa)
Shlomi Fish (shlomif)
Damyan Ivanov
Ilya Pavlov (Ilya33)
Petr Písař (ppisar)
Mohammad S Anwar (MANWAR)
Håkon Hægland (hakonhagland, HAKONH)
Meredith (merrilymeredith, MHOWARD)
Diab Jerius (DJERIUS)
Eric Brine (IKEGAMI)
szTheory
José Joaquín Atria (JJATRIA)
Pete Houston (openstrike, HOUSTON)
COPYRIGHT AND LICENSE
This software is copyright (c) 2015-2022 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.