man3/pthread_setaffinity_np.3

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