NAME

       dlclose - close a dlopen object

SYNOPSIS

       #include <dlfcn.h>

       int dlclose(void *handle);

DESCRIPTION

       The  dlclose()  function  shall  inform  the system that the object referenced by a handle
       returned from a previous dlopen() invocation is no longer needed by the application.

       The use of dlclose() reflects a statement of intent on the part of the process,  but  does
       not create any requirement upon the implementation, such as removal of the code or symbols
       referenced by handle. Once an object has been closed using dlclose() an application should
       assume  that  its  symbols  are  no  longer  available  to  dlsym().  All  objects  loaded
       automatically as a result of invoking dlopen() on the  referenced  object  shall  also  be
       closed if this is the last reference to it.

       Although a dlclose() operation is not required to remove structures from an address space,
       neither is an implementation prohibited from doing so. The  only  restriction  on  such  a
       removal  is that no object shall be removed to which references have been relocated, until
       or unless all such references are removed. For instance, an object that  had  been  loaded
       with  a  dlopen()  operation  specifying  the  RTLD_GLOBAL flag might provide a target for
       dynamic relocations performed in the processing of other objects-in such environments,  an
       application may assume that no relocation, once made, shall be undone or remade unless the
       object requiring the relocation has itself been removed.

RETURN VALUE

       If the referenced object was successfully closed, dlclose() shall return 0. If the  object
       could not be closed, or if handle does not refer to an open object, dlclose() shall return
       a non-zero  value.  More  detailed  diagnostic  information  shall  be  available  through
       dlerror().

ERRORS

       No errors are defined.

       The following sections are informative.

EXAMPLES

       The following example illustrates use of dlopen() and dlclose():

              ...
              /* Open a dynamic library and then close it ... */

              #include <dlfcn.h>
              void *mylib;
              int eret;

              mylib = dlopen("mylib.so", RTLD_LOCAL | RTLD_LAZY);
              ...
              eret = dlclose(mylib);
              ...

APPLICATION USAGE

       A  conforming  application should employ a handle returned from a dlopen() invocation only
       within a given scope bracketed by the dlopen() and dlclose()  operations.  Implementations
       are  free  to  use  reference  counting  or  other  techniques such that multiple calls to
       dlopen()  referencing  the  same  object  may  return  the   same   object   for   handle.
       Implementations  are also free to reuse a handle. For these reasons, the value of a handle
       must be treated as an opaque object by the application, used only in calls to dlsym()  and
       dlclose().

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       dlerror()  ,  dlopen()  ,  dlsym()  , the Base Definitions volume of IEEE Std 1003.1-2001,
       <dlfcn.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .