INSMOD(1)

NAME
insmod - install loadable modules (aout and ELF format)

SYNOPSIS
insmod [ -fkmsxv ] [ -o internal_name ] object_file [ symbol=value ... ]

DESCRIPTION
Insmod installs a loadable module in the kernel.

Insmod tries to load a module into the kernel, and resolves all symbols from the exported kernel symbols, with version information, if available. The module will get its name by removing the '.o' extension from the basename of the object file.
If the '.o' extension is omitted, insmod will attempt to locate the module in some common default directories. If the environment contains the variable MODPATH, where all directories are separated with ':', insmod will look in these directories for the module, in the specified order.

It is possible to load unversioned modules in a versioned kernel, and all combinations of these.
It is also possible to load ELF modules into an a.out kernel, and all combinations of these.

It is possible to stack modules, i.e. let one module use a previously loaded module. All modules that are referenced are updated with this reference. This ensures that a module can't be unloaded if there is another module that refers to it.

It is possible to change integer values in the module when loading it. This makes it possible to "tune" the module.

The options are as follows:

-f  The -f option tries to load the module even if the kernel or symbol versions differs from the version expected by the module. A warning will be issued if the module is locked to a specific kernel version that differs from the current version.

-k  This option should really only be used by modprobe, to indicate that the module insertion was requested by kerneld. All modules inserted using this option will be subject to auto-removal by the kerneld utiliy if they have been unused for more that a minute. (I.e. the usage count is zero and no modules depend on this module.)
    If the kernel is not "kerneld-aware", the module will be rejected by the kernel. Just load it without the "-k" option, and all should be well.

-m  The -m option will make insmod ouput a load map, that will make it easier to debug your modules after a kernel panic...
    Thanks to Derek Atkins <warlord@MIT.EDU>.

-o  The -o option allows the module to be named to an explicit name instead of having a name derived from the name of the object file.
    Note that this option can also be placed _after_ the module name, so that the syntax of insmod looks more similar to ld.

symbol=value[,value] ...
    The values of all integer or character pointer symbols in the module can be changed at load-time by naming a symbol and giving the new value(s).
    If the symbol is defined as an array of integers or character pointers, the elements in the array can be initialized by giving the values separated by commas (','). Specific array entries can be skipped by omitting the value, as in 'symbol=value1,,value2'.
    Each integer value can be given as a decimal, octal or hexadecimal value: 17, 021 or 0x11.
    If the first character in the given value is non-numeric, the value is interpreted as a string. The symbol is assumed to be a character pointer, which will be initialized to point to the string.
    If you want to use a string that starts with a number, you have to enclose the string with quotes, i.e. " or ' (Inspired by Giorgio Caset <gca@wag.ch>).
    Extra space in the module will be allocated for the string itself.
    Note the syntax: no spaces are allowed around the '=' or ','-signs!
    If you want to use persistent module storage, there is a special syntax for selecting persistent data:
        symbol=?key:default,default..
        (Note the '?' and ':' markers!) This means that if there exists some module information that was previously saved with "key" (by e.g. "set_persist("a key", &value, size)"), then this value will be used to update the symbol. The key name can be enclosed in quotes if it contains whitespace.
    If no persistent value can be found, then the default values will be used.

-s  With this option insmod will produce debugging information and error messages using the syslog facility. (Also used by "kerneld", if you have installed it.)

-v  If you want verbose information from the loading, select this option.

-x  is the no-export-flag, which will inhibit the default insmod behaviour: i.e. inserting all the module's external symbols into the kernel symbol table.
    Note that the kernel will still update the references that the module makes to previously loaded modules.

SEE ALSO
rmmod(1), modprobe(1), depmod(1), lsmod(1), ksyms(1), modules(2), genksyms(8)

HISTORY
The module support was first concieved by Anonymous (as far as I know...).
Linux version by Bas Laarhoven <bas@vimec.nl>,
0.99.14 version by Jon Tombs <jon@gtex02.us.es>,
extended by Bjorn Ekwall <bj0rn@blox.se>.
ELF help from Eric Youngdale <eric@aib.com>

BUGS
Insmod relies on the "fact" that symbols, for which one wants to change the value, are defined as integers or character pointers, and that sizeof(int) == sizeof(char *).