kcmodule(1M)

NAME

kcmodule — manage kernel modules and subsystems

SYNOPSIS

kcmodule [-adhvDS] [-b behavior] [-c config] [-C comment] [-P fields]

[module[=[unused|static|loaded|auto|best]]] ...

DESCRIPTION

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.

Only users with appropriate privileges can make changes to module usage.

Options

-a

Include all modules in the output listing. Normally only "interesting" modules are listed: required modules and multiple versions of modules are omitted. Not valid in combination with -D or -S.

-b behavior

Specifies whether or not to update the automatic backup configuration before the requested change. Also specifies the default backup behavior for future changes. See kconfig(5) for a description of the various backup behaviors. Not valid in combination with -c.

For compatibility with old releases, -B is accepted as an alias for -b yes, and -K is accepted as an alias for -b no. These aliases will be removed in a future release.

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

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

-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

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

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 zero such lines.)

desc

A short description of the module.

version

The version number of the module.

timestamp

The modification timestamp of the module file.

state

The state of the module. The states are listed in the table under Arguments, 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.

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

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 to get output that can be parsed.

RETURN VALUE

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

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 