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



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NAME
       dlclose -- close a symbol table handle

SYNOPSIS
       #include <dlfcn.h>

       int dlclose(void *handle);

DESCRIPTION
       The dlclose() function shall inform the system that the symbol table
       handle specified by handle is no longer needed by the application.

       An application writer may use dlclose() to make a statement of intent
       on the part of the process, but this statement does not create any
       requirement upon the implementation. When the symbol table handle is
       closed, the implementation may unload the executable object files that
       were loaded by dlopen() when the symbol table handle was opened and
       those that were loaded by dlsym() when using the symbol table handle
       identified by handle.

       Once a symbol table handle has been closed, an application should
       assume that any symbols (function identifiers and data object
       identifiers) made visible using handle, are no longer available to the
       process.

       Although a dlclose() operation is not required to remove any functions
       or data objects from the address space, neither is an implementation
       prohibited from doing so. The only restriction on such a removal is
       that no function nor data object shall be removed to which references
       have been relocated, until or unless all such references are removed.
       For instance, an executable object file 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
       relocatable objects--in such environments, an application may assume
       that no relocation, once made, shall be undone or remade unless the
       executable object file containing the relocated object has itself been
       removed.

RETURN VALUE
       If the referenced symbol table handle was successfully closed,
       dlclose() shall return 0. If handle does not refer to an open symbol
       table handle or if the symbol table handle could not be closed,
       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():


           #include <dlfcn.h>
           int eret;
           void *mylib;
           ...
           /* Open a dynamic library and then close it ... */
           mylib = dlopen("mylib.so", RTLD_LOCAL | RTLD_LAZY);
           ...
           eret = dlclose(mylib);
           ...

APPLICATION USAGE
       A conforming application should employ a symbol table handle returned
       from a dlopen() invocation only within a given scope bracketed by a
       dlopen() operation and the corresponding dlclose() operation.
       Implementations are free to use reference counting or other techniques
       such that multiple calls to dlopen() referencing the same executable
       object file may return a pointer to the same data object as the symbol
       table handle.

       Implementations are also free to re-use a handle. For these reasons,
       the value of a handle must be treated as an opaque data type 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 POSIX.1-2017, <dlfcn.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                           DLCLOSE(3)
