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