|
MODCTL(2) |
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, or
MODCTL_STAT. 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.
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.
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.
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.
-
[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.
HISTORY
The modctl() function call first appeared in NetBSD 5.0.