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 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  identi-
       fiers)  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 tar-
       get  for dynamic relocations performed in the processing of other relo-
       catable objects--in such environments, an application may  assume  that
       no  relocation,  once  made,  shall be undone or remade unless the exe-
       cutable 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. Implemen-
       tations 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 Electri-
       cal  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.ker-
       nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group                  2013                          DLCLOSE(3P)