| 1 |
'\" t |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH pthread_attr_init 3 2025-09-21 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
pthread_attr_init, pthread_attr_destroy \- initialize and destroy |
| 9 |
thread attributes object |
| 10 |
.SH LIBRARY |
| 11 |
POSIX threads library |
| 12 |
.RI ( libpthread ,\~ \-lpthread ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.B #include <pthread.h> |
| 16 |
.P |
| 17 |
.BI "int pthread_attr_init(pthread_attr_t *" attr ); |
| 18 |
.BI "int pthread_attr_destroy(pthread_attr_t *" attr ); |
| 19 |
.fi |
| 20 |
.SH DESCRIPTION |
| 21 |
The |
| 22 |
.BR pthread_attr_init () |
| 23 |
function initializes the thread attributes object pointed to by |
| 24 |
.I attr |
| 25 |
with default attribute values. |
| 26 |
After this call, individual attributes of the object can be set |
| 27 |
using various related functions (listed under SEE ALSO), |
| 28 |
and then the object can be used in one or more |
| 29 |
.BR pthread_create (3) |
| 30 |
calls that create threads. |
| 31 |
.P |
| 32 |
Calling |
| 33 |
.BR pthread_attr_init () |
| 34 |
on a thread attributes object that has already been initialized |
| 35 |
results in undefined behavior. |
| 36 |
.P |
| 37 |
When a thread attributes object is no longer required, |
| 38 |
it should be destroyed using the |
| 39 |
.BR pthread_attr_destroy () |
| 40 |
function. |
| 41 |
Destroying a thread attributes object has no effect |
| 42 |
on threads that were created using that object. |
| 43 |
.P |
| 44 |
Once a thread attributes object has been destroyed, |
| 45 |
it can be reinitialized using |
| 46 |
.BR pthread_attr_init (). |
| 47 |
Any other use of a destroyed thread attributes object |
| 48 |
has undefined results. |
| 49 |
.SH RETURN VALUE |
| 50 |
On success, these functions return 0; |
| 51 |
on error, they return a nonzero error number. |
| 52 |
.SH ERRORS |
| 53 |
POSIX.1 documents an |
| 54 |
.B ENOMEM |
| 55 |
error for |
| 56 |
.BR pthread_attr_init (); |
| 57 |
on Linux these functions always succeed |
| 58 |
(but portable and future-proof applications should nevertheless |
| 59 |
handle a possible error return). |
| 60 |
.SH ATTRIBUTES |
| 61 |
For an explanation of the terms used in this section, see |
| 62 |
.BR attributes (7). |
| 63 |
.TS |
| 64 |
allbox; |
| 65 |
lbx lb lb |
| 66 |
l l l. |
| 67 |
Interface Attribute Value |
| 68 |
T{ |
| 69 |
.na |
| 70 |
.nh |
| 71 |
.BR pthread_attr_init (), |
| 72 |
.BR pthread_attr_destroy () |
| 73 |
T} Thread safety MT-Safe |
| 74 |
.TE |
| 75 |
.SH STANDARDS |
| 76 |
POSIX.1-2008. |
| 77 |
.SH HISTORY |
| 78 |
POSIX.1-2001. |
| 79 |
.SH NOTES |
| 80 |
The |
| 81 |
.I pthread_attr_t |
| 82 |
type should be treated as opaque: |
| 83 |
any access to the object other than via pthreads functions |
| 84 |
is nonportable and produces undefined results. |
| 85 |
.SH EXAMPLES |
| 86 |
The program below optionally makes use of |
| 87 |
.BR pthread_attr_init () |
| 88 |
and various related functions to initialize a thread attributes |
| 89 |
object that is used to create a single thread. |
| 90 |
Once created, the thread uses the |
| 91 |
.BR pthread_getattr_np (3) |
| 92 |
function (a nonstandard GNU extension) to retrieve the thread's |
| 93 |
attributes, and then displays those attributes. |
| 94 |
.P |
| 95 |
If the program is run with no command-line argument, |
| 96 |
then it passes NULL as the |
| 97 |
.I attr |
| 98 |
argument of |
| 99 |
.BR pthread_create (3), |
| 100 |
so that the thread is created with default attributes. |
| 101 |
Running the program on Linux/x86-32 with the NPTL threading implementation, |
| 102 |
we see the following: |
| 103 |
.P |
| 104 |
.in +4n |
| 105 |
.EX |
| 106 |
.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 |
| 107 |
.RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" |
| 108 |
unlimited |
| 109 |
.RB "$" " ./a.out" |
| 110 |
Thread attributes: |
| 111 |
Detach state = PTHREAD_CREATE_JOINABLE |
| 112 |
Scope = PTHREAD_SCOPE_SYSTEM |
| 113 |
Inherit scheduler = PTHREAD_INHERIT_SCHED |
| 114 |
Scheduling policy = SCHED_OTHER |
| 115 |
Scheduling priority = 0 |
| 116 |
Guard size = 4096 bytes |
| 117 |
Stack address = 0x40196000 |
| 118 |
Stack size = 0x201000 bytes |
| 119 |
.EE |
| 120 |
.in |
| 121 |
.P |
| 122 |
When we supply a stack size as a command-line argument, |
| 123 |
the program initializes a thread attributes object, |
| 124 |
sets various attributes in that object, |
| 125 |
and passes a pointer to the object in the call to |
| 126 |
.BR pthread_create (3). |
| 127 |
Running the program on Linux/x86-32 with the NPTL threading implementation, |
| 128 |
we see the following: |
| 129 |
.P |
| 130 |
.in +4n |
| 131 |
.EX |
| 132 |
.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 |
| 133 |
.RB "$" " ./a.out 0x3000000" |
| 134 |
posix_memalign() allocated at 0x40197000 |
| 135 |
Thread attributes: |
| 136 |
Detach state = PTHREAD_CREATE_DETACHED |
| 137 |
Scope = PTHREAD_SCOPE_SYSTEM |
| 138 |
Inherit scheduler = PTHREAD_EXPLICIT_SCHED |
| 139 |
Scheduling policy = SCHED_OTHER |
| 140 |
Scheduling priority = 0 |
| 141 |
Guard size = 0 bytes |
| 142 |
Stack address = 0x40197000 |
| 143 |
Stack size = 0x3000000 bytes |
| 144 |
.EE |
| 145 |
.in |
| 146 |
.SS Program source |
| 147 |
\& |
| 148 |
.\" SRC BEGIN (pthread_attr_init.c) |
| 149 |
.EX |
| 150 |
#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ |
| 151 |
#include <err.h> |
| 152 |
#include <errno.h> |
| 153 |
#include <pthread.h> |
| 154 |
#include <stdio.h> |
| 155 |
#include <stdlib.h> |
| 156 |
#include <unistd.h> |
| 157 |
\& |
| 158 |
static void |
| 159 |
display_pthread_attr(pthread_attr_t *attr, char *prefix) |
| 160 |
{ |
| 161 |
int s, i; |
| 162 |
size_t v; |
| 163 |
void *stkaddr; |
| 164 |
struct sched_param sp; |
| 165 |
\& |
| 166 |
s = pthread_attr_getdetachstate(attr, &i); |
| 167 |
if (s != 0) |
| 168 |
errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate"); |
| 169 |
printf("%sDetach state = %s\[rs]n", prefix, |
| 170 |
(i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : |
| 171 |
(i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : |
| 172 |
"???"); |
| 173 |
\& |
| 174 |
s = pthread_attr_getscope(attr, &i); |
| 175 |
if (s != 0) |
| 176 |
errc(EXIT_FAILURE, s, "pthread_attr_getscope"); |
| 177 |
printf("%sScope = %s\[rs]n", prefix, |
| 178 |
(i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : |
| 179 |
(i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : |
| 180 |
"???"); |
| 181 |
\& |
| 182 |
s = pthread_attr_getinheritsched(attr, &i); |
| 183 |
if (s != 0) |
| 184 |
errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched"); |
| 185 |
printf("%sInherit scheduler = %s\[rs]n", prefix, |
| 186 |
(i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : |
| 187 |
(i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : |
| 188 |
"???"); |
| 189 |
\& |
| 190 |
s = pthread_attr_getschedpolicy(attr, &i); |
| 191 |
if (s != 0) |
| 192 |
errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy"); |
| 193 |
printf("%sScheduling policy = %s\[rs]n", prefix, |
| 194 |
(i == SCHED_OTHER) ? "SCHED_OTHER" : |
| 195 |
(i == SCHED_FIFO) ? "SCHED_FIFO" : |
| 196 |
(i == SCHED_RR) ? "SCHED_RR" : |
| 197 |
"???"); |
| 198 |
\& |
| 199 |
s = pthread_attr_getschedparam(attr, &sp); |
| 200 |
if (s != 0) |
| 201 |
errc(EXIT_FAILURE, s, "pthread_attr_getschedparam"); |
| 202 |
printf("%sScheduling priority = %d\[rs]n", prefix, sp.sched_priority); |
| 203 |
\& |
| 204 |
s = pthread_attr_getguardsize(attr, &v); |
| 205 |
if (s != 0) |
| 206 |
errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); |
| 207 |
printf("%sGuard size = %zu bytes\[rs]n", prefix, v); |
| 208 |
\& |
| 209 |
s = pthread_attr_getstack(attr, &stkaddr, &v); |
| 210 |
if (s != 0) |
| 211 |
errc(EXIT_FAILURE, s, "pthread_attr_getstack"); |
| 212 |
printf("%sStack address = %p\[rs]n", prefix, stkaddr); |
| 213 |
printf("%sStack size = %#zx bytes\[rs]n", prefix, v); |
| 214 |
} |
| 215 |
\& |
| 216 |
static void * |
| 217 |
thread_start(void *arg) |
| 218 |
{ |
| 219 |
int s; |
| 220 |
pthread_attr_t gattr; |
| 221 |
\& |
| 222 |
/* pthread_getattr_np() is a non\-standard GNU extension that |
| 223 |
retrieves the attributes of the thread specified in its |
| 224 |
first argument. */ |
| 225 |
\& |
| 226 |
s = pthread_getattr_np(pthread_self(), &gattr); |
| 227 |
if (s != 0) |
| 228 |
errc(EXIT_FAILURE, s, "pthread_getattr_np"); |
| 229 |
\& |
| 230 |
printf("Thread attributes:\[rs]n"); |
| 231 |
display_pthread_attr(&gattr, "\[rs]t"); |
| 232 |
\& |
| 233 |
exit(EXIT_SUCCESS); /* Terminate all threads */ |
| 234 |
} |
| 235 |
\& |
| 236 |
int |
| 237 |
main(int argc, char *argv[]) |
| 238 |
{ |
| 239 |
pthread_t thr; |
| 240 |
pthread_attr_t attr; |
| 241 |
pthread_attr_t *attrp; /* NULL or &attr */ |
| 242 |
int s; |
| 243 |
\& |
| 244 |
attrp = NULL; |
| 245 |
\& |
| 246 |
/* If a command\-line argument was supplied, use it to set the |
| 247 |
stack\-size attribute and set a few other thread attributes, |
| 248 |
and set attrp pointing to thread attributes object. */ |
| 249 |
\& |
| 250 |
if (argc > 1) { |
| 251 |
size_t stack_size; |
| 252 |
void *sp; |
| 253 |
\& |
| 254 |
attrp = &attr; |
| 255 |
\& |
| 256 |
s = pthread_attr_init(&attr); |
| 257 |
if (s != 0) |
| 258 |
errc(EXIT_FAILURE, s, "pthread_attr_init"); |
| 259 |
\& |
| 260 |
s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); |
| 261 |
if (s != 0) |
| 262 |
errc(EXIT_FAILURE, s, "pthread_attr_setdetachstate"); |
| 263 |
\& |
| 264 |
s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); |
| 265 |
if (s != 0) |
| 266 |
errc(EXIT_FAILURE, s, "pthread_attr_setinheritsched"); |
| 267 |
\& |
| 268 |
stack_size = strtoul(argv[1], NULL, 0); |
| 269 |
\& |
| 270 |
s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); |
| 271 |
if (s != 0) |
| 272 |
errc(EXIT_FAILURE, s, "posix_memalign"); |
| 273 |
\& |
| 274 |
printf("posix_memalign() allocated at %p\[rs]n", sp); |
| 275 |
\& |
| 276 |
s = pthread_attr_setstack(&attr, sp, stack_size); |
| 277 |
if (s != 0) |
| 278 |
errc(EXIT_FAILURE, s, "pthread_attr_setstack"); |
| 279 |
} |
| 280 |
\& |
| 281 |
s = pthread_create(&thr, attrp, &thread_start, NULL); |
| 282 |
if (s != 0) |
| 283 |
errc(EXIT_FAILURE, s, "pthread_create"); |
| 284 |
\& |
| 285 |
if (attrp != NULL) { |
| 286 |
s = pthread_attr_destroy(attrp); |
| 287 |
if (s != 0) |
| 288 |
errc(EXIT_FAILURE, s, "pthread_attr_destroy"); |
| 289 |
} |
| 290 |
\& |
| 291 |
pause(); /* Terminates when other thread calls exit() */ |
| 292 |
} |
| 293 |
.EE |
| 294 |
.\" SRC END |
| 295 |
.SH SEE ALSO |
| 296 |
.ad l |
| 297 |
.nh |
| 298 |
.BR pthread_attr_setaffinity_np (3), |
| 299 |
.BR pthread_attr_setdetachstate (3), |
| 300 |
.BR pthread_attr_setguardsize (3), |
| 301 |
.BR pthread_attr_setinheritsched (3), |
| 302 |
.BR pthread_attr_setschedparam (3), |
| 303 |
.BR pthread_attr_setschedpolicy (3), |
| 304 |
.BR pthread_attr_setscope (3), |
| 305 |
.BR pthread_attr_setsigmask_np (3), |
| 306 |
.BR pthread_attr_setstack (3), |
| 307 |
.BR pthread_attr_setstackaddr (3), |
| 308 |
.BR pthread_attr_setstacksize (3), |
| 309 |
.BR pthread_create (3), |
| 310 |
.BR pthread_getattr_np (3), |
| 311 |
.BR pthread_setattr_default_np (3), |
| 312 |
.BR pthreads (7) |