Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > D


HP-UX 11i Version 3: February 2007

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index


dlsym() — get the address of a symbol in shared library


cc [flag]... file... -ldl [library]...

#include <dlfcn.h> void *dlsym(void *handle, const char *name);

Multithread Usage

This routine is thread-safe.


dlsym() is one of a family of routines that give the user direct access to the dynamic linking facilities (using the -ldl option on the compiler or ld command line). dlsym() allows a process to obtain the address of a symbol defined within a shared object previously opened by dlopen(). handle is a either the value returned by a call to dlopen() or one of the special flags RTLD_NEXT, RTLD_SELF, and RTLD_DEFAULT. In the former case, the corresponding shared object must not have been closed using dlclose(). name is the symbol's name as a character string.

dlsym() searches for the named symbol in all shared objects loaded automatically as a result of loading the object referenced by handle (see dlopen(3C)).

If handle is RTLD_NEXT, the search begins with the "next" object after the object from which dlsym() was invoked. Objects are searched using a load order symbol resolution algorithm (see dlopen(3C)). The "next" object, and all other objects searched, are either of global scope (because they were loaded at startup or as part of a dlopen() operation with the RTLD_GLOBAL flag) or are objects loaded by the same dlopen() operation that loaded the caller of dlsym().

If handle is RTLD_SELF, the search begins with the object from which dlsym() was invoked. Objects are searched using the load order symbol resolution algorithm.

If handle is RTLD_DEFAULT, then the symbol search is done in the scope of the object that invoked dlsym(). For example, if the caller object was loaded as a result of dlopen() with RTLD_GROUP (see dlopen(3C)), it does not search symbols in objects that were not loaded in same dlopen invocation as the caller object.


If handle does not refer to a valid object opened by dlopen(), or if the named symbol cannot be found within any of the objects associated with handle, dlsym() returns NULL. More detailed diagnostic information is available through dlerror().


If dlsym() fails, a subsequent call to dlerrno() returns one of the following values:


Cannot apply relocation in library.


Internal error encountered in dlsym().


Invalid handle.


End of liblist, invalid RTLD_NEXT argument.


Out of memory.


__thread_setcancelstate failed on entry to or exit from dlsym().


sigenable failed on exit from dlsym().


siginhibit failed on entry to dlsym().


Unknown symbol.


RTLD_NEXT can be used to navigate an intentionally created hierarchy of multiply defined symbols created through interposition. For example, if a program wished to create an implementation of malloc() that embedded some statistics gathering about memory allocations, such an implementation could define its own malloc() which would gather the necessary information, and use dlsym() with RTLD_NEXT to find the "real" malloc(), which would perform the actual memory allocation. Of course, this "real" malloc() could be another user-defined interface that added its own value and then used RTLD_NEXT to find the system malloc().


The following example shows how you can use dlopen() and dlsym() to access either function or data objects. For simplicity, error checking has been omitted.

void *handle; int i, *iptr; int (*fptr)(int); /* open the needed object */ handle = dlopen("/usr/mydir/mylib.sl", RTLD_LAZY); /* find address of function and data objects */ fptr = (int (*)(int))dlsym(handle, "some_function"); iptr = (int *)dlsym(handle, "int_object"); /* invoke function, passing value of integer as a parameter */ i = (*fptr)(*iptr);

The next example shows how one can use dlsym() with RTLD_NEXT to add functionality to an existing interface. Again, error checking has been omitted.

extern void record_malloc(void *, size_t); void * malloc(size_t sz) { void *ptr; void *(*real_malloc)(size_t); real_malloc = (void * (*) (size_t)) dlsym(RTLD_NEXT, "malloc"); ptr = (*real_malloc)(sz); record_malloc(ptr, sz); return ptr; }


dlclose(3C), dlerrno(3C), dlerror(3C), dlopen(3C).

Texts and Tutorials

HP-UX Linker and Libraries Online User Guide

(See the +help option)

HP-UX Linker and Libraries User's Guide

(See manuals(5) for ordering information)

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.