get_kernel_syms

MODULES(2)                    System Calls Manual                   MODULES(2)

NAME
     get_kernel_syms, create_module, init_module, delete_module — loadable
     module support

SYNOPSIS
     #include <linux/module.h>

     int get_kernel_syms(struct kernel_sym *table);

     int create_module(char *module_name, unsigned long size);

     int init_module(char *module_name, char *code, unsigned codesize,
         struct mod_routines *routines, struct symbol_table *symtab);

     int delete_module(char *module_name);

     struct kernel_sym {
          unsigned long value;
          char name[SYM_MAX_NAME];
     };

     struct mod_routines {
          int (*init)(void);
          void (*cleanup)(void);
     };

     struct module_ref {
          struct module *module;
          struct module_ref *next;
     };

     struct internal_symbol {
          void *addr;
          char *name;
     };

     struct symbol_table {
          int size; /* total, including string table!!! */
          int n_symbols;
          int n_refs;
          struct internal_symbol symbol[0];
          struct module_ref ref[0];
     };

DESCRIPTION
     These system calls have not yet been included in any library, which means
     that they have to be called by the syscall(__NR_function) mechanism.

     get_kernel_syms(table);
           has two uses: first, if table is NULL, this call will only return
           the number of symbols, including module names, that are available.
           This number should be used to reserve memory for that many items of
           struct kernel_sym.
           If table is not NULL, this call will copy all kernel symbols and
           module names (and version info) from the kernel to the space
           pointed to by table. The entries are ordered in module LIFO order.
           For each module an entry that decribes the module will be followed
           by entries describing the symbols exported by this module.

           Note that for symbols that describe a module, the value part of the
           structure will contain the kernel adress of the structure that
           describes the module.
           The name part of the structure is the module name prepended with #,
           as in #my_module. The symbol that describes a module will appear
           before the symbols defined by this module.
           Ahead of the kernel resident symbols, a module name symbol with the
           "dummy" name # will appear.  This information can be used to build
           a table of module references when modules are stacked (or layered).

     create_module(module_name, size);
           will allocate size bytes of kernel space for a module, and also
           create the necessary kernel structures for the new module called
           name. The module will now exist in kernel space, with the status
           MOD_UNINITIALIZED.

     init_module(module_name, code, codesize, routines, symtab);
           This is the actual "module loader", that will load the module named
           name into the kernel.  The parameters code and codesize refer to
           the relocated binary object module that is codesize bytes long.
           Note that the first 4 bytes will be used as a reference counter in
           kernel space, updated by the MOD_INC_USE_COUNT and
           MOD_DEC_USE_COUNT macros.
           The functions described in routines will be used to start and stop
           the module.  These pointers should therefore contain the adresses
           of the init_module() and cleanup_module() functions that have to be
           defined for all loadable modules.
           If a module wants to export symbols for use by other modules, or if
           the module makes references to symbols defined by other modules,
           the parameter symtab has to point to a structure that describes
           these.  A NULL value for symtab means that no symbols are exported
           and no references to other modules are made.
           The symtab that will be copied into the kernel consist of a
           symbol_table structure immediately followed by a string table,
           containing the names of the symbols defined by the module.  The
           size element has to include the size of this string table as well.

           Special considerations:
           The n_symbols and n_refs elements tells how many symbols and how
           many module references are included in the symbol_table structure.
           Immediately after these integers, the array of symbol definitions
           follow.  The name element in each struct internal_symbol should
           actually not be an ordinary pointer, but instead the offset of the
           corresponding string table entry relative to the start of the
           symbol_table structure.

           When all defined symbols have been listed, the symbol_table
           structure continues with the array of module references, as
           described by the struct module_ref elements.  Only the module field
           of these structures have to be initialized.  The module adresses
           that were obtained from a previous get_kernel_syms call, for
           elements with names starting with # should be copied to this field.

           If the module could be successfully loaded, and if the call to the
           module function init_module() also succeeds, the status of the
           module will be changed to MOD_RUNNING.  Otherwise, the kernel
           memory occupied by module will be freed.

     delete_module(module_name);
           should be used to unload a module.  If the module reference count
           shows that the module is not active, and if there are no references
           to this module from other modules, the module function
           cleanup_module() will be called.  If all these steps succeed, the
           kernel memory occupied by the module and its structures will be
           freed.

DIAGNOSTICS
     If there are any errors, these functions will return the value -1, and
     the global variable errno will contain the error number.  A descriptive
     text will also be written on the console device.

SEE ALSO
     insmod(1), rmmod(1), lsmod(1), ksyms(1)

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>.

BUGS
     Naah...


Linux                          January 25, 1995                          Linux