The Libdl module in Julia provides specialized and lower-level facilities for dynamic linking with shared libraries. While Julia inherently supports linking to runtime shared libraries through the ccall intrinsic, Libdl extends this capability by offering additional, more granular control. It enables users to search for shared libraries both in memory and the filesystem, manually load them with specific runtime linker options, and look up library symbols as low-level pointers.

dlopen(libfile::AbstractString [, flags::Integer]; throw_error:Bool = true)

Load a shared library, returning an opaque handle.

The extension given by the constant dlext (.so, .dll, or .dylib) can be omitted from the libfile string, as it is automatically appended if needed. If libfile is not an absolute path name, then the paths in the array DL_LOAD_PATH are searched for libfile, followed by the system load path.

The optional flags argument is a bitwise-or of zero or more of RTLD_LOCAL, RTLD_GLOBAL, RTLD_LAZY, RTLD_NOW, RTLD_NODELETE, RTLD_NOLOAD, RTLD_DEEPBIND, and RTLD_FIRST. These are converted to the corresponding flags of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default flags are platform specific. On MacOS the default dlopen flags are RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL while on other platforms the defaults are RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL. An important usage of these flags is to specify non default behavior for when the dynamic library loader binds library references to exported symbols and if the bound references are put into process local or global scope. For instance RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL allows the library's symbols to be available for usage in other shared libraries, addressing situations where there are dependencies between shared libraries.

If the library cannot be found, this method throws an error, unless the keyword argument throw_error is set to false, in which case this method returns nothing.

dlopen_e(libfile::AbstractString [, flags::Integer])

Similar to dlopen, except returns C_NULL instead of raising errors. This method is now deprecated in favor of dlopen(libfile::AbstractString [, flags::Integer]; throw_error=false).

RTLD_DEEPBIND
RTLD_FIRST
RTLD_GLOBAL
RTLD_LAZY
RTLD_LOCAL
RTLD_NODELETE
RTLD_NOLOAD
RTLD_NOW

Enum constant for dlopen. See your platform man page for details, if applicable.

dlsym(handle, sym; throw_error::Bool = true)

Look up a symbol from a shared library handle, return callable function pointer on success.

If the symbol cannot be found, this method throws an error, unless the keyword argument throw_error is set to false, in which case this method returns nothing.

dlsym_e(handle, sym)

Look up a symbol from a shared library handle, silently return C_NULL on lookup failure. This method is now deprecated in favor of dlsym(handle, sym; throw_error=false).

dlclose(::Nothing)

For the very common pattern usage pattern of

try
    hdl = dlopen(library_name)
    ... do something
finally
    dlclose(hdl)
end

We define a dlclose() method that accepts a parameter of type Nothing, so that user code does not have to change its behavior for the case that library_name was not found.

dlclose(handle)

Close shared library referenced by handle.

dlext

File extension for dynamic libraries (e.g. dll, dylib, so) on the current platform.

dllist()

Return the paths of dynamic libraries currently loaded in a Vector{String}.

dlpath(libname::Union{AbstractString, Symbol})

Get the full path of the library libname.

Examples

julia> dlpath("libjulia")

dlpath(handle::Ptr{Cvoid})

Given a library handle from dlopen, return the full path.

find_library(names [, locations])

Searches for the first library in names in the paths in the locations list, DL_LOAD_PATH, or system library paths (in that order) which can successfully be dlopen'd. On success, the return value will be one of the names (potentially prefixed by one of the paths in locations). This string can be assigned to a global const and used as the library name in future ccall's. On failure, it returns the empty string.

DL_LOAD_PATH

When calling dlopen, the paths in this list will be searched first, in order, before searching the system locations for a valid library handle.

LazyLibrary(name; flags = <default dlopen flags>,
            dependencies = LazyLibrary[], on_load_callback = nothing)

Represents a lazily-loaded shared library that delays loading itself and its dependencies until first use in a ccall(), @ccall, dlopen(), dlsym(), dlpath(), or cglobal(). This is a thread-safe mechanism for on-demand library initialization.

Arguments

• name: Library name (or lazy path computation) as a String, LazyLibraryPath, or BundledLazyLibraryPath.
• flags: Optional dlopen flags (default: RTLD_LAZY | RTLD_DEEPBIND). See dlopen.
• dependencies: Vector of LazyLibrary object references to load before this one.
• on_load_callback: Optional function to run arbitrary code on first load (use sparingly, as it is not expected that ccall() should result in large amounts of Julia code being run. You may call ccall() from within the on_load_callback but only for the current library and its dependencies, and user should not call wait() on any tasks within the on load callback as they may deadlock).

The dlopen operation is thread-safe: only one thread loads the library, acquired after the release store of the reference to each dependency from loading of each dependency. Other tasks block until loading completes. The handle is then cached and reused for all subsequent calls (there is no dlclose for lazy library and dlclose should not be called on the returned handled).

Examples

# Basic usage
const mylib = LazyLibrary("libmylib")
@ccall mylib.myfunc(42::Cint)::Cint

# With dependencies
const libfoo = LazyLibrary("libfoo")
const libbar = LazyLibrary("libbar"; dependencies=[libfoo])

For more examples including platform-specific libraries, lazy path construction, and migration from __init__() patterns, see the manual section on Using LazyLibrary for Lazy Loading.

See also LazyLibraryPath, BundledLazyLibraryPath, dlopen, dlsym, add_dependency!.

LazyLibraryPath(path_pieces...)

Helper type for lazily constructed library paths for use with LazyLibrary. Path pieces are stored unevaluated and joined with joinpath() when the library is first accessed. Arguments must be able to have string() called on them.

Example

const mylib = LazyLibrary(LazyLibraryPath(artifact_dir, "lib", "libmylib.so.1.2.3"))

See also LazyLibrary, BundledLazyLibraryPath.

BundledLazyLibraryPath(subpath)

Helper type for lazily constructed library paths within the Julia distribution. Constructs paths relative to Julia's private shared library directory.

Primarily used by Julia's standard library. For example:

const libgmp = LazyLibrary(BundledLazyLibraryPath("libgmp.so.10"))

See also LazyLibrary, LazyLibraryPath.

add_dependency!(library::LazyLibrary, dependency::LazyLibrary)

Dynamically add a dependency that must be loaded before library. Only needed when dependencies cannot be determined at construction time.

Prefer specifying dependencies in the LazyLibrary constructor when possible.

See also LazyLibrary.