modadmin(ADM)

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:

load a loadable module into a running system
unload a loadable module from a running system
display the status of a loadable module(s) that is currently loaded
modify the loadable modules search path

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:

device drivers (block, character, STREAMS and pseudo)
Host Bus Adapter (HBA) drivers
STREAMS modules
TCP/IP stack modules
file systems
exec modules
system calls
miscellaneous modules, such as modules containing code for support routines shared among multiple loadable modules which are not needed in the statically configured kernel

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

are not linked to the kernel until they are needed
must be configured into the system and registered with the running kernel using the idbuild(ADM) command with the -M option before they can be loaded
must be configured in loadable form (requires writing additional module initialization or ``wrapper'' code)
can be loaded and unloaded by the user, as required, using the modadmin command, or by init(ADM), during every system reboot, using the idmodload(ADM) command (called a demand load/unload)
can be loaded and unloaded by the kernel itself (called an auto load/unload--see ``Notices'' section)

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:

module identifier (modid)
the module's pathname
the module's virtual load address
amount of memory the module occupies
the module's reference count
the module's dependent count
the module's unload delay value
the module's descriptive name
the type of module
depending on the type of module, either the module's character major number, block major number, file system switch number, or STREAMS switch number

-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:

for all subsequent demand loads initiated by a modadmin command with the option -l and a named modname
for all subsequent loads performed by the kernel's auto-load mechanism (see ``Notices'' section)
prior to searching any directories already prepended to the search path by a prior modadmin command with the option -d
prior to searching the default search path /etc/conf/mod.d, which is always searched, and is always searched last

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:

must be demand loaded by the user via the modadmin command, or (during system reboot) demand loaded by init via the idmodload command
can not be auto loaded
can not be unloaded (demand or auto)

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(ADM), idmodload(ADM), idtune(ADM), init(ADM), modload(S), moduload(S), modpath(S), modstat(S), prf(HW)