Debian Codegraph @

upstream/debian-trixie/man2/init_module.2

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