pthread_setspecific()--Set Thread Local Storage by Key

 #include <pthread.h>
 int pthread_setspecific(pthread_key_t key, const void *value);  

The pthread_setspecific() function sets the thread local storage value associated with a key. The pthread_setspecific() function may be called fromwithin a data destructor.

The thread local storage value is a variable of type void * that is local to a thread, but global to all of the functions called within that thread. It is accessed by the key.

Authorities and Locks

None.

Parameters

key

(Input) The thread local storage key returned from pthread_key_create().

value

(Input) The pointer to store at the key location for the calling thread.

Return Value

0

pthread_setspecific() was successful.

value

pthread_setspecific() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_setspecific() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the key is not correct.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_getspecific()--Get Thread Local Storage Value by Key
  
  
• pthread_key_create()--Create Thread Local Storage Key
  
  
• pthread_key_delete()--Delete Thread Local Storage Key

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include "check.h"

#define         NUMTHREADS    3
pthread_key_t   tlsKey = 0;

void globalDestructor(void *value)
{
  printf("In global destructor\n");
  free(value);
  pthread_setspecific(tlsKey, NULL);
}


void showGlobal(void)
{
  void                 *global;
  pthread_id_np_t       tid;

  global  = pthread_getspecific(tlsKey);
  pthread_getunique_np((pthread_t *)global, &tid);
  printf("showGlobal: global data stored for thread 0x%.8x %.8x\n",
         tid);
}

void *threadfunc(void *parm)
{
  int           rc;
  int          *myThreadDataStructure;
  pthread_t     me = pthread_self();

  printf("Inside secondary thread\n");

  myThreadDataStructure = malloc(sizeof(pthread_t) + sizeof(int) * 10);
  memcpy(myThreadDataStructure, &me, sizeof(pthread_t));
  pthread_setspecific(tlsKey, myThreadDataStructure);
  showGlobal();
  return NULL;
}

int main(int argc, char **argv)
{
  pthread_t             thread[NUMTHREADS];
  int                   rc=0;
  int                   i=0;

  printf("Enter Testcase - %s\n", argv[0]);

  printf("Create a thread local storage key\n");
  rc = pthread_key_create(&tlsKey, globalDestructor);
  checkResults("pthread_key_create()\n", rc);
  /* The key can now be used from all threads */

  printf("Create %d threads using joinable attributes\n",
         NUMTHREADS);
  for (i=0; i<NUMTHREADS; ++i) {
    rc = pthread_create(&thread[i], NULL, threadfunc, NULL);
    checkResults("pthread_create()\n", rc);
  }

  printf("Join to threads\n");
  for (i=0; i<NUMTHREADS; ++i) {
    rc = pthread_join(thread[i], NULL);
    checkResults("pthread_join()\n", rc);
  }

  printf("Delete a thread local storage key\n");
  rc = pthread_key_delete(tlsKey);
  checkResults("pthread_key_delete()\n", rc);
  /* The key and any remaining values are now gone. */
  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPSETS0
Create a thread local storage key
Create 3 threads using joinable attributes
Join to threads
Inside secondary thread
showGlobal: global data stored for thread 0x00000000 0000011a
In global destructor
Inside secondary thread
showGlobal: global data stored for thread 0x00000000 0000011b
In global destructor
Inside secondary thread
showGlobal: global data stored for thread 0x00000000 0000011c
In global destructor
Delete a thread local storage key
Main completed

[ Back to top | Pthread APIs | APIs by category ]