Provided by: manpages-fr-dev_4.13-4_all bug

NOM

       getaddrinfo_a, gai_suspend, gai_error, gai_cancel - Traduction asynchrone d'adresses et de
       services réseau

SYNOPSIS

       #define _GNU_SOURCE         /* Consultez feature_test_macros(7) */
       #include <netdb.h>

       int getaddrinfo_a(int mode, struct gaicb *list[],
                       int nitems, struct sigevent *sevp);

       int gai_suspend(const struct gaicb * const list[], int nitems,
                       const struct timespec *timeout);

       int gai_error(struct gaicb *req);

       int gai_cancel(struct gaicb *req);

       Effectuez l'édition des liens avec l'option -lanl.

DESCRIPTION

       La fonction getaddrinfo_a() effectue la même opération  que  getaddrinfo(3),  mais  permet
       d'effectuer  plusieurs résolutions de manière asynchrone et de recevoir une notification à
       chaque résolution effectuée.

       Le champ mode peut prendre une des valeurs suivantes :

       GAI_WAIT
              Effectue les  résolutions  de  manière  synchrone.  L'appel  bloque  tant  que  les
              résolutions ne sont pas terminées.

       GAI_NOWAIT
              Effectue  les  résolutions de manière asynchrone. L'appel s'achève immédiatement et
              les requêtes sont résolues en arrière-plan. Consultez la description  du  paramètre
              sevp ci-dessous.

       Le  tableau  list indique les requêtes de recherche à traiter. Le paramètre nitems indique
       le nombre d'éléments dans list. Les opérations de  recherche  demandées  sont  lancées  en
       parallèle.  Les  éléments égal à NULL de list sont ignorés. Chaque requête est décrite par
       une structure gaicb définie ci-dessous :

           struct gaicb {
               const char            *ar_name;
               const char            *ar_service;
               const struct addrinfo *ar_request;
               struct addrinfo       *ar_result;
           };

       Les éléments de cette structure correspondent aux  paramètres  de  getaddrinfo(3).  Ainsi,
       ar_name  correspond  au  paramètre  node  et  ar_service au paramètre service, identifiant
       respectivement un  hôte  et  un  service  Internet.  L'élément  ar_request  correspond  au
       paramètre  hints,  indiquant  le  critère  de sélection des structures d'adresse de socket
       renvoyées.  Enfin,  ar_result  correspond  au  paramètre  res ;  vous  n'avez  pas  besoin
       d'initialiser  ce  paramètre,  il  sera  automatiquement  défini  lorsque  la requête sera
       résolue. La structure addrinfo référencée par les deux derniers éléments est décrite  dans
       getaddrinfo(3).

       Lorsque mode est défini à GAI_NOWAIT, les notifications des requêtes résolues peuvent être
       obtenues avec la structure sigevent pointée par le paramètre sevp. Pour la  définition  et
       les   détails   généraux   de   cette   structure,   consultez   sigevent(7).   Le   champ
       sevp->sigev_notify peut prendre l'une des valeurs suivantes :

       SIGEV_NONE
              Ne fournit pas de notification.

       SIGEV_SIGNAL
              Lorsqu'une recherche se termine, générer le signal  sigev_signo  à  destination  du
              processus.  Consultez  sigevent(7)  pour  plus  de  détails. Le champ si_code de la
              structure siginfo_t sera défini à SI_ASYNCNL.

       SIGEV_THREAD
              Lors d'une résolution, invoquer sigev_notify_function comme si c'était la  fonction
              de création d'un nouveau processus léger. Consultez sigevent(7) pour plus détails.

       Pour   SIGEV_SIGNAL   et   SIGEV_THREAD,   il   peut   être   utile   de   faire   pointer
       sevp->sigev_value.sival_ptr vers list.

       La fonction gai_suspend() suspend l'exécution du processus léger  appelant,  attendant  la
       fin  d'une  ou  plusieurs requêtes du tableau list. L'argument nitems indique la taille du
       tableau  list.  L'appel  est  bloquant  tant  que  l'un  des  événements  suivants  ne  se
       produisent :

       –  Une ou plusieurs des opérations de list se sont terminées.

       –  L'appel a été interrompu par un signal qui a été interrompu.

       –  L'intervalle  de temps indiqué dans timeout s'est écoulé. Ce paramètre indique un délai
          en seconds plus nanosecondes (consultez  nanosleep(2)  pour  plus  de  détails  sur  la
          structure  timespec).  Si  timeout  est  NULL, alors l'appel est bloqué indéfiniment (à
          moins que l'un des événement ci-dessus se produisent).

       Aucune indication explicite sur la requête qui s'est terminée  est  fournie ;  vous  devez
       déterminer  quelle  requête  s'est  terminée  en  parcourant avec gai_error() la liste des
       requête (il peut y avoir plusieurs requêtes).

       La fonction gai_error() renvoie l'état de la  requête  req :  soit  EAI_INPROGRESS  si  la
       requête ne s'est pas encore terminée, soit 0 si elle s'est terminé correctement ou soit un
       code d'erreur si elle ne peut pas être résolue.

       The gai_cancel()  function cancels the request req.  If  the  request  has  been  canceled
       successfully,  the  error  status  of  the  request will be set to EAI_CANCELED and normal
       asynchronous notification will be performed. The request  cannot  be  canceled  if  it  is
       currently  being processed; in that case, it will be handled as if gai_cancel()  has never
       been called. If req is NULL, an attempt is made to cancel all  outstanding  requests  that
       the process has made.

