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

Technical Reference: Base Operating System and Extensions, Volume 1


load Subroutine

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

load subroutine on POWER-based Platform

Purpose

Loads a module into the current process.

Syntax


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

Description

The load subroutine loads 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 exec subroutine is similar to the load subroutine, except that:

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 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. The first instance of the base name found is used; if the file is not of the proper form, or in the case of an archive 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.

Parameters


ModuleName Points to the name of the module to be loaded. The module name consists of a pathname, and on AIX 4.2 or later, an optional member name. If the pathname contains at least on / character, the name is used directly, and no directory searches are performed to locate the file. If the pathname contains no / characters, it is treated as a base name, and should be in one of the directories listed in the library path.

The library path is either the value of the LibraryPath parameter if not a null value, or the value of the LIBPATH environment variable (if set) or the library path used at process exec time (if the L_LIBPATH_EXEC is set). If no library path is provided, the module should be in the current directory.

(This paragraph only applies to AIX 4.2 and later releases.) The ModuleName parameter may explicitly name an archive member. The syntax is pathname(member) where pathname follows the rules specified in the previous paragraph, and member is the name of a specific archive member. The parentheses are a required portion of the specification and no intervening spaces are allowed. If an archive member is named, the L_LOADMEMBER flag must be added to the Flags parameter. Otherwise, the entire ModuleName parameter is treated as an explicit filename.

Flags Modifies the behavior of the load service as follows (see the ldr.h file). If no special behavior is required, set the value of the flags parameter to 0 (zero). For compatibility, a value of 1 (one) may also be specified.

L_LIBPATH_EXEC
Specifies that the library path used at process exec time should be prepended to any library path specified in the load call (either as an argument or environment variable). It is recommended that this flag be specified in all calls to the load subroutine.

L_LOADMEMBER

(This flag only applies to AIX 4.2 and later releases.) Indicates that the ModuleName parameter may specify an archive member. The ModuleName argument is searched for parentheses, and if found the parameter is treated as a filename/member name pair. If this flag is present and the ModuleName parameter does not contain parenthesis the entire ModuleName parameter is treated as a filename specification. Under either condition the filename is expected to be found within the library path or the current directory.

L_NOAUTODEFER
Specifies that any deferred imports in the module being loaded must be explicitly resolved by use of the loadbind subroutine. This allows unresolved imports to be explicitly resolved at a later time with a specified module. If this flag is not specified, deferred imports (marked for deferred resolution) are resolved at the earliest opportunity when any subsequently loaded module exports symbols matching unresolved imports.
LibraryPath Points to a character string that specifies the default library search path.

If the LibraryPath parameter is NULL the LIBPATH environment variable is used. See the section Searching for Dependent Modules for more information.

