Debian Codegraph @

upstream/debian-unstable/man2/init_module.2

raw
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)