]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com> | |
2 | .\" | |
3 | .\" %%%LICENSE_START(VERBATIM) | |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" %%%LICENSE_END | |
24 | .\" | |
25 | .TH DELETE_MODULE 2 2017-09-15 "Linux" "Linux Programmer's Manual" | |
26 | .SH NAME | |
27 | delete_module \- unload a kernel module | |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .BI "int delete_module(const char *" name ", int " flags ); | |
31 | .fi | |
32 | .PP | |
33 | .IR Note : | |
34 | No declaration of this system call is provided in glibc headers; see NOTES. | |
35 | .SH DESCRIPTION | |
36 | The | |
37 | .BR delete_module () | |
38 | system call attempts to remove the unused loadable module entry | |
39 | identified by | |
40 | .IR name . | |
41 | If the module has an | |
42 | .I exit | |
43 | function, then that function is executed before unloading the module. | |
44 | The | |
45 | .IR flags | |
46 | argument is used to modify the behavior of the system call, | |
47 | as described below. | |
48 | This system call requires privilege. | |
49 | .PP | |
50 | Module removal is attempted according to the following rules: | |
51 | .IP 1. 4 | |
52 | If there are other loaded modules that depend on | |
53 | (i.e., refer to symbols defined in) this module, | |
54 | then the call fails. | |
55 | .IP 2. | |
56 | Otherwise, if the reference count for the module | |
57 | (i.e., the number of processes currently using the module) | |
58 | is zero, then the module is immediately unloaded. | |
59 | .IP 3. | |
60 | If a module has a nonzero reference count, | |
61 | then the behavior depends on the bits set in | |
62 | .IR flags . | |
63 | In normal usage (see NOTES), the | |
64 | .BR O_NONBLOCK | |
65 | flag is always specified, and the | |
66 | .BR O_TRUNC | |
67 | flag may additionally be specified. | |
68 | .\" O_TRUNC == KMOD_REMOVE_FORCE in kmod library | |
69 | .\" O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library | |
70 | .IP | |
71 | The various combinations for | |
72 | .I flags | |
73 | have the following effect: | |
74 | .RS 4 | |
75 | .TP | |
76 | .B flags == O_NONBLOCK | |
77 | The call returns immediately, with an error. | |
78 | .TP | |
79 | .B flags == (O_NONBLOCK | O_TRUNC) | |
80 | The module is unloaded immediately, | |
81 | regardless of whether it has a nonzero reference count. | |
82 | .TP | |
83 | .B (flags & O_NONBLOCK) == 0 | |
84 | If | |
85 | .I flags | |
86 | does not specify | |
87 | .BR O_NONBLOCK , | |
88 | the following steps occur: | |
89 | .RS | |
90 | .IP * 3 | |
91 | The module is marked so that no new references are permitted. | |
92 | .IP * | |
93 | If the module's reference count is nonzero, | |
94 | the caller is placed in an uninterruptible sleep state | |
95 | .RB ( TASK_UNINTERRUPTIBLE ) | |
96 | until the reference count is zero, at which point the call unblocks. | |
97 | .IP * | |
98 | The module is unloaded in the usual way. | |
99 | .RE | |
100 | .RE | |
101 | .PP | |
102 | The | |
103 | .B O_TRUNC | |
104 | flag has one further effect on the rules described above. | |
105 | By default, if a module has an | |
106 | .I init | |
107 | function but no | |
108 | .I exit | |
109 | function, then an attempt to remove the module fails. | |
110 | However, if | |
111 | .BR O_TRUNC | |
112 | was specified, this requirement is bypassed. | |
113 | .PP | |
114 | Using the | |
115 | .B O_TRUNC | |
116 | flag is dangerous! | |
117 | If the kernel was not built with | |
118 | .BR CONFIG_MODULE_FORCE_UNLOAD , | |
119 | this flag is silently ignored. | |
120 | (Normally, | |
121 | .BR CONFIG_MODULE_FORCE_UNLOAD | |
122 | is enabled.) | |
123 | Using this flag taints the kernel (TAINT_FORCED_RMMOD). | |
124 | .SH RETURN VALUE | |
125 | On success, zero is returned. | |
126 | On error, \-1 is returned and | |
127 | .I errno | |
128 | is set appropriately. | |
129 | .SH ERRORS | |
130 | .TP | |
131 | .B EBUSY | |
132 | The module is not "live" | |
133 | (i.e., it is still being initialized or is already marked for removal); | |
134 | or, the module has | |
135 | an | |
136 | .I init | |
137 | function but has no | |
138 | .I exit | |
139 | function, and | |
140 | .B O_TRUNC | |
141 | was not specified in | |
142 | .IR flags . | |
143 | .TP | |
144 | .B EFAULT | |
145 | .I name | |
146 | refers to a location outside the process's accessible address space. | |
147 | .TP | |
148 | .B ENOENT | |
149 | No module by that name exists. | |
150 | .TP | |
151 | .B EPERM | |
152 | The caller was not privileged | |
153 | (did not have the | |
154 | .B CAP_SYS_MODULE | |
155 | capability), | |
156 | or module unloading is disabled | |
157 | (see | |
158 | .IR /proc/sys/kernel/modules_disabled | |
159 | in | |
160 | .BR proc (5)). | |
161 | .TP | |
162 | .B EWOULDBLOCK | |
163 | Other modules depend on this module; | |
164 | or, | |
165 | .BR O_NONBLOCK | |
166 | was specified in | |
167 | .IR flags , | |
168 | but the reference count of this module is nonzero and | |
169 | .B O_TRUNC | |
170 | was not specified in | |
171 | .IR flags . | |
172 | .SH CONFORMING TO | |
173 | .BR delete_module () | |
174 | is Linux-specific. | |
175 | .SH NOTES | |
176 | The | |
177 | .BR delete_module () | |
178 | system call is not supported by glibc. | |
179 | No declaration is provided in glibc headers, but, through a quirk of history, | |
180 | glibc versions before 2.23 did export an ABI for this system call. | |
181 | Therefore, in order to employ this system call, | |
182 | it is (before glibc 2.23) sufficient to | |
183 | manually declare the interface in your code; | |
184 | alternatively, you can invoke the system call using | |
185 | .BR syscall (2). | |
186 | .PP | |
187 | The uninterruptible sleep that may occur if | |
188 | .BR O_NONBLOCK | |
189 | is omitted from | |
190 | .IR flags | |
191 | is considered undesirable, because the sleeping process is left | |
192 | in an unkillable state. | |
193 | As at Linux 3.7, specifying | |
194 | .BR O_NONBLOCK | |
195 | is optional, but in future kernels it is likely to become mandatory. | |
196 | .SS Linux 2.4 and earlier | |
197 | In Linux 2.4 and earlier, the system call took only one argument: | |
198 | .PP | |
199 | .BI " int delete_module(const char *" name ); | |
200 | .PP | |
201 | If | |
202 | .I name | |
203 | is NULL, all unused modules marked auto-clean are removed. | |
204 | .PP | |
205 | Some further details of differences in the behavior of | |
206 | .BR delete_module () | |
207 | in Linux 2.4 and earlier are | |
208 | .I not | |
209 | currently explained in this manual page. | |
210 | .SH SEE ALSO | |
211 | .BR create_module (2), | |
212 | .BR init_module (2), | |
213 | .BR query_module (2), | |
214 | .BR lsmod (8), | |
215 | .BR modprobe (8), | |
216 | .BR rmmod (8) |