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 Feb 07, 2015 15.Dt PTHREAD_ATTR_GET_NP 3C 16.Os 17.Sh NAME 18.Nm pthread_attr_get_np 19.Nd get pthread attributes of a running thread 20.Sh SYNOPSIS 21.In pthread.h 22.Ft int 23.Fo pthread_attr_get_np 24.Fa "pthread_t thread" 25.Fa "pthread_attr_t *attr" 26.Fc 27.Sh DESCRIPTION 28The 29.Fn pthread_attr_get_np 30function provides a way to get the attributes of the thread 31.Fa thread 32after it has been created. This function is most commonly used to obtain 33the actual location and size of a thread's stack. 34.Pp 35The attributes pointer, 36.Fa attr , 37will be filled in with the current attributes for the thread. The 38attributes should be allocated by a call to 39.Xr pthread_attr_init 3C 40prior to calling the 41.Fn pthrad_attr_get_np 42function. When 43.Fa attr 44is done being used, it should be destroyed through a call to 45.Xr pthread_attr_destroy 3C . 46.Pp 47The attributes of the thread 48.Fa thread 49will be the same as those passed in at the time 50.Xr pthread_create 3C 51was called (or the default set if none were specified), except that the 52following values will be updated: 53.Bl -tag -width Sy 54.It Sy Thread Stack Size 55If no explicit stack size was specified, then 56.Fa attr 57will contain the actual size of the stack. 58.Pp 59If the size of the stack was specified, then it may have been changed to 60ensure that the required alignment of the platform is satisfied. 61.It Sy The Stack Address 62If no stack address was specified, then 63.Fa attr 64will contain the actual address of the stack that the system allocated 65for the thread. 66.It Sy Thread Detach State 67The detach state, whether or not the thread may be joined by a call to 68.Xr pthread_join 3C , 69may have changed since the process was created due to a call to 70.Xr pthread_detach 3C . 71.Fa attr 72will reflect the current setting of 73.Fa thread . 74.It Sy Thread Scheduling Parameter 75The scheduling parameter attribute will be updated with the current 76scheduling parameter of 77.Fa thread . 78This is the same information as available through 79.Xr pthread_getschedparam 3C 80and it is the preferred interface for obtaining that information. 81.It Sy Thread Scheduling Policy 82The scheduling policy attribute of 83.Fa attr 84will be updated with the current scheduling policy being applied to the 85thread. This may have changed, for example, due to a call to 86.Xr pthread_setschedparam 3C . 87As with the thread's scheduling parameter, the preferred interface for 88obtaining this information is by using 89.Xr pthread_getschedparam 3C . 90.It Sy Thread Guard Size 91The value of the guard size attribute for the thread will be updated to 92reflect the actual size of the guard installed for 93.Fa thread . 94For more information on the guard size of a thread and its purpose, see 95.Xr pthread_attr_getguardsize 3C . 96.El 97.Sh RETURN VALUES 98Upon successful completion, the 99.Fn pthread_attr_get_np 100and 101.Fn pthread_getattr_np 102functions return 103.Sy 0 . 104Otherwise, an error number is returned to indicate the error. 105.Sh EXAMPLES 106The following program demonstrates how to use these functions to get 107the location and stack size of a newly created thread. 108.Bd -literal 109#include <assert.h> 110#include <errno.h> 111#include <pthread.h> 112#include <stdio.h> 113#include <stdlib.h> 114#include <string.h> 115 116static pthread_t g_thr; 117 118void * 119print_stackinfo(void *arg) 120{ 121 int ret; 122 pthread_attr_t attr; 123 pthread_t *thrp = arg; 124 void *stk; 125 size_t stksize; 126 127 if (pthread_attr_init(&attr) != 0) { 128 fprintf(stderr, "failed to init attr: %s\\n", 129 strerror(errno)); 130 exit(1); 131 } 132 133 if (pthread_attr_get_np(*thrp, &attr) != 0) { 134 fprintf(stderr, "failed to get thread attributes: %s\\n", 135 strerror(errno)); 136 exit(1); 137 } 138 139 ret = pthread_attr_getstackaddr(&attr, &stk); 140 assert(ret == 0); 141 ret = pthread_attr_getstacksize(&attr, &stksize); 142 assert(ret == 0); 143 (void) printf("stack base is at %p, it is %d bytes large\\n", 144 stk, stksize); 145 return (NULL); 146} 147 148int 149main(void) 150{ 151 int ret; 152 153 if ((ret = pthread_create(&g_thr, NULL, print_stackinfo, 154 &g_thr) != 0)) { 155 fprintf(stderr, "failed to create a thread: %s\\n", 156 strerror(errno)); 157 exit(1); 158 } 159 160 pthread_join(g_thr, NULL); 161 return (0); 162} 163.Ed 164.Sh ERRORS 165The 166.Fn pthread_attr_get_np 167function will fail if: 168.Bl -tag -width Er 169.It Er EINVAL 170The pthread_attr_t object 171.Fa attr 172was not properly initialized with a call to 173.Xr pthread_attr_init 3C . 174.It Er ESRCH 175No thread could be found corresponding to the specified thread ID, 176.Fa thread . 177.El 178.Sh INTERFACE STABILITY 179.Sy Committed 180.Sh MT-LEVEL 181.Sy MT-Safe 182.Sh SEE ALSO 183.Xr pthread_attr_destroy 3C , 184.Xr pthread_attr_getdetachstate 3C , 185.Xr pthread_attr_getguardsize 3C , 186.Xr pthread_attr_getinheritsched 3C , 187.Xr pthread_attr_getschedparam 3C , 188.Xr pthread_attr_getschedpolicy 3C , 189.Xr pthread_attr_getscope 3C , 190.Xr pthread_attr_getstackaddr 3C , 191.Xr pthread_attr_getstacksize 3C , 192.Xr pthread_attr_init 3C , 193.Xr pthread_create 3C , 194.Xr pthread_detach 3C , 195.Xr pthread_getschedparam 3C , 196.Xr pthread_setschedparam 3C , 197.Xr attributes 5 , 198.Xr threads 5 199