1 TSS(3C)                  Standard C Library Functions                  TSS(3C)
   2 
   3 NAME
   4      tss, tss_create, tss_delete, tss_get, tss_set - thread-specific storage
   5 
   6 SYNOPSIS
   7      #include <threads.h>
   8 
   9      typedef void (*tss_dtor_t)(void *);
  10 
  11      int
  12      tss_create(tss_t *key, tss_dtor_t dtor);
  13 
  14      void
  15      tss_delete(tss_t key);
  16 
  17      void *
  18      tss_get(tss_t key);
  19 
  20      int
  21      tss_set(tss_t key, void *val);
  22 
  23 DESCRIPTION
  24      The tss family of functions create, get, set, and destroy thread-specific
  25      storage.
  26 
  27    Creating and Destroying Thread-Specific Storage
  28      The tss_create() function creates a new thread-specific data key.  The
  29      key space is opaque and global to all threads in the process.  Each
  30      thread has its own value-space which can be manipulated with the
  31      tss_get() and tss_set() functions.  A given key persists until
  32      tss_delete() is called.
  33 
  34      When a key is created, the value NULL is associated with all current
  35      threads.  When a thread is created, the value NULL is assigned as the
  36      value for the entire key-space.
  37 
  38      A key may optionally be created with a destructor function dtor.  The
  39      function dtor will run when the thread exits (see thrd_exit(3C)) if the
  40      value for the key is not NULL.  The key space's destructors may be run in
  41      any order.  When the destructor is run due to a thread exiting, all
  42      signals will be blocked.
  43 
  44      The tss_delete() function deletes the key identify by key from the global
  45      name-space.  When a key is deleted, no registered destructor is called,
  46      it is up to the calling program to free any storage that was associated
  47      with key across all threads.  Because of this property, it is legal to
  48      call tss_delete() from inside a destructor.  Any destructors that had
  49      been associated with key will no longer be called when a thread
  50      terminates.
  51 
  52    Obtaining Values
  53      The tss_get() function may be used to obtain the value associated with
  54      key for the calling thread.  Note that if the calling thread has never
  55      set a value, then it will receive the default value, NULL.  tss_get() may
  56      be called from a tss destructor.
  57 
  58    Setting Values
  59      The tss_set() function sets the value of the key key for the calling
  60      thread to value, which may be obtained by subsequent calls to tss_get.
  61      To remove a value for a specific thread, one may pass NULL in as value.
  62      Changing the value of a key with tss_set() does not cause any destructors
  63      to be invoked.  This means that tss_set() may be used in the context of a
  64      destructor, but special care must be taken to avoid leaking storage or
  65      causing an infinite loop.
  66 
  67 RETURN VALUES
  68      Upon successful completion, the tss_create() and tss_set() functions
  69      return thrd_success.  Otherwise, they return thrd_error to indicate that
  70      an error occurred.
  71 
  72      Upon successful completion, the tss_get() function returns the thread-
  73      specific value associated with the given key.  If no thread-specific
  74      value is associated with the key or an invalid key was passed in, then
  75      NULL is returned.
  76 
  77 INTERFACE STABILITY
  78      Standard
  79 
  80 MT-LEVEL
  81      MT-Safe
  82 
  83 SEE ALSO
  84      pthread_getspecific(3C), pthread_key_create(3C), pthread_key_delete(3C),
  85      pthread_setspecific(3C), attributes(5)
  86 
  87 illumos                         August 20, 2019                        illumos