VALEUR RENVOYÉE

       La  fonction  getaddrinfo_a()  renvoie  0  si  toutes  les  requêtes ont été mises en file
       d'attente avec succès, ou un des codes d'erreur non nuls suivants :

       EAI_AGAIN
              Les ressources nécessaires pour mettre en file d'attente les requêtes de  recherche
              ne  sont  pas  disponibles.  L'application  devrait  vérifier le statut d'erreur de
              chaque requête pour déterminer laquelle a échoué.

       EAI_MEMORY
              Plus assez de mémoire.

       EAI_SYSTEM
              mode est non valable.

       La fonction gai_suspend() renvoie 0 si au moins une des requêtes listées  s'est  terminée.
       Sinon, elle renvoie un des codes d'erreur non nuls suivants :

       EAI_AGAIN
              Le délai d'attente a expiré avant que toute requête ne soit terminée.

       EAI_ALLDONE
              Il n'y a actuellement aucune requête fournie à la fonction.

       EAI_INTR
              Un signal a interrompu la fonction. Notez que cette interruption pourrait avoir été
              causé par une notification de signal de fin de certaines requêtes de recherche.

       The gai_error()  function can return EAI_INPROGRESS for an unfinished look-up  request,  0
       for  a  successfully  completed  look-up (as described above), one of the error codes that
       could be returned by getaddrinfo(3), or the error code EAI_CANCELED  if  the  request  has
       been canceled explicitly before it could be finished.

       La fonction gai_cancel() peut renvoyer une des valeurs suivantes :

       EAI_CANCELED
              La requête a été annulée avec succès.

       EAI_NOTCANCELED
              La requête n'a pas été annulée.

       EAI_ALLDONE
              La requête est déjà terminée.

       La  fonction  gai_strerror(3)  traduit  ces  codes  d'erreur  en  une chaîne de caractères
       compréhensible, utilisable pour rendre compte du problème.

ATTRIBUTS

       Pour une explication des termes utilisés dans cette section, consulter attributes(7).

       ┌────────────────────────────────┬──────────────────────┬─────────┐
       │InterfaceAttributValeur  │
       ├────────────────────────────────┼──────────────────────┼─────────┤
       │getaddrinfo_a(), gai_suspend(), │ Sécurité des threads │ MT-Safe │
       │gai_error(), gai_cancel()       │                      │         │
       └────────────────────────────────┴──────────────────────┴─────────┘

CONFORMITÉ

       Ces  fonctions  sont  des  extensions GNU. Elles ont été introduites dans la glibc dans sa
       version 2.1.1.

NOTES

       L'interface de getaddrinfo_a() a été modifiée après l'interface lio_listio(3).

