dlopen()

Gain access to an executable object file

Synopsis:

#include <dlfcn.h>

void * dlopen( const char * pathname, 
              int mode );

The dlopen() function gives you direct access to the dynamic linking facilities by making the executable object file specified in pathname available to the calling process. It returns a handle used for subsequent calls to dlsym() and dlclose().

The dlopen/() function is available only to a dynamically-linked process. A statically-linked process (one where libc is linked statically) can't call dlopen() because a statically-linked executable:

doesn't export any of its symbols
can't export the required structure for libraries to link against
can't fill structures at startup needed to load subsequent shared objects

Any dependencies recorded within pathname are loaded as part of the dlopen() call. These dependencies are searched in load-order to locate any additional dependencies. This process continues until all of the dependencies for pathname have been satisfied. This dependency tree is called a group.

If pathname is NULL, dlopen() provides a handle to the running process's global symbol object. This provides access to the symbols from the original program image file, the dependencies it loaded at startup, plus any objects opened with dlopen() calls using the RTLD_GLOBAL flag. This set of symbols can change dynamically if the application subsequently calls dlopen() using RTLD_GLOBAL.

Objects whose names resolve to the same absolute or relative path name can be opened any number of times using dlopen(); the object is loaded into the process's address space only once.

When loading shared objects, the application should open a specific version instead of relying on the version pointed to by a symbolic link.

The mode

The mode argument indicates how dlopen() operates on pathname when handling relocations, and controls the visibility of symbols found in pathname and its dependencies.

The mode argument is a bitwise-OR of the constants in the following section. Note that the relocation and visibility constants are mutually exclusive.

Relocation

When an object is loaded with dlopen(), it may contain references to symbols whose addresses aren't known until the object has been loaded; these references must be relocated before accessing the symbols. The mode controls when relocations take place, and can be one of:

RTLD_LAZY: References to data symbols are relocated when the object is loaded. References to functions aren't relocated until that function is invoked. This improves performance by preventing unnecessary relocations.
RTLD_NOW: All references are relocated when the object is loaded. This may waste cycles if relocations are performed for functions that never get called, but this behavior could be useful for applications that need to know that all symbols referenced during execution are available as soon as the object is loaded.

RTLD_LAZY isn't currently supported.

Visibility

The following mode bits determine the scope of visibility for symbols loaded with dlopen():

RTLD_GLOBAL: The object's global symbols are made available to any other object. Symbol lookup using dlopen( 0, mode ) and an associated dlsym() are also able to find the object's symbols.
RTLD_LOCAL: The object's global symbols are only available to objects in the same group.

The program's image and any objects loaded at program startup have a mode of RTLD_GLOBAL; the default mode for objects acquired with dlopen() is RTLD_LOCAL. A local object may be part of the dependencies for more than one group; any object with a RTLD_LOCAL mode referenced as a dependency of an object with a RTLD_GLOBAL mode is promoted to RTLD_GLOBAL.

Objects loaded with dlopen() that require relocations against global symbols can reference the symbols in any RTLD_GLOBAL object.

The mode can be ORed with the following values to affect symbol scope:

RTLD_GROUP: Only symbols from the associated group are available. All dependencies between group members must be satisfied by the objects in the group.
RTLD_WORLD: Only symbols from RTLD_GLOBAL objects are available.

The default mode is RTLD_WORLD | RTLD_GROUP.

Symbol Resolution

When resolving the symbols in the shared object, the runtime linker searches for them in the dynamic symbol table using the following order:

By default:

main executable
the shared object being loaded
all other loaded shared objects that were loaded with the RTLD_GLOBAL flag.

When -Bsymbolic is specified:

the shared object being loaded
main executable
all other loaded shared objects that were loaded with the RTLD_GLOBAL flag.

For executables, the dynamic symbol table typically contains only those symbols that are known to be needed by any shared libraries. This is determined by the linker when the executable is linked against a shared library.

Since you don't link your executable against a shared object that you load with dlopen(), the linker can't determine which executable symbols need to be made available to the shared object.

If your shared object needs to resolve symbols in the executable, then you may force the linker to make all of the symbols in the executable available for dynamic linking by specifying the -E linker option. For example:

qcc -Vgcc_ntox86 -Wc,-E -o main main.o

Shared objects always place all their symbols in dynamic symbol tables, so this option isn't needed when linking a shared object.

Returns:

A handle to the object, or NULL if an error occurs.

Errors:

If an error occurs, more detailed diagnostic information is available from dlerror().

Environment variables:

LD_LIBRARY_PATH: The LD_LIBRARY_PATH environment variable is searched for any dependencies required by pathname.

Classification:

Standard Unix

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	Yes

Caveats:

Some symbols defined in executables or shared object might not be available to the runtime linker. The symbol table created by ld for use by the runtime linker might contain a subset of the symbols defined in the object.