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 performed.
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 an array of modstat_t structures, one
per loaded module. 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
consider 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 proplib dictionary larger than this size will return
ENOMEM
.
The
modstat_t structure used with
MODCTL_STAT
contains the following elements, which are
filled in by the kernel:
-
-
- char
ms_name[MAXMODNAME]
- The name of the module.
-
-
- char
ms_required[MAXMODNAME * MAXMODDEPS]
- The list of modules required by this module as a
comma-delimited list of module names.
-
-
- 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 system.
-
-
- 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.
MODULE_CLASS_ANY
- Any module class.
-
-
- uint64_t
ms_addr
- The load address within the kernel.
-
-
- u_int
ms_size
- Loaded size of the module.
-
-
- 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 operating
system.
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.