libdatastr/doc/libdatastr.3

'\" t
.\" @(#)LIBDATASTR.3 99/10/12 SMI;
.TH LIBDATASTR 3 "10 Oct 1999"
.SH NOM
LIBDATASTR (librairie de structure de donnees a base de noeuds dans un contexte de memoire partagee)
.SH SYNOPSIS
.LP
.BI "cc [flag ...] file ... -lver -ldl -lnode -lshmem -ldatastr [library ...]"
.LP
.BI "#include <datastr.h>"
.LP
.BI "DST_Status DS_Library_Open ( int " Instance " , char * " Context_Name ", DST_Flags " Debug_Mode " );"
.LP
.BI "DST_Status DS_Library_Close ( " void " );
.LP
.BI "DST_Status DS_Library_Stderr_Set ( FILE * " Out " );"
.LP
.BI "DST_Status DS_DataStruct_Open ( char * " DS_Name ", NDT_Root ** " Root ", ND_DataStruct_Type " DS_Type ", char * " Manager_File_Name ", size_t " Segment_Size ", DST_Flags " Open_Mode ", int " Own_Values " );"
.LP
.BI "DST_Status DS_DataStruct_Lock ( NDT_Root * " Root ", DST_Flags " Lock_Mode " , int * " Locked " );"
.LP
.BI "DST_Status DS_DataStruct_Unlock ( NDT_Root * " Root " );"
.LP
.BI "DST_Status DS_DataStruct_Close ( NDT_Root * " Root ", DST_Flags " Close_Mode " );"
.LP
.BI "DST_Status DS_DataStruct_Info_Print ( NDT_Root * " Root ", FILE * " Out " );"
.LP
.BI "DST_Status DS_DataStruct_Reorg ( NDT_Root * " Root ");"
.LP
.BI "DST_Status DS_DataStruct_Traverse ( NDT_Root * " Root ", NDT_Command " Command ", void * " Data " );"
.LP
.BI "DST_Status DS_DataStruct_Convert ( NDT_Root * " Root ", NDT_DataStruct_Type " Target_Type " );"
.LP
.BI "DST_Status DS_DataStruct_Print ( NDT_Root * " Root ", FILE * " Out " );"
.LP
.BI "DST_Status DS_DataStruct_Check ( NDT_Root * " Root ", int * " Nb_Detected ", * int " Nb_Corrected ", FILE * " Out " );"
.LP
.BI "DST_Status DS_DataStruct_Dump ( NDT_Root * " Root ", FILE * " Out " );"
.LP
.BI "DST_Status DS_Node_First_Get ( NDT_Root * " Root ", NDT_Node ** " Node " );"
.LP
.BI "DST_Status DS_Node_Last_Get ( NDT_Root * " Root ", NDT_Node ** " Node " );"
.LP
.BI "DST_Status DS_Node_Next_Get ( NDT_Node * " Node ", NDT_Node ** " Next_Node " );"
.LP
.BI "DST_Status DS_Node_Previous_Get ( NDT_Node * " Node ", NDT_Node ** " Prev_Node " );"
.LP
.BI "DST_Status DS_Node_Add ( NDT_Root * " Root ", ND_Node * " Node " );"
.LP
.BI "DST_Status DS_Node_Remove (ND_Node * " Node " );"
.LP
.BI "DST_Status DS_Node_Find ( NDT_Root * " Root ", NDT_Node ** " Node ", void * " To_Search ", void * " Data " );"
.LP
.BI "DST_Status DS_Value_Alloc ( NDT_Root * " Root ", void ** " Value ", ... );"
.LP
.BI "DST_Status DS_Value_Add ( NDT_Root * " Root ", void * " To_Add " );"
.LP
.BI "DST_Status DS_Value_Remove ( NDT_Root * " Root ", void * " Reference_Value ", void ** " Removed_Value " );"
.LP
.BI "DST_Status DS_Value_Free ( NDT_Root * " Root ", void * " Value " );"
.LP
.BI "DST_Status DS_Alloc ( NDT_Root * " Root ", size_t " Size ", void ** " Ptr " );"
.LP
.BI "DST_Status DS_Free ( NDT_Root * " Root ", void * " Ptr " );"
.LP
.SH DESCRIPTION
.LP
La librairie LIBDATASTR implemente des structures de donnees a base de noeuds dans
un contexte de memoire partagee.
.LP
Elle est basee sur deux librairies sous-jacentes :
.LP
.RS 3
- LIBNODE
: gestion de structure a base de noeuds
.LP
- LIBSHMEM
: gestion de contextes de memoire partagee
.RS -3
.LP
La librairie LIBDATASTR gere les memes types de structure de donnees que la librairie LIBNODE
et propose les memes fonctionnalites que cette derniere.
.LP
L'utilisateur est donc prie de se referer a la documentation de la librairie LIBNODE
pour toute information relative aux structures de donnees manipulees.
.LP
La librairie LIBDATASTR propose une interface (API) tres similaire a celle de la librairie LIBNODE
.
.LP
Toutefois, une premiere difference reside dans le fait que chaque structure de donnees possede un nom.
Chaque structure pourra ainsi etre facilement identifiee dans la base de memoire partagee.
.LP
Par ailleurs, puisque chaque structure gere des valeurs qui lui sont propres, les fonctions de
manipulation (Manager, Allocator, Desallocator) de ces valeurs doivent aussi etre partageables.
C'est pourquoi chaque processus initiateur d'une structure doit fournir un fichier qui definit ces fonctions.
Le nom de ce fichier (.so) sera rattache a la racine de la structure lors de sa creation.
Ainsi, tout processus voulant acceder a une structure dont il ne connait pas les valeurs n'aura qu'a charger dynamiquement ce fichier pour pouvoir les manipuler.
.LP
.SH FONCTIONS
.LP
.BI "DST_Status DS_Library_Open ( int " Instance " , char * " Context_Name ", DST_Flags " Debug_Mode " );"
.RS 3
.LP
Permet d'acceder aux ressources de la librairie LIBDATASTR.
Elle permet notamment d'acceder a la base de memoire partagee d'une instance donnee (voir la librairie LIBSHMEM) et de manipuler des structures de donnees dans un contexte donne.
.LP
Cette fonction attend les arguments suivants :
.LP
.RS 3
- (In)
.I Instance
: designe le numero de l'instance a ouvrir.
.LP
Si cet argument est NULL, alors c'est la variable d'environnement $PROFILE qui definira le numero de l'instance.
.LP
- (In)
.I Context_Name
: designe le nom du contexte a utiliser.
.LP
- (In)
.I Debug_Mode
: mode d'affichage des messages d'erreur :
.LP
.RS 3
-
.B DS_DEBUG_NONE
: aucun message d'erreur n'est affiche
.LP
-
.B DS_DEBUG
: les messages d'erreur generes par la librairie LIBDATASTR sont affiches sur la sortie standard d'erreur
.LP
-
.B DS_DEBUG_ALL
: les messages d'erreur generes par toutes les librairies sous-jacentes a la LIBDATASTR sont affiches sur la sortie standard d'erreur
.RS -3
.LP
.RS -3
.I Rappels
: la notion de contexte permet de creer plusieurs environnements parfaitement distincts au sein d'une meme instance.
.LP
.I Important
: cette fonction devra etre systematiquement appelee au debut de chaque programme utilisant la librairie LIBDATASTR.
.LP
Cette fonction echouera si l'instance de la librairie LIBSHMEM n'a pas ete creee.
.LP
.RS -3
.BI "DST_Status DS_Library_Close ( " void " );"
.RS 3
.LP
Permet de fermer les ressources de l'instance de la librairie LIBDATASTR.
.I NB
: cette fonction etre systematiquement appelee a la fin de chaque programme utilisant la librairie LIBDATASTR.
.LP
.RS -3
.BI "DST_Status DS_Library_Stderr_Set ( FILE * " Out " );"
.LP
.RS 3
Cette fonction permet de definir
.I Out
comme la sortie standard des messages d'erreur de la librarie.
.RS -3
.LP
.BI "DST_Status DS_DataStruct_Open ( char * " DS_Name ", NDT_Root ** " Root ", ND_DataStruct_Type " DS_Type ", char * " Manager_File_Name ", size_t " Segment_Size ", DST_Flags " Open_Mode ", int " Own_Values " );"
.RS 3
.LP
Cette fonction permet d'ouvrir ou de creer une structure de donnees.
.LP
La fonction doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I DS_Name
: le nom de la structure de donnees
.LP
* (Out)
.I Root
: l'adresse du pointeur sur la racine de la structure de donnees
.LP
* (In)
.I DS_Type
: le type de la nouvelle structure de donnees.
Dans le cas de l'ouverture d'une structure de donnees existante, cet argument n'est pas pris en compte.
.LP
* (In)
.I Manager_File_Name
: le nom du fichier (.so) definissant les fonctions manager de la structure.
Dans le cas de l'ouverture d'une structure de donnees existante, cet argument n'est pas pris en compte.
.LP
* (In)
.I Segment_Size
: la taille des segments de donnees du heap sous-jacent.
Bien entendu, cet argument n'est pris en compte que lors de la creation d'une structure dans un nouveau heap.
.LP
* (In)
.I Open_Mode
: le mode d'ouverture pouvant prendre les valeurs suivantes combinees :
.LP
* (In)
.I Own_Values
: indique si la data structure est proprietaire de ses valeurs (TRUE ou FALSE) 
.LP
.RS 3
-
.B DSD_OPEN
pour autoriser l'ouverture d'une structure existante.
.LP
-
.B DSD_CREATE
pour autoriser la creation de la structure si elle n'existe pas.
.LP
-
.B DSD_NEW
pour autoriser la creation d'une autre structure dans le meme heap si elle existe deja.
.RS -3
.LP
.RS -3
.I NB
: une fois qu'une structure de donnees est ouverte, l'utilisateur est assure de son existence, au moins jusqu'a ce que celle-ci soit fermee. 
.LP
.I Information
: toutes les structures de donnees manipulees sont basees sur des heaps dont les noms seront prefixes par "datastr" afin d'indiquer que ces heaps ont ete crees par l'intermediaire de cette librairie.
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Lock ( NDT_Root * " Root ", DST_Flags " Lock_Mode " , int * " Locked " );"
.RS 3
.LP
Cette fonction permet de verrouiller une structure de donnees.
.LP
La fonction doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Lock_Mode
: le mode de verrouillage (
.B DSD_READ
ou
.B DSD_WRITE
)
.LP
* (Out)
.I Locked
: un pointeur sur un indicateur de verrouillage qui prendra la valeur :
.LP
.RS 3
- TRUE si le verrouillage est effectif
.LP
- FALSE si la structure etait deja verrouillee dans ce mode
.RS -3
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Unlock ( NDT_Root * " Root " );"
.RS 3
.LP
Cette fonction permet de deverrouiller une structure de donnees.
.LP
L'argument
.I Root
est un pointeur sur la racine de la structure de donnees a deverrouiller.
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Close ( NDT_Root * " Root ", DST_Flags " Close_Mode " );"
.RS 3
.LP
Cette fonction permet de fermer ou de detruire une structure de donnees.
.LP
La fonction doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Close_Mode
: le mode de fermeture (
.B DSD_CLOSE
ou
.B DSD_DESTROY
)
.RS -3
.LP
.I NB
: une structure de donnees ne pourra etre detruite que si elle n'est plus accedee par aucun autre processus.
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Info_Print ( NDT_Root * " Root ", FILE * " Out " );"
.RS 3
.LP
Cette fonction permet d'afficher les informations d'une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees.
.LP
* (In)
.I Out
: le flux de sortie de l'affichage.
.LP
.RS -3
.RS -3
.BI "DST_Status DS_DataStruct_Traverse ( NDT_Root * " Root ", NDT_Command " Command ", void * " Data " );"
.RS 3
.LP
Cette fonction permet de parcourir tous les noeuds d'une structure de donnees avec execution d'une commande sur chacun d'eux.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: le pointeur sur la racine de la structure de donnees a parcourir.
.LP
* (In)
.I Command
: la commande a executer sur chaque noeud traverse
.LP
* (In)
.I Data
: un pointeur de donnees propre a la commande
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Reorg ( NDT_Root * " Root ");
.RS 3
.LP
Cette fonction permet de reorganiser les donnees d'une structure (tri pour une liste, reequilibrage pour un arbre).
.LP
.I Root
est un pointeur sur la racine de la structure de donnees a reorganiser.
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Convert ( NDT_Root * " Root ", NDT_DataStruct_Type " Target_Type " );"
.RS 3
.LP
Cette fonction permet de convertir une structure de donnees d'un type en un autre.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees a convertir.
.LP
* (In)
.I Target_Type
: le type de la structure cible
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Print ( NDT_Root * " Root ", FILE * " Out " );"
.RS 3
.LP
Cette fonction permet d'afficher toutes les valeurs des noeuds d'une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: le pointeur sur la racine de la structure de donnees a afficher.
.LP
* (In)
.I Out
: un pointeur sur le flux de sortie
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Check ( NDT_Root * " Root ", int * " Nb_Detected ", * int " Nb_Corrected ", FILE * " Out " );"
.RS 3
.LP
Cette fonction realise des controles d'integrite sur une structure de donnees :
.LP
.RS 3
- controle du heap sous-jacent a la structure
.LP
- controle de la structure de noeuds
.LP
.RS -3
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees a corriger.
.LP
* (Out)
.I Nb_Detected
: un pointeur sur le nombre d'erreurs detectees.
.LP
* (Out)
.I Nb_Corrected
: un pointeur sur le nombre d'erreurs corrigees.
.LP
* (In)
.I Out
: un pointeur sur le flux de sortie du rapport.
.RS -3
.LP
.RS -3
.BI "DST_Status DS_DataStruct_Dump ( NDT_Root * " Root ", FILE * " Out " );"
.RS 3
.LP
Cette fonction permet d'afficher une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees a corriger.
.LP
* (In)
.I Out
: un pointeur sur le flux de sortie de l'affichage
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_First_Get ( NDT_Root * " Root ", NDT_Node ** " Node " );"
.LP
.RS 3
Cette fonction permet de recuperer le premier noeud d'une structure.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure
.LP
* (Out)
.I Node
: l'adresse d'un pointeur sur le premier noeud a recuperer
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Last_Get ( NDT_Root * " Root ", NDT_Node ** " Node " );"
.LP
.RS 3
Cette fonction permet de recuperer le dernier noeud d'une structure.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure
.LP
* (Out)
.I Node
: un pointeur sur le dernier noeud a recuperer
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Next_Get ( NDT_Node * " Node ", NDT_Node ** " Next_Node " );"
.LP
.RS 3
Cette fonction permet de recuperer le noeud qui suit immediatement un noeud particulier.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Node
: un pointeur sur le noeud de reference
.LP
* (Out)
.I Next_Node
: l'adresse d'un pointeur sur le noeud qui suit le noeud de reference
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Previous_Get ( NDT_Node * " Node ", NDT_Node ** " Prev_Node " );"
.LP
.RS 3
Cette fonction permet de recuperer le noeud qui precede immediatement un noeud particulier.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Node
: un pointeur sur le noeud de reference
.LP
* (Out)
.I Prev_Node
: l'adresse d'un pointeur sur le noeud qui precede le noeud de reference
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Add ( NDT_Root * " Root ", ND_Node * " Node " );"
.RS 3
.LP
Cette fonction permet d'ajouter un noeud a une structure.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Node
: un pointeur sur le noeud a ajouter
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Node_Remove (ND_Node * " Node " );"
.RS 3
.LP
Cette fonction permet de supprimer le noeud d'une structure de donnees.
.LP
.I Node
est un pointeur sur le noeud a supprimer.
.LP
.I NB
: le noeud supprime n'est pas detruit mais simplement detache de la structure
.LP
.RS -3
.BI "DST_Status DS_Node_Find ( NDT_Root * " Root ", NDT_Node ** " Node ", void * " To_Search ", void * " Data " );"
.RS 3
.LP
Cette fonction permet de rechercher dans une structure de donnees le premier noeud correspondant a une valeur.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (Out)
.I Node
: l'adresse d'un pointeur sur le noeud resultat
.LP
* (In)
.I To_Search
: un pointeur sur la valeur a rechercher
.LP
* (In)
.I Data
: un pointeur de donnees a passer au manager pour la recherche
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Value_Alloc ( NDT_Root * " Root ", void ** " Value ", ... );"
.LP
.RS 3
Cette fonction permet d'allouer une valeur pour une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (Out)
.I Value
: l'adresse d'un pointeur sur la valeur a allouer
.LP
* (In)
.I ...
: des arguments supplementaires pour l'allocation de la valeur
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Value_Add ( NDT_Root * " Root ", void * " To_Add " );"
.RS 3
.LP
Cette fonction permet d'ajouter une valeur a une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I To_Add
: un pointeur sur la valeur a ajouter
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Value_Remove ( NDT_Root * " Root ", void * " Reference_Value ", void ** " Removed_Value " );"
.RS 3
.LP
Cette fonction permet de supprimer une valeur d'une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.RS 3
.LP
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Reference_Value
: un pointeur sur la valeur de reference
.LP
* (Out)
.I Removed_Value
: l'adresse d'un pointeur sur la valeur du noeud supprime
.LP
.RS -3
.I NB
: la suppression d'un noeud implique son retrait de la structure et sa desallocation.
.LP
.RS -3
.BI "DST_Status DS_Value_Free ( NDT_Root * " Root ", void * " Value " );"
.LP
.RS 3
Cette fonction permet de desallouer une valeur faisant partie d'une structure de donnees.
.LP
Elle doit recevoir les arguments suivants :
.LP
.RS 3
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Value
: un pointeur sur la valeur a desallouer
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Alloc ( NDT_Root * " Root ", size_t " Size ", void ** " Ptr " );"
.RS 3
.LP
Cette fonction permet d'allouer de la memoire dans le meme contexte (meme heap) qu'une structure de donnees.
Elle sera utilisee notamment pour l'allocation des valeurs rattachees aux noeuds de la structure.
.LP
Elle doit recevoir les arguments suivants :
.RS 3
.LP
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Size
: la taille de la memoire a allouer.
.LP
* (Out)
.I Ptr
: l'adresse d'un pointeur sur la zone a allouer
.RS -3
.LP
.RS -3
.BI "DST_Status DS_Free ( NDT_Root * " Root ", void * " Ptr " );"
.RS 3
.LP
Cette fonction permet de liberer de la memoire qui a ete allouee dans le meme contexte qu'une structure de donnees (meme heap).
Elle sera utilisee notamment pour desallouer des valeurs rattachees aux noeuds de la structure.
.LP
Elle doit recevoir les arguments suivants :
.RS 3
.LP
* (In)
.I Root
: un pointeur sur la racine de la structure de donnees
.LP
* (In)
.I Ptr
: un pointeur sur la zone a desallouer.
.RS -3
.LP
.SH "CODES RETOUR"
.LP
Toutes les fonctions de la librairie LIBDATASTR retournent une valeur de type
.B DST_Status
:
.LP
.RS 3
-
.B DSS_OK
: la fonction s'est correctement executee et a produit un resultat
.LP
-
.B DSS_KO
: la fonction s'est correctement executee mais n'a pas produit de resultat
.LP
-
.B DSS_ERRAPI
: la fonction a ete appelee avec des arguments de valeur incorrecte
.LP
-
.B DSS_ERRMEM
: la fonction ne s'est pas correctement executee pour un probleme d'allocation memoire
.LP
-
.B DSS_ERRSHM
: la fonction ne s'est pas correctement executee pour un probleme relatif a la memoire partagee
.LP
-
.B DSS_ERRSIG
: une operation sur semaphore a ete interrompue par un signal
.LP
-
.B DSS_ERRSEM
: la fonction ne s'est pas correctement executee pour un probleme relatif a l'utilisation des semaphores
.LP
-
.B DSS_ERRDLL
: la fonction ne s'est pas correctement executee pour un probleme de chargement dynamique d'objet
.LP
.RS -3
.I NB
: la macro
.B DS_ERROR()
permet de tester si un code retour correspond a une erreur.
.LP
En cas d'erreur, la variable
.B DS_Error_Msg
contient un message du type :
.LP
.RS 3
Error <Nom fonction> : <message d'erreur>
.RS -3
.LP
.SH VOIR AUSSI
.B libnode
(3)
,
.B libshmem
(3)