modctl(2)
- NetBSD Manual Pages
MODCTL(2) NetBSD System Calls Manual MODCTL(2)
NAME
modctl -- module control
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/module.h>
int
modctl(int operation, void *argp);
DESCRIPTION
modctl() provides control over loaded kernel modules. The argument
operation is one of MODCTL_LOAD, MODCTL_UNLOAD, MODCTL_STAT, or
MODCTL_EXISTS. The argument argp depends on the operation to be per-
formed.
Operations are:
MODCTL_LOAD Load a module. The argp argument should be a pointer to a
modctl_load_t structure, described below.
MODCTL_UNLOAD Unload a module. In this case, argp should be a string
containing the name of the module to be unloaded.
MODCTL_STAT Return a list of loaded modules. In this case, the argp
argument should be a struct iovec pointing to a suitable
block of memory. The kernel will fill this block with
· a count of the number of modules loaded (including
aliases),
· an array of modstat_t structures, one per loaded mod-
ule, and
· a series of NUL-terminated strings containing the mod-
ules' required modules lists.
If the block is not large enough, the data returned will
be truncated to fit. The kernel will then update the
iov_len member of the iovec to reflect the size of the
complete report, regardless of whether this is larger or
smaller than the size passed in.
MODCTL_EXISTS Test to see if the kernel was compiled with ``options
MODULAR'' and whether or not modules may be loaded at the
moment. In this case, argp should be an integer. It
should be ``0'' to test if a user can load a module via
MODCTL_LOAD, or it should be ``1'' to test if the system
can autoload modules. Note that this test does not con-
sider the sysctl kern.module.autoload.
Data Types
The modctl_load_t structure used with MODCTL_LOAD contains the following
elements, which should be filled in by the caller:
const char *ml_filename
The name/path of the module to load.
int ml_flags
Zero or more of the following flag values:
MODCTL_NO_PROP Don't load <module>.plist.
MODCTL_LOAD_FORCE Ignore kernel version mismatch.
const char *ml_props
Externalized proplib dictionary to pass to module.
size_t ml_propslen
Size of the dictionary blob. ml_props may be NULL in which
case ml_propslen must be 0. An upper limit of 4096 bytes is
imposed on the value of ml_propslen. Attempting to load a pro-
plib dictionary larger than this size will return ENOMEM.
The modstat_t structure used with MODCTL_STAT contains the following ele-
ments, which are filled in by the kernel:
char ms_name[MAXMODNAME]
The name of the module.
modsrc_t ms_source
One of the following enumerated constants:
MODULE_SOURCE_KERNEL The module is compiled into the kernel.
MODULE_SOURCE_BOOT The module was provided by the bootstrap
loader.
MODULE_SOURCE_FILESYS The module was loaded from the file sys-
tem.
modclass_t ms_class
One of the following enumerated constants:
MODULE_CLASS_SECMODEL Security model.
MODULE_CLASS_VFS File system.
MODULE_CLASS_DRIVER Device driver.
MODULE_CLASS_EXEC Executable file format.
MODULE_CLASS_MISC Miscellaneous.
uint64_t ms_addr
The load address within the kernel. (This value is available
only for privileged users.)
u_int ms_size
Loaded size of the module's text section. (This value is
available only for privileged users.)
u_int ms_refcnt
Current number of live references to this module.
u_int ms_flags
The module's flags:
MODFLAG_MUST_FORCE The "force" flag must be specified to
reload this module.
MODFLAG_AUTO_LOADED The module was auto-loaded by the operat-
ing system.
uint_ms_reqoffset
The offset (in bytes) from the beginning of the required-module
data.
RETURN VALUES
Upon successful completion, the value returned is 0.
Otherwise, a value of -1 is returned and errno is set to indicate the
error.
ERRORS
modctl() will fail if:
[EBUSY] The argument operation is MODCTL_UNLOAD and the module
is in use or the module is compiled into the kernel.
[EDEADLK] The argument operation is MODCTL_LOAD and there is a
circular dependency in the module's dependency chain.
[EEXIST] The argument operation is MODCTL_LOAD and the module
is already loaded.
[EFAULT] A bad address was given for argp.
[EFBIG] The argument operation is MODCTL_LOAD, the specified
module resides in the file system, and the module's
default proplib file was too large.
[EINVAL] The argument operation is invalid.
The argument operation is MODCTL_LOAD and ml_props is
not NULL and ``ml_propslen'' is 0, or ml_props is NULL
and ``ml_propslen'' is not 0. The kernel is unable to
internalize the plist. Or, there is a problem with
the module or <module>.plist.
[EMLINK] The argument operation is MODCTL_LOAD and the module
has too many dependencies.
[ENAMETOOLONG] A module name/path is too long.
[ENOENT] The argument operation is MODCTL_LOAD and the module
or a dependency can't be found.
The argument operation is MODCTL_UNLOAD and no module
by the name of argp is loaded.
[ENOEXEC] The argument operation is MODCTL_LOAD and the module
is not a valid object for the system. Most likely,
one or more undefined symbols could not be resolved by
the in-kernel linker.
[ENOMEM] There was not enough memory to perform the operation.
[EPERM] Not allowed to perform the operation.
[EPROGMISMATCH] The argument operation is MODCTL_LOAD, the ml_flags
field in the modctl_load_t structure does not include
MODCTL_LOAD_FORCE, and the requested module does not
match the current kernel's version information.
SEE ALSO
module(7), sysctl(7), module(9)
HISTORY
The modctl() function call first appeared in NetBSD 5.0.
NetBSD 9.4_STABLE December 4, 2019 NetBSD 9.4_STABLE
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.