DragonFly On-Line Manual Pages
DLOPEN(3) DragonFly Library Functions Manual 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)
DragonFly 5.5 April 6, 2012 DragonFly 5.5