DLOPEN(3)

NAME
dlopen, fdlopen - returns handle to dynamically loaded shared object

LIBRARY
This function is not in a library. It is included in every dynamically linked program automatically.

SYNOPSIS
#include <dlfcn.h>
void *
dlopen(const char *name, int mode);
void *
fdlopen(int fd, int mode);

DESCRIPTION
The dlopen() function provides access to the shared object in name, returning a descriptor that can be used for later references to the object in calls to other dl functions. If name was not in the address space prior to the call to dlopen(), it is placed in the address space. When an object is first loaded into the address space in this way, its function _init(), if any, is called by the dynamic linker. If name has already been placed in the address space in a previous call to dlopen(), it is not added a second time, although a reference count of dlopen() operations on name is maintained. A null pointer supplied for name is interpreted as a reference to the main executable of the process. The mode argument controls the way in which external function references from the loaded object are bound to their referents. It must contain one of the following values, possibly ORed with additional flags which will be described subsequently:

RTLD_LAZY
    Each external function reference is resolved when the function is first called.

RTLD_NOW
    All external function references are bound immediately by dlopen().

RTLD_LAZY is normally preferred, for reasons of efficiency. However, RTLD_NOW is useful to ensure that any undefined symbols are discovered during the call to dlopen().

One of the following flags may be ORed into the mode argument:

RTLD_GLOBAL
    Symbols from this shared object and its directed acyclic graph (DAG) of needed objects will be available for resolving undefined references from all other shared objects.

RTLD_LOCAL
    Symbols in this shared object and its DAG of needed objects will be available for resolving undefined references only from other objects in the same DAG. This is the default, but it may be specified explicitly with this flag.

RTLD_TRACE
    When set, causes dynamic linker to exit after loading all objects needed by this shared object and printing a summary which includes the absolute pathnames of all objects, to standard output. With this flag dlopen() will return to the caller only in the case of error.

RTLD_NODELETE
    Prevents unload of the loaded object on dlclose(). The same behaviour may be requested by -z nodelete option of the static linker ld(1).

RTLD_NOLOAD
    Only return valid handle for the object if it is already loaded in the process address space, otherwise NULL is returned. Other mode flags may be specified, which will be applied for promotion for the found object.

If dlopen() fails, it returns a null pointer, and sets an error condition which may be interrogated with dlerror().

The fdlopen() function is similar to dlopen(), but it takes the file descriptor argument fd, which is used for the file operations needed to load an object into the address space. The file descriptor fd is not closed by the function regardless a result of execution, but a duplicate of the file descriptor is. This may be important if a lockf(3) lock is held on the passed descriptor. The fd argument -1 is interpreted as a reference to the main executable of the process, similar to NULL value for the name argument to dlopen(). The fdlopen() function can be used by the code that needs to perform additional checks on the loaded objects, to prevent races with symlinking or renames.

RETURN VALUES
The functions return a null pointer in the event of an error. Whenever an error has been detected, a message detailing it can be retrieved via a call to dlerror().

EXAMPLES
The following program will open any shared gcc library found and display the directory in which it was found using the dfinfo function.

    #include <dlfcn.h>
    #include <stdlib.h>
    #include <stdio.h>
    int
    main (int argc, char *argv[])
    {
        void *handle;
        int   result;
        char origin[256];
        /* open shared gcc library  */
        handle = dlopen("libgcc_s.so", RTLD_LAZY);
        if (!handle) {
           fprintf (stderr, "%s\n", dlerror ());
           exit (EXIT_FAILURE);
        }
        /* get information about the library origin */
        result = dlinfo (handle, RTLD_DI_ORIGIN, (void *)&origin);
        if (result < 0) {
           fprintf (stderr, "%s\n", dlerror ());
           dlclose (handle);
           exit (EXIT_FAILURE);
        }
        /* Display the origin */
        printf ("libgcc_s origin is %s\n", &origin[0]);
        dlclose (handle);
        exit(EXIT_SUCCESS);
    }

SEE ALSO
rtld(1), dlclose(3), dlerror(3), dlfcn(3), dlinfo(3)