man2/delete_module.2

   1 .\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH delete_module 2 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 delete_module \- unload a kernel module
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .BR "#include <fcntl.h>" "            /* Definition of " O_* " constants */"
  14 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  15 .B #include <unistd.h>
  16 .PP
  17 .BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags );
  18 .fi
  19 .PP
  20 .IR Note :
  21 glibc provides no wrapper for
  22 .BR delete_module (),
  23 necessitating the use of
  24 .BR syscall (2).
  25 .SH DESCRIPTION
  26 The
  27 .BR delete_module ()
  28 system call attempts to remove the unused loadable module entry
  29 identified by
  30 .IR name .
  31 If the module has an
  32 .I exit
  33 function, then that function is executed before unloading the module.
  34 The
  35 .I flags
  36 argument is used to modify the behavior of the system call,
  37 as described below.
  38 This system call requires privilege.
  39 .PP
  40 Module removal is attempted according to the following rules:
  41 .IP (1) 5
  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.
  45 .IP (2)
  46 Otherwise, if the reference count for the module
  47 (i.e., the number of processes currently using the module)
  48 is zero, then the module is immediately unloaded.
  49 .IP (3)
  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
  54 .B O_NONBLOCK
  55 flag is always specified, and the
  56 .B O_TRUNC
  57 flag may additionally be specified.
  58 .\"     O_TRUNC == KMOD_REMOVE_FORCE in kmod library
  59 .\"     O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library
  60 .IP
  61 The various combinations for
  62 .I flags
  63 have the following effect:
  64 .RS
  65 .TP
  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
  73 .B (flags & O_NONBLOCK) == 0
  74 If
  75 .I flags
  76 does not specify
  77 .BR O_NONBLOCK ,
  78 the following steps occur:
  79 .RS
  80 .IP \(bu 3
  81 The module is marked so that no new references are permitted.
  82 .IP \(bu
  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.
  87 .IP \(bu
  88 The module is unloaded in the usual way.
  89 .RE
  90 .RE
  91 .PP
  92 The
  93 .B O_TRUNC
  94 flag has one further effect on the rules described above.
  95 By default, if a module has an
  96 .I init
  97 function but no
  98 .I exit
  99 function, then an attempt to remove the module fails.
 100 However, if
 101 .B O_TRUNC
 102 was specified, this requirement is bypassed.
 103 .PP
 104 Using the
 105 .B O_TRUNC
 106 flag is dangerous!
 107 If the kernel was not built with
 108 .BR CONFIG_MODULE_FORCE_UNLOAD ,
 109 this flag is silently ignored.
 110 (Normally,
 111 .B CONFIG_MODULE_FORCE_UNLOAD
 112 is enabled.)
 113 Using this flag taints the kernel (TAINT_FORCED_RMMOD).
 114 .SH RETURN VALUE
 115 On success, zero is returned.
 116 On error, \-1 is returned and
 117 .I errno
 118 is set to indicate the error.
 119 .SH ERRORS
 120 .TP
 121 .B EBUSY
 122 The module is not "live"
 123 (i.e., it is still being initialized or is already marked for removal);
 124 or, the module has
 125 an
 126 .I init
 127 function but has no
 128 .I exit
 129 function, and
 130 .B O_TRUNC
 131 was not specified in
 132 .IR flags .
 133 .TP
 134 .B EFAULT
 135 .I name
 136 refers to a location outside the process's accessible address space.
 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
 145 capability),
 146 or module unloading is disabled
 147 (see
 148 .I /proc/sys/kernel/modules_disabled
 149 in
 150 .BR proc (5)).
 151 .TP
 152 .B EWOULDBLOCK
 153 Other modules depend on this module;
 154 or,
 155 .B O_NONBLOCK
 156 was specified in
 157 .IR flags ,
 158 but the reference count of this module is nonzero and
 159 .B O_TRUNC
 160 was not specified in
 161 .IR flags .
 162 .SH STANDARDS
 163 .BR delete_module ()
 164 is Linux-specific.
 165 .SH NOTES
 166 The
 167 .BR delete_module ()
 168 system call is not supported by glibc.
 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.
 171 Therefore, in order to employ this system call,
 172 it is (before glibc 2.23) sufficient to
 173 manually declare the interface in your code;
 174 alternatively, you can invoke the system call using
 175 .BR syscall (2).
 176 .PP
 177 The uninterruptible sleep that may occur if
 178 .B O_NONBLOCK
 179 is omitted from
 180 .I flags
 181 is considered undesirable, because the sleeping process is left
 182 in an unkillable state.
 183 As at Linux 3.7, specifying
 184 .B O_NONBLOCK
 185 is optional, but in future kernels it is likely to become mandatory.
 186 .SS Linux 2.4 and earlier
 187 In Linux 2.4 and earlier, the system call took only one argument:
 188 .PP
 189 .BI "   int delete_module(const char *" name );
 190 .PP
 191 If
 192 .I name
 193 is NULL, all unused modules marked auto-clean are removed.
 194 .PP
 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.
 200 .SH SEE ALSO
 201 .BR create_module (2),
 202 .BR init_module (2),
 203 .BR query_module (2),
 204 .BR lsmod (8),
 205 .BR modprobe (8),
 206 .BR rmmod (8)