Technical Reference: Base Operating System and Extensions, Volume 1

_lazySetErrorHandler Subroutine

Purpose

Installs an error handler into the lazy loading runtime system for the current process.

Library

Standard C Library (libc.a)

Syntax

#include <sys/ldr.h>
#include <sys/errno.h>

typedef void (*_handler_t(
char *_module,
char *_symbol,
unsigned int _errVal ))();

handler_t *_lazySetErrorHandler(err_handler)
handler_t *err_handler;

Description

This function allows a process to install a custom error handler to be called when a lazy loading reference fails to find the required module or function. This function should only be used when the main program or one of its dependent modules was linked with the -blazy option. To call _lazySetErrorHandler from a module that is not linked with the -blazy option, you must use the -lrtl option. If you use -blazy, you do not need to specify -lrtl.

This function is not thread safe. The calling program should ensure that _lazySetErrorHandler is not called by multiple threads at the same time.

The user-supplied error handler may print its own error message, provide a substitute function to be used in place of the called function, or call the longjmp subroutine. To provide a substitute function that will be called instead of the originally referenced function, the error handler should return a pointer to the substitute function. This substitute function will be called by all subsequent calls to the intended function from the same module. If the value returned by the error handler appears to be invalid (for example, a NULL pointer), the default error handler will be used.

Each calling module resolves its lazy references independent of other modules. That is, if module A and B both call foo subroutine in module C, but module C does not export foo subroutine, the error handler will be called once when foo subroutine is called for the first time from A, and once when foo subroutine is called for the first time from B.

The default lazy loading error handler will print a message containing: the name of module that the program required; the name of the symbol being accessed; and the error value generated by the failure. Since the default handler considers a lazy load error to be fatal, the process will exit with a status of 1.

During execution of a program that utilizes lazy loading, there are a few conditions that may cause an error to occur. In all cases the current error handler will be called.

1. The referenced module (which is to be loaded upon function invocation) is unavailable or cannot be loaded. The errVal parameter will probably indicate the reason for the error if a system call failed.
2. A function is referenced, but the loaded module does not contain a definition for the function. In this case, errVal parameter will be EINVAL.

Some possibilities as to why either of these errors might occur:

1. The LIBPATH environment variable may contain a set of search paths that cause the application to load the wrong version of a module.
2. A module has been changed and no longer provides the same set of symbols that it did when the application was built.
3. The load subroutine fails due to a lack of resources available to the process.

Parameters

Note that the value of module or symbol may be NULL if the calling module has somehow been corrupted.

If the err_handler parameter is NULL, the default error handler is restored.

Return Value

The function returns a pointer to the previous user-supplied error handler, or NULL if the default error handler was in effect.

Implementation Specifics

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

Related Information

The load (load Subroutine) subroutine.

The ld command.

The Shared Library Overview and Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts.

The Shared Library and Lazy Loading in AIX 5L Version 5.1 General Programming Concepts.