libmsg/lib/libmsg.3

'\" t
.\" @(#)LIBMSG.3 1.0 00/07/04 SMA;
.TH LIBMSG 3 "07 Apr 2000"
.SH NOM
LIBMSG (librairie de communication inter-processus par messages)
.SH SYNOPSIS
.LP
.BI "cc [flag ...] file ... -lver -ldl -lnode -lshmem -ldatastr -lmsg [library ...]"
.LP
.BI "#include <msg.h>"
.LP
.BI "MSGT_Status MSG_Library_Open ( int " Instance ", const char * " Context ", MSGT_Flags " Open_Mode " );"
.LP
.BI "MSGT_Status MSG_Library_IsOpen ( void );"
.LP
.BI "MSGT_Status MSG_Library_Signal ( void );"
.LP
.BI "MSGT_Status MSG_Library_Close ( MSGT_Flags " Close_Mode " );"
.LP
.BI "MSGT_Status MSG_Library_Stderr_Set ( FILE * " Out " );"
.LP
.BI "MSGT_Status MSG_Library_Dump ( FILE * " Out " );"
.LP
.BI "MSGT_Status MSG_Port_Open ( int " Id ", MSGT_Port ** " Port ", MSGT_Flags " Open_Mode " );"
.LP
.BI "MSGT_Status MSG_Port_Lock ( MSGT_Port * " Port ", MSGT_Flags " Mode " );"
.LP
.BI "MSGT_Status MSG_Port_Unlock ( MSGT_Port * " Port ", MSGT_Flags " Mode " );"
.LP
.BI "MSGT_Status MSG_Port_Config ( MSGT_Port * " Port ", MSGT_Config " Tag ", " ... " );"
.LP
.BI "MSGT_Status MSG_Port_Close ( MSGT_Port * " Port ", MSGT_Flags " Close_Mode " );"
.LP
.BI "MSGT_Status MSG_PortList_Open ( MSGT_PortList ** " PortList " );"
.LP
.BI "MSGT_Status MSG_PortList_Port_Add ( MSGT_PortList * " PortList ", MSGT_Port * " Port " );"
.LP
.BI "MSGT_Status MSG_PortList_Port_Remove ( MSGT_PortList * " PortList ", MSGT_Port * " Port " );"
.LP
.BI "MSGT_Status MSG_PortList_Close ( MSGT_PortList * " PortList " );"
.LP
.BI "MSGT_Status MSG_PortList_Listen ( MSGT_PortList * " PortList ", unsigned int " Type ", MSGT_Message ** " Msg ", MSGT_Flags " Flags " );"
.LP
.BI "MSGT_Status MSG_Message_Alloc ( MSGT_Message ** " Msg ", size_t " Size " );"
.LP
.BI "MSGT_Status MSG_Message_Config ( MSGT_Message * " Msg ", MSGT_Config " Tag ", " ... " );"
.LP
.BI "MSGT_Status MSG_Message_Free ( MSGT_Message * " Msg " );"
.LP
.BI "MSGT_Status MSG_Message_Send ( MSGT_Port * " From ", , MSGT_Port * " To ", MSGT_Message * " Msg " );"
.LP
.BI "MSGT_Status MSG_Message_Receive ( MSGT_Port * " Port ", unsigned int " Type ", MSGT_Message ** " Msg ", MSGT_Flags " Flags " );"
.LP
.BI "MSGT_Status MSG_Message_Reply ( MSGT_Message * " Msg " );"
.LP
.BI "MSGT_Status MSG_Message_Return ( MSGT_Message * " Msg " );"
.LP
.SH "CODES RETOUR"
.LP
Toutes les fonctions constituant l'API de la librairie LIBMSG retournent un code de type
.B MSGT_Status
:
.LP
.RS 3
-
.B MSGS_OK
: la fonction s'est correctement executee et a produit un resultat
.LP
-
.B MSGS_KO
: la fonction s'est correctement executee mais n'a pas produit de resultat
.LP
-
.B MSGS_ERRAPI
: la fonction a ete appelee avec des arguments de valeur incorrecte
.LP
-
.B MSGS_ERRMEM
: la fonction ne s'est pas correctement executee pour un probleme d'allocation memoire
.LP
-
.B MSGS_ERRSHM
: la fonction ne s'est pas correctement executee pour un probleme relatif a la memoire partagee
.LP
-
.B MSGS_ERRSEM
: la fonction ne s'est pas correctement executee pour un probleme relatif a l'utilisation des semaphores
.LP
-
.B MSGS_ERRSIG
: une operation sur semaphore a ete interrompue par un signal
.LP
-
.B MSGS_ERRNOWAIT
: une operation sur semaphore n'a pas pu etre realisee et le mode d'operation est sans attente
.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 MSG_ERROR()
permet de tester si un code retour correspond a une erreur.
.LP
En cas d'erreur, la variable MSG_Error_Message contient un message du type :
.LP
.RS 3
Error <Nom fonction> : <message d'erreur>
.RS -3
.LP
Pour les fonctions de reception de messages, 3 codes retour supplementaires ont ete definis :
.LP
.RS 3
-
.B MSGS_NO_MSG
si aucun message n'a ete trouve dans le(s) port(s) de messages ecoute(s)
.LP
-
.B MSGS_BAD_TYPE
si des messages sont presents mais qu'aucun ne correspond au type de message demande.
.LP
-
.B MSGS_SIGNAL
si l'ecoute du port a ete interrompue par un signal systeme.
.RS -3
.LP
.SH "FONCTIONS"
.LP
.BI "MSGT_Status MSG_Library_Open ( int " Instance ", const char * " Context ", MSGT_Flags " Open_Mode " );"
.RS 3
.LP
La librairie LIBMSG implemente une base qui reference tous les ports de messages et tous les messages crees.
.LP
Cette fonction permet donc d'acceder a toutes ces ressources pour un contexte et une instance donnes designes par leur nom
.I Context 
et
.I Instance
:
.LP
.RS 3
- en ouverture simple si
.I Open_Mode
vaut
.B MSGD_OPEN
.LP
- en creation si
.I Open_Mode
vaut
.B MSGD_CREATE
.RS -3
.LP
.I NB
: l'indicateur d'ouverture
.I Open_Mode
pourra etre combinee avec un mode de debugging (
.B MSGD_DEBUG_NONE
: aucun message d'erreur n'est affiche
.LP
.B MSGD_DEBUG
: les messages d'erreur generes par la librairie LIBMSG sont affiches sur la sortie standard d'erreur
.LP
.B MSGD_DEBUG_ALL
: les messages d'erreur generes par toutes les librairies sous-jacentes a la LIBMSG sont affiches sur la sortie standard d'erreur
.LP
.I NB
: l'ouverture de la librairie en creation est reservee aux administrateurs.
.LP
L'ouverture de la librairie est obligatoire avant d'utiliser toute autre fonction de la librairie LIBMSG.
.LP
.RS -3
.LP
.BI "MSGT_Status MSG_Library_Signal ( void );"
.RS 3
.LP
Cette fonction permet d'informer la librairie LIBMSG de la reception d'un signal systeme.
.LP
.I NB
: cette fonction sera utile a l'utilisateur pour eviter que le processus reste bloque sur une attente de message malgre la reception de signal.
.RS -3
.LP
.BI "MSGT_Status MSG_Library_IsOpen ( void );"
.RS 3
.LP
Cette fonction permet de tester si une instance de la librairie LIBMSG a deja ete ouverte.
.RS -3
.LP
.BI "MSGT_Status MSG_Library_Close ( MSGT_Flags " Close_Mode " );"
.RS 3
.LP
Cette fonction permet de fermer toutes les ressources de l'instance de la librairie ouverte :
.LP
.RS 3
- fermeture simple si
.I Close_Mode
vaut
.B MSGD_CLOSE
.LP
- destruction si
.I Close_Mode
vaut
.B MSGD_DESTROY
.RS -3
.LP
.I NB
: l'utilisation du parametre
.B MSGD_DESTROY
est reservee aux administrateurs.
.LP
.RS -3
.BI "MSGT_Status MSG_Library_Dump ( FILE * " Out " );"
.RS 3
.LP
Cette fonction permet d'afficher toutes les ressources de l'instance de la librairie ouverte.
.LP
L'argument
.I Out
designe le flux de sortie de l'affichage.
.LP
.RS -3
.BI "MSGT_Status MSG_Port_Open ( int " Id ", MSGT_Port ** " Port ", MSGT_Flags " Open_Mode " );"
.LP
.RS 3
Cette fonction permet d'ouvrir un port de messages.
.LP
Elle requiert les arguments suivants :
.RS 3
.LP
* (In)
.I Id
: l'identifiant numerique du port de messages
.LP
* (Out)
.I Port
: l'adresse d'un pointeur sur le port de messages
.LP
* (In)
.I Open_Mode
: le mode d'ouverture du port de messages
.LP
.RS 3
- en ouverture simple si
.I Open_Mode
vaut
.B MSGD_OPEN
.LP
- en creation si
.I Open_Mode
vaut
.B MSGD_CREATE
.RS -3
.RS -3
.LP
.RS -3
.BI "MSGT_Status MSG_Port_Lock ( MSGT_Port * " Port ", MSGT_Flags " Mode " );"
.RS 3
.LP
Cette fonction permet de verrouiller un port de messages.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Port
: un pointeur sur le port de messages a verrouiller
.LP
* (In)
.I Mode
: le mode de verrouillage (
.B MSGD_READ
ou
.B MSGD_WRITE
)
.LP
.RS -3
.LP
.RS -3
.BI "MSGT_Status MSG_Port_Unlock ( MSGT_Port * " Port ", MSGT_Flags " Mode " );"
.RS 3
.LP
Cette fonction permet d'oter le verrou pose sur un port de messages.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Port
: un pointeur sur le port de messages a deverrouiller
.LP
* (In)
.I Mode
: le mode dans lequel le port est verrouille (
.B MSGD_READ
ou
.B MSGD_WRITE
)
.LP
.RS -3
.LP
.RS -3
.BI "MSGT_Status MSG_Port_Config ( MSGT_Port * " Port ", MSGT_Config " Tag ", " ... " );"
.RS 3
.LP
Cette fonction permet de configurer un port de messages.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Port
: un pointeur sur le port de messages a configurer
.LP
* (In)
.I Tag
: le type de configuration (
.B MSGD_CONFIG_SIZE
)
.LP
* (In)
.I ...
: la ou les valeurs utiles (fonction du type de configuration)
.LP
.RS -3
.LP
.RS -3
.BI "MSGT_Status MSG_Port_Close ( MSGT_Port * " Port ", MSGT_Flags " Close_Mode " );"
.RS 3
.LP
Cette fonction permet de fermer un port de messages.
.LP
Elle requiert les arguments suivants :
.RS 3
.LP
* (In)
.I Port
: un pointeur sur le port de messages a fermer
.LP
* (In)
.I Close_Mode
: le mode de fermeture du port de messages
.LP
.RS 3
- fermeture simple si
.I Close_Mode
vaut
.B MSGD_CLOSE
.LP
- destruction si
.I Close_Mode
vaut
.B MSGD_DESTROY
.RS -3
.RS -3
.LP
.RS -3
.BI "MSGT_Status MSG_PortList_Open ( MSGT_PortList ** " PortList " );"
.RS 3
.LP
Cette fonction permet d'ouvrir une liste de ports de messages.
.LP
L'argument
.I PortList
est l'adresse d'un pointeur sur la liste de port a creer.
.LP
.I NB
: une liste de ports permet a un processus d'ecouter plusieurs ports de messages simultanement.
Une liste de ports n'est pas partageable entre les processus.
.LP
.RS -3
.BI "MSGT_Status MSG_PortList_Port_Add ( MSGT_PortList * " PortList ", MSGT_Port * " Port " );"
.RS 3
.LP
Cette fonction permet d'ajouter un port de messages a une liste de ports.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I PortList
: un pointeur sur une liste de ports
.LP
* (In)
.I Port
: un pointeur sur le port de messages a ajouter
.LP
.RS -3
.LP
.RS -3
.BI "MSGT_Status MSG_PortList_Port_Remove ( MSGT_PortList * " PortList ", MSGT_Port * " Port " );"
.RS 3
.LP
Cette fonction permet de retirer un port de messages d'une liste de ports.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I PortList
: un pointeur sur une liste de ports
.LP
* (In)
.I Port
: un pointeur sur le port de messages a retirer
.LP
.RS -3
.LP
.RS -3
.BI "MSGT_Status MSG_PortList_Close ( MSGT_PortList * " PortList " );"
.RS 3
.LP
Cette fonction permet de detruire une liste de ports de messages.
.LP
L'argument
.I PortList
est un pointeur sur la liste de port a supprimer.
.LP
.I NB
: lorsqu'un processus ajoute un port de messages a sa liste de ports, le port de messages memorise le fait que le processus doit etre averti si un message y est ajoute ou retire.
Il est donc important que chaque processus detruise explicitement toutes les listes de ports qu'il a creees lorsque celles-ci ne sont plus utilisees.
.LP
.RS -3
.BI "MSGT_Status MSG_PortList_Listen ( MSGT_PortList * " PortList ", unsigned int " Type ", MSGT_Message ** " Msg ", MSGT_Flags " Flags " );"
.RS 3
.LP
Cette fonction permet de receptionner un message a partir d'une liste de ports.
La notion d'ecoute correspond au fait qu'un processus pourra se mettre en attente jusqu'a ce qu'un message soit envoye sur l'un des ports.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Port
: un pointeur sur la liste de ports
.LP
* (In)
.I Type
: le type du message a receptionner (la valeur
.B MSGD_NO_TYPE
permet de ne specifier aucun type en particulier)
.LP
* (Out)
.I Msg
: l'adresse d'un pointeur sur le message a receptionner.
.LP
* (In)
.I Flags
: le type d'ecoute (avec attente :
.B MSGD_WAIT
, sans attente :
.B MSGD_NOWAIT
)
.LP
.RS -3
.I NB
: pour une ecoute avec attente, un processus sera reveille a chaque fois qu'un message arrive dans l'un des ports de la liste. Il pourra toutefois se remettre en attente si le message a ete receptionne par un autre processus ou bien si son type n'est pas celui demande.
.LP
.I NB
: la recherche des messages dans les differents ports de la liste s'effectue dans l'ordre dans lequel ils ont ete ajoute a la liste.
.LP
.RS -3
.BI "MSGT_Status MSG_Message_Alloc ( MSGT_Message ** " Msg ", size_t " Size " );"
.RS 3
.LP
Cette fonction permet de creer un message et d'allouer de la memoire pour les donnees associees au message.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (Out)
.I Msg
: l'adresse d'un pointeur sur le message a creer
.LP
* (In)
.I Size
: la taille des donnees du message
.RS -3
.LP
.I NB
: l'utilisateur pourra modifier a sa guise la zone de donnees du message pointee par le champ
.B Data
du message.
Il veillera toutefois a ne pas deborder en dehors de cette zone auquel cas le fonctionnement de la librairie pourrait etre corrompue.
.LP
.RS -3
.BI "MSGT_Status MSG_Message_Config ( MSGT_Message * " Msg ", MSGT_Config " Tag ", " ... " );"
.RS 3
.LP
Cette fonction permet de configurer un message.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Msg
: un pointeur sur le message a configurer
.LP
* (In)
.I Tag
: le type de configuration (
.B MSGD_CONFIG_TYPE
,
.B MSGD_CONFIG_PRIORITY
)
.LP
* (In)
.I ...
: la ou les valeurs utiles (fonction du type de configuration)
.RS -3
.LP
.RS -3
.BI "MSGT_Status MSG_Message_Free ( MSGT_Message * " Msg " );"
.RS 3
.LP
Cette fonction permet de supprimer un message de la base de la librairie LIBMSG.
.LP
L'argument
.I Msg
est un pointeur sur le message a supprimer.
.LP
.I NB
: l'utilisateur veillera a ne pas supprimer les messages de maniere inconsideree, ceux-ci pouvant etre en cours d'envoi dans un port de messages.
.LP
Les regles d'usage veulent que ce soit le processus initiateur d'un message qui le supprime.
Dans le cas ou les messages ne sont pas renvoyes au processus initiateur, c'est le processus qui receptionne le message qui le supprimera.
.LP
.RS -3
.BI "MSGT_Status MSG_Message_Send ( MSGT_Port * " From ", , MSGT_Port * " To ", MSGT_Message * " Msg " );"
.RS 3
.LP
Cette fonction permet d'envoyer un message dans un port de messages.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I From
: un pointeur sur le port de l'emetteur du message
.LP
* (In)
.I To
: un pointeur sur le port destinataire du message
.LP
* (In)
.I Msg
: un pointeur sur le message a envoyer
.LP
.RS -3
.I NB
: un message ne pourra pas etre envoye simultanement dans plusieurs ports de messages.
.LP
.RS -3
.BI "MSGT_Status MSG_Message_Receive ( MSGT_Port * " Port ", unsigned int " Type ", MSGT_Message ** " Msg ", MSGT_Flags " Flags " );"
.RS 3
.LP
Cette fonction permet de receptionner un message dans un port de messages.
.LP
Elle requiert les arguments suivants :
.LP
.RS 3
* (In)
.I Port
: un pointeur sur le port de messages a ecouter
.LP
* (In)
.I Type
: le type du message a receptionner (la valeur
.B MSGD_NO_TYPE
permet de ne specifier aucun type en particulier)
.LP
* (Out)
.I Msg
: l'adresse d'un pointeur sur le message a receptionner.
.LP
* (In)
.I Flags
: le type d'ecoute (avec attente :
.B MSGD_WAIT
, sans attente :
.B MSGD_NOWAIT
)
.LP
.RS -3
.I NB
: la reception d'un message ne fait que retirer celui-ci du port de messages.
Le message n'est donc pas supprime et pourra en consequence etre envoye a nouveau dans une autre port de messages.
.LP
Pour une reception avec attente, un processus sera reveille a chaque fois qu'un message arrive dans le port de la liste.
.LP
Independamment du type demande, les messages sont receptionnes selon leur priorite puis selon leur ordre d'envoi.
.LP
.RS -3
.BI "MSGT_Status MSG_Message_Reply ( MSGT_Message * " Msg " );"
.RS 3
.LP
Cette fonction permet de renvoyer un message a son envoyeur.
.LP
.I NB
: l'envoyeur devra alors avoir precise l'identifiant de son port d'ecoute dans le champ
.B From
du message
.I Msg
.
.LP
.RS -3
.BI "MSGT_Status MSG_Message_Return ( MSGT_Message * " Msg " );"
.RS 3
.LP
Cette fonction permet de renvoyer un message au processus initiateur du message (different de l'envoyeur si le message passe entre plusieurs mains.
.LP
.I NB
: l'initiateur du message devra alors avoir precise l'identifiant de son port d'ecoute dans le champ
.B Init
du message
.I Msg
.
.LP
.RS -3