.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "FFI::Platypus::DL 3pm"
.TH FFI::Platypus::DL 3pm "2020-11-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
FFI::Platypus::DL \- Slightly non\-portable interface to libdl
.SH "VERSION"
.IX Header "VERSION"
version 1.34
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use FFI::Platypus;
\& 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 => 1 );
\& $ffi\->function($address => [] => \*(Aqvoid\*(Aq)\->call;
\& dlclose($handle);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an interface to libdl, the dynamic loader on \s-1UNIX.\s0  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.
.PP
It is somewhat non-portable for these reasons:
.IP "\s-1GNU\s0 extensions" 4
.IX Item "GNU extensions"
It provides some \s-1GNU\s0 extensions to platforms such as Linux that support them.
.IP "Windows" 4
.IX Item "Windows"
It provides an emulation layer on Windows.  The emulation layer only supports \f(CW\*(C`RTLD_PLATYPUS_DEFAULT\*(C'\fR
as a flag.  The emulation layer emulates the convention described below of passing \f(CW\*(C`undef\*(C'\fR 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.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "dlopen"
.IX Subsection "dlopen"
.Vb 1
\& my $handle = dlopen($filename, $flags);
.Ve
.PP
This opens a dynamic library in the context of the dynamic loader.  \f(CW$filename\fR is the full or
relative path to a dynamic library (usually a \f(CW\*(C`.so\*(C'\fR on Linux and some other UNIXen, a \f(CW\*(C`.dll\*(C'\fR on
Windows and a \f(CW\*(C`.dylib\*(C'\fR on \s-1OS X\s0).  \f(CW$flags\fR 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 \f(CW$handle\fR
which can be used to look up symbols with \f(CW\*(C`dlsym\*(C'\fR.  The handle should be closed with \f(CW\*(C`dlclose\*(C'\fR
when you are done with it.
.PP
By convention if you pass in \f(CW\*(C`undef\*(C'\fR 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.
.PP
If there is an error in opening the library then \f(CW\*(C`undef\*(C'\fR will be returned and the diagnostic
for the failure can be retrieved with \f(CW\*(C`dlerror\*(C'\fR as described below.
.PP
Not all flags are supported on all platforms.  You can test if a flag is available using can:
.PP
.Vb 4
\& if(FFI::Platypus::DL\->can(\*(AqRTLD_LAZY\*(Aq))
\& {
\&   ...
\& }
.Ve
.PP
Typically where flags are not mutually exclusive, they can be or'd together:
.PP
.Vb 1
\& my $handle = dlopen("libfoo.so", RTLD_LAZY | RTLD_GLOBAL);
.Ve
.PP
Check your operating system documentation for detailed descriptions of these flags.
.IP "\s-1RTLD_PLATYPUS_DEFAULT\s0" 4
.IX Item "RTLD_PLATYPUS_DEFAULT"
This is the FFI::Platypus default for \f(CW\*(C`dlopen\*(C'\fR (\s-1NOTE: NOT\s0 the libdl default).  This is the only
flag supported on Windows.  For historical reasons, this is usually \f(CW\*(C`RTLD_LAZY\*(C'\fR on Unix and \f(CW0\fR on
Windows.
.IP "\s-1RTLD_LAZY\s0" 4
.IX Item "RTLD_LAZY"
Perform lazy binding.
.IP "\s-1RTLD_NOW\s0" 4
.IX Item "RTLD_NOW"
Resolve all symbols before returning from \f(CW\*(C`dlopen\*(C'\fR.  Error if all symbols cannot resolve.
.IP "\s-1RTLD_GLOBAL\s0" 4
.IX Item "RTLD_GLOBAL"
Symbols are shared.
.IP "\s-1RTLD_LOCAL\s0" 4
.IX Item "RTLD_LOCAL"
Symbols are \s-1NOT\s0 shared.
.IP "\s-1RTLD_NODELETE\s0" 4
.IX Item "RTLD_NODELETE"
glibc 2.2 extension.
.IP "\s-1RTLD_NOLOAD\s0" 4
.IX Item "RTLD_NOLOAD"
glibc 2.2 extension.
.IP "\s-1RTLD_DEEPBIND\s0" 4
.IX Item "RTLD_DEEPBIND"
glibc 2.3.4 extension.
.SS "dlsym"
.IX Subsection "dlsym"
.Vb 1
\& my $opaque = dlsym($handle, $symbol);
.Ve
.PP
This looks up the given \f(CW$symbol\fR in the library pointed to by \f(CW$handle\fR.  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 \f(CW\*(C`function\*(C'\fR and \f(CW\*(C`attach\*(C'\fR methods instead of a function name.
.PP
If the symbol cannot be found then \f(CW\*(C`undef\*(C'\fR will be returned and the diagnostic for the failure can
be retrieved with \f(CW\*(C`dlerror\*(C'\fR as described below.
.SS "dlclose"
.IX Subsection "dlclose"
.Vb 1
\& my $status = dlclose($handle);
.Ve
.PP
On success, \f(CW\*(C`dlclose\*(C'\fR returns 0; on error, it returns a nonzero value, and the diagnostic for the
failure can be retrieved with \f(CW\*(C`dlerror\*(C'\fR as described below.
.SS "dlerror"
.IX Subsection "dlerror"
.Vb 1
\& my $error_string = dlerror;
.Ve
.PP
Returns the human readable diagnostic for the reason for the failure for the most recent \f(CW\*(C`dl\*(C'\fR
prefixed function call.
.SH "CAVEATS"
.IX Header "CAVEATS"
Some flags for \f(CW\*(C`dlopen\*(C'\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "FFI::Platypus" 4
.IX Item "FFI::Platypus"
.SH "AUTHOR"
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Bakkiaraj Murugesan (bakkiaraj)
.PP
Dylan Cali (calid)
.PP
pipcet
.PP
Zaki Mughal (zmughal)
.PP
Fitz Elliott (felliott)
.PP
Vickenty Fesunov (vyf)
.PP
Gregor Herrmann (gregoa)
.PP
Shlomi Fish (shlomif)
.PP
Damyan Ivanov
.PP
Ilya Pavlov (Ilya33)
.PP
Petr Pisar (ppisar)
.PP
Mohammad S Anwar (\s-1MANWAR\s0)
.PP
Håkon Hægland (hakonhagland, \s-1HAKONH\s0)
.PP
Meredith (merrilymeredith, \s-1MHOWARD\s0)
.PP
Diab Jerius (\s-1DJERIUS\s0)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015,2016,2017,2018,2019,2020 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.