unload and terminateAndUnload Subroutines

Purpose

Unloads a module.

Library

Standard C Library (libc.a)

Syntax

#include <sys/ldr.h>

int unload( FunctionPointer)
int (*FunctionPointer)( );

int terminateAndUnload( FunctionPointer)
int (*FunctionPointer)( );

Description

The unload and terminateAndUnload subroutines unload the specified module and its dependents. The value returned by the load subroutine is passed to the unload subroutine as FunctionPointer. The unload subroutine calls termination routines (fini routines) for the specified module and any of its dependents that are not being used by any other module.

The unload and terminateAndUnload subroutines free the storage used by the specified module only if the module is no longer in use. A module is in use as long as any other module that is in use imports symbols from it.

The unload subroutine does not perform C++ termination, that is, calling destructors. Use the terminateAndUnload subroutine instead. The dlclose subroutine performs C++ termination like the terminateAndUnload subroutine does.

When a module is unloaded, any deferred resolution symbols that were bound to the module remain bound. These bindings create references to the module that cannot be undone, even with the unload subroutine.

(This paragraph only applies to AIX® 4.3.1 and previous releases.) When a process is executing under ptrace control, portions of the process's address space are recopied after the unload processing completes. For a 32-bit process, the main program text (loaded in segment 1) and shared library modules (loaded in segment 13) are recopied. Any breakpoints or other modifications to these segments must be reinserted after the unload call. For a 64-bit process, shared library modules are recopied after an unload call. The debugger will be notified by setting the W_SLWTED flag in the status returned by wait, so that it can reinsert breakpoints.

(This paragraph only applies to AIX 4.3.2 and later releases.) When a process executing under ptrace control calls unload, the debugger is notified by setting the W_SLWTED flag in the status returned by wait. If a module loaded in the shared library is no longer in use by the process, the module is deleted from the process's copy of the shared library segment by freeing the pages containing the module.

Parameters

Item Description
FunctionPointer Specifies the name of the function that returns.

Return Values

Upon successful completion, the unload and terminateAndUnload subroutines return a value of 0, even if the module couldn't be unloaded because it is still in use.

Error Codes

If the unload and terminateAndUnload subroutines fail, a value of -1 is returned, the program is not unloaded, and errno is set to indicate the error. errno may be set to one of the following:

Item Description
EINVAL The FunctionPointer parameter does not correspond to a program loaded by the load subroutine.