man2/init_module.2

   1 .\" Copyright (C) 2012 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" A few fragments remain from a version
   3 .\" Copyright (C) 1996 Free Software Foundation, Inc.
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH init_module 2 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 init_module, finit_module \- load a kernel module
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .BR "#include <linux/module.h>" "    /* Definition of " MODULE_* " constants */"
  16 .BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
  17 .B #include <unistd.h>
  18 .PP
  19 .BI "int syscall(SYS_init_module, void *" module_image ", unsigned long " len ,
  20 .BI "            const char *" param_values );
  21 .BI "int syscall(SYS_finit_module, int " fd ", const char *" param_values ,
  22 .BI "            int " flags );
  23 .fi
  24 .PP
  25 .IR Note :
  26 glibc provides no wrappers for these system calls,
  27 necessitating the use of
  28 .BR syscall (2).
  29 .SH DESCRIPTION
  30 .BR init_module ()
  31 loads an ELF image into kernel space,
  32 performs any necessary symbol relocations,
  33 initializes module parameters to values provided by the caller,
  34 and then runs the module's
  35 .I init
  36 function.
  37 This system call requires privilege.
  38 .PP
  39 The
  40 .I module_image
  41 argument points to a buffer containing the binary image
  42 to be loaded;
  43 .I len
  44 specifies the size of that buffer.
  45 The module image should be a valid ELF image, built for the running kernel.
  46 .PP
  47 The
  48 .I param_values
  49 argument is a string containing space-delimited specifications of the
  50 values for module parameters (defined inside the module using
  51 .BR module_param ()
  52 and
  53 .BR module_param_array ()).
  54 The kernel parses this string and initializes the specified
  55 parameters.
  56 Each of the parameter specifications has the form:
  57 .PP
  58 .RI "        " name [\c
  59 .BI = value\c
  60 .RB [ ,\c
  61 .IR value ...]]
  62 .PP
  63 The parameter
  64 .I name
  65 is one of those defined within the module using
  66 .IR module_param ()
  67 (see the Linux kernel source file
  68 .IR include/linux/moduleparam.h ).
  69 The parameter
  70 .I value
  71 is optional in the case of
  72 .I bool
  73 and
  74 .I invbool
  75 parameters.
  76 Values for array parameters are specified as a comma-separated list.
  77 .SS finit_module()
  78 The
  79 .BR finit_module ()
  80 .\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2
  81 .\" https://lwn.net/Articles/519010/
  82 system call is like
  83 .BR init_module (),
  84 but reads the module to be loaded from the file descriptor
  85 .IR fd .
  86 It is useful when the authenticity of a kernel module
  87 can be determined from its location in the filesystem;
  88 in cases where that is possible,
  89 the overhead of using cryptographically signed modules to
  90 determine the authenticity of a module can be avoided.
  91 The
  92 .I param_values
  93 argument is as for
  94 .BR init_module ().
  95 .PP
  96 The
  97 .I flags
  98 argument modifies the operation of
  99 .BR finit_module ().
 100 It is a bit mask value created by ORing
 101 together zero or more of the following flags:
 102 .\" commit 2f3238aebedb243804f58d62d57244edec4149b2
 103 .TP
 104 .B MODULE_INIT_IGNORE_MODVERSIONS
 105 Ignore symbol version hashes.
 106 .TP
 107 .B MODULE_INIT_IGNORE_VERMAGIC
 108 Ignore kernel version magic.
 109 .PP
 110 There are some safety checks built into a module to ensure that
 111 it matches the kernel against which it is loaded.
 112 .\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html
 113 .\" is dated, but informative
 114 These checks are recorded when the module is built and
 115 verified when the module is loaded.
 116 First, the module records a "vermagic" string containing
 117 the kernel version number and prominent features (such as the CPU type).
 118 Second, if the module was built with the
 119 .B CONFIG_MODVERSIONS
 120 configuration option enabled,
 121 a version hash is recorded for each symbol the module uses.
 122 This hash is based on the types of the arguments and return value
 123 for the function named by the symbol.
 124 In this case, the kernel version number within the
 125 "vermagic" string is ignored,
 126 as the symbol version hashes are assumed to be sufficiently reliable.
 127 .PP
 128 Using the
 129 .B MODULE_INIT_IGNORE_VERMAGIC
 130 flag indicates that the "vermagic" string is to be ignored, and the
 131 .B MODULE_INIT_IGNORE_MODVERSIONS
 132 flag indicates that the symbol version hashes are to be ignored.
 133 If the kernel is built to permit forced loading (i.e., configured with
 134 .BR CONFIG_MODULE_FORCE_LOAD ),
 135 then loading continues, otherwise it fails with the error
 136 .B ENOEXEC
 137 as expected for malformed modules.
 138 .SH RETURN VALUE
 139 On success, these system calls return 0.
 140 On error, \-1 is returned and
 141 .I errno
 142 is set to indicate the error.
 143 .SH ERRORS
 144 .TP
 145 .BR EBADMSG " (since Linux 3.7)"
 146 Module signature is misformatted.
 147 .TP
 148 .B EBUSY
 149 Timeout while trying to resolve a symbol reference by this module.
 150 .TP
 151 .B EFAULT
 152 An address argument referred to a location that
 153 is outside the process's accessible address space.
 154 .TP
 155 .BR ENOKEY " (since Linux 3.7)"
 156 .\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1
 157 .\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa
 158 .\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7
 159 Module signature is invalid or
 160 the kernel does not have a key for this module.
 161 This error is returned only if the kernel was configured with
 162 .BR CONFIG_MODULE_SIG_FORCE ;
 163 if the kernel was not configured with this option,
 164 then an invalid or unsigned module simply taints the kernel.
 165 .TP
 166 .B ENOMEM
 167 Out of memory.
 168 .TP
 169 .B EPERM
 170 The caller was not privileged
 171 (did not have the
 172 .B CAP_SYS_MODULE
 173 capability),
 174 or module loading is disabled
 175 (see
 176 .I /proc/sys/kernel/modules_disabled
 177 in
 178 .BR proc (5)).
 179 .PP
 180 The following errors may additionally occur for
 181 .BR init_module ():
 182 .TP
 183 .B EEXIST
 184 A module with this name is already loaded.
 185 .TP
 186 .B EINVAL
 187 .I param_values
 188 is invalid, or some part of the ELF image in
 189 .I module_image
 190 contains inconsistencies.
 191 .\" .TP
 192 .\" .BR EINVAL " (Linux 2.4 and earlier)"
 193 .\" Some
 194 .\" .I image
 195 .\" slot is filled in incorrectly,
 196 .\" .I image\->name
 197 .\" does not correspond to the original module name, some
 198 .\" .I image\->deps
 199 .\" entry does not correspond to a loaded module,
 200 .\" or some other similar inconsistency.
 201 .TP
 202 .B ENOEXEC
 203 The binary image supplied in
 204 .I module_image
 205 is not an ELF image,
 206 or is an ELF image that is invalid or for a different architecture.
 207 .PP
 208 The following errors may additionally occur for
 209 .BR finit_module ():
 210 .TP
 211 .B EBADF
 212 The file referred to by
 213 .I fd
 214 is not opened for reading.
 215 .TP
 216 .B EFBIG
 217 The file referred to by
 218 .I fd
 219 is too large.
 220 .TP
 221 .B EINVAL
 222 .I flags
 223 is invalid.
 224 .TP
 225 .B ENOEXEC
 226 .I fd
 227 does not refer to an open file.
 228 .TP
 229 .BR ETXTBSY " (since Linux 4.7)"
 230 .\" commit 39d637af5aa7577f655c58b9e55587566c63a0af
 231 The file referred to by
 232 .I fd
 233 is opened for read-write.
 234 .PP
 235 In addition to the above errors, if the module's
 236 .I init
 237 function is executed and returns an error, then
 238 .BR init_module ()
 239 or
 240 .BR finit_module ()
 241 fails and
 242 .I errno
 243 is set to the value returned by the
 244 .I init
 245 function.
 246 .SH VERSIONS
 247 .BR finit_module ()
 248 is available since Linux 3.8.
 249 .SH STANDARDS
 250 .BR init_module ()
 251 and
 252 .BR finit_module ()
 253 are Linux-specific.
 254 .SH NOTES
 255 The
 256 .BR init_module ()
 257 system call is not supported by glibc.
 258 No declaration is provided in glibc headers, but, through a quirk of history,
 259 glibc versions before 2.23 did export an ABI for this system call.
 260 Therefore, in order to employ this system call,
 261 it is (before glibc 2.23) sufficient to
 262 manually declare the interface in your code;
 263 alternatively, you can invoke the system call using
 264 .BR syscall (2).
 265 .PP
 266 Information about currently loaded modules can be found in
 267 .I /proc/modules
 268 and in the file trees under the per-module subdirectories under
 269 .IR /sys/module .
 270 .PP
 271 See the Linux kernel source file
 272 .I include/linux/module.h
 273 for some useful background information.
 274 .SS Linux 2.4 and earlier
 275 In Linux 2.4 and earlier, the
 276 .BR init_module ()
 277 system call was rather different:
 278 .PP
 279 .B "    #include <linux/module.h>"
 280 .PP
 281 .BI "    int init_module(const char *" name ", struct module *" image );
 282 .PP
 283 (User-space applications can detect which version of
 284 .BR init_module ()
 285 is available by calling
 286 .BR query_module ();
 287 the latter call fails with the error
 288 .B ENOSYS
 289 on Linux 2.6 and later.)
 290 .PP
 291 The older version of the system call
 292 loads the relocated module image pointed to by
 293 .I image
 294 into kernel space and runs the module's
 295 .I init
 296 function.
 297 The caller is responsible for providing the relocated image (since
 298 Linux 2.6, the
 299 .BR init_module ()
 300 system call does the relocation).
 301 .PP
 302 The module image begins with a module structure and is followed by
 303 code and data as appropriate.
 304 Since Linux 2.2, the module structure is defined as follows:
 305 .PP
 306 .in +4n
 307 .EX
 308 struct module {
 309     unsigned long         size_of_struct;
 310     struct module        *next;
 311     const char           *name;
 312     unsigned long         size;
 313     long                  usecount;
 314     unsigned long         flags;
 315     unsigned int          nsyms;
 316     unsigned int          ndeps;
 317     struct module_symbol *syms;
 318     struct module_ref    *deps;
 319     struct module_ref    *refs;
 320     int                 (*init)(void);
 321     void                (*cleanup)(void);
 322     const struct exception_table_entry *ex_table_start;
 323     const struct exception_table_entry *ex_table_end;
 324 #ifdef __alpha__
 325     unsigned long gp;
 326 #endif
 327 };
 328 .EE
 329 .in
 330 .PP
 331 All of the pointer fields, with the exception of
 332 .I next
 333 and
 334 .IR refs ,
 335 are expected to point within the module body and be
 336 initialized as appropriate for kernel space, that is, relocated with
 337 the rest of the module.
 338 .SH SEE ALSO
 339 .BR create_module (2),
 340 .BR delete_module (2),
 341 .BR query_module (2),
 342 .BR lsmod (8),
 343 .BR modprobe (8)