1.\" Copyright (c) 2003,2004 The DragonFly Project. All rights reserved. 2.\" 3.\" This code is derived from software contributed to The DragonFly Project 4.\" by David Xu <davidxu@freebsd.org> and Matthew Dillon <dillon@backplane.com> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $DragonFly: src/lib/libc/sys/tls.2,v 1.11 2008/05/02 02:05:04 swildner Exp $ 34.\" 35.Dd February 21, 2005 36.Dt TLS 2 37.Os 38.Sh NAME 39.Nm set_tls_area , 40.Nm get_tls_area 41.Nd kernel TLS (thread local storage) support 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/tls.h 46.Ft int 47.Fn set_tls_area "int which" "struct tls_info *info" "size_t infosize" 48.Ft int 49.Fn get_tls_area "int which" "struct tls_info *info" "size_t infosize" 50.Sh DESCRIPTION 51The 52.Fn set_tls_area 53system call creates an entry for the TLS facility 54.Fa which 55representing thread local storage as specified by the 56.Fa info 57structure. A descriptor representing the facility is returned, or -1 if 58an error occurred. The facility may be cleared by specifying a NULL pointer 59and an infosize of 0. 60The 61.Fn get_tls_area 62system call retrieves the requested TLS facility. A descriptor representing 63the facility is returned, or -1 if an error occurred. If you simply want the 64descriptor you may specify a NULL pointer and an infosize of 0. 65.Pp 66The returned descriptor and the TLS mechanism is machine-dependent. On IA32 67three global segment descriptors are supported (0, 1, and 2) and the %gs 68load value is returned. 69.Pp 70The 71.Fa tls_info 72structure passed to 73.Fn set_tls_area 74should first be zerod (to remain compatible with future extensions) 75and then initialized. 76.Bd -literal 77struct tls_info { 78 void *base; /* base address of TLS area */ 79 int size; /* size of TLS area in bytes */ 80}; 81.Ed 82.Pp 83The actual implementation of the area is machine-dependent. If the kernel 84is unable to accommodate the supplied size it may create a larger area. 85If the kernel is unable to accommodate the supplied base address an error 86will be returned. 87.Sh RETURN VALUES 88A return value of 0 is returned on success, -1 on error. 89.Sh EXAMPLE 90.Bd -literal -compact 91 92/* 93 * Pseudo example showing how the TLS system calls work on IA32. 94 */ 95#include <stdio.h> 96#include <unistd.h> 97#include <stdlib.h> 98#include <errno.h> 99#include <sys/tls.h> 100 101int X; 102 103static int getdata(int offset); 104 105int 106main(int ac, char **av) 107{ 108 int i; 109 int gs; 110 struct tls_info info; 111 112 info.base = &X; 113 info.size = sizeof(X); 114 if ((gs = set_tls_area(0, &info, sizeof(info))) < 0) { 115 perror("setarea"); 116 exit(1); 117 } 118 printf("gs = %04x\en", gs); 119 __asm __volatile("mov %0,%%gs" : : "g" (gs) ); 120 121 if (get_tls_area(0, &info, sizeof(info)) < 0) { 122 perror("getarea"); 123 exit(1); 124 } 125 printf("%p/%d\en", info.base, info.size); 126 127 X = 1; 128 printf("should be 1: %d\en", getdata(0)); 129 X = 2; 130 printf("should be 2: %d\en", getdata(0)); 131 132 printf("this should fault:\en"); 133 fflush(stdout); 134 getdata(4); 135 136 return(0); 137} 138 139static int 140getdata(int offset) 141{ 142 int rv; 143 __asm __volatile("movl %%gs:(%0),%%eax; movl %%eax,%1" : "+r" (offset) : "m" 144 (rv) : "ax"); 145 return (rv); 146} 147 148.Ed 149.Sh ERRORS 150.Bl -tag -width Er 151.It Bq Er ERANGE 152The specified facility index, 153.Fa which , 154is not supported. 155.It Bq Er EINVAL 156An invalid parameter has been specified. 157.It Bq Er ENOENT 158(get_tls_area) The specified facility has not been initialized with 159.Fn sys_set_tls_area . 160.El 161.Sh SEE ALSO 162.Xr umtx 2 163.Sh HISTORY 164The 165.Fn set_tls_area , 166and 167.Fn get_tls_area 168function calls first appeared in 169.Dx 1.1 . 170