1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .TH PTHREAD_ATTR_SETSCOPE 3 2021-03-22 "Linux" "Linux Programmer's Manual"
8 pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope
9 attribute in thread attributes object
12 .RI ( libpthread ", " \-lpthread )
15 .B #include <pthread.h>
17 .BI "int pthread_attr_setscope(pthread_attr_t *" attr ", int " scope );
18 .BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr ,
19 .BI " int *restrict " scope );
23 .BR pthread_attr_setscope ()
24 function sets the contention scope attribute of the
25 thread attributes object referred to by
27 to the value specified in
29 The contention scope attribute defines the set of threads
30 against which a thread competes for resources such as the CPU.
31 POSIX.1 specifies two possible values for
34 .B PTHREAD_SCOPE_SYSTEM
35 The thread competes for resources with all other threads
36 in all processes on the system that are in the same scheduling
37 allocation domain (a group of one or more processors).
38 .B PTHREAD_SCOPE_SYSTEM
39 threads are scheduled relative to one another
40 according to their scheduling policy and priority.
42 .B PTHREAD_SCOPE_PROCESS
43 The thread competes for resources with all other threads
44 in the same process that were also created with the
45 .BR PTHREAD_SCOPE_PROCESS
47 .BR PTHREAD_SCOPE_PROCESS
48 threads are scheduled relative to other threads in the process
49 according to their scheduling policy and priority.
50 POSIX.1 leaves it unspecified how these threads contend
51 with other threads in other process on the system or
52 with other threads in the same process that
54 .B PTHREAD_SCOPE_SYSTEM
57 POSIX.1 requires that an implementation support at least one of these
60 .BR PTHREAD_SCOPE_SYSTEM ,
62 .BR PTHREAD_SCOPE_PROCESS .
64 On systems that support multiple contention scopes, then,
65 in order for the parameter setting made by
66 .BR pthread_attr_setscope ()
67 to have effect when calling
68 .BR pthread_create (3),
70 .BR pthread_attr_setinheritsched (3)
71 to set the inherit-scheduler attribute of the attributes object
74 .BR PTHREAD_EXPLICIT_SCHED .
77 .BR pthread_attr_getscope ()
78 function returns the contention scope attribute of the
79 thread attributes object referred to by
81 in the buffer pointed to by
84 On success, these functions return 0;
85 on error, they return a nonzero error number.
87 .BR pthread_attr_setscope ()
88 can fail with the following errors:
91 An invalid value was specified in
97 .BR PTHREAD_SCOPE_PROCESS ,
98 which is not supported on Linux.
100 For an explanation of the terms used in this section, see
108 Interface Attribute Value
110 .BR pthread_attr_setscope (),
111 .BR pthread_attr_getscope ()
112 T} Thread safety MT-Safe
118 POSIX.1-2001, POSIX.1-2008.
121 .B PTHREAD_SCOPE_SYSTEM
122 contention scope typically indicates that a user-space thread is
123 bound directly to a single kernel-scheduling entity.
124 This is the case on Linux for the obsolete LinuxThreads implementation
125 and the modern NPTL implementation,
126 which are both 1:1 threading implementations.
128 POSIX.1 specifies that the default contention scope is
129 implementation-defined.
133 .BR pthread_attr_init (3),
134 .BR pthread_attr_setaffinity_np (3),
135 .BR pthread_attr_setinheritsched (3),
136 .BR pthread_attr_setschedparam (3),
137 .BR pthread_attr_setschedpolicy (3),
138 .BR pthread_create (3),