kcmodule(1M) kcmodule(1M)
NAME [Toc] [Back]
kcmodule - manage kernel modules and subsystems
SYNOPSIS [Toc] [Back]
kcmodule [-adhvBDKS] [-c config] [-C comment] [-P fields]
[module[=[unused|static|loaded| auto|best|uninstall]]]
DESCRIPTION [Toc] [Back]
kcmodule is the administrative command for HP-UX kernel modules. It
gives information about kernel modules and their usage, and makes
changes to their usage.
This command can work with any saved kernel configuration, or with the
currently running kernel configuration, depending on the use of the -c
flag (see below). By default, changes to the currently running kernel
configuration are applied immediately. Some changes cannot be applied
without a reboot; if any such changes are requested, or the -h flag is
given, all changes on the kcmodule command line will be held until
next boot.
Super-user permissions are required when making changes to module
usage.
Options [Toc] [Back]
-a Include all modules in the output listing. Normally only
"interesting" modules are listed: required modules and
container (library) modules are omitted, as are multiple
versions of a module. Not valid in combination with -D
or -S.
-B Forces a backup of the currently running configuration
before making the requested change. For more information
on backup configurations, see kconfig(5). Not valid in
combination with -c.
-c config Tells kcmodule to view or change the saved kernel
configuration named config. If this option is not
specified, kcmodule views or changes the currently
running kernel configuration.
See kconfig(5) for more information on saved kernel
configurations.
-C comment The specified comment will be included in the kernel
configuration log file entry made for this invocation of
kcmodule. For more details on the kernel configuration
log file, see kclog(1M). Note that it will usually be
necessary to quote the comment in order to avoid
interpretation by the shell.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: Sep 2004
kcmodule(1M) kcmodule(1M)
-d Adds the description of each module to the output.
-D Restricts the output to only those modules that have a
state change being held for next reboot. kcmodule will
return 1 if there are any such modules; see RETURN VALUE
below. Not valid in combination with -a, -c, or -S.
-h Changes will be held until next boot, even if they could
be applied immediately. Not valid in combination with -
c.
-K Prevents a backup of the currently running configuration
before making the requested change. For more information
on backup configurations, see kconfig(5). Not valid in
combination with -c.
-P fields Tells kcmodule to include only the specified fields in
its output, and to print them in the machine-readable
form described in kconfig(5). See the Developers Note,
below. Not valid in combination with -d or -v.
-S Only modules in non-default states are included in the
output. In other words, the listing includes only
optional modules that are in use by explicit request. It
does not include unused modules, required modules, or
modules that were automatically selected to resolve
dependencies. Not valid in combination with -a or -D.
-v Print verbose information about each module. The
information includes the name, version and state of the
module, its allowed states and its dependencies on other
modules and interfaces. Not valid in combination with -d
or -P.
Arguments [Toc] [Back]
The arguments to kcmodule may be any mixture of module state queries
and assignments. The arguments must each take one of the forms listed
below. No spaces are permitted within each argument. If no arguments
are given, kcmodule performs a query on all modules (subject to the
constraints of the -a, -D, or -S flags).
module The state of the module will be reported. No change is
made.
module= The module will be put into its best state.
module=state The module will be put into the specified state. The
possible states are:
unused The module is not used in any way.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: Sep 2004
kcmodule(1M) kcmodule(1M)
static The module is statically bound into the
kernel executable.
auto The module will be dynamically loaded into
the kernel when something tries to use it.
loaded The module is dynamically loaded into the
kernel.
best The module will be put into the state
identified by the kernel module developer as
its "best" state. Typically this will be
auto, if supported by the module, otherwise
loaded, if supported by the module, otherwise
static. Note that a module in best state
will inherit any changes that HP makes to the
"best" state for a module, in a patch or a
future release of HP-UX.
uninstall The module will be put into the unused state.
In addition, all of the module's tunable
settings and other associated configuration
data will be purged from the configuration.
This state should be specified only when a
module is being physically removed from the
system.
Some modules do not support all of the possible states. To see which
states a module supports, run kcmodule -v modulename.
Moving modules into or out of the static state requires a kernel
relink, so such changes cannot be applied without a system reboot.
Other module state changes may also require a system reboot, depending
on the nature of the specified module.
Moving a module from loaded to auto has no effect on the currently
running system; the module remains loaded. It will be autoloaded on
first use after future reboots.
Developer's Note
The layout and content of kcmodule's output may change without notice,
except when -P fields is specified. Scripts or applications that need
to parse the output of kcmodule are expected to use the -P fields
option. See kconfig(5) for details.
The fields supported in a kcmodule request are:
name The name of the module.
alias This field will produce a line in the output for
each alternate name for the module. (There may be
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: Sep 2004
kcmodule(1M) kcmodule(1M)
zero such lines.)
desc A short description of the module.
version The version number of the module, if it has one;
otherwise, this field will be omitted from the
output.
state The state of the module. The states are listed in
the table under -s, above.
cause This field indicates how the module got into its
current state. It will have one of the following
values:
explicit The module was explicitly put in its
current state by the administrator.
auto The module was put in auto state by
the administrator. An attempt was
made to use the module, so it has been
automatically loaded.
depend The module inherited its state from
another module that depends on it.
required The module is in use because it is
marked required.
best The module is in this state because it
is the "best" state for this module as
specified by the module developer.
next_state The state of the module at next boot. This field
is present only if -c is not specified.
next_cause This field indicates how the module was given its
state for next boot. It has the same values as
cause, above. This field is present only if -c is
not specified.
before_state The state of the module before the current change.
This field is present only for modules for which
an immediate value change has been made during the
current invocation of kcmodule.
before_cause The cause of the module state before the current
change. This field is present only for modules
for which an immediate value change has been made
during the current invocation of kcmodule.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: Sep 2004
kcmodule(1M) kcmodule(1M)
capable This field will contain a space-separated list of
the states that this module can support. The
states are listed in the table under "Arguments",
above.
depend This field will produce a line in the output for
each dependency this module has on another module
or interface. (There may be zero such lines.)
Each line has the form:
depend type name:version
where type is either interface or module,
indicating the type of object; name is the name of
the interface or module; and version is the
version number of the interface or module on which
this module depends.
exports This field will produce a line in the output for
each interface exported by this module. (There
may be zero such lines.) Each line will contain
the interfacename:interfaceversion of an interface
exported by this module.
The special field name ALL may be specified to indicate that all
defined fields should be included in the output. The output may
include fields not listed in this man page. The fields will be listed
in unspecified order.
Additional fields may be added in future releases or patches.
Default Output [Toc] [Back]
When kcmodule is called with no options, it shows the optional kernel
modules on the system, their current state, the cause for including it
in the configuration and special capabilities if any. If there are
changes that are being held for nextboot, they will be shown as well.
The cause field will be empty for all modules that are not included in
the configuration. The special capabilities of kernel modules would
be one of:
loadable The module can be dynamically changed to the state
loaded.
unloadable The module can be dynamically changed to the state
unused.
auto-loadable The module supports the state auto.
The layout and content of the default output may change in future
releases or patches of HP-UX. Scripts or applications which need to
parse the output of kcmodule must use the -P option for parsable
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: Sep 2004
kcmodule(1M) kcmodule(1M)
output.
RETURN VALUE [Toc] [Back]
kcmodule returns one of the following values:
0 kcmodule was successful. If -D was specified, this return value
indicates that there are no module state changes being held for
next boot.
1 kcmodule was successful. However, there were changes requested
to the currently running system which cannot be applied until the
system reboots. Therefore, all of the requested changes are
being held until next boot.
If -D was specified, this return value indicates that there are
module state changes being held for next boot.
2 kcmodule was not successful.
EXAMPLES [Toc] [Back]
To see all optional modules and their current states:
$ kcmodule
To see all modules, including required modules, and their current states:
$ kcmodule -a
To see verbose information about a module:
$ kcmodule -v module
To load a dynamic module:
$ kcmodule module=loaded
To unload a dynamic module immediately:
$ kcmodule module=unused
To stop using a module when the system reboots:
$ kcmodule -h module=unused
To bind a module into the static kernel:
$ kcmodule module=static
SEE ALSO [Toc] [Back]
kclog(1M), kconfig(5), Managing Kernel Configurations White Paper
available on http://www.hp.com/products1/unix/operating/infolibrary.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: Sep 2004 [ Back ] |
