[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Kernel and Subsystems, 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 not yet 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:
Return Value |
Description |
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. |
Related Information
The kmod_unload kernel service.
Kernel Extension and Device
Driver Management Kernel Services in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]