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