diff options
Diffstat (limited to 'man2/init_module.2')
| -rw-r--r-- | man2/init_module.2 | 342 |
1 files changed, 0 insertions, 342 deletions
diff --git a/man2/init_module.2 b/man2/init_module.2 deleted file mode 100644 index 95917a079..000000000 --- a/man2/init_module.2 +++ /dev/null @@ -1,342 +0,0 @@ -.\" 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 (date) "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. -.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. -.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 ENOEXEC -.I fd -does not refer to an open file. -.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) |