Manual Pages for UNIX Operating System command usage for man pthread_key_create

Standard C Library Functions               pthread_key_create(3C)



NAME
     pthread_key_create,  pthread_key_create_once_np   -   create
     thread-specific data key

SYNOPSIS
     cc -mt [ flag... ] file... -lpthread [ library... ]
     #include 

     int pthread_key_create(pthread_key_t *key,
          void (*destructor)(void*));


     int pthread_key_create_once_np(pthread_key_t *key,
          void (*destructor)(void*));


DESCRIPTION
     The pthread_key_create() function creates a  thread-specific
     data  key  visible to all threads in the process. Key values
     provided by pthread_key_create() are opaque objects used  to
     locate thread-specific data. Although the same key value may
     be used by different threads, the values bound to the key by
     pthread_setspecific()  are  maintained on a per-thread basis
     and persist for the life of the calling thread.


     Upon key creation, the value  NULL is  associated  with  the
     new  key  in  all  active threads. Upon thread creation, the
     value  NULL is associated with all defined keys in  the  new
     thread.


     An optional destructor function may be associated with  each
     key  value.  At  thread  exit, if a key value has a non-NULL
     destructor pointer, and the  thread  has  a  non-NULL  value
     associated  with that key, the function pointed to is called
     with the current associated value as its sole argument. Des-
     tructors can be called in any order.


     If, after all the destructors have been  called for all keys
     with  non-NULL  values,  there are still some keys with non-
     NULL values, the process will  be  repeated.  If,  after  at
     least   PTHREAD_DESTRUCTOR_ITERATIONS iterations of destruc-
     tor calls for outstanding non-NULL values, there  are  still
     some  keys  with  non-NULL values, the process is continued,
     even though this might result in an infinite loop.


     An exiting thread runs with all signals blocked. All  thread
     termination  functions,  including thread-specific data des-
     tructor functions, are called with all signals blocked.



SunOS 5.11           Last change: 2 Nov 2007                    1






Standard C Library Functions               pthread_key_create(3C)



     The pthread_key_create_once_np() function  is  identical  to
     the   pthread_key_create()  function  except  that  the  key
     referred to by *key must be statically initialized with  the
     value        PTHREAD_ONCE_KEY_NP        before       calling
     pthread_key_create_once_np(), and the key is created exactly
     once.   This   function   call   is   equivalent   to  using
     pthread_once(3C) to call a onetime  initialization  function
     that calls pthread_key_create() to create the data key.

RETURN VALUES
     If     successful,     the     pthread_key_create()      and
     pthread_key_create_once_np()   functions   store  the  newly
     created key value at *key and return 0. Otherwise, an  error
     number is returned to indicate the error.

ERRORS
     The  pthread_key_create()  and  pthread_key_create_once_np()
     functions will fail if:

     EAGAIN    The  system  lacked  the  necessary  resources  to
               create  another  thread-specific  data key, or the
               system-imposed limit on the total number  of  keys
               per process PTHREAD_KEYS_MAX has been exceeded.


     ENOMEM    Insufficient memory exists to create the key.



     The  pthread_key_create()  and  pthread_key_create_once_np()
     functions will not return an error value of EINTR.

EXAMPLES
     Example 1 Call thread-specific data  in  the  function  from
     more than one thread without special initialization.


     In the following example, the thread-specific  data  in  the
     function  can  be  called  from more than one thread without
     special initialization. For each argument passed to the exe-
     cutable,  a  thread  is  created  and privately bound to the
     string-value of that argument.


       /* cc -mt thisfile.c */

       #include 
       #include 
       #include 
       #include 

       static void *thread_function(void *);



SunOS 5.11           Last change: 2 Nov 2007                    2






Standard C Library Functions               pthread_key_create(3C)



       static void show_tsd(void);
       static void cleanup(void*);

       #define MAX_THREADS 20

       static pthread_key_t tsd_key = PTHREAD_ONCE_KEY_NP;

       int
       main(int argc, char *argv[])
       {
            pthread_t tid[MAX_THREADS];
            int num_threads;
            int i;

            if ((num_threads = argc - 1) > MAX_THREADS)
                 num_threads = MAX_THREADS;
            for (i = 0; i < num_threads; i++)
                 pthread_create(&tid[i], NULL, thread_function, argv[i+1]);
            for (i = 0; i < num_threads; i++)
                 pthread_join(tid[i], NULL);
            return (0);
       }

       static void *
       thread_function(void *arg)
       {
            char *data;

            pthread_key_create_once_np(&tsd_key, cleanup);
            data = malloc(strlen(arg) + 1);
            strcpy(data, arg);
            pthread_setspecific(tsd_key, data);
            show_tsd();
            return (NULL);
       }

       static void
       show_tsd()
       {
            void *tsd = pthread_getspecific(tsd_key);

            printf("tsd for %d = %s\n", pthread_self(), (char *)tsd);
       }

       /* application-specific clean-up function */
       static void
       cleanup(void *tsd)
       {
            printf("freeing tsd for %d = %s\n", pthread_self(), (char *)tsd);
            free(tsd);
       }




SunOS 5.11           Last change: 2 Nov 2007                    3






Standard C Library Functions               pthread_key_create(3C)



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed.                  |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See below.                  |
    |_____________________________|_____________________________|



     For pthread_key_create(), see standards(5).

SEE ALSO
     pthread_once(3C),                   pthread_getspecific(3C),
     pthread_setspecific(3C),    pthread_key_delete(3C),   attri-
     butes(5), standards(5)































SunOS 5.11           Last change: 2 Nov 2007                    4