EXEMPLES

       Deux exemples sont fournis : un simple exemple qui résout plusieurs requête  en  parallèle
       de façon synchrone et un exemple complexe montrant certaines des capacités asynchrones.

   Exemple synchrone
       Le  programme  ci-dessous résout simplement plusieurs noms d'hôte en parallèle, améliorant
       le temps de résolution des noms d'hôtes comparé à des appels séquentiels à getaddrinfo(3).
       Le programme peut être utilisé comme suit :

           $ ./a.out ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz
           ftp.us.kernel.org: 128.30.2.36
           enoent.linuxfoundation.org: Name or service not known
           gnu.cz: 87.236.197.13

       Voilà le code source du programme

       #define _GNU_SOURCE
       #include <netdb.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       int
       main(int argc, char *argv[])
       {
           int ret;
           struct gaicb *reqs[argc - 1];
           char host[NI_MAXHOST];
           struct addrinfo *res;

           if (argc < 2) {
               fprintf(stderr, "Usage: %s HOST...\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           for (int i = 0; i < argc - 1; i++) {
               reqs[i] = malloc(sizeof(*reqs[0]));
               if (reqs[i] == NULL) {
                   perror("malloc");
                   exit(EXIT_FAILURE);
               }
               memset(reqs[i], 0, sizeof(*reqs[0]));
               reqs[i]->ar_name = argv[i + 1];
           }

           ret = getaddrinfo_a(GAI_WAIT, reqs, argc - 1, NULL);
           if (ret != 0) {
               fprintf(stderr, "getaddrinfo_a() failed: %s\n",
                       gai_strerror(ret));
               exit(EXIT_FAILURE);
           }

           for (int i = 0; i < argc - 1; i++) {
               printf("%s: ", reqs[i]->ar_name);
               ret = gai_error(reqs[i]);
               if (ret == 0) {
                   res = reqs[i]->ar_result;

                   ret = getnameinfo(res->ai_addr, res->ai_addrlen,
                           host, sizeof(host),
                           NULL, 0, NI_NUMERICHOST);
                   if (ret != 0) {
                       fprintf(stderr, "getnameinfo() failed: %s\n",
                               gai_strerror(ret));
                       exit(EXIT_FAILURE);
                   }
                   puts(host);

               } else {
                   puts(gai_strerror(ret));
               }
           }
           exit(EXIT_SUCCESS);
       }

   Exemple asynchrone
       Cet  exemple  est  une  simple  application  interactive  utilisant  getaddrinfo_a().  Les
       fonctionnalités de notification ne sont pas exploitées.

       Un exemple de session pourrait ressembler à ceci :

           $ ./a.out
           > a ftp.us.kernel.org enoent.linuxfoundation.org gnu.cz
           > c 2
           [2] gnu.cz: Request not canceled
           > w 0 1
           [00] ftp.us.kernel.org: Finished
           > l
           [00] ftp.us.kernel.org: 216.165.129.139
           [01] enoent.linuxfoundation.org: Processing request in progress
           [02] gnu.cz: 87.236.197.13
           > l
           [00] ftp.us.kernel.org: 216.165.129.139
           [01] enoent.linuxfoundation.org: Name or service not known
           [02] gnu.cz: 87.236.197.13

       Le code source du programme est :

       #define _GNU_SOURCE
       #include <netdb.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       static struct gaicb **reqs = NULL;
       static int nreqs = 0;

       static char *
       getcmd(void)
       {
           static char buf[256];

           fputs("> ", stdout); fflush(stdout);
           if (fgets(buf, sizeof(buf), stdin) == NULL)
               return NULL;

           if (buf[strlen(buf) - 1] == '\n')
               buf[strlen(buf) - 1] = 0;

           return buf;
       }

       /* Add requests for specified hostnames */
       static void
       add_requests(void)
       {
           int nreqs_base = nreqs;
           char *host;
           int ret;

           while ((host = strtok(NULL, " "))) {
               nreqs++;
               reqs = realloc(reqs, sizeof(reqs[0]) * nreqs);

               reqs[nreqs - 1] = calloc(1, sizeof(*reqs[0]));
               reqs[nreqs - 1]->ar_name = strdup(host);
           }

           /* Queue nreqs_base..nreqs requests. */

           ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base],
                               nreqs - nreqs_base, NULL);
           if (ret) {
               fprintf(stderr, "getaddrinfo_a() failed: %s\n",
                       gai_strerror(ret));
               exit(EXIT_FAILURE);
           }
       }

       /* Wait until at least one of specified requests completes */
       static void
       wait_requests(void)
       {
           char *id;
           int ret, n;
           struct gaicb const **wait_reqs = calloc(nreqs, sizeof(*wait_reqs));
                       /* NULL elements are ignored by gai_suspend(). */

           while ((id = strtok(NULL, " ")) != NULL) {
               n = atoi(id);

               if (n >= nreqs) {
                   printf("Bad request number: %s\n", id);
                   return;
               }

               wait_reqs[n] = reqs[n];
           }

           ret = gai_suspend(wait_reqs, nreqs, NULL);
           if (ret) {
               printf("gai_suspend(): %s\n", gai_strerror(ret));
               return;
           }

           for (int i = 0; i < nreqs; i++) {
               if (wait_reqs[i] == NULL)
                   continue;

               ret = gai_error(reqs[i]);
               if (ret == EAI_INPROGRESS)
                   continue;

               printf("[%02d] %s: %s\n", i, reqs[i]->ar_name,
                      ret == 0 ? "Finished" : gai_strerror(ret));
           }
       }

       /* Cancel specified requests */
       static void
       cancel_requests(void)
       {
           char *id;
           int ret, n;

           while ((id = strtok(NULL, " ")) != NULL) {
               n = atoi(id);

               if (n >= nreqs) {
                   printf("Bad request number: %s\n", id);
                   return;
               }

               ret = gai_cancel(reqs[n]);
               printf("[%s] %s: %s\n", id, reqs[atoi(id)]->ar_name,
                      gai_strerror(ret));
           }
       }

       /* List all requests */
       static void
       list_requests(void)
       {
           int ret;
           char host[NI_MAXHOST];
           struct addrinfo *res;

           for (int i = 0; i < nreqs; i++) {
               printf("[%02d] %s: ", i, reqs[i]->ar_name);
               ret = gai_error(reqs[i]);

               if (!ret) {
                   res = reqs[i]->ar_result;

                   ret = getnameinfo(res->ai_addr, res->ai_addrlen,
                                     host, sizeof(host),
                                     NULL, 0, NI_NUMERICHOST);
                   if (ret) {
                       fprintf(stderr, "getnameinfo() failed: %s\n",
                               gai_strerror(ret));
                       exit(EXIT_FAILURE);
                   }
                   puts(host);
               } else {
                   puts(gai_strerror(ret));
               }
           }
       }

       int
       main(int argc, char *argv[])
       {
           char *cmdline;
           char *cmd;

           while ((cmdline = getcmd()) != NULL) {
               cmd = strtok(cmdline, " ");

               if (cmd == NULL) {
                   list_requests();
               } else {
                   switch (cmd[0]) {
                   case 'a':
                       add_requests();
                       break;
                   case 'w':
                       wait_requests();
                       break;
                   case 'c':
                       cancel_requests();
                       break;
                   case 'l':
                       list_requests();
                       break;
                   default:
                       fprintf(stderr, "Bad command: %c\n", cmd[0]);
                       break;
                   }
               }
           }
           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

       getaddrinfo(3), inet(3), lio_listio(3), hostname(7), ip(7), sigevent(7)

COLOPHON

       Cette page fait partie de la publication 5.10 du projet man-pages Linux.  Une  description
       du  projet et des instructions pour signaler des anomalies et la dernière version de cette
       page peuvent être trouvées à l'adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION

       La traduction française de cette  page  de  manuel  a  été  créée  par  Christophe  Blaess
       <https://www.blaess.fr/christophe/>,  Stéphan  Rafin  <stephan.rafin@laposte.net>, Thierry
       Vignaud <tvignaud@mandriva.com>, François Micaux, Alain  Portal  <aportal@univ-montp2.fr>,
       Jean-Philippe    Guérard   <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)   <jean-
       luc.coulon@wanadoo.fr>,   Julien    Cristau    <jcristau@debian.org>,    Thomas    Huriaux
       <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
       Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>,  Denis
       Barbier <barbier@debian.org> et David Prévot <david@tilapin.org>

       Cette  traduction  est  une  documentation libre ; veuillez vous reporter à la GNU General
       Public  License  version 3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩   concernant   les
       conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
       message à debian-l10n-french@lists.debian.org ⟨⟩.