# dlclose

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


* * *