bionic (3) dlclose.3posix.gz

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.

SEE ALSO

       dlerror(), dlopen(), dlsym()

       The Base Definitions volume of POSIX.1‐2008, <dlfcn.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers,  Inc
       and  The  Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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 .