Debian Codegraph @

upstream/debian-unstable/man3/pthread_setaffinity_np.3

raw
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_setaffinity_np 3 2025-09-21 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_setaffinity_np, pthread_getaffinity_np \- set/get
9 CPU affinity of a thread
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ,\~ \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
16 .B #include <pthread.h>
17 .P
18 .BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize ,
19 .BI " const cpu_set_t *" cpuset );
20 .BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize ,
21 .BI " cpu_set_t *" cpuset );
22 .fi
23 .SH DESCRIPTION
24 The
25 .BR pthread_setaffinity_np ()
26 function
27 sets the CPU affinity mask of the thread
28 .I thread
29 to the CPU set pointed to by
30 .IR cpuset .
31 If the call is successful,
32 and the thread is not currently running on one of the CPUs in
33 .IR cpuset ,
34 then it is migrated to one of those CPUs.
35 .P
36 The
37 .BR pthread_getaffinity_np ()
38 function returns the CPU affinity mask of the thread
39 .I thread
40 in the buffer pointed to by
41 .IR cpuset .
42 .P
43 For more details on CPU affinity masks, see
44 .BR sched_setaffinity (2).
45 For a description of a set of macros
46 that can be used to manipulate and inspect CPU sets, see
47 .BR CPU_SET (3).
48 .P
49 The argument
50 .I cpusetsize
51 is the length (in bytes) of the buffer pointed to by
52 .IR cpuset .
53 Typically, this argument would be specified as
54 .IR sizeof(cpu_set_t) .
55 (It may be some other value, if using the macros described in
56 .BR CPU_SET (3)
57 for dynamically allocating a CPU set.)
58 .SH RETURN VALUE
59 On success, these functions return 0;
60 on error, they return a nonzero error number.
61 .SH ERRORS
62 .TP
63 .B EFAULT
64 A supplied memory address was invalid.
65 .TP
66 .B EINVAL
67 .RB ( pthread_setaffinity_np ())
68 The affinity bit mask
69 .I mask
70 contains no processors that are currently physically on the system
71 and permitted to the thread according to any restrictions that
72 may be imposed by the "cpuset" mechanism described in
73 .BR cpuset (7).
74 .TP
75 .B EINVAL
76 .RB ( pthread_setaffinity_np ())
77 .I cpuset
78 specified a CPU that was outside the set supported by the kernel.
79 (The kernel configuration option
80 .B CONFIG_NR_CPUS
81 defines the range of the set supported by the kernel data type
82 .\" cpumask_t
83 used to represent CPU sets.)
84 .\" The raw sched_getaffinity() system call returns the size (in bytes)
85 .\" of the cpumask_t type.
86 .TP
87 .B EINVAL
88 .RB ( pthread_getaffinity_np ())
89 .I cpusetsize
90 is smaller than the size of the affinity mask used by the kernel.
91 .TP
92 .B ESRCH
93 No thread with the ID
94 .I thread
95 could be found.
96 .SH ATTRIBUTES
97 For an explanation of the terms used in this section, see
98 .BR attributes (7).
99 .TS
100 allbox;
101 lbx lb lb
102 l l l.
103 Interface Attribute Value
104 T{
105 .na
106 .nh
107 .BR pthread_setaffinity_np (),
108 .BR pthread_getaffinity_np ()
109 T} Thread safety MT-Safe
110 .TE
111 .SH STANDARDS
112 GNU;
113 hence the suffix "_np" (nonportable) in the names.
114 .SH HISTORY
115 glibc 2.3.4.
116 .P
117 In glibc 2.3.3 only,
118 versions of these functions were provided that did not have a
119 .I cpusetsize
120 argument.
121 Instead the CPU set size given to the underlying system calls was always
122 .IR sizeof(cpu_set_t) .
123 .SH NOTES
124 After a call to
125 .BR pthread_setaffinity_np (),
126 the set of CPUs on which the thread will actually run is
127 the intersection of the set specified in the
128 .I cpuset
129 argument and the set of CPUs actually present on the system.
130 The system may further restrict the set of CPUs on which the thread
131 runs if the "cpuset" mechanism described in
132 .BR cpuset (7)
133 is being used.
134 These restrictions on the actual set of CPUs on which the thread
135 will run are silently imposed by the kernel.
136 .P
137 These functions are implemented on top of the
138 .BR sched_setaffinity (2)
139 and
140 .BR sched_getaffinity (2)
141 system calls.
142 .P
143 A new thread created by
144 .BR pthread_create (3)
145 inherits a copy of its creator's CPU affinity mask.
146 .SH EXAMPLES
147 In the following program, the main thread uses
148 .BR pthread_setaffinity_np ()
149 to set its CPU affinity mask to include CPUs 0 to 7
150 (which may not all be available on the system),
151 and then calls
152 .BR pthread_getaffinity_np ()
153 to check the resulting CPU affinity mask of the thread.
154 .P
155 .\" SRC BEGIN (pthread_setaffinity_np.c)
156 .EX
157 #define _GNU_SOURCE
158 #include <err.h>
159 #include <pthread.h>
160 #include <sched.h>
161 #include <stdio.h>
162 #include <stdlib.h>
163 \&
164 int
165 main(void)
166 {
167 int s;
168 cpu_set_t cpuset;
169 pthread_t thread;
170 \&
171 thread = pthread_self();
172 \&
173 /* Set affinity mask to include CPUs 0 to 7. */
174 \&
175 CPU_ZERO(&cpuset);
176 for (size_t j = 0; j < 8; j++)
177 CPU_SET(j, &cpuset);
178 \&
179 s = pthread_setaffinity_np(thread, sizeof(cpuset), &cpuset);
180 if (s != 0)
181 errc(EXIT_FAILURE, s, "pthread_setaffinity_np");
182 \&
183 /* Check the actual affinity mask assigned to the thread. */
184 \&
185 s = pthread_getaffinity_np(thread, sizeof(cpuset), &cpuset);
186 if (s != 0)
187 errc(EXIT_FAILURE, s, "pthread_getaffinity_np");
188 \&
189 printf("Set returned by pthread_getaffinity_np() contained:\[rs]n");
190 for (size_t j = 0; j < CPU_SETSIZE; j++)
191 if (CPU_ISSET(j, &cpuset))
192 printf(" CPU %zu\[rs]n", j);
193 \&
194 exit(EXIT_SUCCESS);
195 }
196 .EE
197 .\" SRC END
198 .SH SEE ALSO
199 .BR sched_setaffinity (2),
200 .BR CPU_SET (3),
201 .BR pthread_attr_setaffinity_np (3),
202 .BR pthread_self (3),
203 .BR sched_getcpu (3),
204 .BR cpuset (7),
205 .BR pthreads (7),
206 .BR sched (7)