| 1 |
.\" Copyright 1996, Free Software Foundation, Inc. |
| 2 |
.\" Copyright 2012, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH init_module 2 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
init_module, finit_module \- load a kernel module |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.BR "#include <linux/module.h>" " /* Definition of " MODULE_* " constants */" |
| 16 |
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
| 17 |
.B #include <unistd.h> |
| 18 |
.P |
| 19 |
.BR "int syscall(" "unsigned long size;" |
| 20 |
.B " SYS_init_module," |
| 21 |
.BI " void " module_image [ size "], unsigned long " size , |
| 22 |
.BI " const char *" param_values ); |
| 23 |
.BI "int syscall(SYS_finit_module, int " fd , |
| 24 |
.BI " const char *" param_values ", int " flags ); |
| 25 |
.fi |
| 26 |
.P |
| 27 |
.IR Note : |
| 28 |
glibc provides no wrappers for these system calls, |
| 29 |
necessitating the use of |
| 30 |
.BR syscall (2). |
| 31 |
.SH DESCRIPTION |
| 32 |
.BR init_module () |
| 33 |
loads an ELF image into kernel space, |
| 34 |
performs any necessary symbol relocations, |
| 35 |
initializes module parameters to values provided by the caller, |
| 36 |
and then runs the module's |
| 37 |
.I init |
| 38 |
function. |
| 39 |
This system call requires privilege. |
| 40 |
.P |
| 41 |
The |
| 42 |
.I module_image |
| 43 |
argument points to a buffer containing the binary image |
| 44 |
to be loaded; |
| 45 |
.I size |
| 46 |
specifies the size of that buffer. |
| 47 |
The module image should be a valid ELF image, built for the running kernel. |
| 48 |
.P |
| 49 |
The |
| 50 |
.I param_values |
| 51 |
argument is a string containing space-delimited specifications of the |
| 52 |
values for module parameters (defined inside the module using |
| 53 |
.BR module_param () |
| 54 |
and |
| 55 |
.BR module_param_array ()). |
| 56 |
The kernel parses this string and initializes the specified |
| 57 |
parameters. |
| 58 |
Each of the parameter specifications has the form: |
| 59 |
.P |
| 60 |
.RI " " name [\c |
| 61 |
.BI = value\c |
| 62 |
.RB [ ,\c |
| 63 |
.IR value ...]] |
| 64 |
.P |
| 65 |
The parameter |
| 66 |
.I name |
| 67 |
is one of those defined within the module using |
| 68 |
.IR module_param () |
| 69 |
(see the Linux kernel source file |
| 70 |
.IR include/linux/moduleparam.h ). |
| 71 |
The parameter |
| 72 |
.I value |
| 73 |
is optional in the case of |
| 74 |
.I bool |
| 75 |
and |
| 76 |
.I invbool |
| 77 |
parameters. |
| 78 |
Values for array parameters are specified as a comma-separated list. |
| 79 |
.SS finit_module() |
| 80 |
The |
| 81 |
.BR finit_module () |
| 82 |
.\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2 |
| 83 |
.\" https://lwn.net/Articles/519010/ |
| 84 |
system call is like |
| 85 |
.BR init_module (), |
| 86 |
but reads the module to be loaded from the file descriptor |
| 87 |
.IR fd . |
| 88 |
It is useful when the authenticity of a kernel module |
| 89 |
can be determined from its location in the filesystem; |
| 90 |
in cases where that is possible, |
| 91 |
the overhead of using cryptographically signed modules to |
| 92 |
determine the authenticity of a module can be avoided. |
| 93 |
The |
| 94 |
.I param_values |
| 95 |
argument is as for |
| 96 |
.BR init_module (). |
| 97 |
.P |
| 98 |
The |
| 99 |
.I flags |
| 100 |
argument modifies the operation of |
| 101 |
.BR finit_module (). |
| 102 |
It is a bit mask value created by ORing |
| 103 |
together zero or more of the following flags: |
| 104 |
.\" commit 2f3238aebedb243804f58d62d57244edec4149b2 |
| 105 |
.TP |
| 106 |
.B MODULE_INIT_IGNORE_MODVERSIONS |
| 107 |
Ignore symbol version hashes. |
| 108 |
.TP |
| 109 |
.B MODULE_INIT_IGNORE_VERMAGIC |
| 110 |
Ignore kernel version magic. |
| 111 |
.TP |
| 112 |
.BR MODULE_INIT_COMPRESSED_FILE " (since Linux 5.17)" |
| 113 |
.\" commit b1ae6dc41eaaa98bb75671e0f3665bfda248c3e7 |
| 114 |
Use in-kernel module decompression. |
| 115 |
.P |
| 116 |
There are some safety checks built into a module to ensure that |
| 117 |
it matches the kernel against which it is loaded. |
| 118 |
.\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html |
| 119 |
.\" is dated, but informative |
| 120 |
These checks are recorded when the module is built and |
| 121 |
verified when the module is loaded. |
| 122 |
First, the module records a "vermagic" string containing |
| 123 |
the kernel version number and prominent features (such as the CPU type). |
| 124 |
Second, if the module was built with the |
| 125 |
.B CONFIG_MODVERSIONS |
| 126 |
configuration option enabled, |
| 127 |
a version hash is recorded for each symbol the module uses. |
| 128 |
This hash is based on the types of the arguments and return value |
| 129 |
for the function named by the symbol. |
| 130 |
In this case, the kernel version number within the |
| 131 |
"vermagic" string is ignored, |
| 132 |
as the symbol version hashes are assumed to be sufficiently reliable. |
| 133 |
.P |
| 134 |
Using the |
| 135 |
.B MODULE_INIT_IGNORE_VERMAGIC |
| 136 |
flag indicates that the "vermagic" string is to be ignored, and the |
| 137 |
.B MODULE_INIT_IGNORE_MODVERSIONS |
| 138 |
flag indicates that the symbol version hashes are to be ignored. |
| 139 |
If the kernel is built to permit forced loading (i.e., configured with |
| 140 |
.BR CONFIG_MODULE_FORCE_LOAD ), |
| 141 |
then loading continues, otherwise it fails with the error |
| 142 |
.B ENOEXEC |
| 143 |
as expected for malformed modules. |
| 144 |
.P |
| 145 |
If the kernel was build with |
| 146 |
.BR CONFIG_MODULE_DECOMPRESS , |
| 147 |
the in-kernel decompression feature can be used. |
| 148 |
User-space code can check if the kernel supports decompression |
| 149 |
by reading the |
| 150 |
.I /sys/module/compression |
| 151 |
attribute. |
| 152 |
If the kernel supports decompression, |
| 153 |
the compressed file can directly be passed to |
| 154 |
.BR finit_module () |
| 155 |
using the |
| 156 |
.B MODULE_INIT_COMPRESSED_FILE |
| 157 |
flag. |
| 158 |
The in-kernel module decompressor supports the following compression algorithms: |
| 159 |
.P |
| 160 |
.RS 4 |
| 161 |
.PD 0 |
| 162 |
.IP \[bu] 3 |
| 163 |
.I gzip |
| 164 |
(since Linux 5.17) |
| 165 |
.IP \[bu] |
| 166 |
.I xz |
| 167 |
(since Linux 5.17) |
| 168 |
.IP \[bu] |
| 169 |
.I zstd |
| 170 |
.\" commit 169a58ad824d896b9e291a27193342616e651b82 |
| 171 |
(since Linux 6.2) |
| 172 |
.PD |
| 173 |
.RE |
| 174 |
.P |
| 175 |
The kernel only implements a single decompression method. |
| 176 |
This is selected during module generation accordingly to the compression method |
| 177 |
chosen in the kernel configuration. |
| 178 |
.SH RETURN VALUE |
| 179 |
On success, these system calls return 0. |
| 180 |
On error, \-1 is returned and |
| 181 |
.I errno |
| 182 |
is set to indicate the error. |
| 183 |
.SH ERRORS |
| 184 |
.TP |
| 185 |
.BR EBADMSG " (since Linux 3.7)" |
| 186 |
Module signature is misformatted. |
| 187 |
.TP |
| 188 |
.B EBUSY |
| 189 |
Timeout while trying to resolve a symbol reference by this module. |
| 190 |
.TP |
| 191 |
.B EFAULT |
| 192 |
An address argument referred to a location that |
| 193 |
is outside the process's accessible address space. |
| 194 |
.TP |
| 195 |
.BR ENOKEY " (since Linux 3.7)" |
| 196 |
.\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1 |
| 197 |
.\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa |
| 198 |
.\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7 |
| 199 |
Module signature is invalid or |
| 200 |
the kernel does not have a key for this module. |
| 201 |
This error is returned only if the kernel was configured with |
| 202 |
.BR CONFIG_MODULE_SIG_FORCE ; |
| 203 |
if the kernel was not configured with this option, |
| 204 |
then an invalid or unsigned module simply taints the kernel. |
| 205 |
.TP |
| 206 |
.B ENOMEM |
| 207 |
Out of memory. |
| 208 |
.TP |
| 209 |
.B EPERM |
| 210 |
The caller was not privileged |
| 211 |
(did not have the |
| 212 |
.B CAP_SYS_MODULE |
| 213 |
capability), |
| 214 |
or module loading is disabled |
| 215 |
(see |
| 216 |
.I /proc/sys/kernel/modules_disabled |
| 217 |
in |
| 218 |
.BR proc (5)). |
| 219 |
.P |
| 220 |
The following errors may additionally occur for |
| 221 |
.BR init_module (): |
| 222 |
.TP |
| 223 |
.B EEXIST |
| 224 |
A module with this name is already loaded. |
| 225 |
.TP |
| 226 |
.B EINVAL |
| 227 |
.I param_values |
| 228 |
is invalid, or some part of the ELF image in |
| 229 |
.I module_image |
| 230 |
contains inconsistencies. |
| 231 |
.\" .TP |
| 232 |
.\" .BR EINVAL " (Linux 2.4 and earlier)" |
| 233 |
.\" Some |
| 234 |
.\" .I image |
| 235 |
.\" slot is filled in incorrectly, |
| 236 |
.\" .I image\->name |
| 237 |
.\" does not correspond to the original module name, some |
| 238 |
.\" .I image\->deps |
| 239 |
.\" entry does not correspond to a loaded module, |
| 240 |
.\" or some other similar inconsistency. |
| 241 |
.TP |
| 242 |
.B ENOEXEC |
| 243 |
The binary image supplied in |
| 244 |
.I module_image |
| 245 |
is not an ELF image, |
| 246 |
or is an ELF image that is invalid or for a different architecture. |
| 247 |
.P |
| 248 |
The following errors may additionally occur for |
| 249 |
.BR finit_module (): |
| 250 |
.TP |
| 251 |
.B EBADF |
| 252 |
The file referred to by |
| 253 |
.I fd |
| 254 |
is not opened for reading. |
| 255 |
.TP |
| 256 |
.B EFBIG |
| 257 |
The file referred to by |
| 258 |
.I fd |
| 259 |
is too large. |
| 260 |
.TP |
| 261 |
.B EINVAL |
| 262 |
.I flags |
| 263 |
is invalid. |
| 264 |
.TP |
| 265 |
.B EINVAL |
| 266 |
The decompressor sanity checks failed, |
| 267 |
while loading a compressed module with flag |
| 268 |
.B MODULE_INIT_COMPRESSED_FILE |
| 269 |
set. |
| 270 |
.TP |
| 271 |
.B ENOEXEC |
| 272 |
.I fd |
| 273 |
does not refer to an open file. |
| 274 |
.TP |
| 275 |
.BR EOPNOTSUPP " (since Linux 5.17)" |
| 276 |
The flag |
| 277 |
.B MODULE_INIT_COMPRESSED_FILE |
| 278 |
is set to load a compressed module, |
| 279 |
and the kernel was built without |
| 280 |
.BR CONFIG_MODULE_DECOMPRESS . |
| 281 |
.TP |
| 282 |
.BR ETXTBSY " (since Linux 4.7)" |
| 283 |
.\" commit 39d637af5aa7577f655c58b9e55587566c63a0af |
| 284 |
The file referred to by |
| 285 |
.I fd |
| 286 |
is opened for read-write. |
| 287 |
.P |
| 288 |
In addition to the above errors, if the module's |
| 289 |
.I init |
| 290 |
function is executed and returns an error, then |
| 291 |
.BR init_module () |
| 292 |
or |
| 293 |
.BR finit_module () |
| 294 |
fails and |
| 295 |
.I errno |
| 296 |
is set to the value returned by the |
| 297 |
.I init |
| 298 |
function. |
| 299 |
.SH STANDARDS |
| 300 |
Linux. |
| 301 |
.SH HISTORY |
| 302 |
.TP |
| 303 |
.BR finit_module () |
| 304 |
Linux 3.8. |
| 305 |
.P |
| 306 |
The |
| 307 |
.BR init_module () |
| 308 |
system call is not supported by glibc. |
| 309 |
No declaration is provided in glibc headers, but, through a quirk of history, |
| 310 |
glibc versions before glibc 2.23 did export an ABI for this system call. |
| 311 |
Therefore, in order to employ this system call, |
| 312 |
it is (before glibc 2.23) sufficient to |
| 313 |
manually declare the interface in your code; |
| 314 |
alternatively, you can invoke the system call using |
| 315 |
.BR syscall (2). |
| 316 |
.SS Linux 2.4 and earlier |
| 317 |
In Linux 2.4 and earlier, the |
| 318 |
.BR init_module () |
| 319 |
system call was rather different: |
| 320 |
.P |
| 321 |
.B " #include <linux/module.h>" |
| 322 |
.P |
| 323 |
.BI " int init_module(const char *" name ", struct module *" image ); |
| 324 |
.P |
| 325 |
(User-space applications can detect which version of |
| 326 |
.BR init_module () |
| 327 |
is available by calling |
| 328 |
.BR query_module (); |
| 329 |
the latter call fails with the error |
| 330 |
.B ENOSYS |
| 331 |
on Linux 2.6 and later.) |
| 332 |
.P |
| 333 |
The older version of the system call |
| 334 |
loads the relocated module image pointed to by |
| 335 |
.I image |
| 336 |
into kernel space and runs the module's |
| 337 |
.I init |
| 338 |
function. |
| 339 |
The caller is responsible for providing the relocated image (since |
| 340 |
Linux 2.6, the |
| 341 |
.BR init_module () |
| 342 |
system call does the relocation). |
| 343 |
.P |
| 344 |
The module image begins with a module structure and is followed by |
| 345 |
code and data as appropriate. |
| 346 |
Since Linux 2.2, the module structure is defined as follows: |
| 347 |
.P |
| 348 |
.in +4n |
| 349 |
.EX |
| 350 |
struct module { |
| 351 |
unsigned long size_of_struct; |
| 352 |
struct module *next; |
| 353 |
const char *name; |
| 354 |
unsigned long size; |
| 355 |
long usecount; |
| 356 |
unsigned long flags; |
| 357 |
unsigned int nsyms; |
| 358 |
unsigned int ndeps; |
| 359 |
struct module_symbol *syms; |
| 360 |
struct module_ref *deps; |
| 361 |
struct module_ref *refs; |
| 362 |
typeof(int (void)) *init; |
| 363 |
typeof(void (void)) *cleanup; |
| 364 |
const struct exception_table_entry *ex_table_start; |
| 365 |
const struct exception_table_entry *ex_table_end; |
| 366 |
#ifdef __alpha__ |
| 367 |
unsigned long gp; |
| 368 |
#endif |
| 369 |
}; |
| 370 |
.EE |
| 371 |
.in |
| 372 |
.P |
| 373 |
All of the pointer fields, with the exception of |
| 374 |
.I next |
| 375 |
and |
| 376 |
.IR refs , |
| 377 |
are expected to point within the module body and be |
| 378 |
initialized as appropriate for kernel space, that is, relocated with |
| 379 |
the rest of the module. |
| 380 |
.SH NOTES |
| 381 |
Information about currently loaded modules can be found in |
| 382 |
.I /proc/modules |
| 383 |
and in the file trees under the per-module subdirectories under |
| 384 |
.IR /sys/module . |
| 385 |
.P |
| 386 |
See the Linux kernel source file |
| 387 |
.I include/linux/module.h |
| 388 |
for some useful background information. |
| 389 |
.SH SEE ALSO |
| 390 |
.BR create_module (2), |
| 391 |
.BR delete_module (2), |
| 392 |
.BR query_module (2), |
| 393 |
.BR lsmod (8), |
| 394 |
.BR modprobe (8) |