mirror of https://github.com/mkerrisk/man-pages
355 lines
10 KiB
Groff
355 lines
10 KiB
Groff
.\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" A few fragments remain from a version
|
|
.\" Copyright (C) 1996 Free Software Foundation, Inc.
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH INIT_MODULE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
init_module, finit_module \- load a kernel module
|
|
.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>
|
|
.PP
|
|
.BI "int syscall(SYS_init_module, void *" module_image ", unsigned long " len ,
|
|
.BI " const char *" param_values );
|
|
.BI "int syscall(SYS_finit_module, int " fd ", const char *" param_values ,
|
|
.BI " int " flags );
|
|
.fi
|
|
.PP
|
|
.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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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:
|
|
.PP
|
|
.RI " " name [\c
|
|
.BI = value\c
|
|
.RB [ ,\c
|
|
.IR value ...]]
|
|
.PP
|
|
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 ().
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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
|
|
.IR /proc/sys/kernel/modules_disabled
|
|
in
|
|
.BR proc (5)).
|
|
.PP
|
|
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
|
|
.IR 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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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 VERSIONS
|
|
.BR finit_module ()
|
|
is available since Linux 3.8.
|
|
.SH CONFORMING TO
|
|
.BR init_module ()
|
|
and
|
|
.BR finit_module ()
|
|
are Linux-specific.
|
|
.SH NOTES
|
|
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 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
|
|
Information about currently loaded modules can be found in
|
|
.IR /proc/modules
|
|
and in the file trees under the per-module subdirectories under
|
|
.IR /sys/module .
|
|
.PP
|
|
See the Linux kernel source file
|
|
.I include/linux/module.h
|
|
for some useful background information.
|
|
.SS Linux 2.4 and earlier
|
|
In Linux 2.4 and earlier, the
|
|
.BR init_module ()
|
|
system call was rather different:
|
|
.PP
|
|
.B " #include <linux/module.h>"
|
|
.PP
|
|
.BI " int init_module(const char *" name ", struct module *" image );
|
|
.PP
|
|
(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
|
|
.BR ENOSYS
|
|
on Linux 2.6 and later.)
|
|
.PP
|
|
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).
|
|
.PP
|
|
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:
|
|
.PP
|
|
.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
|
|
.PP
|
|
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 SEE ALSO
|
|
.BR create_module (2),
|
|
.BR delete_module (2),
|
|
.BR query_module (2),
|
|
.BR lsmod (8),
|
|
.BR modprobe (8)
|