load and loadAndInit Subroutines

Purpose

Loads a module into the current process.

Syntax

int *load ( ModuleName, Flags, LibraryPath)
char *ModuleName;
uint Flags;
char *LibraryPath;

int *loadAndInit ( ModuleName, Flags, LibraryPath)
char *ModuleName;
uint Flags;
char *LibraryPath;

Description

The load and loadAndInit subroutines load the specified module into the calling process's address space. A module can be a regular file or a member of an archive. When adding a new module to the address space of a 32-bit process, the load operation may cause the break value to change.

The load subroutine is not a preferred method to load C++ modules. Use loadAndInit subroutine instead. The loadAndInit subroutine uses the same interface as load but performs C++ initialization.

The exec subroutine is similar to the load subroutine, except that:

• The load subroutine does not replace the current program with a new one.
• The exec subroutine does not have an explicit library path parameter; it has only the LIBPATH and LD_LIBRARY_PATH environment variables. Also, these library path environment variables are ignored when the program using the exec subroutine has more privilege than the caller (for example, in the case of a set-UID program).

A large application can be split up into one or more modules in one of two ways that allow execution within the same process. The first way is to create each of the application's modules separately and use load to explicitly load a module when it is needed. The other way is to specify the relationship between the modules when they are created by defining imported and exported symbols.

Modules can import symbols from other modules. Whenever symbols are imported from one or more other modules, these modules are automatically loaded to resolve the symbol references if the required modules are not already loaded, and if the imported symbols are not specified as deferred imports. These modules can be archive members in libraries or individual files and can have either shared or private file characteristics that control how and where they are loaded.

Shared modules (typically members of a shared library archive) are loaded into the shared library region, when their access permissions allow sharing, that is, when they have read-other permission. Private modules, and shared modules without the required permissions for sharing, are loaded into the process private region.

When the loader resolves a symbol, it uses the file name recorded with that symbol to find the module that exports the symbol. If the file name contains any / (slash) characters, it is used directly and must name an appropriate file or archive member. However, if the file name is a base name (contains no / characters), the loader searches the directories specified in the default library path for a file (i.e. a module or an archive) with that base name.

The LibraryPath is a string containing one or more directory path names separated by colons. See the section Searching for Dependent Modules for information on library path searching.

(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 load 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 load call. For a 64-bit process, shared library modules are recopied after a load 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 load, the debugger is notified by setting the W_SLWTED flag in the status returned by wait. Any modules newly loaded into the shared library segments will be copied to the process's private copy of these segments, so that they can be examined or modified by the debugger.

If the program calling the load subroutine was linked on AIX 4.2 or a later release, the load subroutine will call initialization routines (init routines) for the new module and any of its dependents if they were not already loaded.

Modules loaded by this subroutine are automatically unloaded when the process terminates or when the exec subroutine is executed. They are explicitly unloaded by calling the unload subroutine.

Searching for Dependent Modules

The load operation and the exec operation differ slightly in their dependent module search mechanism. When a module is added to the address space of a running process (the load operation), the rules outlined in the next section are used to find the named module. Note that dependency relationships may be loosely defined as a tree but recursive relationships between modules may also exist. The following components may used to create a complete library search path:

1. If the L_LIBPATH_EXEC flag is set, the library search path used at exec-time.
2. The value of the LibraryPath parameter if it is non-null. Note that a null string is a valid search path which refers to the current working directory. If the LibraryPath parameter is NULL, the value of the LIBPATH environment variable, or alternatively the LD_LIBRARY_PATH environment variable (if LIBPATH is not set), is used instead.
3. The library search path contained in the loader section of the module being loaded (the ModuleName parameter).
4. The library search path contained in the loader section of the module whose immediate dependents are being loaded. Note that this per-module information changes when searching for each module's immediate dependents.

To find the ModuleName module, components 1 and 2 are used. To find dependents, components 1, 2, 3 and 4 are used in order. Note that if any modules that are already part of the running process satisfy the dependency requirements of the newly loaded module(s), pre-existing modules are not loaded again.

For each colon-separated portion of the aggregate search specification, if the base name is not found the search continues. Additionally, if the needed file is not an archive member, the search will continue past a file having the wrong object mode. If an archive member is needed, searching stops when the first match of the file name is found. If the file is not of the proper form, or in the case of an archive that does not contain the required archive member, or does not export a definition of a required symbol, an error occurs. The library path search is not performed when either a relative or an absolute path name is specified for a dependent module.

The library search path stored within the module is specified at link-edit time.

The load subroutine may cause the calling process to fail if the module specified has a very long chain of dependencies, (for example, lib1.a, which depends on lib2.a, which depends on lib3.a, etc). This is because the loader processes such relationships recursively on a fixed-size stack. This limitation is exposed only when processing a dependency chain that has over one thousand elements.

Parameters

Return Values

Upon successful completion, the load and loadAndInit subroutines return the pointer to function for the entry point of the module. If the module has no entry point, the address of the data section of the module is returned.

Error Codes

If the load and loadAndInit subroutines fail, a null pointer is returned, the module is not loaded, and errno global variable is set to indicate the error. The load and loadAndInit subroutines fail if one or more of the following are true of a module to be explicitly or automatically loaded: