Yolinux.com

dlclose manpage

Search topic Section


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



NAME
       dlclose, dlopen, dlmopen - open and close a shared object

SYNOPSIS
       #include <dlfcn.h>

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

       int dlclose(void *handle);

       #define _GNU_SOURCE
       #include <dlfcn.h>

       void *dlmopen (Lmid_t lmid, const char *filename, int flags);

       Link with -ldl.

DESCRIPTION
   dlopen()
       The  function dlopen() loads the dynamic shared object (shared library)
       file named by the null-terminated string filename and returns an opaque
       "handle"	 for  the  loaded  object.  This handle is employed with other
       functions in the dlopen API, such as  dlsym(3),	dladdr(3),  dlinfo(3),
       and dlclose().

       If  filename is NULL, then the returned handle is for the main program.
       If filename contains a slash ("/"), then it is interpreted as a	(rela-
       tive or absolute) pathname.  Otherwise, the dynamic linker searches for
       the object as follows (see ld.so(8) for further details):

       o   (ELF only) If the executable file for the calling program  contains
	   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, at the time that the program was started, the environment vari-
	   able	 LD_LIBRARY_PATH was defined to contain 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 pro-
	   grams.)

       o   (ELF only) If the executable file for the calling program  contains
	   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	object	specified by filename has dependencies on other shared
       objects, then these are also automatically loaded by the dynamic linker
       using  the  same	 rules.	 (This process may occur recursively, if those
       objects in turn have dependencies, and so on.)

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

       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 performed only  for
	      function	references; references to variables are always immedi-
	      ately bound when the shared  object  is  loaded.)	  Since	 glibc
	      2.1.1,  this flag is overridden by the effect of the LD_BIND_NOW
	      environment variable.

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

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

       RTLD_GLOBAL
	      The symbols defined by this shared object will be made available
	      for symbol resolution of subsequently loaded shared objects.

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

       RTLD_NODELETE (since glibc 2.2)
	      Do not unload the shared object during dlclose().	 Consequently,
	      the object's static  variables  are  not	reinitialized  if  the
	      object is reloaded with dlopen() at a later time.

       RTLD_NOLOAD (since glibc 2.2)
	      Don't  load  the shared object.  This can be used to test if the
	      object is already resident (dlopen() returns NULL if it is  not,
	      or  the  object's handle if it is resident).  This flag can also
	      be used to promote the flags on a shared object that is  already
	      loaded.  For example, a shared object that was previously loaded
	      with RTLD_LOCAL can be reopened with RTLD_NOLOAD | RTLD_GLOBAL.

       RTLD_DEEPBIND (since glibc 2.3.4)
	      Place the lookup scope of the  symbols  in  this	shared	object
	      ahead  of	 the  global  scope.  This means that a self-contained
	      object will use its own symbols in preference to global  symbols
	      with  the	 same name contained in objects that have already been
	      loaded.

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

       External references in the shared object are resolved using the	shared
       objects	in  that object's dependency list and any other objects previ-
       ously 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  ref-
       erences in a dynamically loaded shared object.

       If  the	same  shared  object  is  loaded again with dlopen(), the same
       object handle is returned.   The	 dynamic  linker  maintains  reference
       counts for object handles, so a dynamically loaded shared object is not
       deallocated until dlclose() has been called on  it  as  many  times  as
       dlopen()	 has  succeeded on it.	Any initialization returns (see below)
       are called just once.  However, a subsequent dlopen() call  that	 loads
       the  same shared object with RTLD_NOW may force symbol resolution for a
       shared object earlier loaded with RTLD_LAZY.

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

   dlmopen()
       This function performs the same	task  as  dlopen()--the	 filename  and
       flags  arguments, as well as the return value, are the same, except for
       the differences noted below.

       The dlmopen() function differs  from  dlopen()  primarily  in  that  it
       accepts	an additional argument, lmid, that specifies the link-map list
       (also referred to as a namespace) in which the shared object should  be
       loaded.	 (By  comparison,  dlopen() adds the dynamically loaded shared
       object to the same namespace  as	 the  shared  object  from  which  the
       dlopen()	 call  is  made.)   The	 Lmid_t	 type is an opaque handle that
       refers to a namespace.

       The lmid argument is either the ID of an existing namespace (which  can
       be  obtained  using  the	 dlinfo(3) RTLD_DI_LMID request) or one of the
       following special values:

       LM_ID_BASE
	      Load the shared object  in  the  initial	namespace  (i.e.,  the
	      application's namespace).

       LM_ID_NEWLM
	      Create a new namespace and load the shared object in that names-
	      pace.  The object must have been correctly linked	 to  reference
	      all  of the other shared objects that it requires, since the new
	      namespace is initially empty.

       If filename is  NULL,  then  the	 only  permitted  value	 for  lmid  is
       LM_ID_BASE.

   dlclose()
       The  function  dlclose()	 decrements the reference count on the dynami-
       cally loaded shared object referred to by  handle.   If	the  reference
       count  drops  to zero, then the object is unloaded.  All shared objects
       that were automatically loaded when dlopen() was invoked on the	object
       referred to by handle are recursively closed in the same manner.

       A  successful return from dlclose() does not guarantee that the symbols
       associated with handle are removed from the caller's address space.  In
       addition to references resulting from explicit dlopen() calls, a shared
       object may have been implicitly loaded (and reference counted)  because
       of dependencies in other shared objects.	 Only when all references have
       been released can the shared object be removed from the address space.

RETURN VALUE
       On success, dlopen() and dlmopen() return a  non-NULL  handle  for  the
       loaded  library.	  On error (file could not be found, was not readable,
       had the wrong format, or caused errors during loading), these functions
       return NULL.

       On success, dlclose() returns 0; on error, it returns a nonzero value.

       Errors from these functions can be diagnosed using dlerror(3).

VERSIONS
       dlopen()	 and  dlclose() are present in glibc 2.0 and later.  dlmopen()
       first appeared in glibc 2.3.4.

ATTRIBUTES
       For  an	explanation  of	 the  terms  used   in	 this	section,   see
       attributes(7).

       +-------------------------------+---------------+---------+
       |Interface		       | Attribute     | Value	 |
       +-------------------------------+---------------+---------+
       |dlopen(), dlmopen(), dlclose() | Thread safety | MT-Safe |
       +-------------------------------+---------------+---------+
CONFORMING TO
       POSIX.1-2001  describes dlclose() and dlopen().	The dlmopen() function
       is a GNU extension.

       The RTLD_NOLOAD, RTLD_NODELETE, and RTLD_DEEPBIND flags are GNU	exten-
       sions; the first two of these flags are also present on Solaris.

NOTES
   dlmopen() and namespaces
       A  link-map  list  defines  an isolated namespace for the resolution of
       symbols by the dynamic linker.  Within a	 namespace,  dependent	shared
       objects	are implicitly loaded according to the usual rules, and symbol
       references are likewise resolved according to the usual rules, but such
       resolution  is confined to the definitions provided by the objects that
       have been (explicitly and implicitly) loaded into the namespace.

       The dlmopen() function permits object-load  isolation--the  ability  to
       load  a	shared	object in a new namespace without exposing the rest of
       the application to the symbols made available by the new object.	  Note
       that the use of the RTLD_LOCAL flag is not sufficient for this purpose,
       since it prevents a shared object's symbols from being available to any
       other  shared  object.	In some cases, we may want to make the symbols
       provided by a dynamically loaded shared object available to  (a	subset
       of)  other  shared objects without exposing those symbols to the entire
       application.  This can be achieved by using a  separate	namespace  and
       the RTLD_GLOBAL flag.

       The  dlmopen()  function	 also  can be used to provide better isolation
       than the RTLD_LOCAL flag.  In particular, shared	 objects  loaded  with
       RTLD_LOCAL  may	be promoted to RTLD_GLOBAL if they are dependencies of
       another shared object loaded with  RTLD_GLOBAL.	 Thus,	RTLD_LOCAL  is
       insufficient to isolate a loaded shared object except in the (uncommon)
       case where one has explicit control over all  shared  object  dependen-
       cies.

       Possible	 uses of dlmopen() are plugins where the author of the plugin-
       loading framework can't trust the plugin authors and does not wish  any
       undefined  symbols  from	 the plugin framework to be resolved to plugin
       symbols.	 Another use is to load the same object more than once.	 With-
       out  the	 use of dlmopen(), this would require the creation of distinct
       copies of the  shared  object  file.   Using  dlmopen(),	 this  can  be
       achieved	 by  loading the same shared object file into different names-
       paces.

       The glibc implementation supports a maximum of 16 namespaces.

   Initialization and finalization functions
       Shared objects may export functions using the  __attribute__((construc-
       tor)) and __attribute__((destructor)) function attributes.  Constructor
       functions are executed before dlopen() returns,	and  destructor	 func-
       tions  are  executed  before  dlclose()	returns.   A shared object may
       export multiple constructors and destructors,  and  priorities  can  be
       associated  with each function to determine the order in which they are
       executed.  See the gcc info pages  (under  "Function  attributes")  for
       further information.

       An older method of (partially) achieving the same result is via the use
       of two special symbols recognized by the linker: _init and _fini.  If a
       dynamically  loaded shared object exports a routine named _init(), then
       that code is executed after loading a shared  object,  before  dlopen()
       returns.	  If  the  shared object exports a routine named _fini(), then
       that routine is called just before the object  is  unloaded.   In  this
       case,  one  must	 avoid linking against the system startup files, which
       contain default versions of these files; this can be done by using  the
       gcc(1) -nostartfiles command-line option.

       Use of _init and _fini is now deprecated in favor of the aforementioned
       constructors and destructors, which among other advantages, permit mul-
       tiple initialization and finalization functions to be defined.

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

   History
       These functions are part of the dlopen API, derived from SunOS.

EXAMPLE
       The program below loads the (glibc) math library, looks up the  address
       of the cos(3) function, and prints the cosine of 2.0.  The following is
       an example of building and running the program:

	   $ cc dlopen_demo.c -ldl
	   $ ./a.out
	   -0.416147

   Program source
       #include <stdio.h>
       #include <stdlib.h>
       #include <dlfcn.h>
       #include <gnu/lib-names.h>  /* Defines LIBM_SO (which will be a
				      string such as "libm.so.6") */
       int
       main(void)
       {
	   void *handle;
	   double (*cosine)(double);
	   char *error;

	   handle = dlopen(LIBM_SO, RTLD_LAZY);
	   if (!handle) {
	       fprintf(stderr, "%s\n", dlerror());
	       exit(EXIT_FAILURE);
	   }

	   dlerror();	 /* Clear any existing error */

	   cosine = (double (*)(double)) dlsym(handle, "cos");

	   /* According to the ISO C standard, casting between function
	      pointers and 'void *', as done above, produces undefined results.
	      POSIX.1-2003 and POSIX.1-2008 accepted this state of affairs and
	      proposed the following workaround:

		  *(void **) (&cosine) = dlsym(handle, "cos");

	      This (clumsy) cast conforms with the ISO C standard and will
	      avoid any compiler warnings.

	      The 2013 Technical Corrigendum to POSIX.1-2008 (a.k.a.
	      POSIX.1-2013) improved matters by requiring that conforming
	      implementations support casting 'void *' to a function pointer.
	      Nevertheless, some compilers (e.g., gcc with the '-pedantic'
	      option) may complain about the cast used in this program. */

	   error = dlerror();
	   if (error != NULL) {
	       fprintf(stderr, "%s\n", error);
	       exit(EXIT_FAILURE);
	   }

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

BUGS
       As  at  glibc  2.21,  specifying	 the  RTLD_GLOBAL  flag	 when  calling
       dlmopen() generates an error.  Furthermore, specifying RTLD_GLOBAL when
       calling dlopen() results in a program crash (SIGSEGV) if	 the  call  is
       made  from  any	object	loaded	in  a namespace other than the initial
       namespace.

SEE ALSO
       ld(1),  ldd(1),	pldd(1),  dl_iterate_phdr(3),  dladdr(3),  dlerror(3),
       dlinfo(3), dlsym(3), rtld-audit(7), ld.so(8), ldconfig(8)

       gcc info pages, ld info pages

COLOPHON
       This  page  is  part of release 4.04 of the Linux man-pages project.  A
       description of the project, information about reporting bugs,  and  the
       latest	  version     of     this    page,    can    be	   found    at
       http://www.kernel.org/doc/man-pages/.



Linux				  2015-12-28			     DLOPEN(3)