diff options
Diffstat (limited to 'man/man2/init_module.2')
| -rw-r--r-- | man/man2/init_module.2 | 393 |
1 files changed, 393 insertions, 0 deletions
diff --git a/man/man2/init_module.2 b/man/man2/init_module.2 new file mode 100644 index 0000000..98b3c5c --- /dev/null +++ b/man/man2/init_module.2 @@ -0,0 +1,393 @@ +.\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com> +.\" A few fragments remain from a version +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH init_module 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +init_module, finit_module \- load a kernel module +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <linux/module.h>" " /* Definition of " MODULE_* " constants */" +.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" +.B #include <unistd.h> +.P +.BI "int syscall(SYS_init_module, void " module_image [. len "], \ +unsigned long " len , +.BI " const char *" param_values ); +.BI "int syscall(SYS_finit_module, int " fd , +.BI " const char *" param_values ", int " flags ); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR init_module () +loads an ELF image into kernel space, +performs any necessary symbol relocations, +initializes module parameters to values provided by the caller, +and then runs the module's +.I init +function. +This system call requires privilege. +.P +The +.I module_image +argument points to a buffer containing the binary image +to be loaded; +.I len +specifies the size of that buffer. +The module image should be a valid ELF image, built for the running kernel. +.P +The +.I param_values +argument is a string containing space-delimited specifications of the +values for module parameters (defined inside the module using +.BR module_param () +and +.BR module_param_array ()). +The kernel parses this string and initializes the specified +parameters. +Each of the parameter specifications has the form: +.P +.RI " " name [\c +.BI = value\c +.RB [ ,\c +.IR value ...]] +.P +The parameter +.I name +is one of those defined within the module using +.IR module_param () +(see the Linux kernel source file +.IR include/linux/moduleparam.h ). +The parameter +.I value +is optional in the case of +.I bool +and +.I invbool +parameters. +Values for array parameters are specified as a comma-separated list. +.SS finit_module() +The +.BR finit_module () +.\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2 +.\" https://lwn.net/Articles/519010/ +system call is like +.BR init_module (), +but reads the module to be loaded from the file descriptor +.IR fd . +It is useful when the authenticity of a kernel module +can be determined from its location in the filesystem; +in cases where that is possible, +the overhead of using cryptographically signed modules to +determine the authenticity of a module can be avoided. +The +.I param_values +argument is as for +.BR init_module (). +.P +The +.I flags +argument modifies the operation of +.BR finit_module (). +It is a bit mask value created by ORing +together zero or more of the following flags: +.\" commit 2f3238aebedb243804f58d62d57244edec4149b2 +.TP +.B MODULE_INIT_IGNORE_MODVERSIONS +Ignore symbol version hashes. +.TP +.B MODULE_INIT_IGNORE_VERMAGIC +Ignore kernel version magic. +.TP +.BR MODULE_INIT_COMPRESSED_FILE " (since Linux 5.17)" +.\" commit b1ae6dc41eaaa98bb75671e0f3665bfda248c3e7 +Use in-kernel module decompression. +.P +There are some safety checks built into a module to ensure that +it matches the kernel against which it is loaded. +.\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html +.\" is dated, but informative +These checks are recorded when the module is built and +verified when the module is loaded. +First, the module records a "vermagic" string containing +the kernel version number and prominent features (such as the CPU type). +Second, if the module was built with the +.B CONFIG_MODVERSIONS +configuration option enabled, +a version hash is recorded for each symbol the module uses. +This hash is based on the types of the arguments and return value +for the function named by the symbol. +In this case, the kernel version number within the +"vermagic" string is ignored, +as the symbol version hashes are assumed to be sufficiently reliable. +.P +Using the +.B MODULE_INIT_IGNORE_VERMAGIC +flag indicates that the "vermagic" string is to be ignored, and the +.B MODULE_INIT_IGNORE_MODVERSIONS +flag indicates that the symbol version hashes are to be ignored. +If the kernel is built to permit forced loading (i.e., configured with +.BR CONFIG_MODULE_FORCE_LOAD ), +then loading continues, otherwise it fails with the error +.B ENOEXEC +as expected for malformed modules. +.P +If the kernel was build with +.BR CONFIG_MODULE_DECOMPRESS , +the in-kernel decompression feature can be used. +User-space code can check if the kernel supports decompression +by reading the +.I /sys/module/compression +attribute. +If the kernel supports decompression, +the compressed file can directly be passed to +.BR finit_module () +using the +.B MODULE_INIT_COMPRESSED_FILE +flag. +The in-kernel module decompressor supports the following compression algorithms: +.P +.RS 4 +.PD 0 +.IP \[bu] 3 +.I gzip +(since Linux 5.17) +.IP \[bu] +.I xz +(since Linux 5.17) +.IP \[bu] +.I zstd +.\" commit 169a58ad824d896b9e291a27193342616e651b82 +(since Linux 6.2) +.PD +.RE +.P +The kernel only implements a single decompression method. +This is selected during module generation accordingly to the compression method +chosen in the kernel configuration. +.SH RETURN VALUE +On success, these system calls return 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.BR EBADMSG " (since Linux 3.7)" +Module signature is misformatted. +.TP +.B EBUSY +Timeout while trying to resolve a symbol reference by this module. +.TP +.B EFAULT +An address argument referred to a location that +is outside the process's accessible address space. +.TP +.BR ENOKEY " (since Linux 3.7)" +.\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1 +.\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa +.\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7 +Module signature is invalid or +the kernel does not have a key for this module. +This error is returned only if the kernel was configured with +.BR CONFIG_MODULE_SIG_FORCE ; +if the kernel was not configured with this option, +then an invalid or unsigned module simply taints the kernel. +.TP +.B ENOMEM +Out of memory. +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability), +or module loading is disabled +(see +.I /proc/sys/kernel/modules_disabled +in +.BR proc (5)). +.P +The following errors may additionally occur for +.BR init_module (): +.TP +.B EEXIST +A module with this name is already loaded. +.TP +.B EINVAL +.I param_values +is invalid, or some part of the ELF image in +.I module_image +contains inconsistencies. +.\" .TP +.\" .BR EINVAL " (Linux 2.4 and earlier)" +.\" Some +.\" .I image +.\" slot is filled in incorrectly, +.\" .I image\->name +.\" does not correspond to the original module name, some +.\" .I image\->deps +.\" entry does not correspond to a loaded module, +.\" or some other similar inconsistency. +.TP +.B ENOEXEC +The binary image supplied in +.I module_image +is not an ELF image, +or is an ELF image that is invalid or for a different architecture. +.P +The following errors may additionally occur for +.BR finit_module (): +.TP +.B EBADF +The file referred to by +.I fd +is not opened for reading. +.TP +.B EFBIG +The file referred to by +.I fd +is too large. +.TP +.B EINVAL +.I flags +is invalid. +.TP +.B EINVAL +The decompressor sanity checks failed, +while loading a compressed module with flag +.B MODULE_INIT_COMPRESSED_FILE +set. +.TP +.B ENOEXEC +.I fd +does not refer to an open file. +.TP +.BR EOPNOTSUPP " (since Linux 5.17)" +The flag +.B MODULE_INIT_COMPRESSED_FILE +is set to load a compressed module, +and the kernel was built without +.BR CONFIG_MODULE_DECOMPRESS . +.TP +.BR ETXTBSY " (since Linux 4.7)" +.\" commit 39d637af5aa7577f655c58b9e55587566c63a0af +The file referred to by +.I fd +is opened for read-write. +.P +In addition to the above errors, if the module's +.I init +function is executed and returns an error, then +.BR init_module () +or +.BR finit_module () +fails and +.I errno +is set to the value returned by the +.I init +function. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR finit_module () +Linux 3.8. +.P +The +.BR init_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 +.BR init_module () +system call was rather different: +.P +.B " #include <linux/module.h>" +.P +.BI " int init_module(const char *" name ", struct module *" image ); +.P +(User-space applications can detect which version of +.BR init_module () +is available by calling +.BR query_module (); +the latter call fails with the error +.B ENOSYS +on Linux 2.6 and later.) +.P +The older version of the system call +loads the relocated module image pointed to by +.I image +into kernel space and runs the module's +.I init +function. +The caller is responsible for providing the relocated image (since +Linux 2.6, the +.BR init_module () +system call does the relocation). +.P +The module image begins with a module structure and is followed by +code and data as appropriate. +Since Linux 2.2, the module structure is defined as follows: +.P +.in +4n +.EX +struct module { + unsigned long size_of_struct; + struct module *next; + const char *name; + unsigned long size; + long usecount; + unsigned long flags; + unsigned int nsyms; + unsigned int ndeps; + struct module_symbol *syms; + struct module_ref *deps; + struct module_ref *refs; + int (*init)(void); + void (*cleanup)(void); + const struct exception_table_entry *ex_table_start; + const struct exception_table_entry *ex_table_end; +#ifdef __alpha__ + unsigned long gp; +#endif +}; +.EE +.in +.P +All of the pointer fields, with the exception of +.I next +and +.IR refs , +are expected to point within the module body and be +initialized as appropriate for kernel space, that is, relocated with +the rest of the module. +.SH NOTES +Information about currently loaded modules can be found in +.I /proc/modules +and in the file trees under the per-module subdirectories under +.IR /sys/module . +.P +See the Linux kernel source file +.I include/linux/module.h +for some useful background information. +.SH SEE ALSO +.BR create_module (2), +.BR delete_module (2), +.BR query_module (2), +.BR lsmod (8), +.BR modprobe (8) |