FFI::Platypus::DL(3pm)

1FFI::Platypus::DL(3)  User Contributed Perl Documentation FFI::Platypus::DL(3)
2
3
4

NAME

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

VERSION

9       version 1.10
10

SYNOPSIS

12        use FFI::Platypus;
13        use FFI::Platypus::DL;
14
15        my $handle = dlopen("./libfoo.so", RTLD_PLATYPUS_DEFAULT);
16        my $address = dlsym($handle, "my_function_named_foo");
17        my $ffi = FFI::Platypus->new( api => 1 );
18        $ffi->function($address => [] => 'void')->call;
19        dlclose($handle);
20

DESCRIPTION

22       This module provides an interface to libdl, the dynamic loader on UNIX.
23       The underlying interface has always been used by FFI::Platypus, but it
24       wasn't a public interface until version 0.52.  The name was changed
25       with that version when it became a public interface, so be sure to
26       specify that version if you are going to use it.
27
28       It is somewhat non-portable for these reasons:
29
30       GNU extensions
31           It provides some GNU extensions to platforms such as Linux that
32           support them.
33
34       Windows
35           It provides an emulation layer on Windows.  The emulation layer
36           only supports "RTLD_PLATYPUS_DEFAULT" as a flag.  The emulation
37           layer emulates the convention described below of passing "undef" as
38           the dynamic library name to mean, use the currently running
39           executable.  I've used it without any problems for years, but
40           Windows is not my main development platform.
41

FUNCTIONS

43   dlopen
44        my $handle = dlopen($filename, $flags);
45
46       This opens a dynamic library in the context of the dynamic loader.
47       $filename is the full or relative path to a dynamic library (usually a
48       ".so" on Linux and some other UNIXen, a ".dll" on Windows and a
49       ".dylib" on OS X).  $flags are flags that can be used to alter the
50       behavior of the library and the symbols it contains.  The return value
51       is an opaque pointer or $handle which can be used to look up symbols
52       with "dlsym".  The handle should be closed with "dlclose" when you are
53       done with it.
54
55       By convention if you pass in "undef" for the filename, the currently
56       loaded executable will be used instead of a separate dynamic library.
57       This is the easiest and most portable way to find the address of
58       symbols in the standard C library.  This convention is baked into most
59       UNIXen, but this capability is emulated in Windows which doesn't come
60       with the capability out of the box.
61
62       If there is an error in opening the library then "undef" will be
63       returned and the diagnostic for the failure can be retrieved with
64       "dlerror" as described below.
65
66       Not all flags are supported on all platforms.  You can test if a flag
67       is available using can:
68
69        if(FFI::Platypus::DL->can('RTLD_LAZY'))
70        {
71          ...
72        }
73
74       Typically where flags are not mutually exclusive, they can be or'd
75       together:
76
77        my $handle = dlopen("libfoo.so", RTLD_LAZY | RTLD_GLOBAL);
78
79       Check your operating system documentation for detailed descriptions of
80       these flags.
81
82       RTLD_PLATYPUS_DEFAULT
83           This is the FFI::Platypus default for "dlopen" (NOTE: NOT the libdl
84           default).  This is the only flag supported on Windows.  For
85           historical reasons, this is usually "RTLD_LAZY" on Unix and 0 on
86           Windows.
87
88       RTLD_LAZY
89           Perform lazy binding.
90
91       RTLD_NOW
92           Resolve all symbols before returning from "dlopen".  Error if all
93           symbols cannot resolve.
94
95       RTLD_GLOBAL
96           Symbols are shared.
97
98       RTLD_LOCAL
99           Symbols are NOT shared.
100
101       RTLD_NODELETE
102           glibc 2.2 extension.
103
104       RTLD_NOLOAD
105           glibc 2.2 extension.
106
107       RTLD_DEEPBIND
108           glibc 2.3.4 extension.
109
110   dlsym
111        my $opaque = dlsym($handle, $symbol);
112
113       This looks up the given $symbol in the library pointed to by $handle.
114       If the symbol is found, the address for that symbol is returned as an
115       opaque pointer.  This pointer can be passed into the FFI::Platypus
116       "function" and "attach" methods instead of a function name.
117
118       If the symbol cannot be found then "undef" will be returned and the
119       diagnostic for the failure can be retrieved with "dlerror" as described
120       below.
121
122   dlclose
123        my $status = dlclose($handle);
124
125       On success, "dlclose" returns 0; on error, it returns a nonzero value,
126       and the diagnostic for the failure can be retrieved with "dlerror" as
127       described below.
128
129   dlerror
130        my $error_string = dlerror;
131
132       Returns the human readable diagnostic for the reason for the failure
133       for the most recent "dl" prefixed function call.
134

CAVEATS

136       Some flags for "dlopen" are not portable.  This module may not be
137       supported platforms added to FFI::Platypus in the future.  It does work
138       as far as I know on all of the currently supported platforms.
139

AUTHOR

144       Author: Graham Ollis <plicease@cpan.org>
145
146       Contributors:
147
148       Bakkiaraj Murugesan (bakkiaraj)
149
150       Dylan Cali (calid)
151
152       pipcet
153
154       Zaki Mughal (zmughal)
155
156       Fitz Elliott (felliott)
157
158       Vickenty Fesunov (vyf)
159
160       Gregor Herrmann (gregoa)
161
162       Shlomi Fish (shlomif)
163
164       Damyan Ivanov
165
166       Ilya Pavlov (Ilya33)
167
168       Petr Pisar (ppisar)
169
170       Mohammad S Anwar (MANWAR)
171
172       Håkon Hægland (hakonhagland, HAKONH)
173
174       Meredith (merrilymeredith, MHOWARD)
175
176       Diab Jerius (DJERIUS)
177

COPYRIGHT AND LICENSE

179       This software is copyright (c) 2015,2016,2017,2018,2019 by Graham
180       Ollis.
181
182       This is free software; you can redistribute it and/or modify it under
183       the same terms as the Perl 5 programming language system itself.
184
185
186
187perl v5.30.1                      2020-02-06              FFI::Platypus::DL(3)