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