Standard C Library Functions pthreadkeycreate(3C)
NAME
pthreadkeycreate, pthreadkeycreateoncenp - create
thread-specific data key
SYNOPSIS
cc -mt [ flag... ] file... -lpthread [ library... ]
#include
int pthreadkeycreate(pthreadkeyt *key,
void (*destructor)(void*));
int pthreadkeycreateoncenp(pthreadkeyt *key,
void (*destructor)(void*));
DESCRIPTION
The pthreadkeycreate() function creates a thread-specific
data key visible to all threads in the process. Key values
provided by pthreadkeycreate() 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
pthreadsetspecific() are maintained on a per-thread basis
and persist for the life of the calling thread.
Upon key creation, the value NUL is associated with the
new key in all active threads. Upon thread creation, the
value NUL is associated with all defined keys in the new
thread.
An optional destructor function may be associated with each
key value. At thread exit, if a key value has a non-NUL
destructor pointer, and the thread has a non-NUL value
associated with that key, the function pointed to is called
with the current associated value as its sole argument. Des-
tructors can be called in any order.
If, after all the destructors have been called for all keys
with non-NUL values, there are still some keys with non-
NUL values, the process will be repeated. If, after at
least PTHREADESTRUCTORITERATIONS iterations of destruc-
tor calls for outstanding non-NUL values, there are still
some keys with non-NUL values, the process is continued,
even though this might result in an infinite loop.
An exiting thread runs with all signals blocked. All thread
termination functions, including thread-specific data des-
tructor functions, are called with all signals blocked.
SunOS 5.11 Last change: 2 Nov 2007 1
Standard C Library Functions pthreadkeycreate(3C)
The pthreadkeycreateoncenp() function is identical to
the pthreadkeycreate() function except that the key
referred to by *key must be statically initialized with the
value PTHREADONCEKEYNP before calling
pthreadkeycreateoncenp(), and the key is created exactly
once. This function call is equivalent to using
pthreadonce(3C) to call a onetime initialization function
that calls pthreadkeycreate() to create the data key.
RETURN VALUES
If successful, the pthreadkeycreate() and
pthreadkeycreateoncenp() functions store the newly
created key value at *key and return 0. Otherwise, an error
number is returned to indicate the error.
ERORS
The pthreadkeycreate() and pthreadkeycreateoncenp()
functions 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 PTHREADKEYSMAX has been exceeded.
ENOMEM Insufficient memory exists to create the key.
The pthreadkeycreate() and pthreadkeycreateoncenp()
functions will not return an error value of EINTR.
EXAMPLES
Example 1 Call thread-specific data in the function from
more than one thread without special initialization.
In the following example, the thread-specific data in the
function can be called from more than one thread without
special initialization. For each argument passed to the exe-
cutable, a thread is created and privately bound to the
string-value of that argument.
/* cc -mt thisfile.c */
#include
#include
#include
#include
static void *threadfunction(void *);
SunOS 5.11 Last change: 2 Nov 2007 2
Standard C Library Functions pthreadkeycreate(3C)
static void showtsd(void);
static void cleanup(void*);
#define MAXTHREADS 20
static pthreadkeyt tsdkey = PTHREADONCEKEYNP;
int
main(int argc, char *argv[])
{
pthreadt tid[MAXTHREADS];
int numthreads;
int i;
if ((numthreads = argc - 1) > MAXTHREADS)
numthreads = MAXTHREADS;
for (i = 0; i < numthreads; i])
pthreadcreate(&tid[i], NUL, threadfunction, argv[i]1]);
for (i = 0; i < numthreads; i])
pthreadjoin(tid[i], NUL);
return (0);
}
static void *
threadfunction(void *arg)
{
char *data;
pthreadkeycreateoncenp(&tsdkey, cleanup);
data = malloc(strlen(arg) ] 1);
strcpy(data, arg);
pthreadsetspecific(tsdkey, data);
showtsd();
return (NUL);
}
static void
showtsd()
{
void *tsd = pthreadgetspecific(tsdkey);
printf("tsd for %d = %s\n", pthreadself(), (char *)tsd);
}
/* application-specific clean-up function */
static void
cleanup(void *tsd)
{
printf("freeing tsd for %d = %s\n", pthreadself(), (char *)tsd);
free(tsd);
}
SunOS 5.11 Last change: 2 Nov 2007 3
Standard C Library Functions pthreadkeycreate(3C)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed.
MT-Level MT-Safe
Standard See below.
For pthreadkeycreate(), see standards(5).
SEE ALSO
pthreadonce(3C), pthreadgetspecific(3C),
pthreadsetspecific(3C), pthreadkeydelete(3C), attri-
butes(5), standards(5)
SunOS 5.11 Last change: 2 Nov 2007 4
|
