# init_module

## NAME



           init_module, finit_module - load a kernel module
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <linux/module.h>    **/* Definition of **MODULE_*** constants */
           **#include <sys/syscall.h>     **/* Definition of **SYS_*** constants */
           **#include <unistd.h>**
    
           **int syscall(** unsigned long size;
                       **SYS_init_module, void** _module_image_**[**_size_**], unsigned long** _size_**,**
                       **const char ***_param_values_**);**
           **int syscall(SYS_finit_module, int** _fd_**,**
                       **const char ***_param_values_**, int** _flags_**);**
    
           _Note_ : glibc provides no wrappers for these system calls,
           necessitating the use of syscall(2).
    


## DESCRIPTION



           **init_module**() loads an ELF image into kernel space, performs any
           necessary symbol relocations, initializes module parameters to
           values provided by the caller, and then runs the module's _init_
           function.  This system call requires privilege.
    
           The _module_image_ argument points to a buffer containing the binary
           image to be loaded; _size_ specifies the size of that buffer.  The
           module image should be a valid ELF image, built for the running
           kernel.
    
           The _param_values_ argument is a string containing space-delimited
           specifications of the values for module parameters (defined inside
           the module using **module_param**() and **module_param_array**()).  The
           kernel parses this string and initializes the specified
           parameters.  Each of the parameter specifications has the form:
    
                   _name_[**=**_value_[**,**_value_...]]
    
           The parameter _name_ is one of those defined within the module using
           _module_param_() (see the Linux kernel source file
           _include/linux/moduleparam.h_).  The parameter _value_ is optional in
           the case of _bool_ and _invbool_ parameters.  Values for array
           parameters are specified as a comma-separated list.
    
       **finit_module()**
           The **finit_module**() system call is like **init_module**(), but reads
           the module to be loaded from the file descriptor _fd_.  It is useful
           when the authenticity of a kernel module can be determined from
           its location in the filesystem; in cases where that is possible,
           the overhead of using cryptographically signed modules to
           determine the authenticity of a module can be avoided.  The
           _param_values_ argument is as for **init_module**().
    
           The _flags_ argument modifies the operation of **finit_module**().  It
           is a bit mask value created by ORing together zero or more of the
           following flags:
    
           **MODULE_INIT_IGNORE_MODVERSIONS**
                  Ignore symbol version hashes.
    
           **MODULE_INIT_IGNORE_VERMAGIC**
                  Ignore kernel version magic.
    
           **MODULE_INIT_COMPRESSED_FILE**(since Linux 5.17)
                  Use in-kernel module decompression.
    
           There are some safety checks built into a module to ensure that it
           matches the kernel against which it is loaded.  These checks are
           recorded when the module is built and verified when the module is
           loaded.  First, the module records a "vermagic" string containing
           the kernel version number and prominent features (such as the CPU
           type).  Second, if the module was built with the
           **CONFIG_MODVERSIONS** configuration option enabled, a version hash is
           recorded for each symbol the module uses.  This hash is based on
           the types of the arguments and return value for the function named
           by the symbol.  In this case, the kernel version number within the
           "vermagic" string is ignored, as the symbol version hashes are
           assumed to be sufficiently reliable.
    
           Using the **MODULE_INIT_IGNORE_VERMAGIC** flag indicates that the
           "vermagic" string is to be ignored, and the
           **MODULE_INIT_IGNORE_MODVERSIONS** flag indicates that the symbol
           version hashes are to be ignored.  If the kernel is built to
           permit forced loading (i.e., configured with
           **CONFIG_MODULE_FORCE_LOAD**), then loading continues, otherwise it
           fails with the error **ENOEXEC** as expected for malformed modules.
    
           If the kernel was build with **CONFIG_MODULE_DECOMPRESS** , the in-
           kernel decompression feature can be used.  User-space code can
           check if the kernel supports decompression by reading the
           _/sys/module/compression_ attribute.  If the kernel supports
           decompression, the compressed file can directly be passed to
           **finit_module**() using the **MODULE_INIT_COMPRESSED_FILE** flag.  The
           in-kernel module decompressor supports the following compression
           algorithms:
    
               •  _gzip_ (since Linux 5.17)
               •  _xz_ (since Linux 5.17)
               •  _zstd_ (since Linux 6.2)
    
           The kernel only implements a single decompression method.  This is
           selected during module generation accordingly to the compression
           method chosen in the kernel configuration.
    


## RETURN VALUE



           On success, these system calls return 0.  On error, -1 is returned
           and _errno_ is set to indicate the error.
    


## ERRORS



           **EBADMSG**(since Linux 3.7)
                  Module signature is misformatted.
    
           **EBUSY** Timeout while trying to resolve a symbol reference by this
                  module.
    
           **EFAULT** An address argument referred to a location that is outside
                  the process's accessible address space.
    
           **ENOKEY**(since Linux 3.7)
                  Module signature is invalid or the kernel does not have a
                  key for this module.  This error is returned only if the
                  kernel was configured with **CONFIG_MODULE_SIG_FORCE** ; if the
                  kernel was not configured with this option, then an invalid
                  or unsigned module simply taints the kernel.
    
           **ENOMEM** Out of memory.
    
           **EPERM** The caller was not privileged (did not have the
                  **CAP_SYS_MODULE** capability), or module loading is disabled
                  (see _/proc/sys/kernel/modules_disabled_ in proc(5)).
    
           The following errors may additionally occur for **init_module**():
    
           **EEXIST** A module with this name is already loaded.
    
           **EINVAL** _param_values_ is invalid, or some part of the ELF image in
                  _module_image_ contains inconsistencies.
    
           **ENOEXEC**
                  The binary image supplied in _module_image_ is not an ELF
                  image, or is an ELF image that is invalid or for a
                  different architecture.
    
           The following errors may additionally occur for **finit_module**():
    
           **EBADF** The file referred to by _fd_ is not opened for reading.
    
           **EFBIG** The file referred to by _fd_ is too large.
    
           **EINVAL** _flags_ is invalid.
    
           **EINVAL** The decompressor sanity checks failed, while loading a
                  compressed module with flag **MODULE_INIT_COMPRESSED_FILE**
                  set.
    
           **ENOEXEC**
                  _fd_ does not refer to an open file.
    
           **EOPNOTSUPP**(since Linux 5.17)
                  The flag **MODULE_INIT_COMPRESSED_FILE** is set to load a
                  compressed module, and the kernel was built without
                  **CONFIG_MODULE_DECOMPRESS**.
    
           **ETXTBSY**(since Linux 4.7)
                  The file referred to by _fd_ is opened for read-write.
    
           In addition to the above errors, if the module's _init_ function is
           executed and returns an error, then **init_module**() or
           **finit_module**() fails and _errno_ is set to the value returned by the
           _init_ function.
    


## STANDARDS



           Linux.
    


## NOTES



           Information about currently loaded modules can be found in
           _/proc/modules_ and in the file trees under the per-module
           subdirectories under _/sys/module_.
    
           See the Linux kernel source file _include/linux/module.h_ for some
           useful background information.
    


* * *