]>
Commit | Line | Data |
---|---|---|
f4008050 | 1 | .\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com> |
c4d4162c | 2 | .\" |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
f4008050 MK |
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. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
c4d4162c | 24 | .\" |
4b8c67d9 | 25 | .TH DELETE_MODULE 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
c4d4162c | 26 | .SH NAME |
460240ca | 27 | delete_module \- unload a kernel module |
c4d4162c MK |
28 | .SH SYNOPSIS |
29 | .nf | |
460240ca | 30 | .BI "int delete_module(const char *" name ", int " flags ); |
c4d4162c | 31 | .fi |
dbfe9c70 | 32 | .PP |
460240ca | 33 | .IR Note : |
90493c8c | 34 | No declaration of this system call is provided in glibc headers; see NOTES. |
c4d4162c | 35 | .SH DESCRIPTION |
b4f49502 | 36 | The |
c4d4162c | 37 | .BR delete_module () |
b4f49502 | 38 | system call attempts to remove the unused loadable module entry |
460240ca MK |
39 | identified by |
40 | .IR name . | |
b4f49502 MK |
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. | |
c4d4162c | 48 | This system call requires privilege. |
efeece04 | 49 | .PP |
b4f49502 MK |
50 | Module removal is attempted according to the following rules: |
51 | .IP 1. 4 | |
460240ca MK |
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. | |
b4f49502 MK |
55 | .IP 2. |
56 | Otherwise, if the reference count for the module | |
3d1ee497 | 57 | (i.e., the number of processes currently using the module) |
b4f49502 MK |
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 | |
efeece04 | 70 | .IP |
b4f49502 MK |
71 | The various combinations for |
72 | .I flags | |
73 | have the following effect: | |
74 | .RS 4 | |
460240ca | 75 | .TP |
b4f49502 MK |
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 | |
0cb430a1 | 83 | .B (flags & O_NONBLOCK) == 0 |
b4f49502 MK |
84 | If |
85 | .I flags | |
86 | does not specify | |
87 | .BR O_NONBLOCK , | |
88 | the following steps occur: | |
460240ca MK |
89 | .RS |
90 | .IP * 3 | |
b4f49502 | 91 | The module is marked so that no new references are permitted. |
460240ca | 92 | .IP * |
b4f49502 MK |
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. | |
460240ca | 99 | .RE |
b4f49502 MK |
100 | .RE |
101 | .PP | |
102 | The | |
103 | .B O_TRUNC | |
104 | flag has one further effect on the rules described above. | |
35f69680 | 105 | By default, if a module has an |
b4f49502 MK |
106 | .I init |
107 | function but no | |
fa1d2749 | 108 | .I exit |
26cd31fd | 109 | function, then an attempt to remove the module fails. |
b4f49502 MK |
110 | However, if |
111 | .BR O_TRUNC | |
112 | was specified, this requirement is bypassed. | |
113 | .PP | |
fa1d2749 | 114 | Using the |
b4f49502 MK |
115 | .B O_TRUNC |
116 | flag is dangerous! | |
460240ca MK |
117 | If the kernel was not built with |
118 | .BR CONFIG_MODULE_FORCE_UNLOAD , | |
119 | this flag is silently ignored. | |
e64bdfcf | 120 | (Normally, |
b4f49502 MK |
121 | .BR CONFIG_MODULE_FORCE_UNLOAD |
122 | is enabled.) | |
123 | Using this flag taints the kernel (TAINT_FORCED_RMMOD). | |
47297adb | 124 | .SH RETURN VALUE |
c13182ef MK |
125 | On success, zero is returned. |
126 | On error, \-1 is returned and | |
c4d4162c MK |
127 | .I errno |
128 | is set appropriately. | |
129 | .SH ERRORS | |
130 | .TP | |
131 | .B EBUSY | |
460240ca MK |
132 | The module is not "live" |
133 | (i.e., it is still being initialized or is already marked for removal); | |
b4f49502 MK |
134 | or, the module has |
135 | an | |
136 | .I init | |
137 | function but has no | |
460240ca | 138 | .I exit |
b4f49502 | 139 | function, and |
460240ca MK |
140 | .B O_TRUNC |
141 | was not specified in | |
142 | .IR flags . | |
c4d4162c MK |
143 | .TP |
144 | .B EFAULT | |
145 | .I name | |
b4f49502 | 146 | refers to a location outside the process's accessible address space. |
c4d4162c MK |
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 | |
460240ca MK |
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 , | |
fa1d2749 | 168 | but the reference count of this module is nonzero and |
460240ca MK |
169 | .B O_TRUNC |
170 | was not specified in | |
171 | .IR flags . | |
47297adb | 172 | .SH CONFORMING TO |
c4d4162c | 173 | .BR delete_module () |
8382f16d | 174 | is Linux-specific. |
460240ca | 175 | .SH NOTES |
4a9c7a5e MK |
176 | The |
177 | .BR delete_module () | |
0b13a3d6 | 178 | system call is not supported by glibc. |
fa3b5cee MK |
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. | |
4a9c7a5e | 181 | Therefore, in order to employ this system call, |
fa3b5cee MK |
182 | it is (before glibc 2.23) sufficient to |
183 | manually declare the interface in your code; | |
4a9c7a5e | 184 | alternatively, you can invoke the system call using |
460240ca | 185 | .BR syscall (2). |
efeece04 | 186 | .PP |
b2fc8e9f | 187 | The uninterruptible sleep that may occur if |
b4f49502 MK |
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. | |
460240ca MK |
196 | .SS Linux 2.4 and earlier |
197 | In Linux 2.4 and earlier, the system call took only one argument: | |
efeece04 | 198 | .PP |
460240ca | 199 | .BI " int delete_module(const char *" name ); |
efeece04 | 200 | .PP |
460240ca MK |
201 | If |
202 | .I name | |
203 | is NULL, all unused modules marked auto-clean are removed. | |
efeece04 | 204 | .PP |
460240ca MK |
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. | |
47297adb | 210 | .SH SEE ALSO |
c4d4162c MK |
211 | .BR create_module (2), |
212 | .BR init_module (2), | |
98038e98 | 213 | .BR query_module (2), |
b4f49502 | 214 | .BR lsmod (8), |
eceb82f7 | 215 | .BR modprobe (8), |
98038e98 | 216 | .BR rmmod (8) |