Loading

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, &not) == -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> ».