Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > P

pthread_key_create(3T)

Pthread Library
HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

pthread_key_create(), pthread_key_delete() — create or delete a thread-specific data key

SYNOPSIS

#include <pthread.h>

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

int pthread_key_delete( pthread_key_t key );

PARAMETERS

key

This is either a pointer to the location where the new key value will to be returned (create function) or the thread-specific data key to be deleted (delete function).

destructor

Function to be called to destroy a data value associated with key when the thread terminates.

DESCRIPTION

pthread_key_create() creates a unique thread-specific data key. The key may be used by threads within the process to maintain thread-specific data. The same key is used by all threads, but each thread has its own thread-specific value associated with key. For each thread, the value associated with key persists for the life of the thread.

By default, the system allows a process to create up to PTHREAD_KEYS_MAX number of thread-specific data keys. If the process needs more keys, the environment variable PTHREAD_USER_KEYS_MAX can set the number of keys up to a maximum of 16384. If a value outside the range of PTHREAD_KEYS_MAX and 16384 is specified, or if the environment variable is not set at all, the default value is considered. When a new thread-specific data key is created, each thread will initially have the value NULL associated with the new key. Each time a thread is created, the new thread will have the value NULL for each thread-specific data key that has been created in the process. A thread may use pthread_setspecific() to change the value associated with a thread-specific data key. Note: pthread_key_t is an opaque data type.

When a thread terminates, it may have non-NULL values associated with some or all of its thread-specific data keys. Typically, these values will be pointers to dynamically allocated memory. If this memory is not released when the thread terminates, memory leaks in the process occur. An optional destructor() function may be provided at key creation time to destroy the thread-specific data of a terminating thread. When a thread terminates, the thread-specific data values associated with the thread will be examined. For each key that has a non-NULL thread-specific data value and a destructor function, the destructor function will be called with the thread-specific data value as its sole argument. The order in which destructor functions are called is unspecified.

Once all the destructor functions have been called, the thread-specific data values for the terminating thread are examined again. If there are still non-NULL values in which the associated keys have destructor functions, the process of calling destructor functions is repeated. If after PTHREAD_DESTRUCTOR_ITERATIONS iterations of this loop there are still some non-NULL values with associated destructors, the system may stop calling the destructors or continue calling the destructors until there are no non-NULL values. Note: This may result in an infinite loop.

If a destructor function is not desired for key, the value NULL may be passed in the destructor parameter.

The pthread_key_delete() function deletes a thread-specific data key. The key must have been previously created by pthread_key_create(). The thread-specific data values associated with key are not required to be NULL when this function is called. Using key after it has been deleted results in undefined behavior.

If a destructor function is associated with key, it will not be invoked by the pthread_key_delete() function. Once key has been deleted, any destructor function that was associated with key is not called when a thread exits. It is the responsibility of the application to free any application storage for each of the threads using key.

The pthread_key_delete() function can be called from a destructor function.

RETURN VALUE

If successful, pthread_key_create() and pthread_key_delete() return zero. Otherwise, an error number is returned to indicate the error (the errno variable is not set).

ERRORS

If any of the following occur, the pthread_key_create() function returns the corresponding error number:

EINVAL

The value specified by key is invalid.

EAGAIN

The necessary resources to create another thread-specific data key are not available, or the total number of keys per process has exceeded PTHREAD_KEYS_MAX, or an invalid value was specified with the environment variable PTHREAD_USER_KEYS_MAX.

ENOMEM

There is insufficient memory available in which to create key.

For each of the following conditions, if the condition is detected, the pthread_key_delete() function returns the corresponding error number:

EINVAL

The value specified by key is invalid.

AUTHOR

pthread_key_create() and pthread_key_delete() were derived from the IEEE POSIX P1003.1c standard.

SEE ALSO

pthread_getspecific(3T), pthread_setspecific(3T).

STANDARDS CONFORMANCE

pthread_key_create(): POSIX 1003.1c. pthread_key_delete(): POSIX 1003.1c.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.