man3/pthread_setaffinity_np.3

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