]>
Commit | Line | Data |
---|---|---|
3371ab17 MK |
1 | .\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" A few fragments remain from a version | |
c4d4162c | 3 | .\" Copyright (C) 1996 Free Software Foundation, Inc. |
c4d4162c | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
3371ab17 MK |
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. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
c4d4162c | 26 | .\" |
726663fd | 27 | .TH INIT_MODULE 2 2014-05-10 "Linux" "Linux Programmer's Manual" |
c4d4162c | 28 | .SH NAME |
2038a83d | 29 | init_module, finit_module \- load a kernel module |
c4d4162c MK |
30 | .SH SYNOPSIS |
31 | .nf | |
fa1d2749 | 32 | .BI "int init_module(void *" module_image ", unsigned long " len , |
8f4d1a1c | 33 | .BI " const char *" param_values ); |
2038a83d MK |
34 | |
35 | .BI "int finit_module(int " fd ", const char *" param_values , | |
01eab330 | 36 | .BI " int " flags ); |
c4d4162c | 37 | .fi |
8f4d1a1c MK |
38 | |
39 | .IR Note : | |
4a9c7a5e MK |
40 | glibc provides no header file declaration of |
41 | .BR init_module () | |
42 | and no wrapper function for | |
43 | .BR finit_module (); | |
44 | see NOTES. | |
c4d4162c MK |
45 | .SH DESCRIPTION |
46 | .BR init_module () | |
ce123e8e KC |
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 | |
c4d4162c MK |
51 | .I init |
52 | function. | |
8f4d1a1c MK |
53 | This system call requires privilege. |
54 | ||
55 | The | |
56 | .I module_image | |
57 | argument points to a buffer containing the binary image | |
58 | to be loaded; | |
59 | .I len | |
60 | specifies the size of that buffer. | |
ce123e8e | 61 | The module image should be a valid ELF image, built for the running kernel. |
8f4d1a1c MK |
62 | |
63 | The | |
64 | .I param_values | |
65 | argument is a string containing space-delimited specifications of the | |
0cb430a1 MK |
66 | values for module parameters (defined inside the module using |
67 | .BR module_param () | |
68 | and | |
69 | .BR module_param_array ()). | |
ce123e8e | 70 | The kernel parses this string and initializes the specified |
0cb430a1 | 71 | parameters. |
ce123e8e | 72 | Each of the parameter specifications has the form: |
8f4d1a1c | 73 | |
8321eae5 DP |
74 | .RI " " name [\c |
75 | .BI = value\c | |
76 | .RB [ ,\c | |
77 | .IR value ...]] | |
8f4d1a1c | 78 | |
8321eae5 DP |
79 | The parameter |
80 | .I name | |
81 | is one of those defined within the module using | |
8f4d1a1c MK |
82 | .IR module_param () |
83 | (see the Linux kernel source file | |
84 | .IR include/linux/moduleparam.h ). | |
8321eae5 DP |
85 | The parameter |
86 | .I value | |
87 | is optional in the case of | |
8f4d1a1c MK |
88 | .I bool |
89 | and | |
90 | .I invbool | |
91 | parameters. | |
92 | Values for array parameters are specified as a comma-separated list. | |
2038a83d MK |
93 | .SS finit_module() |
94 | The | |
95 | .BR finit_module () | |
96 | .\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2 | |
97 | .\" https://lwn.net/Articles/519010/ | |
98 | system call is like | |
99 | .BR init_module (), | |
100 | but reads the module to be loaded from the file descriptor | |
101 | .IR fd . | |
102 | It is useful when the authenticity of a kernel module | |
9ee4a2b6 | 103 | can be determined from its location in the filesystem; |
2038a83d MK |
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. | |
107 | The | |
108 | .I param_values | |
109 | argument is as for | |
110 | .BR init_module (). | |
111 | ||
112 | The | |
113 | .I flags | |
114 | argument modifies the operation of | |
115 | .BR finit_module (). | |
116 | It is a bit mask value created by ORing | |
117 | together zero or more of the following flags: | |
118 | .\" commit 2f3238aebedb243804f58d62d57244edec4149b2 | |
119 | .TP | |
120 | .B MODULE_INIT_IGNORE_MODVERSIONS | |
98a683a7 | 121 | Ignore symbol version hashes. |
9f1b9726 | 122 | .TP |
2038a83d MK |
123 | .B MODULE_INIT_IGNORE_VERMAGIC |
124 | Ignore kernel version magic. | |
98a683a7 RR |
125 | .PP |
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. | |
143 | ||
144 | Using the | |
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 will continue, otherwise it will fail with | |
152 | .B ENOEXEC | |
153 | as expected for malformed modules. | |
47297adb | 154 | .SH RETURN VALUE |
2038a83d | 155 | On success, these system calls return 0. |
8f4d1a1c MK |
156 | On error, \-1 is returned and |
157 | .I errno | |
158 | is set appropriately. | |
159 | .SH ERRORS | |
160 | .TP | |
1428ae81 MK |
161 | .BR EBADMSG " (since Linux 3.7)" |
162 | Module signature is misformatted. | |
163 | .TP | |
8f4d1a1c | 164 | .B EBUSY |
0cb430a1 | 165 | Timeout while trying to resolve a symbol reference by this module. |
8f4d1a1c | 166 | .TP |
8f4d1a1c | 167 | .B EFAULT |
0cb430a1 | 168 | An address argument referred to a location that |
8f4d1a1c MK |
169 | is outside the process's accessible address space. |
170 | .TP | |
1428ae81 MK |
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, | |
bba1fa20 | 180 | then an invalid or unsigned module simply taints the kernel. |
1428ae81 | 181 | .TP |
2038a83d MK |
182 | .B ENOMEM |
183 | Out of memory. | |
184 | .TP | |
185 | .B EPERM | |
186 | The caller was not privileged | |
187 | (did not have the | |
188 | .B CAP_SYS_MODULE | |
189 | capability), | |
190 | or module loading is disabled | |
191 | (see | |
192 | .IR /proc/sys/kernel/modules_disabled | |
193 | in | |
194 | .BR proc (5)). | |
195 | .PP | |
196 | The following errors may additionally occur for | |
197 | .BR init_module (): | |
198 | .TP | |
199 | .B EEXIST | |
200 | A module with this name is already loaded. | |
201 | .TP | |
0cb430a1 | 202 | .B EINVAL |
8f4d1a1c | 203 | .I param_values |
ce123e8e KC |
204 | is invalid, or some part of the ELF image in |
205 | .IR module_image | |
206 | contains inconsistencies. | |
0cb430a1 MK |
207 | .\" .TP |
208 | .\" .BR EINVAL " (Linux 2.4 and earlier)" | |
209 | .\" Some | |
210 | .\" .I image | |
211 | .\" slot is filled in incorrectly, | |
212 | .\" .I image\->name | |
213 | .\" does not correspond to the original module name, some | |
214 | .\" .I image\->deps | |
215 | .\" entry does not correspond to a loaded module, | |
216 | .\" or some other similar inconsistency. | |
8f4d1a1c | 217 | .TP |
ce123e8e | 218 | .B ENOEXEC |
0cb430a1 | 219 | The binary image supplied in |
ce123e8e | 220 | .I module_image |
0cb430a1 MK |
221 | is not an ELF image, |
222 | or is an ELF image that is invalid or for a different architecture. | |
2038a83d MK |
223 | .PP |
224 | The following errors may additionally occur for | |
225 | .BR finit_module (): | |
ce123e8e | 226 | .TP |
2038a83d MK |
227 | .B EBADF |
228 | The file referred to by | |
229 | .I fd | |
230 | is not opened for reading. | |
231 | .TP | |
232 | .B EFBIG | |
233 | The file referred to by | |
234 | .I fd | |
235 | is too large. | |
236 | .TP | |
237 | .B EINVAL | |
238 | .I flags | |
239 | is invalid. | |
240 | .TP | |
241 | .B ENOEXEC | |
242 | .I fd | |
243 | does not refer to an open file. | |
0cb430a1 MK |
244 | .PP |
245 | In addition to the above errors, if the module's | |
246 | .I init | |
247 | function is executed and returns an error, then | |
248 | .BR init_module () | |
2038a83d MK |
249 | or |
250 | .BR finit_module () | |
0cb430a1 MK |
251 | fails and |
252 | .I errno | |
253 | is set to the value returned by the | |
254 | .I init | |
255 | function. | |
2038a83d | 256 | .SH VERSIONS |
0ae31c56 | 257 | .BR finit_module () |
2038a83d | 258 | is available since Linux 3.8. |
47297adb | 259 | .SH CONFORMING TO |
8f4d1a1c | 260 | .BR init_module () |
2038a83d MK |
261 | and |
262 | .BR finit_module () | |
263 | are Linux-specific. | |
8f4d1a1c | 264 | .SH NOTES |
4a9c7a5e MK |
265 | The |
266 | .BR init_module () | |
0b13a3d6 | 267 | system call is not supported by glibc. |
4a9c7a5e MK |
268 | No declaration is provided in glibc headers, but, |
269 | through a quirk of history, glibc does export an ABI for this system call. | |
270 | Therefore, in order to employ this system call, | |
271 | it is sufficient to manually declare the interface in your code; | |
272 | alternatively, you can invoke the system call using | |
273 | .BR syscall (2). | |
274 | ||
275 | Glibc does not provide a wrapper for | |
276 | .BR finit_module (); | |
277 | call it using | |
8f4d1a1c MK |
278 | .BR syscall (2). |
279 | ||
280 | Information about currently loaded modules can be found in | |
281 | .IR /proc/modules | |
282 | and in the file trees under the per-module subdirectories under | |
283 | .IR /sys/module . | |
284 | ||
285 | See the Linux kernel source file | |
286 | .I include/linux/module.h | |
287 | for some useful background information. | |
288 | .SS Linux 2.4 and earlier | |
289 | .PP | |
2038a83d MK |
290 | In Linux 2.4 and earlier, the |
291 | .BR init_module () | |
292 | system call was rather different: | |
8f4d1a1c MK |
293 | |
294 | .B " #include <linux/module.h>" | |
295 | ||
296 | .BI " int init_module(const char *" name ", struct module *" image ); | |
297 | ||
0cb430a1 MK |
298 | (User-space applications can detect which version of |
299 | .BR init_module () | |
300 | is available by calling | |
301 | .BR query_module (); | |
302 | the latter call fails with the error | |
303 | .BR ENOSYS | |
304 | on Linux 2.6 and later.) | |
305 | ||
306 | The older version of the system call | |
8f4d1a1c MK |
307 | loads the relocated module image pointed to by |
308 | .I image | |
309 | into kernel space and runs the module's | |
310 | .I init | |
311 | function. | |
312 | The caller is responsible for providing the relocated image (since | |
313 | Linux 2.6, the | |
314 | .BR init_module () | |
315 | system call does the relocation). | |
c4d4162c MK |
316 | .PP |
317 | The module image begins with a module structure and is followed by | |
318 | code and data as appropriate. | |
0cb430a1 | 319 | Since Linux 2.2, the module structure is defined as follows: |
c4d4162c | 320 | .PP |
a6e2f128 | 321 | .in +4n |
c4d4162c MK |
322 | .nf |
323 | struct module { | |
324 | unsigned long size_of_struct; | |
325 | struct module *next; | |
326 | const char *name; | |
327 | unsigned long size; | |
328 | long usecount; | |
329 | unsigned long flags; | |
330 | unsigned int nsyms; | |
331 | unsigned int ndeps; | |
332 | struct module_symbol *syms; | |
333 | struct module_ref *deps; | |
334 | struct module_ref *refs; | |
335 | int (*init)(void); | |
336 | void (*cleanup)(void); | |
337 | const struct exception_table_entry *ex_table_start; | |
338 | const struct exception_table_entry *ex_table_end; | |
339 | #ifdef __alpha__ | |
340 | unsigned long gp; | |
341 | #endif | |
342 | }; | |
343 | .fi | |
a6e2f128 | 344 | .in |
c4d4162c MK |
345 | .PP |
346 | All of the pointer fields, with the exception of | |
347 | .I next | |
348 | and | |
349 | .IR refs , | |
350 | are expected to point within the module body and be | |
75b94dc3 | 351 | initialized as appropriate for kernel space, that is, relocated with |
c4d4162c | 352 | the rest of the module. |
47297adb | 353 | .SH SEE ALSO |
c4d4162c MK |
354 | .BR create_module (2), |
355 | .BR delete_module (2), | |
8f4d1a1c | 356 | .BR query_module (2), |
0cb430a1 | 357 | .BR lsmod (8), |
8f4d1a1c | 358 | .BR modprobe (8) |