usr/src/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_destroy ,
  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.
  54 The key space is opaque and global to all threads in the process.
  55 Each thread has its own value-space which can be manipulated with the
  56 .Fn tss_get
  57 and
  58 .Fn tss_set
  59 functions.
  60 A given key persists until
  61 .Fn tss_destroy
  62 is called.
  63 .Pp
  64 When a key is created, the value
  65 .Dv NULL
  66 is associated with all current threads.
  67 When a thread is created, the value
  68 .Dv NULL
  69 is assigned as the value for the entire key-space.
  70 .Pp
  71 A key may optionally be created with a destructor function
  72 .Fa dtor .
  73 The function
  74 .Fa dtor
  75 will run when the thread exits (see
  76 .Xr thrd_exit 3C )
  77 if the value for the key is not
  78 .Dv NULL .
  79 The key space's destructors may be run in any order.
  80 When the destructor is run due to a thread exiting, all signals will be blocked.
  81 .Pp
  82 The
  83 .Fn tss_delete
  84 function deletes the key identify by
  85 .Fa key
  86 from the global name-space.
  87 When a key is deleted, no registered destructor is called, it is up to the
  88 calling program to free any storage that was associated with
  89 .Fa key
  90 across all threads.
  91 Because of this propety, it is legal to call
  92 .Fn tss_delete
  93 from inside a destructor.
  94 Any destructors that had been assocaited with
  95 .Fa key
  96 will no longer be called when a thread terminates.
  97 .Ss Obtaining Values
  98 The
  99 .Fn tss_get
 100 function may be used to obtain the value associated with
 101 .Fa key
 102 for the calling thread.
 103 Note that if the calling thread has never set a value, then it will receive the
 104 default value,
 105 .Dv NULL .
 106 .Fn tss_get
 107 may be called from a tss destructor.
 108 .Ss Setting Values
 109 The
 110 .Fn tss_set
 111 function sets the value of the key
 112 .Fa key
 113 for the callling thread to
 114 .Fa value ,
 115 which may be obtained by subsequent calls to
 116 .Fa tss_get .
 117 To remove a value for a specific thread, one may pass
 118 .Dv NULL
 119 in as
 120 .Fa value .
 121 Changing the value of a key with
 122 .Fn tss_set
 123 does not cause any destructors to be invoked.
 124 This means that
 125 .Fn tss_set
 126 may be used in the context of a destructor, but special care must be
 127 taken to avoid leaking storage or causing an infinite loop.
 128 .Sh RETURN VALUES
 129 Upon successful completion, the
 130 .Fn tss_create
 131 and
 132 .Fn tss_set
 133 functions return
 134 .Sy thrd_success .
 135 Otherwise, they return
 136 .Sy thrd_error
 137 to indicate that an error occurred.
 138 .Pp
 139 Upon successful completion, the
 140 .Fn tss_get
 141 function returns the thread-specific value associated with the given
 142 .Fa key .
 143 If no thread-specific value is associated with the key or an invalid key
 144 was passed in, then
 145 .Dv NULL
 146 is returned.
 147 .Sh INTERFACE STABILITY
 148 .Sy Standard
 149 .Sh MT-LEVEL
 150 .Sy MT-Safe
 151 .Sh SEE ALSO
 152 .Xr pthread_getspecific 3C ,
 153 .Xr pthread_key_create 3C ,
 154 .Xr pthread_key_delete 3C ,
 155 .Xr pthread_setspecific 3C ,
 156 .Xr attributes 5