pthread_key_create Subroutine

Purpose

Creates a thread-specific data key.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

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

Description

The pthread_key_create subroutine creates a thread-specific data key. The key is shared among all threads within the process, but each thread has specific data associated with the key. The thread-specific data is a void pointer, initially set to NULL.

The application is responsible for ensuring that this subroutine is called only once for each requested key. This can be done, for example, by calling the subroutine before creating other threads, or by using the one-time initialization facility.

Typically, thread-specific data are pointers to dynamically allocated storage. When freeing the storage, the value should be set to NULL. It is not recommended to cast this pointer into scalar data type (int for example), because the casts may not be portable, and because the value of NULL is implementation dependent.

An optional destructor routine can be specified. It will be called for each thread when it is terminated and detached, after the call to the cleanup routines, if the specific value is not NULL. Typically, the destructor routine will release the storage thread-specific data. It will receive the thread-specific data as a parameter.

Note: The pthread.h header file must be the first included file of each source file using the threads library. Otherwise, the -D_THREAD_SAFE compilation flag should be used, or the cc_r compiler used. In this case, the flag is automatically set.

Parameters

Item	Description
key	Points to where the key will be stored.
destructor	Points to an optional destructor routine, used to cleanup data on thread termination. If no cleanup is desired, this pointer should be NULL.

Return Values

If successful, the pthread_key_create function stores the newly created key value at *key and returns zero. Otherwise, an error number is returned to indicate the error.

Error Codes

The pthread_key_create function will fail if:

Item	Description
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 function will not return an error code of EINTR.