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