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