Provided by: manpages-fr-dev_2.64.1-1_all bug

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);

DESCRIPTION

       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 {                /* Données passées avec la notification */
             int     sival_int;        /* Entier */
             void   *sival_ptr;        /* Pointeur */
         };

         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_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
              Délivrer        des       notifications       en       invoquant
              <notification->sigev_thread_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.

       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 Pas assez de mémoire.

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 <assert.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       #define die(msg) { perror(msg); exit(EXIT_FAILURE); }

       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)
               die("mq_getattr");
           buf = malloc(attr.mq_msgsize);
           if (buf == NULL)
               die("malloc");

           nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
           if (nr == -1)
               die("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;

           assert(argc == 2);

           mqdes = mq_open(argv[1], O_RDONLY);
           if (mqdes == (mqd_t) -1)
               die("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)
               die("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)

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> ».