[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1


dlclose Subroutine

The dlclose subroutine includes information for dlclose subroutine on a POWER-based platform and on dlclose subroutine on an Itanium-based platform.

dlclose Subroutine on POWER-based Platform

Purpose

Closes and unloads a module loaded by the dlopen subroutine.

Syntax

#include <dlfcn.h>

int dlclose(Data);
void *Data;

Description

The dlclose subroutine is used to remove access to a module loaded with the dlopen subroutine. In addition, access to dependent modules of the module being unloaded is removed as well.

Modules being unloaded with the dlclose subroutine will not be removed from the process's address space if they are still required by other modules. Nevertheless, subsequent uses of Data are invalid, and further uses of symbols that were exported by the module being unloaded result in undefined behavior.

Parameters


Data A loaded module reference returned from a previous call to dlopen.

Return Values

Upon successful completion, 0 (zero) is returned. Otherwise, errno is set to EINVAL, and the return value is also EINVAL. Even if the dlclose subroutine succeeds, the specified module may still be part of the process's address space if the module is still needed by other modules.

Error Codes


EINVAL The Data parameter does not refer to a module opened by dlopen that is still open. The parameter may be corrupt or the module may have been unloaded by a previous call to dlclose.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The dlerror (dlerror Subroutine) subroutine, dlopen (dlopen Subroutine) subroutine, dlsym (dladdr Subroutine) subroutine, load (load Subroutine) subroutine, loadquery (loadquery Subroutine) subroutine, unload subroutine, loadbind (loadbind Subroutine) subroutine.

The ld command.

The Shared Libraries and Shared Memory Overview and Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

dlclose Subroutine on Itanium-based Platform

Purpose

Closes a shared object.

Syntax

#include <dlfcn.h> 
 
int dlclose(void *handle); 

Description

dlclose disassociates a shared object previously opened by dlopen from the current process. Once an object has been closed using dlclose, its symbols are no longer available to dlsym. All objects loaded automatically as a result of invoking dlopen on the referenced object [see dlopen) (dlopen Subroutine)] are also closed. handle is the value returned by a previous invocation of dlopen.

A successful invocation of dlclose does not guarantee that the objects associated with handle have actually been removed from the address space of the process. Objects loaded by one invocation of dlopen may also be loaded by another invocation of dlopen. The same object may also be opened multiple times. An object is not removed from the address space until all references to that object through an explicit dlopen invocation have been closed and all other objects implicitly referencing that object have also been closed.

Once an object has been closed by dlclose, referencing symbols contained in that object can cause undefined behavior.

Return values

If the referenced object was successfully closed, dlclose returns 0. If the object could not be closed, or if handle does not refer to an open object, dlclose returns a non-0 value. More detailed diagnostic information is available through dlerror.

Related Information

The dlerror (dlerror Subroutine) subroutine, dlopen (dlopen Subroutine) subroutine, and dlsym (dladdr Subroutine) subroutine.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]