ffi_dlopen#

Open a shared library and return a handle suitable for passing to call.

Synopsis#

my $lib = Peta::FFI::dlopen("libm.so.6");
my $lib = Peta::FFI::dlopen("/usr/lib/libuuid.so.1");   # absolute path

What you get back#

An opaque integer handle. Treat it as a token: pass it to call and later to dlclose, but do not do arithmetic on it. Store it in a lexical and keep it alive as long as you want to call into the library.

The argument is either a bare soname (e.g. "libm.so.6") that the dynamic linker resolves through the usual LD_LIBRARY_PATH / ld.so.cache machinery, or an absolute path to an .so file. Both RTLD_NOW and RTLD_GLOBAL are set — symbols are resolved eagerly and become visible to subsequently loaded libraries.

Edge cases#

  • Library not found — croaks with the message reported by dlerror, e.g. Peta::FFI::dlopen: libnope.so: cannot open shared object file: No such file or directory.

  • Name contains a null byte — croaks with Peta::FFI::dlopen: invalid library name (contains null byte).

  • No argument — croaks with Peta::FFI::dlopen: requires library name.

  • Calling dlopen repeatedly with the same name — returns the same (reference-counted) handle each time. Pair every successful dlopen with a matching dlclose if you want the library to eventually unload.