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.
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.
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.
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
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .TH INIT_MODULE 2 2017-09-15 "Linux" "Linux Programmer's Manual"
29 init_module, finit_module \- load a kernel module
32 .BI "int init_module(void *" module_image ", unsigned long " len ,
33 .BI " const char *" param_values );
35 .BI "int finit_module(int " fd ", const char *" param_values ,
40 glibc provides no header file declaration of
42 and no wrapper function for
47 loads an ELF image into kernel space,
48 performs any necessary symbol relocations,
49 initializes module parameters to values provided by the caller,
50 and then runs the module's
53 This system call requires privilege.
57 argument points to a buffer containing the binary image
60 specifies the size of that buffer.
61 The module image should be a valid ELF image, built for the running kernel.
65 argument is a string containing space-delimited specifications of the
66 values for module parameters (defined inside the module using
69 .BR module_param_array ()).
70 The kernel parses this string and initializes the specified
72 Each of the parameter specifications has the form:
81 is one of those defined within the module using
83 (see the Linux kernel source file
84 .IR include/linux/moduleparam.h ).
87 is optional in the case of
92 Values for array parameters are specified as a comma-separated list.
96 .\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2
97 .\" https://lwn.net/Articles/519010/
100 but reads the module to be loaded from the file descriptor
102 It is useful when the authenticity of a kernel module
103 can be determined from its location in the filesystem;
104 in cases where that is possible,
105 the overhead of using cryptographically signed modules to
106 determine the authenticity of a module can be avoided.
114 argument modifies the operation of
116 It is a bit mask value created by ORing
117 together zero or more of the following flags:
118 .\" commit 2f3238aebedb243804f58d62d57244edec4149b2
120 .B MODULE_INIT_IGNORE_MODVERSIONS
121 Ignore symbol version hashes.
123 .B MODULE_INIT_IGNORE_VERMAGIC
124 Ignore kernel version magic.
126 There are some safety checks built into a module to ensure that
127 it matches the kernel against which it is loaded.
128 .\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html
129 .\" is dated, but informative
130 These checks are recorded when the module is built and
131 verified when the module is loaded.
132 First, the module records a "vermagic" string containing
133 the kernel version number and prominent features (such as the CPU type).
134 Second, if the module was built with the
135 .B CONFIG_MODVERSIONS
136 configuration option enabled,
137 a version hash is recorded for each symbol the module uses.
138 This hash is based on the types of the arguments and return value
139 for the function named by the symbol.
140 In this case, the kernel version number within the
141 "vermagic" string is ignored,
142 as the symbol version hashes are assumed to be sufficiently reliable.
145 .B MODULE_INIT_IGNORE_VERMAGIC
146 flag indicates that the "vermagic" string is to be ignored, and the
147 .B MODULE_INIT_IGNORE_MODVERSIONS
148 flag indicates that the symbol version hashes are to be ignored.
149 If the kernel is built to permit forced loading (i.e., configured with
150 .BR CONFIG_MODULE_FORCE_LOAD ),
151 then loading continues, otherwise it fails with the error
153 as expected for malformed modules.
155 On success, these system calls return 0.
156 On error, \-1 is returned and
158 is set appropriately.
161 .BR EBADMSG " (since Linux 3.7)"
162 Module signature is misformatted.
165 Timeout while trying to resolve a symbol reference by this module.
168 An address argument referred to a location that
169 is outside the process's accessible address space.
171 .BR ENOKEY " (since Linux 3.7)"
172 .\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1
173 .\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa
174 .\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7
175 Module signature is invalid or
176 the kernel does not have a key for this module.
177 This error is returned only if the kernel was configured with
178 .BR CONFIG_MODULE_SIG_FORCE ;
179 if the kernel was not configured with this option,
180 then an invalid or unsigned module simply taints the kernel.
186 The caller was not privileged
190 or module loading is disabled
192 .IR /proc/sys/kernel/modules_disabled
196 The following errors may additionally occur for
200 A module with this name is already loaded.
204 is invalid, or some part of the ELF image in
206 contains inconsistencies.
208 .\" .BR EINVAL " (Linux 2.4 and earlier)"
211 .\" slot is filled in incorrectly,
213 .\" does not correspond to the original module name, some
215 .\" entry does not correspond to a loaded module,
216 .\" or some other similar inconsistency.
219 The binary image supplied in
222 or is an ELF image that is invalid or for a different architecture.
224 The following errors may additionally occur for
228 The file referred to by
230 is not opened for reading.
233 The file referred to by
243 does not refer to an open file.
245 In addition to the above errors, if the module's
247 function is executed and returns an error, then
253 is set to the value returned by the
258 is available since Linux 3.8.
267 system call is not supported by glibc.
268 No declaration is provided in glibc headers, but, through a quirk of history,
269 glibc versions before 2.23 did export an ABI for this system call.
270 Therefore, in order to employ this system call,
271 it is (before glibc 2.23) sufficient to
272 manually declare the interface in your code;
273 alternatively, you can invoke the system call using
276 Glibc does not provide a wrapper for
281 Information about currently loaded modules can be found in
283 and in the file trees under the per-module subdirectories under
286 See the Linux kernel source file
287 .I include/linux/module.h
288 for some useful background information.
289 .SS Linux 2.4 and earlier
291 In Linux 2.4 and earlier, the
293 system call was rather different:
295 .B " #include <linux/module.h>"
297 .BI " int init_module(const char *" name ", struct module *" image );
299 (User-space applications can detect which version of
301 is available by calling
303 the latter call fails with the error
305 on Linux 2.6 and later.)
307 The older version of the system call
308 loads the relocated module image pointed to by
310 into kernel space and runs the module's
313 The caller is responsible for providing the relocated image (since
316 system call does the relocation).
318 The module image begins with a module structure and is followed by
319 code and data as appropriate.
320 Since Linux 2.2, the module structure is defined as follows:
325 unsigned long size_of_struct;
333 struct module_symbol *syms;
334 struct module_ref *deps;
335 struct module_ref *refs;
337 void (*cleanup)(void);
338 const struct exception_table_entry *ex_table_start;
339 const struct exception_table_entry *ex_table_end;
347 All of the pointer fields, with the exception of
351 are expected to point within the module body and be
352 initialized as appropriate for kernel space, that is, relocated with
353 the rest of the module.
355 .BR create_module (2),
356 .BR delete_module (2),
357 .BR query_module (2),