NAME

       FFI::Platypus::DL - Slightly non-portable interface to libdl

VERSION

       version 2.10

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 passing "undef" 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 usually "RTLD_LAZY" on Unix and 0 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

       FFI::Platypus

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)

       Lukas Mai (MAUKE)

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.

perl v5.40.0                                       2025-01-11                             FFI::Platypus::DL(3pm)