Name

The dlopen function loads the DLL specified in the path argument, and returns a descriptor if successful. The descriptor thus returned can be used for later references to the DLL within the calls to dlsym and dlclose. The user side code should not attempt to modify or interpret the value of the descriptor returned by dlopen. If the DLL specified by the path argument is not in the address space prior to the call to dlopen, it is loaded into the address space. When the DLL is first loaded into the address space, constructors of the DLL’s global objects are invoked. If the DLL specified by the path argument has already been placed in the process’s address space in a previous call to dlopen, invoking dlopen, on the same DLL does not add it a second time, but the reference count of dlopen operations on that DLL is incremented. Invoking dlclose on the DLL handle decrements the reference count associated with the DLL. When this reference count reaches zero, the DLL is unloaded from the process address space. Hence, the dynamic library (DLL) thus loaded is not deallocated until dlclose is called on it as many times as dlopen has succeeded on it. dlopen returns NULL is path argument is NULL.

The mode parameter determines the type of operation performed by dlopen with respect to the symbol address relocations and the visibility of the symbols to other shared libraries loaded by the process. In the implementation, the mode argument has the same effect regardless of its value. And it is to resolve all the external function references immediately within dlopen. This is because the external function references are bound immediately by dlopen. So, for all practical purposes the mode parameter’s value could be assumed to be RTLD_NOW ORed with RTLD_LOCAL. Once a DLL is loaded into the address space, all the symbols exported by it can only be accessed by specifying the handle associated with the DLL. The behaviour is outlined below.

mode must contain one of the following values, possibly ORed with additional flags which will be described subsequently:

RTLD_LAZY	In the current implementation this flag causes the external function names to be resolved prior to returning from dlopen.
RTLD_NOW	In the current implementation this flag causes the external function names to be resolved prior to returning from dlopen.

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

RTLD_GLOBAL	Symbols exported from this shared library object will not be available for the processing of relocation addresses of any other shared library object.
RTLD_LOCAL	Symbols exported from this shared library object will not be available for the processing of relocation of addresses in any other shared library object.

If path argument contains a slash character, the entire argument is used as the pathname for the file. C: is considered as the root, and C:\ is prefixed to the path argument to locate the shared library object. If on the other hand, path contains just the name of the shared library to be loaded, then the default search order for the loader is sys\bin. The string in path argument should be limited to a maximum of 256 characters.

dlopen returns the handle for the dynamic library loaded into the address space of the current process.

dlsym function returns the address binding of the symbol associated with the ordinal number. The NULL-terminated character string symbol, consists of the ordinal number (address lookup is based on ordinal number). The symbols exported by shared objects/DLLs added to the address space by dlopen can be accessed only through calls to dlsym.

In the implementation, the symbol names per se are not searched. Instead dlsym locates the symbol name corresponding to the ordinal number and returns the address of the memory location where the symbol is loaded. So the ordinal numbers form the crux of the name lookup. Since all handles have to be identified explicitly (that is, as returned by dlopen ), dlsym returns NULL when presented with special handles such as RTLD_NEXT, RTLD_SELF and RTLD_DEFAULT. The implementation treats a NULL handle to dlsym as an error and returns NULL.

The dlsym function returns a null pointer if the symbol (ordinal) cannot be found, and sets an error condition which may be queried with dlerror.

The dlerror function returns a null-terminated character string describing the last error that occurred during a call to dlopen, dlsym, or dlclose. If no such error has occurred, dlerror returns a null pointer. At each call to dlerror, the error indication is reset. Thus in the case of two calls to dlerror, where the second call follows the first immediately, the second call will always return a null pointer.

The dlclose function deletes a reference to the DLL referenced by handle. If the reference count drops to 0, the DLL is removed from the address space, and handle is rendered invalid. Just before removing the DLL from the current process’s address space, the destructors of the DLL’s global objects are invoked. If dlclose is successful, it returns 0. Otherwise it returns -1, and sets an error condition that can be interrogated with dlerror.

The following code snippet illustrates the usage of dl functions. The example DLL name is MathDll.dll. The function that needs to be accessed is abs().

#include <stdio.h>
#include <dlfcn.h>
int libdl_user()
{
    void *handle = NULL;
    typedef float (*ABS)(float);
    ABS abs = NULL;
    /* Load the DLL dynamically */
    handle = dlopen("MathDll.dll", RTLD_NOW | RTLD_LOCAL);
    if(!handle)
    {
        /* dlopen failed to load the DLL */
        const char *p = dlerror();
        printf("%s", p);
        return -1;
    }
    /* DLL load is successful */
    /* Lookup the address of abs function within the DLL */
    abs = (ABS) dlsym(handle, "1");    /* ordinal number associated with abs() is 1 */
    if(!abs)
    {
        const char *q = dlerror();
        printf("%s", p);
        return -1;
    }
    float num = (*abs)(-100);
    printf("The absolute value of -100 is %f\n", num);
    /* Close the DLL */
    if(dlclose(handle))
    {
        /* An error occured while attempting to close the DLL */
        const char *r = dlerror();
        printf("%s\n", r);
        return -1;
    }
}

Feedback