NOM
mq_notify - S’enregistrer pour la réception d’une notification de
l’arrivée d’un nouveau message
SYNOPSIS
#include <mqueue.h>
mqd_t mq_notify(mqd_t mqdes, const struct sigevent *notification);
Effectuez l’édition des liens avec l’option -lrt.
mq_notify() permet à un processus appelant de s’enregistrer ou de ne
plus s’enregistrer pour délivrer une notification asynchrone lorsqu’un
message entre dans une file de messages vide référencée par le
descripteur mqdes.
L’argument notification est un pointeur vers une structure sigevent qui
est définie comme suit :
union sigval { /* Data passed with notification */
int sival_int; /* Integer value */
void *sival_ptr; /* Pointer value */
};
struct sigevent {
int sigev_notify; /* Notification method */
int sigev_signo; /* Notification signal */
union sigval sigev_value; /* Data passed with
notification */
void (*sigev_notify_function) (union sigval);
/* Function for thread
notification */
void *sigev_notify_attributes;
/* Thread function attributes */
};
Si notification est un pointeur non NULL, alors mq_notify() enregistre
le processus appelant afin de recevoir les notifications. Le champ
sigev_notify de sigevent qui pointe vers notification spécifie comment
la notification est réalisée. Ce champ possède l’une des valeurs
suivantes :
SIGEV_NONE
Une notification « null » : le processus appelant est enregistré
comme destinataire des notifications, mais aucune notification
n’est envoyée lorsqu’un message arrive.
SIGEV_SIGNAL
Notifier le processus en envoyant le signal spécifié dans
sigev_signo. Si le signal est attrapé par un gestionnaire de
signaux qui a été enregistré avec sigaction(2) et le drapeau
SA_SIGINFO, alors les champs suivants sont définis dans la
structure siginfo_t qui est passée en second argument du
gestionnaire : si_code est défini à SI_MESGQ ; si_signo est
défini au numéro du signal ; si_value est défini à la valeur
spécifiée par notification->sigev_value ; si_pid est défini au
pid du processus qui a envoyé le message ; et si_uid est défini
à l’UID du processus qui a envoyé le message. Les mêmes
informations sont disponibles si le signal est accepté avec
sigwaitinfo(2).
SIGEV_THREAD
Envoyer des notifications en invoquant
notification->sigev_notify_function comme fonction de démarrage
d’un nouveau thread. La fonction est invoquée avec
notification->sigev_value comme seul argument. Si
notification->sigev_notify_attributes est non NULL, alors elle
doit pointer vers une structure pthread_attr_t qui définit les
attributs du thread (consultez pthread_attr_init(3)).
Seul un processus peut être enregistré pour recevoir les notifications
d’une file de messages.
Si notification est NULL, et si le processus appelant est actuellement
enregistré pour recevoir des notifications de cette file de messages,
alors l’enregistrement est supprimé ; un autre processus peut
s’enregistrer pour recevoir les notifications de cette file.
Une notification de message n’est créée que lorsqu’un nouveau message
arrive et que la file est vide. Si la file n’est pas vide à ce moment,
mq_notify() est appelée, alors une notification sera créée après que la
file soit vidée et qu’un nouveau message arrive.
Si un autre processus ou thread attend pour lire un message d’une file
vide avec mq_receive(3), alors tout enregistrement de notification de
message est ignoré : le message est délivré au processus ou au thread
appelant avec mq_receive(3) et l’enregistrement de notification de
message garde son effet.
Une notification apparaît une seule fois : après qu’une notification
soit délivrée, l’enregistrement de notification est supprimé et d’autre
processus peuvent s’enregistrer. Si le processus notifié souhaite
recevoir la prochaine notification, il peut utiliser mq_notify() pour
demander une autre notification. Cela doit être fait avant de vider
tous les messages non lus de la file (Placer la file en mode non
bloquant est utile pour la vider sans la bloquer une seule fois si elle
est vide).
VALEUR RENVOYÉE
Si elle réussit, la fonction mq_notify() renvoie 0. En cas d’erreur,
elle renvoie -1 et définit errno en conséquence.
ERREURS
EBADF Le descripteur spécifié dans mqdes n’est pas valable.
EBUSY Un autre processus est déjà enregistré pour recevoir les
notifications de cette file de messages.
EINVAL notification->sigev_notify n’est pas l’une des valeurs
permises ; ou notification->sigev_notify vaut SIGEV_SIGNAL et
notification->sigev_signo n’est pas un numéro de signal valable.
ENOMEM Mémoire insuffisante.
POSIX.1-2008 dit qu’une implémentation pourrait générer une erreur
EINVAL si notification est NULL et si l’appelant n’a pas souscrit aux
notifications de la file mqdes.
CONFORMITÉ
POSIX.1-2001.
EXEMPLE
Le programme suivant enregistre une requête de notification pour une
file de messages nommée avec l’un des arguments de la ligne de
commande. La notification est réalisée en créant un thread. Le thread
exécute une fonction qui lit un message provenant de la file puis le
processus se termine.
#include <pthread.h>
#include <mqueue.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#define handle_error(msg) \
do { perror(msg); exit(EXIT_FAILURE); } while (0)
static void /* Thread start function */
tfunc(union sigval sv)
{
struct mq_attr attr;
ssize_t nr;
void *buf;
mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
/* Determine max. msg size; allocate buffer to receive msg */
if (mq_getattr(mqdes, &attr) == -1)
handle_error("mq_getattr");
buf = malloc(attr.mq_msgsize);
if (buf == NULL)
handle_error("malloc");
nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
if (nr == -1)
handle_error("mq_receive");
printf("Read %ld bytes from MQ\n", (long) nr);
free(buf);
exit(EXIT_SUCCESS); /* Terminate the process */
}
int
main(int argc, char *argv[])
{
mqd_t mqdes;
struct sigevent not;
if (argc != 2) {
fprintf(stderr, "Usage: %s <mq-name>\n", argv[0]);
exit(EXIT_FAILURE);
}
mqdes = mq_open(argv[1], O_RDONLY);
if (mqdes == (mqd_t) -1)
handle_error("mq_open");
not.sigev_notify = SIGEV_THREAD;
not.sigev_notify_function = tfunc;
not.sigev_notify_attributes = NULL;
not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
if (mq_notify(mqdes, ¬) == -1)
handle_error("mq_notify");
pause(); /* Le processus sera terminé par la fonction du proc. */
}
VOIR AUSSI
mq_close(3), mq_getattr(3), mq_open(3), mq_receive(3), mq_send(3),
mq_unlink(3), mq_overview(7)
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».