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 2013-01-07 "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 There are no glibc wrappers for these system calls; see NOTES.
43 loads an ELF image into kernel space,
44 performs any necessary symbol relocations,
45 initializes module parameters to values provided by the caller,
46 and then runs the module's
49 This system call requires privilege.
53 argument points to a buffer containing the binary image
56 specifies the size of that buffer.
57 The module image should be a valid ELF image, built for the running kernel.
61 argument is a string containing space-delimited specifications of the
62 values for module parameters (defined inside the module using
65 .BR module_param_array ()).
66 The kernel parses this string and initializes the specified
68 Each of the parameter specifications has the form:
77 is one of those defined within the module using
79 (see the Linux kernel source file
80 .IR include/linux/moduleparam.h ).
83 is optional in the case of
88 Values for array parameters are specified as a comma-separated list.
92 .\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2
93 .\" https://lwn.net/Articles/519010/
96 but reads the module to be loaded from the file descriptor
98 It is useful when the authenticity of a kernel module
99 can be determined from its location in the file system;
100 in cases where that is possible,
101 the overhead of using cryptographically signed modules to
102 determine the authenticity of a module can be avoided.
110 argument modifies the operation of
112 It is a bit mask value created by ORing
113 together zero or more of the following flags:
114 .\" commit 2f3238aebedb243804f58d62d57244edec4149b2
116 .B MODULE_INIT_IGNORE_MODVERSIONS
117 Ignore symbol version hashes.
119 .B MODULE_INIT_IGNORE_VERMAGIC
120 Ignore kernel version magic.
122 There are some safety checks built into a module to ensure that
123 it matches the kernel against which it is loaded.
124 .\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html
125 .\" is dated, but informative
126 These checks are recorded when the module is built and
127 verified when the module is loaded.
128 First, the module records a "vermagic" string containing
129 the kernel version number and prominent features (such as the CPU type).
130 Second, if the module was built with the
131 .B CONFIG_MODVERSIONS
132 configuration option enabled,
133 a version hash is recorded for each symbol the module uses.
134 This hash is based on the types of the arguments and return value
135 for the function named by the symbol.
136 In this case, the kernel version number within the
137 "vermagic" string is ignored,
138 as the symbol version hashes are assumed to be sufficiently reliable.
141 .B MODULE_INIT_IGNORE_VERMAGIC
142 flag indicates that the "vermagic" string is to be ignored, and the
143 .B MODULE_INIT_IGNORE_MODVERSIONS
144 flag indicates that the symbol version hashes are to be ignored.
145 If the kernel is built to permit forced loading (i.e., configured with
146 .BR CONFIG_MODULE_FORCE_LOAD ),
147 then loading will continue, otherwise it will fail with
149 as expected for malformed modules.
151 On success, these system calls return 0.
152 On error, \-1 is returned and
154 is set appropriately.
157 .BR EBADMSG " (since Linux 3.7)"
158 Module signature is misformatted.
161 Timeout while trying to resolve a symbol reference by this module.
164 An address argument referred to a location that
165 is outside the process's accessible address space.
167 .BR ENOKEY " (since Linux 3.7)"
168 .\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1
169 .\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa
170 .\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7
171 Module signature is invalid or
172 the kernel does not have a key for this module.
173 This error is returned only if the kernel was configured with
174 .BR CONFIG_MODULE_SIG_FORCE ;
175 if the kernel was not configured with this option,
176 then an invalid or unsigned module simply taints the kernel.
182 The caller was not privileged
186 or module loading is disabled
188 .IR /proc/sys/kernel/modules_disabled
192 The following errors may additionally occur for
196 A module with this name is already loaded.
200 is invalid, or some part of the ELF image in
202 contains inconsistencies.
204 .\" .BR EINVAL " (Linux 2.4 and earlier)"
207 .\" slot is filled in incorrectly,
209 .\" does not correspond to the original module name, some
211 .\" entry does not correspond to a loaded module,
212 .\" or some other similar inconsistency.
215 The binary image supplied in
218 or is an ELF image that is invalid or for a different architecture.
220 The following errors may additionally occur for
224 The file referred to by
226 is not opened for reading.
229 The file referred to by
239 does not refer to an open file.
241 In addition to the above errors, if the module's
243 function is executed and returns an error, then
249 is set to the value returned by the
254 is available since Linux 3.8.
261 Glibc does not provide a wrapper for these system calls; call them using
264 Information about currently loaded modules can be found in
266 and in the file trees under the per-module subdirectories under
269 See the Linux kernel source file
270 .I include/linux/module.h
271 for some useful background information.
272 .SS Linux 2.4 and earlier
274 In Linux 2.4 and earlier, the
276 system call was rather different:
278 .B " #include <linux/module.h>"
280 .BI " int init_module(const char *" name ", struct module *" image );
282 (User-space applications can detect which version of
284 is available by calling
286 the latter call fails with the error
288 on Linux 2.6 and later.)
290 The older version of the system call
291 loads the relocated module image pointed to by
293 into kernel space and runs the module's
296 The caller is responsible for providing the relocated image (since
299 system call does the relocation).
301 The module image begins with a module structure and is followed by
302 code and data as appropriate.
303 Since Linux 2.2, the module structure is defined as follows:
308 unsigned long size_of_struct;
316 struct module_symbol *syms;
317 struct module_ref *deps;
318 struct module_ref *refs;
320 void (*cleanup)(void);
321 const struct exception_table_entry *ex_table_start;
322 const struct exception_table_entry *ex_table_end;
330 All of the pointer fields, with the exception of
334 are expected to point within the module body and be
335 initialized as appropriate for kernel space, that is, relocated with
336 the rest of the module.
338 .BR create_module (2),
339 .BR delete_module (2),
340 .BR query_module (2),