share/man/man3c/tss.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd "Jan 11, 2015"
  15 .Dt TSS 3C
  16 .Os
  17 .Sh NAME
  18 .Nm tss ,
  19 .Nm tss_create ,
  20 .Nm tss_delete ,
  21 .Nm tss_get ,
  22 .Nm tss_set
  23 .Nd thread-specific storage
  24 .Sh SYNOPSIS
  25 .In threads.h
  26 .Vt "typedef void (*tss_dtor_t)(void *);"
  27 .Ft int
  28 .Fo tss_create
  29 .Fa "tss_t *key"
  30 .Fa "tss_dtor_t dtor"
  31 .Fc
  32 .Ft void
  33 .Fo tss_delete
  34 .Fa "tss_t key"
  35 .Fc
  36 .Ft void *
  37 .Fo tss_get
  38 .Fa "tss_t key"
  39 .Fc
  40 .Ft int
  41 .Fo tss_set
  42 .Fa "tss_t key"
  43 .Fa "void *val"
  44 .Fc
  45 .Sh DESCRIPTION
  46 The
  47 .Sy tss
  48 family of functions create, get, set, and destroy thread-specific
  49 storage.
  50 .Ss Creating and Destorying Thread-Specific Storage
  51 The
  52 .Fn tss_create
  53 function creates a new thread-specific data key. The key space is opaque
  54 and global to all threads in the process. Each thread has its own
  55 value-space which can be mainpulated with the
  56 .Fn tss_get
  57 and
  58 .Fn tss_set
  59 functions. A given key persists until
  60 .Fn tss_delete
  61 is called.
  62 .Pp
  63 When a key is created, the value
  64 .Dv NULL
  65 is associated with all current threads. When a thread is created, the
  66 value
  67 .Dv NULL
  68 is assigned as the value for the entire key-space.
  69 .Pp
  70 A key may optionally be created with a destructor function
  71 .Fa dtor .
  72 The function
  73 .Fa dtor
  74 will run when the thread exits (see
  75 .Xr thrd_exit 3C )
  76 if the value for the key is not
  77 .Dv NULL .
  78 The key space's destructors may be run in any order. When the destructor
  79 is run due to a thread exiting, all signals will be blocked.
  80 .Pp
  81 The
  82 .Fn tss_delete
  83 function deletes the key identify by
  84 .Fa key
  85 from the global name-space. When a key is deleted, no registered
  86 destructor is called, it is up to the calling program to free any
  87 storage that was associated with
  88 .Fa key
  89 across all threads. Because of this propety, it is legal to call
  90 .Fn tss_delete
  91 from inside a destructor. Any destructors that had been assocaited with
  92 .Fa key
  93 will no longer be called when a thread terminates.
  94 .Ss Obtaining Values
  95 The
  96 .Fn tss_get
  97 function may be used to obtain the value associated with
  98 .Fa key
  99 for the calling thread. Note that if the calling thread has never set a
 100 value, then it will receive the default value,
 101 .Dv NULL .
 102 .Fn tss_get
 103 may be called from a tss destructor.
 104 .Ss Setting Values
 105 The
 106 .Fn tss_set
 107 function sets the value of the key
 108 .Fa key
 109 for the callling thread to
 110 .Fa value ,
 111 which may be obtained by subsequent calls to
 112 .Fa tss_get .
 113 To remove a value for a specific thread, one may pass
 114 .Dv NULL
 115 in as
 116 .Fa value .
 117 Changing the value of a key with
 118 .Fn tss_set
 119 does not cause any destructors to be invoked. This means that
 120 .Fn tss_set
 121 may be used in the context of a destructor, but special care must be
 122 taken to avoid leaking storage or causing an infinite loop.
 123 .Sh RETURN VALUES
 124 Upon successful completion, the
 125 .Fn tss_create
 126 and
 127 .Fn tss_set
 128 functions return
 129 .Sy thrd_success .
 130 Otherwise, they return
 131 .Sy thrd_error
 132 to indicate that an error occurred.
 133 .Pp
 134 Upon successful completion, the
 135 .Fn tss_get
 136 function returns the thread-specific value associated with the given
 137 .Fa key .
 138 If no thread-specific value is associated with the key or an invalid key
 139 was passed in, then
 140 .Dv NULL
 141 is returned.
 142 .Sh INTERFACE STABILITY
 143 .Sy Standard
 144 .Sh MT-LEVEL
 145 .Sy MT-Safe
 146 .Sh SEE ALSO
 147 .Xr pthread_getspecific 3C ,
 148 .Xr pthread_key_create 3C ,
 149 .Xr pthread_key_delete 3C ,
 150 .Xr pthread_setspecific 3C ,
 151 .Xr attributes 5