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-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.