1 files changed, 151 insertions, 0 deletions
diff --git a/linuxthreads/man/pthread_key_create.man b/linuxthreads/man/pthread_key_create.man
new file mode 100644
index 0000000000..6823e304c9
--- /dev/null
+++ b/linuxthreads/man/pthread_key_create.man
@@ -0,0 +1,151 @@
+.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