[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

unload Subroutine

Purpose

Unloads a module.

Library

Standard C Library (libc.a)

Syntax

#include <sys/ldr.h>

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

Description

The unload subroutine unloads the specified module and its dependents. The value returned by the load subroutine is passed to the unload subroutine as FunctionPointer.

If the program calling the unload subroutine was linked on 4.2 or a later release, 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 subroutine frees 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.

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

FunctionPointer Specifies the name of the function returned by the load subroutine.

Return Values

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

Error Codes

If the unload subroutine fails, 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:

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

Implementation Specifics

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

Related Information

The load subroutine, loadbind subroutine, loadquery subroutine, dlclose subroutine.

The ld command.

Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Contents | Glossary | Home | Search ]