1FFI::Platypus::DL(3) User Contributed Perl Documentation FFI::Platypus::DL(3)
2
6 FFI::Platypus::DL - Slightly non-portable interface to libdl
7
9 version 2.08
10
12 use FFI::Platypus 2.00;
13 use FFI::Platypus::DL;
14 my $handle = dlopen("./libfoo.so", RTLD_PLATYPUS_DEFAULT);
16 my $address = dlsym($handle, "my_function_named_foo");
17 my $ffi = FFI::Platypus->new( api => 2 );
18 $ffi->function($address => [] => 'void')->call;
19 dlclose($handle);
20
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 It is somewhat non-portable for these reasons:
29 GNU extensions
31 It provides some GNU extensions to platforms such as Linux that
32 support them.
33 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
43 dlopen
44 my $handle = dlopen($filename, $flags);
45 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 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 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 Not all flags are supported on all platforms. You can test if a flag
67 is available using can:
68 if(FFI::Platypus::DL->can('RTLD_LAZY'))
70 {
71 ...
72 }
73 Typically where flags are not mutually exclusive, they can be or'd
75 together:
76 my $handle = dlopen("libfoo.so", RTLD_LAZY | RTLD_GLOBAL);
78 Check your operating system documentation for detailed descriptions of
80 these flags.
81 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 RTLD_LAZY
89 Perform lazy binding.
90 RTLD_NOW
92 Resolve all symbols before returning from "dlopen". Error if all
93 symbols cannot resolve.
94 RTLD_GLOBAL
96 Symbols are shared.
97 RTLD_LOCAL
99 Symbols are NOT shared.
100 RTLD_NODELETE
102 glibc 2.2 extension.
103 RTLD_NOLOAD
105 glibc 2.2 extension.
106 RTLD_DEEPBIND
108 glibc 2.3.4 extension.
109 dlsym
111 my $opaque = dlsym($handle, $symbol);
112 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 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 dlclose
123 my $status = dlclose($handle);
124 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 dlerror
130 my $error_string = dlerror;
131 Returns the human readable diagnostic for the reason for the failure
133 for the most recent "dl" prefixed function call.
134
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
141 FFI::Platypus
142
144 Author: Graham Ollis <plicease@cpan.org>
145 Contributors:
147 Bakkiaraj Murugesan (bakkiaraj)
149 Dylan Cali (calid)
151 pipcet
153 Zaki Mughal (zmughal)
155 Fitz Elliott (felliott)
157 Vickenty Fesunov (vyf)
159 Gregor Herrmann (gregoa)
161 Shlomi Fish (shlomif)
163 Damyan Ivanov
165 Ilya Pavlov (Ilya33)
167 Petr Písař (ppisar)
169 Mohammad S Anwar (MANWAR)
171 Håkon Hægland (hakonhagland, HAKONH)
173 Meredith (merrilymeredith, MHOWARD)
175 Diab Jerius (DJERIUS)
177 Eric Brine (IKEGAMI)
179 szTheory
181 José Joaquín Atria (JJATRIA)
183 Pete Houston (openstrike, HOUSTON)
185
187 This software is copyright (c) 2015-2022 by Graham Ollis.
188 This is free software; you can redistribute it and/or modify it under
190 the same terms as the Perl 5 programming language system itself.
191perl v5.38.0 2023-07-20 FFI::Platypus::DL(3)