Provided by: manpages-fr-extra_20080921_all bug

NOM

       pthread_key_create,       pthread_key_delete,      pthread_setspecific,
       pthread_getspecific - Gestion de données spécifiques à un thread

SYNOPSIS

       #include <pthread.h>

       int pthread_key_create(pthread_key_t *clé, void (*destr_function) (void
       *));

       int pthread_key_delete(pthread_key_t clé);

       int pthread_setspecific(pthread_key_t clé, const void *pointer);

       void * pthread_getspecific(pthread_key_t clé);

DESCRIPTION

       Les  programmes  ont  souvent besoin de variables globales ou statiques
       ayant différentes  valeurs  dans  des  threads  différents.  Comme  les
       threads  partagent  le  même  espace mémoire, cet objectif ne peut être
       réalisé avec les variables  usuelles.  Les  données  spécifiques  à  un
       thread POSIX sont la réponse à ce problème.

       Chaque thread possède un segment mémoire privé, le TSD (Thread-Specific
       Data : Données Spécifiques au Thread). Cette zone mémoire  est  indexée
       par  des  clés  TSD. La zone TSD associe des valeurs du type void * aux
       clés TSD. Ces clés sont communes à tous les  threads,  mais  la  valeur
       associée à une clé donnée est différente dans chaque thread.

       Pour  concrétiser  ce formalisme, les zones TSD peuvent être vues comme
       des tableaux de pointeurs void  *,  les  clés  TSD  comme  des  indices
       entiers  pour  ces  tableaux,  et  les  valeurs  des clés TSD comme les
       valeurs des entrées correspondantes dans le tableau du thread appelant.

       Quand  un  thread  est  créé,  sa  zone TSD associe initialement NULL à
       toutes les clés.

       pthread_key_create()  alloue  une  nouvelle  clé  TSD.  Cette  clé  est
       enregistrée à l’emplacement pointée par cl. Il ne peut y avoir plus de
       PTHREAD_KEYS_MAX  clés  allouées  à  un  instant   donné.   La   valeur
       initialement  associée  avec  la  clé  renvoyée  est NULL dans tous les
       threads en cours d’exécution.

       Le  paramètre  destr_function,  si  différent  de  NULL,  spécifie  une
       fonction  de destruction associée à une clé. Quand le thread se termine
       par pthread_exit() ou par une annulation,  destr_function  est  appelée
       avec  en  argument  les  valeurs  associées  aux  clés de ce thread. La
       fonction destr_function n’est pas appelée si  cette  valeur  est  NULL.
       L’ordre  dans lequel les fonctions de destruction sont appelées lors de
       la fin du thread n’est pas spécifiée.

       Avant que la fonction de destruction soit appelée, la valeur  NULL  est
       associée  à  la clé dans le thread courant. Une fonction de destruction
       peut cependant réassocier une valeur différente de NULL à cette clé  ou
       une  autre  clé.  Pour gérer ce cas de figure, si après l’appel de tous
       les destructeurs pour  les  valeurs  différentes  de  NULL,  il  existe
       toujours   des  valeurs  différentes  de  NULL  avec  des  destructeurs
       associés,  alors  la  procédure  est   répétée.   L’implémentation   de
       LinuxThreads        interrompt        cette       procédure       après
       PTHREAD_DESTRUCTOR_ITERATIONS itérations, même s’il reste  des  valeurs
       différentes   de   NULL   associées  à  des  descripteurs.  Les  autres
       implémentations peuvent boucler sans fin.

       pthread_key_delete() désalloue une clé TSD. Elle ne vérifie pas si  des
       valeurs  différentes  de  NULL  sont  associées avec cette clé dans les
       threads en cours d’exécution, ni n’appelle la fonction  de  destruction
       associée avec cette clé.

       pthread_setspecific() change la valeur associée avec cl dans le thread
       appelant, sauve le paramètre pointer à sa place.

       pthread_getspecific() renvoie la valeur actuellement associée avec  cl
       dans le thread appelant.

VALEUR RENVOYÉE

       pthread_key_create(),   pthread_key_delete()  et  pthread_setspecific()
       renvoient 0 en cas de succès  et  un  code  d’erreur  non  nul  en  cas
       d’échec.  En  cas  de  succès,  pthread_key_create()  enregistre la clé
       récemment créée à l’emplacement pointé par son argument cl.

       pthread_getspecific() renvoie la valeur associée à cl en cas de succès
       et NULL en cas d’erreur.

ERREURS

       pthread_key_create() renvoie le code d’erreur suivant :

              EAGAIN PTHREAD_KEYS_MAX clés sont déjà allouées.

       pthread_key_delete()   et   pthread_setspecific()   renvoient  le  code
       d’erreur suivant :

              EINVAL cl n’est pas une clé TSD allouée valable.

       pthread_getspecific() renvoie NULL  si  cl  n’est  pas  une  clef  TSD
       allouée valable.

AUTEUR

       Xavier Leroy <Xavier.Leroy@inria.fr>

VOIR AUSSI

       pthread_create(3), pthread_exit(3), pthread_testcancel(3).

EXEMPLE

       L’extrait  de  code  suivant  alloue  dans  un thread un tableau de 100
       caractères, avec libération de la mémoire automatiquement à la  fin  de
       l’exécution du thread.

              /* Clé pour le tampon spécifique au thread */
              static pthread_key_t buffer_key;

              /* Initialisation unique de la clé */
              static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;

              /* Alloue le tampon spécifique au thread */
              void buffer_alloc(void)
              {
                pthread_once(&buffer_key_once, buffer_key_alloc);
                pthread_setspecific(buffer_key, malloc(100));
              }

              /* Renvoie le tampon spécifique au thread */
              char * get_buffer(void)
              {
                return (char *) pthread_getspecific(buffer_key);
              }

              /* Alloue la clé */
              static void buffer_key_alloc()
              {
                pthread_key_create(&buffer_key, buffer_destroy);
              }

              /* Libère le tampon spécifique au thread */
              static void buffer_destroy(void * buf)
              {
                free(buf);
              }

TRADUCTION

       Cette  page  de  manuel a été traduite par Thierry Vignaud <tvignaud AT
       mandriva DOT com> en 2000 et  révisée  par  Alain  Portal  <aportal  AT
       univ-montp2  DOT  fr>  en  2006.   La  version présente dans Debian est
       maintenue par les membres de la liste <debian-l10n-french AT lists  DOT
       debian  DOT  org>.  Veuillez signaler toute erreur de traduction par un
       rapport de bogue sur le paquet manpages-fr-extra.

                                 LinuxThreads              PTHREAD_SPECIFIC(3)