thr_keycreate man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]


       thr_keycreate,  thr_keycreate_once,  thr_setspecific, thr_getspecific -
       thread-specific data functions

       cc -mt [ flag... ] file... [ library... ]
       #include <thread.h>

       int thr_keycreate(thread_key_t *keyp,
	    void (*destructor)(void *));

       int thr_keycreate_once(thread_key_t *keyp,
	    void (*destructor)(void *));

       int thr_setspecific(thread_key_t key, void *value);

       int thr_getspecific(thread_key_t key, void **valuep);

   Create Key
       In general, thread key creation allocates a key that locates data  spe‐
       cific  to  each thread in the process. The key is global to all threads
       in the process, which allows each thread to bind a  value  to  the  key
       once the key has been created. The key independently maintains specific
       values for each binding thread. The  thr_keycreate() function allocates
       a  global  key  namespace,  pointed  to by keyp, that is visible to all
       threads in the process. Each thread is initially	 bound	to  a  private
       element of this key, which allows access to its thread-specific data.

       Upon key creation, a new key is assigned the value  NULL for all active
       threads. Additionally, upon thread  creation,  all  previously  created
       keys in the new thread are assigned the value  NULL.

       Optionally,  a  destructor  function  destructor can be associated with
       each key. Upon thread exit, if a key has a non-null destructor function
       and  the	 thread	 has  a	 non-null  value associated with that key, the
       destructor function is called with the  current	associated  value.  If
       more  than  one destructor exists for a thread when it exits, the order
       of destructor calls is unspecified.

       An exiting thread runs with all signals blocked. All thread termination
       functions,  including  thread-specific  data  destructor functions, are
       called with all signals blocked.

       The thr_keycreate_once() function is identical to  the  thr_keycreate()
       function except that the key pointed to by keyp must be statically ini‐
       tialized	 with  the  value  THR_ONCE_KEY	 before	 calling   thr_keycre‐
       ate_once()  and	the key will be created exactly once.  This is equiva‐
       lent to using pthread_once() to call a onetime initialization  function
       that calls thr_keycreate() to create the data key.

   Set Value
       Once  a	key  has been created, each thread can bind a new value to the
       key using thr_setspecific(). The	 values	 are  unique  to  the  binding
       thread and are  individually maintained.	 These values continue for the
       life of the calling thread.

       Proper synchronization of  key storage and access must  be  ensured  by
       the  caller.  The  value	 argument  to thr_setspecific() is generally a
       pointer to a block of dynamically  allocated  memory  reserved  by  the
       calling thread for its own use. See EXAMPLES below.

       At thread exit, the destructor function, which is associated at time of
       creation,   is called and it uses the specific  key value as  its  sole

   Get Value
       thr_getspecific() stores the current value bound to key for the calling
       thread into the location pointed to by valuep.

       If successful, thr_keycreate(), thr_keycreate_once(), thr_setspecific()
       and  thr_getspecific() return 0. Otherwise, an error number is returned
       to indicate the error.

       If the following	 conditions  occur,  thr_keycreate()  and  thr_keycre‐
       ate_once() return the corresponding error number:

		 The  system  lacked the necessary resources to create another
		 thread-specific data key.

		 Insufficient memory exists to create the key.

       If the following conditions occur, thr_setspecific() returns the corre‐
       sponding error number:

		 Insufficient  memory  exists  to associate the value with the

       The thr_setspecific() function returns the corresponding error number:

		 The key value is invalid.

       Example 1 Call the thread-specific data from more than one thread with‐
       out special initialization.

       In  this	 example,  the	thread-specific	 data  in this function can be
       called from more than one thread without	 special  initialization.  For
       each  argument  passed to the executable,  a thread is created and pri‐
       vately bound to the string-value of that argument.

	 /* cc -mt thisfile.c */

	 #include <stdio.h>
	 #include <stdlib.h>
	 #include <string.h>
	 #include <thread.h>

	 void *thread_specific_data(void *);
	 void cleanup(void*);
	 #define MAX_ARGC 20
	 thread_t tid[MAX_ARGC];
	 int num_threads;

	 main(int argc, char *argv[]) {
	   int i;
	   num_threads = argc - 1;
	   for (i = 0; i < num_threads; i++)
	      thr_create(NULL, 0, thread_specific_data, argv[i+1], 0, &tid[i]);
	   for (i = 0; i < num_threads; i++)
	      thr_join(tid[i], NULL, NULL);
	   return (0);
	 } /* end main */

	 void *
	 thread_specific_data(void *arg) {
	   static thread_key_t key = THR_ONCE_KEY;
	   char *private_data = arg;
	   void *tsd = NULL;
	   void *data;

	   thr_keycreate_once(&key, cleanup);
	   thr_getspecific(key, &tsd);
	   if (tsd == NULL) {
		data = malloc(strlen(private_data) + 1);
		strcpy(data, private_data);
		thr_setspecific(key, data);
		thr_getspecific(key, &tsd);
	   printf("tsd for %d = %s\n", thr_self(), (char *)tsd);
	   thr_getspecific(key, &tsd);
	   printf("tsd for %d remains %s\n", thr_self(), (char *)tsd);
	   return (NULL);
	 } /* end thread_specific_data */

	 cleanup(void *v) {
	   /* application-specific clean-up function */

       See attributes(5) for descriptions of the following attributes:

       │Interface Stability │ Committed	      │
       │MT-Level	    │ MT-Safe	      │

       pthread_once(3C), thr_exit(3C), attributes(5), standards(5)

       The  thr_getspecific() and thr_setspecific() functions  can  be	called
       either  explicitly or implicitly from a thread-specific data destructor
       function. Calling thr_setspecific() from a  destructor  can  result  in
       lost storage or infinite loops.

				  Nov 2, 2007		     THR_KEYCREATE(3C)

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net