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:
-
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(1M)
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(1M),
during every system reboot,
using the
idmodload(1M)
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(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