modadmin(1M)


modadmin -- loadable kernel module administration

Synopsis

modadmin -l modname . . . | pathname . . .

modadmin -u modid . . .

modadmin -U modname . . .

modadmin -q modid . . .

modadmin -Q modname . . .

modadmin -s | S

modadmin -d dirname | D

Description

modadmin is the administrative command for loadable kernel modules. It performs the following functions:

The loadable modules feature lets you add a module to a running system without rebooting the system or rebuilding the kernel. When the module is no longer needed, this feature also lets you dynamically remove the module, thereby freeing system resources for other use.

Types of modules that can be dynamically loaded include:

Loadable modules are maintained in individual object files (.o files) in the same manner as statically configured modules. Unlike static modules, loadable modules:

The modadmin options have the following meanings:


-l modname
Load the named module(s) modname using the current value of the loadable modules search path to locate the module's object file on disk.

This option searches for a matching file in all directories specified in the loadable modules search path. By default, the search pathname is /etc/conf/mod.d.

The load operation performs all tasks associated with link editing the module to the kernel and making the module accessible to the system. If the module depends on other loadable modules (as defined in /etc/conf/mdevice.d), and these modules are not currently loaded, modadmin will automatically load the dependent modules during the load operation.

When loading completes, an integer modid prints on the standard output to identify the module(s) that was loaded.


-l pathname
Same as -l modname, except the absolute pathname pathname is used to locate the module's object file.

-u modid
Unload the module(s) identified by the integer value modid.

If modid specifies 0 (zero), modadmin attempts to unload all loadable modules.

The unload operation performs all tasks associated with disconnecting the module from the kernel and releasing any memory acquired by the module. When unloading completes, an integer modid prints on the standard output to identify the module(s) that was unloaded.

If the module(s) to be unloaded are currently in-use, are dependents of a loadable module that is currently loaded, or are currently being loaded or unloaded, the unload request will fail.


-U modname
Same as -u modid, except the module(s) to be unloaded is specified by name modname.

-q modid
Print the status of the loaded module(s) identified by the integer value modid.

Information returned by this option includes:


-Q modname
Same as -q modid, except the module(s) for which status information is to be reported is specified by name modname.

-s
Print an abbreviated status for all modules currently loaded.

This option returns a listing of module names and module identifiers only.


-S
Print the full status for all modules currently loaded.

This option returns status information of the form returned by the -q option.


-d pathname
Prepend the pathname pathname to the current loadable modules search path, where pathname specifies directories that should be searched:

pathname must specify an absolute pathname or a list of absolute pathnames delimited by colons. The directories identified by pathname do not have to exist on the system at the time the request to modify the search path using modadmin is made. If these directories do not exist at the time a load takes place, the load operation ignores them.

All modifications to the search path made using this option take effect immediately and affect all subsequent loads (demand and auto-load) and all users on the system.


-D
Reset the loadable modules search path to its default value, /etc/conf/mod.d. The reset takes effect immediately and affects all subsequent loads (demand and auto-load) and all users on the system.

Errors

In the following conditions, modadmin fails and sets errno to:

ENOLOAD
failure in loading a loadable exec module

UX:modadmin: ERROR: Incorrect usage
Command line input contained one or more syntax errors. See the SYNOPSIS section for the correct usage.

UX:modadmin: ERROR: modid: No such file or directory
Unable to load the module modid because the module does not exist.

UX:modadmin: ERROR: Device busy
Unable to load a module because the module is currently in-use.

UX:modadmin: ERROR: Non-numeric ID string: string
Unable to unload or obtain status for a module because the module id string specified a non-numeric value.

UX:modadmin: ERROR: modstat: Invalid argument
Unable to unload or obtain status for module modid because the module does not exist.

UX:modadmin: ERROR: Module: modid, not found
Unable to obtain status for module modid because the module is currently unloaded.

Files


/etc/conf/mod.d/*

Notices

Auto loading

Auto-load occurs when the kernel detects a particular loadable module is required to accomplish some task, but is not currently loaded. For example, if the task were a mount of a file system, and the loadable module that supports the file system was not loaded, the kernel would automatically load the file system module. Once the module was loaded, the mount would take place.

Auto-unload occurs when the kernel detects that the amount of available memory is low. At this time, the kernel begins unloading all modules that are not currently in-use--and that have not been used for some predetermined amount of time--to reclaim the memory allocated to these modules. Unloading continues until the amount of available memory reaches a predetermined high water mark, or the list of modules that are candidates for unloading is exhausted. The amount of time that must elapse before unused modules are considered candidates for unloading is controlled by the value of the global tunable parameter DEF_UNLOAD_DELAY in /etc/conf/mtune.d. Individual modules can override the value of the global auto-unload delay by specifying their own auto-unload delay value in their Mtune files.

Modules that are demand loaded using the modadmin command cannot be auto unloaded by the kernel. If a demand-loaded module is no longer needed in the system, it must be demand-unloaded. If a demand unload for a loaded module fails (because the module is in-use, for example) the unload mechanism will add the module to a list of modules that are candidates for the next auto-unload.

Loadable HBA driver considerations

Loadable HBA drivers:

System profiler

When the system profiler prf is turned on, loadable modules are locked into memory and cannot be unloaded. Modules can continue to be loaded with profiling enabled, but these modules will also become locked. When profiling is disabled, the locks for all loadable modules are removed.

References

idbuild(1M), idmodload(1M), idtune(1M), init(1M), modload(2), moduload(2), modpath(2), modstat(2), prf(7)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004