Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 205 insertions, 0 deletions

diff --git a/man2/delete_module.2 b/man2/delete_module.2
new file mode 100644
index 0000000..a909729
--- /dev/null
+++ b/man2/delete_module.2
@@ -0,0 +1,205 @@
+.\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH delete_module 2 2023-03-30 "Linux man-pages 6.05.01"
+.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
+Linux.
+.SH HISTORY
+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).
+.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 NOTES
+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.
+.SH SEE ALSO
+.BR create_module (2),
+.BR init_module (2),
+.BR query_module (2),
+.BR lsmod (8),
+.BR modprobe (8),
+.BR rmmod (8)