libver/doc/libver.3

'\" t
'." @(#)LIBVER.3 2.0 00/06/30 SMA;
.TH LIBVER 3 "01 Apr 2000"
.SH NOM
LIBVER (utilitaires divers)
.SH SYNOPSIS
.LP
.B cc [flag ...] file ... -lver [library ...]
.LP
.BI "#include <ver.h>"
.LP
.BI "VER_INFO_EXPORT( " Object_Name ", " Version ", " CVS_Tag ", " Src_File ", " Author " )"
.LP
.BI "VERT_Status VER_Object_Print ( FILE * " Stream ", VERT_Print_Mode " Print_Mode " );"
.LP
.BI "VERT_Status VER_Info_Next_Get(VERT_Info_Container ** " Container ", VERT_Object * " Object ", VERT_Index * " Index " );"
.LP
.BI "VERT_Status VER_Info_Print(FILE * " Out ", VERT_Info_Container * " Container ", VERT_Print_Mode " Print_Mode " );"
.LP
.SH DESCRIPTION
.LP
La librairie
.B LIBVER
permet a un objet (programme ou librairie) de partager ses informations concernant :
.LP
.RS 3
- son nom
.LP
- sa version
.LP
- son tag CVS
.LP
- le nom de son fichier source
.LP
- l'auteur de son fichier source
.RS -3<>
.LP
La librairie fournit aussi des fonctions d'acces aux informations partagees 
par tous les objets (statiques (.o) ou partages (.so)) dont depend l'objet courant.
.LP
.SH "FONCTIONS & MACRO"
.LP
.BI "VER_INFO_EXPORT(" Object_Name ", " Version ", " CVS_Tag ", " Src_File ", " Author " )"
.RS 3
.LP
Cette macro est interpretee par le preprocesseur C.
Elle permet de generer une fonction C qui exporte les informations de l'objet courant via les API internes de la librairie.
.LP
Cette macro doit recevoir les parametres suivants :
.LP
.RS 3
- (In)
.I Object_Name
: le nom de l'objet (sans guillemets car utilise pour generer le nom de la fonction)
.LP
- (In)
.I Version
: la version de l'objet (entre guillemets)
.LP
- (In)
.I CVS_Tag
: le tag CVS (entre guillemets)
.LP
- (In)
.I Src_File
: le nom du fichier source (entre guillemets)
.LP
- (In)
.I Author
: le nom de l'auteur du fichier (entre guillemets)
.RS -3
.LP
.I NB
: la macro attend des parametres separes par des virgules.
.LP
Chaque fichier voulant exporter ses informations doit definir une instruction ressemblant a ce qui suit :
.LP
.RS 3
VER_INFO_EXPORT(terminator, "1.0", "tag-schwartzy-1_0_0-1", "terminator.c", "Sarah Connors")
.RS -3
.LP
L'instruction pourra se baser sur des mots-cle du preprocesseur ou sur ceux de CVS :
.LP
.RS 3
VER_INFO_EXPORT(monobjet, "$ Revision $", "$ Name $", __FILE__, "$ Author $")
.RS -3
.LP
.RS -3
.LP
.BI "VERT_Status VER_Object_Print ( FILE * " Out ", VERT_Print_Mode " Print_Mode " );"
.RS 3
.LP
Cette fonction permet d'afficher les informations concernant l'objet appelant:
.LP
Elle doit recevoir les parametres suivants :
.LP
.RS 3
- (In)
.I Out
: le flux de sortie de l'affichage
.LP
- (In)
.I Print_Mode
: le mode d'affichage :
.LP
.RS 3
-
.B VERD_MINIMAL
: affichage du nom, de la version et du tag CVS de l'objet appelant.
.LP
-
.B VERD_VERBOSE
: affichage sous forme de tableau de toutes les informations de l'objet appelant et de tous les objets dont il depend.
.LP
.RS -3
.RS -3
.RS -3
.LP
.BI "VERT_Status VER_Info_Next_Get(VERT_Info_Container ** " Container ", VERT_Object * " Object ", VERT_Index * " Index " );"
.RS 3
.LP
Cette fonction permet de recuperer un conteneur d'informations.
.LP
Elle doit recevoir les parametres suivants :
.LP
.RS 3
- (Out)
.I Container
: l'adresse d'un pointeur sur le conteneur a recuperer
.LP
- (In Out)
.I Object
: un pointeur sur l'objet a partir duquel on recherche le conteneur
.LP
- (In Out)
.I Index
: un pointeur sur l'index a partir duquel on recherche le conteneur
.LP
.RS -3
.LP
.I NB
: un objet peut avoir plusieurs conteneurs s'il a ete construit a partir de plusieurs objets statiques (.o).
.LP
L'index permet de distinguer les differents conteneurs d'un meme objet. Il commence a 0.
.LP
Le premier objet correspond a l'objet appelant (deuxieme parametre valorise a NULL).
.LP
Les objets suivants sont des objets partages (.so) dont depend l'objet appelant.
.LP
Si un conteneur a pu etre trouve, l'objet et l'index correspondant a ce conteneur sont alors mis a jour.
.LP
.RS -3
.BI "VERT_Status VER_Info_Print(FILE * " Out ", VERT_Info_Container * " Container ", VERT_Print_Mode " Print_Mode " );"
.RS 3
.LP
Cette fonction permet d'afficher les informations d'un conteneur :
.LP
Elle doit recevoir les parametres suivants :
.LP
.RS 3
- (In)
.I Out
: le flux de sortie de l'affichage
.LP
- (In)
.I Container
: un pointeur sur le conteneur a afficher
.LP
- (In)
.I Print_Mode
: le mode d'affichage :
.LP
.RS 3
-
.B VERD_MINIMAL
: affichage du nom, de la version et du tag CVS du conteneur
.LP
-
.B VERD_VERBOSE
: affichage de toutes les informations du conteneur
.LP
.RS -3
.RS -3
.RS -3
.SH CODES RETOUR
.LP
Toutes les fonctions constituant l'API de la librairie LIBVER retournent un code de type
.B VERT_Status
:
.LP
.RS 3
-
.B VERS_OK
: la fonction s'est correctement executee et a produit un resultat
.LP
-
.B VERS_KO
: la fonction s'est correctement executee mais n'a pas produit de resultat
.LP
-
.B VERS_ERRAPI
: la fonction a ete appelee avec des arguments de valeur incorrecte
.LP
-
.B VERS_ERRMEM
: la fonction ne s'est pas correctement executee pour un probleme d'allocation memoire
.RS -3
.LP
La macro
.B VER_ERROR(rc)
permet de tester si un code retour correspond a une erreur.
.LP
En cas d'erreur, la variable VER_Error_Msg contient un message du type :
.LP
.RS 3
Error <Nom fonction> : <message d'erreur>
.RS -3
.LP