1pthread_key_create(3C) Standard C Library Functions pthread_key_create(3C)
2
6 pthread_key_create, pthread_key_create_once_np - create thread-specific
7 data key
8
10 cc -mt [ flag... ] file... -lpthread [ library... ]
11 #include <pthread.h>
12 int pthread_key_create(pthread_key_t *key,
14 void (*destructor)(void*));
15 int pthread_key_create_once_np(pthread_key_t *key,
18 void (*destructor)(void*));
19
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 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 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 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 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 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
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
69 The pthread_key_create() and pthread_key_create_once_np() functions
70 will fail if:
71 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 ENOMEM Insufficient memory exists to create the key.
79 The pthread_key_create() and pthread_key_create_once_np() functions
83 will not return an error value of EINTR.
84
86 Example 1 Call thread-specific data in the function from more than one
87 thread without special initialization.
88 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 /* cc -mt thisfile.c */
97 #include <stdio.h>
99 #include <stdlib.h>
100 #include <string.h>
101 #include <pthread.h>
102 static void *thread_function(void *);
104 static void show_tsd(void);
105 static void cleanup(void*);
106 #define MAX_THREADS 20
108 static pthread_key_t tsd_key = PTHREAD_ONCE_KEY_NP;
110 int
112 main(int argc, char *argv[])
113 {
114 pthread_t tid[MAX_THREADS];
115 int num_threads;
116 int i;
117 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 static void *
128 thread_function(void *arg)
129 {
130 char *data;
131 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 static void
141 show_tsd()
142 {
143 void *tsd = pthread_getspecific(tsd_key);
144 printf("tsd for %d = %s\n", pthread_self(), (char *)tsd);
146 }
147 /* 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
158 See attributes(5) for descriptions of the following attributes:
159 ┌─────────────────────────────┬─────────────────────────────┐
164 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
165 ├─────────────────────────────┼─────────────────────────────┤
166 │Interface Stability │Committed. │
167 ├─────────────────────────────┼─────────────────────────────┤
168 │MT-Level │MT-Safe │
169 ├─────────────────────────────┼─────────────────────────────┤
170 │Standard │See below. │
171 └─────────────────────────────┴─────────────────────────────┘
172 For pthread_key_create(), see standards(5).
175
177 pthread_once(3C), pthread_getspecific(3C), pthread_setspecific(3C),
178 pthread_key_delete(3C), attributes(5), standards(5)
179SunOS 5.11 2 Nov 2007 pthread_key_create(3C)