← Back to branch summary

~ubuntu-branches/ubuntu/utopic/eglibc/utopic

« back to all changes in this revision

Viewing changes to .pc/all/local-pthread-manpages.diff/linuxthreads/man/pthread_key_create.man

  • Committer: Package Import Robot
  • Author(s): Adam Conrad
  • Date: 2012-10-26 05:14:58 UTC
  • mfrom: (1.5.1) (4.4.22 experimental)
  • Revision ID: package-import@ubuntu.com-20121026051458-oryotr4i03ob5pab
Tags: 2.16-0ubuntu1
* Merge with unreleased 2.16 in Debian experimental, remaining changes:
  - Drop the Breaks line from libc6, which refers to a Debian transition
  - Remove the libc6 recommends on libc6-i686, which we don't build
  - Enable libc6{,-dev}-armel on armhf and libc6{-dev}-armhf on armel
  - Ship update-locale and validlocale in /usr/sbin in libc-bin
  - Don't build locales or locales-all in Ubuntu, we rely on langpacks
  - Heavily mangle the way we do service restarting on major upgrades
  - Use different MIN_KERNEL_SUPPORTED versions than Debian, due to
    buildd needs.  This should be universally bumped to 3.2.0 once all
    our buildds (including the PPA guests) are running precise kernels
  - Build i386 variants as -march=i686, build amd64 with -O3, and build
    ppc64 variants (both 64-bit and 32-bit) with -O3 -fno-tree-vectorize
  - Re-enable unsubmitted-ldconfig-cache-abi.diff and rebuild the cache
    on upgrades from previous versions that used a different constant
  - debian/patches/any/local-CVE-2012-3406.diff: switch to malloc when
    array grows too large to handle via alloca extension (CVE-2012-3406)
  - Build generic i386/i686 flavour with -mno-tls-direct-seg-refs
* Changes added/dropped with this merge while reducing our delta:
  - Stop building glibc docs from the eglibc source, and instead make
    the glibc-docs stub have a hard dependency on glibc-doc-reference
  - Remove outdated conflicts against ancient versions of ia32-libs
  - Drop the tzdata dependency from libc6, it's in required and minimal
  - Use gcc-4.7/g++-4.7 by default on all our supported architectures
  - Save our historical changelog as changelog.ubuntu in the source
  - Drop nscd's libaudit build-dep for now, as libaudit is in universe
  - Drop the unnecessary Breaks from libc6 to locales and locales-all
  - Ship xen's ld.so.conf.d snippet as /etc/ld.so.conf.d/libc6-xen.conf
* Disable hard failures on the test suite for the first upload to raring

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/all/local-pthread-manpages.diff/linuxthreads/man/pthread_key_create.man
 
1
.TH PTHREAD_SPECIFIC 3 LinuxThreads
 
2
 
 
3
.SH NAME
 
4
pthread_key_create, pthread_key_delete, pthread_setspecific, pthread_getspecific \- management of thread-specific data
 
5
 
 
6
.SH SYNOPSIS
 
7
#include <pthread.h>
 
8
 
 
9
int pthread_key_create(pthread_key_t *key, void (*destr_function) (void *));
 
10
 
 
11
int pthread_key_delete(pthread_key_t key);
 
12
 
 
13
int pthread_setspecific(pthread_key_t key, const void *pointer);
 
14
 
 
15
void * pthread_getspecific(pthread_key_t key);
 
16
 
 
17
.SH DESCRIPTION
 
18
 
 
19
Programs often need global or static variables that have different
 
20
values in different threads. Since threads share one memory space,
 
21
this cannot be achieved with regular variables. Thread-specific data
 
22
is the POSIX threads answer to this need.
 
23
 
 
24
Each thread possesses a private memory block, the thread-specific data
 
25
area, or TSD area for short. This area is indexed by TSD keys. The TSD
 
26
area associates values of type !void *! to TSD keys. TSD keys are
 
27
common to all threads, but the value associated with a given TSD key
 
28
can be different in each thread.
 
29
 
 
30
For concreteness, the TSD areas can be viewed as arrays of !void *!
 
31
pointers, TSD keys as integer indices into these arrays, and the value
 
32
of a TSD key as the value of the corresponding array element in the
 
33
calling thread.
 
34
 
 
35
When a thread is created, its TSD area initially associates !NULL!
 
36
with all keys.
 
37
 
 
38
!pthread_key_create! allocates a new TSD key. The key is stored in the
 
