pthread_key_create(3) [osx man page]

PTHREAD_KEY_CREATE(3)					   BSD Library Functions Manual 				     PTHREAD_KEY_CREATE(3)

NAME

     pthread_key_create -- thread-specific data key creation

SYNOPSIS

     #include <pthread.h>

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

DESCRIPTION

     The pthread_key_create() function creates a thread-specific data key that is visible to all threads in the process.  Key values provided by
     pthread_key_create() are opaque objects, used to locate thread-specific data.  Although the same key value may be used by different threads,
     the values bound to the key by pthread_setspecific() are maintained on a per-thread basis and persist for the life of the calling thread.

     Upon key creation, the value NULL is associated with the new key in all active threads.  Upon thread creation, the value NULL is associated
     with all defined keys in the new thread.

     An optional destructor function may be associated with each key value.  If a key value has a non-NULL destructor function pointer, and the
     thread has a non-NULL value associated with the key at the time of thread exit, then the key value is set to NULL and the destructor function
     is called with the previous key value as its argument.  The order of destructor calls at thread exit is unspecified.

     If, after all the destructors have been called for all non-NULL values with associated destructors, there are still some non-NULL values with
     associated destructors, then the process is repeated.  If, after at least [PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for
     outstanding non-NULL values, there are still some non-NULL values with associated destructors, the implementation stops calling destructors.

RETURN VALUES

     If successful, the pthread_key_create() function will store the newly created key value at the location specified by key and returns zero.
     Otherwise, an error number will be returned to indicate the error.

ERRORS

     pthread_key_create() will fail if:

     [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] would be exceeded.

     [ENOMEM]		Insufficient memory exists to create the key.

SEE ALSO

     pthread_getspecific(3), pthread_key_delete(3), pthread_setspecific(3)

STANDARDS

     pthread_key_create() conforms to ISO/IEC 9945-1:1996 (``POSIX.1'').

BSD
								   April 4, 1996							       BSD

pthread_key_create(3T)													    pthread_key_create(3T)

NAME

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

SYNOPSIS

PARAMETERS

	      key	This  is either a pointer to the location where the new key value will to be returned (create function) or the thread-spe-
			cific 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

       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 number of thread-specific data keys.  If the process needs more keys, the  environ-
       ment variable can set the number of keys up to a maximum of 16384.  If a value outside the range of and 16384 is specified, or if the envi-
       ronment variable is not set at all, the default value is considered.  When a new thread-specific data key is created, each thread will ini-
       tially  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 to change the value associated with a thread-specific data
       key.  Note: 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 val-
       ues 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  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 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  function  deletes a thread-specific data key.  The key must have been previously created by 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 function.  Once key has been deleted, any 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 function can be called from a destructor function.

RETURN VALUE

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

ERRORS

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

	      The value specified by
			     key is invalid.

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

	      There is insufficient memory available in which to create
			     key.

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

	      The value specified by
			     key is invalid.

AUTHOR

       and were derived from the IEEE POSIX P1003.1c standard.

SEE ALSO

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

STANDARDS CONFORMANCE

								  Pthread Library					    pthread_key_create(3T)