]>
Commit | Line | Data |
---|---|---|
f4008050 | 1 | .\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com> |
c4d4162c | 2 | .\" |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
c4d4162c | 4 | .\" |
4c1c5274 | 5 | .TH delete_module 2 (date) "Linux man-pages (unreleased)" |
c4d4162c | 6 | .SH NAME |
460240ca | 7 | delete_module \- unload a kernel module |
0bf0ca71 AC |
8 | .SH LIBRARY |
9 | Standard C library | |
8fc3b2cf | 10 | .RI ( libc ", " \-lc ) |
c4d4162c MK |
11 | .SH SYNOPSIS |
12 | .nf | |
43be8898 | 13 | .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" |
46950763 | 14 | .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
1ae6b2c7 | 15 | .B #include <unistd.h> |
43be8898 | 16 | .PP |
46950763 | 17 | .BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags ); |
c4d4162c | 18 | .fi |
bc2813df AC |
19 | .PP |
20 | .IR Note : | |
21 | glibc provides no wrapper for | |
22 | .BR delete_module (), | |
23 | necessitating the use of | |
24 | .BR syscall (2). | |
c4d4162c | 25 | .SH DESCRIPTION |
b4f49502 | 26 | The |
c4d4162c | 27 | .BR delete_module () |
b4f49502 | 28 | system call attempts to remove the unused loadable module entry |
460240ca MK |
29 | identified by |
30 | .IR name . | |
b4f49502 MK |
31 | If the module has an |
32 | .I exit | |
33 | function, then that function is executed before unloading the module. | |
34 | The | |
1ae6b2c7 | 35 | .I flags |
b4f49502 MK |
36 | argument is used to modify the behavior of the system call, |
37 | as described below. | |
c4d4162c | 38 | This system call requires privilege. |
efeece04 | 39 | .PP |
b4f49502 | 40 | Module removal is attempted according to the following rules: |
22356d97 | 41 | .IP (1) 5 |
460240ca MK |
42 | If there are other loaded modules that depend on |
43 | (i.e., refer to symbols defined in) this module, | |
44 | then the call fails. | |
22356d97 | 45 | .IP (2) |
b4f49502 | 46 | Otherwise, if the reference count for the module |
3d1ee497 | 47 | (i.e., the number of processes currently using the module) |
b4f49502 | 48 | is zero, then the module is immediately unloaded. |
22356d97 | 49 | .IP (3) |
b4f49502 MK |
50 | If a module has a nonzero reference count, |
51 | then the behavior depends on the bits set in | |
52 | .IR flags . | |
53 | In normal usage (see NOTES), the | |
1ae6b2c7 | 54 | .B O_NONBLOCK |
b4f49502 | 55 | flag is always specified, and the |
1ae6b2c7 | 56 | .B O_TRUNC |
b4f49502 MK |
57 | flag may additionally be specified. |
58 | .\" O_TRUNC == KMOD_REMOVE_FORCE in kmod library | |
59 | .\" O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library | |
efeece04 | 60 | .IP |
b4f49502 MK |
61 | The various combinations for |
62 | .I flags | |
63 | have the following effect: | |
22356d97 | 64 | .RS |
460240ca | 65 | .TP |
b4f49502 MK |
66 | .B flags == O_NONBLOCK |
67 | The call returns immediately, with an error. | |
68 | .TP | |
69 | .B flags == (O_NONBLOCK | O_TRUNC) | |
70 | The module is unloaded immediately, | |
71 | regardless of whether it has a nonzero reference count. | |
72 | .TP | |
0cb430a1 | 73 | .B (flags & O_NONBLOCK) == 0 |
b4f49502 MK |
74 | If |
75 | .I flags | |
76 | does not specify | |
77 | .BR O_NONBLOCK , | |
78 | the following steps occur: | |
460240ca | 79 | .RS |
22356d97 | 80 | .IP \(bu 3 |
b4f49502 | 81 | The module is marked so that no new references are permitted. |
22356d97 | 82 | .IP \(bu |
b4f49502 MK |
83 | If the module's reference count is nonzero, |
84 | the caller is placed in an uninterruptible sleep state | |
85 | .RB ( TASK_UNINTERRUPTIBLE ) | |
86 | until the reference count is zero, at which point the call unblocks. | |
22356d97 | 87 | .IP \(bu |
b4f49502 | 88 | The module is unloaded in the usual way. |
460240ca | 89 | .RE |
b4f49502 MK |
90 | .RE |
91 | .PP | |
92 | The | |
93 | .B O_TRUNC | |
94 | flag has one further effect on the rules described above. | |
35f69680 | 95 | By default, if a module has an |
b4f49502 MK |
96 | .I init |
97 | function but no | |
fa1d2749 | 98 | .I exit |
26cd31fd | 99 | function, then an attempt to remove the module fails. |
b4f49502 | 100 | However, if |
1ae6b2c7 | 101 | .B O_TRUNC |
b4f49502 MK |
102 | was specified, this requirement is bypassed. |
103 | .PP | |
fa1d2749 | 104 | Using the |
b4f49502 MK |
105 | .B O_TRUNC |
106 | flag is dangerous! | |
460240ca MK |
107 | If the kernel was not built with |
108 | .BR CONFIG_MODULE_FORCE_UNLOAD , | |
109 | this flag is silently ignored. | |
e64bdfcf | 110 | (Normally, |
1ae6b2c7 | 111 | .B CONFIG_MODULE_FORCE_UNLOAD |
b4f49502 MK |
112 | is enabled.) |
113 | Using this flag taints the kernel (TAINT_FORCED_RMMOD). | |
47297adb | 114 | .SH RETURN VALUE |
c13182ef MK |
115 | On success, zero is returned. |
116 | On error, \-1 is returned and | |
c4d4162c | 117 | .I errno |
f6a4078b | 118 | is set to indicate the error. |
c4d4162c MK |
119 | .SH ERRORS |
120 | .TP | |
121 | .B EBUSY | |
460240ca MK |
122 | The module is not "live" |
123 | (i.e., it is still being initialized or is already marked for removal); | |
b4f49502 MK |
124 | or, the module has |
125 | an | |
126 | .I init | |
127 | function but has no | |
460240ca | 128 | .I exit |
b4f49502 | 129 | function, and |
460240ca MK |
130 | .B O_TRUNC |
131 | was not specified in | |
132 | .IR flags . | |
c4d4162c MK |
133 | .TP |
134 | .B EFAULT | |
135 | .I name | |
b4f49502 | 136 | refers to a location outside the process's accessible address space. |
c4d4162c MK |
137 | .TP |
138 | .B ENOENT | |
139 | No module by that name exists. | |
140 | .TP | |
141 | .B EPERM | |
142 | The caller was not privileged | |
143 | (did not have the | |
144 | .B CAP_SYS_MODULE | |
460240ca MK |
145 | capability), |
146 | or module unloading is disabled | |
147 | (see | |
1ae6b2c7 | 148 | .I /proc/sys/kernel/modules_disabled |
460240ca MK |
149 | in |
150 | .BR proc (5)). | |
151 | .TP | |
152 | .B EWOULDBLOCK | |
153 | Other modules depend on this module; | |
154 | or, | |
1ae6b2c7 | 155 | .B O_NONBLOCK |
460240ca MK |
156 | was specified in |
157 | .IR flags , | |
fa1d2749 | 158 | but the reference count of this module is nonzero and |
460240ca MK |
159 | .B O_TRUNC |
160 | was not specified in | |
161 | .IR flags . | |
3113c7f3 | 162 | .SH STANDARDS |
c4d4162c | 163 | .BR delete_module () |
8382f16d | 164 | is Linux-specific. |
460240ca | 165 | .SH NOTES |
4a9c7a5e MK |
166 | The |
167 | .BR delete_module () | |
0b13a3d6 | 168 | system call is not supported by glibc. |
fa3b5cee MK |
169 | No declaration is provided in glibc headers, but, through a quirk of history, |
170 | glibc versions before 2.23 did export an ABI for this system call. | |
4a9c7a5e | 171 | Therefore, in order to employ this system call, |
fa3b5cee MK |
172 | it is (before glibc 2.23) sufficient to |
173 | manually declare the interface in your code; | |
4a9c7a5e | 174 | alternatively, you can invoke the system call using |
460240ca | 175 | .BR syscall (2). |
efeece04 | 176 | .PP |
b2fc8e9f | 177 | The uninterruptible sleep that may occur if |
1ae6b2c7 | 178 | .B O_NONBLOCK |
b4f49502 | 179 | is omitted from |
1ae6b2c7 | 180 | .I flags |
b4f49502 MK |
181 | is considered undesirable, because the sleeping process is left |
182 | in an unkillable state. | |
183 | As at Linux 3.7, specifying | |
1ae6b2c7 | 184 | .B O_NONBLOCK |
b4f49502 | 185 | is optional, but in future kernels it is likely to become mandatory. |
460240ca MK |
186 | .SS Linux 2.4 and earlier |
187 | In Linux 2.4 and earlier, the system call took only one argument: | |
efeece04 | 188 | .PP |
460240ca | 189 | .BI " int delete_module(const char *" name ); |
efeece04 | 190 | .PP |
460240ca MK |
191 | If |
192 | .I name | |
193 | is NULL, all unused modules marked auto-clean are removed. | |
efeece04 | 194 | .PP |
460240ca MK |
195 | Some further details of differences in the behavior of |
196 | .BR delete_module () | |
197 | in Linux 2.4 and earlier are | |
198 | .I not | |
199 | currently explained in this manual page. | |
47297adb | 200 | .SH SEE ALSO |
c4d4162c MK |
201 | .BR create_module (2), |
202 | .BR init_module (2), | |
98038e98 | 203 | .BR query_module (2), |
b4f49502 | 204 | .BR lsmod (8), |
eceb82f7 | 205 | .BR modprobe (8), |
98038e98 | 206 | .BR rmmod (8) |