1pthread_key_create(3C)   Standard C Library Functions   pthread_key_create(3C)
2
3
4

NAME

6       pthread_key_create, pthread_key_create_once_np - create thread-specific
7       data key
8

SYNOPSIS

10       cc -mt [ flag... ] file... -lpthread [ library... ]
11       #include <pthread.h>
12
13       int pthread_key_create(pthread_key_t *key,
14            void (*destructor)(void*));
15
16
17       int pthread_key_create_once_np(pthread_key_t *key,
18            void (*destructor)(void*));
19
20

DESCRIPTION

22       The pthread_key_create() function creates a  thread-specific  data  key
23       visible  to  all  threads  in  the  process.  Key  values  provided  by
24       pthread_key_create() are opaque objects used to locate  thread-specific
25       data. Although the same key value may be used by different threads, the
26       values bound to the key by pthread_setspecific() are  maintained  on  a
27       per-thread basis and persist for the life of the calling thread.
28
29
30       Upon  key  creation,  the value  NULL is associated with the new key in
31       all active threads. Upon thread creation, the value  NULL is associated
32       with all defined keys in the new thread.
33
34
35       An  optional destructor function may be associated with each key value.
36       At thread exit, if a key value has a non-NULL  destructor pointer,  and
37       the  thread has a non-NULL value associated with that key, the function
38       pointed to is called with the current  associated  value  as  its  sole
39       argument. Destructors can be called in any order.
40
41
42       If,  after all the destructors have been  called for all keys with non-
43       NULL values,  there are still  some  keys  with  non-NULL  values,  the
44       process will be repeated. If, after at least  PTHREAD_DESTRUCTOR_ITERA‐
45       TIONS iterations of destructor calls for outstanding  non-NULL  values,
46       there  are still some keys with non-NULL values, the process is contin‐
47       ued, even though this might result in an infinite loop.
48
49
50       An exiting thread runs with all signals blocked. All thread termination
51       functions,  including  thread-specific  data  destructor functions, are
52       called with all signals blocked.
53
54
55       The  pthread_key_create_once_np()  function   is   identical   to   the
56       pthread_key_create()  function  except that the key referred to by *key
57       must be  statically  initialized  with  the  value  PTHREAD_ONCE_KEY_NP
58       before  calling  pthread_key_create_once_np(),  and  the key is created
59       exactly   once.   This   function   call   is   equivalent   to   using
60       pthread_once(3C)  to  call a onetime initialization function that calls
61       pthread_key_create() to create the data key.
62

RETURN VALUES

64       If   successful,   the   pthread_key_create()   and    pthread_key_cre‐
65       ate_once_np()  functions  store the newly created key value at *key and
66       return 0. Otherwise, an error number is returned to indicate the error.
67

ERRORS

69       The  pthread_key_create()  and  pthread_key_create_once_np()  functions
70       will fail if:
71
72       EAGAIN    The  system  lacked the necessary resources to create another
73                 thread-specific data key, or the system-imposed limit on  the
74                 total  number  of  keys per process PTHREAD_KEYS_MAX has been
75                 exceeded.
76
77
78       ENOMEM    Insufficient memory exists to create the key.
79
80
81
82       The  pthread_key_create()  and  pthread_key_create_once_np()  functions
83       will not return an error value of EINTR.
84

EXAMPLES

86       Example  1 Call thread-specific data in the function from more than one
87       thread without special initialization.
88
89
90       In the following example, the thread-specific data in the function  can
91       be called from more than one thread without special initialization. For
92       each argument passed to the executable, a thread is  created  and  pri‐
93       vately bound to the string-value of that argument.
94
95
96         /* cc -mt thisfile.c */
97
98         #include <stdio.h>
99         #include <stdlib.h>
100         #include <string.h>
101         #include <pthread.h>
102
103         static void *thread_function(void *);
104         static void show_tsd(void);
105         static void cleanup(void*);
106
107         #define MAX_THREADS 20
108
109         static pthread_key_t tsd_key = PTHREAD_ONCE_KEY_NP;
110
111         int
112         main(int argc, char *argv[])
113         {
114              pthread_t tid[MAX_THREADS];
115              int num_threads;
116              int i;
117
118              if ((num_threads = argc - 1) > MAX_THREADS)
119                   num_threads = MAX_THREADS;
120              for (i = 0; i < num_threads; i++)
121                   pthread_create(&tid[i], NULL, thread_function, argv[i+1]);
122              for (i = 0; i < num_threads; i++)
123                   pthread_join(tid[i], NULL);
124              return (0);
125         }
126
127         static void *
128         thread_function(void *arg)
129         {
130              char *data;
131
132              pthread_key_create_once_np(&tsd_key, cleanup);
133              data = malloc(strlen(arg) + 1);
134              strcpy(data, arg);
135              pthread_setspecific(tsd_key, data);
136              show_tsd();
137              return (NULL);
138         }
139
140         static void
141         show_tsd()
142         {
143              void *tsd = pthread_getspecific(tsd_key);
144
145              printf("tsd for %d = %s\n", pthread_self(), (char *)tsd);
146         }
147
148         /* application-specific clean-up function */
149         static void
150         cleanup(void *tsd)
151         {
152              printf("freeing tsd for %d = %s\n", pthread_self(), (char *)tsd);
153              free(tsd);
154         }
155
156

ATTRIBUTES

158       See attributes(5) for descriptions of the following attributes:
159
160
161
162
163       ┌─────────────────────────────┬─────────────────────────────┐
164       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
165       ├─────────────────────────────┼─────────────────────────────┤
166       │Interface Stability          │Committed.                   │
167       ├─────────────────────────────┼─────────────────────────────┤
168       │MT-Level                     │MT-Safe                      │
169       ├─────────────────────────────┼─────────────────────────────┤
170       │Standard                     │See below.                   │
171       └─────────────────────────────┴─────────────────────────────┘
172
173
174       For pthread_key_create(), see standards(5).
175

SEE ALSO

177       pthread_once(3C),   pthread_getspecific(3C),   pthread_setspecific(3C),
178       pthread_key_delete(3C), attributes(5), standards(5)
179
180
181
182SunOS 5.11                        2 Nov 2007            pthread_key_create(3C)
Impressum