39
location pointed to by |key|. There is a limit of !PTHREAD_KEYS_MAX!
 
40
on the number of keys allocated at a given time. The value initially
 
41
associated with the returned key is !NULL! in all currently executing
 
42
threads.
 
43
 
 
44
The |destr_function| argument, if not !NULL!, specifies a destructor
 
45
function associated with the key. When a thread terminates via
 
46
!pthread_exit! or by cancellation, |destr_function| is called with
 
47
arguments the value associated with the key in that thread. The
 
48
|destr_function| is not called if that value is !NULL!. The order in
 
49
which destructor functions are called at thread termination time is
 
50
unspecified.
 
51
 
 
52
Before the destructor function is called, the !NULL! value is
 
53
associated with the key in the current thread.  A destructor function
 
54
might, however, re-associate non-!NULL! values to that key or some
 
55
other key.  To deal with this, if after all the destructors have been
 
56
called for all non-!NULL! values, there are still some non-!NULL!
 
57
values with associated destructors, then the process is repeated.  The
 
58
LinuxThreads implementation stops the process after
 
59
!PTHREAD_DESTRUCTOR_ITERATIONS! iterations, even if some non-!NULL!
 
60
values with associated descriptors remain.  Other implementations may
 
61
loop indefinitely.
 
62
 
 
63
!pthread_key_delete! deallocates a TSD key. It does not check whether
 
64
non-!NULL! values are associated with that key in the currently
 
65
executing threads, nor call the destructor function associated with
 
66
the key.
 
67
 
 
68
!pthread_setspecific! changes the value associated with |key| in the
 
69
calling thread, storing the given |pointer| instead.
 
70
 
 
71
!pthread_getspecific! returns the value currently associated with
 
72
|key| in the calling thread.
 
73
 
 
74
.SH "RETURN VALUE"
 
75
 
 
76
!pthread_key_create!, !pthread_key_delete!, and !pthread_setspecific!
 
77
return 0 on success and a non-zero error code on failure. If
 
78
successful, !pthread_key_create! stores the newly allocated key in the
 
79
location pointed to by its |key| argument.
 
80
 
 
81
!pthread_getspecific! returns the value associated with |key| on
 
82
success, and !NULL! on error.
 
83
 
 
84
.SH ERRORS
 
85
!pthread_key_create! returns the following error code on error:
 
86
.RS
 
87
.TP
 
88
!EAGAIN!
 
89
!PTHREAD_KEYS_MAX! keys are already allocated
 
90
.RE
 
91
 
 
92
!pthread_key_delete! and !pthread_setspecific! return the following
 
93
error code on error:
 
94
.RS
 
95
.TP
 
96
!EINVAL!
 
97
|key| is not a valid, allocated TSD key
 
98
.RE
 
99
 
 
100
!pthread_getspecific! returns !NULL! if |key| is not a valid,
 
101
allocated TSD key.
 
102
 
 
103
.SH AUTHOR
 
104
Xavier Leroy <Xavier.Leroy@inria.fr>
 
105
 
 
106
.SH "SEE ALSO"
 
107
pthread_create(3), pthread_exit(3), pthread_testcancel(3).
 
108
 
 
109
.SH EXAMPLE
 
110
 
 
111
The following code fragment allocates a thread-specific array of 100
 
112
characters, with automatic reclaimation at thread exit:
 
113
 
 
114
.RS
 
115
.ft 3
 
116
.nf
 
117
.sp
 
118
/* Key for the thread-specific buffer */
 
119
static pthread_key_t buffer_key;
 
120
 
 
121
/* Once-only initialisation of the key */
 
122
static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
 
123
 
 
124
/* Allocate the thread-specific buffer */
 
125
void buffer_alloc(void)
 
126
{
 
127
  pthread_once(&buffer_key_once, buffer_key_alloc);
 
128
  pthread_setspecific(buffer_key, malloc(100));
 
129
}
 
130
 
 
131
/* Return the thread-specific buffer */
 
132
char * get_buffer(void)
 
133
{
 
134
  return (char *) pthread_getspecific(buffer_key);
 
135
}
 
136
 
 
137
/* Allocate the key */
 
138
static void buffer_key_alloc()
 
139
{
 
140
  pthread_key_create(&buffer_key, buffer_destroy);
 
141
}
 
142
 
 
143
/* Free the thread-specific buffer */
 
144
static void buffer_destroy(void * buf)
 
145
{
 
146
  free(buf);
 
147
}
 
148
.ft
 
149
.LP
 
150
.RE
 
151
.fi