```{index} single: ffi_dlopen; Peta::FFI function ``` ```{index} single: Peta::FFI::ffi_dlopen; Perl function ``` # ffi_dlopen Open a shared library and return a handle suitable for passing to `call`. ## Synopsis ```perl 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.