summary refs log tree commit diff
path: root/linuxthreads/man/pthread_key_create.man
diff options
context:
space:
mode:
Diffstat (limited to 'linuxthreads/man/pthread_key_create.man')
-rw-r--r--linuxthreads/man/pthread_key_create.man151
1 files changed, 0 insertions, 151 deletions
diff --git a/linuxthreads/man/pthread_key_create.man b/linuxthreads/man/pthread_key_create.man
deleted file mode 100644
index 6823e304c9..0000000000
--- a/linuxthreads/man/pthread_key_create.man
+++ /dev/null
@@ -1,151 +0,0 @@
-.TH PTHREAD_SPECIFIC 3 LinuxThreads
-
-.SH NAME
-pthread_key_create, pthread_key_delete, pthread_setspecific, pthread_getspecific \- management of thread-specific data
-
-.SH SYNOPSIS
-#include <pthread.h>
-
-int pthread_key_create(pthread_key_t *key, void (*destr_function) (void *));
-
-int pthread_key_delete(pthread_key_t key);
-
-int pthread_setspecific(pthread_key_t key, const void *pointer);
-
-void * pthread_getspecific(pthread_key_t key);
-
-.SH DESCRIPTION
-
-Programs often need global or static variables that have different
-values in different threads. Since threads share one memory space,
-this cannot be achieved with regular variables. Thread-specific data
-is the POSIX threads answer to this need.
-
-Each thread possesses a private memory block, the thread-specific data
-area, or TSD area for short. This area is indexed by TSD keys. The TSD
-area associates values of type !void *! to TSD keys. TSD keys are
-common to all threads, but the value associated with a given TSD key
-can be different in each thread.
-
-For concreteness, the TSD areas can be viewed as arrays of !void *!
-pointers, TSD keys as integer indices into these arrays, and the value
-of a TSD key as the value of the corresponding array element in the
-calling thread.
-
-When a thread is created, its TSD area initially associates !NULL!
-with all keys.
-
-!pthread_key_create! allocates a new TSD key. The key is stored in the
-location pointed to by |key|. There is a limit of !PTHREAD_KEYS_MAX!
-on the number of keys allocated at a given time. The value initially
-associated with the returned key is !NULL! in all currently executing
-threads.
-
-The |destr_function| argument, if not !NULL!, specifies a destructor
-function associated with the key. When a thread terminates via
-!pthread_exit! or by cancellation, |destr_function| is called with
-arguments the value associated with the key in that thread. The
-|destr_function| is not called if that value is !NULL!. The order in
-which destructor functions are called at thread termination time is
-unspecified.
-
-Before the destructor function is called, the !NULL! value is
-associated with the key in the current thread.  A destructor function
-might, however, re-associate non-!NULL! values to that key or some
-other key.  To deal with this, if after all the destructors have been
-called for all non-!NULL! values, there are still some non-!NULL!
-values with associated destructors, then the process is repeated.  The
-LinuxThreads implementation stops the process after
-!PTHREAD_DESTRUCTOR_ITERATIONS! iterations, even if some non-!NULL!
-values with associated descriptors remain.  Other implementations may
-loop indefinitely.
-
-!pthread_key_delete! deallocates a TSD key. It does not check whether
-non-!NULL! values are associated with that key in the currently
-executing threads, nor call the destructor function associated with
-the key.
-
-!pthread_setspecific! changes the value associated with |key| in the
-calling thread, storing the given |pointer| instead.
-
-!pthread_getspecific! returns the value currently associated with
-|key| in the calling thread.
-
-.SH "RETURN VALUE"
-
-!pthread_key_create!, !pthread_key_delete!, and !pthread_setspecific!
-return 0 on success and a non-zero error code on failure. If
-successful, !pthread_key_create! stores the newly allocated key in the
-location pointed to by its |key| argument.
-
-!pthread_getspecific! returns the value associated with |key| on
-success, and !NULL! on error.
-
-.SH ERRORS
-!pthread_key_create! returns the following error code on error:
-.RS
-.TP
-!EAGAIN!
-!PTHREAD_KEYS_MAX! keys are already allocated
-.RE
-
-!pthread_key_delete! and !pthread_setspecific! return the following
-error code on error:
-.RS
-.TP
-!EINVAL!
-|key| is not a valid, allocated TSD key
-.RE
-
-!pthread_getspecific! returns !NULL! if |key| is not a valid,
-allocated TSD key.
-
-.SH AUTHOR
-Xavier Leroy <Xavier.Leroy@inria.fr>
-
-.SH "SEE ALSO"
-pthread_create(3), pthread_exit(3), pthread_testcancel(3).
-
-.SH EXAMPLE
-
-The following code fragment allocates a thread-specific array of 100
-characters, with automatic reclaimation at thread exit:
-
-.RS
-.ft 3
-.nf
-.sp
-/* Key for the thread-specific buffer */
-static pthread_key_t buffer_key;
-
-/* Once-only initialisation of the key */
-static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
-
-/* Allocate the thread-specific buffer */
-void buffer_alloc(void)
-{
-  pthread_once(&buffer_key_once, buffer_key_alloc);
-  pthread_setspecific(buffer_key, malloc(100));
-}
-
-/* Return the thread-specific buffer */
-char * get_buffer(void)
-{
-  return (char *) pthread_getspecific(buffer_key);
-}
-
-/* Allocate the key */
-static void buffer_key_alloc()
-{
-  pthread_key_create(&buffer_key, buffer_destroy);
-}
-
-/* Free the thread-specific buffer */
-static void buffer_destroy(void * buf)
-{
-  free(buf);
-}
-.ft
-.LP
-.RE
-.fi