original/man3/pthread_setaffinity_np.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .TH PTHREAD_SETAFFINITY_NP 3 2010-09-10 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 pthread_setaffinity_np, pthread_getaffinity_np \- set/get
  27 CPU affinity of a thread
  28 .SH SYNOPSIS
  29 .nf
  30 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  31 .B #include <pthread.h>
  32
  33 .BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize ,
  34 .BI "                           const cpu_set_t *" cpuset );
  35 .BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize ,
  36 .BI "                           cpu_set_t *" cpuset );
  37 .sp
  38 Compile and link with \fI\-pthread\fP.
  39 .fi
  40 .SH DESCRIPTION
  41 The
  42 .BR pthread_setaffinity_np ()
  43 function
  44 sets the CPU affinity mask of the thread
  45 .I thread
  46 to the CPU set pointed to by
  47 .IR cpuset .
  48 If the call is successful,
  49 and the thread is not currently running on one of the CPUs in
  50 .IR cpuset ,
  51 then it is migrated to one of those CPUs.
  52
  53 The
  54 .BR pthread_getaffinity_np ()
  55 function returns the CPU affinity mask of the thread
  56 .I thread
  57 in the buffer pointed to by
  58 .IR cpuset .
  59
  60 For more details on CPU affinity masks, see
  61 .BR sched_setaffinity (2).
  62 For a description of a set of macros
  63 that can be used to manipulate and inspect CPU sets, see
  64 .BR CPU_SET (3).
  65
  66 The argument
  67 .I cpusetsize
  68 is the length (in bytes) of the buffer pointed to by
  69 .IR cpuset .
  70 Typically, this argument would be specified as
  71 .IR sizeof(cpu_set_t) .
  72 (It may be some other value, if using the macros described in
  73 .BR CPU_SET (3)
  74 for dynamically allocating a CPU set.)
  75 .SH RETURN VALUE
  76 On success, these functions return 0;
  77 on error, they return a nonzero error number.
  78 .SH ERRORS
  79 .TP
  80 .B EFAULT
  81 A supplied memory address was invalid.
  82 .TP
  83 .B EINVAL
  84 .RB ( pthread_setaffinity_np ())
  85 The affinity bit mask
  86 .I mask
  87 contains no processors that are currently physically on the system
  88 and permitted to the thread according to any restrictions that
  89 may be imposed by the "cpuset" mechanism described in
  90 .BR cpuset (7).
  91 .TP
  92 .BR EINVAL
  93 .RB ( pthread_setaffinity_np ())
  94 .I cpuset
  95 specified a CPU that was outside the set supported by the kernel.
  96 (The kernel configuration option
  97 .BR CONFIG_NR_CPUS
  98 .\" FIXME . ?
  99 .\" Loic Domaigne commented: it seems that in the future the
 100 .\" kernel developers want to make cpumask_t dynamic, so
 101 .\" CONFIG_NR_CPUS might become obsolete in the future.
 102 defines the range of the set supported by the kernel data type
 103 .\" cpumask_t
 104 used to represent CPU sets.)
 105 .\" The raw sched_getaffinity() system call returns the size (in bytes)
 106 .\" of the cpumask_t type.
 107 .TP
 108 .B EINVAL
 109 .RB ( pthread_getaffinity_np ())
 110 .I cpusetsize
 111 is smaller than the size of the affinity mask used by the kernel.
 112 .TP
 113 .B ESRCH
 114 No thread with the ID
 115 .I thread
 116 could be found.
 117 .SH VERSIONS
 118 These functions are provided by glibc since version 2.3.4.
 119 .SH CONFORMING TO
 120 These functions are nonstandard GNU extensions;
 121 hence the suffix "_np" (nonportable) in the names.
 122 .SH NOTES
 123 After a call to
 124 .BR pthread_setaffinity_np (),
 125 the set of CPUs on which the thread will actually run is
 126 the intersection of the set specified in the
 127 .I cpuset
 128 argument and the set of CPUs actually present on the system.
 129 The system may further restrict the set of CPUs on which the thread
 130 runs if the "cpuset" mechanism described in
 131 .BR cpuset (7)
 132 is being used.
 133 These restrictions on the actual set of CPUs on which the thread
 134 will run are silently imposed by the kernel.
 135
 136 These functions are implemented on top of the
 137 .BR sched_setaffinity (2)
 138 and
 139 .BR sched_getaffinity (2)
 140 system calls.
 141
 142 In glibc 2.3.3 only,
 143 versions of these functions were provided that did not have a
 144 .I cpusetsize
 145 argument.
 146 Instead the CPU set size given to the underlying system calls was always
 147 .IR sizeof(cpu_set_t) .
 148
 149 A new thread created by
 150 .BR pthread_create (3)
 151 inherits a copy of its creator's CPU affinity mask.
 152 .SH EXAMPLE
 153 In the following program, the main thread uses
 154 .BR pthread_setaffinity_np ()
 155 to set its CPU affinity mask to include CPUs 0 to 7
 156 (which may not all be available on the system),
 157 and then calls
 158 .BR pthread_getaffinity_np ()
 159 to check the resulting CPU affinity mask of the thread.
 160
 161 .nf
 162 #define _GNU_SOURCE
 163 #include <pthread.h>
 164 #include <stdio.h>
 165 #include <stdlib.h>
 166 #include <errno.h>
 167
 168 #define handle_error_en(en, msg) \\
 169         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 170
 171 int
 172 main(int argc, char *argv[])
 173 {
 174     int s, j;
 175     cpu_set_t cpuset;
 176     pthread_t thread;
 177
 178     thread = pthread_self();
 179
 180     /* Set affinity mask to include CPUs 0 to 7 */
 181
 182     CPU_ZERO(&cpuset);
 183     for (j = 0; j < 8; j++)
 184         CPU_SET(j, &cpuset);
 185
 186     s = pthread_setaffinity_np(thread, sizeof(cpu_set_t), &cpuset);
 187     if (s != 0)
 188         handle_error_en(s, "pthread_setaffinity_np");
 189
 190     /* Check the actual affinity mask assigned to the thread */
 191
 192     s = pthread_getaffinity_np(thread, sizeof(cpu_set_t), &cpuset);
 193     if (s != 0)
 194         handle_error_en(s, "pthread_getaffinity_np");
 195
 196     printf("Set returned by pthread_getaffinity_np() contained:\\n");
 197     for (j = 0; j < CPU_SETSIZE; j++)
 198         if (CPU_ISSET(j, &cpuset))
 199             printf("    CPU %d\\n", j);
 200
 201     exit(EXIT_SUCCESS);
 202 }
 203 .fi
 204 .SH SEE ALSO
 205 .BR sched_setaffinity (2),
 206 .BR sched_setscheduler (2),
 207 .BR pthread_attr_setaffinity_np (3),
 208 .BR pthread_self (3),
 209 .BR sched_getcpu (3),
 210 .BR cpuset (7),
 211 .BR pthreads (7)