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