Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

NOM

       pthread_cancel - Envoyer une requete d'annulation a un thread

SYNOPSIS

       #include <pthread.h>

       int pthread_cancel(pthread_t thread);

       Compilez et effectuez l'edition des liens avec l'option -pthread.

DESCRIPTION

       La  fonction pthread_cancel() envoie une requete d'annulation au thread
       thread. Si et quand le thread cible reagit a  la  requete  d'annulation
       depend  de  deux attributs qui sont sous le controle de ce thread : son
       etat d'annulation (state) et son mode d'annulation (type).

       L'etat      d'annulation      d'un      thread,      determine      par
       pthread_setcancelstate(3),  peut etre active (enabled), c'est le defaut
       pour les nouveaux  threads,  ou  desactive  (disabled).  Si  un  thread
       desactive  l'annulation, alors une demande d'annulation restera dans la
       file d'attente jusqu'a ce que le  thread  active  l'annulation.  Si  un
       thread  active  l'annulation, alors son mode d'annulation va determiner
       le moment ou cette annulation est effectuee.

       Le     mode     d'annulation     d'un     thread,     determine     par
       pthread_setcanceltype(3),   peut   etre  asynchrone  (asynchronous)  ou
       retardee (deferred), qui est le  mode  par  defaut  pour  les  nouveaux
       threads.  Un  mode  d'annulation asynchrone signifie que le thread peut
       etre annule a tout moment (d'ordinaire immediatement, mais ce n'est pas
       garanti).  Un  mode d'annulation retarde signifie que l'annulation peut
       etre retardee jusqu'a ce que le thread appelle une fonction qui est  un
       point  d'annulation  (cancellation  point). Une liste des fonctions qui
       sont  ou  peuvent  etre  des  points  d'annulation  est   donnee   dans
       pthreads(7).

       Quand  une  requete d'annulation est traitee, les etapes suivantes sont
       effectuees pour thread (dans cet ordre) :

       1. Les gestionnaires de nettoyage sont depiles  (dans  l'ordre  inverse
          dans   lequel   ils   ont   ete   empiles)   et  appeles  (consultez
          pthread_cleanup_push(3)).

       2. Les destructeurs de donnees specifiques aux  threads  sont  appeles,
          dans un ordre non determine (consultez pthread_key_create(3)).

       3. Le thread s'est termine (consultez pthread_exit(3)).

       Les  etapes ci-dessus sont effectuees de maniere asynchrone par rapport
       a l'appel a pthread_cancel(). La valeur de retour  de  pthread_cancel()
       ne  fait  qu'informer  l'appelant  si  une  requete  d'annulation a ete
       correctement mise en file d'attente.

       Apres qu'un thread annule s'est termine, une demande  de  jointure  par
       pthread_join(3)  renvoie  PTHREAD_CANCELED  comme  etat  de  sortie  du
       thread. Il faut noter que joindre un thread est  la  seule  maniere  de
       savoir si une annulation a termine.

VALEUR RENVOY'EE

       En  cas de reussite, pthread_cancel() renvoie 0 ; en cas d'erreur, elle
       renvoie un numero d'erreur non nul.

ERREURS

       ESRCH  Aucun thread avec pour identifiant thread n'a pu etre trouve.

CONFORMIT'E

       POSIX.1-2001.

NOTES

       Sous  Linux,  l'annulation  est  implementee  par  des  signaux.   Avec
       l'implementation  NPTL,  le  premier signal temps-reel (c'est-a-dire le
       signal 32) est utilise dans ce but. Avec LinuxThreads, le second signal
       temps-reel  est  utilise,  si les signaux temps-reels sont disponibles,
       sinon SIGUSR2 est utilise a la place.

EXEMPLE

       Le programme  ci-dessous  cree  un  thread  puis  l'annule.  Le  thread
       principal  joint  le thread annule pour verifier que son etat de sortie
       etait bien PTHREAD_CANCELED. La  session  suivante  montre  un  exemple
       d'execution :

           $ ./a.out
           thread_func(): started; cancellation disabled
           main(): sending cancellation request
           thread_func(): about to enable cancellation
           main(): thread was canceled

   Source du programme

       #include <pthread.h>
       #include <stdio.h>
       #include <errno.h>
       #include <stdlib.h>
       #include <unistd.h>

       #define handle_error_en(en, msg) \
               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

       static void *
       thread_func(void *ignored_argument)
       {
           int s;

           /* Disable cancellation for a while, so that we don't
              immediately react to a cancellation request */

           s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_setcancelstate");

           printf("thread_func(): started; cancellation disabled\n");
           sleep(5);
           printf("thread_func(): about to enable cancellation\n");

           s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_setcancelstate");

           /* sleep() is a cancellation point */

           sleep(1000);        /* Should get canceled while we sleep */

           /* Should never get here */

           printf("thread_func(): not canceled!\n");
           return NULL;
       }

       int
       main(void)
       {
           pthread_t thr;
           void *res;
           int s;

           /* Start a thread and then send it a cancellation request */

           s = pthread_create(&thr, NULL, &thread_func, NULL);
           if (s != 0)
               handle_error_en(s, "pthread_create");

           sleep(2);           /* Give thread a chance to get started */

           printf("main(): sending cancellation request\n");
           s = pthread_cancel(thr);
           if (s != 0)
               handle_error_en(s, "pthread_cancel");

           /* Join with thread to see what its exit status was */

           s = pthread_join(thr, &res);
           if (s != 0)
               handle_error_en(s, "pthread_join");

           if (res == PTHREAD_CANCELED)
               printf("main(): thread was canceled\n");
           else
               printf("main(): thread wasn't canceled (shouldn't happen!)\n");
           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

       pthread_cleanup_push(3),       pthread_create(3),      pthread_exit(3),
       pthread_join(3),   pthread_key_create(3),    pthread_setcancelstate(3),
       pthread_setcanceltype(3), pthread_testcancel(3), pthreads(7)

COLOPHON

       Cette  page  fait  partie  de  la  publication 3.27 du projet man-pages
       Linux. Une description du projet et des instructions pour signaler  des
       anomalies       peuvent       etre       trouvees      a      l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis 2010, cette traduction est maintenue a l'aide  de  l'outil  po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'equipe   de   traduction
       francophone       au       sein        du        projet        perkamon
       <URL:http://perkamon.alioth.debian.org/>.

       Denis Barbier (2010).

       Veuillez   signaler   toute   erreur   de   traduction  en  ecrivant  a
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous  pouvez  toujours avoir acces a la version anglaise de ce document
       en utilisant la commande << man -L C <section> <page_de_man> >>.