man3/pthread_setaffinity_np.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH PTHREAD_SETAFFINITY_NP 3 2021-03-22 "Linux man-pages (unreleased)"
   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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 VERSIONS
  97 These functions are provided by glibc since version 2.3.4.
  98 .SH ATTRIBUTES
  99 For an explanation of the terms used in this section, see
 100 .BR attributes (7).
 101 .ad l
 102 .nh
 103 .TS
 104 allbox;
 105 lbx lb lb
 106 l l l.
 107 Interface       Attribute       Value
 108 T{
 109 .BR pthread_setaffinity_np (),
 110 .BR pthread_getaffinity_np ()
 111 T}      Thread safety   MT-Safe
 112 .TE
 113 .hy
 114 .ad
 115 .sp 1
 116 .SH STANDARDS
 117 These functions are nonstandard GNU extensions;
 118 hence the suffix "_np" (nonportable) in the names.
 119 .SH NOTES
 120 After a call to
 121 .BR pthread_setaffinity_np (),
 122 the set of CPUs on which the thread will actually run is
 123 the intersection of the set specified in the
 124 .I cpuset
 125 argument and the set of CPUs actually present on the system.
 126 The system may further restrict the set of CPUs on which the thread
 127 runs if the "cpuset" mechanism described in
 128 .BR cpuset (7)
 129 is being used.
 130 These restrictions on the actual set of CPUs on which the thread
 131 will run are silently imposed by the kernel.
 132 .PP
 133 These functions are implemented on top of the
 134 .BR sched_setaffinity (2)
 135 and
 136 .BR sched_getaffinity (2)
 137 system calls.
 138 .PP
 139 In glibc 2.3.3 only,
 140 versions of these functions were provided that did not have a
 141 .I cpusetsize
 142 argument.
 143 Instead the CPU set size given to the underlying system calls was always
 144 .IR sizeof(cpu_set_t) .
 145 .PP
 146 A new thread created by
 147 .BR pthread_create (3)
 148 inherits a copy of its creator's CPU affinity mask.
 149 .SH EXAMPLES
 150 In the following program, the main thread uses
 151 .BR pthread_setaffinity_np ()
 152 to set its CPU affinity mask to include CPUs 0 to 7
 153 (which may not all be available on the system),
 154 and then calls
 155 .BR pthread_getaffinity_np ()
 156 to check the resulting CPU affinity mask of the thread.
 157 .PP
 158 .EX
 159 #define _GNU_SOURCE
 160 #include <pthread.h>
 161 #include <stdio.h>
 162 #include <stdlib.h>
 163 #include <errno.h>
 164
 165 #define handle_error_en(en, msg) \e
 166         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 167
 168 int
 169 main(int argc, char *argv[])
 170 {
 171     int s;
 172     cpu_set_t cpuset;
 173     pthread_t thread;
 174
 175     thread = pthread_self();
 176
 177     /* Set affinity mask to include CPUs 0 to 7. */
 178
 179     CPU_ZERO(&cpuset);
 180     for (int j = 0; j < 8; j++)
 181         CPU_SET(j, &cpuset);
 182
 183     s = pthread_setaffinity_np(thread, sizeof(cpuset), &cpuset);
 184     if (s != 0)
 185         handle_error_en(s, "pthread_setaffinity_np");
 186
 187     /* Check the actual affinity mask assigned to the thread. */
 188
 189     s = pthread_getaffinity_np(thread, sizeof(cpuset), &cpuset);
 190     if (s != 0)
 191         handle_error_en(s, "pthread_getaffinity_np");
 192
 193     printf("Set returned by pthread_getaffinity_np() contained:\en");
 194     for (int j = 0; j < CPU_SETSIZE; j++)
 195         if (CPU_ISSET(j, &cpuset))
 196             printf("    CPU %d\en", j);
 197
 198     exit(EXIT_SUCCESS);
 199 }
 200 .EE
 201 .SH SEE ALSO
 202 .BR sched_setaffinity (2),
 203 .BR CPU_SET (3),
 204 .BR pthread_attr_setaffinity_np (3),
 205 .BR pthread_self (3),
 206 .BR sched_getcpu (3),
 207 .BR cpuset (7),
 208 .BR pthreads (7),
 209 .BR sched (7)