MODCTL(2)

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, 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.

December 14, 2010 | NetBSD 5.99