diff options
Diffstat (limited to 'upstream/debian-bookworm/man2/delete_module.2')
| -rw-r--r-- | upstream/debian-bookworm/man2/delete_module.2 | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/delete_module.2 b/upstream/debian-bookworm/man2/delete_module.2 new file mode 100644 index 00000000..ad20fac2 --- /dev/null +++ b/upstream/debian-bookworm/man2/delete_module.2 @@ -0,0 +1,206 @@ +.\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH delete_module 2 2023-02-05 "Linux man-pages 6.03" +.SH NAME +delete_module \- unload a kernel module +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" +.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" +.B #include <unistd.h> +.PP +.BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags ); +.fi +.PP +.IR Note : +glibc provides no wrapper for +.BR delete_module (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR delete_module () +system call attempts to remove the unused loadable module entry +identified by +.IR name . +If the module has an +.I exit +function, then that function is executed before unloading the module. +The +.I flags +argument is used to modify the behavior of the system call, +as described below. +This system call requires privilege. +.PP +Module removal is attempted according to the following rules: +.IP (1) 5 +If there are other loaded modules that depend on +(i.e., refer to symbols defined in) this module, +then the call fails. +.IP (2) +Otherwise, if the reference count for the module +(i.e., the number of processes currently using the module) +is zero, then the module is immediately unloaded. +.IP (3) +If a module has a nonzero reference count, +then the behavior depends on the bits set in +.IR flags . +In normal usage (see NOTES), the +.B O_NONBLOCK +flag is always specified, and the +.B O_TRUNC +flag may additionally be specified. +.\" O_TRUNC == KMOD_REMOVE_FORCE in kmod library +.\" O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library +.IP +The various combinations for +.I flags +have the following effect: +.RS +.TP +.B flags == O_NONBLOCK +The call returns immediately, with an error. +.TP +.B flags == (O_NONBLOCK | O_TRUNC) +The module is unloaded immediately, +regardless of whether it has a nonzero reference count. +.TP +.B (flags & O_NONBLOCK) == 0 +If +.I flags +does not specify +.BR O_NONBLOCK , +the following steps occur: +.RS +.IP \[bu] 3 +The module is marked so that no new references are permitted. +.IP \[bu] +If the module's reference count is nonzero, +the caller is placed in an uninterruptible sleep state +.RB ( TASK_UNINTERRUPTIBLE ) +until the reference count is zero, at which point the call unblocks. +.IP \[bu] +The module is unloaded in the usual way. +.RE +.RE +.PP +The +.B O_TRUNC +flag has one further effect on the rules described above. +By default, if a module has an +.I init +function but no +.I exit +function, then an attempt to remove the module fails. +However, if +.B O_TRUNC +was specified, this requirement is bypassed. +.PP +Using the +.B O_TRUNC +flag is dangerous! +If the kernel was not built with +.BR CONFIG_MODULE_FORCE_UNLOAD , +this flag is silently ignored. +(Normally, +.B CONFIG_MODULE_FORCE_UNLOAD +is enabled.) +Using this flag taints the kernel (TAINT_FORCED_RMMOD). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBUSY +The module is not "live" +(i.e., it is still being initialized or is already marked for removal); +or, the module has +an +.I init +function but has no +.I exit +function, and +.B O_TRUNC +was not specified in +.IR flags . +.TP +.B EFAULT +.I name +refers to a location outside the process's accessible address space. +.TP +.B ENOENT +No module by that name exists. +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability), +or module unloading is disabled +(see +.I /proc/sys/kernel/modules_disabled +in +.BR proc (5)). +.TP +.B EWOULDBLOCK +Other modules depend on this module; +or, +.B O_NONBLOCK +was specified in +.IR flags , +but the reference count of this module is nonzero and +.B O_TRUNC +was not specified in +.IR flags . +.SH STANDARDS +.BR delete_module () +is Linux-specific. +.SH NOTES +The +.BR delete_module () +system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before glibc 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it is (before glibc 2.23) sufficient to +manually declare the interface in your code; +alternatively, you can invoke the system call using +.BR syscall (2). +.PP +The uninterruptible sleep that may occur if +.B O_NONBLOCK +is omitted from +.I flags +is considered undesirable, because the sleeping process is left +in an unkillable state. +As at Linux 3.7, specifying +.B O_NONBLOCK +is optional, but in future kernels it is likely to become mandatory. +.SS Linux 2.4 and earlier +In Linux 2.4 and earlier, the system call took only one argument: +.PP +.BI " int delete_module(const char *" name ); +.PP +If +.I name +is NULL, all unused modules marked auto-clean are removed. +.PP +Some further details of differences in the behavior of +.BR delete_module () +in Linux 2.4 and earlier are +.I not +currently explained in this manual page. +.SH SEE ALSO +.BR create_module (2), +.BR init_module (2), +.BR query_module (2), +.BR lsmod (8), +.BR modprobe (8), +.BR rmmod (8) |