| .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
| .\" <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH PTHREAD_SETAFFINITY_NP 3 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| pthread_setaffinity_np, pthread_getaffinity_np \- set/get |
| CPU affinity of a thread |
| .SH SYNOPSIS |
| .nf |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .B #include <pthread.h> |
| .PP |
| .BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize , |
| .BI " const cpu_set_t *" cpuset ); |
| .BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize , |
| .BI " cpu_set_t *" cpuset ); |
| .PP |
| Compile and link with \fI\-pthread\fP. |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR pthread_setaffinity_np () |
| function |
| sets the CPU affinity mask of the thread |
| .I thread |
| to the CPU set pointed to by |
| .IR cpuset . |
| If the call is successful, |
| and the thread is not currently running on one of the CPUs in |
| .IR cpuset , |
| then it is migrated to one of those CPUs. |
| .PP |
| The |
| .BR pthread_getaffinity_np () |
| function returns the CPU affinity mask of the thread |
| .I thread |
| in the buffer pointed to by |
| .IR cpuset . |
| .PP |
| For more details on CPU affinity masks, see |
| .BR sched_setaffinity (2). |
| For a description of a set of macros |
| that can be used to manipulate and inspect CPU sets, see |
| .BR CPU_SET (3). |
| .PP |
| The argument |
| .I cpusetsize |
| is the length (in bytes) of the buffer pointed to by |
| .IR cpuset . |
| Typically, this argument would be specified as |
| .IR sizeof(cpu_set_t) . |
| (It may be some other value, if using the macros described in |
| .BR CPU_SET (3) |
| for dynamically allocating a CPU set.) |
| .SH RETURN VALUE |
| On success, these functions return 0; |
| on error, they return a nonzero error number. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| A supplied memory address was invalid. |
| .TP |
| .B EINVAL |
| .RB ( pthread_setaffinity_np ()) |
| The affinity bit mask |
| .I mask |
| contains no processors that are currently physically on the system |
| and permitted to the thread according to any restrictions that |
| may be imposed by the "cpuset" mechanism described in |
| .BR cpuset (7). |
| .TP |
| .BR EINVAL |
| .RB ( pthread_setaffinity_np ()) |
| .I cpuset |
| specified a CPU that was outside the set supported by the kernel. |
| (The kernel configuration option |
| .BR CONFIG_NR_CPUS |
| defines the range of the set supported by the kernel data type |
| .\" cpumask_t |
| used to represent CPU sets.) |
| .\" The raw sched_getaffinity() system call returns the size (in bytes) |
| .\" of the cpumask_t type. |
| .TP |
| .B EINVAL |
| .RB ( pthread_getaffinity_np ()) |
| .I cpusetsize |
| is smaller than the size of the affinity mask used by the kernel. |
| .TP |
| .B ESRCH |
| No thread with the ID |
| .I thread |
| could be found. |
| .SH VERSIONS |
| These functions are provided by glibc since version 2.3.4. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR pthread_setaffinity_np (), |
| .BR pthread_getaffinity_np () |
| T} Thread safety MT-Safe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| These functions are nonstandard GNU extensions; |
| hence the suffix "_np" (nonportable) in the names. |
| .SH NOTES |
| After a call to |
| .BR pthread_setaffinity_np (), |
| the set of CPUs on which the thread will actually run is |
| the intersection of the set specified in the |
| .I cpuset |
| argument and the set of CPUs actually present on the system. |
| The system may further restrict the set of CPUs on which the thread |
| runs if the "cpuset" mechanism described in |
| .BR cpuset (7) |
| is being used. |
| These restrictions on the actual set of CPUs on which the thread |
| will run are silently imposed by the kernel. |
| .PP |
| These functions are implemented on top of the |
| .BR sched_setaffinity (2) |
| and |
| .BR sched_getaffinity (2) |
| system calls. |
| .PP |
| In glibc 2.3.3 only, |
| versions of these functions were provided that did not have a |
| .I cpusetsize |
| argument. |
| Instead the CPU set size given to the underlying system calls was always |
| .IR sizeof(cpu_set_t) . |
| .PP |
| A new thread created by |
| .BR pthread_create (3) |
| inherits a copy of its creator's CPU affinity mask. |
| .SH EXAMPLES |
| In the following program, the main thread uses |
| .BR pthread_setaffinity_np () |
| to set its CPU affinity mask to include CPUs 0 to 7 |
| (which may not all be available on the system), |
| and then calls |
| .BR pthread_getaffinity_np () |
| to check the resulting CPU affinity mask of the thread. |
| .PP |
| .EX |
| #define _GNU_SOURCE |
| #include <pthread.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <errno.h> |
| |
| #define handle_error_en(en, msg) \e |
| do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| int s; |
| cpu_set_t cpuset; |
| pthread_t thread; |
| |
| thread = pthread_self(); |
| |
| /* Set affinity mask to include CPUs 0 to 7. */ |
| |
| CPU_ZERO(&cpuset); |
| for (int j = 0; j < 8; j++) |
| CPU_SET(j, &cpuset); |
| |
| s = pthread_setaffinity_np(thread, sizeof(cpuset), &cpuset); |
| if (s != 0) |
| handle_error_en(s, "pthread_setaffinity_np"); |
| |
| /* Check the actual affinity mask assigned to the thread. */ |
| |
| s = pthread_getaffinity_np(thread, sizeof(cpuset), &cpuset); |
| if (s != 0) |
| handle_error_en(s, "pthread_getaffinity_np"); |
| |
| printf("Set returned by pthread_getaffinity_np() contained:\en"); |
| for (int j = 0; j < CPU_SETSIZE; j++) |
| if (CPU_ISSET(j, &cpuset)) |
| printf(" CPU %d\en", j); |
| |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .SH SEE ALSO |
| .BR sched_setaffinity (2), |
| .BR CPU_SET (3), |
| .BR pthread_attr_setaffinity_np (3), |
| .BR pthread_self (3), |
| .BR sched_getcpu (3), |
| .BR cpuset (7), |
| .BR pthreads (7), |
| .BR sched (7) |