dlsym man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

dlsym(3C)		 Standard C Library Functions		     dlsym(3C)

NAME
       dlsym - get the address of a symbol in a shared object or executable

SYNOPSIS
       #include <dlfcn.h>

       void *dlsym(void *restrict handle, const char *restrict name);

DESCRIPTION
       The dlsym() function allows a process to obtain the address of a symbol
       that is defined within a shared object or executable. The handle	 argu‐
       ment  is	 either the value returned from a call to dlopen() or one of a
       family of special handles. The name argument is the symbol's name as  a
       character string.

       If  handle is returned from dlopen(), the associated shared object must
       not have been closed using dlclose(). A handle  can  be	obtained  from
       dlopen()	 using	the RTLD_FIRST mode. With this mode, the dlsym() func‐
       tion searches for the named symbol in the initial object referenced  by
       handle.	Without this mode, the dlsym() function searches for the named
       symbol in the group of shared objects loaded automatically as a	result
       of loading the object referenced by handle. See dlopen(3C) and NOTES.

       The following special handles are supported.

       RTLD_DEFAULT    Instructs dlsym() to search for the named symbol start‐
		       ing with the first object loaded, typically the dynamic
		       executable.  The	 search	 continues through the list of
		       initial dependencies that are loaded with the  process,
		       followed	 by any objects obtained with dlopen(3C). This
		       search follows the default model that is used to	 relo‐
		       cate all objects within the process.

		       This  model also provides for transitioning into a lazy
		       loading environment. If a symbol can not	 be  found  in
		       the  presently  loaded objects, any pending lazy loaded
		       objects are processed in an attempt to locate the  sym‐
		       bol. This loading compensates for objects that have not
		       fully defined their dependencies. However, this compen‐
		       sation can undermine the advantages of lazy loading.

       RTLD_PROBE      Instructs dlsym() to search for the named symbol in the
		       same manner as occurs with a  handle  of	 RTLD_DEFAULT.
		       However,	 this  model  only searches for symbols in the
		       presently loaded objects, together with any lazy	 load‐
		       able  objects  specifically identified by the caller to
		       provide the named symbol. This handle does not  trigger
		       an  exhaustive  load of any lazy loadable symbols in an
		       attempt to find the named symbol. This handle can  pro‐
		       vide  a	more  optimal  search  than  would occur using
		       RTLD_DEFAULT.

       RTLD_NEXT       Instructs dlsym() to search for the named symbol in the
		       objects	that  were  loaded  following  the object from
		       which the dlsym() call is being made.

       RTLD_SELF       Instructs dlsym() to search for the named symbol in the
		       objects	that were loaded starting with the object from
		       which the dlsym() call is being made.

       When used with a special handle,	 dlsym()  is  selective	 in  searching
       objects	that  have  been  loaded  using	 dlopen().  These  objects are
       searched for symbols if one of the following conditions are true.

	   o	  The object is part of the  same  local  dlopen()  dependency
		  hierarchy  as the calling object. See the  for a description
		  of dlopen() dependency hierarchies.

	   o	  The object has global search access. See  dlopen(3C)	for  a
		  discussion of the RTLD_GLOBAL mode.

RETURN VALUES
       The  dlsym()  function returns NULL if handle does not refer to a valid
       object opened by dlopen() or is not one of  the	special	 handles.  The
       function	 also  returns NULL if the named symbol cannot be found within
       any of the objects associated with handle. Additional diagnostic infor‐
       mation is available through dlerror(3C).

EXAMPLES
       Example	1  Use	dlopen()  and  dlsym()	to  access  a function or data
       objects.

       The following code  fragment  demonstrates  how	to  use	 dlopen()  and
       dlsym()	to  access  either  function  or data objects. For simplicity,
       error checking has been omitted.

	 void	   *handle;
	 int	   *iptr, (*fptr)(int);

	 /* open the needed object */
	 handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY);

	 /* find the address of function and data objects */
	 fptr = (int (*)(int))dlsym(handle, "my_function");
	 iptr = (int *)dlsym(handle, "my_object");

	 /* invoke function, passing value of integer as a parameter */
	 (*fptr)(*iptr);

       Example 2 Use dlsym() to verify that a particular function is defined.

       The following code fragment shows how to use dlsym() to verify  that  a
       function is defined. If the function exists, the function is called.

	 int (*fptr)();

	 if ((fptr = (int (*)())dlsym(RTLD_DEFAULT,
	     "my_function")) != NULL) {
		 (*fptr)();
	 }

USAGE
       The dlsym() function is one of a family of functions that give the user
       direct access to the dynamic linking facilities. These  facilities  are
       available to dynamically-linked processes only. See the .

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Standard			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       ld(1),  ld.so.1(1),  dladdr(3C),	 dlclose(3C), dldump(3C), dlerror(3C),
       dlinfo(3C), dlopen(3C), attributes(5), standards(5)

NOTES
       If an object is acting as a filter, care should be  taken  when	inter‐
       preting	the  address  of  any  symbol  obtained using a handle to this
       object. For example, using dlsym() to obtain the symbol _end  for  this
       object,	results in returning the address of the symbol _end within the
       filtee, not the filter. For more information on filters see the .

SunOS 5.10			  1 Jan 2011			     dlsym(3C)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net