HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |NOTES |SEE ALSO |COLOPHON | |
init_module(2) System Calls Manualinit_module(2)init_module, finit_module - load a kernel module
Standard C library (libc,-lc)
#include <linux/module.h>/* Definition ofMODULE_*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>int syscall(unsigned long size;SYS_init_module, voidmodule_image[size], unsigned longsize,const char *param_values);int syscall(SYS_finit_module, intfd,const char *param_values, intflags);Note: glibc provides no wrappers for these system calls, necessitating the use ofsyscall(2).
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'sinit function. This system call requires privilege. Themodule_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. Theparam_values argument is a string containing space-delimited specifications of the values for module parameters (defined inside the module usingmodule_param() andmodule_param_array()). The kernel parses this string and initializes the specified parameters. Each of the parameter specifications has the form:name[=value[,value...]] The parametername is one of those defined within the module usingmodule_param() (see the Linux kernel source fileinclude/linux/moduleparam.h). The parametervalue is optional in the case ofbool andinvbool parameters. Values for array parameters are specified as a comma-separated list.finit_module() Thefinit_module() system call is likeinit_module(), but reads the module to be loaded from the file descriptorfd. 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. Theparam_values argument is as forinit_module(). Theflags argument modifies the operation offinit_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 theCONFIG_MODVERSIONSconfiguration 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 theMODULE_INIT_IGNORE_VERMAGICflag indicates that the "vermagic" string is to be ignored, and theMODULE_INIT_IGNORE_MODVERSIONSflag indicates that the symbol version hashes are to be ignored. If the kernel is built to permit forced loading (i.e., configured withCONFIG_MODULE_FORCE_LOAD), then loading continues, otherwise it fails with the errorENOEXECas expected for malformed modules. If the kernel was build withCONFIG_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 tofinit_module() using theMODULE_INIT_COMPRESSED_FILEflag. 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.
On success, these system calls return 0. On error, -1 is returned anderrno is set to indicate the error.
EBADMSG(since Linux 3.7) Module signature is misformatted.EBUSYTimeout while trying to resolve a symbol reference by this module.EFAULTAn 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 withCONFIG_MODULE_SIG_FORCE; if the kernel was not configured with this option, then an invalid or unsigned module simply taints the kernel.ENOMEMOut of memory.EPERMThe caller was not privileged (did not have theCAP_SYS_MODULEcapability), or module loading is disabled (see/proc/sys/kernel/modules_disabled inproc(5)). The following errors may additionally occur forinit_module():EEXISTA module with this name is already loaded.EINVALparam_values is invalid, or some part of the ELF image inmodule_image contains inconsistencies.ENOEXEC The binary image supplied inmodule_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 forfinit_module():EBADFThe file referred to byfd is not opened for reading.EFBIGThe file referred to byfd is too large.EINVALflags is invalid.EINVALThe decompressor sanity checks failed, while loading a compressed module with flagMODULE_INIT_COMPRESSED_FILE set.ENOEXECfd does not refer to an open file.EOPNOTSUPP(since Linux 5.17) The flagMODULE_INIT_COMPRESSED_FILEis set to load a compressed module, and the kernel was built withoutCONFIG_MODULE_DECOMPRESS.ETXTBSY(since Linux 4.7) The file referred to byfd is opened for read-write. In addition to the above errors, if the module'sinit function is executed and returns an error, theninit_module() orfinit_module() fails anderrno is set to the value returned by theinit function.
Linux.
finit_module() Linux 3.8. Theinit_module() system call is not supported by glibc. No declaration is provided in glibc headers, but, through a quirk of history, glibc versions before glibc 2.23 did export an ABI for this system call. Therefore, in order to employ this system call, it is (before glibc 2.23) sufficient to manually declare the interface in your code; alternatively, you can invoke the system call usingsyscall(2).Linux 2.4 and earlier In Linux 2.4 and earlier, theinit_module() system call was rather different:#include <linux/module.h>int init_module(const char *name, struct module *image); (User-space applications can detect which version ofinit_module() is available by callingquery_module(); the latter call fails with the errorENOSYSon Linux 2.6 and later.) The older version of the system call loads the relocated module image pointed to byimage into kernel space and runs the module'sinit function. The caller is responsible for providing the relocated image (since Linux 2.6, theinit_module() system call does the relocation). The module image begins with a module structure and is followed by code and data as appropriate. Since Linux 2.2, the module structure is defined as follows: struct module { unsigned long size_of_struct; struct module *next; const char *name; unsigned long size; long usecount; unsigned long flags; unsigned int nsyms; unsigned int ndeps; struct module_symbol *syms; struct module_ref *deps; struct module_ref *refs; typeof(int (void)) *init; typeof(void (void)) *cleanup; const struct exception_table_entry *ex_table_start; const struct exception_table_entry *ex_table_end; #ifdef __alpha__ unsigned long gp; #endif }; All of the pointer fields, with the exception ofnext andrefs, are expected to point within the module body and be initialized as appropriate for kernel space, that is, relocated with the rest of the module.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 fileinclude/linux/module.h for some useful background information.
create_module(2),delete_module(2),query_module(2),lsmod(8),modprobe(8)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-06-28init_module(2)Pages that refer to this page:create_module(2), delete_module(2), get_kernel_syms(2), query_module(2), syscalls(2), unimplemented(2), systemd.exec(5), capabilities(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |