dlsym(3C)																 dlsym(3C)

NAME

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

SYNOPSIS

       [flag]...  file...  [library]...

   Multithread Usage
       This routine is thread-safe.

DESCRIPTION

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

       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  the  search begins with the "next" object after the object from which 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 operation with the flag) or are objects loaded by the same operation that loaded the caller of

       If  handle  is  the search begins with the object from which was invoked. Objects are searched using the load order symbol resolution algo-
       rithm.

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

RETURN VALUE

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

ERRORS

       If fails, a subsequent call to returns one of the following values:
	      Cannot apply relocation in library.

	      Internal error encountered in

	      Invalid
		     handle.

	      End of liblist, invalid argument.

	      Out of memory.

	      failed on entry to or exit from

	      failed on exit from

	      failed on entry to

	      Unknown symbol.

APPLICATION USAGE

       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 that embedded some statistics gathering about memory allocations, such an implementation
       could define its own which would gather the necessary information, and use with to find the "real" which would perform  the  actual  memory
       allocation.  Of course, this "real" could be another user-defined interface that added its own value and then used to find the system

EXAMPLES

       The  following  example shows how you can use and to access either function or data objects.  For simplicity, error checking has been omit-
       ted.

		 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 with 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;
		 }

SEE ALSO

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

   Texts and Tutorials
       (See the 	 option)
       (See		 manuals(5) for ordering information)

																	 dlsym(3C)