MODCTL(2)

NAME
modctl - module control

LIBRARY
libc

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.

SEE ALSO
module(7), module(9)

HISTORY
The modctl() function call first appeared in NetBSD 5.0.