1DLCLOSE(3P)                POSIX Programmer's Manual               DLCLOSE(3P)
2
3
4

PROLOG

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

NAME

12       dlclose — close a symbol table handle
13

SYNOPSIS

15       #include <dlfcn.h>
16
17       int dlclose(void *handle);
18

DESCRIPTION

20       The dlclose() function shall inform the system that  the  symbol  table
21       handle specified by handle is no longer needed by the application.
22
23       An  application  writer may use dlclose() to make a statement of intent
24       on the part of the process, but this  statement  does  not  create  any
25       requirement  upon  the  implementation. When the symbol table handle is
26       closed, the implementation may unload the executable object files  that
27       were  loaded  by  dlopen()  when the symbol table handle was opened and
28       those that were loaded by dlsym() when using the  symbol  table  handle
29       identified by handle.
30
31       Once  a  symbol  table  handle  has  been closed, an application should
32       assume that any symbols (function identifiers and data  object  identi‐
33       fiers)  made  visible  using  handle,  are  no  longer available to the
34       process.
35
36       Although a dlclose() operation is not required to remove any  functions
37       or  data  objects  from the address space, neither is an implementation
38       prohibited from doing so. The only restriction on  such  a  removal  is
39       that  no  function nor data object shall be removed to which references
40       have been relocated, until or unless all such references  are  removed.
41       For  instance,  an  executable  object file that had been loaded with a
42       dlopen() operation specifying the RTLD_GLOBAL flag might provide a tar‐
43       get  for dynamic relocations performed in the processing of other relo‐
44       catable objects—in such environments, an application may assume that no
45       relocation,  once made, shall be undone or remade unless the executable
46       object file containing the relocated object has itself been removed.
47

RETURN VALUE

49       If  the  referenced  symbol  table  handle  was  successfully   closed,
50       dlclose()  shall  return  0. If handle does not refer to an open symbol
51       table handle or if  the  symbol  table  handle  could  not  be  closed,
52       dlclose()  shall  return  a  non-zero  value.  More detailed diagnostic
53       information shall be available through dlerror().
54

ERRORS

56       No errors are defined.
57
58       The following sections are informative.
59

EXAMPLES

61       The following example illustrates use of dlopen() and dlclose():
62
63
64           #include <dlfcn.h>
65           int eret;
66           void *mylib;
67           ...
68           /* Open a dynamic library and then close it ... */
69           mylib = dlopen("mylib.so", RTLD_LOCAL | RTLD_LAZY);
70           ...
71           eret = dlclose(mylib);
72           ...
73

APPLICATION USAGE

75       A conforming application should employ a symbol table  handle  returned
76       from  a  dlopen()  invocation  only within a given scope bracketed by a
77       dlopen() operation and the corresponding dlclose() operation. Implemen‐
78       tations  are  free  to  use reference counting or other techniques such
79       that multiple calls to dlopen() referencing the same executable  object
80       file  may  return a pointer to the same data object as the symbol table
81       handle.
82
83       Implementations are also free to re-use a handle.  For  these  reasons,
84       the  value  of  a  handle must be treated as an opaque data type by the
85       application, used only in calls to dlsym() and dlclose().
86

RATIONALE

88       None.
89

FUTURE DIRECTIONS

91       None.
92

SEE ALSO

94       dlerror(), dlopen(), dlsym()
95
96       The Base Definitions volume of POSIX.1‐2017, <dlfcn.h>
97
99       Portions of this text are reprinted and reproduced in  electronic  form
100       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
101       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
102       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
103       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
104       event of any discrepancy between this version and the original IEEE and
105       The Open Group Standard, the original IEEE and The Open Group  Standard
106       is  the  referee document. The original Standard can be obtained online
107       at http://www.opengroup.org/unix/online.html .
108
109       Any typographical or formatting errors that appear  in  this  page  are
110       most likely to have been introduced during the conversion of the source
111       files to man page format. To report such errors,  see  https://www.ker
112       nel.org/doc/man-pages/reporting_bugs.html .
113
114
115
116IEEE/The Open Group                  2017                          DLCLOSE(3P)
Impressum