dladdr man page on OpenBSD

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

DLFCN(3)		  OpenBSD Programmer's Manual		      DLFCN(3)

NAME
     dlopen, dlclose, dlsym, dladdr, dlctl, dlerror - dynamic link interface

SYNOPSIS
     #include <dlfcn.h>

     void *
     dlopen(const char *path, int mode);

     int
     dlclose(void *handle);

     void *
     dlsym(void *handle, const char *symbol);

     int
     dladdr(const void *addr, Dl_info *info);

     int
     dlctl(void *handle, int cmd, void *data);

     const char *
     dlerror(void);

DESCRIPTION
     These functions provide an interface to the run-time linker ld.so(1).
     They allow new shared objects to be loaded into a process's address space
     under program control.

     The dlopen() function takes the name of a shared object as its first
     argument.	The shared object is mapped into the address space, relocated,
     and its external references are resolved in the same way as is done with
     the implicitly loaded shared libraries at program startup.

     The path parameter can be specified as either an absolute pathname to a
     shared library or just the name of the shared library itself.  When an
     absolute pathname is specified, only the path provided will be searched
     for the shared library.  When just a shared library is specified, the
     same paths will be searched that are used for ``intrinsic'' shared
     library searches.

     Shared libraries take the following form:

	   lib<name>.so[.xx[.yy]]

     When a shared library is specified without a version or with a partial
     version, the same library search rules apply that are used for
     ``intrinsic'' shared library searches.  A null pointer supplied for path
     will return a special handle that behaves the same as the RTLD_DEFAULT
     special handle.

     The mode parameter specifies symbol resolution time and symbol
     visibility.  One of the following values may be used to specify symbol
     resolution time:

	   RTLD_NOW	Symbols are resolved immediately.

	   RTLD_LAZY	Symbols are resolved when they are first referred to.
			This is the default value if resolution time is
			unspecified.

     One of the following values may be used to specify symbol visibility:

	   RTLD_GLOBAL	The object's symbols and the symbols of its
			dependencies will be visible to other objects.
	   RTLD_LOCAL	The object's symbols and the symbols of its
			dependencies will not be visible to other objects.
			This is the default value if visibility is
			unspecified.

     To specify both resolution time and visibility, bitwise inclusive OR one
     of each of the above values together.  If an object was opened with
     RTLD_LOCAL and later opened with RTLD_GLOBAL, then it is promoted to
     RTLD_GLOBAL.

     dlopen() returns a handle to be used in calls to dlclose(), dlsym(), and
     dlctl().  If the named shared object has already been loaded by a
     previous call to dlopen() and not yet unloaded by dlclose(), a handle
     referring to the resident copy is returned.

     dlclose() unlinks and removes the object referred to by handle from the
     process address space.  If multiple calls to dlopen() have been done on
     this object or the object is a dependency of another object then the
     object is removed when its reference count drops to zero.	dlclose()
     returns 0 on success and non-zero on failure.

     dlsym() searches for a definition of symbol in the object designated by
     handle and all shared objects that it depends on.	The symbol's address
     is returned.  If the symbol cannot be resolved, NULL is returned.

     dlsym() may also be called with special handles.  dlsym() respects symbol
     visibility as specified by the dlopen() mode parameter.  However, the
     symbols of an object's dependencies are always visible to it.  All shared
     objects loaded at program startup are globally visible.  Only the symbols
     in the main executable that are referenced by a shared object at link
     time will be visible unless it has been linked with the --export-dynamic
     option where all of its symbols will be visible.  The following special
     handles may be used with dlsym():

	   NULL		   Interpreted as a reference to the executable or
			   shared object from which the call is being made.
			   Thus an object can reference its own symbols and
			   the symbols of its dependencies without calling
			   dlopen().

	   RTLD_DEFAULT	   All the visible shared objects and the executable
			   will be searched in the order they were loaded.

	   RTLD_NEXT	   The search for symbol is limited to the visible
			   shared objects which were loaded after the one
			   issuing the call to dlsym().	 Thus, if dlsym() is
			   called from the main program, all the visible
			   shared libraries are searched.  If it is called
			   from a shared library, all subsequently visible
			   shared libraries are searched.

	   RTLD_SELF	   The search for symbol is limited to the shared
			   object issuing the call to dlsym() and those shared
			   objects which were loaded after it that are
			   visible.

     dladdr() queries the dynamic linker for information about the shared
     object containing the address addr.  The information is returned in the
     structure specified by info.  The structure contains at least the
     following members:

     const char *dli_fname     The pathname of the shared object containing
			       the address addr.

     void *dli_fbase	       The base address at which the shared object is
			       mapped into the address space of the calling
			       process.

     const char *dli_sname     The name of the nearest run-time symbol with a
			       address less than or equal to addr.

			       If no symbol with a suitable address is found,
			       both this field and dli_saddr are set to NULL.

     void *dli_saddr	       The address of the symbol returned in
			       dli_sname.

     If a mapped shared object containing addr cannot be found, dladdr()
     returns 0.	 In that case, a message detailing the failure can be
     retrieved by calling dlerror().  On success, a non-zero value is
     returned.	Note: both strings pointed at by dli_fname and dli_sname
     reside in memory private to the run-time linker module and should not be
     modified by the caller.

     In dynamically linked programs, the address of a global function will
     point to its program linkage table entry, rather than to the entry point
     of the function itself.  This causes most global functions to appear to
     be defined within the main executable, rather than in the shared
     libraries where the actual code resides.

     dlctl() provides an interface similar to ioctl(2) to control several
     aspects of the run-time linker's operation.  This interface is currently
     under development.

     dlerror() returns a character string representing the most recent error
     that has occurred while processing one of the other functions described
     here.  If no dynamic linking errors have occurred since the last
     invocation of dlerror(), dlerror() returns NULL.  Thus, invoking
     dlerror() a second time, immediately following a prior invocation, will
     result in NULL being returned.

SEE ALSO
     ld(1), ld.so(1), link(5)

HISTORY
     Some of the dl* functions first appeared in SunOS 4.

OpenBSD 4.9		       February 20, 2010		   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

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