.\" Copyright (c) 1994 Bjorn Ekwall <bj0rn@blox.se>
.\" This program is distributed according to the Gnu General Public License.
.\" See the file COPYING in the kernel source directory /linux
.\"
.\" Traduction  12/10/1996 Christophe BLAESS (ccb@club-internet.fr)
.\" Mise a Jour 8/04/97
.TH MODULES 2 "8 Avril 1997" Linux "Manuel du programmeur Linux"
.SH NOM
get_kernel_syms, create_module, init_module, delete_module
\- Support des modules chargeables de Linux.
.SH SYNOPSIS
.B #include <linux/module.h>
.PP
.B int get_kernel_syms(struct kernel_sym *table);
.PP
.B int create_module(char *module_name, unsigned long size);
.PP
.B int init_module(char *module_name, char *code, unsigned codesize,
.br
.B \ \ \ \ struct mod_routines *routines, struct symbol_table *symtab);
.PP
.B int delete_module(char *module_name);
.PP
.nf
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];
};
.fi
.SH DESCRIPTION
Ces appels systmes ne sont pas encore inclus dans les bibliothques
(au 14 Mai 95) ce qui signifie qu'ils doivent tre appels avec le
mcanisme
.BR syscall(__NR_function) .
.PP
.TB
.B get_kernel_syms(table)
propose deux services : premirement, si
.B table
est NULL, cet appel retournera simplement le nombre de symboles
disponibles, y compris les noms des modules.
Cette valeur peut servir  allouer de la mmoire pour
autant d'lments du type
.B struct kernel_sym.

Si
.B table
n'est pas NULL, cet appel va copier tous les symboles du noyau et
les noms de modules (avec les numros de version) dans la zone
mmoire pointe par
.B table.
Les donnes sont tries dans l'ordre LIFO d'insertion des modules.
Chaque module est dcrit par une entre dans cette table, suivi par
les entres dcrivant les symboles exports par le module.
.PP
Remarquez que pour les symboles, la partie
.B value
de la structure contiendra l'adresse au sein du
.B noyau
de la structure dcrivant le module.
.br
La partie
.B name
de la structure contient le nom du module prcd par
.B #,
comme dans
.BR #my_module .
Le symbole dcrivant un module apparatra avant les symboles
dfinis par le module.

A la fin des symboles rsidents du noyau, apparatra
un symbole dont le nom sera
.B #.
Cette information peut servir  construire une table de
rfrence des modules o ils seront empils.

.TB
.B create_module(module_name, size)
allouera
.B size
octets dans l'espace du noyau pour un module, et
crera galement les structures internes au noyau pour
le nouveau module nomm
.B name.
Ce module existera ds lors dans l'espace du noyau avec
un statut
.B MOD_UNINITIALIZED.

.TB
.B init_module(module_name, code, codesize, routines, symtab)
est le vritable chargeur (loader) de module, qui
va insrer le module nomm
.B name
au sein du noyau.
Les paramtres
.B code
et
.B codesize
correspondent au code objet binaire du module, qui fait
.B codesize
octets de long.

Si l'on effectue un OU binaire entre le paramtre codesize
et MOD_AUTOCLEAN, le module sera soumis au nettoyage automatique,
c'est  dire l'limination priodique des modules inutiliss.
Les 4 premiers octets de l'image du module seront utiliss 
comme compteur de rfrence par le noyau, mis  jour par
les macros MOD_INC_USE_COUNT et MOD_DEC_USE_COUNT.
Ce compteur contiendra galement le bit  MOD_AUTOCLEAN 
et un bit  MOD_VISITED qui sont utiliss pour le nettoyage
automatique.

Les fonctions dcrites dans
.B routines
serviront  dmarrer et arrter le module.
Ces pointeurs devrat contenir l'adresse des fonctions
.B init_module()
et
.B cleanup_module()
dfinies pour tous les modules chargeables.
.br
Si un module dsire exporter des symboles en direction
d'autres modules, ou s'il fait rfrence  des symboles dfinis
par d'autres modules, le paramtre
.B symtab
doit pointer sur une structure les dcrivant.
Une valeur NULL pour
.B symtab
signifie qu'aucun symbole n'est export, et qu'aucune rfrence
aux autres modules n'est effectue.
.br
La 
.B symtab
qui sera copie dans le noyau consiste en une structure
.B symbol_table
suivie immdiatement par une table de chanes de caractres
contenant les noms des symboles dfinis par le module.
L'lment
.B size
doit inclure aussi la taille de la table de chanes.
.PP
.B Spcificits :

Les lments
.B n_symbols
et
.B n_refs
indiquent combien de symboles et combien de rfrences aux autres
modules sont inclus dans la structure
.B symbol_table.
Immdiatement aprs ces entiers se touve la table des symboles.
L'lment
.B name
dans chaque
.B struct internal_symbol
ne doit pas tre un pointeur classique, mais l'
.B offset
de la chane correspondante dans la table, relativement au dbut
de la structure symbol_table.
.PP
Aprs la liste de tous les symboles dfinis, la structure
symbol_table continue avec une table des rfrences de
modules, dcrites par les lments
.B struct module_ref.
Seul le champ
.B module
de ces structures doit tre initialis. Les adresses
de modules obtenues prcdemment avec
.B get_kernel_syms
pour les lments dont le nom commence par
.B #
doivent tre copies dans ces champs.
.PP
Si le module peut tre correctement charg, et si l'appel
de la fonction
.B init_module()
russit galement, le statut du module deviendra MOD_RUNNING.
Autrement, la mmoire du noyau occupe par le module sera
libre.

.B delete_module(module_name)
doit tre utilis pour dcharger un module.
Si le compteur de rfrences montre que le module n'est plus actif,
et qu'aucun autre modules n'y fait rfrence, sa fonction
.B cleanup_module()
sera appele.
Si toutes ces tapes russissent, la mmoire du noyau occupe
par le module et ses structures sera libre.
.PP
Remarquez que si l'argument de
.B delete_module
vaut NULL, le noyau supprimera tous les modules.
.SH DIAGNOSTIQUES
S'il se produit une erreur, toutes ces fonctions renverront \-1,
et la variable globale
.B errno
contiendra le code d'erreur.
Un message d'erreur sera galement affich sur la console.
.SH CONFORMIT
Ces appels systmes sont spcifiques  Linux, et ne doivent pas tre
employs dans des programmes dstines  tre portables.
Le support de module a t conu par Anonymous (si je me souviens bien).
.SH "VOIR AUSSI"
insmod(1), rmmod(1), lsmod(1), ksyms(1), genksyms(8)
.SH BUGS
Naan...

.SH TRADUCTION
Christophe Blaess, 1997.