Creates a key to a thread-specific data area.
#include <pthread.h>
int pthread_key_create (
pthread_key_t *key,
void (*destructor)(void *));
(OUT) Points to the allocated key.
(IN) Points to an application-specified destructor for destroying the value associated with the key.
If successful, returns 0; otherwise, returns a nonzero error code:
A key belongs to the process owning the threads that call pthread_key_create. Its lifetime is independent of the thread which created it. An allocated key remains allocated even if the thread which originally created the key exits. Each thread must set its own value for the key, and that value is destroyed when the thread exits. When the key is created, the key's value is set to NULL for all active threads in the process. When a new thread is created, the key's value is also set to NULL.
An optional destructor function can be specified for an allocated key. This destructor permanently corresponds to the allocated key until the key is deleted:
The destructor applies across all threads.
The destructor can be specified only when the key is created and cannot be subsequently changed.
Each thread cannot set a different destructor for the same key.
The destructor must be able to handle a key value of zero. Because only some threads might use a key and set its value, some threads might exist with a zero value for the key.
The destructor is called when a thread exits. The thread's value for the key is passed as a parameter to the destructor.
The destructor function must correspond to the type of data stored in the key:
If you are storing an integer, you can pass NULL for the destructor. The value doesn't have to be a pointer because an integer value can be stored within the key structure.
If you are storing a pointer to a string in the key and you used malloc for the string's memory, use the free function for the destructor.
If the value is a pointer to complicated data structure, use a developer created function that can walk the structure and free all its memory.
While the allocated key applies across all threads in the NLM™, the specified value is associated with the allocated key only for the calling thread. For example, if your application has three threads, all three threads can use the same key, and each has its own unique value in the key.
Although an application can support up to 64 keys, you seldom need to use more than one because you can store a heap-allocated structure with all the per-thread data your application needs, all with one key.
On NetWare, thread-specific data is called context-specific data. For more information about CSD, see Section 52.3, Context-Specific Data.