1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH PTHREAD_ATTR_SETSCOPE 3 2021-03-22 "Linux" "Linux Programmer's Manual"
28 pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope
29 attribute in thread attributes object
32 .B #include <pthread.h>
34 .BI "int pthread_attr_setscope(pthread_attr_t *" attr ", int " scope );
35 .BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr ,
36 .BI " int *restrict " scope );
38 Compile and link with \fI\-pthread\fP.
42 .BR pthread_attr_setscope ()
43 function sets the contention scope attribute of the
44 thread attributes object referred to by
46 to the value specified in
48 The contention scope attribute defines the set of threads
49 against which a thread competes for resources such as the CPU.
50 POSIX.1 specifies two possible values for
53 .B PTHREAD_SCOPE_SYSTEM
54 The thread competes for resources with all other threads
55 in all processes on the system that are in the same scheduling
56 allocation domain (a group of one or more processors).
57 .B PTHREAD_SCOPE_SYSTEM
58 threads are scheduled relative to one another
59 according to their scheduling policy and priority.
61 .B PTHREAD_SCOPE_PROCESS
62 The thread competes for resources with all other threads
63 in the same process that were also created with the
64 .BR PTHREAD_SCOPE_PROCESS
66 .BR PTHREAD_SCOPE_PROCESS
67 threads are scheduled relative to other threads in the process
68 according to their scheduling policy and priority.
69 POSIX.1 leaves it unspecified how these threads contend
70 with other threads in other process on the system or
71 with other threads in the same process that
73 .B PTHREAD_SCOPE_SYSTEM
76 POSIX.1 requires that an implementation support at least one of these
79 .BR PTHREAD_SCOPE_SYSTEM ,
81 .BR PTHREAD_SCOPE_PROCESS .
83 On systems that support multiple contention scopes, then,
84 in order for the parameter setting made by
85 .BR pthread_attr_setscope ()
86 to have effect when calling
87 .BR pthread_create (3),
89 .BR pthread_attr_setinheritsched (3)
90 to set the inherit-scheduler attribute of the attributes object
93 .BR PTHREAD_EXPLICIT_SCHED .
96 .BR pthread_attr_getscope ()
97 function returns the contention scope attribute of the
98 thread attributes object referred to by
100 in the buffer pointed to by
103 On success, these functions return 0;
104 on error, they return a nonzero error number.
106 .BR pthread_attr_setscope ()
107 can fail with the following errors:
110 An invalid value was specified in
116 .BR PTHREAD_SCOPE_PROCESS ,
117 which is not supported on Linux.
119 For an explanation of the terms used in this section, see
127 Interface Attribute Value
129 .BR pthread_attr_setscope (),
130 .BR pthread_attr_getscope ()
131 T} Thread safety MT-Safe
137 POSIX.1-2001, POSIX.1-2008.
140 .B PTHREAD_SCOPE_SYSTEM
141 contention scope typically indicates that a user-space thread is
142 bound directly to a single kernel-scheduling entity.
143 This is the case on Linux for the obsolete LinuxThreads implementation
144 and the modern NPTL implementation,
145 which are both 1:1 threading implementations.
147 POSIX.1 specifies that the default contention scope is
148 implementation-defined.
152 .BR pthread_attr_init (3),
153 .BR pthread_attr_setaffinity_np (3),
154 .BR pthread_attr_setinheritsched (3),
155 .BR pthread_attr_setschedparam (3),
156 .BR pthread_attr_setschedpolicy (3),
157 .BR pthread_create (3),