dlsym man page on YellowDog

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

DLOPEN(3)		   Linux Programmer's Manual		     DLOPEN(3)

NAME
       dladdr, dlclose, dlerror, dlopen, dlsym, dlvsym - programming interface
       to dynamic linking loader

SYNOPSIS
       #include <dlfcn.h>

       void *dlopen(const char *filename, int flag);

       char *dlerror(void);

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

       int dlclose(void *handle);

DESCRIPTION
       The four functions dlopen(), dlsym(),  dlclose(),  dlerror()  implement
       the interface to the dynamic linking loader.

   dlerror
       The  function  dlerror() returns a human readable string describing the
       most recent error that occurred from  dlopen(),	dlsym()	 or  dlclose()
       since  the  last	 call to dlerror().  It returns NULL if no errors have
       occurred since initialization or since it was last called.

   dlopen
       The function dlopen() loads the dynamic library file named by the null-
       terminated  string  filename  and  returns  an  opaque "handle" for the
       dynamic library.	 If filename is NULL, then the returned handle is  for
       the  main  program.   If	 filename  contains  a slash ("/"), then it is
       interpreted as a	 (relative  or	absolute)  pathname.   Otherwise,  the
       dynamic	linker	searches  for the library as follows (see ld.so(8) for
       further details):

       o      (ELF only) If the executable file for the calling	 program  con‐
	      tains  a	DT_RPATH  tag,	and does not contain a DT_RUNPATH tag,
	      then the directories listed in the DT_RPATH tag are searched.

       o      If the environment variable LD_LIBRARY_PATH is defined  to  con‐
	      tain  a  colon-separated	list  of  directories,	then these are
	      searched.	 (As a security measure this variable is  ignored  for
	      set-user-ID and set-group-ID programs.)

       o      (ELF  only)  If the executable file for the calling program con‐
	      tains a DT_RUNPATH tag, then the directories listed in that  tag
	      are searched.

       o      The  cache  file /etc/ld.so.cache (maintained by ldconfig(8)) is
	      checked to see whether it contains an entry for filename.

       o      The directories /lib and /usr/lib are searched (in that order).

       If the library has dependencies on other shared libraries,  then	 these
       are  also  automatically	 loaded	 by  the dynamic linker using the same
       rules.  (This process may occur recursively, if those libraries in turn
       have dependencies, and so on.)

       One of the following two values must be included in flag:

       RTLD_LAZY
	      Perform  lazy  binding.	Only  resolve symbols as the code that
	      references them is executed.  If the symbol is never referenced,
	      then  it is never resolved.  (Lazy binding is only performed for
	      function references; references to variables are always  immedi‐
	      ately bound when the library is loaded.)

       RTLD_NOW
	      If   this	 value	is  specified,	or  the	 environment  variable
	      LD_BIND_NOW is set to a non-empty string, all undefined  symbols
	      in  the  library	are  resolved before dlopen() returns. If this
	      cannot be done, an error is returned.

       Zero of more of the following values may also be ORed in flag:

       RTLD_GLOBAL
	      The symbols defined by this library will be made	available  for
	      symbol resolution of subsequently loaded libraries.

       RTLD_LOCAL
	      This  is the converse of RTLD_GLOBAL, and the default if neither
	      flag is specified.  Symbols defined in this library are not made
	      available	  to   resolve	 references   in  subsequently	loaded
	      libraries.

       RTLD_NODELETE (since glibc 2.2)
	      Do not unload the library during dlclose().   Consequently,  the
	      library's	 static variables are not reinitialised if the library
	      is reloaded with dlopen() at a later time.   This	 flag  is  not
	      specified in POSIX.1-2001.

       RTLD_NOLOAD (since glibc 2.2)
	      Don't load the library.  This can be used to test if the library
	      is already resident (dlopen() returns NULL if it is not, or  the
	      library's handle if it is resident).  This flag can also be used
	      to promote the flags on a library that is already	 loaded.   For
	      example,	a  library  that was previously loaded with RTLD_LOCAL
	      can be re-opened with RTLD_NOLOAD | RTLD_GLOBAL.	This  flag  is
	      not specified in POSIX.1-2001.

       RTLD_DEEPBIND (since glibc 2.3.4)
	      Place  the  lookup scope of the symbols in this library ahead of
	      the global scope.	 This means that a self-contained library will
	      use  its	own  symbols  in preference to global symbols with the
	      same name contained in libraries that have already been  loaded.
	      This flag is not specified in POSIX.1-2001.

       If filename is a NULL pointer, then the returned handle is for the main
       program.	 When given to dlsym(), this handle causes a search for a sym‐
       bol  in	the  main  program, followed by all shared libraries loaded at
       program startup, and then all shared libraries loaded by dlopen()  with
       the flag RTLD_GLOBAL.

       External	 references in the library are resolved using the libraries in
       that library's dependency  list	and  any  other	 libraries  previously
       opened  with  the  RTLD_GLOBAL flag.  If the executable was linked with
       the flag "-rdynamic" (or, synonymously, "--export-dynamic"),  then  the
       global  symbols	in  the executable will also be used to resolve refer‐
       ences in a dynamically loaded library.

       If the same library is loaded again with dlopen(), the same file handle
       is returned. The dl library maintains reference counts for library han‐
       dles, so a dynamic library is not deallocated until dlclose() has  been
       called  on  it as many times as dlopen() has succeeded on it. The _init
       routine, if present, is only called once. But a	subsequent  call  with
       RTLD_NOW	 may force symbol resolution for a library earlier loaded with
       RTLD_LAZY.

       If dlopen() fails for any reason, it returns NULL.

   dlsym
       The function dlsym() takes a "handle" of a dynamic library returned  by
       dlopen()	 and  the  null-terminated  symbol name, returning the address
       where that symbol is loaded into memory.	 If the symbol is  not	found,
       in  the	specified  library or any of the libraries that were automati‐
       cally loaded by dlopen() when that library was loaded, dlsym()  returns
       NULL.   (The  search  performed by dlsym() is breadth first through the
       dependency tree of these libraries.)  Since the	value  of  the	symbol
       could  actually	be  NULL  (so that a NULL return from dlsym() need not
       indicate an error), the correct way to test for an  error  is  to  call
       dlerror()  to  clear  any  old error conditions, then call dlsym(), and
       then call dlerror() again, saving its return value into a variable, and
       check whether this saved value is not NULL.

       There  are two special pseudo-handles, RTLD_DEFAULT and RTLD_NEXT.  The
       former will find the first occurrence of the desired symbol  using  the
       default	library search order. The latter will find the next occurrence
       of a function in the search order  after	 the  current  library.	  This
       allows  one  to	provide	 a wrapper around a function in another shared
       library.

   dlclose
       The function dlclose() decrements the reference count  on  the  dynamic
       library	handle	handle.	  If  the reference count drops to zero and no
       other loaded libraries use symbols in it, then the dynamic  library  is
       unloaded.

       The function dlclose() returns 0 on success, and non-zero on error.

   The obsolete symbols _init and _fini
       The  linker  recognizes	special symbols _init and _fini.  If a dynamic
       library exports a routine named _init, then that code is executed after
       the  loading, before dlopen() returns. If the dynamic library exports a
       routine named _fini, then  that	routine	 is  called  just  before  the
       library	is unloaded.  In case you  need to  avoid  linking against the
       system startup files, this can be done by  giving  gcc  the  "-nostart‐
       files" parameter on the command line.

       Using these routines, or the gcc -nostartfiles or -nostdlib options, is
       not recommended. Their use may result in undesired behavior, since  the
       constructor/destructor  routines	 will  not be executed (unless special
       measures are taken).

       Instead, libraries should export routines using the __attribute__((con‐
       structor))  and	__attribute__((destructor))  function attributes.  See
       the gcc info pages for information on these.  Constructor routines  are
       executed	 before dlopen() returns, and destructor routines are executed
       before dlclose() returns.

GNU EXTENSIONS
       Glibc adds two functions not described by POSIX, with prototypes

       #define _GNU_SOURCE
       #include <dlfcn.h>

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

       void *dlvsym(void *handle, char *symbol, char *version);

       The function dladdr() takes a function pointer  and  tries  to  resolve
       name and file where it is located. Information is stored in the Dl_info
       structure:

       typedef struct {
	 const char *dli_fname;/* Filename of defining object */
	 void *dli_fbase;      /* Load address of that object */
	 const char *dli_sname;/* Name of nearest lower symbol */
	 void *dli_saddr;      /* Exact value of nearest symbol */
       } Dl_info;

       dladdr() returns 0 on error, and non-zero on success.

       The function dlvsym() does the same as  dlsym()	but  takes  a  version
       string as an additional argument.

EXAMPLE
       Load the math library, and print the cosine of 2.0:

	      #include <stdio.h>
	      #include <stdlib.h>
	      #include <dlfcn.h>

	      int main(int argc, char **argv) {
		  void *handle;
		  double (*cosine)(double);
		  char *error;

		  handle = dlopen ("libm.so", RTLD_LAZY);
		  if (!handle) {
		      fprintf (stderr, "%s\n", dlerror());
		      exit(1);
		  }

		  dlerror();	/* Clear any existing error */
		  cosine = dlsym(handle, "cos");
		  if ((error = dlerror()) != NULL)  {
		      fprintf (stderr, "%s\n", error);
		      exit(1);
		  }

		  printf ("%f\n", (*cosine)(2.0));
		  dlclose(handle);
		  return 0;
	      }

       If  this program were in a file named "foo.c", you would build the pro‐
       gram with the following command:

	      gcc -rdynamic -o foo foo.c -ldl

       Libraries exporting _init() and _fini() will want  to  be  compiled  as
       follows, using bar.c as the example name:

	      gcc -shared -nostartfiles -o bar bar.c

NOTES
       The  symbols  RTLD_DEFAULT  and RTLD_NEXT are defined by <dlfcn.h> only
       when _GNU_SOURCE was defined before including it.

       Since glibc 2.2.3, atexit(3) can be used to register  an	 exit  handler
       that is automatically called when a library is unloaded.

HISTORY
       The  dlopen  interface  standard comes from SunOS. That system also has
       dladdr(), but not dlvsym().

CONFORMING TO
       POSIX.1-2001 describes dlclose(), dlerror(), dlopen(), and dlsym().

SEE ALSO
       ld(1), ldd(1), dl_iterate_phdr(3), ld.so(8),  ldconfig(8),  ld.so  info
       pages, gcc info pages, ld info pages

Linux				  2003-11-17			     DLOPEN(3)
[top]

List of man pages available for YellowDog

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