huschi.net

DLCLOSE(3P)                POSIX Programmer's Manual               DLCLOSE(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
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  refer-
       enced  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() ref-
       erencing the same object may return the same object for handle.  Imple-
       mentations  are  also  free  to  reuse a handle. For these reasons, the
       value of a handle must be treated as an opaque object by  the  applica-
       tion, 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 .

IEEE/The Open Group                  2003                          DLCLOSE(3P)