1.\" $NetBSD: tss.3,v 1.2 2019/04/27 10:57:11 wiz Exp $ 2.\" 3.\" Copyright (c) 2016 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Kamil Rytarowski. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 16, 2016 31.Dt TSS 3 32.Os 33.Sh NAME 34.Nm tss 35.Nd thread-specific storage functions 36.Sh LIBRARY 37.Lb libpthread 38.Sh SYNOPSIS 39.In threads.h 40.Vt "typedef" "void" "(*tss_dtor_t)" "(void *)" 41.Ft int 42.Fn tss_create "tss_t *key" "tss_dtor_t dtor" 43.Ft void 44.Fn tss_delete "tss_t key" 45.Ft void * 46.Fn tss_get "tss_t key" 47.Ft int 48.Fn tss_set "tss_t key" "void *val" 49.Vt #define TSS_DTOR_ITERATIONS /* implementation specified */ 50.Sh DESCRIPTION 51There are two groups of storage in C programs: 52.Bl -dash 53.It 54local storage, 55.It 56global storage. 57.El 58.Pp 59Multithreaded programs in C add the third group 60.Sy thread-specific storage . 61This data is private to thread and every entry of this type has an associated 62.Dv tss_t 63opaque key that is global to all threads in the process. 64A thread using the 65.Dv tss_t * 66pointer accesses private data. 67.Pp 68The 69.Fn tss_create 70function creates a thread-specific storage with the 71.Fa key 72handler with optional destructor 73.Fa dtor . 74If the 75.Fa dtor 76parameter is not 77.Dv NULL , 78then specified appropriate destructor will be called on thread termination. 79The destructor is not called if a thread called the 80.Fn tss_delete 81function for the specified 82.Fa key . 83If, after all the destructors have been called for all 84.Pf non- Dv NULL 85values with associated destructors, 86there are still some 87.Pf non- Dv NULL 88values with associated destructors, 89then the process is repeated. 90If, after at least 91.Dv TSS_DTOR_ITERATIONS 92iterations of destructor calls for outstanding 93.Pf non- Dv NULL 94values, there are still some 95.Pf non- Dv NULL 96values with associated destructors, the 97.Nx 98implementation stops calling further destructors. 99The 100.Xr thrd_exit 3 101function must not be called from a destructor. 102.Pp 103The 104.Fn tss_delete 105function frees resources used by the thread-specific storage identified by the 106.Fa key 107object. 108This function can be called inside the 109.Fa dtor 110destructor, however the destructor is not called by 111.Fn tss_delete . 112.Pp 113The 114.Fn tss_get 115and 116.Fn tss_set 117functions are used to get and set thread-specific storage. 118.Sh RETURN VALUES 119The 120.Fn tss_create 121function returns 122.Dv thrd_success 123on success, otherwise 124.Dv thrd_error 125on failure. 126.Pp 127The 128.Fn tss_delete 129function returns no value. 130.Pp 131The 132.Fn tss_get 133returns pointer to thread-specific storage on success or 134.Dv NULL 135on failure. 136.Pp 137The 138.Fn tss_set 139function returns 140.Dv thrd_success 141on success, otherwise 142.Dv thrd_error 143on failure. 144.Sh SEE ALSO 145.Xr pthread_getspecific 3 , 146.Xr pthread_key_create 3 , 147.Xr threads 3 148.Sh STANDARDS 149The 150.Nm 151interface conforms to 152.St -isoC-2011 . 153.Sh HISTORY 154This interface first appeared in 155.Nx 9 . 156.Sh AUTHORS 157.An Kamil Rytarowski Aq Mt kamil@NetBSD.org 158