dlclose.3p (4611B)
- '\" et
- .TH DLCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH 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.
- .\"
- .SH NAME
- dlclose
- \(em close a symbol table handle
- .SH SYNOPSIS
- .LP
- .nf
- #include <dlfcn.h>
- .P
- int dlclose(void *\fIhandle\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIdlclose\fR()
- function shall inform the system that the symbol table handle specified by
- .IR handle
- is no longer needed by the application.
- .P
- An application writer may use
- \fIdlclose\fR()
- 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
- \fIdlopen\fR()
- when the symbol table handle was opened and those that were loaded by
- \fIdlsym\fR()
- when using the symbol table handle identified by
- .IR handle .
- .P
- Once a symbol table handle has been closed, an application should assume
- that any symbols (function identifiers and data object identifiers)
- made visible using
- .IR handle ,
- are no longer available to the process.
- .P
- Although a
- \fIdlclose\fR()
- 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
- \fIdlopen\fR()
- operation specifying the RTLD_GLOBAL flag might provide a target for
- dynamic relocations performed in the processing of other relocatable
- objects\(emin 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.
- .SH "RETURN VALUE"
- If the referenced symbol table handle was successfully closed,
- \fIdlclose\fR()
- shall return 0. If
- .IR handle
- does not refer to an open symbol table handle or if the symbol table
- handle could not be closed,
- \fIdlclose\fR()
- shall return a non-zero value. More detailed diagnostic information
- shall be available through
- \fIdlerror\fR().
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- The following example illustrates use of
- \fIdlopen\fR()
- and
- \fIdlclose\fR():
- .sp
- .RS 4
- .nf
- #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);
- \&...
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- A conforming application should employ a symbol table handle returned
- from a
- \fIdlopen\fR()
- invocation only within a given scope bracketed by a
- \fIdlopen\fR()
- operation and the corresponding
- \fIdlclose\fR()
- operation. Implementations are free to use reference counting or other
- techniques such that multiple calls to
- \fIdlopen\fR()
- referencing the same executable object file may return a pointer to the
- same data object as the symbol table handle.
- .P
- 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
- \fIdlsym\fR()
- and
- \fIdlclose\fR().
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIdlerror\fR\^(\|)",
- .IR "\fIdlopen\fR\^(\|)",
- .IR "\fIdlsym\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<dlfcn.h>\fP"
- .\"
- .SH COPYRIGHT
- 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 .
- .PP
- 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 .