The library path is used to locate dependent modules that are specified as basenames (that is, their pathname components do not contain a / (slash) character.

Note the difference between setting the LibraryPath parameter to null, and having the LibraryPath parameter point to a null string (" "). A null string is a valid library path which consists of a single directory: the current directory.

Return Values

Upon successful completion, the load subroutine returns 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 subroutine fails, a null pointer is returned, the module is not loaded, and errno global variable is set to indicate the error. The load subroutine fails if one or more of the following are true of a module to be explicitly or automatically loaded:

EACCES Indicates the file is not an ordinary file, or the mode of the program file denies execution permission, or search permission is denied on a component of the path prefix.
EINVAL Indicates the file or archive member has a valid magic number in its header, but the header is damaged or is incorrect for the machine on which the file is to be run.
ELOOP Indicates too many symbolic links were encountered in translating the path name.
ENOEXEC Indicates an error occurred when loading or resolving symbols for the specified module. This can be due to an attempt to load a module with an invalid XCOFF header, a failure to resolve symbols that were not defined as deferred imports or several other load time related problems. The loadquery subroutine can be used to return more information about the load failure. If the main program was linked on a AIX 4.2 or later system, and if runtime linking is used, the load subroutine will fail if the runtime linker could not resolve some symbols. In this case, errno will be set to ENOEXEC, but the loadquery subroutine will not return any additional information.
ENOMEM Indicates the program requires more memory than is allowed by the system-imposed maximum.
ETXTBSY Indicates the file is currently open for writing by some process.
ENAMETOOLONG Indicates a component of a path name exceeded 255 characters, or an entire path name exceeded 1023 characters.
ENOENT Indicates a component of the path prefix does not exist, or the path name is a null value.
ENOTDIR Indicates a component of the path prefix is not a directory.
ESTALE Indicates the process root or current directory is located in a virtual file system that has been unmounted.

Related Information

The dlopen (dlopen Subroutine) subroutine, exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutine, loadbind (loadbind Subroutine) subroutine, loadquery (loadquery Subroutine) subroutine, ptrace (ptrace, ptracex, ptrace64 Subroutine) subroutine, unload subroutine.

The ld command.

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

load subroutine on Itanium-based Platform

Purpose

Loads a module into the current process.

Syntax


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

Description

The load subroutine loads the specified module into the calling process's address space. A module is a shared object. Unlike the exec subroutine, the load subroutine does not replace the current program with a new one. Instead, it loads the new module into the process private segment at the current break value and the break value is updated to point past the new module.

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. These modules can have either shared or private file characteristics that control how and where they are loaded.

Shared modules 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.

If the file name contains any / (slash) characters, it is used directly and must name an appropriate file. However, if the file name is a base name (contains no / characters), the runtime linker searches the directories specified in the default library path for an object file with that base name.

The LibraryPath is a string containing one or more directory path names separated by colons. If the base name is not found, the search continues, using the library path specified in the object file containing the symbol being resolved (normally the library path specified to the ld command that creatred the object file). The first instance of the base name found is used. An error occurs if this module cannot be loaded or does not export a definition of the symbol being resolved.

The default library path may be specified using the LibraryPath parameter. If not explicitly set, the default library path may be obtained from the LD_LIBRARY_PATH environment variable or from the module specified by the FilePath parameter. If the L_LIBPATH_EXEC flag is specified, then the library path used at process exec time is prepended to any other library path specified in the load call.

(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.

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.

Parameters


ModuleName Points to the name of the module to be loaded. If the FilePath contains no / characters, it is treated as a base name, and should be in one of the directories listed in the library path.

The library path is either the value of the LibraryPath parameter if not a null value, or the value of the LD_LIBRARY_PATH environment variable (if set) or the library path used at process exec time (if the L_LIBPATH_EXEC is set). If no library path is provided, the module should be in the current directory.

If the FilePath parameter is not a base name (if it contains at least one / character), the name is used as it is, and no library path searches are performed to locate the object file. However, the library path is used to locate dependent modules.

Flags Modifies the behavior of the load service as follows (see the ldr.h file). If no special behavior is required, set the value of the flags parameter to 0 (zero). For compatibility, a value of 1 (one) may also be specified.

L_LIBPATH_EXEC
Specifies that the library path used at process exec time should be prepended to any library path specified in the load call (either as an argument or environment variable). It is recommended that this flag be specified in all calls to the load subroutine.

L_NOAUTODEFER
Specifies that any deferred imports in the module being loaded must be explicitly resolved by use of the loadbind subroutine. This allows unresolved imports to be explicitly resolved at a later time with a specified module. If this flag is not specified, deferred imports (marked for deferred resolution) are resolved at the earliest opportunity when any subsequently loaded module exports symbols matching unresolved imports.
LibraryPath Points to a character string that specifies the default library search path.

If the LibraryPath parameter is a null value and the LD_LIBRARY_PATH environment variable is set, the LD_LIBRARY_PATH value is used as the default load path. If neither default library path option is provided, the library path specified in the loader section of the object file specified in the FilePath parameter is used as the default library path. If the L_LIBPATH_EXEC flag is specified, then the library path used at process exec time is prepended to the above specified default library path.

Note the difference between setting the LibraryPath parameter to null, and having the LibraryPath parameter point to a null string (" "). A null string is a valid library path which consists of a single directory: the current directory.

If the module is not in the LibraryPath parameter or the LD_LIBRARY_PATH environmental variable (if the LibraryPath parameter was null), then the library path specified in the loader section of the module importing the symbol is used to locate the module exporting the required symbol. The library path in the importing module was specified when the module was link-edited (by the ld command).

The library path search is not performed when either a relative or an absolute path name is specified for the module exporting the symbol.

Return Values

Upon successful completion, the load subroutine returns 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 subroutine fails, a null pointer is returned, the module is not loaded, and errno global variable is set to indicate the error. The load subroutine fails if one or more of the following are true of a module to be explicitly or automatically loaded:

EACCES Indicates the file is not an ordinary file, or the mode of the program file denies execution permission, or search permission is denied on a component of the path prefix.
EINVAL Indicates the file or archive member has a valid magic number in its header, but the header is damaged or is incorrect for the machine on which the file is to be run.
ELOOP Indicates too many symbolic links were encountered in translating the path name.
ENOEXEC Indicates an error occurred when loading or resolving symbols for the specified module. This can be due to an attempt to load a module with an invalid ELF header, a failure to resolve symbols or several other load time related problems. The loadquery subroutine can be used to return more information about the load failure. In this case, errno will be set to ENOEXEC, but the loadquery subroutine will not return any additional information.
ENOMEM Indicates the program requires more memory than is allowed by the system-imposed maximum.
ETXTBSY Indicates the file is currently open for writing by some process.
ENAMETOOLONG Indicates a component of a path name exceeded 255 characters, or an entire path name exceeded 1023 characters.
ENOENT Indicates a component of the path prefix does not exist, or the path name is a null value.
ENOTDIR Indicates a component of the path prefix is not a directory.
ESTALE Indicates the process root or current directory is located in a virtual file system that has been unmounted.

Related Information

The dlopen (dlopen Subroutine) subroutine, exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutine, loadbind (loadbind Subroutine) subroutine, loadquery (loadquery Subroutine) subroutine, ptrace (ptrace, ptracex, ptrace64 Subroutine) subroutine, unload subroutine.

The ld command.

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


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