SYS_KLOAD sysconfig Operation

Purpose

Loads a kernel extension into the kernel.

Description

The SYS_KLOAD sysconfig operation is used to load a kernel extension object file specified by a path name into the kernel. A kernel module ID for that instance of the module is returned. The SYS_KLOAD operation loads a new copy of the object file into the kernel even though one or more copies of the specified object file may have already been loaded into the kernel. The returned module ID can then be used for any of these three functions:

Subsequent invocation of the module's entry point (using the SYS_CFGKMOD (SYS_CFGKMOD sysconfig Operation) operation)
Invocation of a device driver's ddconfig subroutine (using the SYS_CFGDD (SYS_CFGDD sysconfig Operation) operation)
Unloading the kernel module (using the SYS_KULOAD (SYS_KULOAD sysconfig Operation) operation).

The parmp parameter on the sysconfig subroutine must point to a cfg_load structure, (defined in the sys/sysconfig.h file), with the path field specifying the path name for a valid kernel object file. The parmlen parameter should be set to the size of the cfg_load structure.

Note: A separate sysconfig operation, the SYS_SINGLELOAD (SYS_SINGLELOAD sysconfig Operation) operation, also loads kernel extensions. This operation, however, only loads the requested object file if not already loaded.

Loader Symbol Binding Support

The following information describes the symbol binding support provided when loading kernel object files.

Importing Symbols

Symbols imported from the kernel name space are resolved with symbols that exist in the corresponding 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 files. These other kernel object files are loaded along with the specified object file if they are required to resolve the imported symbols.

Finding Directory Locations for Unqualified File Names

If the module header contains an unqualified base file name for the symbol ( that is, no / [slash] characters in the name), a libpath search string is used to find the location of the shared object file required to resolve imported symbols. This libpath search string can be taken from one of two places. If the libpath field in the cfg_load structure is not null, then it points to a character string specifying the libpath to be used. However, if the libpath field is null, then the libpath is taken from the module header of the object file specified by the path field in the same (cfg_load) structure.

The libpath specification found in object files loaded in order to resolve imported symbols is not used.

The kernel loader service does not support deferred symbol resolution. The load of the kernel object file is terminated with an error if any imported symbols cannot be resolved.

Exporting Symbols

Any symbols exported by the specified kernel object file are added to the corresponding kernel name space. This makes these symbols available to other subsequently loaded kernel object files. Any symbols specified with the SYSCALL keyword in the export list at link-edit time are added to the system call table at load time. These symbols are then available to application programs as a system call. Symbols can be added to the 32-bit and 64-bit system call tables separately by using the syscall32 and syscall64 keywords. Symbols can be added to both system call tables by using the syscall3264 keyword. A kernel extension that just exports 32-bit system calls can have all its system calls exported to 64-bit as well by passing the SYS_64BIT flag ORed with the SYS_KLOAD command to sysconfig.

Kernel object files loaded on behalf of the specified kernel object file to resolve imported symbols do not have their exported symbols added to the corresponding kernel name space.

These object files are considered private since they do not export symbols to the kernel name space. For these types of object files, a new copy of the object file is loaded on each SYS_KLOAD operation of a kernel extension that imports symbols from the private object file. In order for a kernel extension to add its exported symbols to the kernel name space, it must be explicitly loaded with the SYS_KLOAD operation before any other object files using the symbols are loaded. For kernel extensions of this type (those exporting symbols to the kernel name space), typically only one copy of the object file should ever be loaded.

Return Values

If the object file is loaded without error, the module ID is returned in the kmid variable within the cfg_load structure and the subroutine returns a value of 0.

Error Codes

On error, the subroutine returns a value of -1 and the errno global variable is set to one of the following values:

Item	Description
EACCES	One of the following reasons applies: The calling process does not have the required privilege. An object module to be loaded is not an ordinary file. The mode of the object module file denies read-only permission.
EFAULT	The calling process does not have sufficient authority to access the data area described by the parmp and parmlen parameters provided on the system call. This error is also returned if an I/O error occurred when accessing data in this area.
ENOEXEC	The program file has the appropriate access permission, but has an invalid XCOFF object file indication in its header. The SYS_KLOAD operation only supports loading of XCOFF object files. This error is also returned if the loader is unable to resolve an imported symbol.
EINVAL	The program file has a valid XCOFF indicator in its header, but the header is damaged or is incorrect for the machine on which the file is to be run.
ENOMEM	The load requires more kernel memory than is allowed by the system-imposed maximum.
ETXTBSY	The object file is currently open for writing by some process.

File

Item	Description
sys/sysconfig.h	Contains structure definitions.