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



PPRROOLLOOGG
       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.

NNAAMMEE
       dlclose -- close a symbol table handle

SSYYNNOOPPSSIISS
       #include <dlfcn.h>

       int dlclose(void *_h_a_n_d_l_e);

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

       An application writer may use _d_l_c_l_o_s_e() 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 _d_l_o_p_e_n() when the symbol table handle was opened and
       those that were loaded by _d_l_s_y_m() when using the symbol table handle
       identified by _h_a_n_d_l_e.

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

       Although a _d_l_c_l_o_s_e() 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
       _d_l_o_p_e_n() 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.

RREETTUURRNN VVAALLUUEE
       If the referenced symbol table handle was successfully closed,
       _d_l_c_l_o_s_e() shall return 0. If _h_a_n_d_l_e does not refer to an open symbol
       table handle or if the symbol table handle could not be closed,
       _d_l_c_l_o_s_e() shall return a non-zero value. More detailed diagnostic
       information shall be available through _d_l_e_r_r_o_r().

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       The following example illustrates use of _d_l_o_p_e_n() and _d_l_c_l_o_s_e():


           #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);
           ...

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       A conforming application should employ a symbol table handle returned
       from a _d_l_o_p_e_n() invocation only within a given scope bracketed by a
       _d_l_o_p_e_n() operation and the corresponding _d_l_c_l_o_s_e() operation.
       Implementations are free to use reference counting or other techniques
       such that multiple calls to _d_l_o_p_e_n() 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 _d_l_s_y_m() and _d_l_c_l_o_s_e().

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _d_l_e_r_r_o_r(), _d_l_o_p_e_n(), _d_l_s_y_m()

       The Base Definitions volume of POSIX.1-2017, <<ddllffccnn..hh>>

CCOOPPYYRRIIGGHHTT
       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)
