[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 1

kmod_load Kernel Service

Purpose

Loads an object file into the kernel or queries for an object file already loaded.

Syntax

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

int kmod_load (pathp, flags,libpathp, kmidp)
caddr_t pathp;
uint flags;
caddr_t libpathp;
mid_t *kmidp;

Parameters

pathp Points to a character string containing the path name of the object file to load or query.
flags Specifies a set of loader flags describing which loader options to invoke. The following flags are defined:
LD_USRPATH The character strings pointed to by the pathp and libpathp parameters are in user address space. If the LD_USRPATH flag is not set, the character strings are assumed to be in kernel, or system, space.
LD_KERNELEX Puts this object file's exported symbols into the /usr/lib/boot/unix name space. Additional object files loaded due to symbol resolution for the specified file do not have their exported symbols placed in kernel name space.
LD_SINGLELOAD When this flag is set, the object file specified by the pathp parameter is loaded into the kernel only if an object file with the same path name has not already been loaded. If an object file with the same path name has already been loaded, its module ID is returned (using the kmidp parameter) and its load count incremented. If the object file is yet not loaded, this service performs the load as if the flag were not set.

This option is useful in supporting global kernel routines where only one copy of the routine and its data can be present. Typically, routines that export symbols to be added to kernel name space are of this type.

Note: A path-name comparison is done to determine whether the same object file has already been loaded. This service will erroneously load a new copy of the object file into the kernel if the path name to the object file is expressed differently than it was on a previous load request.

If neither this flag nor the LD_QUERY flag is set, this service loads a new copy of the object file into the kernel. This occurs even if other copies of the object file have previously been loaded.

LD_QUERY This flag specifies that a query operation will determine if the object file specified by the pathp parameter is loaded. If not loaded, a kernel module ID of 0 is returned using the kmidp parameter. Otherwise, the kernel module ID assigned to the object file is returned.

If multiple instances of this file have been loaded into the kernel, the kernel module ID of the most recently loaded object file is returned.

The libpathp parameter is not used for this option.

Note: A path-name comparison is done to determine whether the same object file has been loaded. This service will erroneously return a not loaded condition if the path name to the object file is expressed differently than it was on a previous load request.

If this flag is set, no object file is loaded and the LD_SINGLELOAD and LD_KERNELEX flags are ignored, if set.

libpathp Points to a character string containing the search path to use for finding object files required to complete symbol resolution for this load. If the parameter is null, the search path is set from the specification in the object file header for the object file specified by the pathp parameter.
kmidp Points to an area where the kernel module ID associated with this load of the specified module is to be returned. The data in this area is not valid if the kmod_load service returns a nonzero return code.

Description

The kmod_load kernel service loads into the kernel a kernel extension object file specified by the pathp parameter. This service returns a kernel module ID for that instance of the module.

You can specify flags to request a single load, which ensures that only one copy of the object file is loaded into the kernel. An additional option is simply to query for a given object file (specified by path name). This allows the user to determine if a module is already loaded and then access its assigned kernel module ID.

The kmod_load service also provides load-time symbol resolution of the loaded module's imported symbols. The kmod_load service loads additional kernel object modules if required for symbol resolution.

Loader Symbol Binding Support

Symbols imported from the kernel name space are resolved with symbols that exist in the kernel name space at the time of the load. (Symbols are imported from the kernel name space by specifying the #!/unix character string as the first field in an import list at link-edit time.)

Kernel modules can also import symbols from other kernel object modules. These other kernel object modules are loaded along with the specified object module if they are needed to resolve the imported symbols.

Any symbols exported by the specified kernel object module are added to the kernel name space if the flags parameter has the LD_KERNELEX flag set. This makes the symbols available to other subsequently loaded kernel object modules. Kernel object modules loaded on behalf of the specified kernel object module (to resolve imported symbols) do not have their exported symbols added to the kernel name space.

Kernel export symbols specified (at link-edit time) with the SYSCALL keyword in the primary module's export list are added to the system call table. These kernel export symbols are available to application programs as system calls.

Finding Shared Object Modules for Resolving Symbol References

The search path search string is taken from the module header of the object module specified by the pathp parameter if the libpathp parameter is null. The module header of the object module specified by the pathp parameter is used.

If the module header contains an unqualified base file name for the symbol (no / [slash] characters in the name), a search string is used to find the location of the shared object module required to resolve the import. This search string can be taken from one of two places. If the libpathp parameter on the call to the kmod_load service is not null, then it points to a character string specifying the search path to be used. However, if the libpathp parameter is null, then the search path is to be taken from the module header for the object module specified by the pathp parameter.

The search path specification found in object modules loaded to resolve imported symbols is not used. The kernel loader service does not support deferred symbol resolution. The load of the kernel module is terminated with an error if any imported symbols cannot be resolved.

Execution Environment

The kmod_load kernel service can be called from the process environment only.

Return Values

If the object file is loaded without error, the module ID is returned in the location pointed to by the kmidp parameter and the return code is set to 0.

Error Codes

If an error results, the module is not loaded, and no kernel module ID is returned. The return code is set to one of the following return values:

EACCES Indicates that an object module to be loaded is not an ordinary file or that the mode of the object module file denies read-only access.
EACCES Search permission is denied on a component of the path prefix.
EFAULT Indicates that the calling process does not have sufficient authority to access the data area described by the pathp or libpathp parameters when the LD_USRPATH flag is set. This error code is also returned if an I/O error occurs when accessing data in this area.
ENOEXEC Indicates that the program file has the appropriate access permission, but has an XCOFF indicator that is not valid in its header. The kmod_load kernel service supports loading of XCOFF (Extended Common Object File Format) object files only. This error code is also returned if the loader is unable to resolve an imported symbol.
EINVAL Indicates that the program file has a valid XCOFF indicator in its header, but the header is either damaged or incorrect for the machine on which the file is to be loaded.
ENOMEM Indicates that the load requires more kernel memory than allowed by the system-imposed maximum.
ETXTBSY Indicates that the object file is currently open for writing by some process.
ENOTDIR Indicates that a component of the path prefix is not a directory.
ENOENT Indicates that no such file or directory exists or the path name is null.
ESTALE Indicates that the caller's root or current directory is located in a virtual file system that has been unmounted.
ELOOP Indicates that too many symbolic links were encountered in translating the path or libpathp parameter.
ENAMETOOLONG Indicates that a component of a path name exceeded 255 characters, or an entire path name exceeded 1023 characters.
EIO Indicates that an I/O error occurred during the operation.

Implementation Specifics

The kmod_unload kernel service is part of Base Operating System (BOS) Runtime.

Related Information

The kmod_unload kernel service.

Kernel Extension and Device Driver Management Kernel Services in AIX Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Home | Search ]